User Tools

Site Tools


Sidebar

Passage markup

basics

coding

extra

list

section

whitespace

Macros

basics

colour

data structure

date and time

game state

live

maths

number

revision

saving

showing and hiding

string

styling

url

deprecated

Types of data

Special keywords

Special passage tags

harlowe:show

(show: HookName) → Command

Reveals hidden hooks, running the code within.

Example usage:

|fan)[The overhead fan spins lazily.]

(link:"Turn on fan")[(show:?fan)]

Rationale:

The purpose of hidden hooks is, of course, to eventually show them - and this macro is how you show them. You can use this Command inside a (link:), trigger it in real-time with a (live:) macro, or anywhere else.

Using (show:) vs (replace:): There are different reasons for using hidden hooks and (show:) instead of (replace:). For your stories, think about whether the prose being revealed is part of the “main” text of the passage, or is just an aside. In neatly-coded stories, the main text should appear early in a passage's code, as the focus of the writer's attention.

When using (replace:), the replacement prose is written far from its insertion point. This can improve readability when the insertion point is part of a long paragraph or sentence, and the prose is a minor aside or amendment, similar to a footnote or post-script, that would clutter the paragraph were it included inside. Additionally, (replace:) can be used in a “header” or “footer” tagged passage to affect certain named hooks throughout the story.

You turn away from her, facing the grandfather clock, its [stern ticking]<1| filling the tense silence.

(click-replace: ?1)[echoing, hollow ticking]

When using (show:), the hidden hook's position is fixed in the passage prose. This can improve readability when the hidden hook contains a lot of the “main” text of a passage, which provides vital context and meaning for the rest of the text.

I don't know where to begin... |1)[The weird state of my birth, the prophecy made centuries ago,
my first day of school, the day of the meteors, the day I awoke my friends' powers... so many strands in
the tapestry of my tale, and no time to unravel them.] ...so for now I'll start with when we fell down the hole.

(link:"Where, indeed?")[(show:?1)]

But, there aren't any hard rules for when you should use one or the other. As a passage changes in the writing, you should feel free to change between one or the other, or leave your choice as-is.

Details:

(show:) will reveal every hook with the given name. To only reveal a specific hook, you can use the possessive syntax, as usual: (show: ?shrub's 1st).

If you provide to (show:) a hook which is already visible, an error will be produced.

See also:

harlowe/show.txt · Last modified: 2017/10/10 00:39 (external edit)