contrib/mom/momdoc/images.html

   1 <?xml version="1.0" encoding="utf-8"?>
   2 <!--
   3 This file is part of groff, the GNU roff type-setting system.
   4
   5 Copyright (C) 2004-2020 Free Software Foundation, Inc.
   6 Written by Peter Schaffter (peter@schaffter.ca).
   7
   8 Permission is granted to copy, distribute and/or modify this document
   9 under the terms of the GNU Free Documentation License, Version 1.3 or
  10 any later version published by the Free Software Foundation; with no
  11 Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
  12 Texts.
  13
  14 A copy of the Free Documentation License is included as a file called
  15 FDL in the main directory of the groff source package.
  16 -->
  17
  18 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
  19 <html xmlns="http://www.w3.org/1999/xhtml">
  20
  21 <head>
  22   <meta http-equiv="content-type" content="text/html;charset=utf-8"/>
  23   <title>Mom -- Graphics, floats, and preprocessor support</title>
  24   <link rel="stylesheet" type="text/css" href="stylesheet.css" />
  25 </head>
  26
  27 <body style="background-color: #f5faff;">
  28
  29 <!-- ==================================================================== -->
  30
  31 <div id="top" class="page">
  32
  33 <!-- Navigation links -->
  34 <table style="width: 100%;">
  35 <tr>
  36   <td><a href="toc.html">Back to Table of Contents</a></td>
  37   <td style="text-align: right;"><a href="headfootpage.html#top">Next: Page headers/footers, pagination</a></td>
  38 </tr>
  39 </table>
  40
  41 <h1 class="docs">Graphics, floats, and preprocessor support</h1>
  42
  43 <div style="width: 80%; margin: auto;">
  44 <ul class="no-enumerator" style="margin-left: -1em;">
  45   <li><a href="#images-intro">Inserting images and graphics</a>
  46   <ul>
  47     <li><a href="#converting">Image conversion and file processing</a>
  48     <ul style="margin-left: -1em">
  49       <li><a href="#pdf">PDF</a></li>
  50       <li><a href="#eps">EPS</a></li>
  51     </ul></li>
  52     <li><a href="#pdf-image">The PDF_IMAGE macro</a>
  53     <ul style="margin-left: -1em">
  54       <li><a href="#pdf-image-frame">PDF_IMAGE_FRAME</a>&mdash;set parameters for image frames</li>
  55     </ul></li>
  56     <li><a href="#pspic">The PSPIC macro</a></li>
  57   </ul></li>
  58   <li><a href="#floats-intro">Floats</a>
  59   <ul>
  60     <li><a href="#float">The FLOAT macro</a></li>
  61     <li><a href="#float-label-caption">Labelling and captioning floats</a>
  62                 <ul style="margin-left: -1em">
  63                 <li><a href="#label">LABEL</a></li>
  64                 <li><a href="#caption">CAPTION</a></li>
  65                 </ul></li>
  66   </ul></li>
  67   <li><a href="#preprocessor-support">Preprocessor support</a>
  68   <ul>
  69     <li><a href="#tbl">tbl</a>
  70     <ul style="margin-left: -1em;">
  71       <li><a href="#ts-te">.TS / .TH / .TE macros and arguments</a></li>
  72     </ul></li>
  73     <li><a href="#eqn">eqn</a>
  74       <ul style="margin-left: -1em;">
  75         <li><a href="#eq-en">.EQ / .EN macros and arguments</a></li>
  76       </ul></li>
  77     <li><a href="#pic">pic</a>
  78     <ul style="margin-left: -1em;">
  79       <li><a href="#ps-pe">.PS / .PE macros and arguments</a></li>
  80       <li><a href="#pic-text-style">PIC_TEXT_STYLE</a>&mdash;set parameters for text in diagrams</li>
  81     </ul></li>
  82     <li><a href="#grap">grap</a></li>
  83     <li><a href="#refer">refer</a></li>
  84   </ul></li>
  85   <li><a href="#captions-and-labels">Captions and labels</a>
  86     <ul>
  87       <li><a href="#autolabel">AUTOLABEL</a></li>
  88       <li><a href="#set-autolabel">SET_AUTOLABEL</a></li>
  89       <li><a href="#caption-after-label">CAPTION_AFTER_LABEL</a></li>
  90       <li><a href="#captions-labels-sources">CAPTIONS / LABELS / SOURCES</a>&mdash;set parameters for each</li>
  91       <li><a href="#mla">MLA</a></li>
  92     </ul></li>
  93   <li><a href="#lists-of">Lists of Figures, Tables, and Equations</a>
  94     <ul>
  95       <li><a href="#lists-placement">Placement of Lists</a></li>
  96       <li><a href="#lists-macros">Macros to generate Lists</a></li>
  97       <li><a href="#formatting-lists">Formatting and style parameters for Lists</a>
  98       <ul style="margin-left: -1em">
  99         <li><a href="#lists-style">LISTS_STYLE</a></li>
 100       </ul></li>
 101   </ul></li>
 102   <li><a href="#box-intro">Shaded backgrounds and frames (boxes)</a>
 103     <ul>
 104       <li><a href="#box-intro">Introduction and description</a></li>
 105       <li><a href="#box">The BOX macro</a></li>
 106       <li><a href="#box-notes">Additional notes on box usage and behaviour</a>
 107         <ul>
 108          <li><a href="#qbef">QUOTE, BLOCKQUOTE, EPIGRAPH, FLOAT</a></li>
 109          <li><a href="#code">CODE</a></li>
 110          <li><a href="#quotes">Description of boxed BLOCKQUOTEs and EPIGRAPHs</a>
 111          <ul style="margin-left: -1em; list-style: disc;">
 112            <li><a href="#leftover">Leftover box syndrome</a></li>
 113          </ul></li>
 114          <li><a href="#slides">Slides</a></li>
 115          <li><a href="#footnotes">Footnotes</a></li>
 116         </ul></li>
 117       <li><a href="#page-color-intro">Page colour</a></li>
 118     </ul>
 119   </li>
 120 </ul>
 121 </div>
 122
 123 <div class="rule-medium"><hr/></div>
 124
 125 <h2 id="images-intro" class="docs">Inserting images and graphics</h2>
 126
 127 <p>
 128 In order to include images in mom documents, the images must be in
 129 either PDF (.pdf) or EPS (.eps) format.  Each format requires its own
 130 macro, but both take the same arguments, and in the same order.
 131 </p>
 132
 133 <p>
 134 Please note that there are differences in the way the files
 135 containing PDF and EPS images must be processed, hence documents may
 136 not contain a mix.
 137 </p>
 138
 139 <h3 id="converting" class="docs">Image conversion and file processing</h3>
 140
 141 <p>
 142 When your image files are not in PDF or EPS format&mdash;jpgs,
 143 for example&mdash;you must convert them before including them in
 144 a mom document.  Any utility for converting images may used.  The
 145 ImageMagick suite of programmes, present on most GNU/Linux
 146 systems, contains <b>convert</b>, which is simple and effective.
 147 </p>
 148
 149 <h4 id="pdf" class="docs">PDF</h4>
 150
 151 <p>
 152 Assuming a jpg image, conversion to PDF is done like this:
 153 <br/>
 154 <span class="pre-in-pp">
 155   convert &lt;image&gt;.jpg &lt;image&gt;.pdf
 156 </span>
 157 Any image type supported by <b>convert</b> may be converted this
 158 way.
 159 </p>
 160
 161 <p>
 162 Mom files containing PDF images must be processed using
 163 groff&#8217;s pdf driver.  Use of
 164 <a href="using.html#pdfmom" style="font-weight: bold">pdfmom</a>
 165 is strongly recommended, which natively invokes the pdf driver.
 166 <br/>
 167 <span class="pre-in-pp">
 168   pdfmom doc.mom &gt; doc.pdf
 169 </span>
 170 </p>
 171
 172 <h4 id="eps" class="docs">EPS</h4>
 173
 174 <p>
 175 Assuming a jpg image, conversion to EPS is done like this:
 176 <br/>
 177 <span class="pre-in-pp">
 178   convert &lt;image&gt;.jpg &lt;image&gt;.eps
 179 </span>
 180 Any image type supported by <b>convert</b> may be converted this
 181 way.  There have been reports of trouble with PostScript level 2
 182 images, so don&#8217;t save your images in this format.
 183 </p>
 184
 185 <p>
 186 Mom files containing EPS images must be processed using
 187 groff&#8217;s postscript driver.  Use of
 188 <a href="using.html#pdfmom" style="font-weight: bold">pdfmom</a>,
 189 which can be told to use the postscript driver, is strongly
 190 recommended.
 191 <br/>
 192 <span class="pre-in-pp">
 193   pdfmom -Tps doc.mom &gt; doc.pdf
 194 </span>
 195 </p>
 196
 197 <!-- -PDF_IMAGE- -->
 198
 199 <div class="macro-id-overline">
 200 <h3 id="pdf-image" class= "macro-id">PDF_IMAGE</h3>
 201 </div>
 202
 203 <div class="box-macro-args">
 204 Macro: <b>PDF_IMAGE</b> \
 205 <br/>
 206 <kbd class="macro-args">[ -L | -C | -R | -I &lt;indent&gt; ] \
 207 <br/>
 208 &lt;pdf image file&gt; &lt;width&gt; &lt;height&gt; [ SCALE &lt;factor&gt; ] \
 209 <br/>
 210 [ ADJUST +|-&lt;vertical adjustment&gt; ] [ NO_SHIM ] [ NO_FLEX ] \
 211 <br/>
 212 [ FRAME ] \
 213 <br/>
 214 [ CAPTION "&lt;caption&gt;" ] [ SHORT_CAPTION "&lt;short caption&gt;" ] \
 215 <br/>
 216 [ LABEL "&lt;label&gt;" ] [ TARGET "&lt;name&gt;" ]</kbd>
 217 </div>
 218 <p class="requires">
 219 &bull;&nbsp;<span style="font-style: normal">
 220 <kbd>&lt;indent&gt;</kbd>,
 221 <kbd>&lt;width&gt;</kbd>,
 222 <kbd>&lt;height&gt;</kbd></span>
 223 and
 224 <span style="font-style: normal">
 225 <kbd>&lt;vertical adjustment&gt;</kbd></span>
 226 require a
 227 <a href="definitions.html#unitofmeasure">unit of measure</a>
 228 </p>
 229
 230 <div class="box-tip">
 231 <p class="tip">
 232 <span class="note">Note:</span>
 233 Mom files with embedded PDF images must be processed with
 234 pdfmom&nbsp;doc.mom&nbsp;&gt;&nbsp;doc.pdf.  Arguments may be broken
 235 into several lines using the &#8220;line-continued&#8221; backslash
 236 (<b>\</b>), as shown above.
 237 </p>
 238 </div>
 239
 240 <p>
 241 Unlike
 242 <a href="#pspic">PSPIC</a>,
 243 which it resembles, PDF_IMAGE requires that the pdf image&#8217;s
 244 dimensions (the bounding box,
 245 <a href="#bounding-box">see below</a>)
 246 be supplied each time it&#8217;s called.
 247 </p>
 248
 249 <p>
 250 The first optional argument tells mom how to align the image
 251 horizontally, with <kbd>-L</kbd>, <kbd>-C</kbd>, and <kbd>-R</kbd>
 252 standing for left, centre and right respectively.  If you need more
 253 precise placement, the <kbd>-I</kbd> argument allows you to give an
 254 indent from the left margin.  Thus, to indent a PDF image 6
 255 <a href="definitions.html#picaspoints">picas</a>
 256 from the left margin
 257 <br/>
 258 <span class="pre-in-pp">
 259   .PDF_IMAGE -I 6P &lt;remaining arguments&gt;
 260 </span>
 261 If you omit the first argument, the image will be centred.
 262 </p>
 263
 264 <p>
 265 <kbd>&lt;pdf image&gt;</kbd> must be in PDF format, with a .pdf
 266 extension.  If it is not, mom will abort with a message.  See
 267 <a href="#pdf">here</a>
 268 for instructions on converting image formats to PDF.
 269 </p>
 270
 271 <p id="bounding-box">
 272 <kbd>&lt;width&gt;</kbd> and <kbd>&lt;height&gt;</kbd> are the
 273 dimensions of the image&#8217;s bounding box.  The most reliable way
 274 of getting the bounding box is with the utility, <strong>pdfinfo</strong>:
 275 <br/>
 276 <span class="pre-in-pp">
 277   pdfinfo &lt;image.pdf&gt; | grep "Page *size"
 278 </span>
 279 This will spit out a line that looks like this:
 280 <br/>
 281 <span class="pre-in-pp">
 282   Page size:      width x height pts
 283 </span>
 284 <kbd>pts</kbd> means
 285 <a href="definitions.html#picaspoints">points</a>,
 286 therefore the unit of measure appended to <kbd>&lt;width&gt;</kbd>
 287 and <kbd>&lt;height&gt;</kbd> must be <kbd>p</kbd>.
 288 </p>
 289
 290 <p>
 291 The remaining arguments are optional and may be entered in any
 292 order, although it&#8217;s best to put <kbd>CAPTION</kbd>,
 293 <kbd>SHORT_CAPTION</kbd>, and <kbd>LABEL</kbd> last.
 294 </p>
 295
 296 <h5 class="docs" style="margin-top: 1em; text-transform: none">SCALE</h5>
 297
 298 <p>
 299 <kbd>SCALE</kbd> allows you to scale the image by
 300 <kbd>&lt;factor&gt;</kbd>.  The factor is a percentage of the
 301 image&#8217;s original dimensions, thus <kbd>SCALE&nbsp;50</kbd>
 302 scales the image to 50 percent of its original size.  No percent
 303 sign or unit of measure should be appended.
 304 </p>
 305
 306 <h5 class="docs" style="margin-top: 1em; text-transform: none">ADJUST</h5>
 307
 308 <p>
 309 <kbd>ADJUST</kbd> lets you raise (<kbd>-</kbd>) or lower
 310 (<kbd>+</kbd>) the image
 311 <span style="font-style: italic">within the space allotted for it</span>
 312 by the amount you specify.  This is useful for achieving good
 313 optical centering between surrounding blocks of type.  A unit of
 314 measure is required.
 315 </p>
 316
 317 <div class="box-tip">
 318 <p class="tip-top">
 319 <span class="note">Tip:</span>
 320 You may sometimes find that a PDF_IMAGE at the bottom of a page
 321 doesn&#8217;t sit flush on the bottom margin, however attempts to lower it
 322 by adding space beforehand result in it being deferred to the next
 323 page.
 324 </p>
 325
 326 <p class="tip-bottom">
 327 The solution is to introduce <i>negative</i> space before the image
 328 so that it displays on the page, then lower it to the bottom margin
 329 with PDF_IMAGE&#8217;s ADJUST argument.
 330 </p>
 331 </div>
 332
 333 <h5 class="docs" style="margin-top: 1em; text-transform: none">NO_SHIM</h5>
 334
 335 <p>
 336 <kbd>NO_SHIM</kbd> instructs mom not to apply
 337 <a href="docprocessing.html#shim-vs-flex">shimming</a>
 338 after an image, which she will do automatically when shimming is
 339 enabled, which it is by default.  Shimming ensures that running text
 340 after the image falls properly on the page&#8217;s
 341 <a href="definitions.html#baseline-grid">baseline grid</a>,
 342 but can result in slightly unequal spacing above and below
 343 (correctable with the <kbd>ADJUST</kbd> argument).
 344 <kbd>NO_SHIM</kbd> is useful when you have several images on the
 345 page and there are visible differences in the spacing beneath them
 346 as a result of shimming.  To ensure a flush bottom margin, the last
 347 image on the page should be shimmed, i.e. should not be given the
 348 <kbd>NO_SHIM</kbd> argument.
 349 </p>
 350
 351 <h5 class="docs" style="margin-top: 1em; text-transform: none">NO_FLEX</h5>
 352
 353 <p>
 354 <kbd>NO_FLEX</kbd> instructs mom not to apply
 355 <a href="docprocessing.html#shim-vs-flex">flex-spacing</a>
 356 after an image, which she will do automatically when flex-spacing is
 357 enabled. <kbd>NO_FLEX</kbd> is useful when you have several images
 358 on the page and you want to distribute excess vertical
 359 whitespace on the page amongst other flex-spacing points on the
 360 page.  If there are no others, the final image should be
 361 flex-spaced, i.e. not given the <kbd>NO_FLEX</kbd> argument.
 362 </p>
 363
 364 <h5 class="docs" style="margin-top: 1em; text-transform: none">FRAME</h5>
 365
 366 <p>
 367 <kbd>FRAME</kbd> instructs mom to put a frame around the image.
 368 Parameters for the frame are set with
 369 <a href="#pdf-image-frame">PDF_IMAGE_FRAME</a>.
 370 </p>
 371
 372 <h5 class="docs" style="margin-top: 1em; text-transform: none">CAPTION</h5>
 373
 374 <p>
 375 <kbd>CAPTION</kbd> allows you to give the image a caption.  By
 376 default, the caption appears above the image, but may be attached to
 377 the label that appears beneath the image.  See
 378 <a href="#caption-after-label">CAPTION_AFTER_LABEL</a>
 379 in
 380 <a href="#captions-and-labels">Captions and labels</a>.
 381 The text of the caption must be surrounded by double-quotes.
 382 </p>
 383
 384 <h5 class="docs" style="margin-top: 1em; text-transform: none">SHORT_CAPTION</h5>
 385
 386 <p>
 387 <kbd>SHORT_CAPTION</kbd> allows you to trim long captions for
 388 inclusion in the List of Figures.  The text you supply, surrounded
 389 by double-quotes, is what will appear in the List.
 390 </p>
 391
 392 <h5 class="docs" style="margin-top: 1em; text-transform: none">LABEL</h5>
 393
 394 <p>
 395 <kbd>LABEL</kbd>, if given, appears beneath the image.  The text you
 396 supply, surrounded by double-quotes, is how the image is labelled
 397 in both the document proper and the List of Figures.  Mom provides
 398 an auto-labelling facility for images (see
 399 <a href="#autolabel">AUTOLABEL</a>),
 400 which, if enabled, overrides the <kbd>LABEL</kbd> argument.
 401 </p>
 402
 403 <h5 class="docs" style="margin-top: 1em; text-transform: none">TARGET</h5>
 404
 405 <p>
 406 <kbd>TARGET</kbd> followed by a unique name surrounded by
 407 double-quotes creates a PDF target for the image so that it may be
 408 linked to from other places in the file (with PDF_LINK; see
 409 <a href="version-2.html#mom-pdf">Producing PDFs with groff and mom</a>).
 410 </p>
 411
 412 <p>
 413 <b><i>Please note:</i></b> The following functionality is available
 414 only with groff 1.22.4 or later.
 415 </p>
 416
 417 <p>
 418 When
 419 <a href="#autolabel">autolabelling</a>
 420 is enabled and the document is processed with
 421 <a href="using.html#pdfmom" style="font-weight: bold">pdfmom</a>,
 422 the target name can be used to generate the target&#8217;s label
 423 number in running text if it is entered as a groff string, i.e. of the
 424 form <kbd><span class="nobr">\*[name]</span></kbd>.  For example, if you create
 425 a target named &#8220;foo&#8221; for a pdf image whose autolabel
 426 number would be 3, entering
 427 <br/>
 428 <span class="pre-in-pp">
 429   See
 430   .PDF_LINK foo "Figure \*[foo]"
 431 </span>
 432 anywhere in running text would result in a pdf link that reads
 433 &#8220;Figure 3&#8221;.  If chapter numbers are being prefixed to
 434 labels, the same string in, say, chapter 5 would produce the pdf
 435 link &#8220;Figure 5.3&#8221;.
 436 </p>
 437
 438 <div class="box-tip">
 439 <p class="tip-top">
 440 <span class="note">Note: Version 2.0-c change</span>
 441 <br/>
 442 Mom now treats all pdf images identically to
 443 <a href="#floats-intro">floats</a>,
 444 which is to say that if an image doesn&#8217;t fit on the output
 445 page, she will defer it to the top of the next page while continuing
 446 to process
 447 <a href="definitions.html#running">running text</a>.
 448 <kbd>ADJUST</kbd> is ignored whenever an image is the first to be
 449 deferred, except when moving from column to column on the same page,
 450 when the image may need to be optically adjusted.  Subsequent images
 451 that do not fit, if any, are output in order immediately after the
 452 first.
 453 </p>
 454
 455 <p class="tip-bottom">
 456 Prior to 2.0-c, it was recommended that images be wrapped inside
 457 <a href="#float">FLOAT</a>,
 458 but this is now no longer required, and should, in fact, be avoided.
 459 </p>
 460 </div>
 461
 462 <!-- -PDF_IMAGE_FRAME- -->
 463
 464 <div class="macro-id-overline">
 465 <h3 id="pdf-image-frame" class= "macro-id">PDF_IMAGE_FRAME</h3>
 466 </div>
 467
 468 <div class="box-macro-args">
 469 Macro: <b>PDF_IMAGE_FRAME</b> <kbd class="macro-args">&lt;inset amount&gt; &lt;rule weight&gt; &lt;color&gt;</kbd>
 470 </div>
 471 <p class="requires">
 472 &bull;&nbsp;<span style="font-style: normal"><kbd>&lt;inset amount&gt;</kbd></span>
 473 requires a
 474 <a href="definitions.html#unitofmeasure">unit of measure</a>;
 475 conversely,
 476 <span style="font-style: normal"><kbd>&lt;rule weight&gt;</kbd></span>
 477 must not have a unit of measure appended
 478 </p>
 479
 480 <p>
 481 PDF_IMAGE_FRAME establishes the parameters for subsequent invocations of
 482 <a href="#pdf-image">PDF_IMAGE</a>
 483 when the <kbd>FRAME</kbd> argument is given.  Arguments must appear
 484 in order, and any you wish left at the current value should be
 485 entered as two adjacent double-quotes.  So, for example,
 486 <br/>
 487 <span class="pre-in-pp">
 488   .PDF_IMAGE_FRAME "" "" blue
 489 </span>
 490 leaves the inset value and rule weight at their current value and
 491 changes the frame colour to blue.
 492 </p>
 493
 494 <p>
 495 Frames are drawn <span class="italic">outside</span> the image at
 496 its requested dimensions inclusive of scaling.  Colours must be
 497 pre-initialized with
 498 <a href="color.html#xcolor">XCOLOR</a>
 499 or
 500 <a href="color.html#newcolor">NEWCOLOR</a>.
 501 </p>
 502
 503 <p>
 504 The default inset is 6 <a
 505 href="definitions.html#picaspoints">points</a>, the default rule
 506 weight is .5 (points), and the default colour is black.
 507 </p>
 508
 509 <!-- -PSPIC- -->
 510
 511 <div class="macro-id-overline">
 512 <h3 id="pspic" class= "macro-id">PSPIC</h3>
 513 </div>
 514
 515 <div class="box-macro-args">
 516 Macro: <b>PSPIC</b> <kbd class="macro-args">[ -L | -R | -I &lt;n&gt; ] &lt;file&gt; [ width [ height ] ]</kbd>
 517 </div>
 518
 519 <p>
 520 PSPIC is not actually part of mom, but rather a macro included with
 521 every groff installation. <kbd>man groff_tmac</kbd> contains the
 522 documentation for PSPIC, but I&#8217;ll repeat it here with a few
 523 modifications for clarity.
 524 </p>
 525
 526 <div class="examples-container">
 527 <h3 id="groff-tmac" class="docs" style="margin-top: .5em;">From <span style="text-transform: none">groff_tmac</span></h3>
 528 <p style="margin-top: .5em; margin-bottom: .5em;">
 529 <kbd>&lt;file&gt;</kbd> is the name of the file containing the
 530 image; <kbd>width</kbd> and <kbd>height</kbd> give the desired
 531 width and height of the image as you wish it to appear within the
 532 document.  The width and height arguments may have
 533 <a href="definitions.html#unitofmeasure">units of measure</a>
 534 attached; the default unit of measure is <kbd>i</kbd>.  PSPIC will
 535 scale the graphic uniformly in the x and y directions so that
 536 it is no more than <kbd>width</kbd> wide and <kbd>height</kbd>
 537 high.  By default, the graphic will be horizontally centred.  The
 538 <kbd>-L</kbd> and <kbd>-R</kbd> options cause the graphic to be
 539 left-aligned and right-aligned, respectively.  The <kbd>-I</kbd>
 540 option causes the graphic to be indented by <kbd>&lt;n&gt;</kbd>;
 541 the default unit of measure is <kbd>m</kbd>
 542 (<a href="definitions.html#em">ems</a>).
 543 </p>
 544 </div>
 545
 546 <p>
 547 It is not necessary to pass PSPIC the <kbd>&lt;width&gt;</kbd>
 548 and <kbd>&lt;height&gt;</kbd> arguments unless you are scaling
 549 the image, in which case you will most likely need the original
 550 dimensions of the EPS image&#8217;s bounding box.  These can be
 551 found with
 552 <br/>
 553 <span class="pre-in-pp">
 554  gs -q -dBATCH -dNOPAUSE -sDEVICE=bbox &lt;image file&gt;.pdf 2&gt;&amp;1 \
 555  | grep "%%BoundingBox" | cut -d " " -f4,5
 556 </span>
 557 The two digits returned are in
 558 <a href="definitions.html#picaspoints">points</a>,
 559 therefore the
 560 <a href="definitions.html#unitofmeasure">unit of measure</a>
 561 <kbd>p</kbd> must be appended to them.
 562 </p>
 563
 564 <p>
 565 Because PSPIC lacks the <kbd>ADJUST</kbd> option offered by
 566 <a href="#pdf-image">PDF_IMAGE</a>
 567 a certain amount of manual tweaking of the vertical placement of the
 568 image will probably be required, typically by using the
 569 <a href="typesetting.html#ald">ALD</a>
 570 and
 571 <a href="typesetting.html#rld">RLD</a>
 572 macros.  Wrapping the image in a
 573 <a href="#float">float</a>
 574 and using FLOAT&#8217;s <kbd>ADJUST</kbd> option can also be used to
 575 correct optical centering.
 576 </p>
 577
 578 <p>
 579 Additionally, non-floated EPS images
 580 will almost certainly disrupt the baseline placement of
 581 <a href="definitions.html#running">running text</a>.
 582 In order to get mom back on track after inserting a non-floated
 583 <kbd>.PSPIC</kbd> image, insert the
 584 <a href="docprocessing.html#shim">SHIM</a>
 585 or
 586 <a href="docprocessing.html#flex">FLEX</a>
 587 macro afterwards, depending on the
 588 <a href="docprocessing.html#vertical-whitespace-management">vertical whitespace management</a>
 589 strategy in effect, so that the bottom margin of running text falls
 590 where it should.
 591 </p>
 592
 593 <p>
 594 Remember that mom files with embedded EPS images must be processed
 595 with
 596 <br/>
 597 <span class="pre-in-pp">
 598  pdfmom -Tps doc.mom &gt; doc.pdf
 599 </span>
 600 </p>
 601
 602 <div class="box-tip">
 603 <p class="tip">
 604 <span class="note">Please note:</span>
 605 <kbd>PSPIC</kbd> does not support
 606 <a href="autolabel">autolabelling</a>,
 607 labels, captions, or inclusion in the List of Figures.  If you wish
 608 this functionality,
 609 <a href="#converting">convert your images to pdf</a>
 610 and use
 611 <a href="#pdf-image">PDF_IMAGE</a>
 612 instead, then process the file with
 613 <a href="using.html#pdfmom" style="font-weight: bold">pdfmom</a>
 614 (without the <kbd>-Tps</kbd> option).
 615 </p>
 616 </div>
 617 <div class="rule-medium"><hr/></div>
 618
 619 <h2 id="floats-intro" class="docs">Introduction to floats</h2>
 620
 621 <p>
 622 Non-textual insertions in a document (tables, for example) sometimes
 623 do not fit on the output page of a PDF or PostScript document at
 624 the place they&#8217;re inserted in the input file.  It&#8217;s
 625 necessary, therefore, to defer them to the next page while carrying
 626 on with
 627 <a href="definitions.html#running">running text</a>.
 628 </p>
 629
 630 <p>
 631 Whenever you need this functionality, mom provides the FLOAT macro.
 632 </p>
 633
 634 <p>
 635 Floats are usually used for images and graphics, but can contain
 636 anything you like, including text.  Whatever&#8217;s in the
 637 float will be kept together as a block, output immediately if
 638 there&#8217;s room, or deferred to the top of the next output page
 639 when there isn&#8217;t; running text continues to the bottom of the
 640 previous page without interruption.
 641 </p>
 642
 643 <p>
 644 In the case of a float that doesn&#8217;t fit being followed by
 645 one that does, both are deferred and output one after the other.
 646 Note that this represents a change from versions 2.1-b_1 and earlier
 647 where the second float was output in position and the first was
 648 deferred.
 649 </p>
 650
 651 <p>
 652 A key distinction between a float and a
 653 <a href="docelement.html#quote">QUOTE</a>
 654 or
 655 <a href="docelement.html#blockquote">BLOCKQUOTE</a>
 656 is that while a float keeps everything together and defers output if
 657 necessary, quotes and blockquotes are output immediately, and may
 658 start on one page and finish on the next.
 659 </p>
 660
 661 <p>
 662 Floats always begin in
 663 <a href="definitions.html#filled">no-fill mode</a>.
 664 Text entered immediately after FLOAT will be set line-for-line
 665 unless a
 666 <a href="typesetting.html#justify">JUSTIFY</a>
 667 or
 668 <a href="typesetting.html#quad">QUAD&nbsp;L|R|C</a>
 669 precedes it.  Alternatively, any macro that sets a quad direction
 670 may be used, e.g.
 671 <a href="docelement.html#pp">PP</a>.
 672 </p>
 673
 674 <p>
 675 Floats always deposit a break before they begin, which means the
 676 line beforehand will not be
 677 <a href="definitions.html#filled">filled</a>.
 678 Floats, therefore, cannot be inserted in the middle of a paragraph
 679 without studying the output file and determining where to break or
 680 <a href="typesetting.html#spread">spread</a>
 681 the line before the float.  Furthermore, if you want a float between
 682 paragraphs, the float should come before <kbd>.PP</kbd>, like this:
 683 <br/>
 684 <span class="pre-in-pp">
 685   .FLOAT
 686   ...
 687   .FLOAT OFF
 688   .PP
 689 </span>
 690 not
 691 <br/>
 692 <span class="pre-in-pp">
 693   .PP
 694   .FLOAT
 695   ...
 696   .FLOAT OFF
 697 </span>
 698 </p>
 699
 700 <p id="float-spacing">
 701 Floats begin on the baseline immediately below the running text
 702 preceding them.  No additional whitespace surrounds them, above or
 703 below.  Running text below a float is, however,
 704 <a href="docprocessing.html#shim">shimmed</a>
 705 or
 706 <a href="docprocessing.html#flex">flex-spaced</a>,
 707 depending on the
 708 <a href="docprocessing.html#vertical-whitespace-management">vertical whitespace management</a>
 709 strategy in effect.  This behaviour can be disabled for individual
 710 floats with <kbd>NO_SHIM</kbd> or <kbd>NO_FLEX</kbd>.
 711 </p>
 712
 713 <p>
 714 If you&#8217;d like more space around a float, you must add it
 715 manually, for example with
 716 <a href="typesetting.html#ald">ALD</a>
 717 or
 718 <a href="typesetting.html#space">SPACE</a>.
 719 </p>
 720
 721 <!-- -FLOAT- -->
 722
 723 <div class="macro-id-overline">
 724 <h3 id="float" class= "macro-id">FLOAT</h3>
 725 </div>
 726
 727 <div class="box-macro-args">
 728 Macro: <b>FLOAT</b> <kbd class="macro-args">&lt;arguments&gt; | &lt;anything&gt;
 729 <br/>
 730 Arguments:
 731 <br/>
 732 [ ADJUST +|-&lt;amount&gt; ] \
 733 <br/>
 734 [ FORCE ] \
 735 <br/>
 736 [ SPAN ] \
 737 <br/>
 738 [ INDENT &lt;value&gt; ] \
 739 <br/>
 740 [ CENTER ] \
 741 <br/>
 742 [ RIGHT ] \
 743 <br/>
 744 [ NO_SHIM] \
 745 <br/>
 746 [ NO_FLEX ] \
 747 <br/>
 748 [ TARGET "&lt;name&gt;" ]</kbd>
 749 <br/>
 750 </div>
 751
 752 <div class="box-tip">
 753 <p class="tip">
 754 <span class="note">Note:</span>
 755 FLOAT is intended for use with the document processing macros only.
 756 </p>
 757 </div>
 758
 759 <div class="box-tip">
 760 <p class="tip">
 761 <span class="note">Note:</span>
 762 As a general rule, avoid consecutive floats that have no intervening
 763 <a href="definitions.html#running">running text</a>.
 764 Rather, wrap all the material into a single float.
 765 </p>
 766 </div>
 767
 768 <div class="box-tip">
 769 <p class="tip">
 770 <span class="note">Note:</span>
 771 Deferred floats are output with the left indent that was in effect
 772 when they were input.  If you do not want this behaviour, disable
 773 the indent prior to inputting the float and re-enable it afterward.
 774 </p>
 775 </div>
 776
 777 <div class="box-tip">
 778 <p class="tip">
 779 <span class="note">Note:</span>
 780 Mom treats <b>pic</b> pre-processor directives and pdf images as
 781 floats so it is not necessary to wrap them inside FLOAT unless
 782 additional material is included in what is floated.
 783 </p>
 784 </div>
 785
 786 <p style="margin-top: -.5em">
 787 To begin a float, simply invoke <kbd>.FLOAT</kbd> and follow it with
 788 whatever you want the float to contain.  When you&#8217;re done,
 789 invoke <kbd>.FLOAT&nbsp;OFF</kbd> (or <kbd>OFF</kbd>,
 790 <kbd>QUIT</kbd>, <kbd>END</kbd>, <kbd>X</kbd>, etc).
 791 </p>
 792
 793 <h5 class="docs" style="margin-top: 1em; text-transform: none">ADJUST</h5>
 794
 795 <p>
 796 The optional <kbd>ADJUST</kbd> argument tells mom to raise
 797 (<kbd>+</kbd>) or lower (<kbd>-</kbd>) the float <i>within
 798 the space allotted to it</i> by the specified amount.
 799 <kbd>&lt;amount&gt;</kbd> must have a
 800 <a href="definitions.html#unitofmeasure">unit of measure</a>
 801 appended.  <kbd>ADJUST</kbd> gives you precise control over
 802 the vertical centering of floats, allowing you to compensate for
 803 unequal spacing that may result from the automatic
 804 <a href="docprocessing.html#shim">shimming</a>
 805 or
 806 <a href="docprocessing.html#flex">flex-spacing</a>
 807 floats.
 808 </p>
 809
 810 <p>
 811 <kbd>ADJUST</kbd> is ignored for the first float deferred to
 812 a following page but respected for subsequent deferred floats
 813 output immediately afterwards.
 814 </p>
 815
 816 <h5 class="docs" style="margin-top: 1em; text-transform: none">FORCE</h5>
 817
 818 <p>
 819 The <kbd>FORCE</kbd> argument instructs mom to output the float
 820 exactly where it occurs in the input file.  With <kbd>FORCE</kbd>,
 821 mom immediately breaks to a new page to output the float if it does
 822 not fit on the current page.  While this is somewhat contrary to the
 823 notion of floats (i.e. that running text should continue to fill the
 824 page), there are circumstances where it may be desirable.
 825 </p>
 826
 827 <p>
 828 If you need to force a page break after completion of a float that
 829 has been deferred to a subsequent page, insert <kbd>\!.bp</kbd>
 830 immediately before terminating the float.
 831 </p>
 832
 833 <h5 class="docs" style="margin-top: 1em; text-transform: none">SPAN</h5>
 834
 835 <p>
 836 The <kbd>SPAN</kbd> argument tells mom that a float, if deferred,
 837 may carry onto multiple pages.  Please note that <kbd>SPAN</kbd> may
 838 not be used for floats containing a boxed table; mom will abort with
 839 a warning should this occur.  Unboxed tables, on the other hand, are
 840 acceptable within floats that are given the <kbd>SPAN</kbd> argument.
 841 </p>
 842
 843 <h5 class="docs" style="margin-top: 1em; text-transform: none">INDENT</h5>
 844
 845 <p>
 846 <kbd>INDENT</kbd> allows you to indent a float from the left margin
 847 by a specified value.  The value must have a
 848 (<a href="definitions.html#unitofmeasure">unit of measure</a>
 849 appended to it.
 850 </p>
 851
 852 <h5 class="docs" style="margin-top: 1em; text-transform: none">CENTER</h5>
 853
 854 <p>
 855 <kbd>CENTER</kbd> instructs mom to center a float if it is not
 856 already centered by default.
 857 </p>
 858
 859 <h5 class="docs" style="margin-top: 1em; text-transform: none">RIGHT</h5>
 860
 861 <p>
 862 <kbd>RIGHT</kbd> instructs mom to place a float at the right of the
 863 page; the longest line in the float will be flush with the
 864 page&#8217;s right margin.
 865 </p>
 866
 867 <h5 class="docs" style="margin-top: 1em; text-transform: none">NO_SHIM</h5>
 868
 869 <p>
 870 <kbd>NO_SHIM</kbd> instructs mom not to apply
 871 <a href="docprocessing.html#shim-vs-flex">shimming</a>
 872 after a float, which she will do automatically when shimming is
 873 enabled, which it is by default.  Shimming ensures that running text
 874 after the float falls properly on the page&#8217;s
 875 <a href="definitions.html#baseline-grid">baseline grid</a>,
 876 but can result in slightly unequal spacing above and below
 877 (correctable with the <kbd>ADJUST</kbd> argument).
 878 <kbd>NO_SHIM</kbd> is useful when you have several floats on the
 879 page and there are visible differences in the spacing beneath them
 880 as a result of shimming.  To ensure a flush bottom margin, the last
 881 float on the page should be shimmed, i.e. should not be given the
 882 <kbd>NO_SHIM</kbd> argument.
 883 </p>
 884
 885 <h5 class="docs" style="margin-top: 1em; text-transform: none">NO_FLEX</h5>
 886
 887 <p>
 888 <kbd>NO_FLEX</kbd> instructs mom not to apply
 889 <a href="docprocessing.html#shim-vs-flex">flex-spacing</a>
 890 after a float, which she will do automatically when flex-spacing is
 891 enabled. <kbd>NO_FLEX</kbd> is useful when you have several floats
 892 on the page and you want to distribute excess vertical
 893 whitespace on the page amongst other flex-spacing points on the
 894 page.  If there are no others, the final float should be
 895 flex-spaced, i.e. not given the <kbd>NO_FLEX</kbd> argument.
 896 </p>
 897
 898 <h5 class="docs" style="margin-top: 1em; text-transform: none">TARGET</h5>
 899
 900 <p>
 901 <kbd>TARGET</kbd> followed by a unique name surrounded by
 902 double-quotes creates a PDF target for the float so that it may be
 903 linked to from other places in the file (with PDF_LINK; see
 904 <a href="version-2.html#mom-pdf">Producing PDFs with groff and mom</a>).
 905 </p>
 906
 907 <p>
 908 Floats cannot be autolabelled, so unlike pdf images and
 909 pre-processor material, the target name cannot be used as a string
 910 to generate the target&#8217;s label number in running text.  Label
 911 numbers for floats must be entered explicitly running text, however
 912 they may be entered symbolically in the argument to
 913 <a href="#label">LABEL</a>.
 914 See
 915 <a href="#reserved-label-strings">Reserved variables for
 916 labels</a>.
 917 </p>
 918
 919
 920 <div class="box-tip">
 921 <p class="tip-top">
 922 <span class="note">Note:</span>
 923 Floats use
 924 <a href="definitions.html#filled">no-fill mode</a>,
 925 with each input line beginning at the left margin.  If this is not
 926 what you want, you must specify the preferred horizontal alignment
 927 <i>within the float</i> (e.g.
 928 <a href="typesetting.html#lrc">CENTER</a>
 929 or
 930 <a href="typesetting.html#lrc">RIGHT</a>).
 931 </p>
 932
 933 <p class="tip-bottom">
 934 Furthermore, if you want text
 935 <a href="definitions.html#filled">filled</a>,
 936 you must specify
 937 <a href="typesetting.html#quad"><kbd>.QUAD&nbsp;L|R|C</kbd></a>
 938 or
 939 <a href="typesetting.html#justify"><kbd>.JUSTIFY</kbd></a>&mdash;again,
 940 within the float.
 941 </p>
 942 </div>
 943
 944 <h2 id="float-label-caption" class="docs">Labelling and captioning floats</h2>
 945
 946 <p>
 947 Labelling and captioning of tables (<b>tbl</b>), equations
 948 (<b>eq</b>), diagrams (<b>pic</b>) and pdf images
 949 (<a href="#pdf-image">PDF_IMAGE</a>)
 950 are handled by the macros that initiate them, regardless of whether
 951 they&#8217;re wrapped inside a float.  However, since a float may
 952 contain any valid input, it is sometimes necessary to add a label
 953 and/or caption to the float itself.
 954 </p>
 955
 956 <div class="box-tip">
 957 <p class="tip">
 958 <span class="important">Important:</span>
 959 Always use the native labelling/captioning facilities for
 960 preprocessor output and pdf images rather than labelling the
 961 containing float, if any.
 962 </p>
 963 </div>
 964
 965 <p>
 966 The macros to label and caption floats are
 967 <a href="#label">LABEL</a>
 968 and
 969 <a href="#caption">CAPTION</a>.
 970 If a label or caption is to appear above the float, the appropriate
 971 macro is entered immediately after
 972 <a href="#float">FLOAT</a>.
 973 If a label or caption is to appear beneath the float, the appropriate
 974 macro is entered immediately before ending the float with
 975 <kbd>FLOAT&nbsp;OFF</kbd>.
 976 </p>
 977
 978 <p>
 979 If a label and caption are to be joined, the <b>LABEL</b> macro is
 980 used to enter both by passing the <kbd>CAPTION</kbd> argument to
 981 <kbd>LABEL</kbd>.
 982 </p>
 983
 984 <p>
 985 It is impossible for mom to know the contents of a float, so
 986 floats cannot be autolabelled.  Each label must be entered
 987 explicitly.  Mom does, however, provide a way to enter both
 988 chapter numbers and incrementing label numbers
 989 <a href="#reserved-label-strings">symbolically</a>,
 990 easing the burden of keeping the numbering scheme intact as
 991 labelled floats are added to or subtracted from a document.
 992 </p>
 993
 994 <div class="box-tip">
 995 <p class="tip">
 996 <span class="note">Tip:</span>
 997 <a href="docelement.html#blockquote">QUOTE</a>
 998 and
 999 <a href="docelement.html#blockquote">BLOCKQUOTE</a>
1000 may also be labelled and captioned using <b>LABEL</b> and
1001 <b>CAPTION</b>.
1002 </p>
1003 </div>
1004
1005 <h4 class="docs">Spacing</h4>
1006
1007 <p>
1008 If a float has a caption at the top, the caption is whitespaced
1009 1/4 linespace from running text and the float itself begins
1010 an additional 1/4 linespace below the caption.  If the float has
1011 no corresponding label at the bottom, the float observes the
1012 bottom-spacing rules for all floats, namely that no extra space is
1013 added other than
1014 <a href="docprocessing.html#shim">shimming</a>
1015 or
1016 <a href="docprocessing.html#shim-vs-flex">flex-spacing</a>,
1017 depending on the
1018 <a href="docprocessing.html#vertical-whitespace-management">vertical whitespace management</a>
1019 in effect.
1020 </p>
1021
1022 <p>
1023 If a float has a label at the bottom but no caption at the top, the
1024 float begins exactly where started, i.e. with no extra whitespace
1025 between running text and the float.  The label (and attached
1026 caption, if any) are whitespaced 1/4 linespace below the float,
1027 with an additional 1/4 linespace underneath <i>plus</i> shimming or
1028 flex-spacing.
1029 </p>
1030
1031 <p>
1032 Labelled/captioned quotes and blockquotes inside floats treat the
1033 labels/captions as part of the quote so the spacing above and
1034 below the whole float block is what you&#8217;d expect from quotes
1035 normally, while the spacing between the label/caption and the quote
1036 is 1/4 linespace.
1037 </p>
1038
1039 <div class="macro-id-overline">
1040 <h3 id="label" class="macro-id">LABEL</h3>
1041 </div>
1042
1043 <div class="box-macro-args">
1044 Macro: <b>LABEL</b>
1045 <kbd class="macro-args">"&lt;label&gt;" [ CAPTION "&lt;caption&gt;" ] [ SHORT_CAPTION ] \
1046 <br/>
1047 [ TO_LIST FIGURES | TABLES | EQUATIONS ]</kbd>
1048 </div>
1049
1050 <p>
1051 The placement of a float&#8217;s label depends on where you put it
1052 inside the float.
1053 </p>
1054
1055 <p>
1056 If you want a label at the top, put <kbd>LABEL</kbd> immediately
1057 underneath
1058 <a href="#float">FLOAT</a>
1059 and follow it with the text of the label surrounded by double-quotes:
1060 <br/>
1061 <span class="pre-in-pp">
1062   .FLOAT
1063   .LABEL "Fig. 1"
1064 </span>
1065 If you want a label at the bottom, put <kbd>LABEL</kbd> immediately
1066 before ending the float:
1067 <br/>
1068 <span class="pre-in-pp">
1069   .FLOAT
1070   &lt;contents of float&gt;
1071   .LABEL "Fig. 1"
1072   .FLOAT OFF
1073 </span>
1074 </p>
1075
1076 <h3  id="reserved-label-strings" class="docs" style="text-transform: none">Reserved variables for labels</h3>
1077
1078 <p>
1079 Mom reserves strings you may use when entering
1080 label text after the <kbd>LABEL</kbd> argument.
1081 <kbd><span class="nobr">\*[chapter]</span></kbd> holds the current chapter
1082 or major section number. <kbd><span class="nobr">\*[fig-label]</span></kbd>,
1083 <kbd><span class="nobr">\*[tbl-label]</span></kbd>, and
1084 <kbd><span class="nobr">\*[eqn-label]</span></kbd> increment the label number of
1085 the appropriate label type by one, and are initially set to zero
1086 after each invocation of
1087 <a href="docprocessing.html#start">START</a>
1088 when the
1089 <a href="docprocessing.html#doctype">DOCTYPE</a>
1090 is <kbd>CHAPTER</kbd>.  Thus, in every chapter requiring numbered
1091 float labels, you can enter
1092 <br/>
1093 <span class="pre-in-pp">
1094   .LABEL "Fig. \*[chapter].\*[fig-label]. TO_LIST FIGURES
1095 </span>
1096 which, assuming the third autolabelled float of Chapter 2, will
1097 produce <kbd>Fig. 2.3.</kbd>
1098 </p>
1099
1100 <p>
1101 If your <b>DOCTYPE</b> is <kbd>DEFAULT</kbd> or <kbd>NAMED</kbd>,
1102 you must reset <kbd><span class="nobr">\*[&lt;type&gt;-label]</span></kbd> after
1103 each
1104 <a href="docprocessing.html#collate">COLLATE</a>
1105 by entering
1106 <br/>
1107 <span class="pre-in-pp">
1108   .AUTOLABEL_&lt;list type&gt;
1109 </span>
1110 before <kbd>.START</kbd>.
1111 </p>
1112
1113 <p>
1114 If
1115 <a href="#autolabel">autolabelling</a>
1116 is enabled, e.g. <kbd>.AUTOLABEL_IMAGES</kbd> (List
1117 of Figures) or <kbd>.AUTOLABEL_PIC</kbd> (also List of Figures),
1118 the prefix is stripped from the label when it appears in
1119 the List.  Thus, if you have invoked <kbd>.AUTOLABEL_PIC</kbd>,
1120 <br/>
1121 <span class="pre-in-pp">
1122   .LABEL "Fig. 1.1."
1123    CAPTION "Caption for label \
1124    TO_LIST FIGURES
1125 </span>
1126 or
1127 <br/>
1128 <span class="pre-in-pp">
1129   .LABEL "Fig. \*[chapter].\*[label]." \
1130    CAPTION "Caption for label \
1131    TO_LIST FIGURES
1132 </span>
1133 will appear in the List of Figures as &#8220;1.1.&nbsp;&nbsp;Caption for
1134 label&#8221;.
1135 </p>
1136
1137 <h3 class="docs">CAPTION</h3>
1138
1139 <p>
1140 If you&#8217;d like a caption attached to the label, pass
1141 <kbd>LABEL</kbd> the optional argument <kbd>CAPTION</kbd> followed
1142 by the text of the caption as a single string surrounded by
1143 double-quotes:
1144 <br/>
1145 <span class="pre-in-pp">
1146   .FLOAT
1147   &lt;contents of float&gt;
1148   .LABEL "Fig. 1" CAPTION "Caption for Fig. 1"
1149   .FLOAT OFF
1150 </span>
1151 Note that the
1152 <a href="#caption">CAPTION</a>
1153 macro by itself permits entering several strings, each output on
1154 a line by itself, whereas the <kbd>CAPTION</kbd> argument to
1155 <kbd>LABEL</kbd> accepts only a single string.
1156 </p>
1157
1158 <h3 class="docs">SHORT_CAPTION</h3>
1159
1160 <p>
1161 If your caption runs long and you&#8217;re including the
1162 float in a &#8220;List of ...&#8221;, (see
1163 <a href="#list-of">TO_LIST</a>, below)
1164 <kbd>SHORT_CAPTION</kbd> tells
1165 mom how you&#8217;d like the caption to appear in the List.
1166 </p>
1167
1168 <h3 class="docs">TO_LIST</h3>
1169
1170 <p>
1171 The optional argument <kbd>TO_LIST</kbd> tells mom to add the
1172 float&#8217;s label and attached caption, if present, to the specified
1173 <a href="#lists-of">list</a>,
1174 which may be one of <kbd>FIGURES</kbd>, <kbd>TABLES</kbd>, or
1175 <kbd>EQUATIONS</kbd>.
1176 </p>
1177
1178 <p>
1179 If, for some reason, you want only the caption appended to the List,
1180 give <kbd>\&amp;</kbd> as the first argument to LABEL, followed by
1181 <kbd>CAPTION&nbsp;&#8220;caption&#8221;</kbd>:
1182 <br/>
1183 <span class="pre-in-pp">
1184   .LABEL \&amp; \
1185   CAPTION "caption"
1186 </span>
1187 </p>
1188
1189 <div class="box-tip">
1190 <p class="tip-top">
1191 <span class="note">Tip:</span>
1192 <kbd>TO_LIST</kbd> can be used to handle situations where labelled
1193 floats need to go to a uniquely named &#8220;List of ...&#8221;.
1194 </p>
1195
1196 <p class="tip-bottom">
1197 Suppose, for example, your document contains figures (e.g.
1198 <b>pic</b> output or pdf-images) and tables, and you need a
1199 &#8220;List of Examples&#8221; for floats labelled &#8220;Example
1200 n.n&#8221;.  By changing the default title string for
1201 <a href="#lists-macros">LIST_OF_EQUATIONS</a>
1202 to &#8220;List of Examples&#8221;, you may include the float in your
1203 List of Examples with
1204 <br/>
1205 <span class="pre-in-pp">
1206   .TO_FIGURES EQUATIONS
1207 </span>
1208 </p>
1209 </div>
1210
1211 <div class="macro-id-overline">
1212 <h3 id="caption" class="macro-id">CAPTION</h3>
1213 </div>
1214
1215 <div class="box-macro-args">
1216 Macro: <b>CAPTION</b>
1217 <kbd class="macro-args">"&lt;caption&gt;" \
1218 <br/>
1219 [ "&lt;additional line&gt;" [ "&lt;additional line&gt;"... ] ] \
1220 <br/>
1221 [ TO_LIST FIGURES | TABLES | EQUATIONS ]</kbd>
1222 </div>
1223
1224 <p>
1225 The placement of a float&#8217;s caption depends on where you put it
1226 inside the float.
1227 </p>
1228
1229 <p>
1230 If you want a caption at the top, put <kbd>CAPTION</kbd> immediately
1231 underneath
1232 <a href="#float">FLOAT</a>
1233 and follow it with the text of the caption surrounded by double-quotes:
1234 <br/>
1235 <span class="pre-in-pp">
1236   .FLOAT
1237   .CAPTION "Caption at top of float"
1238 </span>
1239 <b>CAPTION</b> can take multiple string arguments, allowing for
1240 captions that run to several lines.  There is a caveat: the strings
1241 are not automatically broken into individual lines.  You must
1242 provide strings that include literal breaks or spaces:
1243 <br/>
1244 <span class="pre-in-pp">
1245   .FLOAT
1246   .CAPTION "Caption" ".BR" "at top" ".BR" "of float"
1247 </span>
1248 or, easier to read:
1249 <br/>
1250 <span class="pre-in-pp">
1251   .FLOAT
1252   .CAPTION "Caption" \
1253   ".BR" \
1254   "at top" \
1255   ".BR" \
1256   "of float"
1257 </span>
1258 If you want a caption at the bottom, put <kbd>CAPTION</kbd> immediately
1259 before ending the float:
1260 <br/>
1261 <span class="pre-in-pp">
1262   .FLOAT
1263   &lt;contents of float&gt;
1264   .CAPTION "Caption at bottom of float"
1265   .FLOAT OFF
1266 </span>
1267 </p>
1268
1269 <div class="box-tip">
1270 <p class="tip">
1271 <span class="note">Note:</span>
1272 If you want a caption attached to a label, do not use
1273 <b>CAPTION</b> by itself.  Rather, invoke
1274 <a href="#label"><kbd>.LABEL</kbd></a>
1275 with the <kbd>CAPTION</kbd> argument.
1276 </p>
1277 </div>
1278
1279 <div class="rule-medium"><hr/></div>
1280
1281 <h2 id="preprocessor-support" class="docs">Preprocessor support</h2>
1282
1283 <p>
1284 Mom offers full support for the <b>eqn</b> (equations), <b>pic</b>
1285 (diagrams), <b>grap</b> (graphs), <b>tbl</b> (tables) and
1286 <b>refer</b> (bibliographies/citations) preprocessors, including
1287 captions, labelling, autolabelling, and inclusion in the Lists of
1288 Equations, Figures, and Tables.
1289 </p>
1290
1291 <p>
1292 Other than <b>refer</b>, which is discussed at length in the <a
1293 href="refer.html">Bibliographies and references</a> section, it is
1294 beyond the scope of this documentation to cover full preprocessor
1295 usage.  Consult the manpages <b>eqn(1)</b>, <b>pic(1)</b>,
1296 <b>grap(1)</b> and <b>tbl(1)</b> for instructions.
1297 </p>
1298
1299 <div class="box-tip">
1300 <p class="tip">
1301 <span class="note">Version 2.0-c changes</span>
1302 <br/>
1303 Preprocessor support has been revised and expanded as of version 2.0-c.
1304 Please read the following sections thoroughly and update any
1305 documents created with versions prior to 2.0-c as necessary.
1306 </p>
1307 </div>
1308
1309 <h3 id="tbl" class="docs">tbl support</h3>
1310
1311 <p>
1312 Mom documents can include tables generated with the groff
1313 preprocessor <b>tbl</b>.  If you are unfamiliar with <b>tbl</b>, I
1314 recommend downloading a copy of
1315 <a href="http://plan9.bell-labs.com/10thEdMan/tbl.pdf">Tbl - A Program to Format Tables</a>,
1316 which, in addition to providing a thorough introduction, contains
1317 some fine examples.  If you use <b>tbl</b>, you must pass groff or
1318 pdfmom the <b>-t</b> flag when you process the file.
1319 </p>
1320
1321 <p>
1322 Tables formatted with <kbd>tbl</kbd> begin with the macro
1323 <kbd>.TS</kbd> (<b>T</b>able <b>S</b>tart) and end with
1324 <kbd>.TE</kbd> (<b>T</b>able <b>E</b>nd).  Depending on where you
1325 want your tables output in a document, you may need to wrap
1326 your <kbd>tbl</kbd> code inside a
1327 <a href="#floats-intro">float</a>,
1328 or pass the <kbd>H</kbd> argument to <kbd>.TS</kbd>.
1329 </p>
1330
1331 <p>
1332 If you put <kbd>tbl</kbd> code inside a float, the table will be
1333 output immediately if it fits on the page, or deferred to the top
1334 of the next page if it doesn&#8217;t.  If you prefer a table to
1335 begin where you say and span over to the next page, or if you know
1336 for certain a boxed table will run to multiple pages, simply pass the
1337 <kbd>H</kbd> argument to <kbd>.TS</kbd>, along with a corresponding
1338 <a href="#th"><kbd>TH</kbd></a>
1339 and do not wrap the table inside a float.
1340 </p>
1341
1342 <div class="box-tip">
1343 <p class="tip">
1344 <span class="note">Note:</span>
1345 If you create a boxed table that will span several pages, do not
1346 wrap the table inside a float.  Boxed, multipage tables and FLOAT
1347 should be considered mutually exclusive.  This restriction is
1348 imposed by the <kbd>tbl</kbd> preprocessor itself, not groff or
1349 mom.  Unboxed tables that span several pages, however, are
1350 acceptable within FLOAT.
1351 </p>
1352 </div>
1353
1354 <h4 id="tbl-placement" class="docs">tbl placement in mom docs</h4>
1355
1356 <p>
1357 If you use <kbd>.TS</kbd> without the <kbd>H</kbd> argument (and
1358 therefore no <kbd>.TH</kbd>), tables that fit on the page are output
1359 in position.  If there is not enough room to output the table,
1360 <kbd>tbl</kbd> will abort with message instructing you to use
1361 <kbd>.TS H/.TH</kbd>.  Given that <kbd>.TS</kbd> without <kbd>H</kbd>
1362 may sometimes fail, it is advisable to begin all <b>tbl</b> blocks
1363 with <kbd>.TS H</kbd>.
1364 </p>
1365
1366 <p>
1367 If you give <kbd>.TS</kbd> the <kbd>H</kbd> argument (with a
1368 corresponding <kbd>.TH</kbd>), tables will be output in position and
1369 span as many pages as necessary to complete output.  A table header
1370 will be printed at the top of each page&#8217;s table output.  In the
1371 event that there is not enough room to print the table header and
1372 at least one row of table data near the bottom of a page, mom will
1373 break to a new page before beginning table output, leaving a gap
1374 in
1375 <a href="definitions.html#running">running text</a>.
1376 </p>
1377
1378 <p>
1379 Boxed tables inside
1380 <a href="#floats-intro">floats</a>
1381 are output in position if they fit on the page.  If not, they are
1382 deferred to the top of the next page without a break in running
1383 text.  Boxed tables within floats may not, however, span multiple
1384 pages; mom will abort with a message should a boxed table in a float
1385 run longer than the page.
1386 </p>
1387
1388 <p>
1389 Unboxed tables inside floats may span multiple pages provided the
1390 <kbd>SPAN</kbd> argument has been given to
1391 <a href="#float">FLOAT</a>.
1392 </p>
1393
1394 <div class="box-tip">
1395 <p class="tip">
1396 <span class="note">Note:</span>
1397 The vertical spacing around unfloated tables may appear slightly
1398 unequal, especially if there are several tables on the page.  This
1399 is a result of the
1400 <a href="docprocessing.html#shim">shimming</a>
1401 or
1402 <a href="docprocessing.html#flex">flex-spacing</a>
1403 that mom applies automatically after each table, depending on which
1404 <a href="docprocessing.html#vertical-whitespace-management">vertical whitespace management</a>
1405 is in effect.  You may
1406 disable shimming or flex-spacing with
1407 <a href="docprocessing.html#no-shim">NO_SHIM</a>
1408 or
1409 <a href="docprocessing.html#no-flex">NO_FLEX</a>,
1410 or by passing the <kbd>NO_SHIM</kbd> or <kbd>NO_FLEX</kbd> argument
1411 to <kbd>.TS</kbd>.  In either case, you will still likely want to
1412 adjust the spacing around with table with the <kbd>ADJUST</kbd>
1413 argument to <kbd>.TS</kbd>.  Tables inside floats should be adjusted
1414 with the <kbd>ADJUST</kbd> argument to
1415 <a href="#float">FLOAT</a>,
1416 not the <kbd>ADJUST</kbd> argument to <kbd>.TS</kbd>.
1417 </p>
1418 </div>
1419
1420 <div class="macro-id-overline">
1421 <h3 id="ts-te" class= "macro-id">.TS / .TH / .TE</h3>
1422 </div>
1423
1424 <div class="box-macro-args">
1425 Macro: <a href="#ts"><b>TS</b></a>
1426 <kbd class="macro-args"><br/>
1427 Arguments:
1428 <br/>
1429 &nbsp;&nbsp;[ H ]
1430 <br/>
1431 &nbsp;&nbsp;[ BOXED ]
1432 <br/>
1433 &nbsp;&nbsp;[ CENTER ]
1434 <br/>
1435 &nbsp;&nbsp;[ NEEDS ]
1436 <br/>
1437 &nbsp;&nbsp;[ ADJUST +|-&lt;vertical adjustment&gt;]</kbd>
1438 <span style="font-size: 95%">
1439 (<a href="definitions.html#unitofmeasure">unit of measure</a>
1440 required)
1441 </span>
1442 <kbd class="macro-args"><br/>
1443 &nbsp;&nbsp;[ NO_SHIM ]
1444 <br/>
1445 &nbsp;&nbsp;[ NO_FLEX ]
1446 <br/>
1447 &nbsp;&nbsp;[ CAPTION "&lt;caption&gt;" ]
1448 <br/>
1449 &nbsp;&nbsp;[ SHORT_CAPTION "&lt;short caption&gt;" ]
1450 <br/>
1451 &nbsp;&nbsp;[ LABEL "&lt;label&gt;" ]
1452 <br/>
1453 &nbsp;&nbsp;[ TARGET "&lt;name&gt;" ]
1454 </kbd>
1455 <br/>
1456 Macro: <a href="#th"><b>TH</b></a> <kbd class="macro-args">(optional, only if .TS H)</kbd>
1457 <br/>
1458 Macro: <a href="#te"><b>TE</b></a> <kbd class="macro-args">[ SOURCE "&lt;text of table source&gt;" ]</kbd>
1459 </div>
1460
1461 <p>
1462 Tables to be formatted with <kbd>tbl</kbd> begin with the macro
1463 <kbd>.TS</kbd> and end with <kbd>.TE</kbd>.  Global <kbd>tbl</kbd>
1464 options (&#8220;flags&#8221;), formatting, and data (per
1465 <kbd>tbl(1)</kbd>) come between the two macros.
1466 <br/>
1467 <span class="pre-in-pp">
1468   .TS
1469   &lt;tbl options, formatting, and data&gt;
1470   .TE
1471 </span>
1472 Tables may be wrapped inside a
1473 <a href="#float-intro">float</a>,
1474 in which case, the entire table will be output on the current page
1475 if it fits, or deferred to the next page if it doesn&#8217;t.
1476 <br/>
1477 <span class="pre-in-pp">
1478   .FLOAT
1479   .TS
1480   &lt;tbl options, formatting, and data&gt;
1481   .TE
1482   .FLOAT OFF
1483 </span>
1484 </p>
1485
1486 <div class="macro-id-overline">
1487 <h4 id="ts" class="docs" style="font-size: 100%; margin-top: .5em">The .TS macro</h4>
1488 </div>
1489
1490 <div class="box-tip">
1491 <p class="tip">
1492 <span class="note">Note: Version 2.0-c change</span>
1493 <br/>
1494 2.0-c introduces revisions to the handling of labels and/or
1495 captions, which, along with <kbd>NO_SHIM</kbd>, must now be given
1496 as arguments to <kbd>.TS</kbd> rather than <kbd>.TE</kbd>, as was
1497 the case formerly.  Please read this section carefully if you have
1498 documents containing tables as they may need to be updated.
1499 </p>
1500 </div>
1501
1502 <div class="box-important" style="margin-top: 1em">
1503 <p class="tip">
1504 <span class="important">IMPORTANT:</span>
1505 All arguments to <b>TS</b> must appear on the same line as
1506 <kbd>.TS</kbd>.  Do not attempt to break them up with the
1507 &#8220;line-continued&#8221; backslash.  You may want to set your
1508 text editor to &#8220;wrap&#8221; mode in order to see all your
1509 arguments.  This annoyance stems from the preprocessor mechanism
1510 itself, not groff or mom.
1511 </p>
1512 </div>
1513
1514 <p>
1515 The <b>TS</b> macro must be invoked before entering a <kbd>tbl</kbd>
1516 block.  You may give as many or as few of its arguments as required,
1517 in any order, although it is advisable to put <kbd>CAPTION</kbd>,
1518 <kbd>SHORT_CAPTION</kbd>, and/or <kbd>LABEL</kbd> last.
1519 </p>
1520
1521 <h5 id="h" class="docs" style="margin-top: 1em; text-transform: none">H</h5>
1522
1523 <p>
1524 With the <b>H</b> argument, a table will span as many pages as
1525 necessary, with or without a running header.  The placement of the
1526 corresponding
1527 <a href="#th"><kbd>.TH</kbd></a>,
1528 which is required whenever the <b>H</b> argument is given,
1529 determines what, if anything, goes in the header.  Compare the
1530 following:
1531 <span class="pre-in-pp">
1532   .TS H                   .TS H
1533   c s s                   c s s
1534   c s s                   c s s
1535   c c c                   c c c
1536   n n n.                  n n n.
1537   Percent Increase        .TH
1538   2002-2012               Percent Increase
1539   .TH                     2002-2012
1540   &lt;tbl data&gt;              &lt;tbl data&gt;
1541   .TE                     .TE
1542 </span>
1543 The first example will create a table that spans multiple
1544 pages if necessary, with a running header (&#8220;Percent
1545 Increase&nbsp;/&nbsp;2002-2012&#8221;) for that table appearing at
1546 the top of each page until the table ends.  The second example,
1547 equally, may run to several pages, but without the running header.
1548 See
1549 <a href="#th"><b>TH</b></a>
1550 for an explanation of <kbd>.TH</kbd> placement.
1551 </p>
1552
1553 <div id="h-tip" class="box-tip">
1554 <p class="tip">
1555 <span class="note">Tip:</span>
1556 Generally speaking, it&#8217;s a good idea to get into the habit
1557 of using <kbd>.TS H</kbd> all the time, since there are no
1558 circumstances under which it fails, whereas <kbd>.TS</kbd> without
1559 <kbd>H</kbd> will fail on tables that exceed the page length.
1560 </p>
1561 </div>
1562
1563 <h5 class="docs" style="margin-top: 1em; text-transform: none">BOXED</h5>
1564
1565 <p>
1566 If a table is to be boxed (i.e., <kbd>tbl</kbd> is given the flags
1567 <kbd>'box'</kbd> or <kbd>'allbox'</kbd>) you must pass the argument
1568 <kbd>BOXED</kbd> to <kbd>.TS</kbd>, as in this example:
1569 <br/>
1570 <span class="pre-in-pp">
1571   .TS BOXED
1572   allbox;
1573   c s s
1574   c c c
1575   n n n.
1576   &lt;tbl data&gt;
1577   .TE
1578 </span>
1579 </p>
1580
1581 <h5 class="docs" style="margin-top: 1em; text-transform: none">CENTER</h5>
1582
1583 <p>
1584 If a table is to be centered on the page, (i.e., <kbd>tbl</kbd> is
1585 given the <kbd>'center'</kbd> flag), you must pass the argument
1586 <kbd>CENTER</kbd> to <kbd>.TS</kbd>, as in this example, which
1587 creates a (possibly) multipage boxed table, centered on the page,
1588 with a running header.
1589 <span class="pre-in-pp">
1590   .TS H BOXED CENTER
1591   allbox center;
1592   c s s
1593   c s s
1594   c c c
1595   n n n.
1596   Percent Increase
1597   2002-2012
1598   .TH
1599   &lt;tbl data&gt;
1600   .TE
1601 </span>
1602 </p>
1603
1604 <h5 class="docs" style="margin-top: 1em; text-transform: none">NEEDS</h5>
1605
1606 <p>
1607 If a table is not inside a float and you pass <kbd>.TS </kbd> the
1608 <kbd>H</kbd> argument (which you should; see the tip
1609 <a href="#h-tip">here</a>),
1610 mom begins output immediately where the table occurs in the
1611 input file <i>if there is enough room on the output page for the
1612 table header plus at least one row of table data</i>.  If there
1613 isn&#8217;t enough room, mom breaks to a new page before beginning
1614 the table, leaving a gap in
1615 <a href="definitions.html#running">running text</a>
1616 at the bottom of the previous page.  If, for aesthetic reasons,
1617 you would prefer that mom require more than one row of table data
1618 beneath the header near the bottom of a page, you may increase the
1619 number with the <kbd>NEEDS</kbd> argument, followed by the desired
1620 number of rows.
1621 </p>
1622
1623 <h5 class="docs" style="margin-top: 1em; text-transform: none">ADJUST</h5>
1624
1625 <p>
1626 <kbd>ADJUST</kbd> lets you raise (<kbd>-</kbd>) or lower
1627 (<kbd>+</kbd>) the table
1628 <span style="font-style: italic">within the space allotted for it</span>
1629 by the amount you specify.  This is useful for achieving good
1630 optical centering between surrounding blocks of type.  A unit of
1631 measure is required.
1632 </p>
1633
1634 <h5 class="docs" style="margin-top: 1em; text-transform: none">NO_SHIM</h5>
1635
1636 <p>
1637 <kbd>NO_SHIM</kbd> instructs mom not to apply
1638 <a href="docprocessing.html#shim-vs-flex">shimming</a>
1639 after a table, which she will do automatically when shimming is
1640 enabled, which it is by default.  Shimming ensures that running text
1641 after the table falls properly on the page&#8217;s
1642 <a href="definitions.html#baseline-grid">baseline grid</a>,
1643 but can result in slightly unequal spacing above and below
1644 (correctable with the <kbd>ADJUST</kbd> argument).
1645 <kbd>NO_SHIM</kbd> is useful when you have several tables on the
1646 page and there are visible differences in the spacing beneath them
1647 as a result of shimming.  To ensure a flush bottom margin, the last
1648 table on the page should be shimmed, i.e. should not be given the
1649 <kbd>NO_SHIM</kbd> argument.
1650 </p>
1651
1652 <h5 class="docs" style="margin-top: 1em; text-transform: none">NO_FLEX</h5>
1653
1654 <p>
1655 <kbd>NO_FLEX</kbd> instructs mom not to apply
1656 <a href="docprocessing.html#shim-vs-flex">flex-spacing</a>
1657 after a table, which she will do automatically when flex-spacing is
1658 enabled. <kbd>NO_FLEX</kbd> is useful when you have several tables
1659 on the page and you want to distribute excess vertical
1660 whitespace on the page amongst other flex-spacing points on the
1661 page.  If there are no others, the final table should be
1662 flex-spaced, i.e. not given the <kbd>NO_FLEX</kbd> argument.
1663 </p>
1664
1665 <h5 class="docs" style="margin-top: 1em; text-transform: none">CAPTION</h5>
1666
1667 <p>
1668 <kbd>CAPTION</kbd> allows you to give the table a caption.  By
1669 default, the caption appears above the table, but may be attached to
1670 the label that appears beneath the table.  See
1671 <a href="#caption-after-label">CAPTION_AFTER_LABEL</a>
1672 in
1673 <a href="#captions-and-labels">Captions and labels</a>.
1674 The text of the caption must be surrounded by double-quotes.
1675 </p>
1676
1677 <p>
1678 Please note that if your table has a caption, you must invoke
1679 <kbd>TS</kbd> with the <kbd>H</kbd> flag, which also entails the use
1680 of
1681 <a href="#th">TH</a>.
1682 </p>
1683
1684 <h5 class="docs" style="margin-top: 1em; text-transform: none">SHORT_CAPTION</h5>
1685
1686 <p>
1687 <kbd>SHORT_CAPTION</kbd> allows you to trim long captions for
1688 inclusion in the List of Tables.  The text you supply, surrounded
1689 by double-quotes, is what will appear in the List.
1690 </p>
1691
1692 <h5 class="docs" style="margin-top: 1em; text-transform: none">LABEL</h5>
1693
1694 <p>
1695 <kbd>LABEL</kbd>, if given, appears beneath the table.  The text you
1696 supply, surrounded by double-quotes, is how the table is labelled
1697 in both the document proper and the List of Tables.  Mom provides
1698 an auto-labelling facility for tables (see
1699 <a href="#autolabel">AUTOLABEL</a>),
1700 which, if enabled, overrides the <kbd>LABEL</kbd> argument.
1701 </p>
1702
1703 <h5 class="docs" style="margin-top: 1em; text-transform: none">TARGET</h5>
1704
1705 <p>
1706 <kbd>TARGET</kbd> followed by a unique name surrounded by
1707 double-quotes creates a PDF target for the table so that it may be
1708 linked to from other places in the file (with PDF_LINK; see
1709 <a href="version-2.html#mom-pdf">Producing PDFs with groff and mom</a>).
1710 </p>
1711
1712 <p>
1713 <b><i>Please note:</i></b> The following functionality is available
1714 only with groff 1.22.4 or later.
1715 </p>
1716
1717 <p>
1718 When
1719 <a href="#autolabel">autolabelling</a>
1720 is enabled and the document is processed with
1721 <a href="using.html#pdfmom" style="font-weight: bold">pdfmom</a>,
1722 the target name can be used to generate the target&#8217;s label
1723 number in running text if it is entered as a groff string, i.e. of
1724 the form <kbd><span class="nobr">\*[name]</span></kbd>.  For example, if you
1725 create a target called &#8220;foo&#8221; for a table whose autolabel
1726 number would be 3, entering
1727 <br/>
1728 <span class="pre-in-pp">
1729   See
1730   .PDF_LINK foo "Table \*[foo]"
1731 </span>
1732 anywhere in running text would result in a pdf link that reads
1733 &#8220;Table 3&#8221;.  If chapter numbers are being prefixed to
1734 labels, the same string in, say, chapter 5 would produce the pdf
1735 link &#8220;Table 5.3&#8221;.
1736 </p>
1737
1738 <div class="macro-id-overline">
1739 <h4 id="th" class="docs" style="font-size: 100%; margin-top: .5em">The .TH macro</h4>
1740 </div>
1741
1742 <p>
1743 The <b>TH</b> macro (<b>T</b>able <b>H</b>eader), which is required
1744 when you begin a table with <kbd>.TS H</kbd>, allows you to
1745 determine what goes in a table&#8217;s running header if it spans
1746 multiple pages.  Placing <kbd>.TH</kbd> under the first row of
1747 <kbd>tbl</kbd> data makes the first row the header.  If placed under
1748 the second row, the first and second rows form the header, and so
1749 on.
1750 </p>
1751
1752 <p>
1753 As there are sometimes reasons to run <kbd>.TS H</kbd> when
1754 you don&#8217;t, in fact, want a running header (e.g. when
1755 your table has a caption), you can suppress it by placing
1756 <kbd>.TH</kbd> immediately underneath your <kbd>tbl</kbd> formatting
1757 specifications, the last line of which always ends with a period
1758 (see <kbd>tbl(1)</kbd>).
1759 </p>
1760
1761 <p>
1762 See the
1763 <kbd><a href="#h">H</a></kbd>
1764 argument to <kbd>.TS</kbd> for examples demonstrating <kbd>.TH</kbd>
1765 placement.
1766 </p>
1767
1768 <div class="macro-id-overline">
1769 <h4 id="te" class="docs" style="font-size: 100%; margin-top: .5em">The .TE macro</h4>
1770 </div>
1771
1772 <p>
1773 <kbd>tbl</kbd> blocks must be terminated with <kbd>.TE</kbd>,
1774 which, as of version 2.0-c, takes a single, optional argument,
1775 <kbd>SOURCE</kbd>.  (Formerly, <kbd>TE</kbd> took a label/caption
1776 argument along with arguments controlling placement.)  The argument
1777 is followed by the text of the table&#8217;s source, surrounded by
1778 double-quotes.  The SOURCE argument may only be used if
1779 <a href="#mla">MLA</a>
1780 (Modern Language Association) style is enabled.
1781 </p>
1782
1783 <div class="rule-medium"><hr/></div>
1784
1785 <h3 id="pic" class="docs">pic support</h3>
1786
1787 <p>
1788 Mom documents can include diagrams generated with the groff
1789 preprocessor <b>pic</b>.  If you are unfamiliar with <b>pic</b>, I
1790 recommend downloading a copy of
1791 <a href="http://www.kohala.com/start/troff/gpic.raymond.ps">Making Pictures with GNU PIC</a>
1792 which provides a thorough introduction and contains many examples.
1793 If you use <b>pic</b>, you must pass groff or pdfmom the <b>-p</b>
1794 flag when you process the file.
1795
1796 </p>
1797
1798 <p>
1799 Diagrams created with <kbd>pic</kbd> begin with the macro
1800 <kbd>.PS</kbd> (<b>P</b>ic <b>S</b>tart) and end with
1801 <kbd>.PE</kbd> (<b>P</b>ic <b>E</b>nd).  Everything between them is
1802 interpreted by the preprocessor as pic instructions.  Please note:
1803 <i>Making Pictures with GNU PIC</i> says that <kbd>.PF</kbd> can
1804 also be used to terminate a pic diagram, but this is not supported
1805 by mom.
1806 </p>
1807
1808 <p>
1809 Pic diagrams are always centered.  Note that this represents a
1810 change from version 2.0-b of mom, where centering diagrams required
1811 passing <kbd>-mpic</kbd> to <b>groff</b> or
1812 <a href="using.html#pdfmom" style="font-weight: bold">pdfmom</a>
1813 on the command line.
1814 </p>
1815
1816 <p>
1817 In addition, mom treats <b>pic</b> diagrams identically to
1818 <a href="#floats-intro">floats</a>,
1819 which is to say that if a diagram doesn&#8217;t fit on the output
1820 page, she will defer it to the top of the next page while continuing
1821 to process
1822 <a href="definitions.html#running">running text</a>.
1823 <kbd>ADJUST</kbd> is ignored whenever a diagram is deferred, except
1824 when moving from column to column on the same page, when the diagram
1825 may need to be optically adjusted.  Subsequent diagrams that do not
1826 fit, if any, are output in order immediately after the first.
1827 </p>
1828
1829 <p>
1830 Lastly, if your diagrams contain text, you may set all the type
1831 parameters for the text (family, font, size, leading) separately
1832 from the <b>pic</b> block with the macro
1833 <a href="#pic-text-style">PIC_TEXT_STYLE</a>.
1834 If you need to change the type parameters within the block
1835 on-the-fly, you must use <b>pic</b>&#8217;s native facilities for
1836 doing so.
1837 </p>
1838
1839 <div class="macro-id-overline">
1840 <h3 id="ps-pe" class= "macro-id">.PS / .PE</h3>
1841 </div>
1842
1843 <div class="box-macro-args">
1844 Macro: <b>PS</b>
1845 <kbd class="macro-args">
1846 <br/>
1847 Arguments: [ &lt;width&gt;&nbsp;&lt;height&gt; ]
1848 <kbd class="macro-args">
1849 <br/>
1850 &nbsp;&nbsp;[ LEFT ]</kbd>
1851 <br/>
1852 &nbsp;&nbsp;[ ADJUST +|-&lt;vertical adjustment&gt;]</kbd>
1853 <span style="font-size: 95%">
1854 (<a href="definitions.html#unitofmeasure">unit of measure</a>
1855 required)
1856 </span>
1857 <kbd class="macro-args"><br/>
1858 &nbsp;&nbsp;[ NO_SHIM ]
1859 <br/>
1860 &nbsp;&nbsp;[ NO_FLEX ]
1861 <br/>
1862 &nbsp;&nbsp;[ CAPTION "&lt;caption&gt;" ]
1863 <br/>
1864 &nbsp;&nbsp;[ SHORT_CAPTION "&lt;short caption&gt;" ]
1865 <br/>
1866 &nbsp;&nbsp;[ LABEL "&lt;label&gt;" ]
1867 <br/>
1868 &nbsp;&nbsp;[ TARGET "&lt;name&gt;" ]
1869 </kbd>
1870 <br/>
1871 Macro: <b>PE</b> <span style="font-size: 95%">(no arguments; ends
1872 the <b>pic</b> block)</span>
1873 </div>
1874
1875 <div class="box-important" style="margin-top: 1.5em">
1876 <p class="tip">
1877 <span class="important">IMPORTANT:</span>
1878 All arguments to <b>PS</b> must appear on the same line as
1879 <kbd>.PS</kbd>.  Do not attempt to break them up with the
1880 &#8220;line-continued&#8221; backslash.  You may want to set your
1881 text editor to &#8220;wrap&#8221; mode in order to see all your
1882 arguments.  This annoyance stems from the preprocessor mechanism
1883 itself, not groff or mom.
1884 </p>
1885 </div>
1886
1887 <h5 class="docs" style="margin-top: 1em; text-transform: none">'width' and 'height'</h5>
1888
1889 <p>
1890 The <kbd>width</kbd> and <kbd>height</kbd> arguments to
1891 <kbd>.PS</kbd> are idiosyncratic owing to the preprocessor itself.
1892 Both are optional and both expect a value in inches, so neither
1893 argument should have a
1894 (<a href="definitions.html#unitofmeasure">unit of measure</a>
1895 appended.
1896 </p>
1897
1898 <p>
1899 If the <kbd>width</kbd> argument is supplied, the diagram, but
1900 not any text it contains, is scaled to the given width.  If a
1901 literal width argument of <kbd>0</kbd> (zero) is given and a
1902 <kbd>height</kbd> argument is supplied, the diagram, but not any
1903 text it contains, will be scaled to the requested height.  In the
1904 case of two non-zero arguments being given, only the height scaling
1905 is applied.
1906 </p>
1907
1908 <h5 class="docs" style="margin-top: 1em; text-transform: none">LEFT</h5>
1909
1910 <p>
1911 By default, pic diagrams are centred on the page.  If you would
1912 prefer them to be flush left, pass <kbd>PS</kbd> the <kbd>LEFT</kbd>
1913 argument.
1914 </p>
1915 <h5 class="docs" style="margin-top: 1em; text-transform: none">ADJUST</h5>
1916
1917 <p>
1918 <kbd>ADJUST</kbd> lets you raise (<kbd>-</kbd>) or lower
1919 (<kbd>+</kbd>) a diagram
1920 <span style="font-style: italic">within the space allotted for it</span>
1921 by the amount you specify.  This is useful for achieving good
1922 optical centering between surrounding blocks of type.  A unit of
1923 measure is required.
1924 </p>
1925
1926 <h5 class="docs" style="margin-top: 1em; text-transform: none">NO_SHIM</h5>
1927
1928 <p>
1929 <kbd>NO_SHIM</kbd> instructs mom not to apply
1930 <a href="docprocessing.html#shim-vs-flex">shimming</a>
1931 after a <b>pic</b> diagram, which she will do automatically when
1932 shimming is enabled, which it is by default.  Shimming ensures that
1933 running text after the diagram falls properly on the page&#8217;s
1934 <a href="definitions.html#baseline-grid">baseline grid</a>,
1935 but can result in slightly unequal spacing above and below
1936 (correctable with the <kbd>ADJUST</kbd> argument).
1937 <kbd>NO_SHIM</kbd> is useful when you have several diagrams on the
1938 page and there are visible differences in the spacing beneath them
1939 as a result of shimming.  To ensure a flush bottom margin, the last
1940 diagram on the page should be shimmed, i.e. should not be given the
1941 <kbd>NO_SHIM</kbd> argument.
1942 </p>
1943
1944 <h5 class="docs" style="margin-top: 1em; text-transform: none">NO_FLEX</h5>
1945
1946 <p>
1947 <kbd>NO_FLEX</kbd> instructs mom not to apply
1948 <a href="docprocessing.html#shim-vs-flex">flex-spacing</a>
1949 after a <b>pic</b> diagram, which she will do automatically when
1950 flex-spacing is enabled. <kbd>NO_FLEX</kbd> is useful when you
1951 have several diagrams on the page and you want to distribute excess
1952 vertical whitespace on the page amongst other flex-spacing points
1953 on the page.  If there are no others, the final diagram should be
1954 flex-spaced, i.e. not given the <kbd>NO_FLEX</kbd> argument.
1955 </p>
1956
1957 <h5 class="docs" style="margin-top: 1em; text-transform: none">CAPTION</h5>
1958
1959 <p>
1960 <kbd>CAPTION</kbd> allows you to give the diagram a caption.  By
1961 default, the caption appears above the diagram, but may be attached to
1962 the label that appears beneath it.  See
1963 <a href="#caption-after-label">CAPTION_AFTER_LABEL</a>
1964 in
1965 <a href="#captions-and-labels">Captions and labels</a>.
1966 The text of the caption must be surrounded by double-quotes.
1967 </p>
1968
1969 <h5 class="docs" style="margin-top: 1em; text-transform: none">SHORT_CAPTION</h5>
1970
1971 <p>
1972 <kbd>SHORT_CAPTION</kbd> allows you to trim long captions for
1973 inclusion in the List of Figures.  The text you supply, surrounded
1974 by double-quotes, is what will appear in the List.
1975 </p>
1976
1977 <h5 class="docs" style="margin-top: 1em; text-transform: none">LABEL</h5>
1978
1979 <p>
1980 <kbd>LABEL</kbd>, if given, appears beneath the diagram.  The text you
1981 supply, surrounded by double-quotes, is how the diagram is labelled
1982 in both the document proper and the List of Figures.  Mom provides
1983 an auto-labelling facility for diagrams (see
1984 <a href="#autolabel">AUTOLABEL</a>),
1985 which, if enabled, overrides the <kbd>LABEL</kbd> argument.
1986 </p>
1987
1988 <h5 class="docs" style="margin-top: 1em; text-transform: none">TARGET</h5>
1989
1990 <p>
1991 <kbd>TARGET</kbd> followed by a unique name surrounded by
1992 double-quotes creates a PDF target for the diagram so that it may be
1993 linked to from other places in the file (with PDF_LINK; see
1994 <a href="version-2.html#mom-pdf">Producing PDFs with groff and mom</a>).
1995 </p>
1996
1997 <p>
1998 <b><i>Please note:</i></b> The following functionality is available
1999 only with groff 1.22.4 or later.
2000 </p>
2001
2002 <p>
2003 When
2004 <a href="#autolabel">autolabelling</a>
2005 is enabled and the document is processed with
2006 <a href="using.html#pdfmom" style="font-weight: bold">pdfmom</a>,
2007 the target name can be used to generate the target&#8217;s label
2008 number in running text if it is entered as a groff string, i.e. of
2009 the form <kbd><span class="nobr">\*[name]</span></kbd>.  For example, if you
2010 create a target called &#8220;foo&#8221; for a diagram whose
2011 autolabel number would be 3, entering
2012 <br/>
2013 <span class="pre-in-pp">
2014   See
2015   .PDF_LINK foo "Figure \*[foo]"
2016 </span>
2017 anywhere in running text would result in a pdf link that reads
2018 &#8220;Figure 3&#8221;.  If chapter numbers are being prefixed to
2019 labels, the same string in, say, chapter 5 would produce the pdf
2020 link &#8220;Figure 5.3&#8221;.
2021 </p>
2022
2023 <!-- PIC_TEXT_STYLE -->
2024
2025 <div class="macro-id-overline">
2026 <h3 id="pic-text-style" class= "macro-id">PIC_TEXT_STYLE</h3>
2027 </div>
2028
2029 <div class="box-macro-args">
2030 Macro: <b>PIC_TEXT_STYLE</b> \
2031 <br/>
2032 <kbd class="macro-args">
2033 &nbsp;&nbsp;[ FAMILY ] "&lt;family&gt;" \
2034 <br/>
2035 &nbsp;&nbsp;[ FONT ] "&lt;font&gt;" \
2036 <br/>
2037 &nbsp;&nbsp;[ SIZE ] "+|-&lt;size&gt;" \
2038 <br/>
2039 &nbsp;&nbsp;[ AUTOLEAD ] "&lt;value&gt;"
2040 </kbd>
2041 </div>
2042
2043 <p>
2044 Diagrams drawn with <b>pic</b> may contain text, and groff
2045 <a href="inlines.html#intro-inlines">inline escapes</a>
2046 may be used to alter the text parameters.  A problem that arises
2047 from so doing is that, in many cases, it clutters up the <b>pic</b>
2048 code unnecessarily.
2049 </p>
2050
2051 <p>
2052 PIC_TEXT_STYLE lets you establish the type parameters for text
2053 inside a <b>pic</b> block all at once in cases where so doing
2054 improves the readability of your mom source files.
2055 </p>
2056
2057 <p>
2058 The arguments to PIC_TEXT_STYLE behave identically to the arguments
2059 to other control macros, explained
2060 <a href="docelement.html#control-macro-args">here</a>.
2061 They may be given in any order, and you may use as many or as few as
2062 you like.
2063 </p>
2064
2065 <div class="box-tip">
2066 <p class="tip">
2067 <span class="note">Note:</span>
2068 Text within <b>pic</b> diagrams does not scale when you provide a
2069 scaling argument to <kbd>.PS</kbd>.  This is a limitation of the
2070 preprocessor itself, not groff or mom.
2071 </p>
2072 </div>
2073
2074 <div class="rule-medium"><hr/></div>
2075
2076 <h3 id="grap" class="docs">grap support</h3>
2077
2078 <p>
2079 Grap is a <b>pic</b> preprocessor for creating graphs.  Grap
2080 usage is covered in the <kbd>grap(1)</kbd> manpage.  Its mom
2081 implementation is the same as for <b>pic</b> except that instead of
2082 enclosing directives between
2083 <a href="#ps-pe">.PS&nbsp;/&nbsp;.PE</a>,
2084 they are enclosed between <b>.G1/.G2</b>.  If you use <b>grap</b>,
2085 you must pass groff or pdfmom the <b>-G</b> flag when you process
2086 the file.
2087
2088 </p>
2089
2090 <p>
2091 <b>.G1</b> takes all the same arguments as
2092 <a href="#ps-pe">PS</a>
2093 with one exception: the argument <b>GRAP</b> must always be given to
2094 <b>.G1</b>.  So, for example, a skeleton grap block raised 2 points
2095 and with a caption would be entered:
2096 <br/>
2097 <span class="pre-in-pp">
2098   .G1 GRAP ADJUST +2p CAPTION "Graph caption"
2099   &lt;grap directives&gt;
2100   .G2
2101 </span>
2102
2103 </p>
2104
2105 <div class="rule-medium"><hr/></div>
2106
2107 <h3 id="eqn" class="docs">eqn support</h3>
2108
2109 <p>
2110 Support for <b>eqn</b> is provided via extensions to the standard
2111 <kbd>.EQ/.EN</kbd> macros. <kbd>eqn</kbd> usage itself is beyond
2112 the scope of this documentation, but is covered in the manpage
2113 <kbd>eqn(1)</kbd>.  You can also download a copy of Ted
2114 Harding&#8217;s
2115 <a href="http://lists.gnu.org/archive/html/groff/2013-10/pdfTyBN2VWR1c.pdf">
2116 A Guide to Typesetting Mathematics Using GNU eqn
2117 </a>,
2118 which contains useful examples.  If you use <b>eqn</b>, you must give groff or
2119 pdfmom the <b>-e</b> flag.
2120
2121 </p>
2122
2123 <div class="macro-id-overline">
2124 <h3 id="eq-en" class= "macro-id">.EQ / .EN</h3>
2125 </div>
2126
2127 <div class="box-macro-args">
2128 Macro: <a href="#eq"><b>EQ</b></a>
2129 <br/>
2130 <kbd class="macro-args">Arguments:
2131 <br/>
2132 &nbsp;&nbsp;[ -L | -C | -I &lt;indent&gt; ]</kbd>
2133 <span style="font-size: 95%">
2134 (<a href="definitions.html#unitofmeasure">unit of measure</a>
2135 required)
2136 </span>
2137 <kbd class="macro-args"><br/>
2138 &nbsp;&nbsp;[ ADJUST +|-&lt;vertical adjustment&gt;]</kbd>
2139 <span style="font-size: 95%">
2140 (<a href="definitions.html#unitofmeasure">unit of measure</a>
2141 required)
2142 </span>
2143 <kbd class="macro-args"><br/>
2144 &nbsp;&nbsp;[ NO_SHIM ]
2145 <br/>
2146 &nbsp;&nbsp;[ NO_FLEX ]
2147 <br/>
2148 &nbsp;&nbsp;[ CAPTION "&lt;caption&gt;" ]
2149 <br/>
2150 &nbsp;&nbsp;[ LABEL "&lt;label&gt;" ]
2151 <br/>
2152 &nbsp;&nbsp;[ SHIFT_LABEL +|-&lt;vertical adjustment&gt; ]
2153 <br/>
2154 &nbsp;&nbsp;[ SHORT_CAPTION "&lt;short caption&gt;" ]
2155 <br/>
2156 &nbsp;&nbsp;[ TARGET "&lt;name&gt;" ]
2157 <br/>
2158 &nbsp;&nbsp;[ CONTINUED | CONT | ... ]</kbd>
2159 </div>
2160
2161 <div class="box-tip">
2162 <p class="tip">
2163 <span class="note">Note: Version 2.0-c change</span>
2164 <br/>
2165 2.0-c introduces revisions to <b>EQ</b>, including the addition
2166 of a dash (<kbd>-</kbd>) to the positioning arguments
2167 (<kbd>-L</kbd>, <kbd>-C</kbd>, and <kbd>-I</kbd>) and the removal of a
2168 default value for <kbd>-I</kbd>.  Other changes include passing all
2169 options to <kbd>.EQ</kbd> (including the label) such that
2170 <kbd>.EN</kbd> takes only a single, optional argument saying whether
2171 the equation is to be continued at the next invocation of
2172 <kbd>.EQ</kbd>.  Please read this section carefully if you have
2173 documents containing equations as they may need to be updated.
2174 </p>
2175 </div>
2176
2177 <div class="box-important" style="margin-top: 1em">
2178 <p class="tip">
2179 <span class="important">IMPORTANT:</span>
2180 All arguments to <b>EQ</b> must appear on the same line as
2181 <kbd>.EQ</kbd>.  Do not attempt to break them up with the
2182 &#8220;line-continued&#8221; backslash.  You may want to set your
2183 text editor to &#8220;wrap&#8221; mode in order to see all your
2184 arguments.  This annoyance stems from the preprocessor mechanism
2185 itself, not groff or mom.
2186 </p>
2187 </div>
2188
2189 <div class="macro-id-overline" style="margin-top: .5em">
2190 <h4 id="eq" class="docs" style="font-size: 100%; margin-top: .5em">The .EQ macro</h4>
2191 </div>
2192
2193 <p>
2194 Equations to be set with <b>eqn</b> begin with <kbd>.EQ</kbd>,
2195 followed by <b>eqn</b> code.  Equations are centered by default,
2196 but may be set flush left or indented from the left margin
2197 if <kbd>-L</kbd> or <kbd>-I</kbd> are passed as arguments to
2198 <kbd>.EQ</kbd>.
2199 </p>
2200
2201 <h5 class="docs" style="margin-top: 1em; text-transform: none">ADJUST</h5>
2202
2203 <p>
2204 <kbd>ADJUST</kbd> lets you raise (<kbd>-</kbd>) or lower
2205 (<kbd>+</kbd>) an equation
2206 <span style="font-style: italic">within the space allotted for it</span>
2207 by the amount you specify.  This is useful for achieving good
2208 optical centering between surrounding blocks of type.  A unit of
2209 measure is required.
2210 </p>
2211
2212 <h5 class="docs" style="margin-top: 1em; text-transform: none">NO_SHIM</h5>
2213
2214 <p>
2215 <kbd>NO_SHIM</kbd> instructs mom not to apply
2216 <a href="docprocessing.html#shim-vs-flex">shimming</a>
2217 after an equation, which she will do automatically when shimming is
2218 enabled, which it is by default.  Shimming ensures that running text
2219 after the equation falls properly on the page&#8217;s
2220 <a href="definitions.html#baseline-grid">baseline grid</a>,
2221 but can result in slightly unequal spacing above and
2222 below (correctable with the <kbd>ADJUST</kbd> argument).
2223 <kbd>NO_SHIM</kbd> is useful when you have several equations on the
2224 page and there are visible differences in the spacing beneath them
2225 as a result of shimming.  To ensure a flush bottom margin, the last
2226 equation on the page should be shimmed, i.e. should not be given the
2227 <kbd>NO_SHIM</kbd> argument.
2228 </p>
2229
2230 <h5 class="docs" style="margin-top: 1em; text-transform: none">NO_FLEX</h5>
2231
2232 <p>
2233 <kbd>NO_FLEX</kbd> instructs mom not to apply
2234 <a href="docprocessing.html#shim-vs-flex">flex-spacing</a>
2235 after an equation, which she will do automatically when flex-spacing
2236 is enabled. <kbd>NO_FLEX</kbd> is useful when you have several
2237 equations on the page and you want to distribute excess vertical
2238 whitespace on the page amongst other flex-spacing points on
2239 the page.  If there are no others, the final equation should be
2240 flex-spaced, i.e. not given the <kbd>NO_FLEX</kbd> argument.
2241 </p>
2242
2243 <h5 class="docs" style="margin-top: 1em; text-transform: none">CAPTION</h5>
2244
2245 <p>
2246 <kbd>CAPTION</kbd> allows you to give the equation a caption.
2247 Equation captions always appear beneath the equation.
2248 </p>
2249
2250 <h5 class="docs" style="margin-top: 1em; text-transform: none">SHORT_CAPTION</h5>
2251
2252 <p>
2253 <kbd>SHORT_CAPTION</kbd> allows you to trim long captions for
2254 inclusion in the List of Equations.  The text you supply, surrounded
2255 by double-quotes, is what will appear in the List.
2256 </p>
2257
2258 <h5 class="docs" style="margin-top: 1em; text-transform: none">LABEL</h5>
2259
2260 <p>
2261 <kbd>LABEL</kbd>, if given, appears on the same baseline as the last line of the
2262 equation, flush with the left or right margin, depending on the
2263 equation&#8217;s horizontal position.  The text you supply, surrounded by
2264 double-quotes, is how
2265 the equation is labelled in both the document proper and the List of
2266 Equations.  Mom provides an auto-labelling facility for equations (see
2267 <a href="#autolabel">AUTOLABEL</a>),
2268 which, if enabled, overrides the <kbd>LABEL</kbd> argument.
2269 </p>
2270
2271 <h5 class="docs" style="margin-top: 1em; text-transform: none">SHIFT_LABEL</h5>
2272
2273 <p>
2274 <kbd>SHIFT_LABEL</kbd> allows you to raise (<kbd>-</kbd>) or lower
2275 (<kbd>+</kbd>) the equation label.  It&#8217;s primary use is to
2276 center equation labels vertically on the equation rather than flush
2277 with the last line.  Assuming a three-line equation,
2278 <kbd>.EQ&nbsp;SHIFT_LABEL&nbsp;-1v</kbd> would raise the label by
2279 one line, thus centering it vertically on the equation.
2280 </p>
2281
2282 <h5 class="docs" style="margin-top: 1em; text-transform: none">TARGET</h5>
2283
2284 <p>
2285 <kbd>TARGET</kbd> followed by a unique name surrounded by
2286 double-quotes creates a PDF target for the equation so that it may
2287 be linked to from other places in the file (with PDF_LINK; see
2288 <a href="version-2.html#mom-pdf">Producing PDFs with groff and mom</a>).
2289 </p>
2290
2291 <p>
2292 <b><i>Please note:</i></b> The following functionality is available
2293 only with groff 1.22.4 or later.
2294 </p>
2295
2296 <p>
2297 When
2298 <a href="#autolabel">autolabelling</a>
2299 is enabled and the document is processed with
2300 <a href="using.html#pdfmom" style="font-weight: bold">pdfmom</a>,
2301 the target name can be used to generate the target&#8217;s label
2302 number in running text if it is entered as a groff string, i.e. of
2303 the form <kbd><span class="nobr">\*[name]</span></kbd>.  For example, if you
2304 create a target called &#8220;foo&#8221; for an equation whose
2305 autolabel number would be 3, entering
2306 <br/>
2307 <span class="pre-in-pp">
2308   See
2309   .PDF_LINK foo "Equation \*[foo]"
2310 </span>
2311 anywhere in running text would result in a pdf link that reads
2312 &#8220;Equation 3&#8221;.  If chapter numbers are being prefixed to
2313 labels, the same string in, say, chapter 5 would produce the pdf
2314 link &#8220;Equation 5.3&#8221;.
2315 </p>
2316
2317
2318 <div class="macro-id-overline" style="margin-top: .5em">
2319 <h4 id="en" class="docs" style="font-size: 100%; margin-top: .5em">The .EN macro</h4>
2320 </div>
2321
2322 <p>
2323 A block of <b>eqn</b> code is terminated with <kbd>.EN</kbd>.
2324 </p>
2325
2326 <p>
2327 If an equation needs to span multiple lines, possibly aligned
2328 with <b>eqn</b>&#8217;s <kbd>'mark'</kbd> and <kbd>'lineup'</kbd>
2329 directives, separate invocations of <kbd><span class="nobr">.EQ/.EN</span></kbd>
2330 are required for each line, and the optional argument,
2331 <kbd>CONTINUED</kbd> (or <kbd>CONT</kbd>, or <kbd>...</kbd> [three
2332 dots, an ellipsis]), must be passed to <kbd>.EN</kbd>.
2333 </p>
2334
2335 <p>
2336 If <kbd>-L</kbd> or <kbd>-I</kbd> is given to the first
2337 <kbd>.EQ</kbd> of a multi-line equation, they remain in effect
2338 until an <kbd>.EN</kbd> without the <kbd>CONTINUED</kbd> argument
2339 is reached.
2340 </p>
2341
2342 <p>
2343 Mom does not treat equations as floats, therefore it is possible to
2344 begin an equation on one page and terminate it on the next.  If you
2345 wish to keep all lines of an equation together, you must wrap the
2346 equation, including all invocations of <kbd>.EQ/.EN</kbd>, inside
2347 a
2348 <a href="#floats-intro">float</a>.
2349 </p>
2350
2351 <div class="rule-medium"><hr/></div>
2352
2353 <h3 id="refer" class="docs">refer support</h3>
2354
2355 <p>
2356 <b>refer</b> support is covered in the section
2357 <a href="refer.html">Bibliographies and references</a>.
2358 </p>
2359
2360 <div class="rule-medium"><hr/></div>
2361
2362 <h2 id="captions-and-labels" class="docs">Captions and labels</h2>
2363
2364 <ul>
2365   <li><a href="#autolabel">AUTOLABEL</a></li>
2366   <li><a href="#caption-after-label">CAPTION_AFTER_LABEL</a></li>
2367   <li><a href="#mla">MLA</a>&mdash;MLA-style captioning and labelling</li>
2368   <li><a href="#captions-labels-sources">Set style parameters for captions, labels, and sources</a></li>
2369 </ul>
2370
2371 <p>
2372 Mom includes facilities for adding captions and labels to figures,
2373 tables, equations, and pdf images, including auto-labelling.  If
2374 Lists of Figures, Tables, and Equations are desired, captions (if
2375 any) and labels (if any) are collected and output in the Lists with
2376 the appropriate page number.
2377 </p>
2378
2379 <p>
2380 The distinction between a caption and a label is that labels are
2381 identifiers, e.g. &#8220;Fig. 1&#8221; or &#8220;Table 3&#8221;,
2382 while captions are descriptive or informative.  For most types of
2383 writing, it is usual to provide both.
2384 </p>
2385
2386 <p>
2387 By default, mom sets captions above figures (i.e. <b>pic</b> output and
2388 pdf images) and tables.  This behaviour may be modified with the
2389 macro
2390 <a href="#caption-after-label">CAPTION_AFTER_LABEL</a>.
2391 Equations always have their captions set underneath.  All aspects of
2392 the text style for captions may be set with the macro
2393 <a href="#captions-labels-sources">CAPTIONS</a>.
2394 </p>
2395
2396 <p>
2397 Labels for tables are set underneath the table unless the
2398 <a href="#mla">MLA</a>
2399 macro has been invoked, in which case the label and caption appear
2400 above the table, per MLA style, and the source for the table, if
2401 any, appears underneath.  Labels for figures are set underneath.
2402 Equation labels, by default, are set on the same baseline as the
2403 last line of the equation.  Like captions, all aspects of text style
2404 for labels may be established with a single macro
2405 <a href="#labels">LABELS</a>.
2406 Furthermore, mom can autolabel figures, tables, and equations, with
2407 or without a prefixed chapter number.
2408 </p>
2409
2410 <div class="macro-id-overline">
2411 <h3 id="autolabel" class="macro-id">Autolabel</h3>
2412 </div>
2413
2414 <div class="box-macro-args">
2415 Macro: <b>AUTOLABEL_EQUATIONS</b>
2416 <br/>
2417 Macro: <b>AUTOLABEL_IMAGES</b>
2418 <br/>
2419 Macro: <b>AUTOLABEL_PIC</b>
2420 <br/>
2421 Macro: <b>AUTOLABEL_TABLES</b>
2422 <br/>
2423 <kbd class="macro-args">Arguments:
2424 <br/>
2425 [ PREFIX "&lt;string&gt;"] [ SUFFIX "&lt;string&gt;"] [ PREFIX_CHAPTER [ &lt;n&gt; ] ]
2426 </kbd>
2427 </div>
2428
2429 <p>
2430 <b>AUTOLABEL_&lt;type&gt;</b> takes care of labelling &lt;type&gt; by
2431 identifying each with a separate, incrementing numeric scheme, which
2432 is also collected for output in Lists of Figures, Equations, and
2433 Tables.
2434 </p>
2435
2436 <p>
2437 Autolabelling may be disabled on-the-fly by giving any argument
2438 other than <kbd>PREFIX</kbd>, <kbd>SUFFIX</kbd>, or
2439 <kbd>PREFIX_CHAPTER</kbd> to the appropriate macro.  For example,
2440 <br/>
2441 <span class="pre-in-pp">
2442   .AUTOLABEL_IMAGES NO
2443 </span>
2444 would disable autolabelling of images.
2445 </p>
2446
2447 <h4 class="docs" style="margin-top: -.5em">Prefixes and suffixes</h4>
2448
2449 <p>
2450 By default, when <b>AUTOLABEL</b> is enabled, the label numbers are
2451 prefixed, and, in the case of equations, suffixed, with strings such
2452 that they appear for tables as &#8220;Table&nbsp;&lt;n&gt;&#8221;, for
2453 <b>pic</b> diagrams and pdf images as &#8220;Fig.&nbsp;&lt;n&gt;&#8221;,
2454 and for equations as &#8220;Eq.&nbsp;(&lt;n&gt;)&#8221;.
2455 </p>
2456
2457 <p>
2458 You can use <kbd>PREFIX&nbsp;&lt;"string"&gt;</kbd> to change what
2459 comes before the automatic numbering.  For example, if you are
2460 including musical excerpts in your document, MLA style requires that
2461 they be labelled &#8220;Ex.&nbsp;&lt;n&gt;&#8221;.  Since musical
2462 excerpts are likely to be scanned images (in pdf format, don&#8217;t
2463 forget), you have to change the prefix string for pdf images:
2464 <br/>
2465 <span class="pre-in-pp">
2466   .AUTOLABEL_IMAGES \
2467    PREFIX "Ex. " \
2468    SUFFIX ""
2469 </span>
2470 If you need a suffix after the automatic numbering, use
2471 <kbd>SUFFIX&nbsp;&lt;"string"&gt;</kbd>, like this:
2472 <br/>
2473 <span class="pre-in-pp">
2474   .AUTOLABEL_IMAGES \
2475    PREFIX "(Fig. " \
2476    SUFFIX ")"
2477 </span>
2478 Note from the above that both arguments, <kbd>PREFIX</kbd> and
2479 <kbd>SUFFIX</kbd>, are required should you want either.  Two
2480 adjacent double-quotes leaves the string blank.
2481 </p>
2482
2483 <div class="box-tip">
2484 <p class="tip">
2485 <span class="note">Note:</span>
2486 In automatically formatted
2487 <a href="#lists-macros">&#8220;Lists of ...&#8221;</a>,
2488 label number prefixes are stripped when autolabelling is enabled.
2489 </p>
2490 </div>
2491
2492 <h4 class="docs" style="margin-top: -.5em">Prefixing chapter numbers</h4>
2493
2494 <p>
2495 If you would like mom to prefix chapter numbers to the label,
2496 pass <kbd>AUTOLABEL_&lt;type&gt;</kbd> the argument
2497 <kbd>PREFIX_CHAPTER</kbd>.
2498 </p>
2499
2500 <p>
2501 If for some reason you need to specify the chapter number,
2502 you may do so by passing the number as an argument to
2503 <kbd>PREFIX_CHAPTER</kbd>.  Subsequent chapters or major sections
2504 will increment by one as expected.
2505 </p>
2506
2507 <div class="box-tip">
2508 <p class="tip">
2509 <span class="note">Note:</span>
2510 For the purposes of labelling, mom treats
2511 <a href="docprocessing.html#doctype">DOCTYPE&nbsp;DEFAULT</a>
2512 as if it were <b>DOCTYPE&nbsp;CHAPTER</b>, hence, with
2513 <kbd>PREFIX_CHAPTER</kbd>, each collated <b>DEFAULT</b>
2514 doctype&#8217;s prefixed &#8220;chapter&#8221; number is
2515 incremented and the label number itself reset to &#8220;1&#8221;.
2516 If you do not supply the <kbd>PREFIX_CHAPTER</kbd> argument, the
2517 label number is <i>not</i> reset automatically.  To reset it, invoke
2518 <kbd>.AUTOLABEL_&lt;type&gt;</kbd> after each
2519 <a href="docprocessing.html#collate">COLLATE</a>.
2520 </p>
2521 </div>
2522
2523 <div id="set-autolabel" class="box-macro-args" style="margin-top: .5em">
2524 Macro: <b>SET_AUTOLABEL</b> <kbd class="macro-args">FIG | TBL | PIC | EQN &lt;n&gt;</kbd>
2525 </div>
2526
2527 <p>
2528 You may sometimes need to set or reset the autolabel number for a
2529 particular type of pre-processor or for PDF images.  This is likely
2530 to occur if you are using
2531 <a href="#float">FLOAT</a>
2532 in conjunction with the <kbd>TO_LIST</kbd> argument.
2533 </p>
2534
2535 <p>
2536 For example, if your document has Figures (PDF images, pic diagrams)
2537 and you want your tables to be labelled as Figures as well, you have
2538 to wrap the tables inside a float and label the float manually as
2539 &#8220;Fig.&nbsp;n&#8221;, sending it to the List of Figures with
2540 <kbd>TO_LIST FIGURES</kbd>.
2541 </p>
2542
2543 <p>
2544 Mom does not autolabel floats or assign them automatically
2545 to a list, so she doesn&#8217;t know you&#8217;ve interrupted the
2546 auto-incrementing label numbers.  Use SET_AUTOLABEL get her back on
2547 track.  The number you give as an argument after telling her which
2548 kind of label number to set is the one you want to appear next.
2549 <br/>
2550 <span class="pre-in-pp">
2551   .SET_AUTOLABEL FIG 6
2552 </span>
2553 means the next autolabelled Figure will be &#8220;Fig. 6.&#8221;
2554 </p>
2555
2556 <div class="macro-id-overline">
2557 <h3 id="caption-after-label" class="macro-id">Captions after labels</h3>
2558 </div>
2559
2560 <div class="box-macro-args" style="margin-top: .5em">
2561 Macro: <b>CAPTION_AFTER_LABEL</b> <kbd class="macro-args">IMG | PIC | TBL | ALL [ &lt;anything&gt; ]</kbd>
2562 </div>
2563
2564 <p>
2565 By default, mom sets captions above figures (<b>pic</b> output
2566 and pdf images) and tables; labels are always underneath.
2567 </p>
2568
2569 <p>
2570 <kbd>.CAPTION_AFTER_LABEL</kbd>, with one of the required arguments,
2571 instructs mom to attach captions directly to the appropriate
2572 labels, beginning on the same line.  Any argument after the first
2573 disables this behaviour, restoring caption placement to mom&#8217;s
2574 default.  For example,
2575 <br/>
2576 <span class="pre-in-pp">
2577   .CAPTION_AFTER_LABEL ALL
2578 </span>
2579 would enable captions after labels globally, while a subsequent
2580 <br/>
2581 <span class="pre-in-pp">
2582   .CAPTION_AFTER_LABEL IMG OFF
2583 </span>
2584 would disable captions after labels for pdf images only.
2585 <kbd>OFF</kbd> can be anything you like (<kbd>X</kbd>,
2586 <kbd>NO</kbd>, etc).
2587 </p>
2588
2589 <p>
2590 If
2591 <a href="#mla">MLA</a>
2592 is enabled, there&#8217;s no need to invoke
2593 <kbd>CAPTION_AFTER_LABEL</kbd> as this is implied.
2594 </p>
2595
2596 <div class="box-tip">
2597 <p class="tip">
2598 <span class="note">Note:</span>
2599 A separate invocation of <kbd>.CAPTION_AFTER_LABEL</kbd> is required
2600 for each one of the required first arguments.  You cannot, for
2601 example, do
2602 <br/>
2603 <span class="pre-in-pp">
2604   .CAPTION_AFTER_LABEL IMG TBL
2605 </span>
2606 Rather, you must do
2607 <br/>
2608 <span class="pre-in-pp">
2609   .CAPTION_AFTER_LABEL IMG
2610   .CAPTION_AFTER_LABEL TBL
2611 </span>
2612 </p>
2613 </div>
2614
2615 <div class="macro-id-overline">
2616 <h3 id="mla" class="macro-id">MLA-style captioning and labelling</h3>
2617 </div>
2618
2619 <div class="box-macro-args" style="margin-top: .5em">
2620 Macro: <b>MLA</b> <kbd class="macro-args"> [ &lt;anything&gt; ]</kbd>
2621 </div>
2622
2623 <p>
2624 Modern Language Association style dictates that captions should
2625 always go after labels.  Furthermore, labels and captions for tables
2626 should go <i>above</i> the tables, with the source for the table, if
2627 any, underneath.
2628 </p>
2629
2630 <p>
2631 Invoking <kbd>.MLA</kbd> by itself takes care of these details.  If
2632 you need to disable MLA-style captioning and labelling mid-document,
2633 <kbd>.MLA&nbsp;OFF</kbd> does the trick. <kbd>OFF</kbd> can be
2634 anything you like (<kbd>X</kbd>, <kbd>NO</kbd>, etc).
2635 </p>
2636
2637 <div class="macro-id-overline" style="margin-top: 1em">
2638 <h3 id="captions-labels-sources" class="macro-id">Style parameters for captions, labels and sources</h3>
2639 </div>
2640
2641 <div class="box-macro-args" style="margin-top: .5em">
2642 Macro: <b>CAPTIONS</b> <kbd class="macro-args">EQN | IMG | PIC | TBL | FLOATING | ALL</kbd>
2643 <br/>
2644 Macro: <b>LABELS</b> <kbd class="macro-args">EQN | IMG | PIC | TBL | FLOATING | ALL</kbd>
2645 <br/>
2646 Macro: <b>SOURCES</b> <kbd class="macro-args">TBL</kbd>
2647 <br/>
2648 <kbd class="macro-args">Style arguments:
2649 <br/>
2650 &nbsp;&nbsp;FAMILY &lt;family&gt; \
2651 <br/>
2652 &nbsp;&nbsp;FONT &lt;font&gt; \
2653 <br/>
2654 &nbsp;&nbsp;SIZE +|-&lt;size&gt; \
2655 <br/>
2656 &nbsp;&nbsp;AUTOLEAD &lt;value&gt; \
2657 <br/>
2658 &nbsp;&nbsp;COLOR &lt;color&gt; \
2659 <br/>
2660 &nbsp;&nbsp;QUAD LEFT | CENTER | RIGHT [ ON_LL ] \
2661 <br/>
2662 &nbsp;&nbsp;INDENT &lt;indent&gt; \
2663 <br/>
2664 &nbsp;&nbsp;ADJUST +|-&lt;vertical adjustment&gt;
2665 </kbd>
2666 </div>
2667
2668 <div class="box-tip">
2669 <p class="tip">
2670 <span class="note">Note:</span>
2671 Arguments may be broken into several lines using the
2672 &#8220;line-continued&#8221; backslash (<b>\</b>), as shown above.
2673 </p>
2674 </div>
2675
2676 <div class="box-tip">
2677 <p class="tip">
2678 <span class="note">Additional note:</span>
2679 Mom&#8217;s default style for labels, captions, and sources is
2680 the same as the style used for running text, with two exceptions:
2681 labels are set in bold, except for eqn which is roman medium, and
2682 the autolead value for all three is &#8220;2&#8221;, effectively
2683 tightening the lead.  Furthermore, they are quadded left (except
2684 eqn, which is quadded right.)
2685 </p>
2686 </div>
2687
2688 <p>
2689 With the exception of <kbd>ADJUST</kbd> and <kbd>QUAD</kbd> (which
2690 requires a bit of explanation), the style arguments to <kbd>CAPTIONS</kbd>,
2691 <kbd>LABELS</kbd>, and <kbd>SOURCES</kbd> (which is only available
2692 for tables) behave identically to the
2693 <a href="docelement.html#control-macro-args">arguments to control macros</a>.
2694 </p>
2695
2696 <p>
2697 The first, required argument after <kbd>CAPTIONS</kbd>,
2698 <kbd>LABELS</kbd>, or <kbd>SOURCES</kbd> indicates the preprocessor
2699 type for which you are setting the parameters.  (For convenience
2700 PDF_IMAGE&mdash;argument <kbd>IMG</kbd>&mdash;is here treated as a
2701 preprocessor.)  <kbd>FLOATING</kbd> sets the style for the macros
2702 <a href="#caption">CAPTION</a>
2703 and
2704 <a href="#label">LABEL</a>,
2705 which are used to label floats, quotes, and blockquotes.
2706 </p>
2707
2708 <p>
2709 An argument of <kbd>ALL</kbd> sets a unified style for all
2710 preprocessors, floats, quotes, and blockquotes.  If the
2711 <kbd>ALL</kbd> argument is given, arguments to subsequent
2712 invocations of <kbd>CAPTIONS</kbd>, <kbd>LABELS</kbd>, or
2713 <kbd>SOURCES</kbd> overwrite only the explicitly named style
2714 parameters.
2715 </p>
2716
2717 <h4 class="docs">QUAD &mdash; quadding of labels, captions, and sources</h4>
2718
2719 <h5 class="docs" style="text-transform: none">&bull;&nbsp;pic, tbl, pdf images</h5>
2720
2721 <p>
2722 By default, figures (<b>pic</b> output and pdf images) and tables
2723 have their captions and labels set quad left.  Sources (for
2724 tables) are also set quad left.  Equations have their labels
2725 set quad right, and their captions centered.
2726 </p>
2727
2728 <p>
2729 Regardless of the quad direction, captions, labels and sources
2730 are set on the width of the figure, table, or pdf image
2731 unless you pass the optional <kbd>ON_LL</kbd> argument to
2732 <kbd><span class="nobr">QUAD&nbsp;&lt;direction&gt;</span></kbd>, in which case
2733 the prevailing document line length is used instead.
2734 </p>
2735
2736 <h5 class="docs" style="text-transform: none">&bull;&nbsp;eqn</h5>
2737
2738 <p>
2739 Equations behave differently.  By default, equation labels are
2740 set flush right with the page&#8217;s right margin regardless of
2741 equation positioning, which is, again by default, centered.  If the
2742 equation is positioned left, the label will appear at the right
2743 margin regardless of the direction you give to <kbd>QUAD</kbd>.  If
2744 the equation is indented with the
2745 <kbd><span class="nobr">-I&nbsp;&lt;indent&gt;</span></kbd> option, a quad
2746 direction of <kbd>LEFT</kbd> is observed, but may overprint the last
2747 line of the equation.
2748 </p>
2749
2750 <p>
2751 Note that there is no <kbd>CENTER</kbd> option for equation labels,
2752 and that captions are always quadded over the prevailing document
2753 line length.
2754 </p>
2755
2756 <h5 class="docs" style="text-transform: none">&bull;&nbsp;quotes and blockquotes</h5>
2757
2758 <p>
2759 Floating labels attached to <b>QUOTE</b>s are quadded on the
2760 prevailing document line length, and require the <kbd>INDENT</kbd>
2761 argument if you want to align them with the left and/or right edges
2762 the quote.
2763 </p>
2764
2765 <p>
2766 Floating labels attached to <b>BLOCKQUOTE</b>s are always quadded on
2767 the indent and line length of the blockquote.
2768 </p>
2769
2770 <h5 class="docs" style="text-transform: none">&bull;&nbsp;floats</h5>
2771
2772 <p>
2773 Floating labels and captions attached to <b>FLOAT</b>s are always
2774 quadded over the prevailing document line length, and require the
2775 <kbd>INDENT</kbd> argument if you want to align them with the left
2776 and/or right edges of the float&#8217;s contents.
2777 </p>
2778
2779 <h4 class="docs">INDENT</h4>
2780
2781 <p>
2782 The <kbd>INDENT</kbd> argument may only be used if the label
2783 or caption type is <kbd>FLOATING</kbd>, and only applies to
2784 <b>FLOAT</b>s and <b>QUOTE</b>s, not <b>BLOCKQUOTE</b>s.
2785 </p>
2786
2787 <p>
2788 It is not possible for mom to know the width of a float before
2789 setting a label or caption attached to a float.  She therefore sets
2790 it on the prevailing document line length.  While this isn&#8217;t
2791 much of an issue when the label or caption quad is <b>CENTER</b>,
2792 you may want to adjust the horizontal positioning when the quad is
2793 <b>LEFT</b> or <b>RIGHT</b>.
2794 </p>
2795
2796 <p>
2797 <kbd>INDENT</kbd>, with a numeric value to which a
2798 <a href="definitions.html#unitofmeasure">unit of measure</a>
2799 is appended, allows you to indent a floating label or caption so
2800 it lines up with the left edge of a <b>FLOAT</b> or <b>QUOTE</b>.
2801 <kbd>INDENT&nbsp;RIGHT</kbd> (with a value) allows you to shorten the
2802 line length to the appropriate width.  If you need both a left and
2803 right indent, invoke <kbd>LABELS</kbd> or <kbd>CAPTIONS</kbd> twice,
2804 one instance containing <kbd>INDENT&nbsp;&lt;indent&gt;</kbd> and
2805 the other <kbd>INDENT&nbsp;RIGHT&nbsp;&lt;indent&gt;</kbd>.
2806 </p>
2807
2808 <h4 class="docs">ADJUST</h4>
2809
2810 <p>
2811 The <kbd>ADJUST</kbd> argument allows you to add(<kbd>+</kbd>) or
2812 subtract (<kbd>-</kbd>) vertical space between labels and captions
2813 and the output to which they are attached.  The argument requires a
2814 <a href="definitions.html#unitofmeasure">unit of measure</a>.
2815 For example, if you find that table labels are a bit too close to
2816 the table itself,
2817 <br/>
2818 <span class="pre-in-pp">
2819   .LABELS TBL ADJUST +3p
2820 </span>
2821 would put three extra points of space between the bottoms of tables
2822 and the labels that appear beneath them.
2823 </p>
2824
2825 <h2 id="lists-of" class="docs">Lists of Figures, Tables, and Equations</h2>
2826
2827 <p>
2828 Besides a
2829 <a href="tables-of-contents.html">Table of Contents</a>,
2830 mom can generate Lists of Figures, Tables, and Equations.  Labels
2831 and captions are collected and concatenated, and output in lists
2832 with the appropriate page number, just like a Table of Contents.
2833 Including such lists in a document is as simple as adding whichever
2834 you need of
2835 <br/>
2836 <span class="pre-in-pp">
2837   .LIST_OF_FIGURES
2838   .LIST_OF_EQUATIONS
2839   .LIST_OF_TABLES
2840 </span>
2841 to the end of your input file.
2842 </p>
2843
2844 <p>
2845 Also like the Table of Contents, entries in the Lists&#8217; output
2846 are clickable PDF links when a document is viewed at the screen.
2847 </p>
2848
2849 <h3 id="lists-placement" class="docs">Placement of Lists</h3>
2850
2851 <p>
2852 Lists normally appear after the Table of Contents, and continue
2853 the page numbering scheme used for it.  By default, the Table of
2854 Contents begins on roman-numeral page &#8220;i&#8221;.
2855 </p>
2856
2857 <p>
2858 If you are using mom&#8217;s
2859 <a href="tables-of-contents.html#auto-relocate-toc">AUTO_RELOCATE_TOC</a>
2860 feature, you have two options for placement of the Lists within the
2861 document.  If you want the Lists shifted to the top of the document
2862 along with the Table of Contents, invoke the Lists macros <i>after</i>
2863 <a href="tables-of-contents.html#toc"><kbd>.TOC</kbd></a>.
2864 If you prefer to have the Lists at the end of the document, invoke
2865 the Lists macros <i>before</i> <kbd>.TOC</kbd>.
2866 </p>
2867
2868 <p>
2869 Lists shifted with the Table of Contents do not appear in the Table
2870 of Contents itself, but do appear as clickable links in the PDF
2871 outline typically available in the left panel of most PDF viewers.
2872 Lists that are not shifted with the Table of Contents appear in both
2873 the Table of Contents itself and the PDF outline.
2874 </p>
2875
2876 <div class="macro-id-overline" style="margin-top: 1em">
2877 <h3 id="lists-macros" class="macro-id">Macros to generate Lists</h3>
2878 </div>
2879
2880 <div class="box-macro-args" style="margin-top: .5em">
2881 Macro: <b>LIST_OF_EQUATIONS</b>
2882 <br/>
2883 Macro: <b>LIST_OF_FIGURES</b>
2884 <br/>
2885 Macro: <b>LIST_OF_TABLES</b>
2886 <br/>
2887 <kbd class="macro-args">Arguments:
2888 <br/>
2889 &nbsp;&nbsp;[ TITLE_STRING "&lt;string&gt;" ] [ START_PAGENUM &lt;page number&gt; ]
2890 </kbd>
2891 </div>
2892
2893 <p>
2894 The first optional argument to the <kbd>LIST_OF_&lt;type&gt;</kbd>
2895 macros allows you to change the title that appears at the top of the
2896 page.  This is useful not only for internationalization, or to meet
2897 the requirements of various style guides, but is also useful
2898 for, say, documents containing musical examples, which, per
2899 MLA-style, should be labelled &#8220;Example &#8221; or
2900 &#8220;Ex. &#8221;.  When it comes time to output the List of
2901 Figures (to which musical examples, usually scanned pdf images, belong),
2902 <br/>
2903 <span class="pre-in-pp">
2904   LIST_OF_FIGURES TITLE_STRING "List of Examples"
2905 </span>
2906 ensures that the title of the List is correct.
2907 </p>
2908
2909 <p>
2910 The second optional argument allows you to give a starting page
2911 number for a list in cases where mom&#8217;s pagination scheme does
2912 not provide the List with the starting page number you want.
2913 </p>
2914 <h3 id="formatting-lists" class="docs">Formatting and style parameters for Lists</h3>
2915
2916 <p>
2917 Like the Table of Contents, nearly every aspect of Lists can be
2918 designed independently of a document&#8217;s overall style.  By
2919 default, Lists follow the formatting and style parameters of the
2920 Table of Contents, both mom&#8217;s defaults and any changes you may
2921 have made to the Table of Contents.
2922 </p>
2923
2924 <p>
2925 If you wish to make changes to any aspect of Lists formatting
2926 or styling, the macro <kbd>LISTS_STYLE</kbd> provides all the
2927 tools necessary.  It is unlikely that you&#8217;ll want the
2928 formatting of the various list types to differ one from the other,
2929 so <kbd>LISTS_STYLE</kbd> applies to all Lists.  In the event that
2930 you do need to change some aspect of the formatting for different
2931 list types, simply invoke <kbd>LISTS_STYLE</kbd> immediately prior
2932 to each list whose formatting needs to be changed.
2933 </p>
2934
2935 <div class="macro-id-overline" style="margin-top: 1em">
2936 <h3 id="lists-style" class="macro-id">Lists style</h3>
2937 </div>
2938
2939 <div class="box-macro-args" style="margin-top: .5em">
2940 Macro: <b>LISTS_STYLE</b> <kbd class="macro-args">
2941 <br/>
2942 Arguments:
2943 <br/>
2944 &nbsp;&nbsp;FAMILY &lt;family&gt; \
2945 <br/>
2946 &nbsp;&nbsp;FONT &lt;font&gt; \
2947 <br/>
2948 &nbsp;&nbsp;PT_SIZE &lt;size&gt; \
2949 <br/>
2950 &nbsp;&nbsp;LEAD &lt;leading&gt; \
2951 <br/>
2952 &nbsp;&nbsp;TITLE_FAMILY &lt;family&gt; \
2953 <br/>
2954 &nbsp;&nbsp;TITLE_FONT &lt;font&gt; \
2955 <br/>
2956 &nbsp;&nbsp;TITLE_SIZE +|-&lt;size&gt; \
2957 <br/>
2958 &nbsp;&nbsp;TITLE_QUAD LEFT | CENTER | RIGHT \
2959 <br/>
2960 &nbsp;&nbsp;TOC_HEADER_UNDERSCORE default = none
2961 <br/>
2962 &nbsp;&nbsp;TITLE_COLOR &lt;color&gt; \
2963 <br/>
2964 &nbsp;&nbsp;PN_FAMILY &lt;family&gt; \
2965 <br/>
2966 &nbsp;&nbsp;PN_FONT &lt;font&gt; \
2967 <br/>
2968 &nbsp;&nbsp;PN_SIZE +|-&lt;size&gt; \
2969 <br/>
2970 &nbsp;&nbsp;EQN_PN_PADDING &lt;placeholders&gt; \
2971 <br/>
2972 &nbsp;&nbsp;FIG_PN_PADDING &lt;placeholders&gt; \
2973 <br/>
2974 &nbsp;&nbsp;TBL_PN_PADDING &lt;placeholders&gt; \
2975 <br/>
2976 &nbsp;&nbsp;PAGENUM_STYLE DIGIT | ROMAN | roman | ALPHA | alpha \
2977 <br/>
2978 &nbsp;&nbsp;NO_PAGINATION
2979 </kbd>
2980 </div>
2981
2982 <div class="box-tip">
2983 <p class="tip">
2984 <span class="note">Note:</span>
2985 Arguments may be broken into several lines using the
2986 &#8220;line-continued&#8221; backslash (<b>\</b>), as shown above.
2987 </p>
2988 </div>
2989
2990 <p>
2991 <kbd>FAMILY</kbd> is the family for the entirety of Lists pages.
2992 </p>
2993
2994 <p>
2995 <kbd>FONT</kbd> is the font for the entirety of Lists pages.
2996 </p>
2997
2998 <p>
2999 <kbd>PT_SIZE</kbd> is the base point size for the entirety of Lists
3000 pages.
3001 </p>
3002
3003 <p>
3004 <kbd>LEAD</kbd> is the base leading for the entirety of Lists pages.
3005 </p>
3006
3007 <p>
3008 <kbd>TITLE_FAMILY</kbd> is the family for the Lists titles if you
3009 want it different from the family otherwise used for the Lists
3010 pages.
3011 </p>
3012
3013 <p>
3014 <kbd>TITLE_FONT</kbd> is the font for the Lists titles if you want
3015 it different from the font otherwise used for the Lists pages.
3016 </p>
3017
3018 <p>
3019 <kbd>TITLE_SIZE</kbd> tells mom by how much to increase
3020 (<kbd>+</kbd>) or decrease (<kbd>-</kbd>) the point size of the
3021 titles relative to the overall point size of Lists pages.
3022 </p>
3023
3024 <p>
3025 <kbd>TITLE_QUAD</kbd> tells mom how to position the title
3026 horizontally.
3027 </p>
3028
3029 <p>
3030 <kbd>TITLE_COLOR</kbd> sets the colour for the titles.  The colour
3031 must be pre-initialized with
3032 <a href="color.html#newcolor">NEWCOLOR</a>
3033 or
3034 <a href="color.html#xcolor">XCOLOR</a>.
3035 </p>
3036
3037 <p>
3038 <kbd>PN_FAMILY</kbd> sets the family for entry pagenumbers.
3039 </p>
3040
3041 <p>
3042 <kbd>PN_FONT</kbd> sets the font for entry pagenumbers.
3043 </p>
3044
3045 <p>
3046 <kbd>PN_SIZE</kbd> tells mom by how much to increase (<kbd>+</kbd>)
3047 or decrease (<kbd>-</kbd>) the point size of entry pagenumbers
3048 relative to the overall point size of Lists pages.
3049 </p>
3050
3051 <p>
3052 <kbd>EQN_PN_PADDING</kbd>, <kbd>FIG_PN_PADDING</kbd>, and
3053 <kbd>TBL_PN_PADDING</kbd> tells mom how many placeholders to reserve
3054 for the entry pagenumbers in their respective Lists.  If, for example,
3055 a document with both tables and figures runs to over a hundred
3056 pages, but there are no tables after page 99,
3057 <br/>
3058 <span class="pre-in-pp">
3059   LISTS_STYLE FIG_PN_PADDING 3
3060   LISTS_STYLE TBL_PN_PADDING 2
3061 </span>
3062 would prevent an unneeded, reserved placeholder from putting too
3063 much space between the leader and the entry pagenumber in the List of
3064 Tables.
3065 </p>
3066
3067 <p>
3068 The padding in effect, unless you change it, is whatever was set for
3069 the Tables of Contents; mom&#8217;s default is &#8220;3&#8221;.
3070 </p>
3071
3072 <p>
3073 <kbd>PAGENUM_STYLE</kbd> tells mom which pagination format to use
3074 for the page numbers of the Lists pages themselves.  By default,
3075 since Lists observe what is in effect for the Table of Contents, the
3076 pagination format is &#8220;roman&#8221;.  Please note that the
3077 starting page number for any of the Lists is given as an argument to
3078 the
3079 <a href="#lists-of">LISTS_0F_&lt;type&gt;</a>
3080 macro.
3081 </p>
3082
3083 <p>
3084 <kbd>NO_PAGINATION</kbd> disables pagination of Lists pages.
3085 </p>
3086
3087 <h2 id="box-intro" class="docs">Shaded backgrounds and frames (boxes)</h2>
3088
3089 <p>
3090 Mom lets you add shaded backgrounds and frames to text and other
3091 material.  For convenience, she calls backgrounds and frames
3092 &#8220;boxes.&#8221; Entire passages may be boxed, or individual
3093 document elements like headings, quotes, or pre-processor output.
3094 Furthermore, boxes may be nested.
3095 </p>
3096
3097 <p>
3098 Boxes start on the baseline where the boxed material would have
3099 started were it not for the box, subject to minor aesthetic
3100 corrections mom takes the liberty of making.
3101 </p>
3102
3103 <p>
3104 Boxes extend from the current left margin to the current right
3105 margin, respecting any active left and/or right indents.  There are
3106 two exceptions,
3107 <a href="docelement.html#epigraph">EPIGRAPH BLOCK</a>
3108 and
3109 <a href="docelement.html#blockquote">BLOCKQUOTE</a>,
3110 which are discussed
3111 <a href="#quotes">here</a>.
3112 </p>
3113
3114 <p>
3115 After a box is started, active left and right indents are
3116 cleared.  The box&#8217;s inset determines the new left and right
3117 margins.  Indents set inside a box are relative to the inset.
3118 When a box is stopped, formerly active left and right indents
3119 are restored.
3120 </p>
3121
3122 <p>
3123 Frames are drawn from the perimeter inward.  The inset is
3124 relative to the inner edge of the frame.
3125 </p>
3126
3127 <p>
3128 If a box (including the bottom inset) can complete on a page, it
3129 does, even if there is no further room for type.  This may, on
3130 occasion, result in slight deviations from normal bottom margin
3131 alignment.
3132 </p>
3133
3134 <p>
3135 Boxes span pages whenever the boxed material continues on the next
3136 page.  Spanning boxes extend fully to the bottom margin of the page
3137 on which they begin, leaving a slightly larger inset at the bottom
3138 than around the other sides.
3139 </p>
3140
3141 <p>
3142 When there is not enough room to set at least one line of type
3143 inside a box, mom defers starting the box until the next page,
3144 leaving a gap.
3145 </p>
3146
3147 <p>
3148 Boxed material is not
3149 <a href="docprocessing.html#shim-vs-flex">shimmed</a>
3150 or
3151 <a href="docprocessing.html#shim-vs-flex">flexed</a>.
3152 If either was active prior to the box, it is restored when the box
3153 ends and mom automatically shims or flexes whatever comes next.
3154 </p>
3155
3156 <div class="box-tip">
3157 <p class="tip">
3158 <span class="important">NOTE:</span>
3159 Shaded backgrounds and frames are not available when your
3160 <a href="docprocessing.html#printstyle">PRINTSTYLE</a>
3161 is <kbd>TYPEWRITE</kbd> or when
3162 <a href="docprocessing.html#columns">COLUMNS</a> are enabled.
3163 </p>
3164 </div>
3165
3166 <div class="macro-id-overline">
3167 <h3 id="box" class= "macro-id">BOX</h3>
3168 </div>
3169
3170 <div id="box-macro" class="box-macro-args" style="margin-top: .5em">
3171 Macro: <b>BOX</b> <kbd class="macro-args"> [ &lt;arguments&gt; ] | &lt;anything&gt;
3172 <br/>
3173 Arguments:
3174 <br/>
3175 [ SHADED &lt;color&gt; | OUTLINED &lt;colour&gt; ] \
3176 <br/>
3177 [ INSET &lt;dist&gt; ] \
3178 <br/>
3179 [ WEIGHT &lt;wt&gt; ] \
3180 <br/>
3181 [ ADJUST +|-&lt;amount&gt; ] \
3182 <br/>
3183 [ EQN | PIC | GRAP | IMG ]
3184 </kbd>
3185 </div>
3186
3187 <p>
3188 Without arguments, BOX begins a shaded grey background.
3189 The material inside is inset by one
3190 <a href="definitions.html#picaspoints">pica</a>.
3191 Any other type of box requires at a minimum either
3192 <kbd>SHADED</kbd> or <kbd>OUTLINED</kbd>.  In the case of boxes
3193 that are to contain pdf images or pre-processor material for
3194 <a href="#eqn">eqn</a>,
3195 <a href="#pic">pic</a>,
3196 or
3197 <a href="#grap">grap</a>,
3198 <kbd>IMG</kbd>, <kbd>EQN</kbd>, <kbd>PIC</kbd>, or <kbd>GRAP</kbd>
3199 must also be given.  Note that
3200 <a href="#tbl">tbl</a>
3201 does not have this requirement.
3202 </p>
3203
3204 <p>
3205 BOX is a
3206 <a href="definitions.html#toggle">toggle macro</a>,
3207 so any argument other than one in the list completes the box
3208 (<kbd>QUIT</kbd>, <kbd>END</kbd>, <kbd>X</kbd>, etc).
3209 </p>
3210
3211 <p>
3212 Boxes should be started inside toggle macros like
3213 <a href="docelement.html#quote">QUOTE</a>
3214 or
3215 <a href="#float">FLOAT</a>
3216 just after the macro is called, and terminated just before toggling
3217 the macro off (unless you wish the box to enclose further material).
3218 </p>
3219
3220 <p>
3221 Non-toggle macros like
3222 <a href="docelement.html#heading">HEADING</a>
3223 or
3224 <a href="docelement.html#pp">PP</a>
3225 require that the box be started beforehand.  Boxed pre-processor
3226 material must be fully enclosed by BOX&nbsp;/&nbsp;BOX&nbsp;OFF, as
3227 in this recipe for a one-off boxed pic diagram:
3228 <span class="pre-in-pp">
3229 .BOX
3230 .PS
3231 &lt;pic commands&gt;
3232 .PE
3233 .BOX OFF
3234 </span>
3235 Arguments to BOX are not sticky.  Each time you invoke BOX, you
3236 must invoke it with arguments unless you want mom&#8217;s default grey
3237 background.  If all or several boxes in a document require the same
3238 arguments, create a macro at the top of the input file that calls
3239 BOX with the arguments you want, e.g.
3240 <span class="pre-in-pp">
3241 &nbsp;&nbsp;.de PINK_BOX
3242 &nbsp;&nbsp;.BOX \
3243 &nbsp;&nbsp;&nbsp;&nbsp;SHADED pink \
3244 &nbsp;&nbsp;&nbsp;&nbsp;OUTLINED darkred \
3245 &nbsp;&nbsp;&nbsp;&nbsp;WEIGHT 1p \
3246 &nbsp;&nbsp;&nbsp;&nbsp;INSET 9p
3247 &nbsp;&nbsp;..
3248 </span>
3249 <kbd>.PINK_BOX</kbd> may then be used instead of <kbd>.BOX</kbd> any
3250 time you want a box with those arguments.
3251 </p>
3252
3253 <h3 class="docs">SHADED | OUTLINED</h3>
3254
3255 <p>
3256 <kbd>SHADED</kbd> or <kbd>OUTLINED</kbd> are required.  Both may
3257 be given, resulting in a shaded background with a frame, and both
3258 require a colour, e.g.
3259 <span class="pre-in-pp">
3260 &nbsp;&nbsp;.BOX SHADED blue OUTLINED black
3261 </span>
3262 The colour may be
3263 </p>
3264
3265 <ul style="margin-top: -1em;">
3266   <li>an xcolor name</li>
3267   <li>a colour initialized with
3268       <a href="color.html#newcolor">NEWCOLOR</a>
3269       or
3270       <a href="color.html#xcolor">XCOLOR</a>
3271   </li>
3272   <li>an RGB hexadecimal string beginning with (e.g. #FF0000)</li>
3273 </ul>
3274
3275 <p>
3276 Note that without <kbd>SHADED</kbd>, the above would simply draw a
3277 black frame.
3278 </p>
3279
3280 <h3 class="docs">WEIGHT</h3>
3281
3282 <p>
3283 Mom&#8217;s default weight for <kbd>OUTLINED</kbd> is 1/2
3284 <a href="definitions.html#picaspoints">point</a>.
3285 If you&#8217;d like to change it, give <kbd>WEIGHT</kbd> the desired
3286 value with a unit of measure appended, typically points, e.g.
3287 <span class="pre-in-pp">
3288 &nbsp;&nbsp;.BOX OUTLINED black WEIGHT 1p
3289 </span>
3290 </p>
3291
3292 <h3 class="docs">INSET</h3>
3293
3294 <p>
3295 Mom&#8217;s default inset for boxes is one
3296 <a href="definitions.html#picaspoints">pica</a>
3297 on all sides.  If you&#8217;d like a larger or smaller inset, give
3298 <kbd>INSET</kbd> the distance you want with a unit of measure
3299 appended, e.g.
3300 <span class="pre-in-pp">
3301 &nbsp;&nbsp;.BOX SHADED pink INSET 2m
3302 </span>
3303 </p>
3304
3305 <h3 class="docs">ADJUST</h3>
3306
3307 <p>
3308 If you are not happy with the starting position of a box, you can
3309 change it by giving <kbd>ADJUST</kbd> the distance you want it
3310 raised (-) or lowered (+) with a unit of measure appended.  For
3311 example, to lower a box three points,
3312 <span class="pre-in-pp">
3313 &nbsp;&nbsp;.BOX OUTLINED black ADJUST +3p
3314 </span>
3315 To raise it,
3316 <span class="pre-in-pp">
3317 &nbsp;&nbsp;.BOX OUTLINED black ADJUST -3p
3318 </span>
3319 </p>
3320
3321 <h3 class="docs">PIC / GRAP / EQN / IMG</h3>
3322
3323 <p>
3324 The <kbd>PIC</kbd> argument must be given to BOX if the box contains
3325 any
3326 <a href="#pic">pic</a>
3327 diagrams.  Likewise, graphs made with
3328 <a href="#grap">grap</a>,
3329 equations made with
3330 <a href="#eqn">eqn</a>,
3331 and
3332 <a href="#pdf-image">pdf images</a>
3333 require a corresponding <kbd>GRAP</kbd>, <kbd>EQN</kbd>, or
3334 <kbd>IMG</kbd> argument.
3335 </p>
3336
3337 <p>
3338 If you&#8217;re boxing a single diagram, graph, or pdf image, wrap
3339 it in a float, like this:
3340 <span class="pre-in-pp">
3341 &nbsp;&nbsp;.FLOAT
3342 &nbsp;&nbsp;.BOX PIC &lt;other parameters&gt;
3343 &nbsp;&nbsp;.PS
3344 &nbsp;&nbsp;&lt;pic input&gt;
3345 &nbsp;&nbsp;.PE
3346 &nbsp;&nbsp;.BOX OFF
3347 &nbsp;&nbsp;.FLOAT OFF
3348 </span>
3349 Notice that in the case of pdf images, pic, and grap, this
3350 represents a change from the norm, where the use of FLOAT may be
3351 destructive and is discouraged.
3352 </p>
3353
3354 <h2 id="box-notes" class="docs">Additional notes on BOX usage and behaviour</h2>
3355
3356 <h3 id="qbef" class="docs">QUOTE, BLOCKQUOTE, EPIGRAPH, FLOAT</h3>
3357
3358 <p>
3359 <a href="docelement.html#quote">QUOTE</a>,
3360 <a href="docelement.html#blockquote">BLOCKQUOTE</a>,
3361 <a href="docelement.html#epigraph">EPIGRAPH</a>,
3362 and
3363 <a href="images.html#float">FLOAT</a>
3364 require that boxes be started <i>after</i> they are
3365 invoked and stopped just before they are toggled off:
3366 <span class="pre-in-pp">
3367 &nbsp;&nbsp;.QUOTE
3368 &nbsp;&nbsp;.BOX &lt;parameters&gt;
3369 &nbsp;&nbsp;Text of quote
3370 &nbsp;&nbsp;.BOX OFF
3371 &nbsp;&nbsp;.QUOTE OFF
3372 </span>
3373 </p>
3374
3375 <h3 id="code" class="docs">CODE</h3>
3376
3377 <p>
3378 If you&#8217;re boxing
3379 <a href="docelement.html#code">CODE</a>
3380 that&#8217;s wrapped inside
3381 <a href="docelement.html#quote">QUOTE</a>,
3382 as described
3383 <a href="docelement.html#quote-code">here</a>,
3384 set the quote indent to &#8220;0&#8221; with
3385 <span class="pre-in-pp">
3386 &nbsp;&nbsp;.QUOTE_STYLE INDENT 0
3387 </span>
3388 so that the box&#8217;s leftmost inset is respected.
3389 </p>
3390
3391 <p>
3392 Here&#8217;s a recipe for setting boxed code with an 18-point inset:
3393 <span class="pre-in-pp">
3394 &nbsp;&nbsp;.QUOTE_STYLE INDENT 0
3395 &nbsp;&nbsp;.QUOTE
3396 &nbsp;&nbsp;.CODE
3397 &nbsp;&nbsp;.BOX INSET 18p
3398 &nbsp;&nbsp;Hello, world.
3399 &nbsp;&nbsp;.BOX OFF
3400 &nbsp;&nbsp;.QUOTE OFF
3401 </span>
3402 Note that CODE, wrapped inside QUOTE, does not require a corresponding CODE OFF.
3403 </p>
3404
3405 <h4 id="quotes" class="docs">Description of boxed BLOCKQUOTES and EPIGRAPH BLOCKS</h4>
3406
3407 <p>
3408 When you box a BLOCKQUOTE, or an EPIGRAPH with the <kbd>BLOCK</kbd>
3409 argument, the box is centred on the page and is only as wide as the
3410 blockquote or epigraph plus the box&#8217;s inset.
3411 </p>
3412
3413 <p>
3414 QUOTE and EPIGRAPH (without the <kbd>BLOCK</kbd> argument), on the
3415 other hand, set the box fully to the left and right margins.
3416 </p>
3417
3418 <h4 id="leftover" class="docs">Leftover box syndrome</h4>
3419
3420 <p>
3421 Boxed quotes and blockquotes sometimes exhibit leftover box
3422 syndrome, where the page after a fully terminated boxed quote or
3423 blockquote begins with an empty bit of box.  Equally, you may
3424 sometimes see the lower edge of a quote&#8217;s or
3425 blockquote&#8217;s box falling slightly below the page&#8217;s
3426 bottom margin.
3427 </p>
3428
3429 <p>
3430 The solution in both situations is to use the <kbd>ADJUST</kbd>
3431 argument to raise or lower the box&#8217;s starting position.
3432 Leftover box syndrome is usually fixed by raising the box slightly.
3433 When the box runs too deep, lowering it is generally recommended,
3434 although this will result in a widowed line at the top of the next
3435 page.  In either case, some experimentation is necessary.
3436 </p>
3437
3438 <h3 id="slides" class="docs">SLIDES</h3>
3439
3440 <p>
3441 On a slide with no pauses, boxes behave as they do in printed
3442 documents.
3443 </p>
3444
3445 <p>
3446 When a slide contains pauses, only the material up to the first
3447 pause is boxed.  As subsequent material is revealed, the box changes
3448 location, moving down to surround each new item.  This behaviour
3449 persists until the box is stopped, making it useful for highlighting
3450 material as it is revealed.
3451 </p>
3452
3453 <h3 id="footnotes" class="docs">Footnotes</h3>
3454
3455 <p>
3456 You don&#8217;t have to worry about boxes encroaching on footnotes.
3457 Mom makes sure they don&#8217;t.
3458 </p>
3459
3460 <h2 id="page-color-intro" class="docs">Page colour</h2>
3461
3462 <p>
3463 Mom lets you change the page (&#8220;paper&#8221;) colour
3464 from white to anything you like.  While this has limited application
3465 in printed documents, it can be effective in
3466 <a href="docprocessing.html#slides">slide presentations</a>.
3467 </p>
3468
3469 <div class="macro-id-overline">
3470 <h3 id="page-color" class= "macro-id">PAGE_COLOR</h3>
3471 </div>
3472
3473 <div id="page-color-macro" class="box-macro-args" style="margin-top: .5em">
3474 Macro: <b>PAGE_COLOR</b> <kbd class="macro-args"> &lt;color&gt; | OFF | off</kbd>
3475 </div>
3476 <p class="requires" style="font-style: normal">
3477 <i>Aliased as</i> <kbd>PAGE_COLOUR</kbd>, <kbd>SLIDE_COLOR</kbd>,
3478 <i>and</i> <kbd>SLIDE_COLOUR</kbd>.
3479 </p>
3480
3481 <p>
3482 When you invoke PAGE_COLOR with a <kbd>color</kbd> argument, the
3483 current and subsequent pages turn the colour you request.  If
3484 more than one instance of PAGE_COLOR appears before a page break,
3485 including <kbd>PAGE_COLOR OFF</kbd>, only the last applies.
3486 </p>
3487
3488 <div class="box-tip">
3489 <p class="tip">
3490 <span class="note">Note:</span>
3491 Unlike other
3492 <a href="definitions.html#toggle">toggle macros</a>,
3493 PAGE_COLOR requires the use of <kbd>OFF</kbd> or <kbd>off</kbd>
3494 to terminate it rather than an arbitrary string (<kbd>OFF</kbd>,
3495 <kbd>QUIT</kbd>, <kbd>END</kbd>, <kbd>X</kbd>, etc).
3496 </p>
3497 </div>
3498
3499 <div class="rule-long"><hr/></div>
3500
3501 <!-- Navigation links -->
3502 <table style="width: 100%; margin-top: 12px;">
3503 <tr>
3504   <td style="width: 33%;"><a href="toc.html">Back to Table of Contents</a></td>
3505   <td style="width: 20%; text-align: center;"><a href="#top">Top</a></td>
3506   <td style="width: 46%; text-align: right;"><a href="headfootpage.html">Next: Page headers/footers, pagination</a></td>
3507 </tr>
3508 </table>
3509
3510 </div>
3511
3512 <div class="bottom-spacer"><br/></div>
3513
3514 </body>
3515 </html>