diff options
Diffstat (limited to '')
| -rw-r--r-- | contrib/mom/momdoc/images.html | 3515 |
1 files changed, 3515 insertions, 0 deletions
diff --git a/contrib/mom/momdoc/images.html b/contrib/mom/momdoc/images.html new file mode 100644 index 0000000..dc1837f --- /dev/null +++ b/contrib/mom/momdoc/images.html @@ -0,0 +1,3515 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- +This file is part of groff, the GNU roff type-setting system. + +Copyright (C) 2004-2020 Free Software Foundation, Inc. +Written by Peter Schaffter (peter@schaffter.ca). + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with no +Invariant Sections, with no Front-Cover Texts, and with no Back-Cover +Texts. + +A copy of the Free Documentation License is included as a file called +FDL in the main directory of the groff source package. +--> + +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"> + +<head> + <meta http-equiv="content-type" content="text/html;charset=utf-8"/> + <title>Mom -- Graphics, floats, and preprocessor support</title> + <link rel="stylesheet" type="text/css" href="stylesheet.css" /> +</head> + +<body style="background-color: #f5faff;"> + +<!-- ==================================================================== --> + +<div id="top" class="page"> + +<!-- Navigation links --> +<table style="width: 100%;"> +<tr> + <td><a href="toc.html">Back to Table of Contents</a></td> + <td style="text-align: right;"><a href="headfootpage.html#top">Next: Page headers/footers, pagination</a></td> +</tr> +</table> + +<h1 class="docs">Graphics, floats, and preprocessor support</h1> + +<div style="width: 80%; margin: auto;"> +<ul class="no-enumerator" style="margin-left: -1em;"> + <li><a href="#images-intro">Inserting images and graphics</a> + <ul> + <li><a href="#converting">Image conversion and file processing</a> + <ul style="margin-left: -1em"> + <li><a href="#pdf">PDF</a></li> + <li><a href="#eps">EPS</a></li> + </ul></li> + <li><a href="#pdf-image">The PDF_IMAGE macro</a> + <ul style="margin-left: -1em"> + <li><a href="#pdf-image-frame">PDF_IMAGE_FRAME</a>—set parameters for image frames</li> + </ul></li> + <li><a href="#pspic">The PSPIC macro</a></li> + </ul></li> + <li><a href="#floats-intro">Floats</a> + <ul> + <li><a href="#float">The FLOAT macro</a></li> + <li><a href="#float-label-caption">Labelling and captioning floats</a> + <ul style="margin-left: -1em"> + <li><a href="#label">LABEL</a></li> + <li><a href="#caption">CAPTION</a></li> + </ul></li> + </ul></li> + <li><a href="#preprocessor-support">Preprocessor support</a> + <ul> + <li><a href="#tbl">tbl</a> + <ul style="margin-left: -1em;"> + <li><a href="#ts-te">.TS / .TH / .TE macros and arguments</a></li> + </ul></li> + <li><a href="#eqn">eqn</a> + <ul style="margin-left: -1em;"> + <li><a href="#eq-en">.EQ / .EN macros and arguments</a></li> + </ul></li> + <li><a href="#pic">pic</a> + <ul style="margin-left: -1em;"> + <li><a href="#ps-pe">.PS / .PE macros and arguments</a></li> + <li><a href="#pic-text-style">PIC_TEXT_STYLE</a>—set parameters for text in diagrams</li> + </ul></li> + <li><a href="#grap">grap</a></li> + <li><a href="#refer">refer</a></li> + </ul></li> + <li><a href="#captions-and-labels">Captions and labels</a> + <ul> + <li><a href="#autolabel">AUTOLABEL</a></li> + <li><a href="#set-autolabel">SET_AUTOLABEL</a></li> + <li><a href="#caption-after-label">CAPTION_AFTER_LABEL</a></li> + <li><a href="#captions-labels-sources">CAPTIONS / LABELS / SOURCES</a>—set parameters for each</li> + <li><a href="#mla">MLA</a></li> + </ul></li> + <li><a href="#lists-of">Lists of Figures, Tables, and Equations</a> + <ul> + <li><a href="#lists-placement">Placement of Lists</a></li> + <li><a href="#lists-macros">Macros to generate Lists</a></li> + <li><a href="#formatting-lists">Formatting and style parameters for Lists</a> + <ul style="margin-left: -1em"> + <li><a href="#lists-style">LISTS_STYLE</a></li> + </ul></li> + </ul></li> + <li><a href="#box-intro">Shaded backgrounds and frames (boxes)</a> + <ul> + <li><a href="#box-intro">Introduction and description</a></li> + <li><a href="#box">The BOX macro</a></li> + <li><a href="#box-notes">Additional notes on box usage and behaviour</a> + <ul> + <li><a href="#qbef">QUOTE, BLOCKQUOTE, EPIGRAPH, FLOAT</a></li> + <li><a href="#code">CODE</a></li> + <li><a href="#quotes">Description of boxed BLOCKQUOTEs and EPIGRAPHs</a> + <ul style="margin-left: -1em; list-style: disc;"> + <li><a href="#leftover">Leftover box syndrome</a></li> + </ul></li> + <li><a href="#slides">Slides</a></li> + <li><a href="#footnotes">Footnotes</a></li> + </ul></li> + <li><a href="#page-color-intro">Page colour</a></li> + </ul> + </li> +</ul> +</div> + +<div class="rule-medium"><hr/></div> + +<h2 id="images-intro" class="docs">Inserting images and graphics</h2> + +<p> +In order to include images in mom documents, the images must be in +either PDF (.pdf) or EPS (.eps) format. Each format requires its own +macro, but both take the same arguments, and in the same order. +</p> + +<p> +Please note that there are differences in the way the files +containing PDF and EPS images must be processed, hence documents may +not contain a mix. +</p> + +<h3 id="converting" class="docs">Image conversion and file processing</h3> + +<p> +When your image files are not in PDF or EPS format—jpgs, +for example—you must convert them before including them in +a mom document. Any utility for converting images may used. The +ImageMagick suite of programmes, present on most GNU/Linux +systems, contains <b>convert</b>, which is simple and effective. +</p> + +<h4 id="pdf" class="docs">PDF</h4> + +<p> +Assuming a jpg image, conversion to PDF is done like this: +<br/> +<span class="pre-in-pp"> + convert <image>.jpg <image>.pdf +</span> +Any image type supported by <b>convert</b> may be converted this +way. +</p> + +<p> +Mom files containing PDF images must be processed using +groff’s pdf driver. Use of +<a href="using.html#pdfmom" style="font-weight: bold">pdfmom</a> +is strongly recommended, which natively invokes the pdf driver. +<br/> +<span class="pre-in-pp"> + pdfmom doc.mom > doc.pdf +</span> +</p> + +<h4 id="eps" class="docs">EPS</h4> + +<p> +Assuming a jpg image, conversion to EPS is done like this: +<br/> +<span class="pre-in-pp"> + convert <image>.jpg <image>.eps +</span> +Any image type supported by <b>convert</b> may be converted this +way. There have been reports of trouble with PostScript level 2 +images, so don’t save your images in this format. +</p> + +<p> +Mom files containing EPS images must be processed using +groff’s postscript driver. Use of +<a href="using.html#pdfmom" style="font-weight: bold">pdfmom</a>, +which can be told to use the postscript driver, is strongly +recommended. +<br/> +<span class="pre-in-pp"> + pdfmom -Tps doc.mom > doc.pdf +</span> +</p> + +<!-- -PDF_IMAGE- --> + +<div class="macro-id-overline"> +<h3 id="pdf-image" class= "macro-id">PDF_IMAGE</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>PDF_IMAGE</b> \ +<br/> +<kbd class="macro-args">[ -L | -C | -R | -I <indent> ] \ +<br/> +<pdf image file> <width> <height> [ SCALE <factor> ] \ +<br/> +[ ADJUST +|-<vertical adjustment> ] [ NO_SHIM ] [ NO_FLEX ] \ +<br/> +[ FRAME ] \ +<br/> +[ CAPTION "<caption>" ] [ SHORT_CAPTION "<short caption>" ] \ +<br/> +[ LABEL "<label>" ] [ TARGET "<name>" ]</kbd> +</div> +<p class="requires"> +• <span style="font-style: normal"> +<kbd><indent></kbd>, +<kbd><width></kbd>, +<kbd><height></kbd></span> +and +<span style="font-style: normal"> +<kbd><vertical adjustment></kbd></span> +require a +<a href="definitions.html#unitofmeasure">unit of measure</a> +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +Mom files with embedded PDF images must be processed with +pdfmom doc.mom > doc.pdf. Arguments may be broken +into several lines using the “line-continued” backslash +(<b>\</b>), as shown above. +</p> +</div> + +<p> +Unlike +<a href="#pspic">PSPIC</a>, +which it resembles, PDF_IMAGE requires that the pdf image’s +dimensions (the bounding box, +<a href="#bounding-box">see below</a>) +be supplied each time it’s called. +</p> + +<p> +The first optional argument tells mom how to align the image +horizontally, with <kbd>-L</kbd>, <kbd>-C</kbd>, and <kbd>-R</kbd> +standing for left, centre and right respectively. If you need more +precise placement, the <kbd>-I</kbd> argument allows you to give an +indent from the left margin. Thus, to indent a PDF image 6 +<a href="definitions.html#picaspoints">picas</a> +from the left margin +<br/> +<span class="pre-in-pp"> + .PDF_IMAGE -I 6P <remaining arguments> +</span> +If you omit the first argument, the image will be centred. +</p> + +<p> +<kbd><pdf image></kbd> must be in PDF format, with a .pdf +extension. If it is not, mom will abort with a message. See +<a href="#pdf">here</a> +for instructions on converting image formats to PDF. +</p> + +<p id="bounding-box"> +<kbd><width></kbd> and <kbd><height></kbd> are the +dimensions of the image’s bounding box. The most reliable way +of getting the bounding box is with the utility, <strong>pdfinfo</strong>: +<br/> +<span class="pre-in-pp"> + pdfinfo <image.pdf> | grep "Page *size" +</span> +This will spit out a line that looks like this: +<br/> +<span class="pre-in-pp"> + Page size: width x height pts +</span> +<kbd>pts</kbd> means +<a href="definitions.html#picaspoints">points</a>, +therefore the unit of measure appended to <kbd><width></kbd> +and <kbd><height></kbd> must be <kbd>p</kbd>. +</p> + +<p> +The remaining arguments are optional and may be entered in any +order, although it’s best to put <kbd>CAPTION</kbd>, +<kbd>SHORT_CAPTION</kbd>, and <kbd>LABEL</kbd> last. +</p> + +<h5 class="docs" style="margin-top: 1em; text-transform: none">SCALE</h5> + +<p> +<kbd>SCALE</kbd> allows you to scale the image by +<kbd><factor></kbd>. The factor is a percentage of the +image’s original dimensions, thus <kbd>SCALE 50</kbd> +scales the image to 50 percent of its original size. No percent +sign or unit of measure should be appended. +</p> + +<h5 class="docs" style="margin-top: 1em; text-transform: none">ADJUST</h5> + +<p> +<kbd>ADJUST</kbd> lets you raise (<kbd>-</kbd>) or lower +(<kbd>+</kbd>) the image +<span style="font-style: italic">within the space allotted for it</span> +by the amount you specify. This is useful for achieving good +optical centering between surrounding blocks of type. A unit of +measure is required. +</p> + +<div class="box-tip"> +<p class="tip-top"> +<span class="note">Tip:</span> +You may sometimes find that a PDF_IMAGE at the bottom of a page +doesn’t sit flush on the bottom margin, however attempts to lower it +by adding space beforehand result in it being deferred to the next +page. +</p> + +<p class="tip-bottom"> +The solution is to introduce <i>negative</i> space before the image +so that it displays on the page, then lower it to the bottom margin +with PDF_IMAGE’s ADJUST argument. +</p> +</div> + +<h5 class="docs" style="margin-top: 1em; text-transform: none">NO_SHIM</h5> + +<p> +<kbd>NO_SHIM</kbd> instructs mom not to apply +<a href="docprocessing.html#shim-vs-flex">shimming</a> +after an image, which she will do automatically when shimming is +enabled, which it is by default. Shimming ensures that running text +after the image falls properly on the page’s +<a href="definitions.html#baseline-grid">baseline grid</a>, +but can result in slightly unequal spacing above and below +(correctable with the <kbd>ADJUST</kbd> argument). +<kbd>NO_SHIM</kbd> is useful when you have several images on the +page and there are visible differences in the spacing beneath them +as a result of shimming. To ensure a flush bottom margin, the last +image on the page should be shimmed, i.e. should not be given the +<kbd>NO_SHIM</kbd> argument. +</p> + +<h5 class="docs" style="margin-top: 1em; text-transform: none">NO_FLEX</h5> + +<p> +<kbd>NO_FLEX</kbd> instructs mom not to apply +<a href="docprocessing.html#shim-vs-flex">flex-spacing</a> +after an image, which she will do automatically when flex-spacing is +enabled. <kbd>NO_FLEX</kbd> is useful when you have several images +on the page and you want to distribute excess vertical +whitespace on the page amongst other flex-spacing points on the +page. If there are no others, the final image should be +flex-spaced, i.e. not given the <kbd>NO_FLEX</kbd> argument. +</p> + +<h5 class="docs" style="margin-top: 1em; text-transform: none">FRAME</h5> + +<p> +<kbd>FRAME</kbd> instructs mom to put a frame around the image. +Parameters for the frame are set with +<a href="#pdf-image-frame">PDF_IMAGE_FRAME</a>. +</p> + +<h5 class="docs" style="margin-top: 1em; text-transform: none">CAPTION</h5> + +<p> +<kbd>CAPTION</kbd> allows you to give the image a caption. By +default, the caption appears above the image, but may be attached to +the label that appears beneath the image. See +<a href="#caption-after-label">CAPTION_AFTER_LABEL</a> +in +<a href="#captions-and-labels">Captions and labels</a>. +The text of the caption must be surrounded by double-quotes. +</p> + +<h5 class="docs" style="margin-top: 1em; text-transform: none">SHORT_CAPTION</h5> + +<p> +<kbd>SHORT_CAPTION</kbd> allows you to trim long captions for +inclusion in the List of Figures. The text you supply, surrounded +by double-quotes, is what will appear in the List. +</p> + +<h5 class="docs" style="margin-top: 1em; text-transform: none">LABEL</h5> + +<p> +<kbd>LABEL</kbd>, if given, appears beneath the image. The text you +supply, surrounded by double-quotes, is how the image is labelled +in both the document proper and the List of Figures. Mom provides +an auto-labelling facility for images (see +<a href="#autolabel">AUTOLABEL</a>), +which, if enabled, overrides the <kbd>LABEL</kbd> argument. +</p> + +<h5 class="docs" style="margin-top: 1em; text-transform: none">TARGET</h5> + +<p> +<kbd>TARGET</kbd> followed by a unique name surrounded by +double-quotes creates a PDF target for the image so that it may be +linked to from other places in the file (with PDF_LINK; see +<a href="version-2.html#mom-pdf">Producing PDFs with groff and mom</a>). +</p> + +<p> +<b><i>Please note:</i></b> The following functionality is available +only with groff 1.22.4 or later. +</p> + +<p> +When +<a href="#autolabel">autolabelling</a> +is enabled and the document is processed with +<a href="using.html#pdfmom" style="font-weight: bold">pdfmom</a>, +the target name can be used to generate the target’s label +number in running text if it is entered as a groff string, i.e. of the +form <kbd><span class="nobr">\*[name]</span></kbd>. For example, if you create +a target named “foo” for a pdf image whose autolabel +number would be 3, entering +<br/> +<span class="pre-in-pp"> + See + .PDF_LINK foo "Figure \*[foo]" +</span> +anywhere in running text would result in a pdf link that reads +“Figure 3”. If chapter numbers are being prefixed to +labels, the same string in, say, chapter 5 would produce the pdf +link “Figure 5.3”. +</p> + +<div class="box-tip"> +<p class="tip-top"> +<span class="note">Note: Version 2.0-c change</span> +<br/> +Mom now treats all pdf images identically to +<a href="#floats-intro">floats</a>, +which is to say that if an image doesn’t fit on the output +page, she will defer it to the top of the next page while continuing +to process +<a href="definitions.html#running">running text</a>. +<kbd>ADJUST</kbd> is ignored whenever an image is the first to be +deferred, except when moving from column to column on the same page, +when the image may need to be optically adjusted. Subsequent images +that do not fit, if any, are output in order immediately after the +first. +</p> + +<p class="tip-bottom"> +Prior to 2.0-c, it was recommended that images be wrapped inside +<a href="#float">FLOAT</a>, +but this is now no longer required, and should, in fact, be avoided. +</p> +</div> + +<!-- -PDF_IMAGE_FRAME- --> + +<div class="macro-id-overline"> +<h3 id="pdf-image-frame" class= "macro-id">PDF_IMAGE_FRAME</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>PDF_IMAGE_FRAME</b> <kbd class="macro-args"><inset amount> <rule weight> <color></kbd> +</div> +<p class="requires"> +• <span style="font-style: normal"><kbd><inset amount></kbd></span> +requires a +<a href="definitions.html#unitofmeasure">unit of measure</a>; +conversely, +<span style="font-style: normal"><kbd><rule weight></kbd></span> +must not have a unit of measure appended +</p> + +<p> +PDF_IMAGE_FRAME establishes the parameters for subsequent invocations of +<a href="#pdf-image">PDF_IMAGE</a> +when the <kbd>FRAME</kbd> argument is given. Arguments must appear +in order, and any you wish left at the current value should be +entered as two adjacent double-quotes. So, for example, +<br/> +<span class="pre-in-pp"> + .PDF_IMAGE_FRAME "" "" blue +</span> +leaves the inset value and rule weight at their current value and +changes the frame colour to blue. +</p> + +<p> +Frames are drawn <span class="italic">outside</span> the image at +its requested dimensions inclusive of scaling. Colours must be +pre-initialized with +<a href="color.html#xcolor">XCOLOR</a> +or +<a href="color.html#newcolor">NEWCOLOR</a>. +</p> + +<p> +The default inset is 6 <a +href="definitions.html#picaspoints">points</a>, the default rule +weight is .5 (points), and the default colour is black. +</p> + +<!-- -PSPIC- --> + +<div class="macro-id-overline"> +<h3 id="pspic" class= "macro-id">PSPIC</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>PSPIC</b> <kbd class="macro-args">[ -L | -R | -I <n> ] <file> [ width [ height ] ]</kbd> +</div> + +<p> +PSPIC is not actually part of mom, but rather a macro included with +every groff installation. <kbd>man groff_tmac</kbd> contains the +documentation for PSPIC, but I’ll repeat it here with a few +modifications for clarity. +</p> + +<div class="examples-container"> +<h3 id="groff-tmac" class="docs" style="margin-top: .5em;">From <span style="text-transform: none">groff_tmac</span></h3> +<p style="margin-top: .5em; margin-bottom: .5em;"> +<kbd><file></kbd> is the name of the file containing the +image; <kbd>width</kbd> and <kbd>height</kbd> give the desired +width and height of the image as you wish it to appear within the +document. The width and height arguments may have +<a href="definitions.html#unitofmeasure">units of measure</a> +attached; the default unit of measure is <kbd>i</kbd>. PSPIC will +scale the graphic uniformly in the x and y directions so that +it is no more than <kbd>width</kbd> wide and <kbd>height</kbd> +high. By default, the graphic will be horizontally centred. The +<kbd>-L</kbd> and <kbd>-R</kbd> options cause the graphic to be +left-aligned and right-aligned, respectively. The <kbd>-I</kbd> +option causes the graphic to be indented by <kbd><n></kbd>; +the default unit of measure is <kbd>m</kbd> +(<a href="definitions.html#em">ems</a>). +</p> +</div> + +<p> +It is not necessary to pass PSPIC the <kbd><width></kbd> +and <kbd><height></kbd> arguments unless you are scaling +the image, in which case you will most likely need the original +dimensions of the EPS image’s bounding box. These can be +found with +<br/> +<span class="pre-in-pp"> + gs -q -dBATCH -dNOPAUSE -sDEVICE=bbox <image file>.pdf 2>&1 \ + | grep "%%BoundingBox" | cut -d " " -f4,5 +</span> +The two digits returned are in +<a href="definitions.html#picaspoints">points</a>, +therefore the +<a href="definitions.html#unitofmeasure">unit of measure</a> +<kbd>p</kbd> must be appended to them. +</p> + +<p> +Because PSPIC lacks the <kbd>ADJUST</kbd> option offered by +<a href="#pdf-image">PDF_IMAGE</a> +a certain amount of manual tweaking of the vertical placement of the +image will probably be required, typically by using the +<a href="typesetting.html#ald">ALD</a> +and +<a href="typesetting.html#rld">RLD</a> +macros. Wrapping the image in a +<a href="#float">float</a> +and using FLOAT’s <kbd>ADJUST</kbd> option can also be used to +correct optical centering. +</p> + +<p> +Additionally, non-floated EPS images +will almost certainly disrupt the baseline placement of +<a href="definitions.html#running">running text</a>. +In order to get mom back on track after inserting a non-floated +<kbd>.PSPIC</kbd> image, insert the +<a href="docprocessing.html#shim">SHIM</a> +or +<a href="docprocessing.html#flex">FLEX</a> +macro afterwards, depending on the +<a href="docprocessing.html#vertical-whitespace-management">vertical whitespace management</a> +strategy in effect, so that the bottom margin of running text falls +where it should. +</p> + +<p> +Remember that mom files with embedded EPS images must be processed +with +<br/> +<span class="pre-in-pp"> + pdfmom -Tps doc.mom > doc.pdf +</span> +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Please note:</span> +<kbd>PSPIC</kbd> does not support +<a href="autolabel">autolabelling</a>, +labels, captions, or inclusion in the List of Figures. If you wish +this functionality, +<a href="#converting">convert your images to pdf</a> +and use +<a href="#pdf-image">PDF_IMAGE</a> +instead, then process the file with +<a href="using.html#pdfmom" style="font-weight: bold">pdfmom</a> +(without the <kbd>-Tps</kbd> option). +</p> +</div> +<div class="rule-medium"><hr/></div> + +<h2 id="floats-intro" class="docs">Introduction to floats</h2> + +<p> +Non-textual insertions in a document (tables, for example) sometimes +do not fit on the output page of a PDF or PostScript document at +the place they’re inserted in the input file. It’s +necessary, therefore, to defer them to the next page while carrying +on with +<a href="definitions.html#running">running text</a>. +</p> + +<p> +Whenever you need this functionality, mom provides the FLOAT macro. +</p> + +<p> +Floats are usually used for images and graphics, but can contain +anything you like, including text. Whatever’s in the +float will be kept together as a block, output immediately if +there’s room, or deferred to the top of the next output page +when there isn’t; running text continues to the bottom of the +previous page without interruption. +</p> + +<p> +In the case of a float that doesn’t fit being followed by +one that does, both are deferred and output one after the other. +Note that this represents a change from versions 2.1-b_1 and earlier +where the second float was output in position and the first was +deferred. +</p> + +<p> +A key distinction between a float and a +<a href="docelement.html#quote">QUOTE</a> +or +<a href="docelement.html#blockquote">BLOCKQUOTE</a> +is that while a float keeps everything together and defers output if +necessary, quotes and blockquotes are output immediately, and may +start on one page and finish on the next. +</p> + +<p> +Floats always begin in +<a href="definitions.html#filled">no-fill mode</a>. +Text entered immediately after FLOAT will be set line-for-line +unless a +<a href="typesetting.html#justify">JUSTIFY</a> +or +<a href="typesetting.html#quad">QUAD L|R|C</a> +precedes it. Alternatively, any macro that sets a quad direction +may be used, e.g. +<a href="docelement.html#pp">PP</a>. +</p> + +<p> +Floats always deposit a break before they begin, which means the +line beforehand will not be +<a href="definitions.html#filled">filled</a>. +Floats, therefore, cannot be inserted in the middle of a paragraph +without studying the output file and determining where to break or +<a href="typesetting.html#spread">spread</a> +the line before the float. Furthermore, if you want a float between +paragraphs, the float should come before <kbd>.PP</kbd>, like this: +<br/> +<span class="pre-in-pp"> + .FLOAT + ... + .FLOAT OFF + .PP +</span> +not +<br/> +<span class="pre-in-pp"> + .PP + .FLOAT + ... + .FLOAT OFF +</span> +</p> + +<p id="float-spacing"> +Floats begin on the baseline immediately below the running text +preceding them. No additional whitespace surrounds them, above or +below. Running text below a float is, however, +<a href="docprocessing.html#shim">shimmed</a> +or +<a href="docprocessing.html#flex">flex-spaced</a>, +depending on the +<a href="docprocessing.html#vertical-whitespace-management">vertical whitespace management</a> +strategy in effect. This behaviour can be disabled for individual +floats with <kbd>NO_SHIM</kbd> or <kbd>NO_FLEX</kbd>. +</p> + +<p> +If you’d like more space around a float, you must add it +manually, for example with +<a href="typesetting.html#ald">ALD</a> +or +<a href="typesetting.html#space">SPACE</a>. +</p> + +<!-- -FLOAT- --> + +<div class="macro-id-overline"> +<h3 id="float" class= "macro-id">FLOAT</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>FLOAT</b> <kbd class="macro-args"><arguments> | <anything> +<br/> +Arguments: +<br/> +[ ADJUST +|-<amount> ] \ +<br/> +[ FORCE ] \ +<br/> +[ SPAN ] \ +<br/> +[ INDENT <value> ] \ +<br/> +[ CENTER ] \ +<br/> +[ RIGHT ] \ +<br/> +[ NO_SHIM] \ +<br/> +[ NO_FLEX ] \ +<br/> +[ TARGET "<name>" ]</kbd> +<br/> +</div> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +FLOAT is intended for use with the document processing macros only. +</p> +</div> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +As a general rule, avoid consecutive floats that have no intervening +<a href="definitions.html#running">running text</a>. +Rather, wrap all the material into a single float. +</p> +</div> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +Deferred floats are output with the left indent that was in effect +when they were input. If you do not want this behaviour, disable +the indent prior to inputting the float and re-enable it afterward. +</p> +</div> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +Mom treats <b>pic</b> pre-processor directives and pdf images as +floats so it is not necessary to wrap them inside FLOAT unless +additional material is included in what is floated. +</p> +</div> + +<p style="margin-top: -.5em"> +To begin a float, simply invoke <kbd>.FLOAT</kbd> and follow it with +whatever you want the float to contain. When you’re done, +invoke <kbd>.FLOAT OFF</kbd> (or <kbd>OFF</kbd>, +<kbd>QUIT</kbd>, <kbd>END</kbd>, <kbd>X</kbd>, etc). +</p> + +<h5 class="docs" style="margin-top: 1em; text-transform: none">ADJUST</h5> + +<p> +The optional <kbd>ADJUST</kbd> argument tells mom to raise +(<kbd>+</kbd>) or lower (<kbd>-</kbd>) the float <i>within +the space allotted to it</i> by the specified amount. +<kbd><amount></kbd> must have a +<a href="definitions.html#unitofmeasure">unit of measure</a> +appended. <kbd>ADJUST</kbd> gives you precise control over +the vertical centering of floats, allowing you to compensate for +unequal spacing that may result from the automatic +<a href="docprocessing.html#shim">shimming</a> +or +<a href="docprocessing.html#flex">flex-spacing</a> +floats. +</p> + +<p> +<kbd>ADJUST</kbd> is ignored for the first float deferred to +a following page but respected for subsequent deferred floats +output immediately afterwards. +</p> + +<h5 class="docs" style="margin-top: 1em; text-transform: none">FORCE</h5> + +<p> +The <kbd>FORCE</kbd> argument instructs mom to output the float +exactly where it occurs in the input file. With <kbd>FORCE</kbd>, +mom immediately breaks to a new page to output the float if it does +not fit on the current page. While this is somewhat contrary to the +notion of floats (i.e. that running text should continue to fill the +page), there are circumstances where it may be desirable. +</p> + +<p> +If you need to force a page break after completion of a float that +has been deferred to a subsequent page, insert <kbd>\!.bp</kbd> +immediately before terminating the float. +</p> + +<h5 class="docs" style="margin-top: 1em; text-transform: none">SPAN</h5> + +<p> +The <kbd>SPAN</kbd> argument tells mom that a float, if deferred, +may carry onto multiple pages. Please note that <kbd>SPAN</kbd> may +not be used for floats containing a boxed table; mom will abort with +a warning should this occur. Unboxed tables, on the other hand, are +acceptable within floats that are given the <kbd>SPAN</kbd> argument. +</p> + +<h5 class="docs" style="margin-top: 1em; text-transform: none">INDENT</h5> + +<p> +<kbd>INDENT</kbd> allows you to indent a float from the left margin +by a specified value. The value must have a +(<a href="definitions.html#unitofmeasure">unit of measure</a> +appended to it. +</p> + +<h5 class="docs" style="margin-top: 1em; text-transform: none">CENTER</h5> + +<p> +<kbd>CENTER</kbd> instructs mom to center a float if it is not +already centered by default. +</p> + +<h5 class="docs" style="margin-top: 1em; text-transform: none">RIGHT</h5> + +<p> +<kbd>RIGHT</kbd> instructs mom to place a float at the right of the +page; the longest line in the float will be flush with the +page’s right margin. +</p> + +<h5 class="docs" style="margin-top: 1em; text-transform: none">NO_SHIM</h5> + +<p> +<kbd>NO_SHIM</kbd> instructs mom not to apply +<a href="docprocessing.html#shim-vs-flex">shimming</a> +after a float, which she will do automatically when shimming is +enabled, which it is by default. Shimming ensures that running text +after the float falls properly on the page’s +<a href="definitions.html#baseline-grid">baseline grid</a>, +but can result in slightly unequal spacing above and below +(correctable with the <kbd>ADJUST</kbd> argument). +<kbd>NO_SHIM</kbd> is useful when you have several floats on the +page and there are visible differences in the spacing beneath them +as a result of shimming. To ensure a flush bottom margin, the last +float on the page should be shimmed, i.e. should not be given the +<kbd>NO_SHIM</kbd> argument. +</p> + +<h5 class="docs" style="margin-top: 1em; text-transform: none">NO_FLEX</h5> + +<p> +<kbd>NO_FLEX</kbd> instructs mom not to apply +<a href="docprocessing.html#shim-vs-flex">flex-spacing</a> +after a float, which she will do automatically when flex-spacing is +enabled. <kbd>NO_FLEX</kbd> is useful when you have several floats +on the page and you want to distribute excess vertical +whitespace on the page amongst other flex-spacing points on the +page. If there are no others, the final float should be +flex-spaced, i.e. not given the <kbd>NO_FLEX</kbd> argument. +</p> + +<h5 class="docs" style="margin-top: 1em; text-transform: none">TARGET</h5> + +<p> +<kbd>TARGET</kbd> followed by a unique name surrounded by +double-quotes creates a PDF target for the float so that it may be +linked to from other places in the file (with PDF_LINK; see +<a href="version-2.html#mom-pdf">Producing PDFs with groff and mom</a>). +</p> + +<p> +Floats cannot be autolabelled, so unlike pdf images and +pre-processor material, the target name cannot be used as a string +to generate the target’s label number in running text. Label +numbers for floats must be entered explicitly running text, however +they may be entered symbolically in the argument to +<a href="#label">LABEL</a>. +See +<a href="#reserved-label-strings">Reserved variables for +labels</a>. +</p> + + +<div class="box-tip"> +<p class="tip-top"> +<span class="note">Note:</span> +Floats use +<a href="definitions.html#filled">no-fill mode</a>, +with each input line beginning at the left margin. If this is not +what you want, you must specify the preferred horizontal alignment +<i>within the float</i> (e.g. +<a href="typesetting.html#lrc">CENTER</a> +or +<a href="typesetting.html#lrc">RIGHT</a>). +</p> + +<p class="tip-bottom"> +Furthermore, if you want text +<a href="definitions.html#filled">filled</a>, +you must specify +<a href="typesetting.html#quad"><kbd>.QUAD L|R|C</kbd></a> +or +<a href="typesetting.html#justify"><kbd>.JUSTIFY</kbd></a>—again, +within the float. +</p> +</div> + +<h2 id="float-label-caption" class="docs">Labelling and captioning floats</h2> + +<p> +Labelling and captioning of tables (<b>tbl</b>), equations +(<b>eq</b>), diagrams (<b>pic</b>) and pdf images +(<a href="#pdf-image">PDF_IMAGE</a>) +are handled by the macros that initiate them, regardless of whether +they’re wrapped inside a float. However, since a float may +contain any valid input, it is sometimes necessary to add a label +and/or caption to the float itself. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="important">Important:</span> +Always use the native labelling/captioning facilities for +preprocessor output and pdf images rather than labelling the +containing float, if any. +</p> +</div> + +<p> +The macros to label and caption floats are +<a href="#label">LABEL</a> +and +<a href="#caption">CAPTION</a>. +If a label or caption is to appear above the float, the appropriate +macro is entered immediately after +<a href="#float">FLOAT</a>. +If a label or caption is to appear beneath the float, the appropriate +macro is entered immediately before ending the float with +<kbd>FLOAT OFF</kbd>. +</p> + +<p> +If a label and caption are to be joined, the <b>LABEL</b> macro is +used to enter both by passing the <kbd>CAPTION</kbd> argument to +<kbd>LABEL</kbd>. +</p> + +<p> +It is impossible for mom to know the contents of a float, so +floats cannot be autolabelled. Each label must be entered +explicitly. Mom does, however, provide a way to enter both +chapter numbers and incrementing label numbers +<a href="#reserved-label-strings">symbolically</a>, +easing the burden of keeping the numbering scheme intact as +labelled floats are added to or subtracted from a document. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Tip:</span> +<a href="docelement.html#blockquote">QUOTE</a> +and +<a href="docelement.html#blockquote">BLOCKQUOTE</a> +may also be labelled and captioned using <b>LABEL</b> and +<b>CAPTION</b>. +</p> +</div> + +<h4 class="docs">Spacing</h4> + +<p> +If a float has a caption at the top, the caption is whitespaced +1/4 linespace from running text and the float itself begins +an additional 1/4 linespace below the caption. If the float has +no corresponding label at the bottom, the float observes the +bottom-spacing rules for all floats, namely that no extra space is +added other than +<a href="docprocessing.html#shim">shimming</a> +or +<a href="docprocessing.html#shim-vs-flex">flex-spacing</a>, +depending on the +<a href="docprocessing.html#vertical-whitespace-management">vertical whitespace management</a> +in effect. +</p> + +<p> +If a float has a label at the bottom but no caption at the top, the +float begins exactly where started, i.e. with no extra whitespace +between running text and the float. The label (and attached +caption, if any) are whitespaced 1/4 linespace below the float, +with an additional 1/4 linespace underneath <i>plus</i> shimming or +flex-spacing. +</p> + +<p> +Labelled/captioned quotes and blockquotes inside floats treat the +labels/captions as part of the quote so the spacing above and +below the whole float block is what you’d expect from quotes +normally, while the spacing between the label/caption and the quote +is 1/4 linespace. +</p> + +<div class="macro-id-overline"> +<h3 id="label" class="macro-id">LABEL</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>LABEL</b> +<kbd class="macro-args">"<label>" [ CAPTION "<caption>" ] [ SHORT_CAPTION ] \ +<br/> +[ TO_LIST FIGURES | TABLES | EQUATIONS ]</kbd> +</div> + +<p> +The placement of a float’s label depends on where you put it +inside the float. +</p> + +<p> +If you want a label at the top, put <kbd>LABEL</kbd> immediately +underneath +<a href="#float">FLOAT</a> +and follow it with the text of the label surrounded by double-quotes: +<br/> +<span class="pre-in-pp"> + .FLOAT + .LABEL "Fig. 1" +</span> +If you want a label at the bottom, put <kbd>LABEL</kbd> immediately +before ending the float: +<br/> +<span class="pre-in-pp"> + .FLOAT + <contents of float> + .LABEL "Fig. 1" + .FLOAT OFF +</span> +</p> + +<h3 id="reserved-label-strings" class="docs" style="text-transform: none">Reserved variables for labels</h3> + +<p> +Mom reserves strings you may use when entering +label text after the <kbd>LABEL</kbd> argument. +<kbd><span class="nobr">\*[chapter]</span></kbd> holds the current chapter +or major section number. <kbd><span class="nobr">\*[fig-label]</span></kbd>, +<kbd><span class="nobr">\*[tbl-label]</span></kbd>, and +<kbd><span class="nobr">\*[eqn-label]</span></kbd> increment the label number of +the appropriate label type by one, and are initially set to zero +after each invocation of +<a href="docprocessing.html#start">START</a> +when the +<a href="docprocessing.html#doctype">DOCTYPE</a> +is <kbd>CHAPTER</kbd>. Thus, in every chapter requiring numbered +float labels, you can enter +<br/> +<span class="pre-in-pp"> + .LABEL "Fig. \*[chapter].\*[fig-label]. TO_LIST FIGURES +</span> +which, assuming the third autolabelled float of Chapter 2, will +produce <kbd>Fig. 2.3.</kbd> +</p> + +<p> +If your <b>DOCTYPE</b> is <kbd>DEFAULT</kbd> or <kbd>NAMED</kbd>, +you must reset <kbd><span class="nobr">\*[<type>-label]</span></kbd> after +each +<a href="docprocessing.html#collate">COLLATE</a> +by entering +<br/> +<span class="pre-in-pp"> + .AUTOLABEL_<list type> +</span> +before <kbd>.START</kbd>. +</p> + +<p> +If +<a href="#autolabel">autolabelling</a> +is enabled, e.g. <kbd>.AUTOLABEL_IMAGES</kbd> (List +of Figures) or <kbd>.AUTOLABEL_PIC</kbd> (also List of Figures), +the prefix is stripped from the label when it appears in +the List. Thus, if you have invoked <kbd>.AUTOLABEL_PIC</kbd>, +<br/> +<span class="pre-in-pp"> + .LABEL "Fig. 1.1." + CAPTION "Caption for label \ + TO_LIST FIGURES +</span> +or +<br/> +<span class="pre-in-pp"> + .LABEL "Fig. \*[chapter].\*[label]." \ + CAPTION "Caption for label \ + TO_LIST FIGURES +</span> +will appear in the List of Figures as “1.1. Caption for +label”. +</p> + +<h3 class="docs">CAPTION</h3> + +<p> +If you’d like a caption attached to the label, pass +<kbd>LABEL</kbd> the optional argument <kbd>CAPTION</kbd> followed +by the text of the caption as a single string surrounded by +double-quotes: +<br/> +<span class="pre-in-pp"> + .FLOAT + <contents of float> + .LABEL "Fig. 1" CAPTION "Caption for Fig. 1" + .FLOAT OFF +</span> +Note that the +<a href="#caption">CAPTION</a> +macro by itself permits entering several strings, each output on +a line by itself, whereas the <kbd>CAPTION</kbd> argument to +<kbd>LABEL</kbd> accepts only a single string. +</p> + +<h3 class="docs">SHORT_CAPTION</h3> + +<p> +If your caption runs long and you’re including the +float in a “List of ...”, (see +<a href="#list-of">TO_LIST</a>, below) +<kbd>SHORT_CAPTION</kbd> tells +mom how you’d like the caption to appear in the List. +</p> + +<h3 class="docs">TO_LIST</h3> + +<p> +The optional argument <kbd>TO_LIST</kbd> tells mom to add the +float’s label and attached caption, if present, to the specified +<a href="#lists-of">list</a>, +which may be one of <kbd>FIGURES</kbd>, <kbd>TABLES</kbd>, or +<kbd>EQUATIONS</kbd>. +</p> + +<p> +If, for some reason, you want only the caption appended to the List, +give <kbd>\&</kbd> as the first argument to LABEL, followed by +<kbd>CAPTION “caption”</kbd>: +<br/> +<span class="pre-in-pp"> + .LABEL \& \ + CAPTION "caption" +</span> +</p> + +<div class="box-tip"> +<p class="tip-top"> +<span class="note">Tip:</span> +<kbd>TO_LIST</kbd> can be used to handle situations where labelled +floats need to go to a uniquely named “List of ...”. +</p> + +<p class="tip-bottom"> +Suppose, for example, your document contains figures (e.g. +<b>pic</b> output or pdf-images) and tables, and you need a +“List of Examples” for floats labelled “Example +n.n”. By changing the default title string for +<a href="#lists-macros">LIST_OF_EQUATIONS</a> +to “List of Examples”, you may include the float in your +List of Examples with +<br/> +<span class="pre-in-pp"> + .TO_FIGURES EQUATIONS +</span> +</p> +</div> + +<div class="macro-id-overline"> +<h3 id="caption" class="macro-id">CAPTION</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>CAPTION</b> +<kbd class="macro-args">"<caption>" \ +<br/> +[ "<additional line>" [ "<additional line>"... ] ] \ +<br/> +[ TO_LIST FIGURES | TABLES | EQUATIONS ]</kbd> +</div> + +<p> +The placement of a float’s caption depends on where you put it +inside the float. +</p> + +<p> +If you want a caption at the top, put <kbd>CAPTION</kbd> immediately +underneath +<a href="#float">FLOAT</a> +and follow it with the text of the caption surrounded by double-quotes: +<br/> +<span class="pre-in-pp"> + .FLOAT + .CAPTION "Caption at top of float" +</span> +<b>CAPTION</b> can take multiple string arguments, allowing for +captions that run to several lines. There is a caveat: the strings +are not automatically broken into individual lines. You must +provide strings that include literal breaks or spaces: +<br/> +<span class="pre-in-pp"> + .FLOAT + .CAPTION "Caption" ".BR" "at top" ".BR" "of float" +</span> +or, easier to read: +<br/> +<span class="pre-in-pp"> + .FLOAT + .CAPTION "Caption" \ + ".BR" \ + "at top" \ + ".BR" \ + "of float" +</span> +If you want a caption at the bottom, put <kbd>CAPTION</kbd> immediately +before ending the float: +<br/> +<span class="pre-in-pp"> + .FLOAT + <contents of float> + .CAPTION "Caption at bottom of float" + .FLOAT OFF +</span> +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +If you want a caption attached to a label, do not use +<b>CAPTION</b> by itself. Rather, invoke +<a href="#label"><kbd>.LABEL</kbd></a> +with the <kbd>CAPTION</kbd> argument. +</p> +</div> + +<div class="rule-medium"><hr/></div> + +<h2 id="preprocessor-support" class="docs">Preprocessor support</h2> + +<p> +Mom offers full support for the <b>eqn</b> (equations), <b>pic</b> +(diagrams), <b>grap</b> (graphs), <b>tbl</b> (tables) and +<b>refer</b> (bibliographies/citations) preprocessors, including +captions, labelling, autolabelling, and inclusion in the Lists of +Equations, Figures, and Tables. +</p> + +<p> +Other than <b>refer</b>, which is discussed at length in the <a +href="refer.html">Bibliographies and references</a> section, it is +beyond the scope of this documentation to cover full preprocessor +usage. Consult the manpages <b>eqn(1)</b>, <b>pic(1)</b>, +<b>grap(1)</b> and <b>tbl(1)</b> for instructions. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Version 2.0-c changes</span> +<br/> +Preprocessor support has been revised and expanded as of version 2.0-c. +Please read the following sections thoroughly and update any +documents created with versions prior to 2.0-c as necessary. +</p> +</div> + +<h3 id="tbl" class="docs">tbl support</h3> + +<p> +Mom documents can include tables generated with the groff +preprocessor <b>tbl</b>. If you are unfamiliar with <b>tbl</b>, I +recommend downloading a copy of +<a href="http://plan9.bell-labs.com/10thEdMan/tbl.pdf">Tbl - A Program to Format Tables</a>, +which, in addition to providing a thorough introduction, contains +some fine examples. If you use <b>tbl</b>, you must pass groff or +pdfmom the <b>-t</b> flag when you process the file. +</p> + +<p> +Tables formatted with <kbd>tbl</kbd> begin with the macro +<kbd>.TS</kbd> (<b>T</b>able <b>S</b>tart) and end with +<kbd>.TE</kbd> (<b>T</b>able <b>E</b>nd). Depending on where you +want your tables output in a document, you may need to wrap +your <kbd>tbl</kbd> code inside a +<a href="#floats-intro">float</a>, +or pass the <kbd>H</kbd> argument to <kbd>.TS</kbd>. +</p> + +<p> +If you put <kbd>tbl</kbd> code inside a float, the table will be +output immediately if it fits on the page, or deferred to the top +of the next page if it doesn’t. If you prefer a table to +begin where you say and span over to the next page, or if you know +for certain a boxed table will run to multiple pages, simply pass the +<kbd>H</kbd> argument to <kbd>.TS</kbd>, along with a corresponding +<a href="#th"><kbd>TH</kbd></a> +and do not wrap the table inside a float. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +If you create a boxed table that will span several pages, do not +wrap the table inside a float. Boxed, multipage tables and FLOAT +should be considered mutually exclusive. This restriction is +imposed by the <kbd>tbl</kbd> preprocessor itself, not groff or +mom. Unboxed tables that span several pages, however, are +acceptable within FLOAT. +</p> +</div> + +<h4 id="tbl-placement" class="docs">tbl placement in mom docs</h4> + +<p> +If you use <kbd>.TS</kbd> without the <kbd>H</kbd> argument (and +therefore no <kbd>.TH</kbd>), tables that fit on the page are output +in position. If there is not enough room to output the table, +<kbd>tbl</kbd> will abort with message instructing you to use +<kbd>.TS H/.TH</kbd>. Given that <kbd>.TS</kbd> without <kbd>H</kbd> +may sometimes fail, it is advisable to begin all <b>tbl</b> blocks +with <kbd>.TS H</kbd>. +</p> + +<p> +If you give <kbd>.TS</kbd> the <kbd>H</kbd> argument (with a +corresponding <kbd>.TH</kbd>), tables will be output in position and +span as many pages as necessary to complete output. A table header +will be printed at the top of each page’s table output. In the +event that there is not enough room to print the table header and +at least one row of table data near the bottom of a page, mom will +break to a new page before beginning table output, leaving a gap +in +<a href="definitions.html#running">running text</a>. +</p> + +<p> +Boxed tables inside +<a href="#floats-intro">floats</a> +are output in position if they fit on the page. If not, they are +deferred to the top of the next page without a break in running +text. Boxed tables within floats may not, however, span multiple +pages; mom will abort with a message should a boxed table in a float +run longer than the page. +</p> + +<p> +Unboxed tables inside floats may span multiple pages provided the +<kbd>SPAN</kbd> argument has been given to +<a href="#float">FLOAT</a>. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +The vertical spacing around unfloated tables may appear slightly +unequal, especially if there are several tables on the page. This +is a result of the +<a href="docprocessing.html#shim">shimming</a> +or +<a href="docprocessing.html#flex">flex-spacing</a> +that mom applies automatically after each table, depending on which +<a href="docprocessing.html#vertical-whitespace-management">vertical whitespace management</a> +is in effect. You may +disable shimming or flex-spacing with +<a href="docprocessing.html#no-shim">NO_SHIM</a> +or +<a href="docprocessing.html#no-flex">NO_FLEX</a>, +or by passing the <kbd>NO_SHIM</kbd> or <kbd>NO_FLEX</kbd> argument +to <kbd>.TS</kbd>. In either case, you will still likely want to +adjust the spacing around with table with the <kbd>ADJUST</kbd> +argument to <kbd>.TS</kbd>. Tables inside floats should be adjusted +with the <kbd>ADJUST</kbd> argument to +<a href="#float">FLOAT</a>, +not the <kbd>ADJUST</kbd> argument to <kbd>.TS</kbd>. +</p> +</div> + +<div class="macro-id-overline"> +<h3 id="ts-te" class= "macro-id">.TS / .TH / .TE</h3> +</div> + +<div class="box-macro-args"> +Macro: <a href="#ts"><b>TS</b></a> +<kbd class="macro-args"><br/> +Arguments: +<br/> + [ H ] +<br/> + [ BOXED ] +<br/> + [ CENTER ] +<br/> + [ NEEDS ] +<br/> + [ ADJUST +|-<vertical adjustment>]</kbd> +<span style="font-size: 95%"> +(<a href="definitions.html#unitofmeasure">unit of measure</a> +required) +</span> +<kbd class="macro-args"><br/> + [ NO_SHIM ] +<br/> + [ NO_FLEX ] +<br/> + [ CAPTION "<caption>" ] +<br/> + [ SHORT_CAPTION "<short caption>" ] +<br/> + [ LABEL "<label>" ] +<br/> + [ TARGET "<name>" ] +</kbd> +<br/> +Macro: <a href="#th"><b>TH</b></a> <kbd class="macro-args">(optional, only if .TS H)</kbd> +<br/> +Macro: <a href="#te"><b>TE</b></a> <kbd class="macro-args">[ SOURCE "<text of table source>" ]</kbd> +</div> + +<p> +Tables to be formatted with <kbd>tbl</kbd> begin with the macro +<kbd>.TS</kbd> and end with <kbd>.TE</kbd>. Global <kbd>tbl</kbd> +options (“flags”), formatting, and data (per +<kbd>tbl(1)</kbd>) come between the two macros. +<br/> +<span class="pre-in-pp"> + .TS + <tbl options, formatting, and data> + .TE +</span> +Tables may be wrapped inside a +<a href="#float-intro">float</a>, +in which case, the entire table will be output on the current page +if it fits, or deferred to the next page if it doesn’t. +<br/> +<span class="pre-in-pp"> + .FLOAT + .TS + <tbl options, formatting, and data> + .TE + .FLOAT OFF +</span> +</p> + +<div class="macro-id-overline"> +<h4 id="ts" class="docs" style="font-size: 100%; margin-top: .5em">The .TS macro</h4> +</div> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note: Version 2.0-c change</span> +<br/> +2.0-c introduces revisions to the handling of labels and/or +captions, which, along with <kbd>NO_SHIM</kbd>, must now be given +as arguments to <kbd>.TS</kbd> rather than <kbd>.TE</kbd>, as was +the case formerly. Please read this section carefully if you have +documents containing tables as they may need to be updated. +</p> +</div> + +<div class="box-important" style="margin-top: 1em"> +<p class="tip"> +<span class="important">IMPORTANT:</span> +All arguments to <b>TS</b> must appear on the same line as +<kbd>.TS</kbd>. Do not attempt to break them up with the +“line-continued” backslash. You may want to set your +text editor to “wrap” mode in order to see all your +arguments. This annoyance stems from the preprocessor mechanism +itself, not groff or mom. +</p> +</div> + +<p> +The <b>TS</b> macro must be invoked before entering a <kbd>tbl</kbd> +block. You may give as many or as few of its arguments as required, +in any order, although it is advisable to put <kbd>CAPTION</kbd>, +<kbd>SHORT_CAPTION</kbd>, and/or <kbd>LABEL</kbd> last. +</p> + +<h5 id="h" class="docs" style="margin-top: 1em; text-transform: none">H</h5> + +<p> +With the <b>H</b> argument, a table will span as many pages as +necessary, with or without a running header. The placement of the +corresponding +<a href="#th"><kbd>.TH</kbd></a>, +which is required whenever the <b>H</b> argument is given, +determines what, if anything, goes in the header. Compare the +following: +<span class="pre-in-pp"> + .TS H .TS H + c s s c s s + c s s c s s + c c c c c c + n n n. n n n. + Percent Increase .TH + 2002-2012 Percent Increase + .TH 2002-2012 + <tbl data> <tbl data> + .TE .TE +</span> +The first example will create a table that spans multiple +pages if necessary, with a running header (“Percent +Increase / 2002-2012”) for that table appearing at +the top of each page until the table ends. The second example, +equally, may run to several pages, but without the running header. +See +<a href="#th"><b>TH</b></a> +for an explanation of <kbd>.TH</kbd> placement. +</p> + +<div id="h-tip" class="box-tip"> +<p class="tip"> +<span class="note">Tip:</span> +Generally speaking, it’s a good idea to get into the habit +of using <kbd>.TS H</kbd> all the time, since there are no +circumstances under which it fails, whereas <kbd>.TS</kbd> without +<kbd>H</kbd> will fail on tables that exceed the page length. +</p> +</div> + +<h5 class="docs" style="margin-top: 1em; text-transform: none">BOXED</h5> + +<p> +If a table is to be boxed (i.e., <kbd>tbl</kbd> is given the flags +<kbd>'box'</kbd> or <kbd>'allbox'</kbd>) you must pass the argument +<kbd>BOXED</kbd> to <kbd>.TS</kbd>, as in this example: +<br/> +<span class="pre-in-pp"> + .TS BOXED + allbox; + c s s + c c c + n n n. + <tbl data> + .TE +</span> +</p> + +<h5 class="docs" style="margin-top: 1em; text-transform: none">CENTER</h5> + +<p> +If a table is to be centered on the page, (i.e., <kbd>tbl</kbd> is +given the <kbd>'center'</kbd> flag), you must pass the argument +<kbd>CENTER</kbd> to <kbd>.TS</kbd>, as in this example, which +creates a (possibly) multipage boxed table, centered on the page, +with a running header. +<span class="pre-in-pp"> + .TS H BOXED CENTER + allbox center; + c s s + c s s + c c c + n n n. + Percent Increase + 2002-2012 + .TH + <tbl data> + .TE +</span> +</p> + +<h5 class="docs" style="margin-top: 1em; text-transform: none">NEEDS</h5> + +<p> +If a table is not inside a float and you pass <kbd>.TS </kbd> the +<kbd>H</kbd> argument (which you should; see the tip +<a href="#h-tip">here</a>), +mom begins output immediately where the table occurs in the +input file <i>if there is enough room on the output page for the +table header plus at least one row of table data</i>. If there +isn’t enough room, mom breaks to a new page before beginning +the table, leaving a gap in +<a href="definitions.html#running">running text</a> +at the bottom of the previous page. If, for aesthetic reasons, +you would prefer that mom require more than one row of table data +beneath the header near the bottom of a page, you may increase the +number with the <kbd>NEEDS</kbd> argument, followed by the desired +number of rows. +</p> + +<h5 class="docs" style="margin-top: 1em; text-transform: none">ADJUST</h5> + +<p> +<kbd>ADJUST</kbd> lets you raise (<kbd>-</kbd>) or lower +(<kbd>+</kbd>) the table +<span style="font-style: italic">within the space allotted for it</span> +by the amount you specify. This is useful for achieving good +optical centering between surrounding blocks of type. A unit of +measure is required. +</p> + +<h5 class="docs" style="margin-top: 1em; text-transform: none">NO_SHIM</h5> + +<p> +<kbd>NO_SHIM</kbd> instructs mom not to apply +<a href="docprocessing.html#shim-vs-flex">shimming</a> +after a table, which she will do automatically when shimming is +enabled, which it is by default. Shimming ensures that running text +after the table falls properly on the page’s +<a href="definitions.html#baseline-grid">baseline grid</a>, +but can result in slightly unequal spacing above and below +(correctable with the <kbd>ADJUST</kbd> argument). +<kbd>NO_SHIM</kbd> is useful when you have several tables on the +page and there are visible differences in the spacing beneath them +as a result of shimming. To ensure a flush bottom margin, the last +table on the page should be shimmed, i.e. should not be given the +<kbd>NO_SHIM</kbd> argument. +</p> + +<h5 class="docs" style="margin-top: 1em; text-transform: none">NO_FLEX</h5> + +<p> +<kbd>NO_FLEX</kbd> instructs mom not to apply +<a href="docprocessing.html#shim-vs-flex">flex-spacing</a> +after a table, which she will do automatically when flex-spacing is +enabled. <kbd>NO_FLEX</kbd> is useful when you have several tables +on the page and you want to distribute excess vertical +whitespace on the page amongst other flex-spacing points on the +page. If there are no others, the final table should be +flex-spaced, i.e. not given the <kbd>NO_FLEX</kbd> argument. +</p> + +<h5 class="docs" style="margin-top: 1em; text-transform: none">CAPTION</h5> + +<p> +<kbd>CAPTION</kbd> allows you to give the table a caption. By +default, the caption appears above the table, but may be attached to +the label that appears beneath the table. See +<a href="#caption-after-label">CAPTION_AFTER_LABEL</a> +in +<a href="#captions-and-labels">Captions and labels</a>. +The text of the caption must be surrounded by double-quotes. +</p> + +<p> +Please note that if your table has a caption, you must invoke +<kbd>TS</kbd> with the <kbd>H</kbd> flag, which also entails the use +of +<a href="#th">TH</a>. +</p> + +<h5 class="docs" style="margin-top: 1em; text-transform: none">SHORT_CAPTION</h5> + +<p> +<kbd>SHORT_CAPTION</kbd> allows you to trim long captions for +inclusion in the List of Tables. The text you supply, surrounded +by double-quotes, is what will appear in the List. +</p> + +<h5 class="docs" style="margin-top: 1em; text-transform: none">LABEL</h5> + +<p> +<kbd>LABEL</kbd>, if given, appears beneath the table. The text you +supply, surrounded by double-quotes, is how the table is labelled +in both the document proper and the List of Tables. Mom provides +an auto-labelling facility for tables (see +<a href="#autolabel">AUTOLABEL</a>), +which, if enabled, overrides the <kbd>LABEL</kbd> argument. +</p> + +<h5 class="docs" style="margin-top: 1em; text-transform: none">TARGET</h5> + +<p> +<kbd>TARGET</kbd> followed by a unique name surrounded by +double-quotes creates a PDF target for the table so that it may be +linked to from other places in the file (with PDF_LINK; see +<a href="version-2.html#mom-pdf">Producing PDFs with groff and mom</a>). +</p> + +<p> +<b><i>Please note:</i></b> The following functionality is available +only with groff 1.22.4 or later. +</p> + +<p> +When +<a href="#autolabel">autolabelling</a> +is enabled and the document is processed with +<a href="using.html#pdfmom" style="font-weight: bold">pdfmom</a>, +the target name can be used to generate the target’s label +number in running text if it is entered as a groff string, i.e. of +the form <kbd><span class="nobr">\*[name]</span></kbd>. For example, if you +create a target called “foo” for a table whose autolabel +number would be 3, entering +<br/> +<span class="pre-in-pp"> + See + .PDF_LINK foo "Table \*[foo]" +</span> +anywhere in running text would result in a pdf link that reads +“Table 3”. If chapter numbers are being prefixed to +labels, the same string in, say, chapter 5 would produce the pdf +link “Table 5.3”. +</p> + +<div class="macro-id-overline"> +<h4 id="th" class="docs" style="font-size: 100%; margin-top: .5em">The .TH macro</h4> +</div> + +<p> +The <b>TH</b> macro (<b>T</b>able <b>H</b>eader), which is required +when you begin a table with <kbd>.TS H</kbd>, allows you to +determine what goes in a table’s running header if it spans +multiple pages. Placing <kbd>.TH</kbd> under the first row of +<kbd>tbl</kbd> data makes the first row the header. If placed under +the second row, the first and second rows form the header, and so +on. +</p> + +<p> +As there are sometimes reasons to run <kbd>.TS H</kbd> when +you don’t, in fact, want a running header (e.g. when +your table has a caption), you can suppress it by placing +<kbd>.TH</kbd> immediately underneath your <kbd>tbl</kbd> formatting +specifications, the last line of which always ends with a period +(see <kbd>tbl(1)</kbd>). +</p> + +<p> +See the +<kbd><a href="#h">H</a></kbd> +argument to <kbd>.TS</kbd> for examples demonstrating <kbd>.TH</kbd> +placement. +</p> + +<div class="macro-id-overline"> +<h4 id="te" class="docs" style="font-size: 100%; margin-top: .5em">The .TE macro</h4> +</div> + +<p> +<kbd>tbl</kbd> blocks must be terminated with <kbd>.TE</kbd>, +which, as of version 2.0-c, takes a single, optional argument, +<kbd>SOURCE</kbd>. (Formerly, <kbd>TE</kbd> took a label/caption +argument along with arguments controlling placement.) The argument +is followed by the text of the table’s source, surrounded by +double-quotes. The SOURCE argument may only be used if +<a href="#mla">MLA</a> +(Modern Language Association) style is enabled. +</p> + +<div class="rule-medium"><hr/></div> + +<h3 id="pic" class="docs">pic support</h3> + +<p> +Mom documents can include diagrams generated with the groff +preprocessor <b>pic</b>. If you are unfamiliar with <b>pic</b>, I +recommend downloading a copy of +<a href="http://www.kohala.com/start/troff/gpic.raymond.ps">Making Pictures with GNU PIC</a> +which provides a thorough introduction and contains many examples. +If you use <b>pic</b>, you must pass groff or pdfmom the <b>-p</b> +flag when you process the file. + +</p> + +<p> +Diagrams created with <kbd>pic</kbd> begin with the macro +<kbd>.PS</kbd> (<b>P</b>ic <b>S</b>tart) and end with +<kbd>.PE</kbd> (<b>P</b>ic <b>E</b>nd). Everything between them is +interpreted by the preprocessor as pic instructions. Please note: +<i>Making Pictures with GNU PIC</i> says that <kbd>.PF</kbd> can +also be used to terminate a pic diagram, but this is not supported +by mom. +</p> + +<p> +Pic diagrams are always centered. Note that this represents a +change from version 2.0-b of mom, where centering diagrams required +passing <kbd>-mpic</kbd> to <b>groff</b> or +<a href="using.html#pdfmom" style="font-weight: bold">pdfmom</a> +on the command line. +</p> + +<p> +In addition, mom treats <b>pic</b> diagrams identically to +<a href="#floats-intro">floats</a>, +which is to say that if a diagram doesn’t fit on the output +page, she will defer it to the top of the next page while continuing +to process +<a href="definitions.html#running">running text</a>. +<kbd>ADJUST</kbd> is ignored whenever a diagram is deferred, except +when moving from column to column on the same page, when the diagram +may need to be optically adjusted. Subsequent diagrams that do not +fit, if any, are output in order immediately after the first. +</p> + +<p> +Lastly, if your diagrams contain text, you may set all the type +parameters for the text (family, font, size, leading) separately +from the <b>pic</b> block with the macro +<a href="#pic-text-style">PIC_TEXT_STYLE</a>. +If you need to change the type parameters within the block +on-the-fly, you must use <b>pic</b>’s native facilities for +doing so. +</p> + +<div class="macro-id-overline"> +<h3 id="ps-pe" class= "macro-id">.PS / .PE</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>PS</b> +<kbd class="macro-args"> +<br/> +Arguments: [ <width> <height> ] +<kbd class="macro-args"> +<br/> + [ LEFT ]</kbd> +<br/> + [ ADJUST +|-<vertical adjustment>]</kbd> +<span style="font-size: 95%"> +(<a href="definitions.html#unitofmeasure">unit of measure</a> +required) +</span> +<kbd class="macro-args"><br/> + [ NO_SHIM ] +<br/> + [ NO_FLEX ] +<br/> + [ CAPTION "<caption>" ] +<br/> + [ SHORT_CAPTION "<short caption>" ] +<br/> + [ LABEL "<label>" ] +<br/> + [ TARGET "<name>" ] +</kbd> +<br/> +Macro: <b>PE</b> <span style="font-size: 95%">(no arguments; ends +the <b>pic</b> block)</span> +</div> + +<div class="box-important" style="margin-top: 1.5em"> +<p class="tip"> +<span class="important">IMPORTANT:</span> +All arguments to <b>PS</b> must appear on the same line as +<kbd>.PS</kbd>. Do not attempt to break them up with the +“line-continued” backslash. You may want to set your +text editor to “wrap” mode in order to see all your +arguments. This annoyance stems from the preprocessor mechanism +itself, not groff or mom. +</p> +</div> + +<h5 class="docs" style="margin-top: 1em; text-transform: none">'width' and 'height'</h5> + +<p> +The <kbd>width</kbd> and <kbd>height</kbd> arguments to +<kbd>.PS</kbd> are idiosyncratic owing to the preprocessor itself. +Both are optional and both expect a value in inches, so neither +argument should have a +(<a href="definitions.html#unitofmeasure">unit of measure</a> +appended. +</p> + +<p> +If the <kbd>width</kbd> argument is supplied, the diagram, but +not any text it contains, is scaled to the given width. If a +literal width argument of <kbd>0</kbd> (zero) is given and a +<kbd>height</kbd> argument is supplied, the diagram, but not any +text it contains, will be scaled to the requested height. In the +case of two non-zero arguments being given, only the height scaling +is applied. +</p> + +<h5 class="docs" style="margin-top: 1em; text-transform: none">LEFT</h5> + +<p> +By default, pic diagrams are centred on the page. If you would +prefer them to be flush left, pass <kbd>PS</kbd> the <kbd>LEFT</kbd> +argument. +</p> +<h5 class="docs" style="margin-top: 1em; text-transform: none">ADJUST</h5> + +<p> +<kbd>ADJUST</kbd> lets you raise (<kbd>-</kbd>) or lower +(<kbd>+</kbd>) a diagram +<span style="font-style: italic">within the space allotted for it</span> +by the amount you specify. This is useful for achieving good +optical centering between surrounding blocks of type. A unit of +measure is required. +</p> + +<h5 class="docs" style="margin-top: 1em; text-transform: none">NO_SHIM</h5> + +<p> +<kbd>NO_SHIM</kbd> instructs mom not to apply +<a href="docprocessing.html#shim-vs-flex">shimming</a> +after a <b>pic</b> diagram, which she will do automatically when +shimming is enabled, which it is by default. Shimming ensures that +running text after the diagram falls properly on the page’s +<a href="definitions.html#baseline-grid">baseline grid</a>, +but can result in slightly unequal spacing above and below +(correctable with the <kbd>ADJUST</kbd> argument). +<kbd>NO_SHIM</kbd> is useful when you have several diagrams on the +page and there are visible differences in the spacing beneath them +as a result of shimming. To ensure a flush bottom margin, the last +diagram on the page should be shimmed, i.e. should not be given the +<kbd>NO_SHIM</kbd> argument. +</p> + +<h5 class="docs" style="margin-top: 1em; text-transform: none">NO_FLEX</h5> + +<p> +<kbd>NO_FLEX</kbd> instructs mom not to apply +<a href="docprocessing.html#shim-vs-flex">flex-spacing</a> +after a <b>pic</b> diagram, which she will do automatically when +flex-spacing is enabled. <kbd>NO_FLEX</kbd> is useful when you +have several diagrams on the page and you want to distribute excess +vertical whitespace on the page amongst other flex-spacing points +on the page. If there are no others, the final diagram should be +flex-spaced, i.e. not given the <kbd>NO_FLEX</kbd> argument. +</p> + +<h5 class="docs" style="margin-top: 1em; text-transform: none">CAPTION</h5> + +<p> +<kbd>CAPTION</kbd> allows you to give the diagram a caption. By +default, the caption appears above the diagram, but may be attached to +the label that appears beneath it. See +<a href="#caption-after-label">CAPTION_AFTER_LABEL</a> +in +<a href="#captions-and-labels">Captions and labels</a>. +The text of the caption must be surrounded by double-quotes. +</p> + +<h5 class="docs" style="margin-top: 1em; text-transform: none">SHORT_CAPTION</h5> + +<p> +<kbd>SHORT_CAPTION</kbd> allows you to trim long captions for +inclusion in the List of Figures. The text you supply, surrounded +by double-quotes, is what will appear in the List. +</p> + +<h5 class="docs" style="margin-top: 1em; text-transform: none">LABEL</h5> + +<p> +<kbd>LABEL</kbd>, if given, appears beneath the diagram. The text you +supply, surrounded by double-quotes, is how the diagram is labelled +in both the document proper and the List of Figures. Mom provides +an auto-labelling facility for diagrams (see +<a href="#autolabel">AUTOLABEL</a>), +which, if enabled, overrides the <kbd>LABEL</kbd> argument. +</p> + +<h5 class="docs" style="margin-top: 1em; text-transform: none">TARGET</h5> + +<p> +<kbd>TARGET</kbd> followed by a unique name surrounded by +double-quotes creates a PDF target for the diagram so that it may be +linked to from other places in the file (with PDF_LINK; see +<a href="version-2.html#mom-pdf">Producing PDFs with groff and mom</a>). +</p> + +<p> +<b><i>Please note:</i></b> The following functionality is available +only with groff 1.22.4 or later. +</p> + +<p> +When +<a href="#autolabel">autolabelling</a> +is enabled and the document is processed with +<a href="using.html#pdfmom" style="font-weight: bold">pdfmom</a>, +the target name can be used to generate the target’s label +number in running text if it is entered as a groff string, i.e. of +the form <kbd><span class="nobr">\*[name]</span></kbd>. For example, if you +create a target called “foo” for a diagram whose +autolabel number would be 3, entering +<br/> +<span class="pre-in-pp"> + See + .PDF_LINK foo "Figure \*[foo]" +</span> +anywhere in running text would result in a pdf link that reads +“Figure 3”. If chapter numbers are being prefixed to +labels, the same string in, say, chapter 5 would produce the pdf +link “Figure 5.3”. +</p> + +<!-- PIC_TEXT_STYLE --> + +<div class="macro-id-overline"> +<h3 id="pic-text-style" class= "macro-id">PIC_TEXT_STYLE</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>PIC_TEXT_STYLE</b> \ +<br/> +<kbd class="macro-args"> + [ FAMILY ] "<family>" \ +<br/> + [ FONT ] "<font>" \ +<br/> + [ SIZE ] "+|-<size>" \ +<br/> + [ AUTOLEAD ] "<value>" +</kbd> +</div> + +<p> +Diagrams drawn with <b>pic</b> may contain text, and groff +<a href="inlines.html#intro-inlines">inline escapes</a> +may be used to alter the text parameters. A problem that arises +from so doing is that, in many cases, it clutters up the <b>pic</b> +code unnecessarily. +</p> + +<p> +PIC_TEXT_STYLE lets you establish the type parameters for text +inside a <b>pic</b> block all at once in cases where so doing +improves the readability of your mom source files. +</p> + +<p> +The arguments to PIC_TEXT_STYLE behave identically to the arguments +to other control macros, explained +<a href="docelement.html#control-macro-args">here</a>. +They may be given in any order, and you may use as many or as few as +you like. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +Text within <b>pic</b> diagrams does not scale when you provide a +scaling argument to <kbd>.PS</kbd>. This is a limitation of the +preprocessor itself, not groff or mom. +</p> +</div> + +<div class="rule-medium"><hr/></div> + +<h3 id="grap" class="docs">grap support</h3> + +<p> +Grap is a <b>pic</b> preprocessor for creating graphs. Grap +usage is covered in the <kbd>grap(1)</kbd> manpage. Its mom +implementation is the same as for <b>pic</b> except that instead of +enclosing directives between +<a href="#ps-pe">.PS / .PE</a>, +they are enclosed between <b>.G1/.G2</b>. If you use <b>grap</b>, +you must pass groff or pdfmom the <b>-G</b> flag when you process +the file. + +</p> + +<p> +<b>.G1</b> takes all the same arguments as +<a href="#ps-pe">PS</a> +with one exception: the argument <b>GRAP</b> must always be given to +<b>.G1</b>. So, for example, a skeleton grap block raised 2 points +and with a caption would be entered: +<br/> +<span class="pre-in-pp"> + .G1 GRAP ADJUST +2p CAPTION "Graph caption" + <grap directives> + .G2 +</span> + +</p> + +<div class="rule-medium"><hr/></div> + +<h3 id="eqn" class="docs">eqn support</h3> + +<p> +Support for <b>eqn</b> is provided via extensions to the standard +<kbd>.EQ/.EN</kbd> macros. <kbd>eqn</kbd> usage itself is beyond +the scope of this documentation, but is covered in the manpage +<kbd>eqn(1)</kbd>. You can also download a copy of Ted +Harding’s +<a href="http://lists.gnu.org/archive/html/groff/2013-10/pdfTyBN2VWR1c.pdf"> +A Guide to Typesetting Mathematics Using GNU eqn +</a>, +which contains useful examples. If you use <b>eqn</b>, you must give groff or +pdfmom the <b>-e</b> flag. + +</p> + +<div class="macro-id-overline"> +<h3 id="eq-en" class= "macro-id">.EQ / .EN</h3> +</div> + +<div class="box-macro-args"> +Macro: <a href="#eq"><b>EQ</b></a> +<br/> +<kbd class="macro-args">Arguments: +<br/> + [ -L | -C | -I <indent> ]</kbd> +<span style="font-size: 95%"> +(<a href="definitions.html#unitofmeasure">unit of measure</a> +required) +</span> +<kbd class="macro-args"><br/> + [ ADJUST +|-<vertical adjustment>]</kbd> +<span style="font-size: 95%"> +(<a href="definitions.html#unitofmeasure">unit of measure</a> +required) +</span> +<kbd class="macro-args"><br/> + [ NO_SHIM ] +<br/> + [ NO_FLEX ] +<br/> + [ CAPTION "<caption>" ] +<br/> + [ LABEL "<label>" ] +<br/> + [ SHIFT_LABEL +|-<vertical adjustment> ] +<br/> + [ SHORT_CAPTION "<short caption>" ] +<br/> + [ TARGET "<name>" ] +<br/> + [ CONTINUED | CONT | ... ]</kbd> +</div> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note: Version 2.0-c change</span> +<br/> +2.0-c introduces revisions to <b>EQ</b>, including the addition +of a dash (<kbd>-</kbd>) to the positioning arguments +(<kbd>-L</kbd>, <kbd>-C</kbd>, and <kbd>-I</kbd>) and the removal of a +default value for <kbd>-I</kbd>. Other changes include passing all +options to <kbd>.EQ</kbd> (including the label) such that +<kbd>.EN</kbd> takes only a single, optional argument saying whether +the equation is to be continued at the next invocation of +<kbd>.EQ</kbd>. Please read this section carefully if you have +documents containing equations as they may need to be updated. +</p> +</div> + +<div class="box-important" style="margin-top: 1em"> +<p class="tip"> +<span class="important">IMPORTANT:</span> +All arguments to <b>EQ</b> must appear on the same line as +<kbd>.EQ</kbd>. Do not attempt to break them up with the +“line-continued” backslash. You may want to set your +text editor to “wrap” mode in order to see all your +arguments. This annoyance stems from the preprocessor mechanism +itself, not groff or mom. +</p> +</div> + +<div class="macro-id-overline" style="margin-top: .5em"> +<h4 id="eq" class="docs" style="font-size: 100%; margin-top: .5em">The .EQ macro</h4> +</div> + +<p> +Equations to be set with <b>eqn</b> begin with <kbd>.EQ</kbd>, +followed by <b>eqn</b> code. Equations are centered by default, +but may be set flush left or indented from the left margin +if <kbd>-L</kbd> or <kbd>-I</kbd> are passed as arguments to +<kbd>.EQ</kbd>. +</p> + +<h5 class="docs" style="margin-top: 1em; text-transform: none">ADJUST</h5> + +<p> +<kbd>ADJUST</kbd> lets you raise (<kbd>-</kbd>) or lower +(<kbd>+</kbd>) an equation +<span style="font-style: italic">within the space allotted for it</span> +by the amount you specify. This is useful for achieving good +optical centering between surrounding blocks of type. A unit of +measure is required. +</p> + +<h5 class="docs" style="margin-top: 1em; text-transform: none">NO_SHIM</h5> + +<p> +<kbd>NO_SHIM</kbd> instructs mom not to apply +<a href="docprocessing.html#shim-vs-flex">shimming</a> +after an equation, which she will do automatically when shimming is +enabled, which it is by default. Shimming ensures that running text +after the equation falls properly on the page’s +<a href="definitions.html#baseline-grid">baseline grid</a>, +but can result in slightly unequal spacing above and +below (correctable with the <kbd>ADJUST</kbd> argument). +<kbd>NO_SHIM</kbd> is useful when you have several equations on the +page and there are visible differences in the spacing beneath them +as a result of shimming. To ensure a flush bottom margin, the last +equation on the page should be shimmed, i.e. should not be given the +<kbd>NO_SHIM</kbd> argument. +</p> + +<h5 class="docs" style="margin-top: 1em; text-transform: none">NO_FLEX</h5> + +<p> +<kbd>NO_FLEX</kbd> instructs mom not to apply +<a href="docprocessing.html#shim-vs-flex">flex-spacing</a> +after an equation, which she will do automatically when flex-spacing +is enabled. <kbd>NO_FLEX</kbd> is useful when you have several +equations on the page and you want to distribute excess vertical +whitespace on the page amongst other flex-spacing points on +the page. If there are no others, the final equation should be +flex-spaced, i.e. not given the <kbd>NO_FLEX</kbd> argument. +</p> + +<h5 class="docs" style="margin-top: 1em; text-transform: none">CAPTION</h5> + +<p> +<kbd>CAPTION</kbd> allows you to give the equation a caption. +Equation captions always appear beneath the equation. +</p> + +<h5 class="docs" style="margin-top: 1em; text-transform: none">SHORT_CAPTION</h5> + +<p> +<kbd>SHORT_CAPTION</kbd> allows you to trim long captions for +inclusion in the List of Equations. The text you supply, surrounded +by double-quotes, is what will appear in the List. +</p> + +<h5 class="docs" style="margin-top: 1em; text-transform: none">LABEL</h5> + +<p> +<kbd>LABEL</kbd>, if given, appears on the same baseline as the last line of the +equation, flush with the left or right margin, depending on the +equation’s horizontal position. The text you supply, surrounded by +double-quotes, is how +the equation is labelled in both the document proper and the List of +Equations. Mom provides an auto-labelling facility for equations (see +<a href="#autolabel">AUTOLABEL</a>), +which, if enabled, overrides the <kbd>LABEL</kbd> argument. +</p> + +<h5 class="docs" style="margin-top: 1em; text-transform: none">SHIFT_LABEL</h5> + +<p> +<kbd>SHIFT_LABEL</kbd> allows you to raise (<kbd>-</kbd>) or lower +(<kbd>+</kbd>) the equation label. It’s primary use is to +center equation labels vertically on the equation rather than flush +with the last line. Assuming a three-line equation, +<kbd>.EQ SHIFT_LABEL -1v</kbd> would raise the label by +one line, thus centering it vertically on the equation. +</p> + +<h5 class="docs" style="margin-top: 1em; text-transform: none">TARGET</h5> + +<p> +<kbd>TARGET</kbd> followed by a unique name surrounded by +double-quotes creates a PDF target for the equation so that it may +be linked to from other places in the file (with PDF_LINK; see +<a href="version-2.html#mom-pdf">Producing PDFs with groff and mom</a>). +</p> + +<p> +<b><i>Please note:</i></b> The following functionality is available +only with groff 1.22.4 or later. +</p> + +<p> +When +<a href="#autolabel">autolabelling</a> +is enabled and the document is processed with +<a href="using.html#pdfmom" style="font-weight: bold">pdfmom</a>, +the target name can be used to generate the target’s label +number in running text if it is entered as a groff string, i.e. of +the form <kbd><span class="nobr">\*[name]</span></kbd>. For example, if you +create a target called “foo” for an equation whose +autolabel number would be 3, entering +<br/> +<span class="pre-in-pp"> + See + .PDF_LINK foo "Equation \*[foo]" +</span> +anywhere in running text would result in a pdf link that reads +“Equation 3”. If chapter numbers are being prefixed to +labels, the same string in, say, chapter 5 would produce the pdf +link “Equation 5.3”. +</p> + + +<div class="macro-id-overline" style="margin-top: .5em"> +<h4 id="en" class="docs" style="font-size: 100%; margin-top: .5em">The .EN macro</h4> +</div> + +<p> +A block of <b>eqn</b> code is terminated with <kbd>.EN</kbd>. +</p> + +<p> +If an equation needs to span multiple lines, possibly aligned +with <b>eqn</b>’s <kbd>'mark'</kbd> and <kbd>'lineup'</kbd> +directives, separate invocations of <kbd><span class="nobr">.EQ/.EN</span></kbd> +are required for each line, and the optional argument, +<kbd>CONTINUED</kbd> (or <kbd>CONT</kbd>, or <kbd>...</kbd> [three +dots, an ellipsis]), must be passed to <kbd>.EN</kbd>. +</p> + +<p> +If <kbd>-L</kbd> or <kbd>-I</kbd> is given to the first +<kbd>.EQ</kbd> of a multi-line equation, they remain in effect +until an <kbd>.EN</kbd> without the <kbd>CONTINUED</kbd> argument +is reached. +</p> + +<p> +Mom does not treat equations as floats, therefore it is possible to +begin an equation on one page and terminate it on the next. If you +wish to keep all lines of an equation together, you must wrap the +equation, including all invocations of <kbd>.EQ/.EN</kbd>, inside +a +<a href="#floats-intro">float</a>. +</p> + +<div class="rule-medium"><hr/></div> + +<h3 id="refer" class="docs">refer support</h3> + +<p> +<b>refer</b> support is covered in the section +<a href="refer.html">Bibliographies and references</a>. +</p> + +<div class="rule-medium"><hr/></div> + +<h2 id="captions-and-labels" class="docs">Captions and labels</h2> + +<ul> + <li><a href="#autolabel">AUTOLABEL</a></li> + <li><a href="#caption-after-label">CAPTION_AFTER_LABEL</a></li> + <li><a href="#mla">MLA</a>—MLA-style captioning and labelling</li> + <li><a href="#captions-labels-sources">Set style parameters for captions, labels, and sources</a></li> +</ul> + +<p> +Mom includes facilities for adding captions and labels to figures, +tables, equations, and pdf images, including auto-labelling. If +Lists of Figures, Tables, and Equations are desired, captions (if +any) and labels (if any) are collected and output in the Lists with +the appropriate page number. +</p> + +<p> +The distinction between a caption and a label is that labels are +identifiers, e.g. “Fig. 1” or “Table 3”, +while captions are descriptive or informative. For most types of +writing, it is usual to provide both. +</p> + +<p> +By default, mom sets captions above figures (i.e. <b>pic</b> output and +pdf images) and tables. This behaviour may be modified with the +macro +<a href="#caption-after-label">CAPTION_AFTER_LABEL</a>. +Equations always have their captions set underneath. All aspects of +the text style for captions may be set with the macro +<a href="#captions-labels-sources">CAPTIONS</a>. +</p> + +<p> +Labels for tables are set underneath the table unless the +<a href="#mla">MLA</a> +macro has been invoked, in which case the label and caption appear +above the table, per MLA style, and the source for the table, if +any, appears underneath. Labels for figures are set underneath. +Equation labels, by default, are set on the same baseline as the +last line of the equation. Like captions, all aspects of text style +for labels may be established with a single macro +<a href="#labels">LABELS</a>. +Furthermore, mom can autolabel figures, tables, and equations, with +or without a prefixed chapter number. +</p> + +<div class="macro-id-overline"> +<h3 id="autolabel" class="macro-id">Autolabel</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>AUTOLABEL_EQUATIONS</b> +<br/> +Macro: <b>AUTOLABEL_IMAGES</b> +<br/> +Macro: <b>AUTOLABEL_PIC</b> +<br/> +Macro: <b>AUTOLABEL_TABLES</b> +<br/> +<kbd class="macro-args">Arguments: +<br/> +[ PREFIX "<string>"] [ SUFFIX "<string>"] [ PREFIX_CHAPTER [ <n> ] ] +</kbd> +</div> + +<p> +<b>AUTOLABEL_<type></b> takes care of labelling <type> by +identifying each with a separate, incrementing numeric scheme, which +is also collected for output in Lists of Figures, Equations, and +Tables. +</p> + +<p> +Autolabelling may be disabled on-the-fly by giving any argument +other than <kbd>PREFIX</kbd>, <kbd>SUFFIX</kbd>, or +<kbd>PREFIX_CHAPTER</kbd> to the appropriate macro. For example, +<br/> +<span class="pre-in-pp"> + .AUTOLABEL_IMAGES NO +</span> +would disable autolabelling of images. +</p> + +<h4 class="docs" style="margin-top: -.5em">Prefixes and suffixes</h4> + +<p> +By default, when <b>AUTOLABEL</b> is enabled, the label numbers are +prefixed, and, in the case of equations, suffixed, with strings such +that they appear for tables as “Table <n>”, for +<b>pic</b> diagrams and pdf images as “Fig. <n>”, +and for equations as “Eq. (<n>)”. +</p> + +<p> +You can use <kbd>PREFIX <"string"></kbd> to change what +comes before the automatic numbering. For example, if you are +including musical excerpts in your document, MLA style requires that +they be labelled “Ex. <n>”. Since musical +excerpts are likely to be scanned images (in pdf format, don’t +forget), you have to change the prefix string for pdf images: +<br/> +<span class="pre-in-pp"> + .AUTOLABEL_IMAGES \ + PREFIX "Ex. " \ + SUFFIX "" +</span> +If you need a suffix after the automatic numbering, use +<kbd>SUFFIX <"string"></kbd>, like this: +<br/> +<span class="pre-in-pp"> + .AUTOLABEL_IMAGES \ + PREFIX "(Fig. " \ + SUFFIX ")" +</span> +Note from the above that both arguments, <kbd>PREFIX</kbd> and +<kbd>SUFFIX</kbd>, are required should you want either. Two +adjacent double-quotes leaves the string blank. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +In automatically formatted +<a href="#lists-macros">“Lists of ...”</a>, +label number prefixes are stripped when autolabelling is enabled. +</p> +</div> + +<h4 class="docs" style="margin-top: -.5em">Prefixing chapter numbers</h4> + +<p> +If you would like mom to prefix chapter numbers to the label, +pass <kbd>AUTOLABEL_<type></kbd> the argument +<kbd>PREFIX_CHAPTER</kbd>. +</p> + +<p> +If for some reason you need to specify the chapter number, +you may do so by passing the number as an argument to +<kbd>PREFIX_CHAPTER</kbd>. Subsequent chapters or major sections +will increment by one as expected. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +For the purposes of labelling, mom treats +<a href="docprocessing.html#doctype">DOCTYPE DEFAULT</a> +as if it were <b>DOCTYPE CHAPTER</b>, hence, with +<kbd>PREFIX_CHAPTER</kbd>, each collated <b>DEFAULT</b> +doctype’s prefixed “chapter” number is +incremented and the label number itself reset to “1”. +If you do not supply the <kbd>PREFIX_CHAPTER</kbd> argument, the +label number is <i>not</i> reset automatically. To reset it, invoke +<kbd>.AUTOLABEL_<type></kbd> after each +<a href="docprocessing.html#collate">COLLATE</a>. +</p> +</div> + +<div id="set-autolabel" class="box-macro-args" style="margin-top: .5em"> +Macro: <b>SET_AUTOLABEL</b> <kbd class="macro-args">FIG | TBL | PIC | EQN <n></kbd> +</div> + +<p> +You may sometimes need to set or reset the autolabel number for a +particular type of pre-processor or for PDF images. This is likely +to occur if you are using +<a href="#float">FLOAT</a> +in conjunction with the <kbd>TO_LIST</kbd> argument. +</p> + +<p> +For example, if your document has Figures (PDF images, pic diagrams) +and you want your tables to be labelled as Figures as well, you have +to wrap the tables inside a float and label the float manually as +“Fig. n”, sending it to the List of Figures with +<kbd>TO_LIST FIGURES</kbd>. +</p> + +<p> +Mom does not autolabel floats or assign them automatically +to a list, so she doesn’t know you’ve interrupted the +auto-incrementing label numbers. Use SET_AUTOLABEL get her back on +track. The number you give as an argument after telling her which +kind of label number to set is the one you want to appear next. +<br/> +<span class="pre-in-pp"> + .SET_AUTOLABEL FIG 6 +</span> +means the next autolabelled Figure will be “Fig. 6.” +</p> + +<div class="macro-id-overline"> +<h3 id="caption-after-label" class="macro-id">Captions after labels</h3> +</div> + +<div class="box-macro-args" style="margin-top: .5em"> +Macro: <b>CAPTION_AFTER_LABEL</b> <kbd class="macro-args">IMG | PIC | TBL | ALL [ <anything> ]</kbd> +</div> + +<p> +By default, mom sets captions above figures (<b>pic</b> output +and pdf images) and tables; labels are always underneath. +</p> + +<p> +<kbd>.CAPTION_AFTER_LABEL</kbd>, with one of the required arguments, +instructs mom to attach captions directly to the appropriate +labels, beginning on the same line. Any argument after the first +disables this behaviour, restoring caption placement to mom’s +default. For example, +<br/> +<span class="pre-in-pp"> + .CAPTION_AFTER_LABEL ALL +</span> +would enable captions after labels globally, while a subsequent +<br/> +<span class="pre-in-pp"> + .CAPTION_AFTER_LABEL IMG OFF +</span> +would disable captions after labels for pdf images only. +<kbd>OFF</kbd> can be anything you like (<kbd>X</kbd>, +<kbd>NO</kbd>, etc). +</p> + +<p> +If +<a href="#mla">MLA</a> +is enabled, there’s no need to invoke +<kbd>CAPTION_AFTER_LABEL</kbd> as this is implied. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +A separate invocation of <kbd>.CAPTION_AFTER_LABEL</kbd> is required +for each one of the required first arguments. You cannot, for +example, do +<br/> +<span class="pre-in-pp"> + .CAPTION_AFTER_LABEL IMG TBL +</span> +Rather, you must do +<br/> +<span class="pre-in-pp"> + .CAPTION_AFTER_LABEL IMG + .CAPTION_AFTER_LABEL TBL +</span> +</p> +</div> + +<div class="macro-id-overline"> +<h3 id="mla" class="macro-id">MLA-style captioning and labelling</h3> +</div> + +<div class="box-macro-args" style="margin-top: .5em"> +Macro: <b>MLA</b> <kbd class="macro-args"> [ <anything> ]</kbd> +</div> + +<p> +Modern Language Association style dictates that captions should +always go after labels. Furthermore, labels and captions for tables +should go <i>above</i> the tables, with the source for the table, if +any, underneath. +</p> + +<p> +Invoking <kbd>.MLA</kbd> by itself takes care of these details. If +you need to disable MLA-style captioning and labelling mid-document, +<kbd>.MLA OFF</kbd> does the trick. <kbd>OFF</kbd> can be +anything you like (<kbd>X</kbd>, <kbd>NO</kbd>, etc). +</p> + +<div class="macro-id-overline" style="margin-top: 1em"> +<h3 id="captions-labels-sources" class="macro-id">Style parameters for captions, labels and sources</h3> +</div> + +<div class="box-macro-args" style="margin-top: .5em"> +Macro: <b>CAPTIONS</b> <kbd class="macro-args">EQN | IMG | PIC | TBL | FLOATING | ALL</kbd> +<br/> +Macro: <b>LABELS</b> <kbd class="macro-args">EQN | IMG | PIC | TBL | FLOATING | ALL</kbd> +<br/> +Macro: <b>SOURCES</b> <kbd class="macro-args">TBL</kbd> +<br/> +<kbd class="macro-args">Style arguments: +<br/> + FAMILY <family> \ +<br/> + FONT <font> \ +<br/> + SIZE +|-<size> \ +<br/> + AUTOLEAD <value> \ +<br/> + COLOR <color> \ +<br/> + QUAD LEFT | CENTER | RIGHT [ ON_LL ] \ +<br/> + INDENT <indent> \ +<br/> + ADJUST +|-<vertical adjustment> +</kbd> +</div> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +Arguments may be broken into several lines using the +“line-continued” backslash (<b>\</b>), as shown above. +</p> +</div> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Additional note:</span> +Mom’s default style for labels, captions, and sources is +the same as the style used for running text, with two exceptions: +labels are set in bold, except for eqn which is roman medium, and +the autolead value for all three is “2”, effectively +tightening the lead. Furthermore, they are quadded left (except +eqn, which is quadded right.) +</p> +</div> + +<p> +With the exception of <kbd>ADJUST</kbd> and <kbd>QUAD</kbd> (which +requires a bit of explanation), the style arguments to <kbd>CAPTIONS</kbd>, +<kbd>LABELS</kbd>, and <kbd>SOURCES</kbd> (which is only available +for tables) behave identically to the +<a href="docelement.html#control-macro-args">arguments to control macros</a>. +</p> + +<p> +The first, required argument after <kbd>CAPTIONS</kbd>, +<kbd>LABELS</kbd>, or <kbd>SOURCES</kbd> indicates the preprocessor +type for which you are setting the parameters. (For convenience +PDF_IMAGE—argument <kbd>IMG</kbd>—is here treated as a +preprocessor.) <kbd>FLOATING</kbd> sets the style for the macros +<a href="#caption">CAPTION</a> +and +<a href="#label">LABEL</a>, +which are used to label floats, quotes, and blockquotes. +</p> + +<p> +An argument of <kbd>ALL</kbd> sets a unified style for all +preprocessors, floats, quotes, and blockquotes. If the +<kbd>ALL</kbd> argument is given, arguments to subsequent +invocations of <kbd>CAPTIONS</kbd>, <kbd>LABELS</kbd>, or +<kbd>SOURCES</kbd> overwrite only the explicitly named style +parameters. +</p> + +<h4 class="docs">QUAD — quadding of labels, captions, and sources</h4> + +<h5 class="docs" style="text-transform: none">• pic, tbl, pdf images</h5> + +<p> +By default, figures (<b>pic</b> output and pdf images) and tables +have their captions and labels set quad left. Sources (for +tables) are also set quad left. Equations have their labels +set quad right, and their captions centered. +</p> + +<p> +Regardless of the quad direction, captions, labels and sources +are set on the width of the figure, table, or pdf image +unless you pass the optional <kbd>ON_LL</kbd> argument to +<kbd><span class="nobr">QUAD <direction></span></kbd>, in which case +the prevailing document line length is used instead. +</p> + +<h5 class="docs" style="text-transform: none">• eqn</h5> + +<p> +Equations behave differently. By default, equation labels are +set flush right with the page’s right margin regardless of +equation positioning, which is, again by default, centered. If the +equation is positioned left, the label will appear at the right +margin regardless of the direction you give to <kbd>QUAD</kbd>. If +the equation is indented with the +<kbd><span class="nobr">-I <indent></span></kbd> option, a quad +direction of <kbd>LEFT</kbd> is observed, but may overprint the last +line of the equation. +</p> + +<p> +Note that there is no <kbd>CENTER</kbd> option for equation labels, +and that captions are always quadded over the prevailing document +line length. +</p> + +<h5 class="docs" style="text-transform: none">• quotes and blockquotes</h5> + +<p> +Floating labels attached to <b>QUOTE</b>s are quadded on the +prevailing document line length, and require the <kbd>INDENT</kbd> +argument if you want to align them with the left and/or right edges +the quote. +</p> + +<p> +Floating labels attached to <b>BLOCKQUOTE</b>s are always quadded on +the indent and line length of the blockquote. +</p> + +<h5 class="docs" style="text-transform: none">• floats</h5> + +<p> +Floating labels and captions attached to <b>FLOAT</b>s are always +quadded over the prevailing document line length, and require the +<kbd>INDENT</kbd> argument if you want to align them with the left +and/or right edges of the float’s contents. +</p> + +<h4 class="docs">INDENT</h4> + +<p> +The <kbd>INDENT</kbd> argument may only be used if the label +or caption type is <kbd>FLOATING</kbd>, and only applies to +<b>FLOAT</b>s and <b>QUOTE</b>s, not <b>BLOCKQUOTE</b>s. +</p> + +<p> +It is not possible for mom to know the width of a float before +setting a label or caption attached to a float. She therefore sets +it on the prevailing document line length. While this isn’t +much of an issue when the label or caption quad is <b>CENTER</b>, +you may want to adjust the horizontal positioning when the quad is +<b>LEFT</b> or <b>RIGHT</b>. +</p> + +<p> +<kbd>INDENT</kbd>, with a numeric value to which a +<a href="definitions.html#unitofmeasure">unit of measure</a> +is appended, allows you to indent a floating label or caption so +it lines up with the left edge of a <b>FLOAT</b> or <b>QUOTE</b>. +<kbd>INDENT RIGHT</kbd> (with a value) allows you to shorten the +line length to the appropriate width. If you need both a left and +right indent, invoke <kbd>LABELS</kbd> or <kbd>CAPTIONS</kbd> twice, +one instance containing <kbd>INDENT <indent></kbd> and +the other <kbd>INDENT RIGHT <indent></kbd>. +</p> + +<h4 class="docs">ADJUST</h4> + +<p> +The <kbd>ADJUST</kbd> argument allows you to add(<kbd>+</kbd>) or +subtract (<kbd>-</kbd>) vertical space between labels and captions +and the output to which they are attached. The argument requires a +<a href="definitions.html#unitofmeasure">unit of measure</a>. +For example, if you find that table labels are a bit too close to +the table itself, +<br/> +<span class="pre-in-pp"> + .LABELS TBL ADJUST +3p +</span> +would put three extra points of space between the bottoms of tables +and the labels that appear beneath them. +</p> + +<h2 id="lists-of" class="docs">Lists of Figures, Tables, and Equations</h2> + +<p> +Besides a +<a href="tables-of-contents.html">Table of Contents</a>, +mom can generate Lists of Figures, Tables, and Equations. Labels +and captions are collected and concatenated, and output in lists +with the appropriate page number, just like a Table of Contents. +Including such lists in a document is as simple as adding whichever +you need of +<br/> +<span class="pre-in-pp"> + .LIST_OF_FIGURES + .LIST_OF_EQUATIONS + .LIST_OF_TABLES +</span> +to the end of your input file. +</p> + +<p> +Also like the Table of Contents, entries in the Lists’ output +are clickable PDF links when a document is viewed at the screen. +</p> + +<h3 id="lists-placement" class="docs">Placement of Lists</h3> + +<p> +Lists normally appear after the Table of Contents, and continue +the page numbering scheme used for it. By default, the Table of +Contents begins on roman-numeral page “i”. +</p> + +<p> +If you are using mom’s +<a href="tables-of-contents.html#auto-relocate-toc">AUTO_RELOCATE_TOC</a> +feature, you have two options for placement of the Lists within the +document. If you want the Lists shifted to the top of the document +along with the Table of Contents, invoke the Lists macros <i>after</i> +<a href="tables-of-contents.html#toc"><kbd>.TOC</kbd></a>. +If you prefer to have the Lists at the end of the document, invoke +the Lists macros <i>before</i> <kbd>.TOC</kbd>. +</p> + +<p> +Lists shifted with the Table of Contents do not appear in the Table +of Contents itself, but do appear as clickable links in the PDF +outline typically available in the left panel of most PDF viewers. +Lists that are not shifted with the Table of Contents appear in both +the Table of Contents itself and the PDF outline. +</p> + +<div class="macro-id-overline" style="margin-top: 1em"> +<h3 id="lists-macros" class="macro-id">Macros to generate Lists</h3> +</div> + +<div class="box-macro-args" style="margin-top: .5em"> +Macro: <b>LIST_OF_EQUATIONS</b> +<br/> +Macro: <b>LIST_OF_FIGURES</b> +<br/> +Macro: <b>LIST_OF_TABLES</b> +<br/> +<kbd class="macro-args">Arguments: +<br/> + [ TITLE_STRING "<string>" ] [ START_PAGENUM <page number> ] +</kbd> +</div> + +<p> +The first optional argument to the <kbd>LIST_OF_<type></kbd> +macros allows you to change the title that appears at the top of the +page. This is useful not only for internationalization, or to meet +the requirements of various style guides, but is also useful +for, say, documents containing musical examples, which, per +MLA-style, should be labelled “Example ” or +“Ex. ”. When it comes time to output the List of +Figures (to which musical examples, usually scanned pdf images, belong), +<br/> +<span class="pre-in-pp"> + LIST_OF_FIGURES TITLE_STRING "List of Examples" +</span> +ensures that the title of the List is correct. +</p> + +<p> +The second optional argument allows you to give a starting page +number for a list in cases where mom’s pagination scheme does +not provide the List with the starting page number you want. +</p> +<h3 id="formatting-lists" class="docs">Formatting and style parameters for Lists</h3> + +<p> +Like the Table of Contents, nearly every aspect of Lists can be +designed independently of a document’s overall style. By +default, Lists follow the formatting and style parameters of the +Table of Contents, both mom’s defaults and any changes you may +have made to the Table of Contents. +</p> + +<p> +If you wish to make changes to any aspect of Lists formatting +or styling, the macro <kbd>LISTS_STYLE</kbd> provides all the +tools necessary. It is unlikely that you’ll want the +formatting of the various list types to differ one from the other, +so <kbd>LISTS_STYLE</kbd> applies to all Lists. In the event that +you do need to change some aspect of the formatting for different +list types, simply invoke <kbd>LISTS_STYLE</kbd> immediately prior +to each list whose formatting needs to be changed. +</p> + +<div class="macro-id-overline" style="margin-top: 1em"> +<h3 id="lists-style" class="macro-id">Lists style</h3> +</div> + +<div class="box-macro-args" style="margin-top: .5em"> +Macro: <b>LISTS_STYLE</b> <kbd class="macro-args"> +<br/> +Arguments: +<br/> + FAMILY <family> \ +<br/> + FONT <font> \ +<br/> + PT_SIZE <size> \ +<br/> + LEAD <leading> \ +<br/> + TITLE_FAMILY <family> \ +<br/> + TITLE_FONT <font> \ +<br/> + TITLE_SIZE +|-<size> \ +<br/> + TITLE_QUAD LEFT | CENTER | RIGHT \ +<br/> + TOC_HEADER_UNDERSCORE default = none +<br/> + TITLE_COLOR <color> \ +<br/> + PN_FAMILY <family> \ +<br/> + PN_FONT <font> \ +<br/> + PN_SIZE +|-<size> \ +<br/> + EQN_PN_PADDING <placeholders> \ +<br/> + FIG_PN_PADDING <placeholders> \ +<br/> + TBL_PN_PADDING <placeholders> \ +<br/> + PAGENUM_STYLE DIGIT | ROMAN | roman | ALPHA | alpha \ +<br/> + NO_PAGINATION +</kbd> +</div> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +Arguments may be broken into several lines using the +“line-continued” backslash (<b>\</b>), as shown above. +</p> +</div> + +<p> +<kbd>FAMILY</kbd> is the family for the entirety of Lists pages. +</p> + +<p> +<kbd>FONT</kbd> is the font for the entirety of Lists pages. +</p> + +<p> +<kbd>PT_SIZE</kbd> is the base point size for the entirety of Lists +pages. +</p> + +<p> +<kbd>LEAD</kbd> is the base leading for the entirety of Lists pages. +</p> + +<p> +<kbd>TITLE_FAMILY</kbd> is the family for the Lists titles if you +want it different from the family otherwise used for the Lists +pages. +</p> + +<p> +<kbd>TITLE_FONT</kbd> is the font for the Lists titles if you want +it different from the font otherwise used for the Lists pages. +</p> + +<p> +<kbd>TITLE_SIZE</kbd> tells mom by how much to increase +(<kbd>+</kbd>) or decrease (<kbd>-</kbd>) the point size of the +titles relative to the overall point size of Lists pages. +</p> + +<p> +<kbd>TITLE_QUAD</kbd> tells mom how to position the title +horizontally. +</p> + +<p> +<kbd>TITLE_COLOR</kbd> sets the colour for the titles. The colour +must be pre-initialized with +<a href="color.html#newcolor">NEWCOLOR</a> +or +<a href="color.html#xcolor">XCOLOR</a>. +</p> + +<p> +<kbd>PN_FAMILY</kbd> sets the family for entry pagenumbers. +</p> + +<p> +<kbd>PN_FONT</kbd> sets the font for entry pagenumbers. +</p> + +<p> +<kbd>PN_SIZE</kbd> tells mom by how much to increase (<kbd>+</kbd>) +or decrease (<kbd>-</kbd>) the point size of entry pagenumbers +relative to the overall point size of Lists pages. +</p> + +<p> +<kbd>EQN_PN_PADDING</kbd>, <kbd>FIG_PN_PADDING</kbd>, and +<kbd>TBL_PN_PADDING</kbd> tells mom how many placeholders to reserve +for the entry pagenumbers in their respective Lists. If, for example, +a document with both tables and figures runs to over a hundred +pages, but there are no tables after page 99, +<br/> +<span class="pre-in-pp"> + LISTS_STYLE FIG_PN_PADDING 3 + LISTS_STYLE TBL_PN_PADDING 2 +</span> +would prevent an unneeded, reserved placeholder from putting too +much space between the leader and the entry pagenumber in the List of +Tables. +</p> + +<p> +The padding in effect, unless you change it, is whatever was set for +the Tables of Contents; mom’s default is “3”. +</p> + +<p> +<kbd>PAGENUM_STYLE</kbd> tells mom which pagination format to use +for the page numbers of the Lists pages themselves. By default, +since Lists observe what is in effect for the Table of Contents, the +pagination format is “roman”. Please note that the +starting page number for any of the Lists is given as an argument to +the +<a href="#lists-of">LISTS_0F_<type></a> +macro. +</p> + +<p> +<kbd>NO_PAGINATION</kbd> disables pagination of Lists pages. +</p> + +<h2 id="box-intro" class="docs">Shaded backgrounds and frames (boxes)</h2> + +<p> +Mom lets you add shaded backgrounds and frames to text and other +material. For convenience, she calls backgrounds and frames +“boxes.” Entire passages may be boxed, or individual +document elements like headings, quotes, or pre-processor output. +Furthermore, boxes may be nested. +</p> + +<p> +Boxes start on the baseline where the boxed material would have +started were it not for the box, subject to minor aesthetic +corrections mom takes the liberty of making. +</p> + +<p> +Boxes extend from the current left margin to the current right +margin, respecting any active left and/or right indents. There are +two exceptions, +<a href="docelement.html#epigraph">EPIGRAPH BLOCK</a> +and +<a href="docelement.html#blockquote">BLOCKQUOTE</a>, +which are discussed +<a href="#quotes">here</a>. +</p> + +<p> +After a box is started, active left and right indents are +cleared. The box’s inset determines the new left and right +margins. Indents set inside a box are relative to the inset. +When a box is stopped, formerly active left and right indents +are restored. +</p> + +<p> +Frames are drawn from the perimeter inward. The inset is +relative to the inner edge of the frame. +</p> + +<p> +If a box (including the bottom inset) can complete on a page, it +does, even if there is no further room for type. This may, on +occasion, result in slight deviations from normal bottom margin +alignment. +</p> + +<p> +Boxes span pages whenever the boxed material continues on the next +page. Spanning boxes extend fully to the bottom margin of the page +on which they begin, leaving a slightly larger inset at the bottom +than around the other sides. +</p> + +<p> +When there is not enough room to set at least one line of type +inside a box, mom defers starting the box until the next page, +leaving a gap. +</p> + +<p> +Boxed material is not +<a href="docprocessing.html#shim-vs-flex">shimmed</a> +or +<a href="docprocessing.html#shim-vs-flex">flexed</a>. +If either was active prior to the box, it is restored when the box +ends and mom automatically shims or flexes whatever comes next. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="important">NOTE:</span> +Shaded backgrounds and frames are not available when your +<a href="docprocessing.html#printstyle">PRINTSTYLE</a> +is <kbd>TYPEWRITE</kbd> or when +<a href="docprocessing.html#columns">COLUMNS</a> are enabled. +</p> +</div> + +<div class="macro-id-overline"> +<h3 id="box" class= "macro-id">BOX</h3> +</div> + +<div id="box-macro" class="box-macro-args" style="margin-top: .5em"> +Macro: <b>BOX</b> <kbd class="macro-args"> [ <arguments> ] | <anything> +<br/> +Arguments: +<br/> +[ SHADED <color> | OUTLINED <colour> ] \ +<br/> +[ INSET <dist> ] \ +<br/> +[ WEIGHT <wt> ] \ +<br/> +[ ADJUST +|-<amount> ] \ +<br/> +[ EQN | PIC | GRAP | IMG ] +</kbd> +</div> + +<p> +Without arguments, BOX begins a shaded grey background. +The material inside is inset by one +<a href="definitions.html#picaspoints">pica</a>. +Any other type of box requires at a minimum either +<kbd>SHADED</kbd> or <kbd>OUTLINED</kbd>. In the case of boxes +that are to contain pdf images or pre-processor material for +<a href="#eqn">eqn</a>, +<a href="#pic">pic</a>, +or +<a href="#grap">grap</a>, +<kbd>IMG</kbd>, <kbd>EQN</kbd>, <kbd>PIC</kbd>, or <kbd>GRAP</kbd> +must also be given. Note that +<a href="#tbl">tbl</a> +does not have this requirement. +</p> + +<p> +BOX is a +<a href="definitions.html#toggle">toggle macro</a>, +so any argument other than one in the list completes the box +(<kbd>QUIT</kbd>, <kbd>END</kbd>, <kbd>X</kbd>, etc). +</p> + +<p> +Boxes should be started inside toggle macros like +<a href="docelement.html#quote">QUOTE</a> +or +<a href="#float">FLOAT</a> +just after the macro is called, and terminated just before toggling +the macro off (unless you wish the box to enclose further material). +</p> + +<p> +Non-toggle macros like +<a href="docelement.html#heading">HEADING</a> +or +<a href="docelement.html#pp">PP</a> +require that the box be started beforehand. Boxed pre-processor +material must be fully enclosed by BOX / BOX OFF, as +in this recipe for a one-off boxed pic diagram: +<span class="pre-in-pp"> +.BOX +.PS +<pic commands> +.PE +.BOX OFF +</span> +Arguments to BOX are not sticky. Each time you invoke BOX, you +must invoke it with arguments unless you want mom’s default grey +background. If all or several boxes in a document require the same +arguments, create a macro at the top of the input file that calls +BOX with the arguments you want, e.g. +<span class="pre-in-pp"> + .de PINK_BOX + .BOX \ + SHADED pink \ + OUTLINED darkred \ + WEIGHT 1p \ + INSET 9p + .. +</span> +<kbd>.PINK_BOX</kbd> may then be used instead of <kbd>.BOX</kbd> any +time you want a box with those arguments. +</p> + +<h3 class="docs">SHADED | OUTLINED</h3> + +<p> +<kbd>SHADED</kbd> or <kbd>OUTLINED</kbd> are required. Both may +be given, resulting in a shaded background with a frame, and both +require a colour, e.g. +<span class="pre-in-pp"> + .BOX SHADED blue OUTLINED black +</span> +The colour may be +</p> + +<ul style="margin-top: -1em;"> + <li>an xcolor name</li> + <li>a colour initialized with + <a href="color.html#newcolor">NEWCOLOR</a> + or + <a href="color.html#xcolor">XCOLOR</a> + </li> + <li>an RGB hexadecimal string beginning with (e.g. #FF0000)</li> +</ul> + +<p> +Note that without <kbd>SHADED</kbd>, the above would simply draw a +black frame. +</p> + +<h3 class="docs">WEIGHT</h3> + +<p> +Mom’s default weight for <kbd>OUTLINED</kbd> is 1/2 +<a href="definitions.html#picaspoints">point</a>. +If you’d like to change it, give <kbd>WEIGHT</kbd> the desired +value with a unit of measure appended, typically points, e.g. +<span class="pre-in-pp"> + .BOX OUTLINED black WEIGHT 1p +</span> +</p> + +<h3 class="docs">INSET</h3> + +<p> +Mom’s default inset for boxes is one +<a href="definitions.html#picaspoints">pica</a> +on all sides. If you’d like a larger or smaller inset, give +<kbd>INSET</kbd> the distance you want with a unit of measure +appended, e.g. +<span class="pre-in-pp"> + .BOX SHADED pink INSET 2m +</span> +</p> + +<h3 class="docs">ADJUST</h3> + +<p> +If you are not happy with the starting position of a box, you can +change it by giving <kbd>ADJUST</kbd> the distance you want it +raised (-) or lowered (+) with a unit of measure appended. For +example, to lower a box three points, +<span class="pre-in-pp"> + .BOX OUTLINED black ADJUST +3p +</span> +To raise it, +<span class="pre-in-pp"> + .BOX OUTLINED black ADJUST -3p +</span> +</p> + +<h3 class="docs">PIC / GRAP / EQN / IMG</h3> + +<p> +The <kbd>PIC</kbd> argument must be given to BOX if the box contains +any +<a href="#pic">pic</a> +diagrams. Likewise, graphs made with +<a href="#grap">grap</a>, +equations made with +<a href="#eqn">eqn</a>, +and +<a href="#pdf-image">pdf images</a> +require a corresponding <kbd>GRAP</kbd>, <kbd>EQN</kbd>, or +<kbd>IMG</kbd> argument. +</p> + +<p> +If you’re boxing a single diagram, graph, or pdf image, wrap +it in a float, like this: +<span class="pre-in-pp"> + .FLOAT + .BOX PIC <other parameters> + .PS + <pic input> + .PE + .BOX OFF + .FLOAT OFF +</span> +Notice that in the case of pdf images, pic, and grap, this +represents a change from the norm, where the use of FLOAT may be +destructive and is discouraged. +</p> + +<h2 id="box-notes" class="docs">Additional notes on BOX usage and behaviour</h2> + +<h3 id="qbef" class="docs">QUOTE, BLOCKQUOTE, EPIGRAPH, FLOAT</h3> + +<p> +<a href="docelement.html#quote">QUOTE</a>, +<a href="docelement.html#blockquote">BLOCKQUOTE</a>, +<a href="docelement.html#epigraph">EPIGRAPH</a>, +and +<a href="images.html#float">FLOAT</a> +require that boxes be started <i>after</i> they are +invoked and stopped just before they are toggled off: +<span class="pre-in-pp"> + .QUOTE + .BOX <parameters> + Text of quote + .BOX OFF + .QUOTE OFF +</span> +</p> + +<h3 id="code" class="docs">CODE</h3> + +<p> +If you’re boxing +<a href="docelement.html#code">CODE</a> +that’s wrapped inside +<a href="docelement.html#quote">QUOTE</a>, +as described +<a href="docelement.html#quote-code">here</a>, +set the quote indent to “0” with +<span class="pre-in-pp"> + .QUOTE_STYLE INDENT 0 +</span> +so that the box’s leftmost inset is respected. +</p> + +<p> +Here’s a recipe for setting boxed code with an 18-point inset: +<span class="pre-in-pp"> + .QUOTE_STYLE INDENT 0 + .QUOTE + .CODE + .BOX INSET 18p + Hello, world. + .BOX OFF + .QUOTE OFF +</span> +Note that CODE, wrapped inside QUOTE, does not require a corresponding CODE OFF. +</p> + +<h4 id="quotes" class="docs">Description of boxed BLOCKQUOTES and EPIGRAPH BLOCKS</h4> + +<p> +When you box a BLOCKQUOTE, or an EPIGRAPH with the <kbd>BLOCK</kbd> +argument, the box is centred on the page and is only as wide as the +blockquote or epigraph plus the box’s inset. +</p> + +<p> +QUOTE and EPIGRAPH (without the <kbd>BLOCK</kbd> argument), on the +other hand, set the box fully to the left and right margins. +</p> + +<h4 id="leftover" class="docs">Leftover box syndrome</h4> + +<p> +Boxed quotes and blockquotes sometimes exhibit leftover box +syndrome, where the page after a fully terminated boxed quote or +blockquote begins with an empty bit of box. Equally, you may +sometimes see the lower edge of a quote’s or +blockquote’s box falling slightly below the page’s +bottom margin. +</p> + +<p> +The solution in both situations is to use the <kbd>ADJUST</kbd> +argument to raise or lower the box’s starting position. +Leftover box syndrome is usually fixed by raising the box slightly. +When the box runs too deep, lowering it is generally recommended, +although this will result in a widowed line at the top of the next +page. In either case, some experimentation is necessary. +</p> + +<h3 id="slides" class="docs">SLIDES</h3> + +<p> +On a slide with no pauses, boxes behave as they do in printed +documents. +</p> + +<p> +When a slide contains pauses, only the material up to the first +pause is boxed. As subsequent material is revealed, the box changes +location, moving down to surround each new item. This behaviour +persists until the box is stopped, making it useful for highlighting +material as it is revealed. +</p> + +<h3 id="footnotes" class="docs">Footnotes</h3> + +<p> +You don’t have to worry about boxes encroaching on footnotes. +Mom makes sure they don’t. +</p> + +<h2 id="page-color-intro" class="docs">Page colour</h2> + +<p> +Mom lets you change the page (“paper”) colour +from white to anything you like. While this has limited application +in printed documents, it can be effective in +<a href="docprocessing.html#slides">slide presentations</a>. +</p> + +<div class="macro-id-overline"> +<h3 id="page-color" class= "macro-id">PAGE_COLOR</h3> +</div> + +<div id="page-color-macro" class="box-macro-args" style="margin-top: .5em"> +Macro: <b>PAGE_COLOR</b> <kbd class="macro-args"> <color> | OFF | off</kbd> +</div> +<p class="requires" style="font-style: normal"> +<i>Aliased as</i> <kbd>PAGE_COLOUR</kbd>, <kbd>SLIDE_COLOR</kbd>, +<i>and</i> <kbd>SLIDE_COLOUR</kbd>. +</p> + +<p> +When you invoke PAGE_COLOR with a <kbd>color</kbd> argument, the +current and subsequent pages turn the colour you request. If +more than one instance of PAGE_COLOR appears before a page break, +including <kbd>PAGE_COLOR OFF</kbd>, only the last applies. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +Unlike other +<a href="definitions.html#toggle">toggle macros</a>, +PAGE_COLOR requires the use of <kbd>OFF</kbd> or <kbd>off</kbd> +to terminate it rather than an arbitrary string (<kbd>OFF</kbd>, +<kbd>QUIT</kbd>, <kbd>END</kbd>, <kbd>X</kbd>, etc). +</p> +</div> + +<div class="rule-long"><hr/></div> + +<!-- Navigation links --> +<table style="width: 100%; margin-top: 12px;"> +<tr> + <td style="width: 33%;"><a href="toc.html">Back to Table of Contents</a></td> + <td style="width: 20%; text-align: center;"><a href="#top">Top</a></td> + <td style="width: 46%; text-align: right;"><a href="headfootpage.html">Next: Page headers/footers, pagination</a></td> +</tr> +</table> + +</div> + +<div class="bottom-spacer"><br/></div> + +</body> +</html> |