PPTools/Ppgen/Tutorial/Captions

Captions with ppgen

Long captions

Captions on illustrations are usually short sentences that easily fit with standard ppgen markup. There are exceptions, however. The first is handling a very long caption. Internally, the caption text has to be on on one line, but that is messy for the PPer to edit. Ppgen allows a long caption to span several lines in source. Here is an example:

 .il fn=i_003.jpg w=430px
 .ca “Aim right at his head,” added “Pee Wee”\
 Wise, another schoolmate who was to accompany\
 Bobby and Fred to Rockledge. “You can’t miss\
 that red mop of his,” put in Scat heartlessly.

Ppgen will join those lines and process them as expected. Here is the result in the generated text:

And in the generated HTML:

Multi-Line Captions

Sometimes captions are arranged on separate lines, and you may want to keep them that way, rather than letting ppgen wrap them to the page width as it normally does. You can do that using a different form of the .ca command. Here is an example:

 .il fn=i_003.jpg w=430px
 .ca
 Here is line 1 of the caption
 And here is line 2
 And line 3
 .ca-

When you use this form of .ca ppgen will keep the 3 caption lines separate in both the HTML and text output files.

HTML output files

For the HTML output file: To control the presentation of the caption lines you can use the cj= operand on the preceding .il command. The default, cj=c, will center the caption lines under the illustration. Alternatively you may select cj=l (left-align the caption lines under the illustration), cj=r (right-align the caption lines), or cj=f (justify the caption lines).

Text output files, before ppgen version 3.44c

For the text output file(s) ppgen ignores the cj= operand on the .il command and produces the captions in a fixed format. For example, using the above 3-line caption, ppgen produces:

 [Illustration: Here is line 1 of the caption
 And here is line 2
 And line 3]

Note that all 3 lines start in position 1. This could cause issues later if someone rewraps the text output file.

Text output files, ppgen version 3.44c and later

By default, in 3.44c and later, ppgen will still produce the captions in a fixed format, but one that is designed to be safe if the text output file is rewrapped later:

 [Illustration:

   Here is line 1 of the caption
   And here is line 2
   And line 3
 ]

In that format, the actual caption lines start at position 3, and are safe from later rewrapping. If an individual caption line is too long for the current line width it will be wrapped, with the overflow indented 2 spaces further.

If you do not like that default format, you can provide a named caption model for ppgen to use by using the new .cm (Caption Model) command, and by telling ppgen to use it with the new cm= operand on the .il command. For example, this caption model would duplicate the old behavior, before 3.44c:

 .cm old-style
 [Illustration: $1
 $2
 $3]
 .cm-

 ...

 .il fn=i_003.jpg w=430px cm=old-style
 .ca
 Here is line 1 of the caption
 And here is line 2
 And line 3
 .ca-

Or, perhaps you want the lines indented but with a blank line between them. For that you might use:

 .cm double-spaced
 [Illustration: 
   $1

   $2

   $3]
 .cm-

which would produce, if invoked using .il with cm=double-spaced:

 [Illustration:
   Here is line 1 of the caption

   And here is line 2

   And line 3]

There are a few simple rules for working with caption models and captions:

• Caption models apply only to the style of caption that uses .ca and .ca- which normally would be a multi-line caption. However, they will work even if you provide only a single caption line between the .ca and .ca- commands.
• ppgen will produce one line of output for each line of the caption model.
• A line of caption model may contain
  • purely static text (e.g., just something like "[Illustration:" or "]" or all blanks, or whatever you might like)
  • a marker telling ppgen to "consume" a line of the actual caption and produce it, in the form $<number>, e.g., $1 or $2 or....
  • a mix of static text and a marker, e.g., "[Illustration: $1"
• Any line of the caption model which has a marker must have only one marker. That is, you cannot have a model line which contains both $1 and $2.
• Markers must occur in numeric order within the model
• The model must "consume" all of the caption lines present in the .ca block. Any mismatches will cause an error message (for example, a 3-line caption used with a model that has only $1 and $2, or a 2-line caption used with a model that has $1, $2, and $3). So, if you have some 2-line captions and some 3-line captions you will need to define two models, one for each style of caption.

Some more examples:

.cm model3   // a model for a 3-line caption, with the word Illustration in Spanish
[Ilustración: $1
 $2
 $3]
.cm-

.cm model4   // Like the one above, but for a 4-line caption
[Ilustración: $1
 $2
 $3
 $4]
.cm-

.cm 3_and_blank  // A model that produces a blank line between caption lines 1 and 2  
[Illustration: $1

 $2
 $3]
.cm-

Here are two examples of using that last model (3_and_blank) to demonstrate another aspect of how captions and models work.

(1)

.il fn=filename.jpg w=nnnpx cm=3_and_blank
.ca
Line one
Line two
Line three
.ca-

produces

[Illustration: Line one

 Line two
 Line three]

(2)

.il fn=filename2.jpg w=nnnpx cm=3_and_blank
.ca
Line one

Line two
.ca-

produces

[Illustration: Line one


 Line two]

In that last one, the blank line in the .ca block was consumed by the $2 model line, and the "Line two" line of the .ca block was consumed by the $3 model line.

Complex Captions

Sometimes an illustration has an unusual caption. Here is an image of what the PPer is facing in this example:

Many post-processors would retain the caption less the references. That would be encoded in the source file like this:

 .il fn=i_003.jpg w=440px
 .ca <sc>“Dick-Dick,” she gasped, “a dreadful thing has happened!”</sc>

Some post-processors would want to create as close a match as possible to the original caption. To do that, the PPer has to escape out of ppgen source code and put in literal HTML. A PPer might ask for help with this step if they aren't familiar with HTML.

Here's an example of how to split it into text and HTML.

 .if t
 .li
 [Illustration: "Dick-Dick,” she gasped, “a dreadful thing has happened!"
 Frontispiece]                                                  [page 350]
 .li-
 .if-
 .if h
 .li
 <div class='figcenter'>
 <div style='width:440px; max-width:100%; display:inline-block; text-align:center;'>
 <img src='images/i_003.jpg' style='width:440px; max-width:100%; height:auto;' />
 <table style='text-align:center; margin-left:auto; margin-right:auto; width:440px;' summary='caption'>
 <tr><td colspan="2"><span class='sc'>“Dick-Dick,” she gasped, “a dreadful thing has happened!”</span></td></tr>
 <tr><td style='text-align:left'><i>Frontispiece</i>]</td><td style='text-align:right'>[<i>page</i> 350.</td></tr>
 </table>
 </div>
 </div>
 .li-
 .if-

Notice a table had to be used to split the second line. Here's how the HTML looks after ppgen has generated the output file. The ".li" bracketing says to use literal HTML or text, depending on which output is being generated. Here's how it looks in the generated HTML file:

Most illustration captions aren't as complicated as this, and even if they are, often a post-processer will simplify the caption. Most captions fit nicely into ppgen markup. But escaping to literal HTML and text as shown here for complicated captions is always an option.