+ + + + + + + +

+ +

Graphics, floats, and preprocessor support

+ +

Inserting images and graphics +
- Image conversion and file processing +
  - PDF
  - EPS
- The PDF_IMAGE macro +
  - PDF_IMAGE_FRAME—set parameters for image frames
- The PSPIC macro
Floats +
- The FLOAT macro
- Labelling and captioning floats +
  - LABEL
  - CAPTION
Preprocessor support +
- tbl +
  - .TS / .TH / .TE macros and arguments
- eqn +
  - .EQ / .EN macros and arguments
- pic +
  - .PS / .PE macros and arguments
  - PIC_TEXT_STYLE—set parameters for text in diagrams
- grap
- refer
Captions and labels +
- AUTOLABEL
- SET_AUTOLABEL
- CAPTION_AFTER_LABEL
- CAPTIONS / LABELS / SOURCES—set parameters for each
- MLA
Lists of Figures, Tables, and Equations +
- Placement of Lists
- Macros to generate Lists
- Formatting and style parameters for Lists +
  - LISTS_STYLE
Shaded backgrounds and frames (boxes) +
- Introduction and description
- The BOX macro
- Additional notes on box usage and behaviour +
  - QUOTE, BLOCKQUOTE, EPIGRAPH, FLOAT
  - CODE
  - Description of boxed BLOCKQUOTEs and EPIGRAPHs +
    - Leftover box syndrome
  - Slides
  - Footnotes
- Page colour
+

+ +

Inserting images and graphics

+ +

+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. +

+ +

+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. +

+ +

Image conversion and file processing

+ +

+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 convert, which is simple and effective. +

+ +

PDF

+ +

+Assuming a jpg image, conversion to PDF is done like this: +
+ + convert <image>.jpg <image>.pdf + +Any image type supported by convert may be converted this +way. +

+ +

+Mom files containing PDF images must be processed using +groff’s pdf driver. Use of +pdfmom +is strongly recommended, which natively invokes the pdf driver. +
+ + pdfmom doc.mom > doc.pdf + +

+ +

EPS

+ +

+Assuming a jpg image, conversion to EPS is done like this: +
+ + convert <image>.jpg <image>.eps + +Any image type supported by convert 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. +

+ +

+Mom files containing EPS images must be processed using +groff’s postscript driver. Use of +pdfmom, +which can be told to use the postscript driver, is strongly +recommended. +
+ + pdfmom -Tps doc.mom > doc.pdf + +

+ + + +

PDF_IMAGE

+ +

+Macro: PDF_IMAGE \ +
+[ -L | -C | -R | -I <indent> ] \ + +<pdf image file> <width> <height> [ SCALE <factor> ] \ + +[ ADJUST +|-<vertical adjustment> ] [ NO_SHIM ] [ NO_FLEX ] \ + +[ FRAME ] \ + +[ CAPTION "<caption>" ] [ SHORT_CAPTION "<short caption>" ] \ + +[ LABEL "<label>" ] [ TARGET "<name>" ] +

+• +<indent>, +<width>, +<height> +and + +<vertical adjustment> +require a +unit of measure +

+ +

+Note: +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 +(\), as shown above. +

+ +

+Unlike +PSPIC, +which it resembles, PDF_IMAGE requires that the pdf image’s +dimensions (the bounding box, +see below) +be supplied each time it’s called. +

+ +

+The first optional argument tells mom how to align the image +horizontally, with -L, -C, and -R +standing for left, centre and right respectively. If you need more +precise placement, the -I argument allows you to give an +indent from the left margin. Thus, to indent a PDF image 6 +picas +from the left margin +
+ + .PDF_IMAGE -I 6P <remaining arguments> + +If you omit the first argument, the image will be centred. +

+ +

+<pdf image> must be in PDF format, with a .pdf +extension. If it is not, mom will abort with a message. See +here +for instructions on converting image formats to PDF. +

+ +

+<width> and <height> are the +dimensions of the image’s bounding box. The most reliable way +of getting the bounding box is with the utility, pdfinfo: +
+ + pdfinfo <image.pdf> | grep "Page *size" + +This will spit out a line that looks like this: +
+ + Page size: width x height pts + +pts means +points, +therefore the unit of measure appended to <width> +and <height> must be p. +

+ +

+The remaining arguments are optional and may be entered in any +order, although it’s best to put CAPTION, +SHORT_CAPTION, and LABEL last. +

+ +

SCALE

+ +

+SCALE allows you to scale the image by +<factor>. The factor is a percentage of the +image’s original dimensions, thus SCALE 50 +scales the image to 50 percent of its original size. No percent +sign or unit of measure should be appended. +

+ +

ADJUST

+ +

+ADJUST lets you raise (-) or lower +(+) the image +within the space allotted for it +by the amount you specify. This is useful for achieving good +optical centering between surrounding blocks of type. A unit of +measure is required. +

+ +

+Tip: +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. +

+ +

+The solution is to introduce negative space before the image +so that it displays on the page, then lower it to the bottom margin +with PDF_IMAGE’s ADJUST argument. +

+ +

NO_SHIM

+ +

+NO_SHIM instructs mom not to apply +shimming +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 +baseline grid, +but can result in slightly unequal spacing above and below +(correctable with the ADJUST argument). +NO_SHIM 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 +NO_SHIM argument. +

+ +

NO_FLEX

+ +

+NO_FLEX instructs mom not to apply +flex-spacing +after an image, which she will do automatically when flex-spacing is +enabled. NO_FLEX 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 NO_FLEX argument. +

+ +

FRAME

+ +

+FRAME instructs mom to put a frame around the image. +Parameters for the frame are set with +PDF_IMAGE_FRAME. +

+ +

CAPTION

+ +

+CAPTION 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 +CAPTION_AFTER_LABEL +in +Captions and labels. +The text of the caption must be surrounded by double-quotes. +

+ +

SHORT_CAPTION

+ +

+SHORT_CAPTION 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. +

+ +

LABEL

+ +

+LABEL, 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 +AUTOLABEL), +which, if enabled, overrides the LABEL argument. +

+ +

TARGET

+ +

+TARGET 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 +Producing PDFs with groff and mom). +

+ +

+Please note: The following functionality is available +only with groff 1.22.4 or later. +

+ +

+When +autolabelling +is enabled and the document is processed with +pdfmom, +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 \*[name]. For example, if you create +a target named “foo” for a pdf image whose autolabel +number would be 3, entering +
+ + See + .PDF_LINK foo "Figure \*[foo]" + +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”. +

+ +

+Note: Version 2.0-c change +
+Mom now treats all pdf images identically to +floats, +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 +running text. +ADJUST 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. +

+ +

+Prior to 2.0-c, it was recommended that images be wrapped inside +FLOAT, +but this is now no longer required, and should, in fact, be avoided. +

+ + + +

PDF_IMAGE_FRAME

+ +

+Macro: PDF_IMAGE_FRAME <inset amount> <rule weight> <color> +

+• <inset amount> +requires a +unit of measure; +conversely, +<rule weight> +must not have a unit of measure appended +

+ +

+PDF_IMAGE_FRAME establishes the parameters for subsequent invocations of +PDF_IMAGE +when the FRAME 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, +
+ + .PDF_IMAGE_FRAME "" "" blue + +leaves the inset value and rule weight at their current value and +changes the frame colour to blue. +

+ +

+Frames are drawn outside the image at +its requested dimensions inclusive of scaling. Colours must be +pre-initialized with +XCOLOR +or +NEWCOLOR. +

+ +

+The default inset is 6 points, the default rule +weight is .5 (points), and the default colour is black. +

+ + + +

PSPIC

+ +

+Macro: PSPIC [ -L | -R | -I <n> ] <file> [ width [ height ] ] +

+ +

+PSPIC is not actually part of mom, but rather a macro included with +every groff installation. man groff_tmac contains the +documentation for PSPIC, but I’ll repeat it here with a few +modifications for clarity. +

+ +

From groff_tmac

+<file> is the name of the file containing the +image; width and height 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 +units of measure +attached; the default unit of measure is i. PSPIC will +scale the graphic uniformly in the x and y directions so that +it is no more than width wide and height +high. By default, the graphic will be horizontally centred. The +-L and -R options cause the graphic to be +left-aligned and right-aligned, respectively. The -I +option causes the graphic to be indented by <n>; +the default unit of measure is m +(ems). +

+ +

+It is not necessary to pass PSPIC the <width> +and <height> 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 +
+ + gs -q -dBATCH -dNOPAUSE -sDEVICE=bbox <image file>.pdf 2>&1 \ + | grep "%%BoundingBox" | cut -d " " -f4,5 + +The two digits returned are in +points, +therefore the +unit of measure +p must be appended to them. +

+ +

+Because PSPIC lacks the ADJUST option offered by +PDF_IMAGE +a certain amount of manual tweaking of the vertical placement of the +image will probably be required, typically by using the +ALD +and +RLD +macros. Wrapping the image in a +float +and using FLOAT’s ADJUST option can also be used to +correct optical centering. +

+ +

+Additionally, non-floated EPS images +will almost certainly disrupt the baseline placement of +running text. +In order to get mom back on track after inserting a non-floated +.PSPIC image, insert the +SHIM +or +FLEX +macro afterwards, depending on the +vertical whitespace management +strategy in effect, so that the bottom margin of running text falls +where it should. +

+ +

+Remember that mom files with embedded EPS images must be processed +with +
+ + pdfmom -Tps doc.mom > doc.pdf + +

+ +

+Please note: +PSPIC does not support +autolabelling, +labels, captions, or inclusion in the List of Figures. If you wish +this functionality, +convert your images to pdf +and use +PDF_IMAGE +instead, then process the file with +pdfmom +(without the -Tps option). +

+ +

Introduction to floats

+ +

+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 +running text. +

+ +

+Whenever you need this functionality, mom provides the FLOAT macro. +

+ +

+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. +

+ +

+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. +

+ +

+A key distinction between a float and a +QUOTE +or +BLOCKQUOTE +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. +

+ +

+Floats always begin in +no-fill mode. +Text entered immediately after FLOAT will be set line-for-line +unless a +JUSTIFY +or +QUAD L|R|C +precedes it. Alternatively, any macro that sets a quad direction +may be used, e.g. +PP. +

+ +

+Floats always deposit a break before they begin, which means the +line beforehand will not be +filled. +Floats, therefore, cannot be inserted in the middle of a paragraph +without studying the output file and determining where to break or +spread +the line before the float. Furthermore, if you want a float between +paragraphs, the float should come before .PP, like this: +
+ + .FLOAT + ... + .FLOAT OFF + .PP + +not +
+ + .PP + .FLOAT + ... + .FLOAT OFF + +

+ +

+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, +shimmed +or +flex-spaced, +depending on the +vertical whitespace management +strategy in effect. This behaviour can be disabled for individual +floats with NO_SHIM or NO_FLEX. +

+ +

+If you’d like more space around a float, you must add it +manually, for example with +ALD +or +SPACE. +

+ + + +

FLOAT

+ +

+Macro: FLOAT <arguments> | <anything> + +Arguments: + +[ ADJUST +|-<amount> ] \ + +[ FORCE ] \ + +[ SPAN ] \ + +[ INDENT <value> ] \ + +[ CENTER ] \ + +[ RIGHT ] \ + +[ NO_SHIM] \ + +[ NO_FLEX ] \ + +[ TARGET "<name>" ] +
+

+ +

+Note: +FLOAT is intended for use with the document processing macros only. +

+ +

+Note: +As a general rule, avoid consecutive floats that have no intervening +running text. +Rather, wrap all the material into a single float. +

+ +

+Note: +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. +

+ +

+Note: +Mom treats pic 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. +

+ +

+To begin a float, simply invoke .FLOAT and follow it with +whatever you want the float to contain. When you’re done, +invoke .FLOAT OFF (or OFF, +QUIT, END, X, etc). +

+ +

ADJUST

+ +

+The optional ADJUST argument tells mom to raise +(+) or lower (-) the float within +the space allotted to it by the specified amount. +<amount> must have a +unit of measure +appended. ADJUST gives you precise control over +the vertical centering of floats, allowing you to compensate for +unequal spacing that may result from the automatic +shimming +or +flex-spacing +floats. +

+ +

+ADJUST is ignored for the first float deferred to +a following page but respected for subsequent deferred floats +output immediately afterwards. +

+ +

FORCE

+ +

+The FORCE argument instructs mom to output the float +exactly where it occurs in the input file. With FORCE, +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. +

+ +

+If you need to force a page break after completion of a float that +has been deferred to a subsequent page, insert \!.bp +immediately before terminating the float. +

+ +

SPAN

+ +

+The SPAN argument tells mom that a float, if deferred, +may carry onto multiple pages. Please note that SPAN 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 SPAN argument. +

+ +

INDENT

+ +

+INDENT allows you to indent a float from the left margin +by a specified value. The value must have a +(unit of measure +appended to it. +

+ +

CENTER

+ +

+CENTER instructs mom to center a float if it is not +already centered by default. +

+ +

RIGHT

+ +

+RIGHT 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. +

+ +

NO_SHIM

+ +

+NO_SHIM instructs mom not to apply +shimming +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 +baseline grid, +but can result in slightly unequal spacing above and below +(correctable with the ADJUST argument). +NO_SHIM 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 +NO_SHIM argument. +

+ +

NO_FLEX

+ +

+NO_FLEX instructs mom not to apply +flex-spacing +after a float, which she will do automatically when flex-spacing is +enabled. NO_FLEX 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 NO_FLEX argument. +

+ +

TARGET

+ +

+TARGET 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 +Producing PDFs with groff and mom). +

+ +

+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 +LABEL. +See +Reserved variables for +labels. +

+ + +

+Note: +Floats use +no-fill mode, +with each input line beginning at the left margin. If this is not +what you want, you must specify the preferred horizontal alignment +within the float (e.g. +CENTER +or +RIGHT). +

+ +

+Furthermore, if you want text +filled, +you must specify +.QUAD L|R|C +or +.JUSTIFY—again, +within the float. +

+ +

Labelling and captioning floats

+ +

+Labelling and captioning of tables (tbl), equations +(eq), diagrams (pic) and pdf images +(PDF_IMAGE) +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. +

+ +

+Important: +Always use the native labelling/captioning facilities for +preprocessor output and pdf images rather than labelling the +containing float, if any. +

+ +

+The macros to label and caption floats are +LABEL +and +CAPTION. +If a label or caption is to appear above the float, the appropriate +macro is entered immediately after +FLOAT. +If a label or caption is to appear beneath the float, the appropriate +macro is entered immediately before ending the float with +FLOAT OFF. +

+ +

+If a label and caption are to be joined, the LABEL macro is +used to enter both by passing the CAPTION argument to +LABEL. +

+ +

+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 +symbolically, +easing the burden of keeping the numbering scheme intact as +labelled floats are added to or subtracted from a document. +

+ +

+Tip: +QUOTE +and +BLOCKQUOTE +may also be labelled and captioned using LABEL and +CAPTION. +

+ +

Spacing

+ +

+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 +shimming +or +flex-spacing, +depending on the +vertical whitespace management +in effect. +

+ +

+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 plus shimming or +flex-spacing. +

+ +

+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. +

+ +

LABEL

+ +

+Macro: LABEL +"<label>" [ CAPTION "<caption>" ] [ SHORT_CAPTION ] \ + +[ TO_LIST FIGURES | TABLES | EQUATIONS ] +

+ +

+The placement of a float’s label depends on where you put it +inside the float. +

+ +

+If you want a label at the top, put LABEL immediately +underneath +FLOAT +and follow it with the text of the label surrounded by double-quotes: +
+ + .FLOAT + .LABEL "Fig. 1" + +If you want a label at the bottom, put LABEL immediately +before ending the float: +
+ + .FLOAT + <contents of float> + .LABEL "Fig. 1" + .FLOAT OFF + +

+ +

Reserved variables for labels

+ +

+Mom reserves strings you may use when entering +label text after the LABEL argument. +\*[chapter] holds the current chapter +or major section number. \*[fig-label], +\*[tbl-label], and +\*[eqn-label] increment the label number of +the appropriate label type by one, and are initially set to zero +after each invocation of +START +when the +DOCTYPE +is CHAPTER. Thus, in every chapter requiring numbered +float labels, you can enter +
+ + .LABEL "Fig. \*[chapter].\*[fig-label]. TO_LIST FIGURES + +which, assuming the third autolabelled float of Chapter 2, will +produce Fig. 2.3. +

+ +

+If your DOCTYPE is DEFAULT or NAMED, +you must reset \*[<type>-label] after +each +COLLATE +by entering +
+ + .AUTOLABEL_<list type> + +before .START. +

+ +

+If +autolabelling +is enabled, e.g. .AUTOLABEL_IMAGES (List +of Figures) or .AUTOLABEL_PIC (also List of Figures), +the prefix is stripped from the label when it appears in +the List. Thus, if you have invoked .AUTOLABEL_PIC, +
+ + .LABEL "Fig. 1.1." + CAPTION "Caption for label \ + TO_LIST FIGURES + +or +
+ + .LABEL "Fig. \*[chapter].\*[label]." \ + CAPTION "Caption for label \ + TO_LIST FIGURES + +will appear in the List of Figures as “1.1. Caption for +label”. +

+ +

CAPTION

+ +

+If you’d like a caption attached to the label, pass +LABEL the optional argument CAPTION followed +by the text of the caption as a single string surrounded by +double-quotes: +
+ + .FLOAT + <contents of float> + .LABEL "Fig. 1" CAPTION "Caption for Fig. 1" + .FLOAT OFF + +Note that the +CAPTION +macro by itself permits entering several strings, each output on +a line by itself, whereas the CAPTION argument to +LABEL accepts only a single string. +

+ +

SHORT_CAPTION

+ +

+If your caption runs long and you’re including the +float in a “List of ...”, (see +TO_LIST, below) +SHORT_CAPTION tells +mom how you’d like the caption to appear in the List. +

+ +

TO_LIST

+ +

+The optional argument TO_LIST tells mom to add the +float’s label and attached caption, if present, to the specified +list, +which may be one of FIGURES, TABLES, or +EQUATIONS. +

+ +

+If, for some reason, you want only the caption appended to the List, +give \& as the first argument to LABEL, followed by +CAPTION “caption”: +
+ + .LABEL \& \ + CAPTION "caption" + +

+ +

+Tip: +TO_LIST can be used to handle situations where labelled +floats need to go to a uniquely named “List of ...”. +

+ +

+Suppose, for example, your document contains figures (e.g. +pic 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 +LIST_OF_EQUATIONS +to “List of Examples”, you may include the float in your +List of Examples with +
+ + .TO_FIGURES EQUATIONS + +

+ +

CAPTION

+ +

+Macro: CAPTION +"<caption>" \ + +[ "<additional line>" [ "<additional line>"... ] ] \ + +[ TO_LIST FIGURES | TABLES | EQUATIONS ] +

+ +

+The placement of a float’s caption depends on where you put it +inside the float. +

+ +

+If you want a caption at the top, put CAPTION immediately +underneath +FLOAT +and follow it with the text of the caption surrounded by double-quotes: +
+ + .FLOAT + .CAPTION "Caption at top of float" + +CAPTION 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: +
+ + .FLOAT + .CAPTION "Caption" ".BR" "at top" ".BR" "of float" + +or, easier to read: +
+ + .FLOAT + .CAPTION "Caption" \ + ".BR" \ + "at top" \ + ".BR" \ + "of float" + +If you want a caption at the bottom, put CAPTION immediately +before ending the float: +
+ + .FLOAT + <contents of float> + .CAPTION "Caption at bottom of float" + .FLOAT OFF + +

+ +

+Note: +If you want a caption attached to a label, do not use +CAPTION by itself. Rather, invoke +.LABEL +with the CAPTION argument. +

+ +

Preprocessor support

+ +

+Mom offers full support for the eqn (equations), pic +(diagrams), grap (graphs), tbl (tables) and +refer (bibliographies/citations) preprocessors, including +captions, labelling, autolabelling, and inclusion in the Lists of +Equations, Figures, and Tables. +

+ +

+Other than refer, which is discussed at length in the Bibliographies and references section, it is +beyond the scope of this documentation to cover full preprocessor +usage. Consult the manpages eqn(1), pic(1), +grap(1) and tbl(1) for instructions. +

+ +

+Version 2.0-c changes +
+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. +

+ +

tbl support

+ +

+Mom documents can include tables generated with the groff +preprocessor tbl. If you are unfamiliar with tbl, I +recommend downloading a copy of +Tbl - A Program to Format Tables, +which, in addition to providing a thorough introduction, contains +some fine examples. If you use tbl, you must pass groff or +pdfmom the -t flag when you process the file. +

+ +

+Tables formatted with tbl begin with the macro +.TS (Table Start) and end with +.TE (Table End). Depending on where you +want your tables output in a document, you may need to wrap +your tbl code inside a +float, +or pass the H argument to .TS. +

+ +

+If you put tbl 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 +H argument to .TS, along with a corresponding +TH +and do not wrap the table inside a float. +

+ +

+Note: +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 tbl preprocessor itself, not groff or +mom. Unboxed tables that span several pages, however, are +acceptable within FLOAT. +

+ +

tbl placement in mom docs

+ +

+If you use .TS without the H argument (and +therefore no .TH), tables that fit on the page are output +in position. If there is not enough room to output the table, +tbl will abort with message instructing you to use +.TS H/.TH. Given that .TS without H +may sometimes fail, it is advisable to begin all tbl blocks +with .TS H. +

+ +

+If you give .TS the H argument (with a +corresponding .TH), 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 +running text. +

+ +

+Boxed tables inside +floats +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. +

+ +

+Unboxed tables inside floats may span multiple pages provided the +SPAN argument has been given to +FLOAT. +

+ +

+Note: +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 +shimming +or +flex-spacing +that mom applies automatically after each table, depending on which +vertical whitespace management +is in effect. You may +disable shimming or flex-spacing with +NO_SHIM +or +NO_FLEX, +or by passing the NO_SHIM or NO_FLEX argument +to .TS. In either case, you will still likely want to +adjust the spacing around with table with the ADJUST +argument to .TS. Tables inside floats should be adjusted +with the ADJUST argument to +FLOAT, +not the ADJUST argument to .TS. +

+ +

.TS / .TH / .TE

+ +

+Macro: TS ++Arguments: + + [ H ] + + [ BOXED ] + + [ CENTER ] + + [ NEEDS ] + + [ ADJUST +|-<vertical adjustment>] + +(unit of measure +required) + ++ [ NO_SHIM ] + + [ NO_FLEX ] + + [ CAPTION "<caption>" ] + + [ SHORT_CAPTION "<short caption>" ] + + [ LABEL "<label>" ] + + [ TARGET "<name>" ] + +
+Macro: TH (optional, only if .TS H) +
+Macro: TE [ SOURCE "<text of table source>" ] +

+ +

+Tables to be formatted with tbl begin with the macro +.TS and end with .TE. Global tbl +options (“flags”), formatting, and data (per +tbl(1)) come between the two macros. +
+ + .TS + <tbl options, formatting, and data> + .TE + +Tables may be wrapped inside a +float, +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. +
+ + .FLOAT + .TS + <tbl options, formatting, and data> + .TE + .FLOAT OFF + +

+ +

The .TS macro

+ +

+Note: Version 2.0-c change +
+2.0-c introduces revisions to the handling of labels and/or +captions, which, along with NO_SHIM, must now be given +as arguments to .TS rather than .TE, as was +the case formerly. Please read this section carefully if you have +documents containing tables as they may need to be updated. +

+ +

+IMPORTANT: +All arguments to TS must appear on the same line as +.TS. 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. +

+ +

+The TS macro must be invoked before entering a tbl +block. You may give as many or as few of its arguments as required, +in any order, although it is advisable to put CAPTION, +SHORT_CAPTION, and/or LABEL last. +

+ +

H

+ +

+With the H argument, a table will span as many pages as +necessary, with or without a running header. The placement of the +corresponding +.TH, +which is required whenever the H argument is given, +determines what, if anything, goes in the header. Compare the +following: + + .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 + +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 +TH +for an explanation of .TH placement. +

+ +

+Tip: +Generally speaking, it’s a good idea to get into the habit +of using .TS H all the time, since there are no +circumstances under which it fails, whereas .TS without +H will fail on tables that exceed the page length. +

+ +

BOXED

+ +

+If a table is to be boxed (i.e., tbl is given the flags +'box' or 'allbox') you must pass the argument +BOXED to .TS, as in this example: +
+ + .TS BOXED + allbox; + c s s + c c c + n n n. + <tbl data> + .TE + +

+ +

CENTER

+ +

+If a table is to be centered on the page, (i.e., tbl is +given the 'center' flag), you must pass the argument +CENTER to .TS, as in this example, which +creates a (possibly) multipage boxed table, centered on the page, +with a running header. + + .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 + +

+ +

NEEDS

+ +

+If a table is not inside a float and you pass .TS the +H argument (which you should; see the tip +here), +mom begins output immediately where the table occurs in the +input file if there is enough room on the output page for the +table header plus at least one row of table data. If there +isn’t enough room, mom breaks to a new page before beginning +the table, leaving a gap in +running text +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 NEEDS argument, followed by the desired +number of rows. +

+ +

ADJUST

+ +

+ADJUST lets you raise (-) or lower +(+) the table +within the space allotted for it +by the amount you specify. This is useful for achieving good +optical centering between surrounding blocks of type. A unit of +measure is required. +

+ +

NO_SHIM

+ +

+NO_SHIM instructs mom not to apply +shimming +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 +baseline grid, +but can result in slightly unequal spacing above and below +(correctable with the ADJUST argument). +NO_SHIM 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 +NO_SHIM argument. +

+ +

NO_FLEX

+ +

+NO_FLEX instructs mom not to apply +flex-spacing +after a table, which she will do automatically when flex-spacing is +enabled. NO_FLEX 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 NO_FLEX argument. +

+ +

CAPTION

+ +

+CAPTION 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 +CAPTION_AFTER_LABEL +in +Captions and labels. +The text of the caption must be surrounded by double-quotes. +

+ +

+Please note that if your table has a caption, you must invoke +TS with the H flag, which also entails the use +of +TH. +

+ +

SHORT_CAPTION

+ +

+SHORT_CAPTION 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. +

+ +

LABEL

+ +

+LABEL, 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 +AUTOLABEL), +which, if enabled, overrides the LABEL argument. +

+ +

TARGET

+ +

+TARGET 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 +Producing PDFs with groff and mom). +

+ +

+Please note: The following functionality is available +only with groff 1.22.4 or later. +

+ +

+When +autolabelling +is enabled and the document is processed with +pdfmom, +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 \*[name]. For example, if you +create a target called “foo” for a table whose autolabel +number would be 3, entering +
+ + See + .PDF_LINK foo "Table \*[foo]" + +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”. +

+ +

The .TH macro

+ +

+The TH macro (Table Header), which is required +when you begin a table with .TS H, allows you to +determine what goes in a table’s running header if it spans +multiple pages. Placing .TH under the first row of +tbl data makes the first row the header. If placed under +the second row, the first and second rows form the header, and so +on. +

+ +

+As there are sometimes reasons to run .TS H when +you don’t, in fact, want a running header (e.g. when +your table has a caption), you can suppress it by placing +.TH immediately underneath your tbl formatting +specifications, the last line of which always ends with a period +(see tbl(1)). +

+ +

+See the +H +argument to .TS for examples demonstrating .TH +placement. +

+ +

The .TE macro

+ +

+tbl blocks must be terminated with .TE, +which, as of version 2.0-c, takes a single, optional argument, +SOURCE. (Formerly, TE 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 +MLA +(Modern Language Association) style is enabled. +

+ +

pic support

+ +

+Mom documents can include diagrams generated with the groff +preprocessor pic. If you are unfamiliar with pic, I +recommend downloading a copy of +Making Pictures with GNU PIC +which provides a thorough introduction and contains many examples. +If you use pic, you must pass groff or pdfmom the -p +flag when you process the file. + +

+ +

+Diagrams created with pic begin with the macro +.PS (Pic Start) and end with +.PE (Pic End). Everything between them is +interpreted by the preprocessor as pic instructions. Please note: +Making Pictures with GNU PIC says that .PF can +also be used to terminate a pic diagram, but this is not supported +by mom. +

+ +

+Pic diagrams are always centered. Note that this represents a +change from version 2.0-b of mom, where centering diagrams required +passing -mpic to groff or +pdfmom +on the command line. +

+ +

+In addition, mom treats pic diagrams identically to +floats, +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 +running text. +ADJUST 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. +

+ +

+Lastly, if your diagrams contain text, you may set all the type +parameters for the text (family, font, size, leading) separately +from the pic block with the macro +PIC_TEXT_STYLE. +If you need to change the type parameters within the block +on-the-fly, you must use pic’s native facilities for +doing so. +

+ +

.PS / .PE

+ +

+Macro: PS ++ +Arguments: [ <width> <height> ] + + + [ LEFT ] + + [ ADJUST +|-<vertical adjustment>] + +(unit of measure +required) + ++ [ NO_SHIM ] + + [ NO_FLEX ] + + [ CAPTION "<caption>" ] + + [ SHORT_CAPTION "<short caption>" ] + + [ LABEL "<label>" ] + + [ TARGET "<name>" ] + +
+Macro: PE (no arguments; ends +the pic block) +

+ +

+IMPORTANT: +All arguments to PS must appear on the same line as +.PS. 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. +

+ +

'width' and 'height'

+ +

+The width and height arguments to +.PS are idiosyncratic owing to the preprocessor itself. +Both are optional and both expect a value in inches, so neither +argument should have a +(unit of measure +appended. +

+ +

+If the width argument is supplied, the diagram, but +not any text it contains, is scaled to the given width. If a +literal width argument of 0 (zero) is given and a +height 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. +

+ +

LEFT

+ +

+By default, pic diagrams are centred on the page. If you would +prefer them to be flush left, pass PS the LEFT +argument. +

ADJUST

+ +

+ADJUST lets you raise (-) or lower +(+) a diagram +within the space allotted for it +by the amount you specify. This is useful for achieving good +optical centering between surrounding blocks of type. A unit of +measure is required. +

+ +

NO_SHIM

+ +

+NO_SHIM instructs mom not to apply +shimming +after a pic 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 +baseline grid, +but can result in slightly unequal spacing above and below +(correctable with the ADJUST argument). +NO_SHIM 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 +NO_SHIM argument. +

+ +

NO_FLEX

+ +

+NO_FLEX instructs mom not to apply +flex-spacing +after a pic diagram, which she will do automatically when +flex-spacing is enabled. NO_FLEX 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 NO_FLEX argument. +

+ +

CAPTION

+ +

+CAPTION 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 +CAPTION_AFTER_LABEL +in +Captions and labels. +The text of the caption must be surrounded by double-quotes. +

+ +

SHORT_CAPTION

+ +

+SHORT_CAPTION 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. +

+ +

LABEL

+ +

+LABEL, 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 +AUTOLABEL), +which, if enabled, overrides the LABEL argument. +

+ +

TARGET

+ +

+TARGET 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 +Producing PDFs with groff and mom). +

+ +

+Please note: The following functionality is available +only with groff 1.22.4 or later. +

+ +

+When +autolabelling +is enabled and the document is processed with +pdfmom, +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 \*[name]. For example, if you +create a target called “foo” for a diagram whose +autolabel number would be 3, entering +
+ + See + .PDF_LINK foo "Figure \*[foo]" + +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”. +

+ + + +

PIC_TEXT_STYLE

+ +

+Macro: PIC_TEXT_STYLE \ +
++ [ FAMILY ] "<family>" \ + + [ FONT ] "" \ + + [ SIZE ] "+|-<size>" \ + + [ AUTOLEAD ] "<value>" + +

+ +

+Diagrams drawn with pic may contain text, and groff +inline escapes +may be used to alter the text parameters. A problem that arises +from so doing is that, in many cases, it clutters up the pic +code unnecessarily. +

+ +

+PIC_TEXT_STYLE lets you establish the type parameters for text +inside a pic block all at once in cases where so doing +improves the readability of your mom source files. +

+ +

+The arguments to PIC_TEXT_STYLE behave identically to the arguments +to other control macros, explained +here. +They may be given in any order, and you may use as many or as few as +you like. +

+ +

+Note: +Text within pic diagrams does not scale when you provide a +scaling argument to .PS. This is a limitation of the +preprocessor itself, not groff or mom. +

+ +

grap support

+ +

+Grap is a pic preprocessor for creating graphs. Grap +usage is covered in the grap(1) manpage. Its mom +implementation is the same as for pic except that instead of +enclosing directives between +.PS / .PE, +they are enclosed between .G1/.G2. If you use grap, +you must pass groff or pdfmom the -G flag when you process +the file. + +

+ +

+.G1 takes all the same arguments as +PS +with one exception: the argument GRAP must always be given to +.G1. So, for example, a skeleton grap block raised 2 points +and with a caption would be entered: +
+ + .G1 GRAP ADJUST +2p CAPTION "Graph caption" + <grap directives> + .G2 + + +

+ +

eqn support

+ +

+Support for eqn is provided via extensions to the standard +.EQ/.EN macros. eqn usage itself is beyond +the scope of this documentation, but is covered in the manpage +eqn(1). You can also download a copy of Ted +Harding’s + +A Guide to Typesetting Mathematics Using GNU eqn +, +which contains useful examples. If you use eqn, you must give groff or +pdfmom the -e flag. + +

+ +

.EQ / .EN

+ +

+Macro: EQ +
+Arguments: + + [ -L | -C | -I <indent> ] + +(unit of measure +required) + ++ [ ADJUST +|-<vertical adjustment>] + +(unit of measure +required) + ++ [ NO_SHIM ] + + [ NO_FLEX ] + + [ CAPTION "<caption>" ] + + [ LABEL "<label>" ] + + [ SHIFT_LABEL +|-<vertical adjustment> ] + + [ SHORT_CAPTION "<short caption>" ] + + [ TARGET "<name>" ] + + [ CONTINUED | CONT | ... ] +

+ +

+Note: Version 2.0-c change +
+2.0-c introduces revisions to EQ, including the addition +of a dash (-) to the positioning arguments +(-L, -C, and -I) and the removal of a +default value for -I. Other changes include passing all +options to .EQ (including the label) such that +.EN takes only a single, optional argument saying whether +the equation is to be continued at the next invocation of +.EQ. Please read this section carefully if you have +documents containing equations as they may need to be updated. +

+ +

+IMPORTANT: +All arguments to EQ must appear on the same line as +.EQ. 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. +

+ +

The .EQ macro

+ +

+Equations to be set with eqn begin with .EQ, +followed by eqn code. Equations are centered by default, +but may be set flush left or indented from the left margin +if -L or -I are passed as arguments to +.EQ. +

+ +

ADJUST

+ +

+ADJUST lets you raise (-) or lower +(+) an equation +within the space allotted for it +by the amount you specify. This is useful for achieving good +optical centering between surrounding blocks of type. A unit of +measure is required. +

+ +

NO_SHIM

+ +

+NO_SHIM instructs mom not to apply +shimming +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 +baseline grid, +but can result in slightly unequal spacing above and +below (correctable with the ADJUST argument). +NO_SHIM 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 +NO_SHIM argument. +

+ +

NO_FLEX

+ +

+NO_FLEX instructs mom not to apply +flex-spacing +after an equation, which she will do automatically when flex-spacing +is enabled. NO_FLEX 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 NO_FLEX argument. +

+ +

CAPTION

+ +

+CAPTION allows you to give the equation a caption. +Equation captions always appear beneath the equation. +

+ +

SHORT_CAPTION

+ +

+SHORT_CAPTION 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. +

+ +

LABEL

+ +

+LABEL, 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 +AUTOLABEL), +which, if enabled, overrides the LABEL argument. +

+ +

SHIFT_LABEL

+ +

+SHIFT_LABEL allows you to raise (-) or lower +(+) 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, +.EQ SHIFT_LABEL -1v would raise the label by +one line, thus centering it vertically on the equation. +

+ +

TARGET

+ +

+TARGET 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 +Producing PDFs with groff and mom). +

+ +

+Please note: The following functionality is available +only with groff 1.22.4 or later. +

+ +

+When +autolabelling +is enabled and the document is processed with +pdfmom, +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 \*[name]. For example, if you +create a target called “foo” for an equation whose +autolabel number would be 3, entering +
+ + See + .PDF_LINK foo "Equation \*[foo]" + +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”. +

+ + +

The .EN macro

+ +

+A block of eqn code is terminated with .EN. +

+ +

+If an equation needs to span multiple lines, possibly aligned +with eqn’s 'mark' and 'lineup' +directives, separate invocations of .EQ/.EN +are required for each line, and the optional argument, +CONTINUED (or CONT, or ... [three +dots, an ellipsis]), must be passed to .EN. +

+ +

+If -L or -I is given to the first +.EQ of a multi-line equation, they remain in effect +until an .EN without the CONTINUED argument +is reached. +

+ +

+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 .EQ/.EN, inside +a +float. +

+ +

refer support

+ +

+refer support is covered in the section +Bibliographies and references. +

+ +

Captions and labels

+ +

AUTOLABEL
CAPTION_AFTER_LABEL
MLA—MLA-style captioning and labelling
Set style parameters for captions, labels, and sources

+ +

+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. +

+ +

+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. +

+ +

+By default, mom sets captions above figures (i.e. pic output and +pdf images) and tables. This behaviour may be modified with the +macro +CAPTION_AFTER_LABEL. +Equations always have their captions set underneath. All aspects of +the text style for captions may be set with the macro +CAPTIONS. +

+ +

+Labels for tables are set underneath the table unless the +MLA +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 +LABELS. +Furthermore, mom can autolabel figures, tables, and equations, with +or without a prefixed chapter number. +

+ +

Autolabel

+ +

+Macro: AUTOLABEL_EQUATIONS +
+Macro: AUTOLABEL_IMAGES +
+Macro: AUTOLABEL_PIC +
+Macro: AUTOLABEL_TABLES +
+Arguments: + +[ PREFIX "<string>"] [ SUFFIX "<string>"] [ PREFIX_CHAPTER [ <n> ] ] + +

+ +

+AUTOLABEL_<type> 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. +

+ +

+Autolabelling may be disabled on-the-fly by giving any argument +other than PREFIX, SUFFIX, or +PREFIX_CHAPTER to the appropriate macro. For example, +
+ + .AUTOLABEL_IMAGES NO + +would disable autolabelling of images. +

+ +

Prefixes and suffixes

+ +

+By default, when AUTOLABEL 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 +pic diagrams and pdf images as “Fig. <n>”, +and for equations as “Eq. (<n>)”. +

+ +

+You can use PREFIX <"string"> 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: +
+ + .AUTOLABEL_IMAGES \ + PREFIX "Ex. " \ + SUFFIX "" + +If you need a suffix after the automatic numbering, use +SUFFIX <"string">, like this: +
+ + .AUTOLABEL_IMAGES \ + PREFIX "(Fig. " \ + SUFFIX ")" + +Note from the above that both arguments, PREFIX and +SUFFIX, are required should you want either. Two +adjacent double-quotes leaves the string blank. +

+ +

+Note: +In automatically formatted +“Lists of ...”, +label number prefixes are stripped when autolabelling is enabled. +

+ +

Prefixing chapter numbers

+ +

+If you would like mom to prefix chapter numbers to the label, +pass AUTOLABEL_<type> the argument +PREFIX_CHAPTER. +

+ +

+If for some reason you need to specify the chapter number, +you may do so by passing the number as an argument to +PREFIX_CHAPTER. Subsequent chapters or major sections +will increment by one as expected. +

+ +

+Note: +For the purposes of labelling, mom treats +DOCTYPE DEFAULT +as if it were DOCTYPE CHAPTER, hence, with +PREFIX_CHAPTER, each collated DEFAULT +doctype’s prefixed “chapter” number is +incremented and the label number itself reset to “1”. +If you do not supply the PREFIX_CHAPTER argument, the +label number is not reset automatically. To reset it, invoke +.AUTOLABEL_<type> after each +COLLATE. +

+ +

+Macro: SET_AUTOLABEL FIG | TBL | PIC | EQN <n> +

+ +

+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 +FLOAT +in conjunction with the TO_LIST argument. +

+ +

+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 +TO_LIST FIGURES. +

+ +

+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. +
+ + .SET_AUTOLABEL FIG 6 + +means the next autolabelled Figure will be “Fig. 6.” +

+ +

Captions after labels

+ +

+Macro: CAPTION_AFTER_LABEL IMG | PIC | TBL | ALL [ <anything> ] +

+ +

+By default, mom sets captions above figures (pic output +and pdf images) and tables; labels are always underneath. +

+ +

+.CAPTION_AFTER_LABEL, 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, +
+ + .CAPTION_AFTER_LABEL ALL + +would enable captions after labels globally, while a subsequent +
+ + .CAPTION_AFTER_LABEL IMG OFF + +would disable captions after labels for pdf images only. +OFF can be anything you like (X, +NO, etc). +

+ +

+If +MLA +is enabled, there’s no need to invoke +CAPTION_AFTER_LABEL as this is implied. +

+ +

+Note: +A separate invocation of .CAPTION_AFTER_LABEL is required +for each one of the required first arguments. You cannot, for +example, do +
+ + .CAPTION_AFTER_LABEL IMG TBL + +Rather, you must do +
+ + .CAPTION_AFTER_LABEL IMG + .CAPTION_AFTER_LABEL TBL + +

+ +

MLA-style captioning and labelling

+ +

+Macro: MLA [ <anything> ] +

+ +

+Modern Language Association style dictates that captions should +always go after labels. Furthermore, labels and captions for tables +should go above the tables, with the source for the table, if +any, underneath. +

+ +

+Invoking .MLA by itself takes care of these details. If +you need to disable MLA-style captioning and labelling mid-document, +.MLA OFF does the trick. OFF can be +anything you like (X, NO, etc). +

+ +

Style parameters for captions, labels and sources

+ +

+ +

+Note: +Arguments may be broken into several lines using the +“line-continued” backslash (\), as shown above. +

+ +

+Additional note: +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.) +

+ +

+With the exception of ADJUST and QUAD (which +requires a bit of explanation), the style arguments to CAPTIONS, +LABELS, and SOURCES (which is only available +for tables) behave identically to the +arguments to control macros. +

+ +

+The first, required argument after CAPTIONS, +LABELS, or SOURCES indicates the preprocessor +type for which you are setting the parameters. (For convenience +PDF_IMAGE—argument IMG—is here treated as a +preprocessor.) FLOATING sets the style for the macros +CAPTION +and +LABEL, +which are used to label floats, quotes, and blockquotes. +

+ +

+An argument of ALL sets a unified style for all +preprocessors, floats, quotes, and blockquotes. If the +ALL argument is given, arguments to subsequent +invocations of CAPTIONS, LABELS, or +SOURCES overwrite only the explicitly named style +parameters. +

+ +

QUAD — quadding of labels, captions, and sources

+ +

• pic, tbl, pdf images

+ +

+By default, figures (pic 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. +

+ +

+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 ON_LL argument to +QUAD <direction>, in which case +the prevailing document line length is used instead. +

+ +

• eqn

+ +

+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 QUAD. If +the equation is indented with the +-I <indent> option, a quad +direction of LEFT is observed, but may overprint the last +line of the equation. +

+ +

+Note that there is no CENTER option for equation labels, +and that captions are always quadded over the prevailing document +line length. +

+ +

• quotes and blockquotes

+ +

+Floating labels attached to QUOTEs are quadded on the +prevailing document line length, and require the INDENT +argument if you want to align them with the left and/or right edges +the quote. +

+ +

+Floating labels attached to BLOCKQUOTEs are always quadded on +the indent and line length of the blockquote. +

+ +

• floats

+ +

+Floating labels and captions attached to FLOATs are always +quadded over the prevailing document line length, and require the +INDENT argument if you want to align them with the left +and/or right edges of the float’s contents. +

+ +

INDENT

+ +

+The INDENT argument may only be used if the label +or caption type is FLOATING, and only applies to +FLOATs and QUOTEs, not BLOCKQUOTEs. +

+ +

+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 CENTER, +you may want to adjust the horizontal positioning when the quad is +LEFT or RIGHT. +

+ +

+INDENT, with a numeric value to which a +unit of measure +is appended, allows you to indent a floating label or caption so +it lines up with the left edge of a FLOAT or QUOTE. +INDENT RIGHT (with a value) allows you to shorten the +line length to the appropriate width. If you need both a left and +right indent, invoke LABELS or CAPTIONS twice, +one instance containing INDENT <indent> and +the other INDENT RIGHT <indent>. +

+ +

ADJUST

+ +

+The ADJUST argument allows you to add(+) or +subtract (-) vertical space between labels and captions +and the output to which they are attached. The argument requires a +unit of measure. +For example, if you find that table labels are a bit too close to +the table itself, +
+ + .LABELS TBL ADJUST +3p + +would put three extra points of space between the bottoms of tables +and the labels that appear beneath them. +

+ +

Lists of Figures, Tables, and Equations

+ +

+Besides a +Table of Contents, +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 +
+ + .LIST_OF_FIGURES + .LIST_OF_EQUATIONS + .LIST_OF_TABLES + +to the end of your input file. +

+ +

+Also like the Table of Contents, entries in the Lists’ output +are clickable PDF links when a document is viewed at the screen. +

+ +

Placement of Lists

+ +

+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”. +

+ +

+If you are using mom’s +AUTO_RELOCATE_TOC +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 after +.TOC. +If you prefer to have the Lists at the end of the document, invoke +the Lists macros before .TOC. +

+ +

+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. +

+ +

Macros to generate Lists

+ +

+Macro: LIST_OF_EQUATIONS +
+Macro: LIST_OF_FIGURES +
+Macro: LIST_OF_TABLES +
+Arguments: + + [ TITLE_STRING "<string>" ] [ START_PAGENUM <page number> ] + +

+ +

+The first optional argument to the LIST_OF_<type> +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), +
+ + LIST_OF_FIGURES TITLE_STRING "List of Examples" + +ensures that the title of the List is correct. +

+ +

+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. +

Formatting and style parameters for Lists

+ +

+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. +

+ +

+If you wish to make changes to any aspect of Lists formatting +or styling, the macro LISTS_STYLE 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 LISTS_STYLE applies to all Lists. In the event that +you do need to change some aspect of the formatting for different +list types, simply invoke LISTS_STYLE immediately prior +to each list whose formatting needs to be changed. +

+ +

Lists style

+ +

+Macro: LISTS_STYLE + +Arguments: + + FAMILY <family> \ + + FONT \ + + PT_SIZE <size> \ + + LEAD <leading> \ + + TITLE_FAMILY <family> \ + + TITLE_FONT \ + + TITLE_SIZE +|-<size> \ + + TITLE_QUAD LEFT | CENTER | RIGHT \ + + TOC_HEADER_UNDERSCORE default = none + + TITLE_COLOR <color> \ + + PN_FAMILY <family> \ + + PN_FONT \ + + PN_SIZE +|-<size> \ + + EQN_PN_PADDING <placeholders> \ + + FIG_PN_PADDING <placeholders> \ + + TBL_PN_PADDING <placeholders> \ + + PAGENUM_STYLE DIGIT | ROMAN | roman | ALPHA | alpha \ + + NO_PAGINATION + +

+ +

+Note: +Arguments may be broken into several lines using the +“line-continued” backslash (\), as shown above. +

+ +

+FAMILY is the family for the entirety of Lists pages. +

+ +

+FONT is the font for the entirety of Lists pages. +

+ +

+PT_SIZE is the base point size for the entirety of Lists +pages. +

+ +

+LEAD is the base leading for the entirety of Lists pages. +

+ +

+TITLE_FAMILY is the family for the Lists titles if you +want it different from the family otherwise used for the Lists +pages. +

+ +

+TITLE_FONT is the font for the Lists titles if you want +it different from the font otherwise used for the Lists pages. +

+ +

+TITLE_SIZE tells mom by how much to increase +(+) or decrease (-) the point size of the +titles relative to the overall point size of Lists pages. +

+ +

+TITLE_QUAD tells mom how to position the title +horizontally. +

+ +

+TITLE_COLOR sets the colour for the titles. The colour +must be pre-initialized with +NEWCOLOR +or +XCOLOR. +

+ +

+PN_FAMILY sets the family for entry pagenumbers. +

+ +

+PN_FONT sets the font for entry pagenumbers. +

+ +

+PN_SIZE tells mom by how much to increase (+) +or decrease (-) the point size of entry pagenumbers +relative to the overall point size of Lists pages. +

+ +

+EQN_PN_PADDING, FIG_PN_PADDING, and +TBL_PN_PADDING 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, +
+ + LISTS_STYLE FIG_PN_PADDING 3 + LISTS_STYLE TBL_PN_PADDING 2 + +would prevent an unneeded, reserved placeholder from putting too +much space between the leader and the entry pagenumber in the List of +Tables. +

+ +

+The padding in effect, unless you change it, is whatever was set for +the Tables of Contents; mom’s default is “3”. +

+ +

+PAGENUM_STYLE 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 +LISTS_0F_<type> +macro. +

+ +

+NO_PAGINATION disables pagination of Lists pages. +

+ +

Shaded backgrounds and frames (boxes)

+ +

+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. +

+ +

+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. +

+ +

+Boxes extend from the current left margin to the current right +margin, respecting any active left and/or right indents. There are +two exceptions, +EPIGRAPH BLOCK +and +BLOCKQUOTE, +which are discussed +here. +

+ +

+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. +

+ +

+Frames are drawn from the perimeter inward. The inset is +relative to the inner edge of the frame. +

+ +

+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. +

+ +

+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. +

+ +

+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. +

+ +

+Boxed material is not +shimmed +or +flexed. +If either was active prior to the box, it is restored when the box +ends and mom automatically shims or flexes whatever comes next. +

+ +

+NOTE: +Shaded backgrounds and frames are not available when your +PRINTSTYLE +is TYPEWRITE or when +COLUMNS are enabled. +

+ +

BOX

+ +

+ +

+Without arguments, BOX begins a shaded grey background. +The material inside is inset by one +pica. +Any other type of box requires at a minimum either +SHADED or OUTLINED. In the case of boxes +that are to contain pdf images or pre-processor material for +eqn, +pic, +or +grap, +IMG, EQN, PIC, or GRAP +must also be given. Note that +tbl +does not have this requirement. +

+ +

+BOX is a +toggle macro, +so any argument other than one in the list completes the box +(QUIT, END, X, etc). +

+ +

+Boxes should be started inside toggle macros like +QUOTE +or +FLOAT +just after the macro is called, and terminated just before toggling +the macro off (unless you wish the box to enclose further material). +

+ +

+Non-toggle macros like +HEADING +or +PP +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: + +.BOX +.PS +<pic commands> +.PE +.BOX OFF + +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. + + .de PINK_BOX + .BOX \ + SHADED pink \ + OUTLINED darkred \ + WEIGHT 1p \ + INSET 9p + .. + +.PINK_BOX may then be used instead of .BOX any +time you want a box with those arguments. +

+ +

SHADED | OUTLINED

+ +

+SHADED or OUTLINED are required. Both may +be given, resulting in a shaded background with a frame, and both +require a colour, e.g. + + .BOX SHADED blue OUTLINED black + +The colour may be +

+ +

an xcolor name
a colour initialized with + NEWCOLOR + or + XCOLOR +
an RGB hexadecimal string beginning with (e.g. #FF0000)

+ +

+Note that without SHADED, the above would simply draw a +black frame. +

+ +

WEIGHT

+ +

+Mom’s default weight for OUTLINED is 1/2 +point. +If you’d like to change it, give WEIGHT the desired +value with a unit of measure appended, typically points, e.g. + + .BOX OUTLINED black WEIGHT 1p + +

+ +

INSET

+ +

+Mom’s default inset for boxes is one +pica +on all sides. If you’d like a larger or smaller inset, give +INSET the distance you want with a unit of measure +appended, e.g. + + .BOX SHADED pink INSET 2m + +

+ +

ADJUST

+ +

+If you are not happy with the starting position of a box, you can +change it by giving ADJUST the distance you want it +raised (-) or lowered (+) with a unit of measure appended. For +example, to lower a box three points, + + .BOX OUTLINED black ADJUST +3p + +To raise it, + + .BOX OUTLINED black ADJUST -3p + +

+ +

PIC / GRAP / EQN / IMG

+ +

+The PIC argument must be given to BOX if the box contains +any +pic +diagrams. Likewise, graphs made with +grap, +equations made with +eqn, +and +pdf images +require a corresponding GRAP, EQN, or +IMG argument. +

+ +

+If you’re boxing a single diagram, graph, or pdf image, wrap +it in a float, like this: + + .FLOAT + .BOX PIC <other parameters> + .PS + <pic input> + .PE + .BOX OFF + .FLOAT OFF + +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. +

+ +

Additional notes on BOX usage and behaviour

+ +

QUOTE, BLOCKQUOTE, EPIGRAPH, FLOAT

+ +

+QUOTE, +BLOCKQUOTE, +EPIGRAPH, +and +FLOAT +require that boxes be started after they are +invoked and stopped just before they are toggled off: + + .QUOTE + .BOX <parameters> + Text of quote + .BOX OFF + .QUOTE OFF + +

+ +

CODE

+ +

+If you’re boxing +CODE +that’s wrapped inside +QUOTE, +as described +here, +set the quote indent to “0” with + + .QUOTE_STYLE INDENT 0 + +so that the box’s leftmost inset is respected. +

+ +

+Here’s a recipe for setting boxed code with an 18-point inset: + + .QUOTE_STYLE INDENT 0 + .QUOTE + .CODE + .BOX INSET 18p + Hello, world. + .BOX OFF + .QUOTE OFF + +Note that CODE, wrapped inside QUOTE, does not require a corresponding CODE OFF. +

+ +

Description of boxed BLOCKQUOTES and EPIGRAPH BLOCKS

+ +

+When you box a BLOCKQUOTE, or an EPIGRAPH with the BLOCK +argument, the box is centred on the page and is only as wide as the +blockquote or epigraph plus the box’s inset. +

+ +

+QUOTE and EPIGRAPH (without the BLOCK argument), on the +other hand, set the box fully to the left and right margins. +

+ +

Leftover box syndrome

+ +

+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. +

+ +

+The solution in both situations is to use the ADJUST +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. +

+ +

SLIDES

+ +

+On a slide with no pauses, boxes behave as they do in printed +documents. +

+ +

+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. +

+ +

Footnotes

+ +

+You don’t have to worry about boxes encroaching on footnotes. +Mom makes sure they don’t. +

+ +

Page colour

+ +

+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 +slide presentations. +

+ +

PAGE_COLOR

+ +

+Macro: PAGE_COLOR <color> | OFF | off +

+Aliased as PAGE_COLOUR, SLIDE_COLOR, +and SLIDE_COLOUR. +

+ +

+When you invoke PAGE_COLOR with a color 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 PAGE_COLOR OFF, only the last applies. +

+ +

+Note: +Unlike other +toggle macros, +PAGE_COLOR requires the use of OFF or off +to terminate it rather than an arbitrary string (OFF, +QUIT, END, X, etc). +

+ +

+ + + + + + + + +

Back to Table of Contents

Top

Next: Page headers/footers, pagination

+ +