diff options
Diffstat (limited to '')
| -rw-r--r-- | contrib/mom/momdoc/docelement.html | 6639 |
1 files changed, 6639 insertions, 0 deletions
diff --git a/contrib/mom/momdoc/docelement.html b/contrib/mom/momdoc/docelement.html new file mode 100644 index 0000000..43f79d4 --- /dev/null +++ b/contrib/mom/momdoc/docelement.html @@ -0,0 +1,6639 @@ +<?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 -- Document processing, element tags</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="images.html#top">Next: Graphics, floats, preprocessor support</a></td> +</tr> +</table> + +<h1 class="docs">The document element tags</h1> + +<div style="width: 460px; margin: auto;"> +<ul class="no-enumerator"> + <li><a href="#docelement-intro">Introduction to the document element tags</a></li> + <li><a href="#docelement-control">Control macros – changing the tag defaults</a> + <ul style="margin-left: -.5em; list-style-type: disc;"> + <li><a href="#control-macro-args">Arguments to the control macros</a> + <ul style="margin-left: -.5em; list-style-type: circle;"> + <li><a href="#family-and-font">family and font</a></li> + <li><a href="#point-size">point size</a></li> + <li><a href="#color">colour</a></li> + <li><a href="#quad">quad/justification</a></li> + <li><a href="#underline">underline style, rule weight</a></li> + </ul></li> + <li><a href="#grouping">Grouping control macros</a></li> + </ul></li> +</ul> +</div> + +<div class="rule-medium"><hr/></div> + +<h2 id="toc-doc-element" class="docs" style="text-align: center;">Document element tags table of contents</h2> + +<div id="docelement-mini-toc" style="font-size: 100%; line-height: 150%; margin-top: .5em;"> +<div class="mini-toc-col-1" style="margin-left: 0;"> +<h3 class="toc toc-docproc-header" style="margin-top: 1em;"><a class="header-link" href="#epigraph-intro">Epigraphs</a></h3> +<ul class="toc-docproc" style="margin-top: .5em;"> + <li><a href="#epigraph">EPIGRAPH</a></li> + <li><a href="#epigraph-control">Epigraph control</a></li> +</ul> +<h3 class="toc toc-docproc-header"><a class="header-link" href="#pp-intro">Paragraphs</a></h3> +<ul class="toc-docproc" style="margin-top: .5em;"> + <li><a href="#pp">PP</a></li> + <li><a href="#pp-control">Paragraph control</a></li> +</ul> +<h3 class="toc toc-docproc-header"><a class="header-link" href="#heading-intro">Headings</a></h3> +<ul class="toc-docproc" style="margin-top: .5em;"> + <li><a href="#heading">HEADING</a></li> + <li><a href="#heading-control">Heading control</a></li> + <li><a href="#oldstyle-headings-intro">Oldstyle headings</a></li> +</ul> +<h3 class="toc toc-docproc-header"><a class="header-link" href="#linebreak-intro">Linebreaks (section breaks)</a></h3> +<ul class="toc-docproc" style="margin-top: .5em;"> + <li><a href="#linebreak">LINEBREAK</a></li> + <li><a href="#linebreak-control">Linebreak control</a></li> +</ul> +<h3 class="toc toc-docproc-header"><a class="header-link" href="#quote-intro">Quotes (line for line; poetry or code)</a></h3> +<ul class="toc-docproc" style="margin-top: .5em;"> + <li><a href="#quote">QUOTE</a></li> + <li><a href="#quote-control">Quote control</a></li> +</ul> +<h3 class="toc toc-docproc-header"><a class="header-link" href="#blockquote-intro">Blockquotes (cited material)</a></h3> +<ul class="toc-docproc" style="margin-top: .5em;"> + <li><a href="#blockquote">BLOCKQUOTE</a></li> + <li><a href="#blockquote-control">Blockquote control</a></li> +</ul> +<h3 class="toc toc-docproc-header"><a class="header-link" href="#code-intro">Inserting code snippets</a></h3> +<ul class="toc-docproc" style="margin-top: .5em;"> + <li><a href="#code">CODE</a></li> + <li><a href="#code-control">Code control</a></li> +</ul> +</div> +<div class="mini-toc-col-2" style="margin-top: 1.5em;"> +<h3 class="toc toc-docproc-header"><a class="header-link" href="#list-intro">Nested lists</a></h3> +<ul class="toc-docproc" style="margin-top: .5em;"> + <li><a href="#list">LIST</a></li> + <li><a href="#item">ITEM</a></li> + <li><a href="#list-control">List control</a></li> +</ul> +<h3 class="toc toc-docproc-header"><a class="header-link" href="#number-lines-intro">Line numbering</a></h3> +<ul class="toc-docproc" style="margin-top: .5em;"> + <li><a href="#number-lines">NUMBER_LINES</a></li> + <li><a href="#number-lines-control">Line numbering control</a></li> +</ul> +<h3 class="toc toc-docproc-header"><a class="header-link" href="#footnote-intro">Footnotes</a></h3> +<ul class="toc-docproc" style="margin-top: .5em;"> + <li><a href="#footnote">FOOTNOTE</a></li> + <li><a href="#footnote-control">Footnote control</a></li> +</ul> +<h3 class="toc toc-docproc-header"><a class="header-link" href="#endnote-intro">Endnotes</a></h3> +<ul class="toc-docproc" style="margin-top: .5em;"> + <li><a href="#endnote">ENDNOTE</a></li> + <li><a href="#endnote-control">Endnote control</a></li> +</ul> +<h3 class="toc toc-docproc-header"><a class="header-link" href="#margin-notes-intro">Margin notes</a></h3> +<ul class="toc-docproc" style="margin-top: .5em;"> + <li><a href="#mn-init">MN_INIT (set margin notes parameters)</a></li> + <li><a href="#mn">MN</a></li> +</ul> +<h3 class="toc toc-docproc-header"><a class="header-link" href="#finis-intro">Document termination string</a></h3> +<ul class="toc-docproc" style="margin-top: .5em;"> + <li><a href="#finis">FINIS</a></li> + <li><a href="#finis-control">Finis control</a></li> +</ul> +</div> +</div> + +<div class="rule-medium" style="clear: both;"><hr/></div> + +<h2 id="docelement-intro" class="docs">Introduction to the document element tags</h2> + +<p> +Once you’ve completed the setup for a document (see +<a href="docprocessing.html#docprocessing-tut">Setting up a mom document</a>), +formatting it is a snap. Simply invoke the appropriate tag for +each document element as you need it. The tags are macros that +tell mom: “This is a paragraph; this is a heading; this is a +footnote,” and so on. +</p> + +<p> +Generally, for each tag, there are +<a href="definitions.html#controlmacro">control macros</a> +for the tag’s family, font and point size. Where appropriate, +there are macros to control leading, indents, quad and special +features as well. +Mom has tasteful defaults for all the tags, hence you only use the +control macros when you want to change the way she does things. +This is usually done prior to +<a href="docprocessing.html#start">START</a>, +but can, in fact, be done at any time in the course of a document. +Any change to a tag’s style affects all subsequent invocations +of the tag. +</p> + +<h2 id="docelement-control" class="docs">Control macros – changing the tag defaults</h2> + +<p> +The control macros for document processing tags let you design the +look of all the parts of your documents—should you wish. At +a bare minimum, all tags have macros to change mom’s defaults +for family, font, point size and colour. Where appropriate, there +are macros to control leading, indents and quad as well. +</p> + +<p> +In addition, many tags have special macros to control features that +are pertinent to those tags alone. Have a look at the section +dealing with any particular tag to find out what macros control the +tag, and what mom’s defaults for the tag are. +</p> + +<p> +The control macros may be used at any time during the course of a +document (i.e. before or after +<a href="docprocessing.html#start">START</a>). +The changes you make alter all subsequent invocations of the +affected tag until you make another change, either by passing new +arguments to the tag’s control macro, or toggling a particular +feature of the tag on or off. +</p> + +<p> +And don’t forget: the +<a href="typesetting.html#macros-typesetting">typesetting macros</a> +can be used at any time, including inside +<a href="definitions.html#toggle">toggle</a> +tags (affecting only that particular invocation of the tag). +Equally, +<a href="definitions.html#inlines">inline escapes</a> +can be used in tags that take +<a href="definitions.html#stringargument">string arguments.</a> +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="tip">Tip:</span> +Get familiar with mom at her default settings before exploring the +control macros. Put her through her paces. See how she behaves. +Get to know what she feels like and how she looks, both in your +text editor and on the printed page. Then, if you don’t like +something, use this documentation to find the precise macro you need +to change it. There are tons of control macros. Reading up on them +and trying to remember them all might lead you to think that mom is +complex and unwieldy, which is not only untrue, but would offend her +mightily. +</p> +</div> + +<div class="box-important"> +<p class="tip-top"> +<span class="important">Important:</span> +The family, font, point size, colour and leading control macros have +no effect in +<a href="docprocessing.html#printstyle">PRINTSTYLE <kbd>TYPEWRITE</kbd></a>, +except where noted throughout this documentation. +</p> + +<p class="tip-bottom"> +Please also note that the defaults listed with the control macros +apply only to +<a href="docprocessing.html#printstyle">PRINTSTYLE <kbd>TYPESET</kbd></a> +unless a default for <kbd>TYPEWRITE</kbd> is also given. +</p> +</div> + +<h3 id="control-macro-args" class="docs">Arguments to the control macros</h3> + +<h4 id="family-and-font" class="docs" style="margin-top: 1em; margin-bottom: -.75em;">Family and font</h4> + +<p> +The arguments to the control macros that end in _FAMILY or _FONT are +the same as for +<a href="typesetting.html#family">FAMILY</a> +and +<a href="typesetting.html#font">FT</a>. +</p> + +<h4 id="point-size" class="docs" style="margin-top: -.5em; margin-bottom: -.75em;">Point size</h4> + +<p> +Control macros that end in _SIZE always take +the form <kbd>+<n></kbd> or <kbd>-<n></kbd> where +<n> is the number of +<a href="definitions.html#picaspoints">points</a> +larger (+) or smaller (-) than the point size of paragraphs +you want the document element to be. For example, to set +blockquotes 2 points smaller than the type in paragraphs, do +<br/> +<span class="pre-in-pp"> + .BLOCKQUOTE_SIZE -2 +</span> +There’s no need for a +<a href="definitions.html#unitofmeasure">unit of measure</a> +with the _SIZE control macros; points is assumed. +</p> + +<h4 id="color" class="docs" style="margin-top: -.5em; margin-bottom: -.75em;">Colour</h4> + +<p> +Control macros that end in _COLOR take as their argument a colour +name pre-defined (or “initialized”) with +<a href="color.html#newcolor">NEWCOLOR</a> +or +<a href="color.html#xcolor">XCOLOR</a>. +For example, if you want your +<a href="#linebreak">author linebreaks</a> +to be red, once you’ve defined or initialized the colour, red, +<br/> +<span class="pre-in-pp"> + .LINEBREAK_COLOR red +</span> +will turn them red. +</p> + +<h4 id="lead" class="docs" style="margin-top: -.5em; margin-bottom: -.75em;">Lead / linespacing</h4> + +<p> +Control macros that end in _AUTOLEAD take the same argument as +<a href="typesetting.html#autolead">AUTOLEAD</a>, +<i>viz.</i> a digit that represents the number of points to add to +the tag’s point size to arrive at its +<a href="definitions.html#leading">leading</a>. +For example, to set footnotes +<a href="definitions.html#solid">solid</a>, do +<br/> +<span class="pre-in-pp"> + .FOOTNOTE_AUTOLEAD 0 +</span> +To set footnotes with a 1-point lead (i.e. with the line spacing +one point greater than the footnote’s point size), do +<br/> +<span class="pre-in-pp"> + .FOOTNOTE_AUTOLEAD 1 +</span> +</p> + +<div class="box-tip" style="margin-top: -1.25em;"> +<p class="tip"> +<span class="note">Note:</span> +_AUTOLEAD control macros do not have a <kbd>FACTOR</kbd> argument. +</p> +</div> + + +<h4 id="control-indents" class="docs" style="margin-top: -.75em; margin-bottom: -.75em;">Indents</h4> + +<p> +Except for +<a href="#para-indent">PARA_INDENT</a>, +the argument to control macros that end in _INDENT can take +either a single numeral (whole numbers only, no decimal fractions) +<i>without</i> a +<a href="definitions.html#unitofmeasure">unit of measure</a> +appended to it, or a digit (including decimal fractions) <i>with</i> +a unit of measure appended. +</p> + +<p> +A digit <i>without</i> a unit of measure appended represents by +how much you want your paragraph first-line indents (set with +PARA_INDENT) multiplied to achieve the correct indent for a +particular tag. For example, +<br/> +<span class="pre-in-pp"> + .PARA_INDENT 2m + .BLOCKQUOTE_INDENT 2 +</span> +means that blockquotes will be indented from the left and right +margins by twice the size of the paragraph indent, or 4 +<a href="definitions.html#em">ems</a>. +</p> + +<p> +A digit <i>with</i> a unit of measure appended defines an absolute +indent, relative to nothing. In the following, blockquotes will be +indented by 3 +<a href="definitions.html#picaspoints">picas</a> +and 6 +<a href="definitions.html#picaspoints">points</a>, +regardless of the paragraph indent. +<br/> +<span class="pre-in-pp"> + .PARA_INDENT 2m + .BLOCKQUOTE_INDENT 3P+6p +</span> +</p> + +<h4 id="quad" class="docs" style="margin-top: -1em; margin-bottom: -.75em;">Quad / justification style</h4> + +<p> +Control macros that end in _QUAD take the same arguments as +<a href="typesetting.html#quad">QUAD</a>. +</p> + +<h4 id="underscore" class="docs" style="margin-bottom: -.75em;">Underscore style, rule weight</h4> + +<p> +If mom gives the option to underscore a document element, the weight +of the underline and its distance from the +<a href="definitions.html#baseline">baseline</a> +are controlled by macros that end in _UNDERSCORE or _UNDERLINE, the +two being synonymous. These macros take the following arguments: +<br/> +<span class="pre-in-pp"> + DOUBLE - double underscore + <weight> - the underscore weight (in points, no unit of measure required + <distance> - distance from baseline (unit of measure required) + <rule gap> - distance between double underscore rules (unit of measure required) +</span> +<kbd>DOUBLE</kbd> by itself will double-underscore the element. The +remaining arguments must be entered in the order given. You may not +skip over any of them, which means that if you only wish to change +<kbd><rule gap></kbd>, you must still enter a +<kbd><weight></kbd> and <kbd><distance></kbd> argument. +</p> + +<p> +Page elements that are separated from +<a href="definitions.html#running">running text</a> +by a rule (i.e. page headers, page footers, and footnotes) are +controlled by macros that end in _RULE_WEIGHT. +</p> + +<p> +The weight argument to _UNDERSCORE macros is the same as the +argument to +<a href="inlines.html#rule-weight">RULE_WEIGHT</a>, +as is the argument to _RULE_WEIGHT macros. +</p> + +<h3 id="grouping" class="docs">Grouping control macros</h3> + +<p> +As of version 2.1, it is possible to group control macros for a +particular tag into a single <kbd><element>_STYLE</kbd> macro. +For example, rather than setting the family, size, and indent of +<a href="#blockquote-intro">BLOCKQUOTES</a> +with +<br/> +<span class="pre-in-pp"> + .BLOCKQUOTE_FAMILY H + .BLOCKQUOTE_SIZE -2 + .BLOCKQUOTE_INDENT 4P +</span> +you can enter the same style parameter changes with +<br/> +<span class="pre-in-pp"> + .BLOCKQUOTE_STYLE \ + FAMILY H \ + SIZE -2 \ + INDENT 4P +</span> +<kbd><element>_STYLE</kbd> macros use +“keyword/value” pairs (<kbd>FAMILY</kbd> is a keyword, +<kbd>H</kbd> is a value), and may be entered entirely on one line, +or, as the example shows, broken into several readable lines using +the backslash. The macro itself and all but the last keyword/value +pair require the backslash when this style is used. +</p> + +<p> +Not all the control macros for a particular tag may be available +with an <kbd><element>_STYLE</kbd> macro. Generally speaking, +though, if a tag has control macros for +</p> +<table style="font-family: monospace; font-weight: bold; margin-left: 5em; margin-top: -1em"> + <tr> + <td style="padding-right: 1em">FAMILY</td> + <td style="padding-right: 1em">LEAD</td> + <td style="padding-right: 1em">INDENT</td> + <td style="padding-right: 1em">SMALLCAPS</td> + </tr> + <tr> + <td style="padding-right: 1em">FONT</td> + <td style="padding-right: 1em">AUTOLEAD</td> + <td style="padding-right: 1em">COLOR</td> + <td style="padding-right: 1em">UNDERSCORE or UNDERLINE</td> + </tr> + <tr> + <td style="padding-right: 1em">SIZE</td> + <td style="padding-right: 1em">QUAD</td> + <td style="padding-right: 1em">CAPS</td> + </tr> +</table> +<p style="margin-top: .5em"> +those parameters may be used within an +<kbd><element>_STYLE</kbd> macro. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +If you need to reverse the sense of <kbd>CAPS</kbd>, +<kbd>SMALLCAPS</kbd> or <kbd>UNDERSCORE/UNDERLINE</kbd>, which +do not take a value after the keyword, use <kbd>NO_CAPS</kbd>, +<kbd>NO_SMALLCAPS</kbd>, and <kbd>NO_UNDERSCORE/NO_UNDERLINE</kbd>. +</p> +</div> + +<div class="rule-short"><hr/></div> + +<!-- ==================================================================== --> + +<h2 id="epigraph-intro" class="macro-group">Epigraphs</h2> + +<ul style="margin-left: -.5em;"> + <li><a href="#epigraph">Tag: EPIGRAPH</a></li> + <li><a href="#epigraph-control">Epigraph control macros and defaults</a></li> +</ul> + +<p> +<a href="definitions.html#epigraph">Epigraphs</a> +colour, flavour, or comment on the document they precede. +Typically, they are centred at the top of a document’s first page +(underneath the title) and set in a smaller point size than that of +paragraph text. +</p> + +<p> +By default, mom sets epigraphs centred and +<a href="definitions.html#filled">unfilled</a>; +this lets you input them on a line for line basis. This behaviour +can be changed to accommodate +<a href="definitions.html#filled">filled</a> +epigraph “blocks.” +</p> + +<!-- -EPIGRAPH- --> + +<div class="macro-id-overline"> +<h3 id="epigraph" class="macro-id">EPIGRAPH</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>EPIGRAPH</b> <kbd class="macro-args"><toggle> | [ BLOCK ]</kbd> +</div> + +<p> +EPIGRAPH is a toggle, used like this: +<br/> +<span class="pre-in-pp"> + .EPIGRAPH + <text of epigraph> + .EPIGRAPH OFF +</span> +<kbd>OFF</kbd>, above, could be anything—say, <kbd>Q</kbd> or +<kbd>X</kbd>—since any argument other than <kbd>BLOCK</kbd> +turns it off. +</p> + +<p> +If given the argument, <kbd>BLOCK</kbd>, EPIGRAPH sets epigraphs +<a href="definitions.html#filled">filled</a>, +justified or quadded in the same direction as paragraphs, indented +equally from both the left and right margins. +</p> + +<p> +If a block-style epigraph runs to more than one paragraph (unlikely, +but conceivable), you must introduce every paragraph—including +the first—with the +<a href="#pp">PP</a> +tag. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +EPIGRAPH should only be used at the top of a document (i.e. just +after +<a href="docprocessing.html#start">START</a>) +or after headings. The latter is not especially recommended, but it +does work. In all other places where you want quotes or cited text, +use +<a href="#quote">QUOTE</a> +or +<a href="#blockquote">BLOCKQUOTE</a>. +</p> +</div> + +<div class="box-tip"> +<p class="tip"> +<span class="tip">Tips on vertical spacing around epigraphs:</span> +If you wish to change the vertical position of an epigraph with +<a href="typesetting.html#space">SPACE</a>, +<a href="typesetting.html#ald">ALD</a>, or +<a href="typesetting.html#rld">RLD</a>, +do so before invoking <kbd>.EPIGRAPH</kbd>, like this: +<br/> +<span class="pre-in-pp"> + .SP -6p + .EPIGRAPH + A notable quote. + .EPIGRAPH OFF +</span> +If you’re setting a document in +<a href="docprocessing.html#columns">columns</a> +and you’d like to add or subtract space <i>after</i> the +epigraph, which is centred over the top of both columns, the place +to do it is inside the epigraph, like this: +<br/> +<span class="pre-in-pp"> + .EPIGRAPH + A notable quote. + .SP 1v + .EPIGRAPH OFF +</span> +If you were to add the <kbd>.SP 1v</kbd> outside the epigraph, the +space would be added to the top of the leftmost column only, +resulting in unbalanced columns. +</p> +</div> + +<div class="defaults-container" style="padding-bottom: 8px;"> +<h3 id="epigraph-control" class="docs defaults" style="margin-top: -.25em;">EPIGRAPH control macros and defaults</h3> + +<p class="defaults"> +See +<a href="#control-macro-args">Arguments to the control macros</a>. +<br/> +The following EPIGRAPH control macros may also be +<a href="#grouping">grouped</a> +using EPIGRAPH_STYLE. +</p> + +<span class="pre defaults"> +.EPIGRAPH_FAMILY default = prevailing document family; default is Times Roman +.EPIGRAPH_FONT default = roman +.EPIGRAPH_SIZE default = -1.5 (points) +.EPIGRAPH_COLOR default = black +.EPIGRAPH_AUTOLEAD default = 2 points +(The next two apply to “block” style epigraphs only) +.EPIGRAPH_INDENT* (see Note on EPIGRAPH_INDENT, below) + +*Indent here refers to the indent from both the left and right margins + that centres block style epigraphs on the page. +</span> +</div> + +<div class="box-notes"> +<h3 id="epigraph-indent" class="docs notes" style="margin-bottom: -.75em;">Note on EPIGRAPH_INDENT</h3> + +<p style="margin-top: .5em;"> +If you pass EPIGRAPH_INDENT an integer with no unit of measure +appended, the integer represents the amount by which to multiply +PARA_INDENT to arrive at an indent for block style epigraphs. If +you append a unit of measure to the argument, the indent will be +precisely the amount specified. +</p> + +<p> +Please also note that if your PARA_INDENT is <kbd>0</kbd> (i.e. +no indenting of the first line of paragraphs), you must set an +EPIGRAPH_INDENT yourself, with a unit of measure appended to the +argument. Mom has no default for EPIGRAPH_INDENT if paragraph first +lines are not being indented. +</p> + +<p class="tip-bottom"> +The default value for EPIGRAPH_INDENT is <kbd>3</kbd> (for +<a href="docprocessing.html#printstyle">PRINTSTYLE TYPESET</a>) +and <kbd>2</kbd> (for +<a href="docprocessing.html#printstyle">PRINTSTYLE TYPEWRITE</a>). +</p> +</div> + +<div class="rule-short"><hr/></div> + +<!-- ==================================================================== --> + +<h2 id="pp-intro" class="macro-group">Paragraphs</h2> + +<ul style="margin-left: -.5em;"> + <li><a href="#pp">Tag: PP</a></li> + <li><a href="#pp-control">Paragraph control macros and defaults</a></li> +</ul> + +<p> +The paragraph macro is the one you use most often. Consequently, +it’s one of most powerful, yet simplest to use—just the +letters PP. No arguments, nothing. Just <kbd>.PP</kbd> on a line +by itself any time, in any document element, tells mom you want to +start a new paragraph. The spacing and indent appropriate to where +you are in your document are taken care of automatically. +</p> + +<p> +By default, mom does not indent the first paragraph of a document, +nor paragraphs that fall immediately after headings. The first +paragraphs of blockquotes and block-style epigraphs are also not +indented. This behaviour can be changed with the control macro +<kbd><a href="#para-indent-first">INDENT_FIRST_PARAS</a></kbd>. +</p> + +<p> +Mom does not deposit a blank line between paragraphs. If you want +her to do so, use the control macro +<a href="#pp-space">PARA_SPACE</a>. +(I don’t recommend using this macro with +<a href="typesetting.html#printstyle">PRINTSTYLE TYPEWRITE</a>.) +</p> + +<p> +Note that mom does not provide widow or orphan control for +paragraphs (i.e., even if only one line of a paragraph fits at the +bottom of a page, she will set it on that page). The reason for +this is that writers of fiction often have single-line paragraphs +(e.g. in dialogue). Groff’s simplistic orphan control will +break these one-liners—if they fall at the bottom of the +page—to a new page, which is not what you want. +</p> + +<!-- -PP- --> + +<div class="macro-id-overline"> +<h3 id="pp" class="macro-id">PP</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>PP</b> +</div> +<p> +<kbd>.PP</kbd> (on a line by itself, of course) tells mom to start a +new paragraph. See +<a href="#pp-intro">above</a> +for more details. In addition to regular text paragraphs, you can +use PP in +<a href="#epigraph-intro">epigraphs</a>, +<a href="#blockquote-intro">blockquotes</a>, +<a href="#endnote-intro">endnotes</a> +and +<a href="#footnote-intro">footnotes</a>. +</p> + +<div class="defaults-container" style="background-color: #ded4bd; border: none;"> +<h3 id="pp-control" class="docs defaults">PP control macros and defaults</h3> + +<p class="defaults"> +The PP macro being so important, and representing, as it were, the +basis of everything that goes on in a document, its control is +managed in a manner somewhat different from other document element +tags. As a result, the control macros for PP may not be +<a href="#grouping">grouped</a> +within a <kbd>_STYLE</kbd> macro. +</p> + +<ol style="margin-top: .5em; padding-bottom: .5em;"> + <li><a href="#pp-family">Family control</a></li> + <li><a href="#pp-font">Font control</a></li> + <li><a href="#pp-color">Paragraph colour</a></li> + <li><a href="#pp-leading">Leading/linespacing control</a></li> + <li><a href="#pp-just-quad">Justification/quad control</a></li> + <li><a href="#para-indent">First-line indent control</a></li> + <li><a href="#para-indent-first">Initial paragraphs indent control</a></li> + <li><a href="#pp-space">Inter-paragraph spacing</a></li> +</ol> +</div> + +<h4 id="pp-family" class="docs" style="margin-top: -1.5em;">1. Family control</h4> + +<p> +The paragraph +<a href="definitions.html#family">family</a> +is set with +<a href="typesetting.html#family">FAMILY</a> +prior to +<a href="docprocessing.html#start">START</a>, +or +<a href="docprocessing.html#doc-family">DOC_FAMILY</a> +afterwards. Please note that both globally affect the family of +every element in the document. +</p> + +<p> +If you wish to change the family for regular text paragraphs only, +invoke <kbd>.FAMILY</kbd> immediately after <kbd>.PP</kbd> in every +paragraph whose family you wish to differ from the prevailing +document family. Alternatively, set the family and font for +paragraphs with PP_FONT, giving it a complete family+font name, e.g. +<br/> +<span class="pre-in-pp"> + PP_FONT TI +</span> +which would make the font used in paragraphs Times Roman Italic. +</p> + +<p> +Mom’s default paragraph (and document) family is Times Roman. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +Neither FAMILY nor DOC_FAMILY has any effect when the PRINTSTYLE is +<kbd>TYPEWRITE</kbd>. +</p> +</div> + +<h4 id="pp-font" class="docs" style="margin-top: -.25em;">2. Font control</h4> + +<p> +To change the +<a href="definitions.html#font">font</a> +used in regular text paragraphs, use PP_FONT, which takes the same +argument as +<a href="typesetting.html#font">FT</a>. +PP_FONT may be used before or after +<a href="docprocessing.html#start">START</a>. +Only regular text paragraphs are affected; paragraphs in +<a href="#epigraph-intro">epigraphs</a>, +<a href="#blockquote-intro">blockquotes</a>, +<a href="#endnote-intro">endnotes</a>, +and +<a href="#footnote-intro">footnotes</a> +remain at their default setting (medium roman) unless you change +them with the appropriate control macros. +</p> + +<p> +Mom’s default paragraph font is medium roman. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +PP_FONT has no effect when the PRINTSTYLE is <kbd>TYPEWRITE</kbd>. +If you wish to set whole typewritten paragraphs in italic, invoke +<kbd>.FT I</kbd> immediately after <kbd>.PP</kbd>. Depending +on which of +<a href="docprocessing.html#printstyle-italics">UNDERLINE_ITALIC</a> +or +<a href="docprocessing.html#printstyle-italics">ITALIC_MEANS_ITALIC</a> +is currently enabled, the paragraph will be set underlined or in +italic. Neither persists past the end of the paragraph. +</p> +</div> + +<h4 id="pp-color" class="docs" style="margin-top: -.25em;">3. Paragraph colour</h4> + +<p> +Mom has no special control macro for colourising paragraphs. If you +wish a colourised paragraph, you must use the macro +<a href="color.html#color">COLOR</a> +or the +<a href="definitions.html#inline">inline escape</a>, +<a href="color.html#color-inline"><kbd><span class="nobr">\*[<colourname>]</span></kbd></a>, +<i>after</i> <kbd>.PP</kbd>. The colour must be one pre-defined (or +“initialized”) with +<a href="color.html#newcolor">NEWCOLOR</a> +or +<a href="color.html#xcolor">XCOLOR</a>. +</p> + +<p> +Please note that unless you change the colour back to it’s +default (usually black) at the end of the paragraph, all subsequent +paragraphs will be set in the new colour, although most other +elements of your document will continue to be set in the default +colour (usually black). +</p> + +<p> +For example, assuming you have defined the colour, blue, +<br/> +<span class="pre-in-pp"> + .PP + .COLOR blue + <first paragraph> + .HEADING 1 "Monty Python" + .HEADING 2 "The Origins of Spam" + .PP + <second paragraph> +</span> +the first paragraph will be blue, the head and subhead will be in +the document’s default colour (usually black), and the second +paragraph will be in blue. +</p> + +<h4 id="pp-leading" class="docs" style="margin-top: -.25em;">4. Leading</h4> + +<p> +The paragraph +<a href="definitions.html#leading">leading</a> +is set with +<a href="typesetting.html#leading">LS</a> +prior to +<a href="docprocessing.html#start">START</a>, +or +<a href="docprocessing.html#doc-lead">DOC_LEAD</a> +afterwards. Please note that either method globally affects the +leading and spacing of every document element (except +<a href="definitions.html#header">headers</a> +and +<a href="definitions.html#footer">footers</a>). +</p> + +<p> +If you wish to change the leading of regular text paragraphs only, +invoke <kbd>.LS</kbd> immediately after <kbd>.PP</kbd> in any +paragraph whose leading you wish to change. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Warning:</span> +Changing a paragraph’s leading will almost certainly screw up +mom’s ability to balance the bottom margin of pages. Should +you absolutely require a change to a paragraph’s leading and +need to get mom back on track leading-wise afterwards, use the +<a href="docprocessing.html#shim">SHIM</a> +or +<a href="docprocessing.html#shim">FLEX</a> +macro, depending on which +<a href="docprocessing.html#vertical-whitespace-management">vertical whitespace management</a> +strategy you are using. +</p> +</div> + +<p> +Mom’s default paragraph leading (document leading) +is 16 points, adjusted to fill the page. +</p> + +<h4 id="pp-just-quad" class="docs" style="margin-top: -.25em;">5. Justification / quad</h4> + +<p> +The justification/quad-direction of regular text paragraphs (i.e. +<a href="definitions.html#just">justified</a>, +or +<a href="definitions.html#filled">filled</a> +and +<a href="definitions.html#quad">quadded</a> +left/right/centre) is set with +<a href="typesetting.html#justify">JUSTIFY</a> +or +<a href="typesetting.html#quad">QUAD</a> +prior to +<a href="docprocessing.html#start">START</a>, +and with +<a href="docprocessing.html#doc-quad">DOC_QUAD</a> +afterwards. +</p> + +<p> +Please note that either method of setting the paragraph +justification/quad-direction also affects +<a href="#epigraph-intro">epigraphs</a>, +<a href="#footnote-intro">footnotes</a>, +and +<a href="#endnote-intro">endnotes</a>, +but not +<a href="#blockquote-intro">blockquotes</a> +(whose default is quad left unless you change it with +<a href="#blockquote">BLOCKQUOTE_QUAD</a>). +The justification/quad-direction of epigraphs and footnotes may be +changed with their own control macros. +</p> + +<p> +If you wish to change the justification/quad-direction of individual +paragraphs, invoke +<a href="typesetting.html#justify"><kbd>.JUSTIFY</kbd></a> +or +<a href="typesetting.html#quad"><kbd>.QUAD</kbd></a> +on the line immediately after <kbd>.PP</kbd>. Only the paragraph +in question gets justified or quadded differently; subsequent +paragraphs remain unaffected. +</p> + +<p> +Mom’s default justification/quad-direction for paragraphs +when the +<a href="docprocessing.html#printstyle">PRINTSTYLE</a> +is <kbd>TYPESET</kbd> is justified; for PRINTSTYLE +<kbd>TYPEWRITE</kbd>, the default is quad left. +</p> + +<h4 id="para-indent" class="docs" style="margin-top: -.25em;">6. First-line indent</h4> + +<p> +The first-line indent of paragraphs is controlled by PARA_INDENT, +which takes one argument: the size of the indent. PARA_INDENT may be +used before or after +<a href="docprocessing.html#start">START</a>. +A +<a href="definitions.html#unitofmeasure">unit of measure</a> +is required; fractional sizes are allowed. Thus, to set the +paragraph indent to 4-1/2 +<a href="definitions.html#em">ems</a>, do +<br/> +<span class="pre-in-pp"> + .PARA_INDENT 4.5m +</span> +In addition to establishing the basic first line-indent of +paragraphs, PARA_INDENT also affects +<a href="#epigraph-intro">epigraphs</a>, +<a href="#quote-intro">quotes</a> +and +<a href="#blockquote-intro">blockquotes</a>, +whose overall indenting from the left and (where applicable) +right margins is relative to PARA_INDENT if +the _INDENT control macro for these tags has +no +<a href="definitions.html#unitofmeasure">unit of measure</a> +appended to it. Furthermore, the first-line indent of paragraphs +within these document elements (as well as footnotes) is also +relative to PARA_INDENT (always 1/2 of PARA_INDENT), hence they are +also affected. +</p> + +<p> +Mom’s default PARA_INDENT is 2 ems for +<a href="docprocessing.html#printstyle">PRINTSTYLE</a> +<kbd>TYPESET</kbd> and 3 picas (1/2 inch) for +<a href="docprocessing.html#printstyle">PRINTSTYLE</a> +<kbd>TYPEWRITE</kbd>. +</p> + +<h4 id="para-indent-first" class="docs" style="margin-top: -.25em;">7. Indenting initial paragraphs</h4> + +<p> +By default, mom does not indent the first paragraph of a document, +nor the first paragraph after a heading or +<a href="#linebreak-intro">linebreak</a>, +nor the first paragraphs of +<a href="#epigraph-intro">epigraphs</a>, +<a href="#blockquote-intro">blockquotes</a>, +<a href="#endnote-intro">endnotes</a> +or +<a href="#footnote-intro">footnotes</a> +that run to more than one paragraph. +</p> + +<p> +If you wish to have first paragraphs indented, invoke the macro +INDENT_FIRST_PARAS without an argument, either before or after +<a href="docprocessing.html#start">START</a>. +INDENT_FIRST_PARAS is a toggle macro, therefore passing it any +argument (<kbd>OFF</kbd>, <kbd>QUIT</kbd>, <kbd>Q</kbd>, +<kbd>X</kbd>...) cancels its effect, meaning that first paragraphs +will once again not be indented. +</p> + +<h4 id="pp-space" class="docs">8. Inter-paragraph spacing</h4> + +<p> +By default, mom does not insert a blank line between +paragraphs. If you would like her to do so, invoke the macro +PARA_SPACE without an argument, either before or after +<a href="docprocessing.html#start">START</a>. +PARA_SPACE is a toggle macro, therefore passing it any argument +(<kbd>OFF</kbd>, <kbd>QUIT</kbd>, <kbd>Q</kbd>, <kbd>X</kbd>...) +cancels its effect, meaning that paragraphs will once again not be +separated by a blank line. +</p> + +<p> +If you would like to space paragraphs by less than a full linespace, +invoke PARA_SPACE with the amount of space you want as a numeric +argument. A +<a href="definitions.html#unitofmeasure">unit of measure</a> +is required. For example, to space paragraphs by one-quarter +linespace +<span class="pre-in-pp"> + .PARA_SPACE .25v +</span> +is how you’d do it, or, if you want six points between +paragraphs +<span class="pre-in-pp"> + .PARA_SPACE 6p +</span> +</p> + +<p style="margin-top: -1em" > +If +<a href="docprocessing.html#flex-vs-shim">flex-spacing</a> +is enabled, additional flexible vertical whitespace can be inserted +between spaced paragraphs with the +<a href="docprocessing.html#flex">FLEX</a> +macro. +</p> + +<p> +PARA_SPACE is not recommended for use with PRINTSTYLE TYPEWRITE +unless you give PRINTSTYLE the <kbd>SINGLESPACE</kbd> option. +</p> + +<div class="box-tip"> +<p class="tip-top"> +<span class="note">Note:</span> +If PARA_SPACE is on, mom spaces only those paragraphs that come +after an initial paragraph. Initial paragraphs are those that come +immediately after the +<a href="definitions.html#docheader">docheader</a> +(i.e. the start of a document), +<a href="#epigraph-intro">epigraphs</a>, +<a href="#heading-intro">headings</a>, +and +<a href="#linebreak-intro">linebreaks</a>. +(The first paragraph after these document elements requires no +blank line to separate it from other paragraphs.) +</p> + +<p class="tip-bottom"> +Sometimes, you can be fairly deep into a document before using PP +for the first time, and when you do, because mom is still waiting +for that initial paragraph, she doesn’t space it with a blank +line, even though you expect her to. The simple workaround for this +is to invoke <kbd>.PP</kbd> twice (in succession) at the point you +expect the blank line to appear. +</p> +</div> + +<div class="rule-short"><hr/></div> + +<!-- ==================================================================== --> + +<h2 id="heading-intro" class="macro-group">Headings</h2> + +<ul style="margin-left: -.5em;"> + <li><a href="#heading">Tag: HEADING</a></li> + <li><a href="#head-spacing-notes">Spacing of headings</a></li> + <li><a href="#heading-control">Heading control macros and defaults</a></li> + <li><a href="#prefix-chapter-number">Prefixing chapter numbers</a></li> + <li><a href="#oldstyle-headings">Oldstyle headings</a> + <ul style="list-style-type: circle; margin-left: -1.25em"> + <li><a href="#parahead">Important information about PARAHEAD</a> + <ul style="list-style-type: square; margin-left: -1.25em"> + <li><a href="#parahead-usage">Correct usage of paraheads</a></li> + </ul></li> + </ul></li> +</ul> + +<p> +Heads, subheads, and deeper levels of section headings are +handled by a single macro, HEADING, to which you pass an argument +stating the desired level. +<kbd><span class="nobr">.HEADING 1 "<text>"</span></kbd>, +for example, would be a main head; +<kbd><span class="nobr">.HEADING 2 "<text>"</span></kbd> +would be a subhead; etc. +</p> + +<p> +In addition to printing headings in the body of your document, +HEADING collects the heading as an entry for the Table of Contents, +if the document is to have one, and the +<a href="definitions.html#pdfoutline">PDF outline</a>. +With the <kbd>NAMED</kbd> argument, it furthermore acts as a +bookmark for +<a href="definitions.html#pdflink">PDF links</a>. +</p> + +<p> +Headings can also be numbered on a per-heading-level basis, +hierarchically and concatenatively, e.g. +<br/> +<span class="pre-in-pp"> + 1. + 1.1 + 1.2 + 1.2.1 + 2. + 2.1 + 2.2 + 2.2.1 +</span> +By default, a blank line precedes headings, regardless of the level. +Mom initially sets up a very basic style for nine levels of heading, +of which you can have an infinite number, although as has been said, +if you need more than four levels of heading, you should consider +re-organising your material. The pared-down style of mom’s +defaults is intentional; it is expected that you will design +headings to your own specifications with the +<a href="definitions.html#controlmacro">control macro</a>, +<a href="#heading-style">HEADING_STYLE</a>. +</p> + +<p> +It is very good practice, and strongly recommended, that you respect +the hierarchy of headings, using level-1 for main heads, level-2 for +subheads, level-3 for subsubheads, etc. The ease of designing and +re-designing the style for each level, plus mom’s very basic +defaults, are meant, in part, to prevent the whimsical misuse of +a particular heading level just because its style appeals to you. +</p> + +<!-- -HEAD- --> + +<div class="macro-id-overline"> +<h3 id="heading" class="macro-id">HEADING</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>HEADING</b> <kbd class="macro-args"><level> [ +PARAHEAD ] [ NAMED <pdf-id> ] "<heading text>"</kbd> +</div> + +<p> +The first argument to HEADING is the <kbd>level</kbd>. Level 1 is +analogous to a main head; level 2 is analogous to a subhead; level 3 +is analogous to a subsubhead; etc. +</p> + +<p> +The second (optional) argument, <kbd>PARAHEAD</kbd>, instructs mom +that the heading should be treated as a +<a href="definitions.html#parahead">paragraph head</a>. +If HEADING is being used to create a parahead, it must come after +<a href="#pp">PP</a>, +not before. +</p> + +<p> +The indent applied to a parahead is the same as what would be +expected from a paragraph without the parahead (see +<a href="#para-indent-first">Indenting initial paragraphs</a>). +If you wish that a paragraph introduced by a parahead not be +indented, use +<a href="#para-indent">PARA_INDENT</a> +to set the paragraph indent to zero, then reset the indent for +subsequent paragraphs. +</p> + +<p> +The optional third argument, <kbd>NAMED <id></kbd>, gives +the heading a unique, non-printing identifier that allows it to be +referenced from anywhere in the final PDF document with the PDF_LINK +macro, provided the mom file is processed with +<a href="using.html#pdfmom" style="font-weight: bold">pdfmom</a>. +PDF_LINK usage is explained in the manual, +<a href="http://www.schaffter.ca/mom/pdf/mom-pdf.pdf"><span class="book-title">Producing PDFs with groff and mom</span></a>. +</p> + +<p> +The final argument is the text of the heading, surrounded by double +quotes. Long headings that are likely to exceed the current +line length should be broken into chunks, each surrounded by +double-quotes, like this: +<br/> +<span class="pre-in-pp"> + .HEADING 1 "A needlessly long but instructive" "first level heading" +</span> +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +If a heading falls near the bottom of an output page and mom is +unable to fit the heading plus at least one line of text underneath +it, she will set the head at the top of the next page. +</p> +</div> + +<div class="box-tip"> +<h3 id="head-spacing-notes" class="docs" style="padding-top: 9px; font-size: 100%; text-transform: none">Spacing of headings</h3> + +<p> +As described above, mom inserts a blank line before each heading. +If the leading of your document never changes, and you introduce no +additional space into the text—as, for example, between +paragraphs—this will result in perfectly equal whitespace before +each heading. +</p> + +<p> +If, however, you disrupt the regular placement of text on +mom’s +<a href="definitions.html#baseline-grid">baseline grid</a>, +HEADING adds extra whitespace to the blank line according to the +<a href="docprocessing.html#vertical-whitespace-management">vertical whitespace management</a> +strategy in effect. This, along with a similar strategy for +whitespace around quotes, blockquotes, and +<a href="definitions.html#float">floated</a> +and +<a href="definitions.html#preprocessor">pre-processor material</a> +is what allows mom to balance the bottom +margins of pages effectively. +</p> + +<p> +It occasionally happens that the extra whitespace becomes +noticeable. This typically occurs when the amount of whitespace +adjustment approaches the value of the current leading. The result +looks like two blank lines instead of one. When this happens, a +simple but effective fix is to reduce the space before the heading +by backing up one line, either with +<br/> +<span class="pre-in-pp"> + .SPACE -1v +</span> +or +<br/> +<span class="pre-in-pp"> + .RLD -1v +</span> +This results in slightly less whitespace than normal, but the +difference is usually not apparent. Alternatively, you may pass the +<kbd>NO_SHIM</kbd> or <kbd>NO_FLEX</kbd> argument to +<a href="#heading-style">HEADING_STYLE</a> +to prevent shimming or flex-spacing of any particular heading level +either globally or selectively. If shimming/flex-spacing is +disabled selectively with +<br/> +<span class="pre-in-pp"> + .HEADING_STYLE <n> NO_SHIM | NO_FLEX +</span> +it can be re-enabled for the heading level with +<br/> +<span class="pre-in-pp"> + .HEADING_STYLE <n> SHIM | FLEX +</span> +</p> +</div> + +<div class="defaults-container" style="background-color: #ded4bd; border: none;"> +<h3 id="heading-control" class="defaults" style="margin-left: 6px; margin-bottom: -1em">HEADING control and defaults</h3> + +<div style="padding-left: 15px; padding-right: 15px"> +<p style="margin-bottom: 1em"> +By default, mom pre-initializes nine levels of headings to use +the bold font of the prevailing document family, with a baseline +adjustment of 1/10 of the current +<a href="definitions.html#leading">leading</a>. +In addition, level-1 headings are 3 points larger than running text, +level-2 headings 2 points larger, and level 3-headings 1 point +larger. The remaining 6 levels are the same size as running text. +A single blank line precedes all levels of heading. +</p> + +<h4 id="heading-style" class="docs" style="margin-bottom: -.5em">The HEADING_STYLE macro</h4> + +<p> +Styling heads is accomplished with a single macro +<br/> +<span class="pre-in-pp"> + .HEADING_STYLE <level> +</span> +where <kbd><level></kbd> is the numeric heading level to which +the style applies. +</p> + +<p> +HEADING_STYLE takes any or all of the following arguments, +which may be given in any order: +<br/> +<span class="pre defaults"> + FAMILY <family> \ + FONT <font> \ + SIZE <+|-size> \ + QUAD <direction> \ + COLOR <colour> \ + UNDERSCORE <weight> <gap> | NO_UNDERSCORE \ + UNDERSCORE2 <weight> <gap1> <gap2> | NO_UNDERSCORE2 \ + CAPS | NO_CAPS \ + SMALLCAPS | NO_SMALLCAPS \ + BASELINE_ADJUST <amount to raise heading from the baseline> \ + NEEDS <lines of text required beneath the heading> \ + PREFIX_CHAPTER [<n>] \ + SPACE_AFTER | NO_SPACE_AFTER \ + NUMBER | NO_NUMBER \ + NO_SHIM | SHIM \ + NO_FLEX | FLEX +</span> +</p> + +<p> +You may enter your entire argument list on a single line, or, if it +is very long, break it into shorter lines with the +“line-continued” backslash (<kbd>\</kbd>), as shown +above. +</p> + +<p class="defaults" style="margin-bottom: 1em"> +The arguments to <kbd>FAMILY</kbd>, <kbd>FONT</kbd>, +<kbd>SIZE</kbd>, <kbd>QUAD</kbd>, and +<kbd>COLOR</kbd> are the same as +those you’d give to the +<a href="#docelement-control">control macros</a> +ending in _FAMILY, _FONT, _SIZE, _QUAD, or _COLOR. See +<a href="#control-macro-args">Arguments to the control macros</a>. +</p> + +<p class="defaults" style="margin-bottom: 1em"> +<kbd>UNDERSCORE</kbd> and <kbd>UNDERSCORE2</kbd> require that a +weight for the underscore be given, in points (decimal fractions +allowed), but without the unit of measure <kbd>p</kbd> appended. +They also require that the underscore’s distance from the +baseline be supplied; in the case of UNDERSCORE2, an additional gap +argument representing the distance between the two underscores must +be provided. +</p> + +<p class="defaults" style="margin-bottom: 1em"> +The <kbd>CAPS</kbd> argument capitalizes the text of a heading +level in the body of a document but not in the Table of +Contents, where capitalization of entries is controlled by +<a href="tables-of-contents.html#toc-entry-style">TOC_ENTRY_STYLE <n></a>. +</p> + +<p class="defaults" style="margin-bottom: 1em"> +<kbd>BASELINE_ADJUST</kbd> allows you to raise a heading slightly +above the baseline on which it would otherwise sit. For aesthetic +reasons, it is often desirable to introduce a small amount of space +between a heading and the text following it. Since headings are +preceded by a blank line, it is preferable to move the heading +upward than to lower the text following it. The argument to +BASELINE_ADJUST is the amount by which to raise the heading. It +requires no <kbd>+</kbd> or <kbd>-</kbd> sign, and must have a +<a href="definitions.html#unitofmeasure">unit of measure</a> +appended to it. +</p> + +<p class="defaults" style="margin-bottom: 1em"> +<kbd>NEEDS</kbd> lets you reserve the number of lines of text +required beneath a heading, including fractions thereof (e.g. +“1.5” for one line of text plus half a linespace). +If a heading falls near the bottom margin and there isn’t +sufficient room for both the heading and the reserved space, mom +will break to a new page for the heading. A +<a href="definitions.html#unitofmeasure">unit of measure</a> +should not be appended to the argument. +<span class="note"><i>Note:</i></span> If you have +<a href="goodies.html#dropcap">DROPCAP</a>s +after headings, you must increase the value of <kbd>NEEDS</kbd> +to match the number of dropcap lines. +</p> + +<p class="defaults" style="margin-bottom: 1em"> +<kbd>PREFIX_CHAPTER</kbd> instructs mom to prefix the current +chapter number to numbered headings. If mom is unable to determine +a chapter number, she will ask for one. +</p> + +<p class="defaults" style="margin-bottom: 1em"> +Note that using <kbd>PREFIX_CHAPTER</kbd> with an explicit chapter +number will also set the chapter number for subsequent +<a href="images.html#autolabel">automatically-generated image and pre-processor labels</a> +as well. +</p> + +<p class="defaults" style="margin-bottom: 1em"> +<kbd>SPACE_AFTER</kbd> inserts a blank line equal to the current +<a href="definitions.html#leading">leading</a> after a HEADING. +If you’d like a full linespace after a heading level, use +<kbd>SPACE_AFTER</kbd>. If you’d like additional space before +a heading level, you must introduce it yourself with +<a href="typesetting.html#space">SPACE</a> +or +<a href="typesetting.html#ald">ALD</a>. +</p> + +<p class="defaults" style="margin-bottom: 1em"> +<kbd>NUMBER</kbd> and <kbd>NO_NUMBER</kbd> allow you to determine +whether mom prepends a hierarchic numbering scheme to a heading +level in the body of a document. Numbering of Table of Contents +entries is controlled separately with +<a href="tables-of-contents.html#toc-entry-numbers">TOC_ENTRY_NUMBERS</a>. +Mom also has a special macro to toggle whether to prefix a chapter +number to numbered headings and Table of Contents entries, +<a href="#prefix-chapter-number">PREFIX_CHAPTER_NUMBER</a>. +</p> + +<p class="defaults" style="margin-bottom: 1em"> +<kbd>SHIM</kbd> is not necessary if shimming is enabled +globally, which it is by default; it exists to re-enable +shimming for the heading level if you have previously passed +HEADING_STYLE <kbd><n></kbd> a <kbd>NO_SHIM</kbd> +argument. The <kbd>FLEX</kbd> and <kbd>NO_FLEX</kbd> arguments work +the same way if flex-spacing is enabled. +</p> + +<p class="defaults" style="padding-bottom: .5em"> +The argument list is long, so you may want to break it into +several lines by using the backslash character (<kbd>\</kbd>). +Here’s an example of how you might style a level 1 heading: +<br/> +<span class="pre defaults"> + .HEADING_STYLE 1 \ + FONT B \ + QUAD C \ + UNDERSCORE .5 2p \ + BASELINE_ADJUST 3p \ + NUMBER +</span> +This creates a level-1 heading style that’s bold, centred, +underscored and numbered, raised by 3 points from the baseline. +</p> +</div> +</div> + +<!-- -PREFIX_CHAPTER_NUMBER- --> + +<div id="prefix-chapter-number" class="macro-id-overline" style="margin-top: -1em;"> +<h3 class="macro-id" style="text-transform: none; font-size: 105%;">Prefixing chapter numbers</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>PREFIX_CHAPTER_NUMBER</b> <kbd class="macro-args"><none> | <chapter number as digit> | <anything></kbd> +</div> + +<p> +If, in addition to numbering heads, you want mom to prepend the +chapter number, invoke <kbd>.PREFIX_CHAPTER_NUMBER</kbd>. +</p> + +<p> +When you invoke <kbd>.PREFIX_CHAPTER_NUMBER</kbd> without an +argument, mom checks to see whether the argument you passed to <a +href="docprocessing.html#chapter">CHAPTER</a> (if it’s been +called) is a digit. If it isn’t (say you’ve numbered your +chapter “One” instead of “1”), mom will +abort with a request that you pass PREFIX_CHAPTER_NUMBER a digit +representing the chapter number. +</p> + +<p> +After you invoke <kbd>.PREFIX_CHAPTER_NUMBER</kbd>, mom will prepend +the chapter number to all headings you have requested be numbered +with +<a href="#heading-style"><kbd>.HEADING_STYLE <n> NUMBER</kbd></a>. +Thus, assuming chapter number twelve (12): +<br/> +<span class="pre-in-pp"> + 1. LEVEL 1 HEADING + 1.1. Level 2 heading +</span> +would become +<br/> +<span class="pre-in-pp"> + 12.1. LEVEL 1 HEADING + 12.1.1. Level 2 heading +</span> +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +If a chapter number is given to PREFIX_CHAPTER_NUMBER, automatically +generated labels with a prepended chapter number are also affected. +</p> +</div> + +<p> +In collated documents, mom automatically increments the digit used +by PREFIX_CHAPTER_NUMBER by one (current chapter digit + 1) every +time you invoke +<a href="rectoverso.html#collate"><kbd>.COLLATE</kbd></a>, +even if you’ve (temporarily) turned off the prefixing +of chapter numbers. Thus, even if you number your chapters +“One”, “Two”, “Three” instead of +“1”, “2”, “3”, mom will Do The +Right Thing with respect to numbering head (and label) elements +in all collated chapters following the first invocation of +PREFIX_CHAPTER_NUMBER (assuming, of course, that the collated +chapters are in incrementing order; if not, you must put +<br/> +<span class="pre-in-pp"> + .PREFIX_CHAPTER_NUMBER <chapter number> +</span> +somewhere after the invocation of COLLATE and before the first +numbered head element of each collated document). +</p> + +<p> +PREFIX_CHAPTER_NUMBER can be disabled by passing it any argument +other than a digit (e.g. (<kbd>OFF</kbd>, <kbd>QUIT</kbd>, <kbd>Q</kbd>, +<kbd>X</kbd>...), although, as noted above, mom will keep, +and—in the case of collated documents—increment the +chapter number, allowing you to turn prefixing of chapter numbers to +numbered head elements off and on according to your needs or whims. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +Because PREFIX_CHAPTER_NUMBER takes an (optional) digit representing +the chapter number, it’s use need not be restricted to +<a href="docprocessing.html#doctype">DOCTYPE <kbd>CHAPTER</kbd></a>. +You can use it with any document type. Furthermore, even if +your doctype isn’t <kbd>CHAPTER</kbd>, you can identify +the document as a chapter for the purposes of numbering head +elements by invoking the macro +<a href="docprocessing.html#chapter"><kbd>.CHAPTER</kbd></a> +with a +<a href="definitions.html#numericargument">numeric argument</a> +in your document setup. +</p> +</div> +<div class="rule-short"><hr/></div> + +<!-- ==================================================================== --> + +<h2 id="oldstyle-headings-intro" class="macro-group">Oldstyle headings</h2> + +<ul style="margin-left: -.5em;"> + <li><a href="#oldstyle-headings">Macro: OLDSTYLE_HEADINGS</a></li> + <li><a href="#head">Macro: HEAD</a></li> + <li><a href="#subhead">Macro: SUBHEAD</a></li> + <li><a href="#subsubhead">Macro: SUBSUBHEAD</a></li> +</ul> + +<p> +In versions of mom prior to 2.0, headings were entered by their +commonly used names, <i>viz.</i> HEAD, SUBHEAD, and SUBSUBHEAD. The +new +<a href="#heading-intro">HEADING</a> +scheme allows for greater flexibility, and permits seamless +integration with PDF output. +</p> + +<p> +Documents created with pre-2.0 versions may still use the oldstyle +heading names, as may new documents, however there are some +differences in their behaviour. +</p> + +<p> +Whenever mom encounters an oldstyle heading, she loads the default +style formerly associated with the oldstyle name. See below for a +description of the default styles in the sections +<a href="#head">HEAD</a> (now HEADING 1), +<a href="#subhead">SUBHEAD</a> (now HEADING 2), +and +<a href="#subsubhead">SUBSUBHEAD</a> (now HEADING 3). +Mom also emits a message to stderr alerting you to what she’s +doing. +</p> + +<p> +The control macros formerly associated with oldstyle headings are no +longer present in mom’s macro file, which means that if you +made changes to mom’s default for those headings, you must +recreate the changes with the +<a href="#heading-style">HEADING_STYLE</a> +macro. The entire style need not be recreated, only those +parameters that differed from mom’s defaults. Thus, if your +HEADs were set flush left, instead of the oldstyle default, centred, +but otherwise kept mom’s settings, you need only do +<br/> +<span class="pre-in-pp"> + .HEADING_STYLE 1 QUAD L +</span> +</p> + +<div id="parahead" class="box-important"> +<p class="tip-top"> +<span class="important">Important:</span> +The macro PARAHEAD is no longer available. You must create paragraph +heads using the +<a href="#heading">HEADING</a> +macro. Mom will abort with an informational message whenever she +encounters PARAHEAD. Assuming a heading level of 3 for your +paraheads, the former defaults for PARAHEAD can be set up like this: +<br/> +<span class="pre-in-pp"> + .HEADING STYLE 3 FONT BI SIZE -.25 \" For PRINTSTYLE TYPESET + .HEADING STYLE 3 FONT I SIZE +0 \" For PRINTSTYLE TYPEWRITE +</span> +Equally, the macro NUMBER_PARAHEADS is no longer available. You +must enable numbering of the correct level for paraheads with +HEADING_STYLE. Again assuming a heading level of 3 for paraheads, +it’s simply done: +<br/> +<span class="pre-in-pp"> + .HEADING_STYLE 3 NUMBER +</span> +</p> + +<h3 id="parahead-usage" class="docs" style="text-transform: none; margin-top: -1em">Correct usage of paraheads</h3> + +<p style="margin-top: .5em"> +It is tempting to choose an arbitrary heading level for paraheads, +since they are sometimes needed out-of-sequence; for example, +immediately after a main head (level-1) in a document that +subsequently requires subheads (level-2). In such a circumstance, +choosing level-3 for all your paraheads might seem to make sense, +but in fact doesn’t, since it disrupts the hierarchy of +both the Table of Contents (if your document has one) and the PDF +outline. +</p> + +<p> +Correct use of the <kbd>PARAHEAD</kbd> option to HEADING under such +circumstances requires always assigning <kbd>PARAHEAD</kbd> to +the next logical level in the heading hierarchy. For example, if +there are no headings before the parahead, it should be assigned to +level-1. If subsequently there is a main head to be followed by +more paraheads, the main head should be level-1, and the paraheads +level-2. This will almost certainly require assigning new style +parameters to level-1 (with +<a href="#heading-style">HEADING_STYLE</a>) +and to the level now being used for paraheads. The following +example demonstrates. +<br/> +<span class="pre-in-pp"> + .HEADING_STYLE 1 FONT BI SIZE +.25 \" parahead style, level-1 + .PP + .HEADING 1 PARAHEAD <parahead> + <paragraph text> + .PP + .HEADING 1 PARAHEAD <parahead> + <paragraph text> + \# main head style, level-1 + .HEADING_STYLE 1 FONT B SIZE +3 QUAD CENTER UNDERSCORE .5 2p + .HEADING_STYLE 2 FONT BI SIZE +.25 \" parahead style, level-2 + .HEADING 1 <main head> + .PP + <paragraph text> + .PP + .HEADING 2 PARAHEAD <parahead> + <paragraph text> +</span> +</p> +</div> + +<!-- -OLDSTYLE_HEADINGS - --> + +<div class="macro-id-overline"> +<h3 id="oldstyle-headings" class="macro-id">OLDSTYLE HEADINGS</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>OLDSTYLE_HEADINGS</b> +</div> + +<p> +OLDSTYLE_HEADINGS requires no argument. It instructs mom to set the +first three levels of heading to the parameters of her old defaults +for HEAD, SUBHEAD, and SUBSUBHEAD. Use of OLDSTYLE_HEADINGS will +also prevent mom from generating the message she issues the first +time she encounters HEAD, SUBHEAD, and SUBSUBHEAD. +</p> + +<!-- -HEAD- --> + +<div id="head" class="box-macro-args"> +Macro: <b>HEAD</b> <kbd class="macro-args">[ NAMED <id> ] "<text of head>" "<another line>"...</kbd> +</div> + +<p> +When invoked for the first time, with or without +<a href="oldstyle-headings">OLDSTYLE_HEADINGS</a>, +HEAD sets the parameters for level-1 headings to mom’s old +HEAD defaults, then prints the head as a level-1 heading. +The <kbd>NAMED <id></kbd> optional argument is explained in +the description of +<a href="#heading">HEADING</a>. +</p> + +<p> +If, prior to invoking HEAD, you have given any parameters to level-1 +heads with +<a href="#heading-style">HEADING STYLE</a>, +they will be preserved; any you give afterwards will be respected. +</p> + +<p> +The former style defaults for HEAD were: +<br/> +<span class="pre-in-pp"> + FAMILY = prevailing document family + FONT = bold (TYPESET); roman (TYPEWRITE) + SIZE = +1 (TYPESET); +0 (TYPEWRITE) + QUAD = C + UNDERSCORE .5 2p + CAPS +</span> +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +The macro NUMBER_HEADS from pre-2.0 versions of mom, can still be +used, though it is now a wrapper for +<br/> +<span class="pre-in-pp"> + .HEADING_STYLE 1 NUMBER +</span> +Mom will alert you to this on stderr. +</p> +</div> + +<!-- -SUBHEAD- --> + +<div id="subhead" class="box-macro-args"> +Macro: <b>SUBHEAD</b> <kbd class="macro-args">[ NAMED <id> ] "<text of head>" "<another line>"...</kbd> +</div> + +<p> +When invoked for the first time, with or without +<a href="oldstyle-headings">OLDSTYLE_HEADINGS</a>, +SUBHEAD sets the parameters for level-2 headings to mom’s old +SUBHEAD defaults, then prints the subhead as a level-2 heading. +The <kbd>NAMED <id></kbd> optional argument is explained in +the description of +<a href="#heading">HEADING</a>. +</p> + +<p> +The former style defaults for SUBHEAD were: +<br/> +<span class="pre-in-pp"> + FAMILY = prevailing document family + FONT = bold (TYPESET); italic, i.e. underlined (TYPEWRITE) + SIZE = +.5 (TYPESET); +0 (TYPEWRITE) + QUAD = L + BASELINE_ADJUST = 1/8 the current leading +</span> +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +The macro NUMBER_SUBHEADS from pre-2.0 versions of mom, can still be +used, though it is now a wrapper for +<br/> +<span class="pre-in-pp"> + .HEADING_STYLE 2 NUMBER +</span> +Mom will alert you to this on stderr. +</p> +</div> + +<!-- -SUBSUBHEAD- --> + +<div id="subsubhead" class="box-macro-args"> +Macro: <b>SUBSUBHEAD</b> <kbd class="macro-args">[ NAMED <id> ] "<text of head>" "<another line>"...</kbd> + +</div> + +<p> +When invoked for the first time, with or without +<a href="oldstyle-headings">OLDSTYLE_HEADINGS</a>, +SUBSUBHEAD sets the parameters for level-3 headings to mom’s old +SUBSUBHEAD defaults, then prints the subsubhead as a level-3 heading. +The <kbd>NAMED <id></kbd> optional argument is explained in +the description of +<a href="#heading">HEADING</a>. +</p> + +<p> +The former style defaults for SUBSUBHEAD were: +<br/> +<span class="pre-in-pp"> + FAMILY = prevailing document family + FONT = italic (TYPESET); roman (TYPEWRITE) + SIZE = +.5 (TYPESET); +0 (TYPEWRITE) + QUAD = L + BASELINE_ADJUST = 1/8 the current leading +</span> +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +The macro NUMBER_SUBSUBHEADS from pre-2.0 versions of mom, can still be +used, though it is now a wrapper for +<br/> +<span class="pre-in-pp"> + .HEADING_STYLE 3 NUMBER +</span> +Mom will alert you to this on stderr. +</p> +</div> + +<div class="rule-short"><hr/></div> + +<!-- ==================================================================== --> + +<h2 id="linebreak-intro" class="macro-group">Linebreaks (section breaks)</h2> + +<ul style="margin-left: -.5em;"> + <li><a href="#linebreak">Tag: LINEBREAK</a></li> + <li><a href="#linebreak-control">Linebreak control macros and defaults</a></li> +</ul> + +<p> +Linebreaks (“author linebreaks”, “section +breaks”) are gaps in the vertical flow of running text that +indicate a shift in content (e.g. a scene change in story). They +are frequently set off by typographic symbols, sometimes whimsical +in nature. +</p> + +<!-- -LINEBREAK- --> + +<div class="macro-id-overline"> +<h3 id="linebreak" class="macro-id">LINEBREAK</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>LINEBREAK</b> +</div> +<p class="alias" style="margin-bottom: 0;"> +<i>Alias:</i> <b>SECTION</b> +</p> + +<p> +LINEBREAK takes no arguments. Simply invoke it (on a line by +itself, of course) whenever you want to insert an author linebreak. +</p> + +<div class="defaults-container" style="background-color: #ded4bd; border: none;"> +<h3 id="linebreak-control" class="docs defaults">LINEBREAK control macros and defaults</h3> + +<p class="defaults"> +By default, mom marks +<a href="definitions.html#linebreak">author linebreaks</a> +with three centred asterisks (stars) in the prevailing colour of the +document (by default, black). You can alter this with the control +macros +</p> +<ol style="margin-top: .5em; padding-bottom: .5em;"> + <li><a href="#linebreak-char">LINEBREAK_CHAR</a></li> + <li><a href="#linebreak-color">LINEBREAK_COLOR</a></li> +</ol> +</div> + +<h4 id="linebreak-char" class="docs" style="margin-top: -1.5em; margin-bottom: .5em;">1. Linebreak character</h4> +<div class="box-macro-args"> +Macro: <b>LINEBREAK_CHAR</b> <kbd class="macro-args">[ <character> ] [ <iterations> [ <vertical adjustment> ] ]</kbd> +</div> + +<p class="alias" style="margin-bottom: 0;"> +<i>Alias:</i> <b>SECTION_CHAR</b> +</p> +<p class="requires"> +• The third optional argument requires a +<a href="definitions.html#unitofmeasure">unit of measure</a>. +</p> + +<p> +LINEBREAK_CHAR determines what mom prints when LINEBREAK is invoked. +It takes 3 optional arguments: the character you want deposited at +the line break, the number of times you want the character repeated, +and a vertical adjustment factor. +</p> + +<p> +The first argument is any valid groff character (e.g. <kbd>*</kbd> +[an asterisk], <kbd>\[dg]</kbd> [a dagger], <kbd>\f[ZD]\N'141'\fP</kbd> +[an arbitrary character from Zapf Dingbats], <kbd>\l'4P'</kbd> [a +4-pica long rule]). Mom sets the character centred on the current +line length. (See <kbd>man groff_char</kbd> for a list of all +valid groff characters.) +</p> + +<p> +The second argument is the number of times to repeat the character. +</p> + +<p> +The third argument is a +|-value by which to raise (-) or lower (+) +the character in order to make it appear visually centred between +sections of text. This lets you make vertical adjustments to +characters that don’t sit on the +<a href="definitions.html#baseline">baseline</a> +(such as asterisks). The argument must be preceded by a plus or +minus sign, and must include a unit of measure. +</p> + +<p> +If you enter LINEBREAK_CHAR with no arguments, sections of +text will be separated by two blank lines when you invoke +<kbd>.LINEBREAK</kbd>. +</p> + +<p> +Mom’s default for LINEBREAK_CHAR is +<br/> +<span class="pre-in-pp"> + .LINEBREAK_CHAR * 3 -3p +</span> +i.e. three asterisks, raised 3 points from their normal vertical +position (for +<a href="docprocessing.html#printstyle">PRINTSTYLE <kbd>TYPESET</kbd></a>; +the vertical adjustment is -2 points for +<a href="docprocessing.html#printstyle">PRINTSTYLE <kbd>TYPEWRITE</kbd></a>). +</p> + +<h4 id="linebreak-color" class="docs" style="margin-top: -.25em; margin-bottom: .5em;">2. Linebreak colour</h4> + +<div class="box-macro-args"> +Macro: <b>LINEBREAK_COLOR</b> <kbd class="macro-args"><colourname></kbd> +</div> +<p class="alias" style="margin-bottom: 0;"> +<i>Alias:</i> <b>SECTION_COLOR</b> +</p> + +<p> +To change the colour of the linebreak character(s), simply invoke +<kbd>.LINEBREAK_COLOR</kbd> with the name of a colour pre-defined +(or “initialized”) with +<a href="color.html#newcolor">NEWCOLOR</a> +or +<a href="color.html#xcolor">XCOLOR</a>. + +</p> + +<div class="rule-short"><hr/></div> + +<!-- ==================================================================== --> + +<h2 id="quote-intro" class="macro-group">Quotes (line for line, poetry or code)</h2> + +<ul style="margin-left: -.5em;"> + <li><a href="#quote-description">Introduction</a> + <ul style="margin-left: -1.25em"> + <li><a href="#quote-spacing">Quote spacing</a> + <ul style="margin-left: -1.25em"> + <li><a href="#quote-spacing-notes">Notes on quote spacing</a></li> + </ul></li> + <li><a href="#no-shim">Disable shimming of quotes and blockquotes</a></li> + <li><a href="#float-quote">Keeping quotes and blockquotes together as a block</a></li> + <li><a href="#label-caption">Labelling/captioning quotes and blockquotes</a></li> + </ul></li> + <li><a href="#quote">Tag: QUOTE</a></li> + <li><a href="#quote-control">Quote control macros and defaults</a></li> +</ul> + +<p id="quote-decription"> +<a href="definitions.html#quote">Quotes</a> +are always set in +<a href="definitions.html#filled">nofill mode</a>, +flush left. This permits entering quotes on a line for line basis +in your text editor and have them come out the same way on output +copy. (See +<a href="#blockquote-intro">Blockquotes</a> +for how quotes, in the present sense, differ from longer passages of +cited text.) +</p> + +<p> +Since mom originally came into being to serve the needs of creative +writers (i.e. novelists, short story writers, etc.—not +to cast aspersions on the creativity of mathematicians and +programmers), she sets quotes in italics +<a href="docprocessing.html#printstyle">(PRINTSTYLE <kbd>TYPESET</kbd>)</a> +or underlined +<a href="docprocessing.html#printstyle">(PRINTSTYLE <kbd>TYPEWRITE</kbd>)</a>, +indented from the left margin. Obviously, she’s thinking +“quotes from poetry or song lyrics”, but with the +<a href="#quote-control">QUOTE control macros</a> +you can change her defaults so QUOTE serves other needs, e.g. +entering verbatim snippets of programming code, command-line +instructions, and so on. (See the +<a href="#code">CODE</a> +for a convenience macro to assist in including code snippets in +documents.) +</p> + +<h3 id="quote-spacing" class="docs">QUOTE spacing</h3> + +<p> +Besides indenting quotes, mom further sets them off from +<a href="definitions.html#running">running text</a> +with a small amount of vertical whitespace top and bottom. In +<a href="docprocessing.html#printstyle">PRINTSTYLE <kbd>TYPEWRITE</kbd></a>, +this is always one full linespace. In +<a href="docprocessing.html#printstyle">PRINTSTYLE <kbd>TYPESET</kbd></a>, +it’s 1/2 of the prevailing +<a href="definitions.html#leading">leading</a> +if the quote fits fully on the page (i.e. with running text above +and below it), otherwise it’s a full linespace either above +or below as is necessary to balance the page to the bottom margin. +This behaviour can be changed with the control macro +<a href="#always-fullspace-quotes">ALWAYS_FULLSPACE_QUOTES</a>. +</p> + +<div class="box-tip"> +<h3 id="quote-spacing-notes" class="docs" style="padding-top: 9px; font-size: 95%;">Notes on quote spacing</h3> + +<p style="margin-top: .5em"> +If your quote (or blockquote) leading differs from the document +leading, mom attempts to observe the same rules for vertical +whitespace outlined above; however, she will also insert a small, +flexible amount of extra whitespace +(<a href="docprocessing.html#shim-vs-flex">shim or flex-spacing</a>) +around the quotes to make sure the whitespace is equal, top and +bottom. When shimming is enabled, this may result in multiple +quotes or blockquotes on the same page being spaced slightly +differently. +</p> + +<h4 id="no-shim" class="docs">Disable shimming/flex-spacing of quotes and blockquotes</h4> + +<p class="tip-bottom"> +If you don’t want the behaviour +described above (i.e., you don’t want mom putting additional shim +or flex-spacing around quotes and +blockquotes), put <kbd>.NO_SHIM</kbd> or/and <kbd>.NO_FLEX</kbd> +in the style sheet section of your document (i.e. after PRINTSTYLE +but before START), which will disable shimming or/and flex-spacing +globally for all tags, or disable shimming/flex-spacing +on a per-instance basis prior to <kbd>.QUOTE</kbd> or +<kbd>.BLOCKQUOTE</kbd>, re-enabling it after the terminating +<kbd>.QUOTE OFF</kbd> or <kbd>.BLOCKQUOTE OFF</kbd> with +<kbd>.NO_SHIM OFF</kbd> or <kbd>.NO_FLEX OFF</kbd>. +</p> + +</div> + +<h3 id="float-quote" class="docs">Keeping QUOTEs and BLOCKQUOTEs together as a block</h3> + +<p> +The text of quotes and blockquotes is output immediately, and may therefore +start on one page and finish on the next. If you wish to keep the +text together as a block, deferred to the following page if the +block doesn’t all fit on one page, wrap +<kbd><span class="nobr">(BLOCK)QUOTE...(BLOCK)QUOTE OFF</span></kbd> +inside a +<a href="images.html#floats-intro">float</a>. +If you further wish to force a page break before the floated quote +or blockquote (leaving whitespace at the bottom of the page, pass +<a href="images.html#float">FLOAT</a> +the <kbd>FORCE</kbd> argument. +<span class="pre-in-pp"> + .FLOAT FORCE + .QUOTE + Fly me to the moon + And let me play among the stars + Let me see what life is like + On Jupiter and Mars + .QUOTE END + .FLOAT OFF +</span> +</p> + +<h3 id="label-caption" class="docs">Labelling/captioning quotes and blockquotes</h3> + +<p> +Quotes and blockquotes may be labelled and/or captioned identically to +<a href="images.html#floats-intro">floats</a> +with the macros +<a href="images.html#label">LABEL</a> +and +<a href="images.html#caption">CAPTION</a> +(see +<a href="images.html#float-label-caption">Labelling and captioning floats</a>). +</p> + +<!-- -QUOTE- --> + +<div class="macro-id-overline"> +<h3 id="quote" class="macro-id">QUOTE</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>QUOTE</b> <kbd class="macro-args">[ ADJUST +|-<space> ] | <anything></kbd> +</div> +<p class="requires"> +• The argument to <kbd style="font-style: normal">ADJUST</kbd> requires a +<a href="definitions.html#unitofmeasure">unit of measure</a> +</p> + +<p> +QUOTE is a toggle macro. To begin a section of quoted text, invoke +it with no argument, then type in your quote. When you’re +finished, invoke <kbd>.QUOTE</kbd> with any argument (e.g. <kbd>OFF, +END, X, Q</kbd>...) to turn it off. Example: +<br/> +<span class="pre-in-pp"> + .QUOTE + Nymphomaniacal Jill + Used a dynamite stick for a thrill + They found her vagina + In North Carolina + And bits of her tits in Brazil. + .QUOTE END +</span> +Mom does her best to equalize whitespace around quotes and make +sure the line following it falls on a valid baseline. On occasion, +you may need to tweak the quote placement slightly, which is done +by passing <kbd>ADJUST</kbd> to QUOTE with a plus or minus value. +The quote will be lowered (<kbd>+</kbd>) or raised (<kbd>-</kbd>) +<i>within the space allotted for it</i> by the given amount. For +example, to lower a quote slightly within the space allotted for it, +you’d do +<br/> +<span class="pre-in-pp"> + .QUOTE ADJUST +3p + There was a soprano named Golda + Whose lovers grew colda and colda + For during love-making + She'd sing the earth-shaking + Love theme from Tristan und Isolde. + .QUOTE off +</span> +</p> + +<div class="defaults-container" style="background-color: #ded4bd; border: none;"> + +<h3 id="quote-control" class="docs defaults">QUOTE control macros and defaults</h3> + +<ol style="margin-top: .5em; padding-bottom: .5em;"> + <li><a href="#quote-general">Family/font/size/leading/colour/indent</a></li> + <li><a href="#always-fullspace-quotes">Spacing above and below quotes (typeset only)</a></li> + <li><a href="#underline-quotes">Underlining quotes (typewrite only)</a></li> +</ol> +</div> + +<h4 id="quote-general" class="docs" style="margin-top: -1.5em; margin-bottom: .5em;">1. Family/font/size/colour/indent</h4> + +<div class="defaults-container" style="padding-bottom: 8px;"> +<p class="defaults" style="padding-top: 6px;"> +See +<a href="#control-macro-args">Arguments to the control macros</a>. +<br/> +The following QUOTE control macros may also be +<a href="#grouping">grouped</a> +using QUOTE_STYLE. If you do so, <kbd>QUOTE_LEFT</kbd>, <kbd>QUOTE_CENTER</kbd>, +and <kbd>QUOTE_RIGHT</kbd> must be entered as: +<br/> +<kbd> QUAD LEFT</kbd><br/> +<kbd> QUAD CENTER</kbd><br/> +<kbd> QUAD RIGHT</kbd> +</p> + +<span class="pre defaults"> +.QUOTE_FAMILY default = prevailing document family; default is Times Roman +.QUOTE_FONT default = italic; underlined in TYPEWRITE +.QUOTE_SIZE default = +0 (i.e. same size as paragraph text) +<a id="quote-autolead">.QUOTE_AUTOLEAD default = none; leading of quotes is the same as paragraphs </a> +.QUOTE_COLOR default = black +.QUOTE_INDENT (see below, "Quote indent") +.QUOTE_LEFT -+ Quad direction of quote. +.QUOTE_CENTER | LEFT observes QUOTE_INDENT; +.QUOTE_RIGHT -+ CENTER and RIGHT do not +</span> +</div> + +<h4 id="quote-indent" class="docs" style="margin-top: -1.5em;">Quote indent</h4> + +<p> +<kbd>QUOTE_INDENT</kbd> takes one of two kinds of argument: an integer +representing the amount by which to multiply the argument passed to +<a href="#para-indent"><kbd>.PARA_INDENT</kbd></a> +(by default, 2 +<a href="definitions.html#em">ems</a> +for TYPESET, 3 +<a href="definitions.html#picaspoints">picas</a> +for TYPEWRITE) to arrive at the quote indent, or a distance with a +<a href="definitions.html#unitofmesaure">unit of measure</a> +appended. +</p> + +<p> +Be careful when using QUOTE. If a quote is set flush left (the +default), the QUOTE_INDENT applies only to the left margin. Because +quote lines are output as-is (see +<a href="definitions.html#no-fill">no-fill mode</a>), +they do not respect line length and may extend beyond a document's +right margin. Similarly, if a quote is being set flush right, the +indent applies only to the right margin; long lines may extend into +the left margin. Centered quotes are never indented, so long lines +may extend beyond both the left and right margins. +</p> + +<p> +The default value for QUOTE_INDENT is 3 (for +<a href="docprocessing.html#printstyle">PRINTSTYLE <kbd>TYPESET</kbd></a>) +and 1 (for +<a href="docprocessing.html#printstyle">PRINTSTYLE <kbd>TYPEWRITE</kbd></a>). +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +If your PARA_INDENT is 0 (i.e. no indenting of the first line of +paragraphs), you <i>must</i> set a QUOTE_INDENT yourself, with a +unit of measure appended to the argument. Mom has no default for +QUOTE_INDENT if paragraph first lines are not being indented. +</p> +</div> + +<h4 id="always-fullspace-quotes" class="docs" style="margin-top: -.25em;">2. Spacing above and below quotes (typeset only)</h4> + +<p> +If you’d like mom always to put a full linespace above and +below quotes, invoke +<br/> +<span class="pre-in-pp"> + .ALWAYS_FULLSPACE_QUOTES +</span> +with no argument. If you wish to restore mom’s +default behaviour regarding the spacing of quotes (see +<a href="#quote-spacing">Quote spacing</a>), +invoke the macro with any argument (<kbd>OFF</kbd>, <kbd>QUIT</kbd>, +<kbd>END</kbd>, <kbd>X</kbd>...) +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +This macro also sets mom’s spacing policy for +<a href="#blockquote-intro">blockquotes</a>. +</p> +</div> + +<h4 id="underline-quotes" class="docs" style="margin-top: -.25em;">3. Underlining quotes (typewrite only)</h4> + +<p> +By default in +<a href="docprocessing.html#printstyle">PRINTSTYLE TYPEWRITE</a>, +mom underlines quotes. If you’d rather she didn’t, +invoke <kbd>.UNDERLINE_QUOTES</kbd> with any argument +(<kbd>OFF</kbd>, <kbd>QUIT</kbd>, <kbd>END</kbd>, <kbd>X</kbd>...) +to disable the feature. Invoke it without an argument to restore +mom’s default underlining of quotes. +</p> + +<p> +If you not only wish that mom not underline quotes, but also that +she set them in italic, you must follow each instance of QUOTE with +the typesetting macro +<a href="typesetting.html#font">FT I</a>. +Furthermore, since mom underlines all instances of italics by +default in PRINTSTYLE TYPEWRITE, you must also make sure that +ITALIC_MEANS_ITALIC is enabled (see +<a href="docprocessing.html#typewrite-control">PRINTSTYLE TYPEWRITE control macros</a>). +</p> + +<div class="rule-short"><hr/></div> + +<!-- ==================================================================== --> + +<h2 id="blockquote-intro" class="macro-group">Blockquotes (cited material)</h2> + +<ul style="margin-left: -.5em;"> + <li><a href="#blockquote-description">Introduction</a></li> + <li><a href="#blockquote">Tag: BLOCKQUOTE</a></li> + <li><a href="#blockquote-control">BLOCKQUOTE control macros</a></li> +</ul> + +<p id="blockquote-description"> +<a href="definitions.html#blockquote">Blockquotes</a> +are used to cite passages from another author’s work. So that +they stand out well from +<a href="definitions.html#running">running text</a>, +mom indents them from both the left and right margins and sets them +in a different point size +(<a href="docprocessing.html#printstyle">PRINTSTYLE TYPESET</a> +only). +<a href="definitions.html#outputline">Output lines</a> +are +<a href="definitions.html#filled">filled</a>, +and, by default, +<a href="definitions.html#quad">quadded</a> +left. +</p> + +<p> +Besides indenting blockquotes, mom further sets them off from +running text with a small amount of vertical whitespace top and +bottom. (See +<a href="#quote-spacing">Quote spacing</a> +for a complete explanation of how this is managed, and how +to control it.) +</p> + +<p> +Additional information concerning blockquotes, floats, and labelling +blockquotes can be found in the sections +<a href="#float-quote">Keeping quotes and blockquotes together as a block</a>, +and +<a href="#label-caption">Labelling/captioning quotes and blockquotes</a>. +</p> + +<!-- -BLOCKQUOTE- --> + +<div class="macro-id-overline"> +<h3 id="blockquote" class="macro-id">BLOCKQUOTE</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>BLOCKQUOTE</b> <kbd class="macro-args">[ ADJUST +|-<space> ] | <anything></kbd> +</div> + +<p class="alias" style="margin-bottom: 0;"> +<i>Aliases: </i> <b>CITE, CITATION</b> +</p> + +<p class="requires"> +• The argument to <kbd style="font-style: normal">ADJUST</kbd> requires a +<a href="definitions.html#unitofmeasure">unit of measure</a> +</p> + +<p> +BLOCKQUOTE is a toggle macro. To begin a cited passage, invoke +the tag with no argument, then type in your blockquote. When +you’re finished, invoke <kbd>.BLOCKQUOTE</kbd> with any +argument (e.g. <kbd>OFF, END, X, Q</kbd>...) to turn it off. +Example: +<br/> +<span class="pre-in-pp"> + .BLOCKQUOTE + Redefining the role of the United States from enablers to keep + the peace to enablers to keep the peace from peacekeepers is + going to be an assignment. + .RIGHT + \[em]George W. Bush + .BLOCKQUOTE END +</span> +If the cited passage runs to more than one paragraph, you must +introduce each paragraph—including the first—with +<kbd><a href="#pp">.PP</a></kbd>. +</p> + +<p> +Mom does her best to equalize whitespace around blockquotes and make +sure the line following it falls on a valid baseline. On occasion, +you may need to tweak the blockquote placement slightly, which is +done by passing <kbd>ADJUST</kbd> to BLOCKQUOTE with a plus or minus +value. The blockquote will be lowered (<kbd>+</kbd>) or raised +(<kbd>-</kbd>) <i>within the space allotted for it</i> by the given +amount. For example, to raise a blockquote slightly within the +space allotted for it, you’d do +<br/> +<span class="pre-in-pp"> + .BLOCKQUOTE ADJUST -3p + True! - nervous - very, very dreadfully nervous I had been and + am; but why will you say that I am mad? The disease had sharpened + my senses - not destroyed - not dulled them. + .RIGHT + \[em]Edgar Allen Poe, The Tell-Tale Heart + .QUOTE off +</span> +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +The aliases CITE and CITATION may be used in place of the BLOCKQUOTE +tag, as well as in any of the control macros that begin or end with +BLOCKQUOTE_. +</p> +</div> + +<div class="defaults-container" style="background-color: #ded4bd; border: none;"> +<h3 id="blockquote-control" class="docs defaults">BLOCKQUOTE control macros and defaults</h3> + +<ol style="margin-top: .5em; padding-bottom: .5em;"> + <li><a href="#blockquote-general">Family/font/size/leading/colour/quad/indent</a></li> + <li><a href="#bq-always-fullspace-quotes">Spacing above and below (typeset only)</a></li> +</ol> +</div> + +<h4 id="blockquote-general" class="docs" style="margin-top: -1.5em; margin-bottom: .5em;">1. Family/font/size/colour/quad/indent</h4> + +<div class="defaults-container" style="padding-bottom: 8px;"> +<p class="defaults" style="padding-top: 6px;"> +See +<a href="#control-macro-args">Arguments to the control macros</a>. +<br/> +The following BLOCKQUOTE control macros may also be +<a href="#grouping">grouped</a> +using BLOCKQUOTE_STYLE. +</p> +<span class="pre defaults"> +.BLOCKQUOTE_FAMILY default = prevailing document family; default is Times Roman +.BLOCKQUOTE_FONT default = roman +.BLOCKQUOTE_SIZE default = -1 (point) +<a id="blockquote-autolead">.BLOCKQUOTE_AUTOLEAD default = none; leading of blockquotes is the same as paragraphs</a> +.BLOCKQUOTE_COLOR default = black +.BLOCKQUOTE_QUAD default = left +.BLOCKQUOTE_INDENT (see below) +</span> +</div> + +<h4 id="blockquote-indent" class="docs" style="margin-top: -1.5em;">Blockquote indent</h4> + +<p> +<kbd>BLOCKQUOTE_INDENT</kbd> takes one of two kinds of argument: an +integer representing the amount by which to multiply the argument +passed to +<a href="#para-indent">PARA_INDENT</a> +(by default, 2 +<a href="definitions.html#em">ems</a> +for TYPESET, 3 +<a href="definitions.html#picaspoints">picas</a> +for TYPEWRITE) to arrive at the blockquote indent, or a distance with a +<a href="definitions.html#unitofmesaure">unit of measure</a> +appended. Both result in blockquotes being indented equally from +the left and right margins. +</p> + +<p> +The default value for BLOCKQUOTE_INDENT is 3 (for +<a href="docprocessing.html#printstyle">PRINTSTYLE <kbd>TYPESET</kbd></a>) +and 1 (for +<a href="docprocessing.html#printstyle">PRINTSTYLE <kbd>TYPEWRITE</kbd></a>). +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +If your PARA_INDENT is 0 (i.e. no indenting of the first line of +paragraphs), you must set a BLOCKQUOTE_INDENT yourself, with +a unit of measure appended to the argument. Mom has no default for +BLOCKQUOTE_INDENT if paragraph first lines are not being indented. +</p> +</div> + + + +<h4 id="bq-always-fullspace-quotes" class="docs">2. Spacing above and below blockquotes (typeset only)</h4> + +<p> +If you’d like mom always to put a full linespace above and +below blockquotes, invoke +<br/> +<span class="pre-in-pp"> + .ALWAYS_FULLSPACE_QUOTES +</span> +with no argument. If you wish to restore mom’s default +behaviour regarding the spacing of blockquotes (see +<a href="#quote-spacing">Quote spacing</a>), +invoke the macro with any argument (<kbd>OFF</kbd>, <kbd>QUIT</kbd>, +<kbd>END</kbd>, <kbd>X</kbd>...). +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +This macro also sets mom’s spacing policy for +<a href="#quote-intro">quotes</a>. +</p> +</div> + +<div class="rule-short"><hr/></div> + +<!-- ==================================================================== --> + +<h2 id="code-intro" class="macro-group">Inserting code into a document</h2> + +<ul style="margin-left: -.5em;"> + <li><a href="#code">Tag: CODE</a></li> + <li><a href="#code-control">CODE control macros and defaults</a></li> +</ul> + +<p> +CODE is a convenience macro that facilitates entering code blocks +into documents. Its use is not restricted to documents created +using mom’s document processing macros; it can be used for +“manually” typeset documents as well. +</p> + +<div class="macro-id-overline"> +<h3 id="code" class="macro-id">CODE</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>CODE</b> <kbd class="macro-args">[BR | BREAK | SPREAD] <anything></kbd> +</div> + +<p class="requires" style="font-style: normal"> +Inline escape: <b><kbd>\*[CODE]</kbd></b> +</p> + +<p> +When you invoke the macro CODE or insert +<kbd><span class="nobr">\*[CODE]</span></kbd> into running text, mom switches to +a +<a href="definitions.html#fixedwidthfont">fixed-width font</a> +(Courier, by default) and turns +<a href="goodies.html#smartquotes">SMARTQUOTES</a> +off. +</p> + +<p> +If your code includes the backslash character, which is +groff’s escape character, you will have to change the +escape character temporarily to something else with the macro +<a href="goodies.html#esc-char">ESC_CHAR</a>. +Mom has no way of knowing what special characters you’re going +to use in code snippets, therefore she cannot automatically replace +the escape character with something else. +</p> + +<p> +The correct order for changing the escape character inside +<kbd>CODE</kbd> is +<span class="pre-in-pp"> + .CODE + .ESC_CHAR character + <code> + .ESC_CHAR \ + .CODE OFF +</span> +Be aware that changing the escape character prevents subsequent +macros, which require that the backslash be the escape character, +from functioning correctly. Therefore, do not introduce any macros +into your CODE block without first restoring the escape character to +its default. +</p> + +<p> +Alternatively, you can enter the backslash character as +<kbd>\e</kbd> or <kbd>\\</kbd> (two backslashes), which tells groff +to print a literal backslash. +</p> + +<div class="box-tip"> +<p class="tip-top"> +<span class="tip">Note:</span> +<kbd>.CODE</kbd> does not cause a line break when +you’re in a +<a href="definitions.html#filled">fill mode</a> +(i.e. +<a href="typesetting.html#justify">JUSTIFY</a> +or +<a href="typesetting.html#quad">QUAD</a> +<kbd>LEFT, CENTER,</kbd> or <kbd>RIGHT</kbd>). +If you want CODE to deposit a break, invoke <kbd>.CODE</kbd> with +the argument <kbd>BR</kbd> (or <kbd>BREAK</kbd>). If, in addition +to having mom break the line before <kbd>.CODE</kbd>, you want her +to +<a href="definitions.html#force">force justify</a> +it as well, invoke <kbd>.CODE</kbd> with the argument, +<kbd>SPREAD</kbd>. If, in addition to breaking the line before CODE +you want a break afterwards, you must supply it manually with +<a href="typesetting.html#br">BR</a> +unless what follows immediately is a macro that automatically causes +a break (e.g. +<a href="#pp">PP</a>). +</p> + +<p id="quote-code" class="tip-bottom"> +In all likelihood, if you want the situation described above (i.e. a +break before and after CODE), what you probably want is to use +<a href="quote">QUOTE</a> +in conjunction with CODE, like this: +<br/> +<span class="pre-in-pp"> + .QUOTE + .CODE + $ echo "Hello, world" | sed -e 's/Hello,/Goodbye, cruel/' + .QUOTE OFF +</span> +QUOTE takes care of breaking both the text and the code, as well as +indenting the code and offsetting it from +<a href="definitions.html#running">running text</a> +with vertical whitespace. Notice that <kbd>.CODE</kbd>, above, has +no corresponding <kbd>.CODE OFF</kbd>. <kbd>.CODE</kbd> inside a QUOTE +does not require a terminating <kbd>.CODE OFF</kbd>, which risks +introducing unwanted vertical whitespace. +</p> +</div> + +<p> +Passing any argument other than <kbd>BR</kbd>, <kbd>BREAK</kbd> or +<kbd>SPREAD</kbd> to CODE (e.g. <kbd>OFF</kbd>, <kbd>QUIT</kbd>, +<kbd>END</kbd>, <kbd>X</kbd>, etc) turns CODE off and returns the +family, font, and smartquotes back to their former state. +</p> + +<h4 class="docs" style="font-size: 102%">Using <kbd>\*[CODE]</kbd> inline</h4> + +<p> +<kbd><span class="nobr">\*[CODE]</span></kbd> invokes <kbd>.CODE</kbd>, allowing you to +bracket code snippets inline. It does not accept the <kbd>BR</kbd>, +<kbd>BREAK</kbd>, or <kbd>SPREAD</kbd> arguments. It is most useful +for short snippets, as in the following example. +<br/> +<span class="pre-in-pp"> + \*[CODE]apropos\*[CODE X] and \*[CODE]man -k\*[CODE X] are identical. +</span> +</p> + +<p> +<kbd><span class="nobr">\*[CODE]</span></kbd> does not permit changing the escape +character, so <kbd>\e</kbd> or a doubled backslash must be used. +Furthermore, if your code starts with a period, you must enter it as +“<kbd>\&.</kbd>”. +<br/> +<span class="pre-in-pp"> + Registers are created with the \*[CODE]\&.nr\*[CODE X] request. +</span> +</p> + +<h4 class="docs" style="font-size: 102%; margin-top: -1em">CODE and punctuation</h4> + +<p> +<kbd>.CODE OFF</kbd> automatically inserts a word space into +running text. If your CODE block is to be followed by punctuation +with the parameters of +<a href="definitions.html#running">running text</a>, +you must terminate the block with “<kbd>\c</kbd>” and +enter the punctuation at the beginning of the next input line. If +the punctuation mark is a period or an apostrophe, you must precede +it with +“<kbd>\&</kbd>”. +<br/> +<span class="pre-in-pp"> + ...for example, + .CODE + echo "Hello, world" | sed -e 's/Hello,/Goodbye, cruel/'\c + .CODE OFF + \&. As this demonstrates... +</span> +Use of <kbd><span class="nobr">\*[CODE]</span></kbd> inline does not require +the <kbd>\c</kbd>, however periods and apostrophes after +<kbd><span class="nobr">\*[CODE X]</span></kbd> still need to be introduced +with <kbd>\&</kbd>, as in this example: +<br/> +<span class="pre-in-pp"> + ...append the unit of measure \*[CODE]p\*[CODE OFF]\&. New sentence... +</span> +</p> + + +<div class="defaults-container" style="background-color: #ded4bd; border: none;"> +<h3 id="code-control" class="docs defaults">CODE control macros and defaults</h3> + +<ol style="margin-top: .5em; padding-bottom: .5em;"> + <li><a href="#code-general">Family/Font/Colour</a></li> + <li><a href="#code-size">Size</a></li> +</ol> +</div> + +<h4 id="code-general" class="docs" style="margin-top: -1.5em; margin-bottom: .5em;">1. Family/font/colour</h4> + +<div class="defaults-container" style="padding-bottom: 8px;"> +<p class="defaults" style="padding-top: 6px;"> +See +<a href="#control-macro-args">Arguments to the control macros</a>. +<br/> +The following CODE control macros may also be +<a href="#grouping">grouped</a> +using CODE_STYLE. +</p> +<span class="pre defaults"> +.CODE_FAMILY default = Courier +.CODE_FONT default = roman; see Note +.CODE_COLOR default = black + +Note: Unlike other control macros, CODE_FONT sets the code font for both +PRINTSTYLE TYPESET and PRINTSTYLE TYPEWRITE. +</span> +</div> + +<h4 id="code-size" class="docs" style="margin-top: -1.25em;">2. Size</h4> + +<p> +CODE_SIZE works a little differently from the other _SIZE macros +(see <a href="#control-macro-args">Arguments to the control +macros</a>). The argument you pass it is a percentage of the +prevailing document point size. It does not require a prepended +plus (<kbd>+</kbd>) or minus (<kbd>-</kbd>) sign, nor an appended +percent sign (<kbd>%</kbd>). Thus, if you want the point size of your CODE font to be +90% of the prevailing document point size, you enter: +<br/> +<span class="pre-in-pp"> + .CODE_SIZE 90 +</span> +Fixed-width fonts have notoriously whimsical +<a href="definitions.html#xheight">x-heights</a>, +meaning that they frequently look bigger (or, in some cases, +smaller) than the type surrounding them, even if they’re +technically the same point size. CODE_SIZE lets you choose a +percentage of the prevailing point size for your fixed-width +CODE font so it doesn’t look gangly or minuscule in relation +to the type around it. All invocations of <kbd>.CODE</kbd> or +<kbd><span class="nobr">\*[CODE]</span></kbd> will use this size, so that if you +decide to change the prevailing point size of your document, the +CODE font will be scaled proportionally. +</p> + +<div class="rule-short"><hr/></div> + +<!-- ==================================================================== --> + +<h2 id="list-intro" class="macro-group">Nested lists</h2> + +<ul style="margin-left: -.5em;"> + <li><a href="#list">Tag: LIST</a></li> + <li><a href="#item">Tag: ITEM</a></li> + <li><a href="#list-control">LIST control macros and defaults</a></li> +</ul> + +<p> +Lists are points or items of interest or importance that are +separated from +<a href="definitions.html#running">running text</a> +by enumerators. Some typical enumerators are +<a href="definitions.html#em">en-dashes</a>, +<a href="definitions.html#bullet">bullets</a>, +digits and letters. +</p> + +<p> +Setting lists with mom is easy. First, you initialize a list with +the LIST macro. Then, for every item in the list, you invoke +the macro <kbd>.ITEM</kbd> followed by the text of the item. +When a list is finished, you exit the list with +<kbd>.LIST OFF</kbd> (or <kbd>QUIT</kbd>, <kbd>END</kbd>, +<kbd>BACK</kbd>, etc.) +</p> + +<p> +By default mom starts each list with the enumerator flush with the +left margin of running text that comes before it, like this: +<br/> +<span class="pre-in-pp"> + My daily schedule needs organising. I can’t + seem to get everything done I want. + o an hour’s worth of exercise + o time to prepare at least one healthy + meal per day + o reading time + o work on mom + o writing + - changes from publisher + - current novel + o a couple of hours at the piano +</span> +In other words, mom does not, by default, indent entire lists. +Indenting a list is controlled by the macro +<a href="#shift-list">SHIFT_LIST</a>. +(This is a design decision; there are too many instances where a +default indent is not desirable.) Equally, mom does not add any +extra space above or below lists. +</p> + +<p> +Lists can be nested (as in the example above). In other words, +you can set lists within lists, each with an enumerator (and +possibly, indent) of your choosing. In nested lists, each +invocation of <kbd>.LIST OFF</kbd> (you may prefer to use +<kbd>.LIST BACK</kbd>) takes you back to the previous depth +(or level) of list, with that list’s enumerator and indent +intact. The final <kbd>.LIST OFF</kbd> exits lists completely +and returns you to the left margin of running text. +</p> + +<p> +If +<kbd><a href="typesetting.html#quad">QUAD CENTER</a></kbd> +is in effect when LIST is invoked, the list is set quad left but +centred on the page as a block, based on the longest line of list +text. Equally, if <kbd>QUAD RIGHT</kbd> in in effect, the list is +set flush left but quadded right as a block. If you want a centred +or right-quadded list in an otherwise left-quadded or justified +document, simply invoke <kbd>.QUAD <direction></kbd> +before the list and reset the quad afterwards. Do not use +<kbd><a href="typesetting.html#lrc">CENTER</a></kbd> +or +<kbd><a href="typesetting.html#lrc">RIGHT</a></kbd>. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +Mom centres lists over the entire line length, disregarding +<a href="typesetting.html#ib">IB</a> +if it is in effect. If there are lines in the list that exceed +the margins of IB, they must be broken manually with +<kbd>.BR</kbd> if you wish to keep them within the indented margins. +</p> +</div> + +<p> +Finally, lists can be used in documents created with either the +<a href="docprocessing.html#top">document processing macros</a> +or just the +<a href="typesetting.html#top">typesetting macros</a>. +</p> + +<!-- -LIST- --> + +<div class="macro-id-overline"> +<h3 id="list" class="macro-id">LIST</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>LIST</b> <kbd class="macro-args">[ BULLET | DASH | DIGIT | ALPHA | alpha | ROMAN<n> | roman<n> | USER <user-defined enumerator> | PLAIN | VARIABLE <character>] [ <separator> ] [ <prefix> ] [ <anything> ]</kbd> +</div> + +<p> +Invoked by itself (i.e. with no argument), LIST +initializes a list with bullets as the default enumerator. +Afterwards, each block of input text preceded by +<kbd><a href="#item">.ITEM</a></kbd>, +on a line by itself, is treated as a list item. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +Every time you invoke <kbd>.LIST</kbd> to start a list (as opposed to +<a href="#list-exit">exiting one</a>), +you must supply an enumerator (and optionally, a separator) for the +list, unless you want mom’s default enumerator, which is a +bullet. Within nested lists, mom stores the enumerator, separator +and indent for any list you return <i>backwards</i> to (i.e. with +<kbd>.LIST OFF</kbd>), but does not store any information for lists +you move <i>forward</i> to. +</p> +</div> + +<p> +There are a lot of arguments (be sure to side-scroll through them +all, above), so I’ll discuss them one at a time here. +</p> +<h3 class="docs">The first argument – enumerator style</h3> + +<p> +The optional arguments <kbd>BULLET</kbd>, <kbd>DASH</kbd>, +<kbd>DIGIT</kbd> (for Arabic numerals), <kbd>ALPHA</kbd> (for +uppercase letters), <kbd>alpha</kbd> (for lowercase letters), +<kbd>ROMAN<n></kbd> (for uppercase roman numerals), +<kbd>roman<n></kbd> (for lowercase roman numerals) tell +mom what kind of enumerator to use for a given list. +</p> + +<p> +The arguments, <kbd>ROMAN<n></kbd> and +<kbd>roman<n></kbd>, are special. You must append to them +a digit (arabic, e.g. "1" or "9" or "17") saying how many items a +particular roman-numeraled LIST is going to have. Mom requires this +information in order to align roman numerals sensibly, and will +abort—with a message — if you don’t provide it. +(For setting roman numeral and digit lists with the enumerators +aligned flush right—the default is flush left—see +<a href="#pad-list-digits">PAD_LIST_DIGITS</a>.) +</p> + +<p> +A roman-numeraled list containing, say, five items, would be set +up like this: +<br/> +<span class="pre-in-pp"> + .LIST roman5 producing i) Item 1. + .ITEM ii) Item 2. + Item 1. iii) Item 3. + .ITEM iv) Item 4. + Item 2. v) Item 5. + .ITEM + Item 3 + .ITEM + Item 4 + .ITEM + Item 5 +</span> +</p> + +<p> +The argument <kbd>VARIABLE <character></kbd> lets +you choose different enumerators for the items in a list. +<kbd><character></kbd> is the widest enumerator to +be used. Thus, if you have a list enumerated by both bullets +and em-dashes, you’d set it up with +<br/> +<span class="pre-in-pp"> + .LIST VARIABLE \[em] +</span> +and select the enumerator you want with +<br/> +<span class="pre-in-pp"> + .ITEM \[em] +</span> +or +<br/> +<span class="pre-in-pp"> + .ITEM \[bu] +</span> +If your enumerator contains spaces, you must enclose the +<kbd><character></kbd> argument in both LIST and ITEM in +double-quotes, e.g. +<br/> +<span class="pre-in-pp"> + .LIST VARIABLE "\*[UP 1p]\[bu]\*[DOWN 1p]" + .ITEM "\*[UP 1p]\[bu]\*[DOWN 1p]" +</span> +</p> + +<p> +The argument <kbd>USER</kbd> lets you make up your own enumerator, +and must be followed by a second argument: what you’d like the +enumerator to look like. For example, if you want a list enumerated +with <kbd>=></kbd>, +<br/> +<span class="pre-in-pp"> + .LIST USER => + .ITEM + A list item +</span> + +will produce +<br/> +<span class="pre-in-pp"> + => A list item +</span> +Some useful special groff characters you might want to pass to +<kbd>USER</kbd> are: +<span class="pre-in-pp"> + \[sq] - square box + \[rh] - pointing hand + \[->] - right arrow + \[rA] - right double arrow + \[OK] - checkmark +</span> +The size and vertical positioning of special characters may be +adjusted with +<a href="definitions.html#inlines">inline escapes</a> +in the argument passed to USER. For example, to raise the position +of <kbd><span class="nobr">\[sq]</span></kbd> slightly, you might do +<span class="pre-in-pp"> + .LIST USER "\*[UP .25p]\[sq]\*[DOWN .25p]" + or + .LIST USER \v'-.25p'\[sq]\v'.25p' +</span> +</p> + +<p> +The argument <kbd>PLAIN</kbd> initializes a list with no enumerator. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +If the argument to <kbd>USER</kbd> contains spaces, you must enclose +the argument in double quotes. +</p> +</div> + +<h3 class="docs">The second argument – separator style</h3> + +<p> +If you choose <kbd>DIGIT</kbd>, <kbd>ALPHA</kbd>, <kbd>alpha</kbd>, +<kbd>ROMAN<n></kbd>, or <kbd>roman<n></kbd>, you may +enter the optional argument, <kbd>separator</kbd>, to say what kind +of separator you want after the enumerator. The separator can be +anything you like. The default for <kbd>DIGIT</kbd> is a period +(dot), like this: +<br/> +<span class="pre-in-pp"> + 1. A list item +</span> +The default separator for <kbd>ALPHA</kbd>, <kbd>alpha</kbd>, +<kbd>ROMAN<n></kbd> and <kbd>roman<n></kbd> is a right +parenthesis, like this: +<br/> +<span class="pre-in-pp"> + a) An alpha-ed list item + b) A second alpha-ed list item +</span> +If you’d prefer, say, digits with right-parenthesis separators +instead of the default period, you’d do +<br/> +<span class="pre-in-pp"> + .LIST DIGIT ) + .ITEM + A numbered list item +</span> +which would produce +<br/> +<span class="pre-in-pp"> + 1) A numbered list item +</span> +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +<kbd>BULLET</kbd>, <kbd>DASH</kbd> and <kbd>USER</kbd> do not take a +separator. +</p> +</div> + +<h3 class="docs">The third argument – prefix style</h3> + +<p> +Additionally, you may give a prefix (i.e. a character +that comes <i>before</i> the enumerator) when your +enumerator style for a particular list is <kbd>DIGIT</kbd>, +<kbd>ALPHA</kbd>, <kbd>alpha</kbd>, <kbd>ROMAN<n></kbd> or +<kbd>roman<n></kbd>. In the arguments to LIST, the prefix +comes <i>after</i> the separator, which is counter-intuitive, +so please be careful. +</p> + +<p> +A prefix can be anything you like. Most likely, you’ll want +some kind of open-bracket, such as a left parenthesis. If, for +example, you want a <kbd>DIGIT</kbd> list with the numbers enclosed +in parentheses, you’d enter +<br/> +<span class="pre-in-pp"> + .LIST DIGIT ) ( + .ITEM + The first item on the list. + .ITEM + The second item on the list. +</span> +which would produce +<br/> +<span class="pre-in-pp"> + (1) The first item on the list. + (2) The second item on the list. +</span> +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +<kbd>BULLET</kbd>, <kbd>DASH</kbd> and +<kbd>USER</kbd> do not take a prefix. +</p> +</div> + +<h3 class="docs">Exiting lists – LIST OFF / BACK or QUIT_LISTS</h3> + +<p> +Any single argument to <kbd>LIST</kbd> other than +<kbd>BULLET</kbd>, <kbd>DASH</kbd>, <kbd>DIGIT</kbd>, +<kbd>ALPHA</kbd>, <kbd>alpha</kbd>, <kbd>ROMAN<n></kbd>, +<kbd>roman<n></kbd> or <kbd>USER</kbd> (e.g. +<kbd>LIST OFF</kbd> or <kbd>LIST BACK</kbd>) takes you out +of the current list. +</p> + +<p> +If you are at the first list-level (or list-depth), mom returns you +to the left margin of running text. Any indents that were in effect +prior to setting the list are fully restored. +</p> + +<p> +If you are in a nested list, mom moves you back one list-level +(i.e., does not take you out of the list structure) and restores the +enumerator, separator and indent appropriate to that level. +</p> + +<p> +Each invocation of <kbd>.LIST</kbd> should thus be matched by +a corresponding <kbd>.LIST OFF</kbd> in order to fully exit +lists. For example, +<br/> +<span class="pre-in-pp"> + Lorem ipsum dolor sit amet, consetetur sadipscing elitr, + sed diam nonumy eirmod tempor invidunt ut labore. + o List item in level 1 + o List item in level 1 + - List item in level 2 + - List item in level 2 + Lorem ipsum dolor sit amet, consetetur sadipscing elitr, + sed diam nonumy eirmod tempor invidunt ut labore. +</span> +is created like this: +<br/> +<span class="pre-in-pp"> + Lorem ipsum dolor sit amet, consetetur sadipscing elitr, + sed diam nonumy eirmod tempor invidunt ut labore. + .LIST BULLET + .ITEM + List item in level 1 + .ITEM + List item in level 1 + .LIST DASH + .ITEM + List item in level 2 + .ITEM + List item in level 2 + .LIST OFF \" Turn level 2 list off + .LIST OFF \" Turn level 1 list off + Lorem ipsum dolor sit amet, consetetur sadipscing elitr, + sed diam nonumy eirmod tempor invidunt ut labore. +</span> +Alternatively, you may use the single-purpose macro +<kbd>.QUIT_LISTS</kbd>, to get yourself out of a list structure. In +the example above, the two <kbd>.LIST OFF</kbd> lines could be +replaced with a single <kbd>.QUIT_LISTS</kbd>. +</p> + +<div class="macro-id-overline"> +<h3 id="item" class="macro-id">ITEM</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>ITEM</b> <kbd class="macro-args">[<enumerator>] [<space>]</kbd> +</div> +<p class="requires"> +• The argument to <kbd style="font-style: normal"><space></kbd> requires a +<a href="definitions.html#unitofmeasure">unit of measure</a> +</p> + +<p> +After you’ve initialized a list with +<a href="#list">LIST</a>, +precede each item you want in the list with <kbd>.ITEM</kbd>. Mom +takes care of everything else with respect to setting the item +appropriate to the list you’re in. +</p> + +<p> +If you’ve chosen the <kbd>VARIABLE</kbd> argument when +invoking LIST, ITEM must be followed by an enumerator character. +</p> + +<p> +If you give ITEM a space argument, either by itself or after a +variable enumerator character, the item will be spaced by the amount +of the argument. +</p> + +<p> +In document processing, it is valid to have list items that contain +multiple paragraphs. Simply issue a +<kbd><a href="#pp">.PP</a></kbd> +request for each paragraph <i>following</i> the first item. +I.e., don’t do this: +<br/> +<span class="pre-in-pp"> + .ITEM + .PP + Some text... + .PP + A second paragraph of text +</span> +but rather +<br/> +<span class="pre-in-pp"> + .ITEM + Some text... + .PP + A second paragraph of text +</span> +</p> + +<div class="defaults-container" style="background-color: #ded4bd; border: none;"> +<h3 id="list-control" class="docs defaults">LIST control macros and defaults</h3> + +<p style="margin-top: 0; margin-left: .5em"> +LIST control macros may not be +<a href="#grouping">grouped</a>. +</p> + +<ol style="margin-top: -.5em; padding-left: 1.5em; padding-bottom: .5em;"> + <li><a href="#shift-list">Indenting lists (SHIFT_LIST)</a></li> + <li><a href="#reset-list">Resetting an initialized list’s enumerator (RESET_LIST)</a></li> + <li><a href="#pad-list-digits">Padding digit enumerators (PAD_LIST_DIGITS)</a></li> +</ol> +</div> + +<h4 id="shift-list" class="docs" style="margin-top: -1.5em;">1. Indenting lists – SHIFT_LIST</h4> + +<p> +If you want a list to be indented to the right of running text, or +indented to the right of a current list, use the macro SHIFT_LIST +immediately after +<a href="#list">LIST</a>. +SHIFT_LIST takes just one argument: the amount by which you want the +list shifted to the right. The argument requires a +<a href="definitions.html#unitofmeasure">unit of measure</a>. +</p> + +<p> +SHIFT_LIST applies only to the list you just initialized with LIST. +It does not carry over from one invocation of LIST to the next. +However, the indent remains in effect when you return to a list +level in a nested list. +</p> + +<p> +For example, if you want a 2-level list, with each list indented to +the right by 18 +<a href="definitions.html#picaspoints">points</a>, +<br/> +<span class="pre-in-pp"> + Lorem ipsum dolor sit amet, consetetur sadipscing elitr, + sed diam nonumy eirmod tempor invidunt ut labore. + .LIST \" List 1 + .SHIFT_LIST 18p \" Indent 18 points right of running text + .ITEM + List 1 item + .ITEM + List 1 item + .LIST DASH \" List 2 + .SHIFT_LIST 18p \" Indent 18 points right of list 1 + .ITEM + List 2 item + .ITEM + List 2 item + .LIST OFF \" Move back to list 1 + .ITEM + List 1 item + .ITEM + List 1 item + .LIST OFF \" Exit lists + Lorem ipsum dolor sit amet, consetetur sadipscing elitr, + sed diam nonumy eirmod tempor invidunt ut labore. +</span> +produces (approximately) +<br/> +<span class="pre-in-pp"> + Lorem ipsum dolor sit amet, consetetur sadipscing elitr, + sed diam nonumy eirmod tempor invidunt ut labore. + • List 1 item + • List 1 item + - List 2 item + - List 2 item + • List 1 item + • List 1 item + Lorem ipsum dolor sit amet, consetetur sadipscing elitr, + sed diam nonumy eirmod tempor invidunt ut labore. +</span> +</p> + +<h4 id="reset-list" class="docs" style="margin-top: -.25em;">2. Resetting an initialized list’s enumerator – RESET_LIST</h4> + +<p> +In nested lists, if your choice of enumerator for a given level +of list is <kbd>DIGIT</kbd>, <kbd>ALPHA</kbd>, <kbd>alpha</kbd>, +<kbd>ROMAN</kbd> or <kbd>roman</kbd>, you may sometimes want to +reset the list’s enumerator when you return to that list. +Consider the following: +<br/> +<span class="pre-in-pp"> + Things to do religiously each and every day: + • take care of the dog + a) walk every day + b) brush once a week + - trim around the eyes every fourth brushing + - don’t forget to check nails + • feed the cat + d) soft food on Mon., Wed. and Fri. + e) dry food on Tues., Thurs. and Sat. + f) canned tuna on Sunday +</span> +</p> + +<p> +The alpha-enumerated items under “Feed the cat” +would be normally a), b), c), but we want d), e), f). The +solution is to reset the second <kbd>.LIST alpha</kbd>’s +enumerator—before the first <kbd>.ITEM</kbd>—with +the macro RESET_LIST. +</p> + +<p> +With no argument, <kbd>.RESET_LIST</kbd> resets an incrementing +enumerator to 1, A, a, I or i depending on the style of enumerator. +If you pass <kbd>.RESET_LIST</kbd> a +<a href="definitions.html#numericargument">numeric argument</a>, +it represents the starting position for an incrementing enumerator. In +the example above, <kbd>.RESET_LIST 4</kbd> starts the second +alpha-ed list at d). +</p> + +<h4 id="pad-list-digits" class="docs" style="margin-top: -.25em;">3. Padding digit enumerators – PAD_LIST_DIGITS</h4> + +<h5 class="docs" style="margin-top: 1em;">Arabic digits</h5> + +<p style="margin-top: .5em;"> +When your choice of enumerators is DIGIT and the number of items +in the list exceeds nine (9), you have to make a design decision: +should mom leave room for the extra numeral in two-numeral digits to +the right or the left of the single-numeral digits? +</p> + +<p> +If you want the extra space to the right, invoke the macro +<kbd>.PAD_LIST_DIGITS</kbd> (with no argument), after +<kbd>.LIST</kbd> and before <kbd>.ITEM</kbd>. This will produce +something like +<br/> +<span class="pre-in-pp"> + 8. List item + 9. List item + 10. List item +</span> +If you want the extra space to the left, invoke +<kbd>.PAD_LIST_DIGITS</kbd> with the single argument, +<kbd>LEFT</kbd>, which will produce +<br/> +<span class="pre-in-pp"> + 8. List item + 9. List item + 10. List item +</span> +</p> + +<p> +Of course, if the number of items in the list is less than ten +(10), there’s no need for PAD_LIST_DIGITS. +</p> + +<h5 class="docs" style="margin-top: -.5em;">Roman numerals</h5> + +<p style="margin-top: .5em;"> +By default, mom sets roman numerals in lists flush left. The +<kbd><n></kbd> argument appended to <kbd>ROMAN<n></kbd> +or <kbd>roman<n></kbd> allows her to calculate how much space +to put after each numeral in order to ensure that the text of items +lines up properly. +</p> + +<p> +If you’d like the roman numerals to line +up flush right (i.e. be padded "left"), simply +invoke <kbd>.PAD_LIST_DIGITS LEFT</kbd> after +<kbd>.LIST ROMAN<n></kbd> or +<kbd>.LIST roman<n></kbd> and before <kbd>.ITEM</kbd>. +</p> + +<div class="rule-short"><hr/></div> + +<!-- -LINE NUMBERING- --> + +<h2 id="number-lines-intro" class="macro-group">Line numbering – prepend numbers to output lines</h2> + +<ul style="margin-left: -.5em;"> + <li><a href="#number-lines">Macro: <b>NUMBER_LINES</b></a> + <ul style="margin-left: -.5em;"> + <li><a href="#ln-control">Line numbering control (off/suspend, resume)</a></li> + </ul></li> + <li><a href="#number-lines-control">Control macros and defaults</a> + <ul style="margin-left: -.5em;"> + <li><a href="#number-quote-lines">Line numbering control macros for quotes and blockquotes</a></li> + </ul></li> +</ul> + +<p style="margin-top: -.5em;"> +When you turn line-numbering on, mom, by default +</p> +<ul style="margin-top: -.5em;"> + <li>numbers every line of paragraph text; line-numbering is + suspended for all other document processing tags (like + docheaders, epigraphs, headings, quotes, etc.) and special + pages (covers, endotes, bibliographies, etc.); be aware, + though, that if you turn + <a href="definitions.html#docheader">docheaders</a> + off (with + <a href="docprocessing.html#docheader">DOCHEADER</a> OFF) + and create your own docheader, mom + <i>will</i> line-number your custom docheader, so turn + line numbering on afterwards + </li> + <li>doesn’t touch your line length; line numbers are hung + outside your current left margin (as set with + <a href="typesetting.html#l-margin">L_MARGIN</a>, + <a href="typesetting.html#page">PAGE</a> + or + <a href="docprocessing.html#doc-left-margin">DOC_LEFT_MARGIN</a>), + regardless of any indents that may be active + </li> + <li>separates line numbers from running text by two + <a href="definitions.html#figurespace">figure spaces</a>. + </li> +</ul> + +<p> +Mom expects that +<a href="#quote">QUOTE</a>s +and +<a href="#blockquote">BLOCKQUOTE</a>s +will not be line-numbered, however control macros are provided to +enable line numbering for either. +See +<a href="#number-quote-lines">Line numbering control macros for quotes and blockquotes</a>. +</p> + +<!-- -NUMBER_LINES- --> + +<div class="macro-id-overline"> +<h3 id="number-lines" class="macro-id">NUMBER_LINES</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>NUMBER_LINES</b> <kbd class="macro-args"><start number> [ <which lines to number> [ <gutter> ] ]</kbd> +</div> + +<div class="box-macro-args" style="margin-top: 1em;"> +Macro: <b>NUMBER_LINES</b> <kbd class="macro-args"><anything> | RESUME</kbd> +</div> + +<p> +NUMBER_LINES does what it says: prints line numbers, to the left of +<a href="definitions.html#outputline">output lines</a> +of paragraph text. One of the chief reasons for wanting numbered +lines is in order to identify footnotes or endnotes by line number +instead of by a marker in the text. (See +<a href="#footnotes-by-linenumber">Footnotes by linenumber</a> +for instructions on line-numbered footnotes, and +<a href="#endnote-marker-style">ENDNOTE_MARKER_STYLE LINE</a> +for instructions on line-numbered endnotes.) +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +Do not use NUMBER_LINES inside +<a href="#quote">QUOTE</a> +or +<a href="#blockquote">BLOCKQUOTE</a>. +By default, mom expects that quotes and blockquotes will not be +line numbered. If you wish to enable line numbering for them, you +must invoke +<a href="#number-quote-lines">NUMBER_QUOTE_LINES</a> +or +<a href="#number-quote-lines">NUMBER_BLOCKQUOTE_LINES</a>. +</p> +</div> + + +<p> +The first time you invoke +<a href="#number-lines">NUMBER_LINES</a> +you must, at a minimum, tell it what line number you want the +<i>next</i> +<a href="definitions.html#outputline">output line</a> +to have. The optional arguments <kbd><which lines to number></kbd> +and <kbd><gutter></kbd> allow you to state which lines should +be numbered (e.g. every five or every ten lines), and the gutter to +place between line numbers and +<a href="definitions.html#running">running text</a>. +</p> + +<p> +For example, if you want mom to number output lines using her defaults, +<span class="pre-in-pp"> + .NUMBER_LINES 1 +</span> +will prepend the number, 1, to the next output line and number all +subsequent output lines sequentially. +</p> + +<p> +If you want only every five lines numbered, pass mom the optional +<kbd><which lines to number></kbd> argument, like this: +<span class="pre-in-pp"> + .NUMBER_LINES 1 5 +</span> +</p> + +<div class="box-important"> +<p class="tip-top"> +<span class="important">GOTCHA!</span> +The argument to <kbd><which lines to number></kbd> instructs +mom to number only those lines that are multiples of the argument. +Hence, in the above example, line number <kbd>1</kbd> will +<i>not</i> be numbered, since <kbd>1</kbd> is not a multiple of +<kbd>5</kbd>. +</p> + +<p> +If you want line number <kbd>1</kbd> to be numbered, you have +to invoke <kbd><span class="nobr">.NUMBER_LINES 1 1</span></kbd> before the +first output line you want numbered, then study your <i>output</i> +copy and determine where best to insert the following in your +<i>input</i> text: +<br/> +<span class="pre-in-pp"> + .NUMBER_LINES \n[ln] 5 +</span> +(The escape <kbd>\n[ln]</kbd> ensures that NUMBER_LINES +automatically supplies the correct value for the first argument, +<kbd><start number></kbd>.) +</p> + +<p class="tip-bottom"> +Following this recipe, line number <kbd>1</kbd> will be numbered; +subsequently, only line numbers that are multiples of 5 will be +numbered. A little experimentation may be required to determine the +best place for it in your input text. +</p> +</div> + +<p> +The optional argument, <kbd><gutter></kbd>, tells mom how much +space to put between the line numbers and the running text. +<kbd><gutter></kbd> does not require (or even accept) a +<a href="definitions.html#unitofmeasure">unit of measure</a>. +The argument you pass to it is the number of +<a href="definitions.html#figurespace">figure spaces</a> +you want between line numbers and running text. +Mom’s default gutter is two figure spaces. If +you’d like a wider gutter, say, four figures spaces, you’d do +<br/> +<span class="pre-in-pp"> + .NUMBER_LINES 1 1 4 + | + +-- Notice you *must* supply a value + for the 2nd argument in order to supply + a value for the 3rd. +</span> +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +When giving a value for <kbd><gutter></kbd>, you cannot skip +the <kbd><which lines to number></kbd> argument. Either fill +in the desired value, or use two double-quotes ( <kbd>""</kbd> ) to +have mom use the value formerly in effect. +</p> +</div> + +<h3 id="ln-control" class="docs" style="margin-top: -.5em;">Off/suspend, resume</h3> + +<p style="margin-top: .5em;"> +After initializing line numbering, you can suspend it, with the +option to resume, using +<br/> +<span class="pre-in-pp"> + .NUMBER_LINES OFF +</span> +(or <kbd>END</kbd>, <kbd>QUIT</kbd>, <kbd>X</kbd>, etc). +</p> + +<p>To resume line numbering: +<br/> +<span class="pre-in-pp"> + .NUMBER_LINES RESUME +</span> +When you resume, the line number will be the next in sequence +from where you left off. If that is not what you want—say +you want to reset the line number to <kbd>1</kbd>—re-invoke +<kbd>.NUMBER_LINES</kbd> with whatever arguments are needed for the +desired result. +</p> + +<div class="box-tip" style="margin-left: 6px;"> +<p class="tip"> +<span class="note">Additional notes:</span> +</p> +<ol style="margin-top: -1.25em; margin-left: -1.25em; padding-bottom: .5em;"> + <li>In document processing, you may invoke + <kbd>.NUMBER_LINES</kbd> either before or after + <kbd>.START</kbd>. Mom doesn’t care. + </li> + <li style="margin-top: .25em;">If you’re collating documents with + <a href="rectoverso.html#collate">COLLATE</a>, + you should re-invoke, at a minimum, + <kbd>.NUMBER_LINES 1</kbd> for each collated + document, in order to ensure that each begins with the + number <kbd>1</kbd> prepended to the first line. + </li> + <li style="margin-top: .25em;">Occasionally, you may want to + change the current gutter between line numbers and running + text without knowing what the next output line number should + be. Since NUMBER_LINES requires this number as its first + argument, in such instances, pass NUMBER_LINES as its first + argument the escape + <kbd>\n[ln]</kbd>. + <br/> + <span style="display: block; margin-top: .5em;">For example, if you were numbering every 5 lines with a + gutter of 2 (figure spaces) and you needed to change the + gutter to 4 (figures spaces), + <br/> + <span class="pre-in-pp" style="margin-bottom: -2em;"> + .NUMBER_LINES \n[ln] 5 4 + </span> + would do the trick. + </span> + </li> + <li style="margin-top: .25em;">If you’re using + <a href="#mn-intro">margin notes</a> + in a document, be sure to set the gutter for margin notes wide + enough to allow room for the line numbers. + </li> + <li style="margin-top: .25em;">Mom (groff, actually), only numbers + lines <i>to the left</i> of running text. For aesthetic + reason, therefore, the use of line numbering when setting a + document in columns is discouraged. However, should you wish + to number lines when setting in columns, make sure the + <a href="definitions.html#gutter">gutter(s)</a> + between columns is wide enough to leave room for the numbers. + </li> +</ol> +</div> + +<div class="defaults-container" style="background-color: #ded4bd; border: none;"> +<h3 id="number-lines-control" class="docs defaults">NUMBER_LINES control macros and defaults</h3> + +<ol style="margin-top: .5em; padding-bottom: .5em;"> + <li><a href="#number-lines-general">Family/font/size/colour</a></li> + <li><a href="#number-lines-per-section">Reset line numbering after COLLATE</a></li> + <li><a href="#number-quote-lines">Line numbering control for quotes and blockquotes</a> + <ul style="padding-left: 1em"> + <li><a href="#number-quote-lines-global">Including QUOTEs and BLOCKQUOTEs in the line numbering scheme</a></li> + <li><a href="#number-quote-lines-selective">Selectively enabling line numbering for QUOTEs and BLOCKQUOTEs</a></li> + <li><a href="#number-quote-lines-gutter">Changing the line number gutter for QUOTEs and BLOCKQUOTEs</a></li> + <li><a href="#number-quote-lines-silent">Silently increment line numbers during QUOTE and BLOCKQUOTE</a></li> + </ul></li> +</ol> +</div> + +<h4 id="number-lines-general" class="docs" style="margin-top: -1.5em; margin-bottom: .5em;">1. Family/font/size/colour</h4> + +<div class="defaults-container" style="padding-bottom: 8px;"> +<p class="defaults" style="padding-top: 6px;"> +See +<a href="#control-macro-args">Arguments to the control macros</a>. +<br/> +The following NUMBER_LINES control macros may also be +<a href="#grouping">grouped</a> +using LINENUMBER_STYLE. +</p> +<span class="pre defaults"> +.LINENUMBER_FAMILY default = prevailing family or document family; default is Times Roman +.LINENUMBER_FONT default = prevailing font +.LINENUMBER_SIZE default = +0 +.LINENUMBER_COLOR default = black +</span> +</div> + +<h4 id="number-lines-per-section" class="docs" style="margin-top: -1.75em;">2. Reset line numbering after COLLATE</h4> + +<p> +After +<a href="rectoverso.html#collate">COLLATE</a>, +line numbering continues from where it left off. If you would like +each chapter or major document section to begin its line numbering +at “1”, invoke +<span class="pre-in-pp"> + .NUMBER_LINES_PER_SECTION +</span> +after +<a href="#number-lines"><kbd>.NUMBER_LINES</kbd></a>. +</p> + +<h4 id="number-quote-lines" class="docs" style="margin-top: 0em;">3. Line numbering control macros for QUOTE and BLOCKQUOTE</h4> + +<h5 id="number-quote-lines-global" class="docs" style="font-size: 87%">• Including QUOTEs and BLOCKQUOTEs in the line numbering scheme</h5> + +<p> +If you’d like mom to number lines in a +<a href="#quote">QUOTE</a> +or +<a href="#blockquote">BLOCKQUOTE</a> +as part of the same order and sequence as paragraph text, +invoke +<span class="pre-in-pp"> + .NUMBER_QUOTE_LINES +</span> +or +<span class="pre-in-pp"> + .NUMBER_BLOCKQUOTE_LINES +</span> +either before or after NUMBER_LINES. Both behave identically with +respect to the affected macro (i.e. QUOTE or BLOCKQUOTE). +</p> + +<h5 id="number-quote-lines-selective" class="docs" style="font-size: 87%">• Selectively enabling line numbering for QUOTEs and BLOCKQUOTEs</h5> + +<p> +If you’d like to enable line numbering selectively for quotes +and blockquotes <i>only</i>, invoke <kbd>.NUMBER_QUOTE_LINES</kbd> +or <kbd>.NUMBER_BLOCKQUOTE_LINES</kbd> first, followed by +<kbd>.NUMBER_LINES <n></kbd>, where <kbd><n></kbd> +is the first line number of the quote or blockquote. Afterwards, +enter your QUOTE or BLOCKQUOTE. When the quote or blockquote +is finished (i.e. after <kbd>.QUOTE OFF</kbd> or +<kbd>.BLOCKQUOTE OFF</kbd>), turn line numbering off. Each +subsequent quote or blockquote you want line numbered requires +only <kbd>.NUMBER_LINES <n></kbd> (with a corresponding +<kbd>.NUMBER_LINES OFF</kbd>) until you turn NUMBER_QUOTE_LINES or +NUMBER_BLOCKQUOTE_LINES off. +</p> + +<p> +Here’s a recipe where the first line number of quotes starts +repeatedly at “1”. +<span class="pre-in-pp"> + <running text> + .NUMBER_QUOTE_LINES + .NUMBER_LINES 1 + .QUOTE + <text of quote> + .QUOTE OFF + .NUMBER_LINES OFF + <further running text> + .NUMBER_LINES 1 + .QUOTE + <text of quote> + .QUOTE OFF + .NUMBER_LINES OFF + <further running text> +</span> +</p> + +<h5 id="number-quote-lines-gutter" class="docs" style="font-size: 87%">• Changing the line number gutter for QUOTEs and BLOCKQUOTEs</h5> + +<p> +Owing to groff’s restriction on accepting only the figure +space as the line number +<a href="definitions.html#gutter">gutter</a>’s +unit of measure, it is not possible for line numbers in quotes +or blockquotes to hang outside a document’s overall left +margin and be reliably flush with the line numbers of paragraph +text. Consequently, line numbers in quotes or blockquotes hang +to the left of the quote, separated by the currently active +gutter for NUMBER_LINES. +</p> + +<p> +If you’d like to change the line number gutter for quotes +or blockquotes, invoke <kbd>.NUMBER_QUOTE_LINES</kbd> or +<kbd>.NUMBER_BLOCKQUOTE_LINES</kbd> with a digit representing the +number of +<a href="definitions.html#figurespace">figure spaces</a> +you’d like between the line numbers and the quoted text, like this: +<br/> +<span class="pre-in-pp"> + .NUMBER_QUOTE_LINES 3 +</span> +With the above, line numbers in quotes (and only quotes) will have +a gutter of 3 figure spaces. +</p> + +<h5 id="number-quote-lines-silent" class="docs" style="font-size: 87%">• Silently increment line numbers during QUOTE and BLOCKQUOTE</h5> + +<p> +If you’ve asked mom not to line number quotes or blockquotes, +but would like line numbering to continue while they’re +being output (as opposed to mom’s default behaviour of +<i>suspending</i> incrementing of line numbers during the output of +quotes and blockquotes), invoke +<span class="pre-in-pp"> + .NUMBER_QUOTE_LINES SILENT +</span> +or +<span class="pre-in-pp"> + .NUMBER_BLOCKQUOTE_LINES SILENT +</span> +With these, mom continues to increment line numbers while quotes +or blockquotes are being output, but the line numbers won’t +appear in the output copy. +</p> + +<p> +Once having turned NUMBER_QUOTE_LINES or NUMBER_BLOCKQUOTE_LINES on, +you may disable them with +<span class="pre-in-pp"> + .NUMBER_QUOTE_LINES OFF +</span> +or +<span class="pre-in-pp"> + .NUMBER_BLOCKQUOTE_LINES OFF +</span> +</p> + +<div class="rule-short"><hr/></div> + +<!-- ==================================================================== --> + +<h2 id="footnote-intro" class="macro-group">Footnotes</h2> + +<ul> + <li><a href="#footnote-behaviour">Footnote behaviour</a> + <ul style="margin-left: -.5em;"> + <li><a href="#fn-and-punct">Footnote markers and punctuation in the running text</a></li> + </ul></li> + <li><a href="#footnote">Tag: FOOTNOTE</a></li> + <li><a href="#footnote-control">Footnote control macros and defaults</a></li> +</ul> + +<p> +For something so complex behind the scenes, footnotes are easy to use. +You just type, for example, +<br/> +<span id="footnote-example" class="pre-in-pp"> + ...the doctrines of Identity as urged by Schelling\c + .FOOTNOTE + <footnote about who the hell is Schelling> + .FOOTNOTE OFF + were generally the points of discussion presenting the most + of beauty to the imaginative Morella. +</span> +and be done with it. +(Note the obligatory use of the <kbd>\c</kbd> +<a href="definitions.html#inlines">inline escape</a>, +required whenever your +<a href="#footnote-marker-style">FOOTNOTE_MARKER_STYLE</a> +is either <kbd>STAR</kbd> [star/dagger footnotes] or +<kbd>NUMBER</kbd> [superscript numbers].) +</p> + +<p> +After you invoke <kbd>.FOOTNOTE</kbd>, mom takes care of everything: +putting footnote markers in the body of the document, keeping track +of how many footnotes are on the page, identifying the footnotes +themselves appropriately, balancing them properly with the bottom +margin, deferring footnotes that don’t fit on the page... +Even if you’re using +<a href="docprocessing.html#columns">COLUMNS</a>, +mom knows what to do, and Does The Right Thing. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +See +<a href="refer.html">refer.html</a> +for information on using footnotes with the <kbd>refer</kbd> +bibliographic database. +</p> +</div> + +<h3 id="footnote-behaviour" class="docs">Footnote behaviour</h3> + +<p> +Footnotes can be sly little beasts. If you’re writing a +document that’s footnote-heavy, you might want to read the +following. +</p> + +<p> +By default, mom marks footnotes with alternating stars (asterisks), +daggers, and double-daggers. The first footnote gets a star, the +second a dagger, the third a double-dagger, the fourth two stars, +the fifth two daggers, etc. If you prefer numbered footnotes, rest +assured mom is happy to oblige. +</p> + +<p> +A small amount of vertical whitespace and a short horizontal rule +separate footnotes from the document body. When +<a href="docprocessing.html#flex-vs-shim">shimming</a> +is enabled, the amount of whitespace +may vary slightly from page to page depending on the number of lines +in the footnotes. Mom tries for a nice balance between too little +whitespace and too much, but when push comes to shove, she’ll +usually opt for ample over cramped. The last lines of footnotes are +always flush with the document’s bottom margin. +</p> + +<p> +When +<a href="docprocessing.html#flex-vs-shim">flex-spacing</a> +is enabled, the distance between the last line of text and the +first footnote is always the same. +</p> + +<p> +If mom sees that a portion of a footnote cannot be fit on its page, +she carries that portion over to the next page. If an entire +footnote can’t be fit on its page (i.e., FOOTNOTE has been +called too close to the bottom), she defers the footnote to the next +page, but sets it with the appropriate marker from the previous +page. +</p> + +<p> +When footnotes occur within cited text, for example a +<a href="#quote">QUOTE</a> +or a +<a href="#blockquote">BLOCKQUOTE</a>, +mom will usually opt for deferring the footnote over to the next +page if it allows her to complete the cited text on one page. +</p> + +<p> +In the unfortunate happenstance that a deferred footnote is the +only footnote on its page (i.e., it’s marked in the document +body with a star) and the page it’s deferred to has its own +footnotes, mom separates the deferred footnote from the page’s +proper footnote(s) with a blank line. This avoids the confusion +that might result from readers seeing two footnote entries on +the same page identified by a single star (or the number 1 if +you’ve requested numbered footnotes that begin at 1 on every +page). The blank line makes it clear that the first footnote entry +belongs to the previous page. +</p> + +<p> +In the circumstance where a deferred footnote is not the only one +on its page, and is consequently marked by something other than +a single star, there’s no confusion and mom doesn’t +bother with the blank line. (By convention, the first footnote on +a page is always marked with a single star, so if readers see, say, +a dagger or double-dagger marking the first footnote entry, +they’ll know the entry belongs to the previous page). +</p> + +<p> +Very exceptionally, two footnotes may have to be deferred (e.g., one +occurs on the second to last line of a page, and another on the last +line). In such a circumstance, mom does not add +a blank after the second deferred footnote. If you’d like a blank +line separating both deferred footnotes from any footnotes proper to +the page the deferred ones were moved to, add the space manually by +putting a +<a href="typesetting.html#space"><kbd>.SPACE</kbd></a> +command at the end of the footnote text, before +<kbd>.FOOTNOTE OFF</kbd> (or <kbd>OFF</kbd>, <kbd>QUIT</kbd>, +<kbd>END</kbd>, <kbd>X</kbd>, etc). +</p> + +<p> +Obviously, deferred footnotes aren’t an issue if you request +numbered footnotes that increase incrementally throughout the whole +document—yet another convenience mom has thought of. +</p> + +<p> +While mom’s handling of footnotes is sophisticated, +and tries to take nearly every imaginable situation under which they +might occur into account, some situations are simply impossible from +a typographic standpoint. For example, if you have a +<a href="#head">HEAD</a> +near the bottom of a page and the page has some footnotes on it, mom +may simply not have room to set any text under the head (normally, +she insists on having room for at least one line of text beneath +a head). In such an instance, mom will either set the head, with +nothing under it but footnotes, or transfer the head to the next +page. Either way, you’ll have a gaping hole at the bottom +of the page. It’s a sort of typographic Catch-22, and can +only be resolved by you, the writer or formatter of the document, +adjusting the type on the offending page so as to circumvent the +problem. +</p> + +<h3 id="fn-and-punct" class="docs">Footnote markers and punctuation in the running text</h3> + +<ol style="margin-left: -1.25em;"> + <li><a href="#fn-and-punct-fill">“Fill” modes – JUSTIFY, or QUAD LEFT | CENTER | RIGHT</a></li> + <li><a href="#fn-and-punct-nofill">“No-fill” modes – LEFT, CENTER, RIGHT</a></li> +</ol> + +<h4 id="fn-and-punct-fill" class="docs">1. “Fill” modes – JUSTIFY, or QUAD LEFT | CENTER | RIGHT</h4> + +<p> +In +<a href="definitions.html#filled">fill</a> +modes, the correct way to enter the line after +<kbd>.FOOTNOTE OFF</kbd> is to input it as if it’s +literally a continuation of the input line you were entering before +you invoked <kbd>.FOOTNOTE</kbd>. Therefore, if necessary, the +input line may have to begin with space(s) or a punctuation mark, as +in the two following examples. +</p> + +<div id="examples-footnotes-1" class="examples-container" style="padding-bottom: 1em;"> +<div class="examples" style="margin-top: 0; margin-bottom: -.25em;">Example 1</div> +<span class="pre"> +A line of text,\c +.FOOTNOTE +A footnote line. +.FOOTNOTE OFF + broken up with a comma. +^ +(last line begins with a literal space) +</span> +</div> + +<div id="examples-footnotes-2" class="examples-container" style="margin-top: 1em; padding-bottom: 1em;"> +<div class="examples" style="margin-top: 0; margin-bottom: -.25em;">Example 2</div> +<span class="pre"> +A line of text\c +.FOOTNOTE +A footnote line. +.FOOTNOTE OFF +, broken up with a comma. +^ +(last line begins with a comma and a space) +</span> +</div> + +<p> +Example 1 produces, on output +<br/> +<span class="pre-in-pp"> + A line of text,* broken up with a comma. +</span> +Example 2 produces +<br/> +<span class="pre-in-pp"> + A line of text*, broken up with a comma. +</span> +Care must be taken, though, if the punctuation mark that begins the +line after <kbd>.FOOTNOTE OFF</kbd> is a period (dot). You +<b><i>must</i></b> begin such lines with <kbd>\&.</kbd>, like +this: +<br/> +<span class="pre-in-pp"> + ...end of sentence\c + .FOOTNOTE + A footnote line. + .FOOTNOTE OFF + \&. A new sentence... +</span> +If you omit the <kbd>\&.</kbd>, the line will vanish! +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +The document element tags, +<a href="#epigraph">EPIGRAPH</a> +and +<a href="#blockquote">BLOCKQUOTE</a>, +imply a fill mode, therefore these instructions also apply when you +insert a footnote into epigraphs or blockquotes. +</p> +</div> + +<h4 id="fn-and-punct-nofill" class="docs">2. “No-fill” modes – LEFT, CENTER, RIGHT</h4> + +<p> +In +<a href="definitions.html#filled">no-fill</a> +modes, you must decide a) whether text on the <i>input</i> line +after <kbd>.FOOTNOTE OFF</kbd> is to be joined to the +<i>output</i> line before <kbd>.FOOTNOTE</kbd> was invoked, or b) +whether you want the <i>output</i> text to begin on a new line. +</p> + +<p> +In the first instance, simply follow the instructions, +<a href="#fn-and-punct-fill">above</a>, +for fill modes. +</p> + +<p> +In the second instance, you must explicitly tell mom that +you want input text after <kbd>.FOOTNOTE OFF</kbd> to +begin on a new output line. This is accomplished by passing +<kbd>.FOOTNOTE OFF</kbd> (or <kbd>OFF</kbd>, <kbd>QUIT</kbd>, +<kbd>END</kbd>, <kbd>X</kbd>, etc) an additional argument: +<kbd>BREAK</kbd> or <kbd>BR</kbd>. +</p> + +<p> +Study the two examples below to understand the difference. +</p> + +<div id="examples-footnotes-3" class="examples-container" style="padding-bottom: 1em;"> +<div class="examples" style="margin-top: 0; margin-bottom: -.25em;">Example 1</div> +<span class="pre"> +.LEFT +A line of text\c +.FOOTNOTE +A footnote line +.FOOTNOTE OFF +that carries on after the footnote. +</span> +</div> + +<div id="examples-footnotes-4" class="examples-container" style="margin-top: 1em; padding-bottom: 1em;"> +<div class="examples" style="margin-top: 0; margin-bottom: -.25em;">Example 2</div> +<span class="pre"> +.LEFT +A line of text\c +.FOOTNOTE +A footnote line +.FOOTNOTE OFF BREAK +that doesn’t carry on after the footnote. +</span> +</div> + +<p> +Example 1, on output, produces +<br/> +<span class="pre-in-pp"> + A line of text* that carries on after the footnote. +</span> +whereas Example 2 produces +<span class="pre-in-pp"> + A line of text* + that doesn’t carry on after the footnote. +</span> +The distinction becomes particularly important if you like to see +punctuation marks come <i>after</i> footnote markers. In no-fill +modes, that’s accomplished like this: +<br/> +<span class="pre-in-pp"> + .LEFT + A line of text\c + .FOOTNOTE + A footnote line + .FOOTNOTE OFF + , + broken up with a comma. +</span> +The output of the above looks like this: +<br/> +<span class="pre-in-pp"> + A line of text*, + broken up with a comma. +</span> +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +The document element tag, +<a href="#quote">QUOTE</a>, +implies a no-fill mode, therefore these instructions also apply when +you insert footnotes into quotes. +</p> +</div> + +<!-- -FOOTNOTE- --> + +<div class="macro-id-overline"> +<h3 id="footnote" class="macro-id">FOOTNOTE</h3> +</div> + +<div class="box-macro-args"> +Tag: FOOTNOTE <kbd class="macro-args"><toggle> [ BREAK | BR ] [ INDENT LEFT | RIGHT | BOTH <indent value> ]</kbd> +</div> + +<p class="requires"> +• <kbd><span style="font-style: normal"><indent value></span></kbd> requires a <a href="definitions.html#unitofmeasure">unit of measure</a> +<br/> +See <span style="font-style: normal"><a href="#footnote-note">HYPER-IMPORTANT NOTE</a></span>. +</p> + +<p> +FOOTNOTE is a toggle macro, therefore invoking it on a line by +itself allows you to enter a footnote in the body of a document. +Invoking it with any argument other than <kbd>INDENT</kbd> (i.e. +<kbd>OFF</kbd>, <kbd>QUIT</kbd>, <kbd>END</kbd>, <kbd>X</kbd>...) +tells mom you’re finished. +</p> + +<p> +Footnotes are the only element of +<a href="definitions.html#running">running text</a> +that are not affected by the typesetting +<a href="typesetting.html#indents">indent macros</a>. +In the unlikely event that you want a page’s footnotes to +line up with a running indent, invoke <kbd>.FOOTNOTE</kbd> with +the <kbd>INDENT</kbd> argument and pass it an indent direction and +indent value. <kbd>L, R,</kbd> and <kbd>B</kbd> may be used in place +of <kbd>LEFT, RIGHT,</kbd> and <kbd>BOTH</kbd>. FOOTNOTE must be +invoked with <kbd>INDENT</kbd> for every footnote you want indented; +mom does not save any footnote indent information from invocation to +invocation. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +If a footnote runs to more than one paragraph, do <i>not</i> begin +the footnote with the +<a href="#pp">PP</a> +tag. Use <kbd>.PP</kbd> only to introduce subsequent paragraphs. +</p> +</div> + +<div id="footnote-note" class="box-tip"> +<p class="tip-top"> +<span class="note">HYPER-IMPORTANT NOTE:</span> +The final word on the +<a href="definitions.html#inputline">input line</a> +that comes immediately before FOOTNOTE <i>must</i> terminate with a +<kbd><a href="typesetting.html#join">\c</a></kbd> +inline escape if your +<a href="#footnote-marker-style">FOOTNOTE_MARKER_STYLE</a> +is either <kbd>STAR</kbd> or <kbd>NUMBER</kbd>. See the +<a href="#footnote-example">footnote example</a> +above. +</p> + +<p> +Additionally, in +<a href="definitions.html#filled">fill</a> +modes +(<a href="typesetting.html#justify">JUSTIFY</a> +or +<a href="typesetting.html#quad">QUAD</a>), +the line <i>after</i> a <kbd>.FOOTNOTE OFF</kbd> should be +entered as if there were no interruption in the input text, i.e., +the line should begin with a literal space or punctuation mark (see +explanation and examples +<a href="#fn-and-punct">here</a>). +</p> + +<p> +In +<a href="definitions.html#filled">no-fill</a> +modes, the optional argument <kbd>BREAK</kbd> or <kbd>BR</kbd> may +be used after the <kbd>OFF</kbd> (or <kbd>OFF</kbd>, +<kbd>QUIT</kbd>, <kbd>END</kbd>, <kbd>X</kbd>, etc) argument to +instruct mom not to join the next input line to the previous output. +See +<a href="#fn-and-punct-nofill">here</a> +for a more complete explanation, with examples. +</p> + +<p class="tip-bottom"> +Do not use the <kbd>\c</kbd> inline escape if your +FOOTNOTE_MARKER_STYLE is <kbd>LINE</kbd>, or if you have disabled +footnote markers with +<kbd><a href="#footnote-markers">.FOOTNOTE_MARKERS OFF</a></kbd>. +In these instances, the line after <kbd>.FOOTNOTE OFF</kbd> +should be entered normally. +</p> +</div> + +<div class="defaults-container" style="background-color: #ded4bd; border: none;"> +<h3 id="footnote-control" class="docs defaults">FOOTNOTE control macros and defaults</h3> + +<ol style="margin-top: .5em; padding-bottom: .5em;"> + <li><a href="#footnote-general">Family/font/size/colour/lead/quad</a></li> + <li><a href="#footnote-markers">Footnote markers</a> – on or off</li> + <li><a href="#footnote-marker-style">Footnote marker style</a> – star+dagger or numbered + <ul style="margin-left: -.5em; list-style-type: disc;"> + <li><a href="#footnote-number-placeholders">Left padding of footnote numbers</a></li> + </ul></li> + <li><a href="#footnotes-by-linenumber">Footnotes by line number</a> + <ul style="margin-left: -.5em; list-style-type: disc;"> + <li><a href="#footnote-linenumber-brackets">FOOTNOTE_LINENUMBER_BRACKETS</a></li> + <li><a href="#footnote-linenumber-separator">FOOTNOTE_LINENUMBER_SEPARATOR</a></li> + <li><a href="#footnotes-run-on">FOOTNOTES_RUN_ON</a> – line-numbered footnotes only</li> + </ul></li> + <li><a href="#reset-footnote-number">Reset footnote number</a> – set footnote marker number to 1</li> + <li><a href="#footnote-space">Inter-footnote spacing</a></li> + <li><a href="#footnote-rule">Footnote rule</a> – on or off</li> + <li><a href="#footnote-rule-length">Footnote rule length</a> – length of footnote separator rule</li> + <li><a href="#footnote-rule-weight">Footnote rule weight</a> – weight of footnote separator rule</li> + <li><a href="#footnote-rule-adj">Adjust vertical position of footnote separator rule</a></li> +</ol> +</div> + +<h4 id="footnote-general" class="docs" style="margin-top: -1.5em; margin-bottom: .5em;">1. Family/font/size/colour/lead/quad</h4> + +<div class="defaults-container" style="padding-bottom: 8px;"> +<p class="defaults" style="padding-top: 6px;"> +See +<a href="#control-macro-args">Arguments to the control macros</a>. +<br/> +The following FOOTNOTE control macros may also be +<a href="#grouping">grouped</a> +using FOOTNOTE_STYLE. +</p> +<span class="pre defaults"> +.FOOTNOTE_FAMILY default = prevailing document family; default is Times Roman +.FOOTNOTE_FONT default = roman +.FOOTNOTE_SIZE default = -2 (points) +.FOOTNOTE_COLOR default = black +.FOOTNOTE_AUTOLEAD default = 2 points (typeset); single-spaced (typewrite) +.FOOTNOTE_QUAD default = same as paragraphs +</span> +</div> + +<h4 id="footnote-markers" class="docs" style="margin-top: -1.25em;">2. Footnote markers – FOOTNOTE_MARKERS</h4> + +<p> +If you don’t want footnote markers in either the body of +the document or beside footnote entries themselves, toggle them +off with <kbd>.FOOTNOTE_MARKERS OFF</kbd> (or <kbd>OFF</kbd>, +<kbd>QUIT</kbd>, <kbd>END</kbd>, <kbd>X</kbd>...). This means, +of course, that you’ll have to roll your own. If you want +them back on, invoke <kbd>.FOOTNOTE_MARKERS</kbd> with no argument. +Footnote markers are on by default. +</p> + +<p> +If FOOTNOTE_MARKERS are disabled, do not use the <kbd>\c</kbd> +inline escape to terminate the line before <kbd>.FOOTNOTE</kbd>. +</p> + +<h4 id="footnote-marker-style" class="docs" style="margin-top: -.25em;">3. Footnote marker style – FOOTNOTE_MARKER_STYLE</h4> + +<p> +Mom gives you two choices of footnote marker style: star+dagger (see +<a href="#footnote-behaviour">footnote behaviour</a> +above), or numbered. +</p> + +<p> +<kbd>.FOOTNOTE_MARKER_STYLE STAR</kbd> gives you star+dagger (the +default). There is a limit of 10 footnotes per page with this +style. +</p> + +<p> +<kbd>.FOOTNOTE_MARKER_STYLE NUMBER</kbd> gives you superscript +numbers, both in the document body and in the footnote entries +themselves. By default, footnote numbers increase incrementally +(prev. footnote number + 1) throughout the whole document. You +can ask mom to start each page’s footnote numbers at 1 with +<kbd>.RESET_FOOTNOTE_NUMBER</kbd> +(<a href="#reset-footnote-number">see below</a>.) +</p> + +<p> +If your +<a href="docprocessing.html#printstyle">PRINTSTYLE</a> +is <kbd>TYPEWRITE</kbd> and you would prefer that the footnotes +themselves not use superscript numbers, you may pass +<kbd>.FOOTNOTE_MARKER_STYLE NUMBER</kbd> an additional argument: +<kbd>NO_SUPERSCRIPT</kbd>. While the marker in the text will still +be superscript, the footnotes themselves will be identified with +normal-sized, base aligned numbers, surrounded by parentheses. +</p> + +<h5 id="footnote-number-placeholders" class="docs">Left padding of footnote numbers</h5> + +<p> +When footnote numbering is enabled, in order to ensure that the +left margin of footnote text aligns regardless of the footnote +number, you sometimes have to pad the footnote numbers. This will +be the case any time the footnote numbers change from 9 to 10 on +the same page, or from 99 to 100. Consider this scenario: +<br/> +<span class="pre-in-pp"> + <sup>9</sup> Footnote text + <sup>10</sup> Footnote text + <sup>11</sup> Footnote text +</span> +As you can see, the left margins of the footnotes are not aligned. +</p> + +<p> +In order to correct this, use the macro +<kbd>.FOOTNOTE_NUMBER_PLACEHOLDERS</kbd>, which takes a single +argument: the number of placeholders in the longer digit. For +example, placed at an appropriate point in your input file, +<kbd>.FOOTNOTE_NUMBER_PLACEHOLDERS 2</kbd> causes the above +example to come out like this: +<br/> +<span class="pre-in-pp"> + <sup> 9</sup> Footnote text + <sup>10</sup> Footnote text + <sup>11</sup> Footnote text +</span> +Given the impossibility of knowing in advance when the number of +placeholders required for footnote numbers will change, you must +study your <i>output</i> file to determine where to insert this +macro into your <i>input</i> file. +</p> + +<p> +Obviously, mom does not provide a default for +<kbd>.FOOTNOTE_NUMBER_PLACEHOLDERS</kbd>. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +<kbd>.FOOTNOTE_NUMBER_PLACEHOLDERS</kbd> affects both superscript +footnote numbers, and, in +<a href="docprocessing.html#printstyle">PRINTSTYLE TYPEWRITE</a>, +the normal, base-aligned numbers surrounded by parentheses that you +get with +<kbd>.FOOTNOTE_MARKER_STYLE NUMBER NO_SUPERSCRIPT</kbd>. +</p> +</div> + +<h4 id="footnotes-by-linenumber" class="docs" style="margin-top: -.25em;">4. Footnotes by line number – FOOTNOTE_MARKER_STYLE LINE</h4> + +<p> +FOOTNOTE_MARKER_STYLE with the argument, <kbd>LINE</kbd> lets you +have footnotes which are identified by line number, rather than by a +marker in the text. (Note that +<a href="#number-lines">NUMBER_LINES</a> +must be enabled in order to use this marker style.) +</p> + +<p> +With FOOTNOTE_MARKER_STYLE <kbd>LINE</kbd>, mom will identify +footnotes either by single line numbers, or line ranges. If +what you want is a single line number, you need only invoke +<kbd>.FOOTNOTE</kbd>, <i>without the terminating</i> <kbd>\c</kbd>, +at the appropriate place in running text. Input lines after the +footnote has been terminated (e.g. with +<kbd>.FOOTNOTE OFF</kbd>) are entered normally. +</p> + +<p> +If you want a range of line numbers (e.g. [5-11] ), +insert, directly into the first line of the range you want, the +<a href="definitions.html#inlines">inline escape</a>, +<kbd><span class="nobr">\*[FN_MARK]</span></kbd>. For the terminating line +number of the range, you need only invoke <kbd>.FOOTNOTE</kbd> +(again, without the terminating <kbd>\c</kbd>); mom is smart enough +to figure out that where <kbd>.FOOTNOTE</kbd> was invoked represents +the terminating line number. +</p> + +<p> +Range-numbered footnotes are always output on the page +where <kbd>.FOOTNOTE</kbd> was invoked, not the page where +<kbd><span class="nobr">\*[FN_MARK]</span></kbd> appears (subject, of course, to +the rules for footnotes that fall too close to the bottom of a page, +as outlined +<a href="#footnote-rules">here</a>). +</p> + +<p> +The behaviour of line-numbered footnotes can be controlled with the +macros: +<br/> +<span style="display: inline-block; margin-left: 2em; margin-top: .5em;"><a href="#footnote-linenumber-brackets">FOOTNOTE_LINENUMBER_BRACKETS</a></span> +<br/> +<span style="margin-left: 2em;"><a href="#footnote-linenumber-separator">FOOTNOTE_LINENUMBER_SEPARATOR</a></span> +<br/> +<span style="margin-left: 2em;"><a href="#footnotes-run-on">FOOTNOTES_RUN_ON</a></span> +</p> + +<div style="margin-left: 1.25em;"> +<h5 id="footnote-linenumber-brackets" class="docs" style="margin-top: -.25em;">• FOOTNOTE_LINENUMBER_BRACKETS</h5> + +<p style="margin-left: .5em;"> +Mom, by default, surrounds footnote line numbers with square +brackets. The style of the brackets may be changed with the macro +<br/> +<span class="pre-in-pp"> + .FOOTNOTE_LINENUMBER_BRACKETS +</span> +which takes one of three possible arguments: <kbd>PARENS</kbd> +(round brackets), <kbd>SQUARE</kbd> (the default) or +<kbd>BRACES</kbd> (curly braces). If you prefer a shortform, the +arguments, <kbd>(</kbd>, <kbd>[</kbd> or <kbd>{</kbd> may be used +instead. +</p> + +<p style="margin-left: .5em;">Thus, for example, either +<br/> +<span class="pre-in-pp"> + .FOOTNOTE_LINENUMBER_BRACKETS PARENS +</span> +or +<br/> +<span class="pre-in-pp"> + .FOOTNOTE_LINENUMBER_BRACKETS ( +</span> +will surround footnote line numbers with round brackets. +</p> + +<h5 id="footnote-linenumber-separator" class="docs" style="margin-top: -.25em;">• FOOTNOTE_LINENUMBER_SEPARATOR</h5> + +<p style="margin-left: .5em;"> +If you don’t want the numbers enclosed in brackets, you +may tell mom to use a “separator” instead. A common +separator would be the colon, but it can be anything you like. +The macro to do this is +<br/> +<span class="pre-in-pp"> + .FOOTNOTE_LINENUMBER_SEPARATOR +</span> +which takes, as its single argument, the separator you want. For +safety and consistency’s sake, always enclose the argument in +double-quotes. The separator can be composed of any valid groff +character, or any combination of characters. +</p> + +<p style="margin-left: .5em;"> +<b>A word of caution:</b> when using a separator, mom doesn’t +insert any space after the separator. Hence, if you want space +(you probably do), you must make the space part of the argument you +pass to FOOTNOTE_LINENUMBER_SEPARATOR. For example, to get a colon +separator with a space after it, you’d do +<br/> +<span class="pre-in-pp"> + .FOOTNOTE_LINENUMBER_SEPARATOR ": " +</span> +</p> + +<h5 id="footnotes-run-on" class="docs" style="margin-top: -1em;">• FOOTNOTES_RUN_ON</h5> + +<p style="margin-left: .5em;"> +Finally, if your footnote marker style is <kbd>LINE</kbd>, you may +instruct mom to do “run-on style” footnotes. Run-on +footnotes do not treat footnotes as discrete entities, i.e. each +beginning on a new line. Rather, each footnote is separated from +the footnote before it by horizontal space in the running line, so +that the footnotes on any given page form a continuous block, like +lines in a paragraph. +</p> + +<p style="margin-left: .5em;"> +The macro to get mom to run footnotes on is +<br/> +<span class="pre-in-pp"> + .FOOTNOTES_RUN_ON +</span> +Invoked by itself, it turns the feature on. Invoked with any other +argument (<kbd>OFF, NO</kbd>, etc.), it turns the feature off. +It is generally not a good idea to turn the feature on and off +during the course of a single document. If you do, mom will issue +a warning if there’s going to be a problem. However, it is +always perfectly safe to enable/disable the feature after +<a href="rectoverso.html#collate">COLLATE</a>. +</p> +</div> + +<h4 id="reset-footnote-number" class="docs" style="margin-top: -.25em;">5. Reset footnote number – RESET_FOOTNOTE_NUMBER</h4> + +<p> +<kbd>.RESET_FOOTNOTE_NUMBER</kbd>, by itself, resets footnote +numbering so that the next footnote you enter is numbered 1. +</p> + +<p> +<kbd>.RESET_FOOTNOTE_NUMBER PAGE</kbd> tells mom to start every +page’s footnote numbering at 1. +</p> + +<h4 id="footnote-space" class="docs" style="margin-top: -.25em;">6. Inter-footnote spacing – FOOTNOTE_SPACING</h4> + +<p> +If you’d like some space between footnotes, you can +have mom put it in for you by invoking <kbd>.FOOTNOTE_SPACING</kbd> +with an argument representing the amount of extra space you’d +like. The argument to FOOTNOTE_SPACING requires a +<a href="definitions.html#unitofmeasure">unit of measure</a>. +</p> + +<p> +In the following example, footnotes will be separated from each +other by 3 +<a href="definitions.html#picaspoints">points</a>. +<br/> +<span class="pre-in-pp"> + .FOOTNOTE_SPACING 3p +</span> +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +If you’re using footnotes for references generated from the +refer database (see +<a href="refer.html">refer.html</a>), +correct MLA style requires a full linespace between footnotes, which +you can accomplish with <kbd>.FOOTNOTE_SPACING 1v</kbd>. +</p> +</div> + +<h4 id="footnote-rule" class="docs" style="margin-top: -.25em;">7. Footnote rule – FOOTNOTE_RULE</h4> + +<p> +If you don’t want a footnote separator rule, toggle it +off with <kbd>.FOOTNOTE_RULE OFF</kbd> (or <kbd>END</kbd>, +<kbd>QUIT</kbd>, <kbd>X</kbd>...). Toggle it back on by invoking +<kbd>.FOOTNOTE_RULE</kbd> with no argument. The default is to print +the rule. +</p> + +<h4 id="footnote-rule-length" class="docs" style="margin-top: -.25em;">8. Footnote rule length – FOOTNOTE_RULE_LENGTH</h4> + +<p> +If you want to change the length of the footnote separator rule, +invoke <kbd>.FOOTNOTE_RULE_LENGTH</kbd> with a length, like this, +<br/> +<span class="pre-in-pp"> + .FOOTNOTE_RULE_LENGTH 1i +</span> + +which sets the length to 1 inch. Note that a +<a href="definitions.html#unitofmeasure">unit of measure</a> +is required. The default is 4 +<a href="definitions.html#picaspoints">picas</a> +for both +<a href="docprocessing.html#printstyle">PRINTSTYLE</a>s. +</p> + +<h4 id="footnote-rule-weight" class="docs" style="margin-top: -.25em;">9. Footnote rule weight – FOOTNOTE_RULE_WEIGHT</h4> + +<p> +If you want to change the weight (“thickness”) of the +footnote separator rule, invoke <kbd>.FOOTNOTE_RULE_WEIGHT</kbd> +with the desired weight. The weight is measured in +<a href="definitions.html#picaspoints">points</a>; +however, do not append the +<a href="definitions.html#unitofmeasure">unit of measure</a>, +<kbd>p</kbd>, to the argument. +</p> + +<p> +Mom’s default footnote rule weight is 1/2 point. If +you’d like a 1-point rule instead,<br/> +<span class="pre-in-pp"> + .FOOTNOTE_RULE_WEIGHT 1 +</span> +is how you’d get it. +</p> + +<h4 id="footnote-rule-adj" class="docs" style="margin-top: -.25em;">10. Adjust vertical position of footnote separator rule – FOOTNOTE_RULE_ADJ</h4> + +<p> +The footnote separator rule is a rule whose bottom edge falls +on the +<a href="definitions.html#baseline">baseline</a> +(at the footnote +<a href="definitions.html#leading">leading</a>) +one line above the first line of a page’s footnotes. By default, +mom raises the rule 3 +<a href="definitions.html#picaspoints">points</a> +from the baseline so that the separator and the footnotes don’t +look jammed together. If you’d prefer a different vertical +adjustment, invoke <kbd>.FOOTNOTE_RULE_ADJ</kbd> with the +amount you’d like. For example +<br/> +<span class="pre-in-pp"> + .FOOTNOTE_RULE_ADJ 4.25p +</span> +raises the rule by 4-1/4 points. Note that you can only raise +the rule, not lower it. A +<a href="definitions.html#unitofmeasure">unit of measure</a> +is required. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +If your document +<a href="definitions.html#leading">leading</a> +is 2 +<a href="definitions.html#picaspoints">points</a> +or less (e.g your +<a href="definitions.html#ps">point size</a> +is 10 and your linespacing is 10, 11, or 12), lowering mom’s +default footnote rule adjustment will almost certainly give you +nicer looking results than leaving the adjustment at the default. +Furthermore, you can invoke <kbd>.FOOTNOTE_RULE_ADJ</kbd> on any +page in which footnotes appear, or in any column, so that the +placement of the footnote rule can be changed on-the-fly, should you +wish. +</p> +</div> + +<div class="rule-short"><hr/></div> + +<!-- ==================================================================== --> + +<h2 id="endnote-intro" class="macro-group">Endnotes</h2> + +<ul style="margin-left: -.5em;"> + <li><a href="#endnote-behaviour">Endnotes behaviour</a> + <ul style="margin-left: -.5em;"> + <li><a href="#endnote-columns">Endnotes and columnar documents</a></li> + </ul></li> + <li><a href="#endnote">Tag: ENDNOTE</a></li> + <li><a href="#endnotes">Macro: <b>ENDNOTES</b></a>—tell mom to output endnotes</li> + <li><a href="#endnote-control">ENDNOTES control macros and defaults</a></li> +</ul> + +<p> +Embedding endnotes into mom documents is accomplished the same way +as embedding +<a href="#footnote-intro">footnotes</a>. +The example below is identical to the one shown in the +<a href="#footnote-example">introduction to footnotes</a>, +except that <kbd>.FOOTNOTE</kbd> has been replaced with +<kbd>.ENDNOTE</kbd>. +</p> + +<div id="examples" class="examples-container" style="padding-bottom: 1em;"> +<div class="examples" style="margin-top: 0; margin-bottom: -.25em;">Example</div> +<span id="endnote-example" class="pre"> + ...the doctrines of Identity as urged by Schelling\c + .ENDNOTE + <endnote about who the hell is Schelling> + .ENDNOTE OFF + were generally the points of discussion presenting the most + of beauty to the imaginative Morella. +</span> +</div> + +<p> +As with footnotes, note the obligatory use of the <kbd>\c</kbd> +<a href="definitions.html#inlines">inline escape</a> +when your +<a href="#endnote-marker-style">ENDNOTE_MARKER_STYLE</a> +is <kbd>NUMBER</kbd> or <kbd>SUPERSCRIPT</kbd> (both of which mark +endnotes references in +<a href="definitions.html#running">running text</a> +with superscript numbers). When the marker style is +<kbd>LINE</kbd>, you must <i>not</i> use the <kbd>\c</kbd> +escape. +</p> + +<p> +Endnotes differ from footnotes in two ways (other than the fact that +endnotes come at the end of a document whereas footnotes appear in +the body of the document): +</p> + +<ol style="margin-top: -.5em;"> + <li>When your ENDNOTE_MARKER_STYLE is <kbd>NUMBER</kbd> or + <kbd>SUPERSCRIPT</kbd>, endnotes are always numbered + incrementally, starting at “1”. + </li> + <li>Endnotes must be output explicitly; mom does not output + them for you. In + <a href="rectoverso.html#collate">collated</a> + documents, this allows you to choose whether you want the + endnotes to appear at the end of each chapter or article in a + document, or grouped together at the very end of the document. + </li> +</ol> + +<p> +Within endnotes, you may use the document element tags +<a href="#pp">PP</a>, +<a href="#quote">QUOTE</a> +and +<a href="#blockquote">BLOCKQUOTE</a>. +This provides the flexibility to create endnotes that run to several +paragraphs, as well as to embed cited text within endnotes. +</p> + +<p> +Should you wish to change the appearance of quotes or blockquotes +that appear within endnotes, you may do so with the +<a href="#quote-control">quote control macros</a> +or +<a href="#blockquote-control">blockquote control macros</a>. +However, you must make the changes <i>within</i> each endnote, +prior to invoking <kbd>.QUOTE</kbd> or <kbd>.BLOCKQUOTE</kbd>, +and undo them prior to terminating the endnote (i.e. before +<kbd>.ENDNOTE OFF</kbd>), otherwise the changes will affect +subsequent quotes and blockquotes that appear in the document body +as well. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +See +<a href="refer.html">refer.html</a> +for information on using endnotes with the <kbd>refer</kbd> +bibliographic database. +</p> +</div> + +<h3 id="endnote-behaviour" class="docs">Endnotes behaviour</h3> + +<p> +When you output endnotes (with +<kbd><a href="#endnotes">.ENDNOTES</a></kbd>), +mom finishes processing the last page of your document, then breaks +to a new page for printing the endnotes. If the document type is +<kbd><a href="docprocessing.html#doctype">CHAPTER</a></kbd>, +the centre part of the +<a href="definitions.html#header">header</a> +(or footer), which, by default, contains a chapter number or title, +is removed. +</p> + +<p> +By default, mom starts the endnotes page with a bold, centred head, +“ENDNOTES”. Subsequently, for each section in a +<a href="rectoverso.html#collate-intro">collated</a> +document (e.g. chapters in a book), she identifies the section in bold +type, flush left and underscored, followed by one-half linespace. +Endnotes pertaining to the section are output underneath, identified +by superscript numbers. The text of the endnotes themselves is +indented to the right of the numbers. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +The one-half linespace between section identifiers and the endnotes +themselves, plus the need to group identifiers and endnotes sensibly, +means that mom cannot guarantee perfectly aligned bottom margins. +This is an unavoidable consequence of the structure of endnotes. +</p> +</div> + +<p> +Of course, all the defaults, as well as the overall style of the +endnotes pages, can be changed with the +<a href="#endnote-control">endnote control macros</a>. +The attentive will notice that endnotes have an awful lot of control +macros. This is because endnotes are like a mini-document unto +themselves, and therefore need not be bound by the style parameters +of the body of the document. +</p> + +<h3 id="endnote-columns" class="docs">Endnotes and columnar documents</h3> + +<p> +If your document is set in columns (see +<a href="docprocessing.html#columns">COLUMNS</a>), +mom gives you the option to have endnotes appear in either +the column format or set to the full page width. See +<a href="#endnotes-no-columns">ENDNOTES_NO_COLUMNS</a>. +</p> + +<!-- -ENDNOTE- --> + +<div class="macro-id-overline"> +<h3 id="endnote" class="macro-id">ENDNOTE</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>ENDNOTE</b> <kbd class="macro-args"><toggle> [ BREAK | BR ]</kbd> +</div> +<p class="requires"> +See <span style="font-style: normal"><a href="#endnote-note">HYPER-IMPORTANT NOTE</a></span> +</p> + +<p> +ENDNOTE is a toggle macro, therefore invoking it on a line by itself +allows you to enter an endnote in the body of a document. Invoking +it with any other argument (i.e. <kbd>OFF</kbd>, <kbd>QUIT</kbd>, +<kbd>END</kbd>, <kbd>X</kbd>...) tells mom that you’ve +finished the endnote. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +If an endnote runs to more than one paragraph, do <i>not</i> begin +the endnote with the +<a href="#pp">PP</a> +tag. Use PP only to introduce subsequent paragraphs. +</p> +</div> + +<div id="endnote-note" class="box-tip"> +<p class="tip-top"> +<span class="note">HYPER-IMPORTANT NOTE:</span> +If your +<a href="#endnote-marker-style">ENDNOTE_MARKER_STYLE</a> +is <kbd>NUMBER</kbd> or <kbd>SUPERSCRIPT</kbd> (mom’s +default is <kbd>NUMBER</kbd> unless you have +<a href="refer.html#endnote-refs">ENDNOTE_REFS</a> +enabled, in which case it’s <kbd>SUPERSCRIPT</kbd>), the final word on the +<a href="definitions.html#inputline">input line</a> +that comes immediately before <kbd>.ENDNOTE</kbd> must terminate +with a +<a href="typesetting.html#join"><kbd>\c</kbd></a> +inline escape. See the +<a href="#endnote-example">endnote example</a> +above. +</p> + +<p> +Additionally, in +<a href="definitions.html#filled">fill</a> +modes +(<a href="typesetting.html#justify">JUSTIFY</a> +or +<a href="typesetting.html#quad">QUAD</a>, +the line after <kbd>.ENDNOTE OFF</kbd> should be +entered as if there were no interruption in the input text, i.e., +the line should begin with a literal space or punctuation mark (see +explanation and examples for footnotes, which apply equally to +endnotes, +<a href="#fn-and-punct">here</a>). +</p> + +<p> +In +<a href="definitions.html#filled">no-fill</a> +modes, the optional argument <kbd>BREAK</kbd> or <kbd>BR</kbd> may +be used after the <kbd>OFF</kbd> (or <kbd>OFF</kbd>, +<kbd>QUIT</kbd>, <kbd>END</kbd>, <kbd>X</kbd>, etc) argument to +instruct mom not to join the next input line to the previous output. +See +<a href="#fn-and-punct-nofill">here</a> +for a more complete explanation. The examples are for +<kbd>.FOOTNOTE</kbd>, but apply equally to <kbd>.ENDNOTE</kbd>. +</p> + +<p class="tip-bottom"> +If your ENDNOTE_MARKER_STYLE is LINE, do not use the <kbd>\c</kbd> +escape, and enter the line after <kbd>.ENDNOTE OFF</kbd> normally, +ie at your text editor’s left margin. +</p> +</div> + +<!-- -ENDNOTES- --> + +<div class="macro-id-overline"> +<h3 id="endnotes" class="macro-id">ENDNOTES</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>ENDNOTES</b> +</div> + +<p> +Unlike footnotes, which mom automatically outputs at the bottom +of pages, endnotes must be explicitly output by you, the +user. ENDNOTES, by itself (i.e. without any argument), is the macro +to do this. +</p> + +<p> +Typically, you’ll use ENDNOTES at the end of a document. If +it’s a single (i.e. not collated) document, mom will print +the endnotes pertaining to it. If it’s a collated document, +mom will print all the endnotes contained within all sections of +the document (typically chapters), appropriately identified and +numbered. +</p> + +<p> +Should you wish to output the endnotes for each section of a +collated document at the ends of the sections (instead of at the +very end of the document), simply invoke <kbd>.ENDNOTES</kbd> +immediately prior to +<a href="rectoverso.html#collate">COLLATE</a>. +Mom will print the endnotes, identified and numbered appropriately, +on a separate page prior to starting the next section of the +document. Each subsequent invocation of <kbd>.ENDNOTES</kbd> +outputs only those endnotes that mom collected after the previous +invocation. +</p> + +<div class="defaults-container" style="background-color: #ded4bd; border: none;"> +<h3 id="endnote-control" class="docs defaults">ENDNOTES control macros and defaults</h3> + +<div class="box-important" style="width: 700px; margin: auto; background-color: #ded4bd;"> +<p class="tip-top" style="color: #000056;"> +<span class="important">Important:</span> +Endnotes control macros must always be invoked prior to the first +instance of +<a href="#endnote"><kbd>.ENDNOTE</kbd></a>. +</p> + +<p style="color: #000056; margin-top: -.5em;"> +When you embed endnotes in the body of a document, mom collects +<i>and processes</i> them for later outputting (when you invoke +<a href="#endnotes"><kbd>.ENDNOTES</kbd></a>). +By the time you do invoke <kbd +style="color: #000056;">.ENDNOTES</kbd>, it’s much too late to +change your mind about how you want them to look. +</p> + +<p class="tip-bottom" style="color: #000056; margin-top: -.5em;"> +My advice? If you’re planning to change the default +appearance of endnotes pages, set them up prior to +<a href="docprocessing.html#start">START</a>. +</p> +</div> + +<ol style="margin-top: .5em; padding-bottom: .5em;"> + <li><a href="#endnotes-general"><b>General endnotes style control</b></a> + <ul style="margin-left: -.5em;"> + <li><a href="#endnote-style">Base family/font/quad</a></li> + <li><a href="#endnote-pt-size">Base point size</a></li> + <li><a href="#endnote-lead">Leading</a></li> + <li><a href="#endnote-spacing">Spacing between endnotes</a></li> + <li><a href="#singlespace-endnotes">Singlespace endnotes (TYPEWRITE only)</a></li> + <li><a href="#endnote-para-indent">Paragraph indenting</a></li> + <li><a href="#endnote-para-space">Inter-paragraph spacing</a></li> + <li><a href="#endnotes-no-columns">Turning off column mode during endnotes output</a></li> + </ul></li> + <li><a href="#endnotes-pagination"><b>Pagination of endnotes</b></a> + <ul style="margin-left: -.5em;"> + <li><a href="#endnotes-pagenum-style">Page numbering style</a></li> + <li><a href="#endnotes-first-pagenumber">Setting the first page number of endnotes</a></li> + <li><a href="#endnotes-no-first-pagenum">Omitting a page number on the first page of endnotes</a></li> + <li><a href="#suspend-pagination">Suspending pagination during endnotes output</a></li> + </ul></li> + <li><a href="#endnotes-header-control"><b>Header/footer control</b></a> + <ul style="margin-left: -.5em;"> + <li><a href="#endnotes-modify-hdrftr">Modifying what goes in the endnotes header/footer</a></li> + <li><a href="#endnotes-hdrftr-center">Header/footer centre string when doctype is CHAPTER</a></li> + <li><a href="#endnotes-allows-headers">Allow headers on endnotes pages</a></li> + </ul></li> + <li><a href="#endnotes-header"><b>Endnotes header (first-page title) control</b></a> + <ul style="margin-left: -.5em;"> + <li><a href="#endnotes-header-string">Header string</a></li> + <li><a href="#endnotes-header-string-control">Header string control macros and defaults</a></li> + <li><a href="#endnotes-header-placement">Header string placement</a></li> + <li><a href="#endnotes-header-underscore">Header string underscoring</a></li> + <li><a href="#endnotes-header-caps">Header string capitalization</a></li> + </ul></li> + <li><a href="#endnotes-doc-title"><b>Endnotes document-identification string control</b></a> + <ul style="margin-left: -.5em;"> + <li><a href="#endnote-title">Document-identification string(s)</a></li> + <li><a href="#endnote-title-control">Document-identification string control macros and defaults</a></li> + </ul></li> + <li><a href="#endnotes-numbering"><b>Endnotes referencing style</b></a> + <ul style="margin-left: -.5em;"> + <li><a href="#endnote-marker-style">Endnote marker style</a> – by numbers in the text, or by line number + <ul style="margin-left: -.5em;"> + <li><a href="#endnote-linenumber-gap">Spacing between line-numbered endnotes and the endnote text</a></li> + <li><a href="#endnote-linenumber-brackets">Brackets around endnote line numbers</a></li> + <li><a href="#endnote-linenumber-separator">Separator after endnote line numbers instead of brackets</a></li> + </ul></li> + <li><a href="#endnote-number-control">Endnote numbering control macros and defaults</a></li> + <li><a href="#endnote-number-alignment">Endnote numbering alignment</a></li> + </ul></li> +</ol> +</div> + +<h4 id="endnotes-general" class="docs" style="margin-top: -1.5em; margin-bottom: .5em;">1. General endnotes page style control</h4> + +<h5 id="endnote-style" class="docs" style="margin-top: 0; margin-bottom: .5em; margin-left: .5em;">• Base family/font/quad</h5> + +<div class="defaults-container" style="padding-bottom: 8px;"> +<p class="defaults" style="padding-top: 6px;"> +See +<a href="#control-macro-args">Arguments to the control macros</a>. +<br/> +The following ENDNOTE control macros may also be +<a href="#grouping">grouped</a> +using ENDNOTE_STYLE. +</p> +<span class="pre defaults"> +.ENDNOTE_FAMILY default = prevailing document family; default is Times Roman +.ENDNOTE_FONT default = roman +.ENDNOTE_QUAD* default = justified + +*Note: ENDNOTE_QUAD must be set to either L (LEFT) or J (JUSTIFIED); + R (RIGHT) and C (CENTER) will not work. +</span> +</div> + +<!-- -ENDNOTE_PT_SIZE- --> + +<h5 id="endnote-pt-size" class="docs" style="margin-top: -1.5em; margin-bottom: .5em; margin-left: .5em;">• Base point size</h5> + +<div class="box-macro-args"> +Macro: <b>ENDNOTE_PT_SIZE</b> <kbd class="macro-args"><base type size of endnotes></kbd> +</div> + +<p> +Unlike most other control macros that deal with size of document +elements, ENDNOTE_PT_SIZE takes as its argument an absolute value, +relative to nothing. Therefore, the argument represents the size of +endnote type in +<a href="definitions.html#picaspoints">points</a>, +unless you append an alternative +<a href="definitions.html#unitofmeasure">unit of measure</a>. +For example, +<br/> +<span class="pre-in-pp"> + .ENDNOTE_PT_SIZE 12 +</span> +sets the base point size of type on the endnotes page to 12 +points, whereas +<br/> +<span class="pre-in-pp"> + .ENDNOTE_PT_SIZE .6i +</span> +sets the base point size of type on the endnotes page to 1/6 of an +inch. +</p> + +<p> +The type size set with ENDNOTE_PT_SIZE is the size of type used for +the text of the endnotes, and forms the basis from which the point +size of other endnote page elements is calculated. +</p> + +<p> +The default for +<a href="docprocessing.html#printstyle">PRINTSTYLE <kbd>TYPESET</kbd></a> +is 12.5 points (the same default size used in the body of the +document). +</p> + +<!-- -ENDNOTE_LEAD- --> + +<h5 id="endnote-lead" class="docs" style="margin-top: -.5em; margin-bottom: .5em; margin-left: .5em;">• Leading</h5> + +<div class="box-macro-args"> +Macro: <b>ENDNOTE_LEAD</b> <kbd class="macro-args"><base leading of endnotes> [ ADJUST ] </kbd> +</div> + +<p class="requires"> +• Does not require a <a href="definitions.html#unitofmeasure">unit of measure</a>; points is assumed +</p> + +<p> +Unlike most other control macros that deal with leading of document +elements, ENDNOTE_LEAD takes as its argument an absolute value, +relative to nothing. Therefore, the argument represents the +<a href="definitions.html#leading">leading</a> +of endnotes in +<a href="definitions.html#picaspoints">points</a> +unless you append an alternative +<a href="definitions.html#unitofmeasure">unit of measure</a>. +For example, +<br/> +<span class="pre-in-pp"> + .ENDNOTE_LEAD 14 +</span> +sets the base leading of type on the endnotes page to 14 +points, whereas +<br/> +<span class="pre-in-pp"> + .ENDNOTE_LEAD .5i +</span> +sets the base leading of type on the endnotes page to 1/2 inch. +</p> + +<p> +If you want the leading of endnotes adjusted to fill the page, pass +ENDNOTE_LEAD the optional argument +<kbd>ADJUST</kbd>. (See +<a href="docprocessing.html#doc-lead-adjust">DOC_LEAD_ADJUST</a> +for an explanation of leading adjustment.) +</p> + +<p> +The default for +<a href="docprocessing.html#printstyle">PRINTSTYLE <kbd>TYPESET</kbd></a> +is the prevailing document leading (16 by default), adjusted. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +Even if you give mom a <kbd>.DOC_LEAD_ADJUST OFF</kbd> command, she +will still, by default, adjust endnote leading. You <i>must</i> +enter <kbd>.ENDNOTE_LEAD <lead></kbd> with no +<kbd>ADJUST</kbd> argument to disable this default behaviour. +</p> +</div> + +<!-- -ENDNOTE_SPACING- --> + +<h5 id="endnote-spacing" class="docs" style="margin-top: -.5em; margin-bottom: .5em; margin-left: .5em;">• Spacing between endnotes</h5> + +<div class="box-macro-args"> +Macro: <b>ENDNOTE_SPACING</b> <kbd class="macro-args"><space to insert between endnotes></kbd> +</div> +<p class="requires"> +• Requires a <a href="definitions.html#unitofmeasure">unit of measure</a> +</p> + +<p> +If you’d like some whitespace between endnotes, just invoke +ENDNOTE_SPACING with the amount of space you want, e.g. +<br/> +<span class="pre-in-pp"> + .ENDNOTE_SPACING 6p +</span> +which inserts 6 points of lead between endnotes. Be aware, though, +that inserting space between endnotes means that the bottoms of +endnotes pages will most likely not align. +</p> + +<p> +Mom’s default is not to insert any whitespace between endnotes. +</p> + +<!-- -SINGLESPACE_ENDNOTES- --> + +<h5 id="singlespace-endnotes" class="docs" style="margin-top: 0; margin-bottom: .5em; margin-left: .5em;">• Singlespace endnotes (TYPEWRITE only)</h5> + +<div class="box-macro-args"> +Macro: <b>SINGLESPACE_ENDNOTES</b> <kbd class="macro-args"><toggle></kbd> +</div> + +<p> +If your +<a href="docprocessing.html#printstyle">PRINTSTYLE</a> +is <kbd>TYPEWRITE</kbd> and you use TYPEWRITE’s default +double-spacing, endnotes are double-spaced. If your document is +single-spaced, endnotes are single-spaced. +</p> + +<p> +If, for some reason, you’d prefer that endnotes be +single-spaced in an otherwise double-spaced document (including +double-spaced +<a href="rectoverso.html#collate">collated</a> +documents), invoke +<br/> +<span class="pre-in-pp"> + .SINGLESPACE_ENDNOTES +</span> +with no argument. And if, god help you, you want to change endnote +single-spacing back to double-spacing for different spacing of +endnotes output at the ends of separate documents in a collated +document, invoke <kbd>.SINGLESPACE_ENDNOTES</kbd> with any argument +(<kbd>OFF</kbd>, <kbd>QUIT</kbd>, <kbd>END</kbd>, <kbd>X</kbd>...). +</p> + +<!-- -ENDNOTE_PARA_INDENT- --> + +<h5 id="endnote-para-indent" class="docs" style="margin-top: 0; margin-bottom: .5em; margin-left: .5em;">• Paragraph indenting</h5> + +<div class="box-macro-args"> +Macro: <b>ENDNOTE_PARA_INDENT</b> <kbd class="macro-args"><amount to indent first line of paragraphs in endnotes></kbd> +</div> + +<p class="requires"> +• Requires a <a href="definitions.html#unitofmeasure">unit of measure</a> +</p> + +<p> +ENDNOTE_PARA_INDENT works exactly the same way as +<a href="#para-indent">PARA_INDENT</a>, +except that the indent given is the amount by which to indent the +first lines of endnote paragraphs, not document body paragraphs. +</p> + +<p> +The default is 1.5 +<a href="definitions.html#em">ems</a> +for +<a href="docprocessing.html#printstyle">PRINTSTYLE <kbd>TYPESET</kbd></a>; +1/2 inch for +<a href="docprocessing.html#printstyle">PRINTSTYLE <kbd>TYPEWRITE</kbd></a>. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +The first line of the first paragraph of endnotes (the one attached +immediately to the identifying endnote number) is never indented. +Only subsequent paragraphs are affected by ENDNOTE_PARA_INDENT. +</p> +</div> + +<!-- -ENDNOTE_PARA_SPACE- --> + +<h5 id="endnote-para-space" class="docs" style="margin-top: -.5em; margin-bottom: .5em; margin-left: .5em;">• Inter-paragraph spacing</h5> + +<div class="box-macro-args"> +Macro: <b>ENDNOTE_PARA_SPACE</b> <kbd class="macro-args"><toggle></kbd> +</div> + +<p> +ENDNOTE_PARA_SPACE works exactly the same way as +<a href="#pp-space">PARA_SPACE</a>, +except that it inserts a blank line between endnote paragraphs, not +document body paragraphs. +</p> + +<p> +The default is not to insert a blank line between paragraphs in +endnotes. +</p> + +<!-- -ENDNOTES_NO_COLUMNS- --> + +<h5 id="endnotes-no-columns" class="docs" style="margin-top: 0; margin-bottom: .5em; margin-left: .5em;">• Turning off column mode during endnotes output</h5> + +<div class="box-macro-args"> +Macro: <b>ENDNOTES_NO_COLUMNS</b> <kbd class="macro-args"><toggle></kbd> +</div> + +<p> +By default, if your document is set in +<a href="docprocessing.html#columns">columns</a>, +mom sets the endnotes in columns, too. However, if your document +is set in columns and you’d like the endnotes not to be, +just invoke <kbd>.ENDNOTES_NO_COLUMNS</kbd> with no argument. +The endnotes pages will be set to the full page measure of your +document. +</p> + +<p> +If you output endnotes at the end of each document in a +<a href="rectoverso.html#collate">collated</a> +document set in columns, column mode will automatically be +reinstated for each document, even with ENDNOTES_NO_COLUMNS turned +on. In such circumstances, you must re-enable ENDNOTES_NO_COLUMNS +for each separate collated document. +</p> + +<h4 id="endnotes-pagination" class="docs" style="margin-bottom: .5em;">2. Pagination of endnotes</h4> + +<!-- -ENDNOTES_PAGENUM_STYLE- --> + +<h5 id="endnotes-pagenum-style" class="docs" style="margin-top: 0; margin-bottom: .5em; margin-left: .5em;">• Page numbering style</h5> + +<div class="box-macro-args"> +Macro: <b>ENDNOTES_PAGENUM_STYLE</b> <kbd class="macro-args">DIGIT | ROMAN | roman | ALPHA | alpha</kbd> +</div> + +<p> +Use this macro to set the page numbering style of endnotes pages. +The arguments are identical to those for +<a href="headfootpage.html#pagenum-style">PAGENUM_STYLE</a>. +The default is <kbd>digit</kbd>. You may want to change it to, say, +<kbd>alpha</kbd>, which you would do with +<br/> +<span class="pre-in-pp"> + .ENDNOTES_PAGENUM_STYLE alpha +</span> +</p> + +<!-- -ENDNOTES_FIRST_PAGENUMBER- --> + +<h5 id="endnotes-first-pagenumber" class="docs" style="margin-top: -.5em; margin-bottom: .5em; margin-left: .5em;">• Setting the first page number of endnotes</h5> + +<div class="box-macro-args"> +Macro: <b>ENDNOTES_FIRST_PAGENUMBER</b> <kbd class="macro-args"><page # that appears on page 1 of endnotes></kbd> +</div> + +<p> +Use this macro with caution. If all endnotes for several +<a href="rectoverso.html#collate">collated</a> +documents are to be output at once, i.e. not at the end of each +separate doc, ENDNOTES_FIRST_PAGENUMBER tells mom what page number +to put on the first page of the endnotes. +</p> + +<p> +However, if you set ENDNOTES_FIRST_PAGENUMBER in collated documents +in which the endnotes are output after each section (chapter, +article, etc), you have to reset every section’s first page +number after +<a href="rectoverso.html#collate">COLLATE</a> +and before +<a href="docprocessing.html#start">START</a> +with +<a href="headfootpage.html#pagenumber">PAGENUMBER</a>. +</p> + +<!-- -ENDNOTES_NO_FIRST_PAGENUN- --> + +<h5 id="endnotes-no-first-pagenum" class="docs" style="margin-top: -.25em; margin-bottom: .5em; margin-left: .5em;">• Omitting a page number on the first page of endnotes</h5> + +<div class="box-macro-args"> +Macro: <b>ENDNOTES_NO_FIRST_PAGENUM</b> <kbd class="macro-args"><toggle></kbd> +</div> + +<p> +This macro is for use only if +<a href="headfootpage.html#footers">FOOTERS</a> +are on. It tells +<a href="#endnotes">ENDNOTES</a> +not to print a page number on the first endnotes page. Mom’s +default is to print the page number. +</p> + +<!-- -SUSPEND_PAGINATION- --> + +<h5 id="suspend-pagination" class="docs" style="margin-top: -.5em; margin-bottom: .5em; margin-left: .5em;">• Suspending pagination during endnotes output</h5> + +<div class="box-macro-args" style="margin-bottom: 1em;"> +Macro: <b>SUSPEND_PAGINATION</b> +</div> + +<div class="box-macro-args"> +Macro: <b>RESTORE_PAGINATION</b> +</div> + +<p> +SUSPEND_PAGINATION doesn’t take an argument. Invoked +immediately prior to +<a href="#endnotes">ENDNOTES</a>, +it turns off endnotes pages pagination. Mom continues, however to +increment page numbers silently. +</p> + +<p> +To restore normal document pagination after endnotes, invoke +<kbd>.RESTORE_PAGINATION</kbd> (again, with no argument) immediately +after <kbd>.ENDNOTES</kbd>. +</p> + +<h4 id="endnotes-header-control" class="docs" style="margin-bottom: .5em;">3. Header/footer control</h4> + +<h5 id="endnotes-modify-hdrftr" class="docs" style="margin-top: 0; margin-bottom: -.75em; margin-left: .5em;">• Modifying what goes in the endnotes header/footer</h5> + +<p> +If you wish to modify what appears in the header/footer that appears +on endnotes page(s), make the changes before you invoke +<a href="#endnotes"><kbd>.ENDNOTES</kbd></a>, +not afterwards. +</p> + +<p> +Except in the case of +<a href="docprocessing.html#doctype">DOCTYPE <kbd>CHAPTER</kbd></a>, +mom prints the same header or footer used throughout the document +on the endnotes page(s). Chapters get treated differently in that, +by default, mom does not print the header/footer centre string +(normally the chapter number or chapter title.) In most cases, this +is what you want. However, should you not want mom to remove +the centre string from the endnotes page(s) headers/footers, invoke +<kbd><a href="#endnotes-hdrftr-center">.ENDNOTES_HEADER_CENTER</a></kbd> +with no argument. +</p> + +<p> +An important change you may want to make is to put the word +“Endnotes” in the header/footer centre position. To do +so, invoke +<br/> +<span class="pre-in-pp" style="margin-bottom: -1em;"> + .HEADER_CENTER "Endnotes" +</span> +or +<span class="pre-in-pp" style="margin-top: -.5em;"> + .FOOTER_CENTER "Endnotes" +</span> +prior to invoking <kbd>.ENDNOTES</kbd>. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +If your +<a href="docprocessing.html#doctype">DOCTYPE</a> +is <kbd>CHAPTER</kbd>, you must also invoke +<a href="#endnotes-hdrftr-center">ENDNOTES_HEADER_CENTER</a> +for the ENDNOTES_HEADER_CENTER to appear. +</p> +</div> + +<h5 id="endnotes-hdrftr-center" class="docs" style="margin-top: 0; margin-bottom: .5em; margin-left: .5em;">• Header/footer centre string when doctype is CHAPTER</h5> + +<div class="box-macro-args"> +Macro: <b>ENDNOTES_HEADER_CENTER</b> <kbd class="macro-args">toggle</kbd> +</div> + +<p> +If your +<a href="docprocessing.html#doctype">DOCTYPE</a> +is <kbd>CHAPTER</kbd> and you want mom to include a centre +string in the headers/footers that appear on endnotes +pages, invoke <kbd>.ENDNOTES_HEADER_CENTER</kbd> (or +<kbd>.ENDNOTES_FOOTER_CENTER</kbd>) with no argument. Mom’s +default is not to print the centre string. +</p> + +<p> +If, for some reason, having enabled the header/footer centre string +on endnotes pages, you wish to disable it, invoke the same macro +with any argument (<kbd>OFF</kbd>, <kbd>QUIT</kbd>, <kbd>END</kbd>, +<kbd>X</kbd>...). </p> + +<h5 id="endnotes-allows-headers" class="docs" style="margin-top: -.5em; margin-bottom: .5em; margin-left: .5em;">• Allow headers on endnotes pages</h5> + +<div class="box-macro-args"> +Macro: <b>ENDNOTES_ALLOWS_HEADERS</b> <kbd class="macro-args"><none> | ALL</kbd> +</div> + +<p> +By default, if HEADERS are on, mom prints page headers on all +endnotes pages except the first. If you don’t want her to +print headers on endnotes pages, do +<br/> +<span class="pre-in-pp"> + .ENDNOTES_ALLOWS_HEADERS OFF +</span> +If you want headers on every page including the first, do +<br/> +<span class="pre-in-pp"> + .ENDNOTES_ALLOWS_HEADERS ALL +</span> +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +If FOOTERS are on, mom prints footers on every endnotes page. +This is a style convention. In mom, there is no such beast as +ENDNOTES_ALLOWS_FOOTERS OFF. +</p> +</div> + +<h4 id="endnotes-header" class="docs">4. Endnotes header (first-page title) control</h4> + +<!-- -ENDNOTES_HEADER_STRING- --> + +<h5 id="endnotes-header-string" class="docs" style="margin-top: 1em; margin-bottom: .5em; margin-left: .5em;">• Header (first-page title) string</h5> + +<div class="box-macro-args"> +Macro: <b>ENDNOTES_HEADER_STRING</b> <kbd class="macro-args">"<title to print at the top of endnotes>"</kbd> +</div> + +<p class="alias" style="margin-bottom: 0;"> +<i>Alias:</i> <b>ENDNOTE_STRING</b> (for compatibility with older documents) +</p> + +<p> +By default, mom prints the word “ENDNOTES” as a head +at the top of the first page of endnotes. If you want her to +print something else, invoke <kbd>.ENDNOTES_HEADER_STRING</kbd> +with the endnotes-page head you want, surrounded by double-quotes. +If you don’t want a head at the top of the first +endnotes-page, invoke <kbd>.ENDNOTES_HEADER_STRING</kbd> +with a blank argument (either two double-quotes side by +side—<kbd>""</kbd>—or no argument at all). +</p> + +<!-- -ENDNOTES_HEADER_CONTROL- --> + +<h5 id="endnotes-header-string-control" class="docs" style="margin-top: -.5em; margin-bottom: .5em; margin-left: .5em;">• Header (first-page title) control macros and defaults</h5> + +<div class="defaults-container" style="padding-bottom: 8px;"> +<p class="defaults" style="padding-top: 6px;"> +See +<a href="#control-macro-args">Arguments to the control macros</a>. +<br/> +The following ENDNOTES_HEADER control macros may also be +<a href="#grouping">grouped</a> +using ENDNOTES_HEADER_STYLE. +</p> + +<p style="margin-top: .5em; margin-bottom: 0; margin-left: .5em"> +Please note that “_HEADER_”, here, refers to the title +that appears at the top of the first endnotes page, not to the page +headers of subsequent endnotes pages. +<span class="pre defaults"> +.ENDNOTES_HEADER_FAMILY default = prevailing document family +.ENDNOTES_HEADER_FONT default = bold +.ENDNOTES_HEADER_SIZE* default = +1 +.ENDNOTES_HEADER_QUAD default = centred +.ENDNOTES_HEADER_COLOR default = black + +*Relative to the size of the endnotes text (set with ENDNOTE_PT_SIZE) +</span> +</p> +</div> + +<p style="margin-top: -2em"> +<b>Note:</b> <i>For compatibility with older documents, these macros are aliased +as</i> <kbd>.ENDNOTE_STRING_<SPEC></kbd>, e.g. <kbd>.ENDNOTE_STRING_FAMILY</kbd>. +</p> + +<!-- -ENDNOTES_HEADER_V_POS- --> + +<h5 id="endnotes-header-placement" class="docs" style="margin-top: -.25em; margin-bottom: .5em; margin-left: .5em;">• Header (first-page title) placement</h5> + +<div class="box-macro-args"> +Macro: <b>ENDNOTES_HEADER_V_POS</b> <kbd class="macro-args"><distance from top of page></kbd> +</div> + +<p class="requires"> +• Argument requires a <a href="definitions.html#unitofmeasure">unit of measure</a> +</p> + +<p class="alias" style="margin-top: -1em; margin-bottom: 0;"> +<i>Alias:</i> <b>ENDNOTE_STRING_ADVANCE</b> (for compatibility with older documents) +</p> + +<p> +By default, mom places the title (the docheader, as it were) of +endnotes pages (typically "ENDNOTES") on the same +<a href="definitions.html#baseline">baseline</a> +that is used for the start of +<a href="definitions.html#running">running text</a>. +If you’d prefer another location, higher or lower on the page +(thereby also raising or lowering the starting position of the +endnotes themselves), invoke <kbd>.ENDNOTES_HEADER_V_POS</kbd> with +an argument stating the distance from the top edge of the page at +which you’d like the title placed. +</p> + +<p> +The argument requires a unit of measure, so if you’d like the title +to appear 1-1/2 inches from the top edge of the page, you’d tell +mom about it like this: +<br/> +<span class="pre-in-pp"> + .ENDNOTES_HEADER_V_POS 1.5i +</span> +</p> + +<!-- -ENDNOTES_HEADER_UNDERSCORE- --> + +<h5 id="endnotes-header-underscore" class="docs" style="margin-top: -1em; margin-bottom: .5em; margin-left: .5em;">• Header (first-page title) underscoring</h5> + +<div class="box-macro-args"> +Macro: <b>ENDNOTES_HEADER_UNDERSCORE</b> <kbd class="macro-args">[DOUBLE] [<underscore weight> [<underscore gap> [<distance between double rules]]] | <none> | <anything></kbd> +</div> + +<p class="alias" style="margin-bottom: 0;"> +<i>Alias:</i> <b>ENDNOTES_HEADER_UNDERLINE</b>. +<i>(For compatibility with older documents, also +aliased as</i> <b>ENDNOTE_STRING_UNDERSCORE</b> <i>and</i> +<b>ENDNOTE_STRING_UNDERLINE</b>.) +</p> + +<p class="requires"> +• The argument +<span style="font-style: normal"><kbd><underscore weight></kbd></span> +must not have the +<a href="definitions.html#unitofmeasure">unit of measure</a>, +<span style="font-style: normal;"><kbd>p</kbd></span>, +appended to it; all other arguments require a unit of measure +</p> + +<p> +Invoked without an argument, <kbd>.ENDNOTES_HEADER_UNDERSCORE</kbd> +will place a single rule underneath the endnotes page title. Invoked +with the argument, <kbd>DOUBLE</kbd>, ENDNOTES_HEADER_UNDERSCORE will +double-underscore the title. Invoked with any other non-numeric +argument, (e.g. <kbd>OFF, NO, X</kbd>, etc.) the macro disables +underscoring of the title. +</p> + +<p> +In addition, you can use ENDNOTES_HEADER_UNDERSCORE to control the +weight of the underscore rule(s), the gap between the title and the +underscore, and, in the case of double-underscores, the distance +between the two rules. +</p> + +<p> +Some examples: +<br/> +<span class="pre-in-pp"> + .ENDNOTES_HEADER_UNDERSCORE 1 + - turn underscoring on; set the rule weight to 1 point + + .ENDNOTES_HEADER_UNDERSCORE 1 3p + - turn underscoring on; set the rule weight to 1 point; set + the gap between the title and the underscore to 3 points + + .ENDNOTES_HEADER_UNDERSCORE DOUBLE .75 3p + - turn double-underscoring on; set the rule weight to 3/4 of + a point; set the gap between the title and the upper + underscore to 3 points; leave the gap between the upper + and the lower underscore at the default + + .ENDNOTES_HEADER_UNDERSCORE DOUBLE 1.5 1.5p 1.5p + - turn double-underscoring on; set the rule weight to 1-1/2 + points; set the gap between the title and the upper + underscore to 1-1/2 points; set the gap between the upper + and the lower underscore to 1-1/2 points +</span> +Note, from the above, that in all instances, underscoring (single +or double) is enabled whenever ENDNOTES_HEADER_UNDERSCORE is used in +this way. +</p> + +<p> +By default, mom double-underscores the title if your +<a href="docprocessing.html#printstyle">PRINTSTYLE</a> +is <kbd>TYPEWRITE</kbd>. +</p> + +<!-- -ENDNOTES_HEADER_CAPS- --> + +<h5 id="endnotes-header-caps" class="docs" style="margin-top: -.5em; margin-bottom: .5em; margin-left: .5em;">• Header (first-page title) capitalization</h5> + +<div class="box-macro-args"> +Macro: <b>ENDNOTES_HEADER_CAPS</b> <kbd class="macro-args">toggle</kbd> +</div> + +<p class="alias" style="margin-bottom: 0;"> +<i>Alias:</i> <b>ENDNOTE_STRING_CAPS</b> (for compatibility with older documents) +</p> + +<p> +Invoked by itself, <kbd>.ENDNOTES_HEADER_CAPS</kbd> will +automatically capitalize the endnotes-page title. Invoked with any +other argument, the macro disables automatic capitalization of the +title. +</p> + +<p> +If you’re generating a table of contents, you may want the +endnotes pages title to be in caps, but the toc entry in caps/lower +case. If the argument to +<a href="#endnotes-header-string">ENDNOTES_HEADER_STRING</a> +is in caps/lower case and ENDNOTES_HEADER_CAPS is on, this is exactly +what will happen. +</p> + +<p> +Mom’s default is to capitalize the endnotes pages title string. +</p> + +<!-- -ENDNOTE_TITLE- --> + +<h4 id="endnotes-doc-title" class="docs" style="margin-top: -.25em;">5. Endnotes document-identification title control</h4> + +<h5 id="endnote-title" class="docs" style="margin-top: 1em; margin-bottom: .5em; margin-left: .5em;">• Document-identification title string(s)</h5> + +<div class="box-macro-args"> +Macro: <b>ENDNOTE_TITLE</b> <kbd class="macro-args">"<title to identify a document in endnotes>"</kbd> +</div> + +<p> +By default, mom identifies the document(s) to which endnotes belong +by the document title(s) given to the +<a href="docprocessing.html#title">TITLE</a> +macro. If you’d like her to identify the document(s) another +way, simply invoke <kbd>.ENDNOTE_TITLE</kbd> prior to +<a href="docprocessing.html#start">START</a> +with the identifying title you want, surrounded by double-quotes. +</p> + +<p> +If you don’t want any identifying title, invoke +<kbd>.ENDNOTE_TITLE</kbd> with a blank argument, either two +double-quotes side by side (<kbd>""</kbd>) or no argument +at all. This is particularly useful if you have a single (i.e. +non-collated) document and find having the document’s title +included in the endnotes redundant. +</p> + +<!-- -ENDNOTE_TITLE_CONTROL- --> + +<h5 id="endnote-title-control" class="docs" style="margin-top: .75em; margin-bottom: .5em; margin-left: .5em;">• Document-identification string control macros and defaults</h5> + +<div class="defaults-container" style="padding-bottom: 8px;"> +<p class="defaults" style="padding-top: 6px;"> +See +<a href="#control-macro-args">Arguments to the control macros</a>. +<br/> +The following ENDNOTE_TITLE_STYLE control macros may also be +<a href="#grouping">grouped</a> +using ENDNOTE_TITLE_STYLE_STYLE. +</p> +<span class="pre defaults"> +.ENDNOTE_TITLE_FAMILY default = prevailing document family; default is Times Roman +.ENDNOTE_TITLE_FONT default = bold +.ENDNOTE_TITLE_SIZE* default = 0 +.ENDNOTE_TITLE_COLOR default = black +.ENDNOTE_TITLE_QUAD default = left +.ENDNOTE_TITLE_CAPS +.ENDNOTE_TITLE_SMALLCAPS +.ENDNOTE_TITLE_UNDERSCORE default = single underscore + +*Relative to the size of the endnotes text (set with ENDNOTE_PT_SIZE) +</span> +</div> + +<!-- -ENDNOTE_NUMBERING- --> + +<h4 id="endnotes-numbering" class="docs" style="margin-top: -.25em;">6. Endnotes referencing style</h4> + +<h5 id="endnote-marker-style" class="docs" style="margin-top: 1em; margin-bottom: .5em; margin-left: .5em;">• Endnote marker style</h5> + +<div class="box-macro-args"> +Macro: <b>ENDNOTE_MARKER_STYLE</b> <kbd class="macro-args"><a href="#line">LINE</a> | <a href="#number">NUMBER</a> | <a href="#superscript">SUPERSCRIPT</a></kbd> +</div> + +<p id="line"> +<span style="display: block; margin-bottom: .25em;">• <i>Argument:</i> <kbd>LINE</kbd></span> +By default, mom places superscript numbers in +<a href="definitions.html#running">running text</a> +to identify endnotes. However, if you have +<a href="#number-lines">linenumbering</a> +turned on, you may instruct mom not to put superscript numbers in +the running text, but rather to reference endnotes by line number. +The command to do this is +<br/> +<span class="pre-in-pp"> + .ENDNOTE_MARKER_STYLE LINE +</span> +With ENDNOTE_MARKER_STYLE <kbd>LINE</kbd>, mom will identify +endnotes either by single line numbers or by line ranges. If +what you want is a single line number, you need only invoke +<kbd>.ENDNOTE</kbd> at the appropriate place in running +text <i>without the terminating</i> <kbd>\c</kbd>. Input lines +after the endnote has been terminated (e.g. with <kbd>.ENDNOTE +OFF</kbd>) must begin at the left margin. +</p> + +<p> +(Should you wish to revert to mom’s default behaviour of +placing a superscript number in the text to identify an endnote, +you can invoke <kbd>.ENDNOTE_MARKER_STYLE</kbd> with the argument, +<kbd>NUMBER</kbd>. It is not advisable to switch marker styles +within a single document, for aesthetic reasons, but there is +nothing to prevent you from doing so.) +</p> + +<p id="en-mark"> +If you want a range of line numbers (e.g. [5-11] ), +insert, directly into the first line of the range you want, the +<a href="definitions.html#inlines">inline escape</a>, +<kbd><span class="nobr">\*[EN-MARK]</span></kbd>. For the terminating line +number of the range, you need only invoke <kbd>.ENDNOTE</kbd> +(again, without the terminating <kbd>\c</kbd>). Mom is smart enough +to figure out that where <kbd>.ENDNOTE</kbd> is invoked represents +the terminating line number. +</p> + +<div id="endnote-linenumbers-note" class="box-tip"> +<p class="tip-top"> +<span class="note">Note:</span> +By default, mom reserves a fixed amount of space, equal to 8 +placeholders, for the linenumbers of linenumbered endnotes. Within +that space, the numbers are flush right with each other. The +reserved space is enough to print a range of linenumbers of the form +<kbd>[nnnn-nnnn]</kbd>, but may be more than you need. +</p> + +<p> +The goal with linenumbered endnotes is to ensure that the longest +linenumber or range of lines is flush with the left margin of the +page. Adjusting the reserved space is done with the macro +<a href="docelement.html#endnote-numbers-align">ENDNOTE_NUMBERS_ALIGN</a>, +and the rules for getting it right are simple. +</p> + +<p class="tip-bottom"> +If your document runs to less than 100 lines, invoke +<br/> +<span class="pre-in-pp"> + .ENDNOTE_NUMBERS_ALIGN RIGHT 0 +</span> +If your document has between 100 and 999 lines +<br/> +<span class="pre-in-pp"> + .ENDNOTE_NUMBERS_ALIGN RIGHT 1 +</span> +If your document has between 1000 and 9999 lines +<br/> +<span class="pre-in-pp"> + .ENDNOTE_NUMBERS_ALIGN RIGHT 2 +</span> +etc. +</p> +</div> + +<p id="number" style="margin-top: -.5em;"> +<span style="display: block; margin-bottom: .25em;">• <i>Argument:</i> <kbd>NUMBER</kbd></span> +With the argument <kbd>NUMBER</kbd>, mom places superscript numbers +in running text, but identifies endnotes in the endnotes section +of your document with normal-sized, base-aligned numbers. +</p> + +<p id="superscript" style="margin-top: -.5em;"> +<span style="display: block; margin-bottom: .25em;">• <i>Argument:</i> <kbd>SUPERSCRIPT</kbd></span> +With the argument <kbd>SUPERSCRIPT</kbd>, mom places superscript +numbers in running text, and identifies endnotes in the endnotes +section of your document with superscript numbers as well. This is +mom’s default. +</p> + +<div id="endnote-superscript-note" class="box-tip"> +<p class="tip-top"> +<span class="note">Note:</span> +By default, mom reserves a fixed amount of space, equal to 2 +placeholders, for the superscript numbers identifying endnotes in +the endnotes section of your document. Within that space, the +numbers are flush right with each other. +</p> + +<p class="tip-bottom"> +If you need less space (the total number of endnotes is less than 10) or +more (the total number of endnotes is greater than 99), use the +macro +<a href="docelement.html#endnote-numbers-align">ENDNOTE_NUMBERS_ALIGN</a>, +to set the desired amount of reserved space, e.g. +<br/> +<span class="pre-in-pp"> + .ENDNOTE_NUMBERS_ALIGN RIGHT 1 +</span> +or +<br/> +<span class="pre-in-pp"> + .ENDNOTE_NUMBERS_ALIGN RIGHT 3 +</span> +</p> +</div> + +<h5 id="endnote-linenumber-gap" class="docs" style="margin-bottom: .5em; margin-left: .5em;">• Spacing between line-numbered endnotes and the endnote text</h5> + +<div class="box-macro-args"> +Macro: <b>ENDNOTE_LINENUMBER_GAP</b> <kbd class="macro-args"><size of gap></kbd> +</div> + +<p class="requires"> +• Requires a <a href="definitions.html#unitofmeasure">unit of measure</a> +</p> + +<p> +When your +<a href="#endnote-marker-style">ENDNOTE_MARKER_STYLE</a> +is <kbd>LINE</kbd>, mom, by default, inserts a space equal to +1/2-<a href="definitions.html#em">en</a> +between the linenumber and the text of an endnote. For aesthetic +reasons, you may want to change the size of the gap, which is done +with the macro ENDNOTE_LINENUMBER_GAP. +</p> + +<p> +ENDNOTE_LINENUMBER_GAP takes as its single argument the size +of the gap. The argument requires a +<a href="definitions.html#unitofmeasure">unit of measure</a>, +so, for example, to change the gap to 2 +<a href="definitions.html#picaspoints">picas</a>, +you’d do +<br/> +<span class="pre-in-pp"> + .ENDNOTE_LINENUMBER_GAP 2P +</span> +</p> + +<h5 id="endnote-linenumber-brackets" class="docs" style="margin-top: -.5em; margin-bottom: .5em; margin-left: .5em;">• Brackets around endnote line numbers</h5> + +<div class="box-macro-args"> +Macro: <b>ENDNOTE_LINENUMBER_BRACKETS</b> <kbd class="macro-args">PARENS | SQUARE | BRACES | ( | [ | {</kbd> +</div> + +<p> +By default, mom puts endnote line numbers inside square brackets. +The style of the brackets may be changed with the macro +ENDNOTE_LINENUMBER_BRACKETS, which takes one of three possible +arguments: <kbd>PARENS</kbd> (“round” brackets), +<kbd>SQUARE</kbd> (the default) or <kbd>BRACES</kbd> (curly braces). +If you prefer a shortform, the arguments, <kbd>(</kbd>, <kbd>[</kbd> +or <kbd>{</kbd> may be used instead. +</p> + +<h5 id="endnote-linenumber-separator" class="docs" style="margin-top: -.5em; margin-bottom: .5em; margin-left: .5em;">• Separator after endnote line numbers instead of brackets</h5> + +<div class="box-macro-args"> +Macro: <b>ENDNOTE_LINENUMBER_SEPARATOR</b> <kbd class="macro-args"><character></kbd> +</div> + +<p> +If you don’t want the numbers enclosed in brackets, you may tell +mom to use a separator instead. A common +separator would be the colon, but it can be anything you like. +</p> + +<p> +ENDNOTE_LINENUMBER_SEPARATOR takes as its single argument the +separator you want. (If the argument contains spaces, don’t +forget to enclose the argument in double-quotes.) The separator +can be composed of any valid groff character, or any combination of +characters. For example, to get a colon separator after the line +number in line-numbered endnotes, you’d do +<br/> +<span class="pre-in-pp"> + .ENDNOTE_LINENUMBER_SEPARATOR : +</span> +</p> + +<h5 id="endnote-number-control" class="docs" style="margin-top: -1em; margin-bottom: .5em; margin-left: .5em;">• Endnote numbering style control</h5> + +<div class="defaults-container" style="padding-bottom: 8px;"> +<p class="defaults" style="padding-top: 6px;"> +See +<a href="#control-macro-args">Arguments to the control macros</a>. +</p> + +<p class="defaults"> +Please note that the control macros for endnote numbering affect only +the numbers that appear on the endnotes pages themselves, not the +endnote numbers that appear in the body of a document. +</p> +<span class="pre defaults"> +Numbered endnotes +.ENDNOTE_NUMBER_FAMILY default = prevailing document family; default Times Roman +.ENDNOTE_NUMBER_FONT default = bold +.ENDNOTE_NUMBER_SIZE* default = 0 +Linenumbered endnotes +.ENDNOTE_LINENUMBER_FAMILY default = prevailing document family; default Times Roman +.ENDNOTE_LINENUMBER_FONT default = bold +.ENDNOTE_LINENUMBER_SIZE* default = 0 + +*Relative to the size of the endnotes text (set with ENDNOTE_PT_SIZE) +</span> +</div> + +<h5 id="endnote-number-alignment" class="docs" style="margin-top: -1.25em; margin-bottom: -.5em; margin-left: .5em;">• Endnote numbering alignment</h5> + +<p style="margin-top: .75em;"> +By default, when your +<a href="#endnote-marker-style">ENDNOTE_MARKER_STYLE</a> +is <kbd>NUMBER</kbd>, mom hangs the numbers on endnotes pages, +aligned right to two placeholders, producing this: +<br/> +<span id="endnote-numbering-alignment-example" class="pre-in-pp"> + 9. Lorem ipsum dolor sit amet, consetetur sadipscing elitr, + sed diam nonumy eirmod tempor invidunt ut labore et + dolore magna aliquyam erat, sed diam voluptua. + + 10. Lorem ipsum dolor sit amet, consetetur sadipscing elitr, + sed diam nonumy eirmod tempor invidunt ut labore et + dolore magna aliquyam erat, sed diam voluptua. +</span> +If you wish to change either the alignment or the number of +placeholders, the macro to use is ENDNOTE_NUMBERS_ALIGN. +</p> + +<!-- -ENDNOTE_NUMBERS_ALIGN- --> + +<div id="endnote-numbers-align" class="box-macro-args"> +Macro: <b>ENDNOTE_NUMBERS_ALIGN</b> <kbd class="macro-args">LEFT | RIGHT <number of placeholders></kbd> +</div> + +<p> +ENDNOTE_NUMBERS_ALIGN determines how endnote numbers are aligned. If you invoke +<br/> +<span class="pre-in-pp"> + .ENDNOTE_NUMBERS_ALIGN RIGHT 2 +</span> +the periods (dots) after the numbers will align, like this +<span class="pre-in-pp"> + 9. Lorem ipsum dolor sit amet, consetetur sadipscing elitr, + sed diam nonumy eirmod tempor invidunt ut labore et + dolore magna aliquyam erat, sed diam voluptua. + + 10. Lorem ipsum dolor sit amet, consetetur sadipscing elitr, + sed diam nonumy eirmod tempor invidunt ut labore et + dolore magna aliquyam erat, sed diam voluptua. +</span> +If you invoke +<span class="pre-in-pp"> + .ENDNOTE_NUMBERS_ALIGN LEFT 2 +</span> +the first digits of the numbers will line up flush left, like this +<span class="pre-in-pp"> + 9. Lorem ipsum dolor sit amet, consetetur sadipscing elitr, + sed diam nonumy eirmod tempor invidunt ut labore et + dolore magna aliquyam erat, sed diam voluptua. + + 10. Lorem ipsum dolor sit amet, consetetur sadipscing elitr, + sed diam nonumy eirmod tempor invidunt ut labore et + dolore magna aliquyam erat, sed diam voluptua. +</span> +The argument <kbd><number of placeholders></kbd> represents +the maximum size of the numbers, expressed as the number of +digits in the largest number. Numbers in the range 0-9 require +1 placeholder; in the range 10-99, 2 placeholders; in the range +100-999 3 placeholders, and so on. +</p> + +<p> +Therefore, if you have fewer than ten endnotes, +<br/> +<span class="pre-in-pp"> + .ENDNOTE_NUMBERS_ALIGN RIGHT 1 +</span> +would ensure proper right alignment of endnote numbers. +</p> + +<p> +Mom’s default for endnote number alignment is to align the +numbers right to two placeholders. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +ENDNOTE_NUMBERS_ALIGN can also be used to establish the alignment +and number of placeholders when your +<a href="#endnote-marker-style">ENDNOTE_MARKER_STYLE</a> +is <kbd>SUPERSCRIPT</kbd>. Furthermore, it can be used to establish +the number of placeholders to reserve when your ENDNOTE_MARKER_STYLE +is <kbd>LINE</kbd>, even though, in such an instance, the numbers +themselves are always aligned right. See +<a href="#endnote-linenumbers-note">here</a> +for examples. +</p> +</div> + +<div class="rule-short"><hr/></div> + +<!-- ==================================================================== --> + +<h2 id="margin-notes-intro" class="macro-group">Margin notes</h2> + +<ul style="margin-left: -.5em;"> + <li><a href="#margin-notes-behaviour">Margin notes behaviour</a> + <ul style="margin-left: -.5em;"> + <li><a href="#margin-notes-vertical">Adjusting the vertical position of margin notes</a></li> + </ul></li> + <li><a href="#mn-init">Macro: <b>MN_INIT</b></a> – set margin notes parameters</li> + <li><a href="#mn">Tag: MN</a></li> +</ul> + +<p> +Margin notes are short annotations that appear in either the left +or right margin of a document. Sometimes they comment on the text. +Sometimes they assist in following the “flow” of a +document by summarizing the subject of a portion of text. Sometimes +they’re comments to yourself in a draft copy. +</p> + +<p> +The margin notes macros and routines in om.tmac (mom) are +“mommified” versions of the margin notes macros and +routines written by Werner Lemberg and patched by Gaius Mulley. +</p> + +<h3 id="margin-notes-behaviour" class="docs">Margin notes behaviour</h3> + +<p> +First things first: before you enter your first margin note, you +must “initialize” margin notes with +<a href="#mn-init">MN_INIT</a>. +MN_INIT sets up the style parameters for margin notes, including +things like +<a href="definitions.html#font">font</a>, +<a href="definitions.html#family">family</a> +and +<a href="definitions.html#leading">leading</a>. +MN_INIT may be called before or after +<a href="docprocessing.html#start">START</a>. +</p> + +<p> +After initializing margin notes, you create margin notes with the +<a href="#mn">MN</a> +macro. Based on the argument you pass MN, your margin note will go +in either the left or the right margin. +</p> + +<p> +Margin notes are tricky from a typographic standpoint with respect +to vertical placement. Since the leading of margin notes may differ +from that of +<a href="definitions.html#running">running text</a>, +it’s impossible for mom to guess whether to align +the first lines of margin notes with a document +<a href="definitions.html#baseline">baseline</a>, +whether to align the last lines of margin notes with a document +baseline, or whether to centre them, vertically, so that neither +first nor last line aligns with anything! +</p> + +<p> +Given this difficulty, mom always aligns the first line of any +margin note with a document baseline. If you want a different +behaviour, you must adjust the position(s) of margin notes yourself, +on a note by note basis. (See +<a href="#margin-notes-vertical">Adjusting the vertical position of margin notes</a>.) +</p> + +<p> +Generally speaking, mom tries to place margin notes at the point +where you invoke +<a href="#mn">MN</a>. +However, in the event that a margin note runs deep, she may not be +able to place a subsequent margin note exactly where you want. In +such an instance, mom will “shift” the margin note down +on the page, placing it one (margin note) linespace beneath the +previous margin note (plus whatever vertical space is required to +get the first line to line up with a baseline of running text). A +warning will be issued, letting you know this has happened, and +where. +</p> + +<p> +Sometimes, if a margin note has to be shifted down, there simply +isn’t enough room to start the margin note on the page on +which <kbd>.MN</kbd> is invoked. In that case, mom ignores the +margin note entirely and issues a warning, letting you know what +she’s done, and where. </p> + +<p> +In the event that a margin note, successfully begun on a page, runs +past your bottom margin (or the last line before footnotes begin), +the margin note will “flow” onto the next page. If +it is a “left” margin note, it will continue in the +left margin. If it is a “right” margin note, it will +continue in the right margin. +</p> + +<p> +If your document is being set in two columns, mom will sensibly and +automatically set all margin notes pertaining to the left column in +the left margin, and all margin notes pertaining to the right column +in the right margin, regardless of the “direction” +argument you give the MN tag. If you try to use MN in documents of +more than two columns, mom will ignore all margin notes, and issue +a warning for each. +</p> + +<h3 id="margin-notes-vertical" class="docs">Adjusting the vertical position of margin notes</h3> + +<p> +When the +<a href="definitions.html#term-leading">leading</a> +of margin notes differs from the leading used throughout a document, +you may want to adjust the vertical position of individual margin +notes. This is most often going to be the case with margin notes +that end near the bottom of the page, where you want the last line +of the margin note to line up with the last line of text on the +page. +</p> + +<p> +Adjustments to the vertical position of margin notes must be done +inside the margin note (i.e. after <kbd>.MN</kbd>), at the top, +before entering text. The commands to use are +<kbd>\!<a href="typesetting.html#ald">.ALD</a></kbd> +(to lower the margin note) and +<kbd>\!<a href="typesetting.html#rld">.RLD</a></kbd> +(to raise it). + +The <kbd>\!</kbd> must precede the macros, or they +won’t have any effect. +</p> + +<!-- -MN_INIT- --> + +<div class="macro-id-overline"> +<h3 id="mn-init" class="macro-id">MN_INIT</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>MN_INIT</b> <kbd class="macro-args"><arguments> (see list)</kbd> +</div> + +<h4 style="margin-top: .75em; margin-left: .5em; font-style: normal; font-weight: bold: font-size: 105%; color: #6f614a;">Argument list:</h4> + +<span class="pre" style="margin-top: -1.5em; margin-left: .5em;"> +RAGGED | SYMMETRIC +<L_WIDTH> <value> +<R_WIDTH> <value> +<GUTTER> <value> +<FONTSTYLE> <value> +<SIZE> <value> +<LEAD> <value> +<COLOR> <value> +<HY> <value> +</span> + +<p style="margin-top: 1.25em;"> +Before you enter your first margin note, you must initialize +the style parameters associated with margin notes using MN_INIT. +If you forget to do so, mom will issue a warning and abort. +</p> + +<p> +The arguments may be entered in any order, and since the list is +long, use of the backslash character ( <kbd>\</kbd> ) to put each on +a separate line is recommended, e.g. +<br/> +<span class="pre-in-pp"> + .MN_INIT \ + SYMMETRIC \ + L_WIDTH 4P \ + SIZE 8 \ + LEAD 9 \ + HY 14 +</span> +All arguments are optional, but since mom requires you to run +MN_INIT before entering margin notes, you should, at a minimum, set +the <kbd>RAGGED</kbd> or <kbd>SYMMETRIC</kbd> parameter. +You will almost certainly want to set <kbd>L_WIDTH</kbd>, <kbd>R_WIDTH</kbd>, +<kbd>SIZE</kbd> and <kbd>LEAD</kbd> as well. +</p> + +<h4 class="docs arg-list"><kbd>RAGGED | SYMMETRIC</kbd></h4> + +<p> +If the argument <kbd>RAGGED</kbd> is given, both left and +right margin notes will be flush left. If the argument +<kbd>SYMMETRIC</kbd> is given, left margin notes will be set flush +<i>right</i>, and right margin notes flush <i>left</i>. The effect +is something like this: +<br/> +<span class="pre-in-pp"> + A left This is a meaningless batch A right + margin note of text whose sole purpose is margin note + with just to demonstrate how the sym- with just + a few words metric argument to MN sets left a few words + in it. and right margin notes. in it. +</span> +</p> + +<p> +If the argument is omitted, both left and right margin notes will +be set justified. (Justified is usually not a good idea, since the +narrow measure of margin notes makes pleasing justification a near +impossibility.) +</p> + +<h4 class="docs arg-list"><kbd>L_WIDTH <value></kbd></h4> + +<p> +The width of left margin notes. A +<a href="definitions.html#unitofmeasure">unit of measure</a> +must be appended directly onto the argument. The default is to set +left margin notes right out to the edge of the page, which is almost +certainly not what you want, so you should give a value for this +argument if using left margin notes. +</p> + +<h4 class="docs arg-list"><kbd>R_WIDTH <value></kbd></h4> + +<p> +The width of right margin notes. A +<a href="definitions.html#unitofmeasure">unit of measure</a> +must be appended directly onto the argument. The default is to +set right margin notes right out to the edge of the page, which is +almost certainly not what you want, so you should give a value for +this argument if using right margin notes. +</p> + +<h4 class="docs arg-list"><kbd>GUTTER <value></kbd></h4> + +<p> +The +<a href="definitions.html#gutter">gutter</a> +between margin notes and +<a href="definitions.html#running">running text</a>. +A +<a href="definitions.html#unitofmeasure">unit of measure</a> +must be appended directly onto the argument. The gutter applies to +both left and right margin notes. The default is 1 +<a href="definitions.html#em">em</a>. +</p> + +<h4 class="docs arg-list"><kbd>FONTSTYLE <value></kbd></h4> + +<p> +The family+font for margin notes. Yes, that’s right: the +family <i>plus</i> font combo. For example, if you want Times +Roman Medium, the argument must be <kbd>TR</kbd>. If you want Palatino +Medium Italic, the argument must be <kbd>PI</kbd>. The default is the same +family+font combo used for a document’s paragraph text. +</p> + +<h4 class="docs arg-list"><kbd>SIZE <value></kbd></h4> + +<p> +The point size of type for margin notes. There is no need to append a +<a href="definitions.html#unitofmeasure">unit of measure</a> +to the argument; +<a href="definitions.html#picaspoints">points</a> +is assumed (although there’s nothing preventing you from +appending an alternative unit of measure directly to the argument). +The default is for margin notes to use the same point size of type +as is used in document paragraphs. +</p> + +<h4 class="docs arg-list"><kbd>LEAD <value></kbd></h4> + +<p> +The +<a href="definitions.html#leading">leading</a> +of margin notes. <kbd><LEAD></kbd> takes +<a href="definitions.html#picaspoints">points</a> +as its unit of measure, so don’t tack a unit of measure onto +the end of the argument. The default lead is the same as paragraph +text (i.e. the document’s base leading). +</p> + +<h4 class="docs arg-list"><kbd>COLOR <value></kbd></h4> + +<p> +The colour of margin notes. The colour must be pre-initialized +with +<a href="color.html#newcolor">NEWCOLOR</a> +or +<a href="color.html#xcolor">XCOLOR</a>. +The default is black. +</p> + +<h4 class="docs arg-list"><kbd>HY <value></kbd></h4> + +<p> +<kbd><value></kbd> is a digit telling groff how you want margin +notes hyphenated. +<br/> +<span class="pre-in-pp"> + 0 = do not hyphenate + 1 = hyphenate without restrictions + 2 = do not hyphenate the last word on the page + 4 = do not hyphenate the last two characters of a word + 8 = do not hyphenate the first two characters of a word +</span> +The values can be added together, so, for example, if you want +neither the first two nor the last two characters of words +hyphenated, the hyphenation-flag would be 12. The default value is +14 (i.e. 2+4+8). +</p> + +<!-- -MN- --> + +<div class="macro-id-overline"> +<h3 id="mn" class="macro-id">MN</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>MN</b> <kbd class="macro-args">LEFT | RIGHT</kbd> +</div> + +<p> +Once you’ve initialized margin notes with +<kbd><a href="#mn-init">.MN_INIT</a></kbd>, +you can enter margin notes any time you like with <kbd>.MN</kbd>. +An argument of <kbd>LEFT</kbd> will set a left margin note. An +argument of <kbd>RIGHT</kbd> will set a right margin note. +</p> + +<p> +Any argument, such as <kbd>OFF</kbd> (or <kbd>OFF</kbd>, +<kbd>QUIT</kbd>, <kbd>END</kbd>, <kbd>X</kbd>, etc) exits the +current margin note. +</p> + +<div class="rule-short"><hr/></div> + +<!-- ==================================================================== --> + +<!-- -FINIS- --> + +<h2 id="finis-intro" class="macro-group">Document termination string</h2> + +<ul style="margin-left: -.5em;"> + <li><a href="#finis">Tag: FINIS</a></li> + <li><a href="#finis-control">FINIS control macros</a> + <ul style="margin-left: -1.25em;"> + <li><a href="#finis-string">Changing the FINIS string</a></li> + <li><a href="#finis-string-caps">Automatic capitalization of the FINIS string</a></li> + <li><a href="#finis-color">Changing the FINIS colour</a></li> + <li><a href="#finis-no-dashes">Removing the dashes around FINIS</a></li> + </ul></li> +</ul> + +<p> +The use of FINIS is optional. If you invoke it at the end of a +document (before +<kbd><a href="#endnotes">.ENDNOTES</a></kbd>, +<kbd><a href="refer.html#bibliography">.BIBLIOGRAPHY</a></kbd> +or +<kbd><a href="tables-of-contents.html#toc">.TOC</a></kbd>) +mom deposits the word, <b>END</b>, centred after a blank line, +beneath the last line of the document. <b>END</b> is enclosed +between +<a href="definitions.html#em">em-dashes</a>, +like this: +<br/> +<span class="pre-in-pp"> + ...and they all lived happily ever after. + + — END — +</span> +If there is insufficient room for FINIS on the last page of a +document, mom will alert you on stderr. +</p> + +<p> +If you’re writing in a language other than English, you can +change what mom prints for END with the control macro +<a href="#finis-string">FINIS_STRING</a>. +</p> + +<div class="macro-id-overline"> +<h3 id="finis" class="macro-id">FINIS</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>FINIS</b> +</div> + +<p> +The use of FINIS is optional, but if you use it, it should be the +last macro you invoke in a document before +<kbd><a href="#endnotes">.ENDNOTES</a></kbd>, +<kbd><a href="refer.html#bibliography">.BIBLIOGRAPHY</a></kbd> +or +<kbd><a href="tables-of-contents.html#toc">.TOC</a></kbd>. +See +<a href="#finis-intro">above</a> +for a description of how FINIS behaves. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +If you don’t use FINIS, and you don’t want +<a href="definitions.html#footer">footers</a> +(if they’re on) or a page number at the bottom of the last +page of a document, you have to turn them off manually, as the last +two lines of your document file, like this: +<br/> +<span class="pre-in-pp"> + .FOOTERS OFF + .PAGINATE OFF +</span> +</p> +</div> + +<!-- -FINIS STRING- --> + +<h3 id="finis-control" class="docs" style="margin-bottom: -1em">Finis control macros</h3> + +<p> +Since FINIS is only used once in a document, it has few control +macros. It is expected that you will make changes to style +parameters such as family, font, and size with +<a href="definitions.html#inlines">inline escapes</a> +in the FINIS string itself (see below). +</p> + +<h4 id="finis-string" class="docs" style="margin-top: -.5em">Changing the FINIS string</h4> + +<p> +By default, FINIS prints the word, END, between +<a href="definitions.html#em">em-dashes</a>. +If you’d like mom to print something else between the dashes, +use the FINIS_STRING macro (anywhere in the document prior to +FINIS). +</p> + +<p> +For example, if your document’s in French, you’d do +<br/> +<span class="pre-in-pp"> + .FINIS_STRING "FIN" +</span> +Double-quotes must enclose the macro’s argument. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +If you pass FINIS_STRING a blank string, +<br/> +<span class="pre-in-pp"> + .FINIS_STRING "" +</span> +mom will still print the em-dashes when you invoke +<kbd>.FINIS</kbd>. This, in effect, produces a short, centred +horizontal rule that terminates the document. (In +<a href="docprocessing.html#printstyle">PRINTSTYLE <kbd>TYPEWRITE</kbd></a>, +it’s a short, dashed line composed of four hyphens.) +</p> +</div> + +<!-- -FINIS STRING CAPS- --> + +<h4 id="finis-string-caps" class="docs">Automatic capitalization of the FINIS string</h4> + +<p> +By default, mom sets the string you pass to FINIS all-caps. +If you’d prefer that she not do so, but rather respect +the FINIS string exactly as you enter it, invoke the macro +<kbd>.FINIS_STRING_CAPS</kbd> with the <kbd>OFF</kbd> argument, like +this: +<br/> +<span class="pre-in-pp"> + .FINIS_STRING_CAPS OFF +</span> +<kbd>OFF</kbd>, above, could be anything, e.g. <kbd>NO</kbd> or +<kbd>X</kbd>. +</p> + +<!-- -FINIS COLOR- --> + +<h4 id="finis-color" class="docs">Changing the FINIS colour</h4> + +<p> +Invoking the control macro <kbd>.FINIS_COLOR</kbd> with a +pre-defined (or “initialized”) colour changes the colour +of both the FINIS string and the em-dashes that surround it. If you +use the +<a href="definitions.html#inline">inline escape</a>, +<a href="color.html#color-inline"><kbd><span class="nobr">\*[<colourname>]</span></kbd></a>, +in the argument passed to FINIS, only the text will be in the +new colour; the em-dashes will be in the default document colour +(usually black). +</p> + +<!-- -FINIS DASHES- --> + +<h4 id="finis-no-dashes" class="docs">Removing the dashes around FINIS</h4> + +<p> +If you don’t want the dashes around the FINIS string, you can +remove them with +<br/> +<span class="pre-in-pp"> + .FINIS_NO_DASHES +</span> +</p> + +<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: 33%; text-align: center;"><a href="#top">Top</a></td> + <td style="width: 33%; text-align: right;"><a href="images.html#top">Next: Graphics, floats, and preprocessor support</a></td> +</tr> +</table> + +</div> + +<div class="bottom-spacer"><br/></div> + +</body> +</html> |