I6 Template Layer

Printing.i6t

Paragraph Control.

Ah, yes: the paragraph breaking algorithm. In T_EX: The Program, Donald Knuth writes at § 768: "It's sort of a miracle whenever \halign and \valign work, because they cut across so many of the control structures of T_EX." 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.

The basic method is to set say__p, 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 say__p, and print a skipped line (and clear say__p again) if we find it. Thus:

A divide paragraph point occurs between any two rules in an action rulebook, but not an activity rulebook: many activities exist to print text, such as the names of objects, and there would be wild spacing accidents if paragraphs were divided there. Inform places DPPs elsewhere, too: and the text substitution "[conditional paragraph break]" allows the user to place one anywhere.

A traditional layout convention handed down from Infocom makes an exception of the first paragraph to appear after the prompt, but only in one situation. Ordinarily, the first paragraph of any turn appears straight after the prompt:

The command is echoed on screen as the player types, but this doesn't set the paragraph flag, which is still clear when the text "Mme Tourmalet's..." begins to be printed. The single exception occurs when the command calls for the player to go to a new location, when a skipped line is printed before the room description for the new room. Thus:

(Note that this is not inherent in the looking action:

...which obeys the standard paragraphing conventions.)

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.

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:

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.

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:

But sometimes it is followed directly by a subsequent paragraph, and again we want no skip:

And sometimes it is the only content of the room description and is followed only by the prompt:

To recap, we have five kinds of paragraph break:

(a) Standard breaks at "divide paragraph points", used between rules. (b) The "going look break", used before the room description after going to a new room. (c) A "command clarification break", used after text clarifying a command. (d) A "run paragraph on" break, used to merge multiple paragraphs into a single block of text. (e) The "special look spacing" break, used after the boldface headline of a room description.

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.

State.

The current state is stored in a combination of two global variables:

(1) say__p, the "say paragraph" flag, which is set if a paragraph break needs to be printed before the next text can begin; (2) say__pc, originally named as the "paragraph completed" flag, but which is now a bitmap: (-2a) PARA_COMPLETED is set if a standard paragraph break has been made since the last time the flag was cleared; (-2b) PARA_PROMPTSKIP 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; (-2c) PARA_SUPPRESSPROMPTSKIP is set to indicate that, despite PARA_PROMPTSKIP being set, no skipped line is needed before the prompt after all; (-2d) PARA_NORULEBOOKBREAKS 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.) (-2e) PARA_CONTENTEXPECTED is set after a paragraph division as a signal that if any contents looks likely to be printed soon then say__p needs to be set, because a successor paragraph will then have started. This is checked by calling ParaContent() – 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.

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 say__p and say__pc variables onto the VM stack and call ClearParagraphing() before starting to print to the new stream, and then pull the variables back again before resuming printing to the old stream.

In no other case should any code alter say__pc except via the routines below.