<ulclass="crumbs"><li><ahref="../webs.html">★</a></li><li><ahref="index.html">basic_inform Template Library</a></li><li><b>Paragraphing</b></li></ul><pclass="purpose">To manage the line skips which space paragraphs out.</p>
<pclass="inwebparagraph"><aid="SP1"></a><b>§1. Paragraph Control. </b>Ah, yes: the paragraph breaking algorithm. In TeX: The Program,
Donald Knuth writes at \S 768: "It's sort of a miracle whenever <codeclass="display"><spanclass="extract">\halign</span></code>
and <codeclass="display"><spanclass="extract">\valign</span></code> work, because they cut across so many of the control structures
of TeX." It's sort of a miracle whenever Inform 7's paragraph breaking
system works, too. Most users probably imagine that it's implemented by
having I7 look at where the cursor currently is (at the start of a line or
not) and whether a line has just been skipped. In fact, the virtual machines
simply do not offer facilities like that, and so we have to use our own
book-keeping. Given the huge number of ways in which text can be printed,
this is a delicate business. For some years now, "spacing bugs" — those
where a spurious extra skipped line appears in a paragraph break, or
where, conversely, no line is skipped at all — have been the least
welcome in the Inform bugs database.
</p>
<pclass="inwebparagraph">The basic method is to set <codeclass="display"><spanclass="extract">say__p</span></code>, the paragraph flag, when we print any
matter; every so often we reach a "divide paragraph" point — for instance
when one rule has finished and before another is about to start — and at
those positions we look for <codeclass="display"><spanclass="extract">say__p</span></code>, and print a skipped line (and clear
<codeclass="display"><spanclass="extract">say__p</span></code> again) if we find it. Thus:
<pclass="inwebparagraph">(Note that this is not inherent in the looking action:
</p>
<pclass="inwebparagraph"></p>
<preclass="display">
<spanclass="plain">> LOOK</span>
<spanclass="plain">Rocky Beach</span>
</pre>
<pclass="inwebparagraph">...which obeys the standard paragraphing conventions.)
</p>
<pclass="inwebparagraph">So much for automatic paragraph breaks. However, we need a variety of different
ways explicitly to control paragraphs, in order to accommodate traditional
layout conventions handed down from Infocom.
</p>
<pclass="inwebparagraph">The simplest exceptional kind of paragraph break is a "command
clarification break", in which a single new-line is printed but there is
no skipped line: as the name implies, it's traditionally used when a
command such as OPEN DOOR is clarified. For example:
</p>
<pclass="inwebparagraph"></p>
<preclass="display">
<spanclass="plain">(first unlocking the oak door)</span>
...now a command clarification break <spanclass="plain">You open the oak door.</span>
</pre>
<pclass="inwebparagraph">This is not quite the same thing as a "run paragraph on" break, in which
we also deliberately suppress the skipped line, but make an exception for
the skipped line which ought to appear last before the prompt: the idea is
to merge two or more paragraphs together.
</p>
<pclass="inwebparagraph"></p>
<preclass="display">
<spanclass="plain">> TAKE ALL</span>
<spanclass="plain">marmot: Taken.</span>
...we run paragraph on here <spanclass="plain">weasel: Taken.</span>
...and also here <spanclass="plain"></span>
...despite which the final skip does occur <spanclass="plain">></span>
...before the next prompt</pre>
<pclass="inwebparagraph">A more complicated case is "special look spacing", used for the break which
occurs after the (boldface) short name of a room description is printed. This
is tricky because it is sometimes followed directly by a long description, and
we don't want a skipped line:
</p>
<pclass="inwebparagraph"></p>
<preclass="display">
<spanclass="plain">Villa Christiane</span>
...a special look spacing break <spanclass="plain">The walled garden of a villa in Cap d'Agde.</span>
<spanclass="plain"></span>
...a Divide Paragraph break <spanclass="plain">Mme Tourmalet's borzoi lazes in the long grass.</span>
</pre>
<pclass="inwebparagraph">But sometimes it is followed directly by a subsequent paragraph, and again
we want no skip:
</p>
<pclass="inwebparagraph"></p>
<preclass="display">
<spanclass="plain">Villa Christiane</span>
...a special look spacing break <spanclass="plain">Mme Tourmalet's borzoi lazes in the long grass.</span>
</pre>
<pclass="inwebparagraph">And sometimes it is the only content of the room description and is followed
only by the prompt:
</p>
<pclass="inwebparagraph"></p>
<preclass="display">
<spanclass="plain">Villa Christiane</span>
...a special look spacing break <spanclass="plain"></span>
...a break inserted before the prompt <spanclass="plain">></span>
</pre>
<pclass="inwebparagraph">To recap, we have five kinds of paragraph break:
</p>
<pclass="inwebparagraph"></p>
<ulclass="items"><li>(a) Standard breaks at "divide paragraph points", used between rules.
</li><li>(b) The "going look break", used before the room description after going to
a new room.
</li><li>(c) A "command clarification break", used after text clarifying a command.
</li><li>(d) A "run paragraph on" break, used to merge multiple paragraphs into a
single block of text.
</li><li>(e) The "special look spacing" break, used after the boldface headline of
a room description.
</li></ul>
<pclass="inwebparagraph">We now have to implement all of these behaviours. The code, while very simple,
is highly prone to behaving unexpectedly if changes are made, simply because
of the huge number of circumstances in which paragraphs are printed: so change
nothing without very careful testing.
</p>
<pclass="inwebparagraph"><aid="SP2"></a><b>§2. State. </b>The current state is stored in a combination of two global variables:
</p>
<pclass="inwebparagraph"></p>
<ulclass="items"><li>(1) <codeclass="display"><spanclass="extract">say__p</span></code>, the "say paragraph" flag, which is set if a paragraph break
needs to be printed before the next text can begin;
</li><li>(2) <codeclass="display"><spanclass="extract">say__pc</span></code>, originally named as the "paragraph completed" flag, but
which is now a bitmap:
<ulclass="items"><li>(2a) <codeclass="display"><spanclass="extract">PARA_COMPLETED</span></code> is set if a standard paragraph break has been made
since the last time the flag was cleared;
</li><li>(2b) <codeclass="display"><spanclass="extract">PARA_PROMPTSKIP</span></code> is set to indicate that the current printing position
does not follow a skipped line, and that further material is expected which
will run on from the previous paragraph, but that if no further material turns
up then a skipped line would be needed before the next prompt;
</li><li>(2c) <codeclass="display"><spanclass="extract">PARA_SUPPRESSPROMPTSKIP</span></code> is set to indicate that, despite <codeclass="display"><spanclass="extract">PARA_PROMPTSKIP</span></code>
being set, no skipped line is needed before the prompt after all;
</li><li>(2d) <codeclass="display"><spanclass="extract">PARA_NORULEBOOKBREAKS</span></code> suppresses divide paragraph points in between
rules in rulebooks; it treats all rulebooks, and in particular action rulebooks,
the way activity rulebooks are treated. (The flag is used for short periods
only and never across turn boundaries, prompts and so on.)
</li><li>(2e) <codeclass="display"><spanclass="extract">PARA_CONTENTEXPECTED</span></code> is set after a paragraph division as a signal
that if any contents looks likely to be printed soon then <codeclass="display"><spanclass="extract">say__p</span></code> needs
to be set, because a successor paragraph will then have started. This
is checked by calling <codeclass="display"><spanclass="extract">ParaContent()</span></code>— while it's slow to have to call
this routine so often, that's better than compiling inline code with the
same effect, because minimising compiled code size is more important, and
speed is never a big deal when printing.
</li></ul>
</li></ul>
<pclass="inwebparagraph">Not all printing is to the screen: sometimes the output is to a file, or to
memory, and in that case we want to start the switched output at a clear
paragraphing state and then go back to the screen afterwards without any
sign of change. The correct way to do this is to push the <codeclass="display"><spanclass="extract">say__p</span></code> and
<codeclass="display"><spanclass="extract">say__pc</span></code> variables onto the VM stack and call <codeclass="display"><spanclass="extract">ClearParagraphing()</span></code> before
starting to print to the new stream, and then pull the variables back again
before resuming printing to the old stream.
</p>
<pclass="inwebparagraph">In no other case should any code alter <codeclass="display"><spanclass="extract">say__pc</span></code> except via the routines
<ulclass="toc"><li><ahref="S-mt2.html">Back to 'MStack Template'</a></li><li><ahref="S-rt.html">Continue with 'RegExp Template'</a></li></ul><hrclass="tocbar">