diff options
Diffstat (limited to 'contrib/mom/momdoc/docelement.html')
| -rw-r--r-- | contrib/mom/momdoc/docelement.html | 6162 |
1 files changed, 6162 insertions, 0 deletions
diff --git a/contrib/mom/momdoc/docelement.html b/contrib/mom/momdoc/docelement.html new file mode 100644 index 00000000..7d99277c --- /dev/null +++ b/contrib/mom/momdoc/docelement.html @@ -0,0 +1,6162 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- +This file is part of groff, the GNU roff type-setting system. + +Copyright (C) 2004, 2005, 2006, 2009, 2010 Free Software Foundation, Inc. +Written by Peter Schaffter. + +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 the +Invariant Sections being this comment section, 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: Inserting images</a></td> +</tr> +</table> + +<h1 class="docs">The document element tags</h1> + +<div style="width: 386px; 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> + </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="#head-intro">Main heads</a></h3> +<ul class="toc-docproc" style="margin-top: .5em;"> + <li><a href="#head">HEAD</a></li> + <li><a href="#head-control">Head control</a></li> +</ul> +<h3 class="toc toc-docproc-header"><a class="header-link" href="#subhead-intro">Subheads</a></h3> +<ul class="toc-docproc" style="margin-top: .5em;"> + <li><a href="#subhead">SUBHEAD</a></li> + <li><a href="#subhead-control">Subhead control</a></li> +</ul> +<h3 class="toc toc-docproc-header"><a class="header-link" href="#parahead-intro">Paragraph heads</a></h3> +<ul class="toc-docproc" style="margin-top: .5em;"> + <li><a href="#parahead">PARAHEAD</a></li> + <li><a href="#parahead-control">Parahead control</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> +</div> +<div class="mini-toc-col-2" style="margin-top: 1.5em;"> +<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> +<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</a></li> + <li><a href="#mn">MN</a></li> + <li><a href="#margin-notes-control">Margin notes control</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 subhead; this is a +footnote,” and so on. +</p> + +<p> +The list of tags is actually quite small—ideal for the users +mom brought herself into being for (see +<a href="intro.html#intro-intro">Who mom is meant for</a>). +However, the list of macros that control the appearance of the tags +upon output is extensive. 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. +</p> + +<p> +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>, +which sets everyTHING in Courier roman, 12/24 (i.e. 12-point type on +a linespace of 24 points). +</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 change +subheads to 1-1/2 points larger than the type in paragraphs, do +<br/> +<span class="pre-in-pp"> + .SUBHEAD_SIZE +1.5 +</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 heads to be red, once you’ve defined +or initialized the color, red, +<br/> +<span class="pre-in-pp"> + .HEAD_COLOR red +</span> +will turn your heads 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 margin 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="underline" class="docs" style="margin-bottom: -.75em;">Underline style, rule weight</h4> + +<p> +If mom gives the option to underline 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 _UNDERLINE. +</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 _UNDERLINE 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> + +<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 accomodate +<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 <i>must</i> 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 +<a href="#head-intro">heads</a>. +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="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>. +</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_QUAD default = same as paragraphs +.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;"> +Prior to version 1.4-b, mom allowed only the passing of an integer +to the macro, EPIGRAPH_INDENT. The integer represented the amount +by which to multiply the argument passed to +<a href="#para-indent">PARA_INDENT</a> +to arrive at an indent for block style epigraphs. +</p> + +<p> +As of version 1.4-b, you can now append a +<a href="definitions.html#unitofmeasure">unit of measure</a> +to the argument passed to EPIGRAPH_INDENT, thus setting an absolute +indent, relative to nothing. The old behaviour is still respected, +though; in other words, 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. +</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 <i>must</i> 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 +<a href="#head-intro">heads</a> +or +<a href="#subhead-intro">subheads</a>. +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> +In contrast to some other macro sets, mom does not deposit a blank +line between paragraphs. If you want her to do so, use the control +macro PARA_SPACE. (I don’t recommend using this macro with +<a href="typesetting.html#printstyle">PRINTSTYLE TYPEWRITE</a>.) +</p> + +<p> +Note that mom does not provide “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> + +<div class="box-tip"> +<p class="tip-top"> +<span class="tip">Tip:</span> +The last thing you want while you’re writing and editing +drafts of a document (particularly stories and chapters) is a +text file cluttered up with <kbd>.PP</kbd>’s. The visual +interruption in the flow of text is a serious obstacle to creativity +and critiquing. +</p> + +<p> +I use the tab key on my keyboard to indent paragraphs by four spaces +when I'm writing, producing a text file that looks pretty much like +what you see on a printed page. When it comes time to format and +print the file, I run it through a sed script that (amongst other +things) converts the intial four spaces into <kbd>.PP</kbd> (plus a +new line) and pipes the output to groff for processing and printing. +</p> + +<p class="tip-bottom"> +Another solution would be to insert a blank line between paragraphs +of your text files. The blank lines can then be sedded out at +print time, as above (<kbd>.PP</kbd> plus a newline), or, more +conveniently, you could use the <kbd>.blm</kbd> +<a href="definitions.html#primitives">primitive</a> +(blank line macro) to tell groff (and mom) that blank lines should +be interpreted as PP’s. +<br/> +<span class="pre-in-pp"> + .blm PP +</span> +tells groff that blank lines are really the macro PP. +</p> +</div> + +<!-- -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> +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. +</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">Paragraph spacing control</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. +</p> + +<p> +Mom’s default paragraph (and document) family is Times Roman. +</p> + +<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> +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> + +<h4 id="pp-color" class="docs" style="margin-top: -.25em;">3. Paragraph colour</h4> + +<p> +Mom has no special control macro for colourizing paragraphs. If you +wish a colourized 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>\*[<colorname>]</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> + .HEAD "Monty Python" + .SUBHEAD "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> + +<p> +The one document element that is affected by changing the colour of +paragraphs is +<a href="#parahead">paraheads</a>, +since paraheads are attached directly to the body of paragraphs. +In other words, if you change the colour of a paragraph and do not +reset the paragraph colour back to its default, subsequent paraheads +will appear in the same colour as your paragraphs unless you have +explicitly told mom you want a pre-defined (or +“initialized”) color (usually black) for your paraheads. +</p> + +<p> +See the footnote to +<a href="#parahead-color">PARAHEAD_COLOR</a>. +</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 every +paragraph whose leading you wish to change. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Warning:</span> +It is extremely unwise to change a paragraph's leading with LS as +it will, in all cases, screw up mom’s ability to balance +the bottom margin of pages. Should you absolutely need to change +paragraph leading with LS, and subsequently want mom to get back on +the right leading track, use the +<a href="docprocessing.html#shim">SHIM</a> +macro. +</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> +and +<a href="#footnote-intro">footnotes</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 head or subhead, nor the first +paragraphs of +<a href="#epigraph-intro">epigraphs</a>, +<a href="#blockquote-intro">blockquotes</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 +<kbd>.INDENT_FIRST_PARAS</kbd> 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 (<b>OFF, QUIT, Q, X</b>...) cancels its effect, meaning +that first paragraphs will once again not be indented. +</p> + +<h4 id="pp-space" class="docs">8. Spacing paragraphs</h4> + +<p> +By default, mom does not insert a blank line between +paragraphs. If you would like her to do so, invoke the macro, +<kbd>.PARA_SPACE</kbd>, 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 +(<b>OFF, QUIT, Q, X</b>...) cancels its effect, meaning that +paragraphs will once again not be separated by a blank line. +</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>, +<a href="#epigraph-intro">epigraphs</a>, +<a href="#head-intro">heads</a>, +<a href="#subhead-intro">subheads</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="head-intro" class="macro-group">Main heads</h2> + +<ul style="margin-left: -.5em;"> + <li><a href="#head">Tag: HEAD</a></li> + <li><a href="#head-control">Head control macros and defaults</a></li> +</ul> + +<p> +Main heads—or, in this documentation, just +“heads”—should be used any place you want titles +to introduce major sections of a document. If you wish, mom can +number your heads for you. Head numbers can also be included +hierarchically in numbered +<a href="#subhead-intro">subheads</a> +and +<a href="#parahead-intro">paraheads</a>. +</p> + +<p> +By default, heads are centred on the page, underlined, all in caps. +A double linespace precedes each head. In +<a href="docprocessing.html#printstyle">PRINTSTYLE <kbd>TYPESET</kbd></a>, +heads are bold, slightly larger than paragraph text. +</p> + +<p> +If these defaults don’t suit you, you can change them with the +head control macros. +</p> + +<!-- -HEAD- --> + +<div class="macro-id-overline"> +<h3 id="head" class="macro-id">HEAD</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>HEAD</b> <kbd class="macro-args">"<text of head>" [ "<2nd line>" [ "<3rd line>" ... ] ]</kbd> +</div> + +<p> +The argument to HEAD is the text of the head, surrounded by +double-quotes. If you need additional lines for a head, simply +surround each line with double-quotes. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +If a head falls near the bottom of an output page and mom is unable +to fit the head <i>plus at least one line of text underneath it</i>, +she will set the head at the top of the next page. +</p> + +<p class="tip-bottom"> +<span class="additional-note">Additional note:</span> +If an +<a href="definitions.html#inputline">input line</a> +in a head (i.e. one of the lines surrounded by double-quotes) has +to be broken by mom in order to fit the current line-length (say, +a narrow column measure), the head underline (underscore) will not +behave. You’ll recognize the problem as soon as you preview +your document. If you encounter a head that misbehaves with respect +to underlining, the solution is to supply each line <i>as you want +it</i> as a separate argument (surrounded by double-quotes) to the +HEAD macro. +</p> + +<p> +For example, if mom breaks +<br/> +<span class="pre-in-pp"> + .HEAD "This is a very, very, very long head" +</span> +into<br/> +<span class="pre-in-pp"> + This is a very, very, very + long head +</span> +you’ll see the misbehaving underscore and should change the +argument to HEAD to +<br/> +<span class="pre-in-pp"> + .HEAD "This is a very, very very" "long head" +</span> +</p> +</div> + +<div class="defaults-container" style="background-color: #ded4bd; border: none;"> +<h3 id="head-control" class="docs defaults">HEAD control macros and defaults</h3> + +<p class="defaults"> +There are, in addition to the usual family/font/size/quad control +macros, a number of macros to manage head numbering, spacing, +underlining, and so on. Check them out if you’re unhappy with +mom’s defaults. +</p> +<ol style="margin-top: .5em; padding-bottom: .5em;"> + <li><a href="#head-general">Family/font/size/colour/quad</a></li> + <li><a href="#head-caps">Capitalizing heads</a></li> + <li><a href="#head-space">Pre-head space</a></li> + <li><a href="#head-underline">Underscoring</a></li> + <li><a href="#number-heads">Numbering</a></li> + <li><a href="#reset-head-number">Reset head numbering</a></li> + <li><a href="#head-inlines">Vertical inline escapes inside heads</a></li> +</ol> +</div> + +<h4 id="head-general" class="docs" style="margin-top: -1.5em; margin-bottom: .5em;">1. Family/font/size/colour/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>. +</p> +<span class="pre defaults"> +.HEAD_FAMILY default = prevailing document family; default is Times Roman +.HEAD_FONT default = bold +.HEAD_SIZE default = +1 (point) +.HEAD_COLOR default = black +.HEAD_QUAD default = CENTER +</span> +</div> + +<h4 id="head-caps" class="docs" style="margin-top: -1.25em;">2. Capitalizing heads</h4> + +<p> +By default, mom sets heads in caps, regardless of the +<a href="definitions.html#stringargument">string(s)</a> +you give to +<a href="#head">HEAD</a>. +To change this behaviour, do +<br/> +<span class="pre-in-pp"> + .HEAD_CAPS OFF +</span> +HEAD_CAPS is a toggle macro, therefore you can use any argument you +like instead of <kbd>OFF</kbd> (<b>END, QUIT, Q, X</b>...). To turn +HEAD_CAPS back on, simply invoke it without an argument. +</p> + +<h4 id="head-space" class="docs" style="margin-top: -.25em;">3. Pre-head space</h4> + +<p> +By default, mom deposits 2 blank lines prior to every head. If +you’d prefer just a single blank line, do +<br/> +<span class="pre-in-pp"> + .HEAD_SPACE OFF +</span> +HEAD_SPACE is a toggle macro, therefore you can use any argument +you like instead of <kbd>OFF</kbd> (<kbd>END, QUIT, Q, X</kbd>...). +To restore the space before heads to 2 blank lines, invoke +<kbd>.HEAD_SPACE</kbd> without an argument. +</p> + +<h4 id="head-underline" class="docs" style="margin-top: -.25em;">4. Underscoring</h4> + +<p> +By default, mom underlines heads. To change this behaviour, do +<br/> +<span class="pre-in-pp"> + .HEAD_UNDERLINE OFF +</span> +HEAD_UNDERLINE can be used as a toggle macro, therefore you can +use any argument you like instead of <kbd>OFF</kbd> (<kbd>END, +QUIT, Q, X</kbd>...) to turn it off, or invoke it by itself to +turn head underlining on. +</p> + +<p> +In addition to toggling head underlining on or off, as of +version 1.5 of mom, you can use HEAD_UNDERLINE to set the weight +of the underline and its distance from the head, like this: +<br/> +<span class="pre-in-pp"> + .HEAD_UNDERLINE <weight> [<gap>] +</span> +The <kbd>weight</kbd> argument is in points, or fractions thereof, +and must not have the +<a href="definitions.html#unitofmeasure">unit of measure</a>, +<kbd>p</kbd>, appended. Like +<a href="inlines.html#rule-weight">RULE_WEIGHT</a>, +weights must be greater than 0 and less than 100. Mom’s +default for head underlines is 1/2 point. +</p> + +<p> +The <kbd>gap</kbd> argument determines the distance from the +baseline of the head to the upper edge of the underline. It can +be given using any unit of measure, and must have the unit of +measure appended to the argument. Mom’s default gap for head +underlines is 2 points. +</p> + +<p> +As an example, suppose you want your heads underlined with a +4-point rule separated from the head by 3 points. The way to +accomplish it is: +<br/> +<span class="pre-in-pp"> + .HEAD_UNDERLINE 4 3p +</span> +If you wanted the same thing, but were content with mom’s +default gap of 2 points, +<br/> +<span class="pre-in-pp"> + .HEAD_UNDERLINE 4 +</span> +would do the trick. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +If you supply a weight to HEAD_UNDERLINE, and optionally a gap, you +also turn the underlining of heads on; if this is not what you want, +you must turn head underlining off manually afterwards. +</p> +</div> + +<h4 id="number-heads" class="docs" style="margin-top: -.25em;">5. Numbering</h4> + +<p> +If you’d like your heads numbered, simply invoke +<span class="pre-in-pp"> + .NUMBER_HEADS +</span> +with no argument. Mom will number all subsequent heads automatically +(in ascending order, naturally). +</p> + +<p> +If, in addition to numbering heads, you also request that +<a href="#subhead-intro">subheads</a> +and/or +<a href="#parahead-intro">paraheads</a> +be numbered, the head number will be included in their numbers (each +number separated by a period [dot]). +</p> + +<p> +Should you wish to stop head numbering, invoke +<kbd>.NUMBER_HEADS</kbd> with any argument (<kbd>OFF, QUIT, END, +X</kbd>...). Head numbering will cease, and the head number will +not be included in the numbering of subheads and/or paraheads. +</p> + +<p> +See also +<a href="#prefix-chapter-number">Prefixing chapter numbers</a> +if you’d like chapter numbers prepended to the head numbers. +</p> + +<h4 id="reset-head-number" class="docs" style="margin-top: -.25em;">6. Reset head numbering</h4> + +<p> +Should you wish to reset the head number to “1”, +invoke +<span class="pre-in-pp"> + .RESET_HEAD_NUMBER +</span> +with no argument. If, for some reason, you want mom to use a head +number that is not the next in ascending order (i.e. the last head +number + 1), invoke <kbd>.RESET_HEAD_NUMBER</kbd> with the number +you want, e.g. +<br/> +<span class="pre-in-pp"> + .RESET_HEAD_NUMBER 6 +</span> +Your next head will be numbered “6” and subsequent heads will +be numbered in ascending order from “6”. +</p> + +<h4 id="head-inlines" class="docs" style="margin-top: -.25em;">7. Vertical inline escapes inside heads</h4> + +<p> +If you need to adjust the +<a href="definitions.html#baseline">baseline</a> +position of a head (e.g. the head falls at the top of a column and +you want its +<a href="definitions.html#ascender">ascenders</a> +to line up with the ascenders of +<a href="definitions.html#running">running text</a> +in other columns), you can embed a vertical motion +<a href="definitions.html#inlines">inline escape</a> +(either +<a href="inlines.html#inline-vertical-mom">mom</a>’s +or +<a href="inlines.html#inline-vertical-groff">groff</a>’s +in the string(s) you pass to HEAD. +</p> + +<p> +For example, +<br/> +<span class="pre-in-pp" style="margin-bottom: -1em;"> + .HEAD "\*[DOWN 3p]Text of head" +</span> +or +<span class="pre-in-pp" style="margin-top: -.5em;"> + .HEAD "\v'3p'Text of head" +</span> +will lower the baseline of the head by three points. Note that +there’s no need to reverse the sense of the inline escape. +</p> + +<p> +In the case of heads that run to more than one line, you must embed +the escape in the string for each line, like this: +<br/> +<span class="pre-in-pp" style="margin-bottom: -1em;"> + .HEAD "\*[DOWN 3p]First line" "\[DOWN 3p]Next line" +</span> +or +<span class="pre-in-pp" style="margin-top: -.5em;"> + .HEAD "\v'3p'First line" "\v'3p'Next line" +</span> +</p> + +<div class="rule-short"><hr/></div> + +<!-- ==================================================================== --> + +<h2 id="subhead-intro" class="macro-group">Subheads</h2> + +<ul style="margin-left: -.5em;"> + <li><a href="#subhead">Tag: SUBHEAD</a></li> + <li><a href="#subhead-control">Subhead control macros</a></li> +</ul> + +<p> +Subheads should be used any place you want titles to introduce +sections of a document below heads. If you wish, mom can +number subheads for you. Subhead numbers can also be included +hierarchically in numbered +<a href="#parahead-intro">paraheads</a>. +</p> + +<p> +By default, subheads are flush left. In +<a href="docprocessing.html#printstyle">PRINTSTYLE <kbd>TYPESET</kbd></a>, +they are set bold, slightly larger than paragraph text. In +<a href="docprocessing.html#printstyle">PRINTSTYLE <kbd>TYPEWRITE</kbd></a>, +they are underlined. A single linespace precedes them in both +printstyles, and a tiny space adjustment raises them slightly +above text that comes afterwards for greater clarity in document +structuring. +</p> + +<p> +If these defaults don’t suit you, you can change them with the +subhead control macros. +</p> + +<!-- -SUBHEAD- --> + +<div class="macro-id-overline"> +<h3 id="subhead" class="macro-id">SUBHEAD</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>SUBHEAD</b> <kbd class="macro-args">"<text of subhead>" [ "<2nd line>" [ "<3rd line>" ... ] ]</kbd> +</div> + +<p> +The argument to SUBHEAD is the text of the subhead, surrounded by +double-quotes. If you need additional lines for a subhead, simply +surround each line with double-quotes. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +If a subhead falls near the bottom of an output page and mom is +unable to fit the head <i>plus at least one line of text underneath +it</i>, she will set the subhead at the top of the next page. +</p> +</div> + +<div class="defaults-container" style="background-color: #ded4bd; border: none;"> +<h3 id="subhead-control" class="docs defaults">SUBHEAD control macros and defaults</h3> + +<p class="defaults"> +In addition to the usual family/font/size/quad control macros, there +are macros to manage subhead numbering. +</p> + +<ol style="margin-top: .5em; padding-bottom: .5em;"> + <li><a href="#subhead-general">Family/font/size/colour/quad</a></li> + <li><a href="#number-subheads">Numbering</a></li> + <li><a href="#reset-subhead-number">Reset subhead numbering</a></li> + <li><a href="#subhead-inlines">Vertical inline escapes inside subheads</a></li> +</ol> +</div> + +<h4 id="subhead-general" class="docs" style="margin-top: -1.5em; margin-bottom: .5em;">1. Family/font/size/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>. +</p> +<span class="pre defaults" style="padding-bottom: -1em;"> +.SUBHEAD_FAMILY default = prevailing document family; default is Times Roman +.SUBHEAD_FONT default = bold +.SUBHEAD_SIZE default = +.5 (point) +.SUBHEAD_COLOR default = black +.SUBHEAD_QUAD default = LEFT +</span> +</div> + +<h4 id="number-subheads" class="docs" style="margin-top: -1.25em;">2. Number subheads</h4> + +<p> +If you’d like your subheads numbered, simply invoke +<kbd>.NUMBER_SUBHEADS</kbd> with no argument. Mom +will number all subsequent subheads automatically (in ascending +order, naturally). +</p> + +<p> +If, in addition to numbering subheads, you also request that +<a href="#head-intro">heads</a> +be numbered, the head number will be included in the subhead number +(separated by a period [dot]). +</p> + +<p> +Should you wish to stop subhead numbering, invoke +<kbd>.NUMBER_SUBHEADS</kbd> with any argument (<kbd>OFF, QUIT, END, +X</kbd>...). Subhead numbering will cease, and the subhead number +will not be included in the numbering of paraheads. +</p> + +<p> +See also +<a href="#prefix-chapter-number">Prefixing chapter numbers</a> +if you’d like chapter numbers prepended to the subhead numbers. +</p> + +<h4 id="reset-subhead-number" class="docs" style="margin-top: -.25em;">3. Reset subhead numbering</h4> + +<p> +Should you wish to reset the subhead number to “1”, +invoke +<span class="pre-in-pp"> + .RESET_SUBHEAD_NUMBER +</span> +with no argument. If, for some reason, you want mom to use a +subhead number that is not the next in ascending order (i.e. the +last subhead number + 1), invoke <kbd>.RESET_SUBHEAD_NUMBER</kbd> +with the number you want, e.g. +<br/> +<span class="pre-in-pp"> + .RESET_SUBHEAD_NUMBER 4 +</span> + +Your next subhead will be numbered “4” and subsequent +subheads will be numbered in ascending order from “4”. +</p> + +<h4 id="subhead-inlines" class="docs" style="margin-top: -.25em;">4. Vertical inline escapes inside subheads</h4> + +<p> +See +<a href="#head-inlines">Vertical inline escapes inside heads</a>. +The information there applies equally to subheads. +</p> + +<div class="rule-short"><hr/></div> + +<!-- ==================================================================== --> + +<h2 id="parahead-intro" class="macro-group">Paragraph heads</h2> + +<ul style="margin-left: -.5em;"> + <li><a href="#parahead">Tag: PARAHEAD</a></li> + <li><a href="#parahead-control">Parahead control macros</a></li> +</ul> + +<p> +Paragraph heads (paraheads) should be used any place you want titles +to introduce paragraphs below heads or subheads. If you wish, mom +can number paraheads for you. +</p> + +<p> +By default, paraheads are joined to the body of a paragraph, +slightly indented (provided the paragraph is not a +“first” paragraph as defined in +<a href="#para-indent-first">Indenting initial paragraphs</a>) +and separated from the body of the paragraph by a small amount of +horizontal space. In +<a href="docprocessing.html#printstyle">PRINTSTYLE <kbd>TYPESET</kbd></a>, +they are set bold italic, slightly larger than paragraph text. In +<a href="docprocessing.html#printstyle">PRINTSTYLE <kbd>TYPEWRITE</kbd></a>, +they are underlined. +</p> + +<p> +If these defaults don’t suit you, you can change them with the +parahead control macros. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="tip">Tip:</span> +If you really need a heading level below subhead (a sub-subhead) +that isn’t joined to the body of a paragraph, you can trick +PARAHEAD into giving you one by creating a paragraph that contains +only a parahead, like this: +<br/> +<span class="pre-in-pp"> + .PP + .PARAHEAD "My Sub-Subhead" + .PP + <text> +</span> +</p> +</div> + +<!-- -PARAHEAD- --> + +<div class="macro-id-overline"> +<h3 id="parahead" class="macro-id">PARAHEAD</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>PARAHEAD</b> <kbd class="macro-args">"<text of parahead>"</kbd> +</div> + +<p> +PARAHEAD must come after +<a href="#pp">PP</a> +or it will not work. +</p> + +<p> +The argument is the text of the parahead, surrounded by +double-quotes. Because paraheads are joined to the body of a +paragraph, they accept only one argument (see +<a href="#head">HEAD</a> +and +<a href="#subhead">SUBHEAD</a>). +</p> + +<div class="defaults-container" style="background-color: #ded4bd; border: none;"> +<h3 id="parahead-control" class="docs defaults">PARAHEAD control macros and defaults</h3> + +<p class="defaults"> +In addition to the family/font/size/colour/indent control macros, +there are macros to manage parahead numbering. +</p> + +<ol style="margin-top: .5em; padding-bottom: .5em;"> + <li><a href="#parahead-general">Family/font/size/color</a></li> + <li><a href="#parahead-indent">Indent</a></li> + <li><a href="#parahead-space">Horizontal space</a></li> + <li><a href="#number-paraheads">Numbering</a></li> + <li><a href="#reset-parahead-number">Reset parahead numbering</a></li> +</ol> +</div> + +<h4 id="parahead-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>. +</p> +<span class="pre defaults"> +.PARAHEAD_FAMILY default = prevailing document family; default is Times Roman +.PARAHEAD_FONT default = bold italic +.PARAHEAD_SIZE default = +.5 (point) +.PARAHEAD_COLOR default = black* + +*If you colourize paragraph text, paraheads will appear in the same + colour as the text unless you explicitly tell mom to colour them + otherwise by invoking .PARAHEAD_COLOR. If you do want paraheads + that are coloured the same as paragraph text, it’s generally a good + idea to invoke .PARAHEAD_COLOR anyway (with the same colour used + for paragraph text), just to let mom know. +</span> +</div> + +<h4 id="parahead-indent" class="docs" style="margin-top: -1.25em;">2. Indent</h4> + +<p> +Unlike other control macros that end in +<a href="#control-indents">_INDENT</a>, +the argument to the macro that controls indenting of paragraph +heads (PARAHEAD_INDENT) is not relative to the first-line indent of +normal paragraphs. In other words, it takes an absolute value, and +requires a +<a href="definitions.html#unitofmeasure">unit of measure</a>. +For example, to set the paragraph head indent to 2-1/2 picas, you +do: +<br/> +<span class="pre-in-pp"> + .PARAHEAD_INDENT 2.5P +</span> +</p> + +<p> +Mom’s default indent for paragraph heads is 1/2 the first-line +indent of normal paragraphs (both printstyles). However, as stated +above, if you choose to change the indent, you must give an absolute +value (unless you’re a groff expert and want to manipulate the +number register <kbd>\n[#PP_INDENT]u</kbd> arithmetically as the +argument to PARAHEAD_INDENT for an indent that’s relative to +PP_INDENT.) +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +Paragraph heads in “first paragraphs”, as defined in +<a href="#para-indent-first">Indenting initial paragraphs</a>, +are not indented unless you turn +<kbd><a href="#indent-first-paras">INDENT_FIRST_PARAS</a></kbd> +on. +</p> +</div> + +<h4 id="parahead-space" class="docs" style="margin-top: -.25em;">3. Horizontal space</h4> + +<p> +The default amount of horizontal space between a parahead and the +text that begins the body of a paragraph is 2/3 of an +<a href="definitions.html#em">em</a> +for +<a href="docprocessing.html#printstyle">PRINTSTYLE <kbd>TYPESET</kbd></a>) +and 1 +<a href="definitions.html#figurespace">figure space</a> +for +<a href="docprocessing.html#printstyle">PRINTSTYLE <kbd>TYPEWRITE</kbd></a>). +</p> + +<p> +The default for <kbd>TYPEWRITE</kbd> is fixed, but if the default +for <kbd>TYPESET</kbd> doesn’t suit you, you can change it +with the macro, PARAHEAD_SPACE. +</p> +<p> +PARAHEAD_SPACE takes just one argument: the amount of space you +want, with a +<a href="definitions.html#unitofmeasure">unit of measure</a> +appended. Thus, if you want the horizontal space between a parahead +and the start of paragraph text to be 6 +<a href="definitions.html#picaspoints">points</a>, +you’d do: +<br/> +<span class="pre-in-pp"> + .PARAHEAD_SPACE 6p +</span> +</p> + +<h4 id="number-paraheads" class="docs" style="margin-top: -1.25em;">4. Numbering</h4> + +<p> +If you’d like your paraheads numbered, simply invoke +<kbd>.NUMBER_PARAHEADS</kbd> with no argument. Mom +will number all subsequent paraheads automatically (in ascending +order, naturally). +</p> + +<p> +If, in addition to numbering paraheads, you also request that +<a href="#head-intro">heads</a> +and +<a href="#subhead-intro">subheads</a> +be numbered, the head and/or subhead number will be included in the +parahead number (separated by a period [dot]). +</p> + +<p> +Should you wish to stop parahead numbering, invoke +<kbd>.NUMBER_PARAHEADS</kbd> with any argument (<kbd>OFF, QUIT, END, +X</kbd>...). Parahead numbering will cease. +</p> + +<p> +See also +<a href="#prefix-chapter-number">Prefixing chapter numbers</a> +if you’d like chapter numbers prepended to the paragraph head +numbers. +</p> + +<h4 id="reset-parahead-number" class="docs" style="margin-top: -.25em;">5. Reset paragraph head numbering</h4> + +<p> +Should you wish to reset the parahead number to “1”, +invoke +<span class="pre-in-pp"> + .RESET_PARAHEAD_NUMBER +</span> +with no argument. If, for some reason, you want mom to use a +parahead number that is not the next in ascending order (i.e. the +last parahead number + 1), invoke <kbd>.RESET_PARAHEAD_NUMBER</kbd> +with the number you want, e.g. +<br/> +<span class="pre-in-pp"> + .RESET_PARAHEAD_NUMBER 7 +</span> +Your next parahead will be numbered “7” and subsequent +paraheads will be numbered in ascending order from “7”. +</p> + +<!-- -PREFIX_CHAPTER_NUMBER- --> + +<div class="examples-container" style="margin-bottom: 1.5em;"> +<div id="prefix-chapter-number" class="macro-id-overline" style="border-top: none;"> +<h3 class="macro-id" style="margin-top: 9px; text-transform: none; font-size: 105%;">Prefixing chapter numbers</h3> +</div> + +<div class="box-macro-args" style="width: 686px;"> +Macro: <b>PREFIX_CHAPTER_NUMBER</b> <kbd class="macro-args"><none> | <chapter number as digit> | <anything></kbd> +</div> + +<p> +If you’ve requested numbering of heads, subheads and/or paragraph +heads (with +<a href="#number-heads">NUMBER_HEADS</a>, +<a href="#number-subheads">NUMBER_SUBHEADS</a> +and/or +<a href="#number-paraheads">NUMBER_PARAHEADS</a>) +and you’d like mom, in addition, to prefix +a chapter number to the numbering scheme, you can do so with +PREFIX_CHAPTER_NUMBER. +</p> + +<p> +After you invoke <kbd>.PREFIX_CHAPTER_NUMBER</kbd>, mom will prepend +the current chapter number to all subsequent head elements (main +heads, subheads or paragraph heads) for which you have requested +numbering. Thus, assuming chapter number twelve (12): +<br/> +<span class="pre-in-pp"> + 1. FIRST MAIN HEAD + ------------------ + + 1.1. First Subhead Under Main Head +</span> +becomes +<br/> +<span class="pre-in-pp"> + 12.1. FIRST MAIN HEAD + --------------------- + + 12.1.1. First Subhead Under Main Head +</span> +</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> +is a digit. If it is, she immediately starts pre-pending the +current chapter number to numbered head elements. If it isn’t +(say you’ve called your chapter “One” instead of +“1”), mom will abort with a request that +you pass PREFIX_CHAPTER_NUMBER a digit representing +the current chapter number. +</p> + +<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 call your chapters “One”, +“Two”, “Three” instead of “1”, +“2”, “3”, mom will Do +The Right Thing with respect to numbering head 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 <i>must</i> 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. <b>OFF, QUIT, END, +X</b>, etc), 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> + +<p> +<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 <i>for the purposes of numbering head +elements</i> 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="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, lowered 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"><color name></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">Tag: QUOTE</a></li> + <li><a href="#quote-control">Quote control macros and defaults</a></li> +</ul> + +<p> +<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 programming 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"> +<h2 id="quote-spacing-notes" class="docs" style="padding-top: 9px; font-size: 100%;">Further notes on quote spacing</h2> +<p class="cefaults"> +As of version 1.3 of mom, handling of the vertical whitespace around +quotes changed slightly from its original implementation. +</p> + +<p> +In versions of mom prior to 1.3, it was not possible to alter the +<a href="definitions.html#leading">leading</a> +of quotes and blockquotes (which was the same as the document +leading), ensuring that the vertical whitespace remained consistent, +as described above. +</p> + +<p> +As of version 1.3, it became possible to change the +leading of quotes and blockquotes with <kbd>.QUOTE_AUTOLEAD</kbd> and +<kbd>BLOCKQUOTE_AUTOLEAD</kbd>, with the following changes in +mom’s behaviour: +</p> + +<p> +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 around the quotes to make sure +the whitespace is equal, top and bottom. Since she does this +on a quote by quote basis, rather than by figuring out how much +extra whitespace is needed to adjust <i>all</i> quotes on a page, +the spacing around multiple quotes on the same page will differ +slightly, although each will be balanced between lines of normal +<a href="definitions.html#running">running text</a>, +top and bottom. (The inability to scan an entire page and insert +equalized whitespace at marked places is a limitation of groff, +which, by and large, processes text on a line-per-line basis.) +</p> + +<p> +If you don’t want the behaviour described above (i.e. you +don’t want mom shimming [possibly irregularly linespaced] +quotes or blockquotes), issue the macro +<br/> +<span class="pre-in-pp"> + .NO_SHIM +</span> +prior to invoking <kbd>.QUOTE</kbd> or <kbd>.BLOCKQUOTE</kbd>. +</p> + +<p> +If you’ve disabled shimming of quotes and blockquotes with +<kbd>.NO_SHIM</kbd> and you want mom to return to her default +behaviour in this matter, invoke <kbd>.NO_SHIM OFF</kbd> (or +<kbd>QUIT, END, X</kbd>, etc). +</p> + +<p class="tip-bottom"> +If you don’t provide mom with a QUOTE_AUTOLEAD, quotes are +leaded at the default for normal running text, meaning that multiple +quotes on the same page are all spaced identically. +</p> +</div> + +<!-- -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">toggle</kbd> +</div> + +<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> +</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> + <li><a href="#break-quote">Manually break a footnoted quote that crosses pages/columns (deprecated)</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>. +</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) +.QUOTE_AUTOLEAD default = none; leading of quotes is the same as paragraphs +.QUOTE_COLOR default = black +.QUOTE_INDENT (see below, "Quote indent") +</span> +</div> + +<h4 id="quote-indent" class="docs" style="margin-top: -1.5em;">Quote indent</h4> + +<p> +Prior to version 1.4-b, mom allowed only the passing of an integer +to the macro, <kbd>.QUOTE_INDENT</kbd>. The integer represented the +amount by which to multiply the argument passed to +<kbd><a href="#para-indent">PARA_INDENT</a></kbd> +to arrive at an indent for quotes (and blockquotes). +</p> + +<p> +As of version 1.4-b, you can now append a +<a href="definitions.html#unitofmeasure">unit of measure</a> +to the argument passed to <kbd>.QUOTE_INDENT</kbd>, thus +setting an absolute indent, relative to nothing. The old +behaviour is still respected, though; in other words, if you +pass <kbd>.QUOTE_INDENT</kbd> an integer with no unit of measure +appended, the integer represents the amount by which to multiply +<kbd>.PARA_INDENT</kbd> to arrive at an indent for quotes (and +blockquotes). +</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> + +<p> +The default value for QUOTE_INDENT is 3 (for +<a href="docprocessing.html#printstyle">PRINTSTYLE <kbd>TYPESET</kbd></a>) +and 2 (for +<a href="docprocessing.html#printstyle">PRINTSTYLE <kbd>TYPEWRITE</kbd></a>). +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +QUOTE_INDENT also sets the indent for +<a href="#blockquote">blockquotes</a>. +</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">above</a>), +invoke the macro with any argument (<kbd>OFF, QUIT, END, 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 (<b>OFF, +QUIT, END, X</b>...) 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 <b>PRINTSTYLE TYPEWRITE</b>, you +must also make sure that ITALIC_MEANS_ITALIC is +enabled (see +<a href="docprocessing.html#typewrite-control">PRINTSTYLE TYPEWRITE control macros</a>). +</p> + +<h4 id="break-quote" class="docs">4. Manually break a footnoted quote that crosses pages/columns (deprecated)</h4> + +<div class="box-tip"> +<p class="tip"> +<i>As of version 1.1.9, the macro</i> BREAK_QUOTE <i>became obsolete +(or, at least, should have become obsolete.) It remains here for +backward compatibility with documents created prior to 1.1.9, and +just in case despite my efforts to make it obsolete you still +encounter the problem it’s supposed to fix. Should you find +yourself having to use</i> BREAK_QUOTE <i>while running</i> mom +1.1.9 <i>or higher, please notify me immediately.</i> +</p> +</div> + +<p style="margin-top: -.5em;"> +Exceptionally, a quote or blockquote containing a footnote may +cross a page or column. When this happens, the footnote marker may +not be correct for its position relative to other footnotes on the +page, and the footnote itself may appear on the wrong page or at the +bottom of the wrong column. When this happens, study your output to +determine the precise point at which the quote breaks (or at which +you want it to break), and add +<span class="pre-in-pp"> + .BREAK_QUOTE +</span> +on a line by itself afterwards. No other intervention is required, +and the footnote(s) will be marked correctly and appear on the +correct page. +</p> + +<p> +<kbd>.BREAK_QUOTE</kbd> may be used with both quotes and +blockquotes, and hence is aliased as <kbd>.BREAK_BLOCKQUOTE</kbd>, +<kbd>BREAK_CITATION</kbd> and <kbd>BREAK_CITE</kbd>. +</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">Tag: BLOCKQUOTE</a></li> + <li><a href="#blockquote-control">BLOCKQUOTE control macros</a></li> +</ul> + +<p> +<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">above</a> +for a complete explanation of how this is managed, and how +to control it.) +</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">toggle</kbd> +</div> + +<p class="alias" style="margin-bottom: 0;"> +<i>Aliases: </i> <b>CITE, CITATION</b> +</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> + +<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 +<kbd>BLOCKQUOTE_</kbd>. +</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> + <li><a href="#break-quote">Manually break a footnoted blockquote that crosses pages/columns</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>. +</p> +<span class="pre defaults"> +.BLOCKQUOTE_FAMILY default = prevailing document family; default is Times Roman +.BLOCKQUOTE_FONT default = roman +.BLOCKQUOTE_SIZE default = -1 (point) +.BLOCKQUOTE_AUTOLEAD default = none; leading of blockquotes is the same as paragraphs +.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> +Prior to version 1.4-b, mom allowed only the passing of an integer +to the macro, BLOCKQUOTE_INDENT. The integer represented the amount +by which to multiply the argument passed to +<kbd><a href="#para-indent">PARA_INDENT</a></kbd> +to arrive at an indent for blockquotes (and quotes). +</p> + +<p> +As of version 1.4-b, you can append a +<a href="definitions.html#unitofmeasure">unit of measure</a> +to the argument passed to <kbd>.BLOCKQUOTE_INDENT</kbd>, thus +setting an absolute indent, relative to nothing. The old +behaviour is still respected, though. In other words, if you pass +<kbd>.BLOCKQUOTE_INDENT</kbd> an integer with no unit of measure +appended, the integer represents the amount by which to multiply +<kbd>.PARA_INDENT</kbd> to arrive at an indent for blockquotes (and +quotes). +</p> + +<p> +The default value for <kbd>.BLOCKQUOTE_INDENT</kbd> is 3 (for +<a href="docprocessing.html#printstyle">PRINTSTYLE <kbd>TYPESET</kbd></a>) +and 2 (for PRINTSTYLE +<a href="docprocessing.html#printstyle">PRINTSTYLE <kbd>TYPEWRITE</kbd></a>). +</p> + +<div class="box-tip"> +<p class="tip-top"> +<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> + +<p class="tip-bottom"> +<span class="additional-note">Additional note:</span> +BLOCKQUOTE_INDENT also sets the indent for +<a href="#quote">QUOTES</a>. +</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">above</a>), +invoke the macro with any argument (<b>OFF, QUIT, END, +X</b>...). +</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 snippets</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 snippets +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] toggle</kbd> +</div> + +<p class="requires" style="font-style: normal"> +Inline escape: <b><kbd>\*[CODE]</kbd></b> +</p> + +<p> +When you invoke <kbd>.CODE</kbd> without an argument, or use the +<a href="definitions.html#inlines">inline escape</a>, +<kbd>\*[CODE]</kbd>, +mom changes the font to a +<a href="definitions.html#fixedwidthfont">fixed-width font</a> +(Courier, by default) and turns +<a href="goodies.html#smartquotes">SMARTQUOTES</a> +off. Additionally, if you invoke <kbd>.CODE</kbd> inside +<a href="#quote">QUOTE</a> +while in +<a href="docprocessing.html#printstyle">PRINTSTYLE <kbd>TYPEWRITE</kbd></a> +with the default underlining of quotes turned on, it disables the +underlining for the duration of CODE. +</p> + +<p> +Passing any argument other than <kbd>BR</kbd>, <kbd>BREAK</kbd> +or <kbd>SPREAD</kbd> to CODE (e.g. <kbd>OFF, QUIT, END, X,</kbd> +etc.) turns CODE off and returns the family, font, smartquotes +and (if applicable) underlining of quotes to their former state. +If you’ve used the inline escape, <kbd>\*[CODE]</kbd>, to +initiate a section of code, <kbd>\*[CODE OFF]</kbd> equally returns +things to their former state. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +If your code snippet 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> +</div> + +<div class="box-important"> +<p class="tip-top"> +<span class="important">Important:</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 immeidately is a macro that automatically causes +a break (e.g. +<a href="#pp">PP</a>). +</p> + +<p> +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' + .CODE OFF + .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. +</p> + +<p class="tip-bottom"> +<span class="note">Note:</span> +<kbd>BR</kbd>, <kbd>BREAK</kbd> and <kbd>SPREAD</kbd> have no +effect when used with the inline escape, <kbd>\*[CODE]</kbd>. The +assumption behind <kbd>\*[CODE]</kbd> is that you’re inserting +a bit of code into a line, not creating a distinct code block. +</p> +</div> + +<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/Color</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>. +</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 pre-pended +plus (<kbd>+</kbd>) or minus (<kbd>-</kbd>) sign, nor an appended +percent sign (<kbd>%</kbd>). Thus, is 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 miniscule in relation to the type around it. All +invocations of <kbd>.CODE</kbd> or <kbd>\*[CODE]</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, END, 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 organizing. 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> +Finally, lists can be used in documents created with either the +<a href="docprocessing.html#top">document processing macros</a> +or 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 <string>] [ <separator> | <user-defined enumerator> ] [ <prefix> ] [ <off> ]</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 +<kbd>mom</kbd> 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-numeralled 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. +</p> + +<p> +A roman-numeralled 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>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. +</p> + +<p> +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> +</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 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> +</p> + +<p> +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> +</div> + +<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> +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> + +<ol style="margin-top: .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. + o List 1 item + o List 1 item + - List 2 item + - List 2 item + o List 1 item + o 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 list 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: + 1. 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 + 2. Feed the cat + a) soft food on Mon., Wed. and Fri. + b) dry food on Tues., Thurs. and Sat. + c) canned tuna on Sunday +</span> +</p> + +<p> +Normally, within a nested list, when you return to an +incrementally-enumerated list, the enumerator continues incrementing +from where it left off. That means, in the example above, the +normal state of affairs for the alpha'ed list under +<br/> +<span class="pre-in-pp"> + 2. Feed the cat +</span> +would be d), e) and f). The solution, in such a case, is simply +to reset the enumerator—before <kbd>.ITEM</kbd>—with +the macro, <kbd>.RESET_LIST</kbd>. By default, with no argument, +<kbd>.RESET_LIST</kbd> resets the enumerator to 1, A, a, I or i +depending on the style of enumerator. You may, if you wish, pass +<kbd>.RESET_LIST</kbd> a +<a href="definitions.html#numericargument">numeric argument</a> +representing the starting enumerator for the reset (if different +from "1"), although I can’t at present think of a use for this +feature. +</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-lines-control-quote">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, heads, subheads, 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 + </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> +Line numbering may be enabled and disabled for +<kbd><a href="#quote">QUOTE</a></kbd> +and/or +<kbd><a href="#blockquote">BLOCKQUOTE</a></kbd> +in one of three styles. See +<a href="#number-lines-control-quote">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="#footnote-linenumbers">FOOTNOTE_MARKER_STYLE LINE</a> +for instructions on line-numbered footnotes, and +<a href="#endnote-marker-style">ENDNOTE_MARKER_STYLE</a> +for instructions on line-numbered endnotes.) +</p> + +<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 which <kbd>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>.NUMBER_LINES 1 1</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> input 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, QUIT, 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-control-quote">Line numbering control for quotes and blockquotes</a> + <ul style="margin-left: -.75em; list-style-type: disc;"> + <li><a href="#number-quote-lines">Number QUOTE lines</a></li> + <li><a href="#number-blockquote-lines">Number BLOCKQUOTE lines</a></li> + <li><a href="#number-lines-control-case">Numbering QUOTE and BLOCKQUOTE lines on a case by case basis</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>. +</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-control-quote" class="docs" style="margin-top: -1.75em;">2. Line numbering control macros for QUOTE and BLOCKQUOTE</h4> + +<h5 id="number-quote-lines" class="docs" style="margin-top: 1em;">Number QUOTE lines</h5> + +<p> +If you’d like mom to number lines of output text +in a +<a href="#quote">QUOTE</a> +as part of the same order and sequence as paragraph text, simply +invoke +<span class="pre-in-pp"> + .NUMBER_QUOTE_LINES +</span> +by itself. +</p> + +<p> +There is a catch with numbering quotes, though. Owing to groff’s +restriction on accepting only the figure space as the line number +gutter’s unit of measure, it is not possible for line numbers +in quotes to hang outside a document’s overall left margin and +be reliably flush with the line numbers of paragraph text. +Conseqently, line numbers in quotes hang to the left of the quote, +separated from the quote by the <kbd><gutter></kbd> argument. +</p> + +<p> +If you’d like to change the gutter for quotes line-numbered in +this way, invoke <kbd>.NUMBER_QUOTE_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 1 +</span> +With the above, line numbers in quotes (and only quotes) will have +a gutter of 1 figure space. +</p> + +<p> +If you’re using "line numbering style" for footnotes +(<a href="#footnote-marker-style">FOOTNOTE_MARKER_STYLE <kbd>LINE</kbd>)</a>, +you may not wish to have quotes <i>visibly</i> line-numbered, but +still want to embed footnotes inside quotes. In order to do that, +mom allows you to say +<span class="pre-in-pp"> + .NUMBER_QUOTE_LINES SILENT +</span> +When you invoke <kbd>.NUMBER_QUOTE_LINES SILENT</kbd>, +mom continues to increment line numbers while quotes are being +output, but they won’t appear in the output copy. (Compare +this with mom’s default behaviour of <i>suspending</i> +incrementing of line numbers during the output of quotes.) This +allows you to embed line-numbered footnotes inside quotes and have +the line number label in the footnote come out sensibly. +</p> + +<p> +Once having turned NUMBER_QUOTE_LINES on, you may disable it with +<span class="pre-in-pp"> + .NUMBER_QUOTE_LINES OFF +</span> +(or <kbd>QUIT, END, X,</kbd> etc). +</p> + +<h5 id="number-blockquote-lines" class="docs">Number BLOCKQUOTE lines</h5> + +<p> +If you’d like mom to number lines of output text +in a +<a href="#quote">BLOCKQUOTE</a> +as part of the same order and sequence as paragraph text, simply +invoke +<span class="pre-in-pp"> + .NUMBER_BLOCKQUOTE_LINES +</span> +by itself. +</p> + +<p> +There is a catch with numbering blockquotes, though. Owing to +groff’s restriction of accepting only the figure space as the +line number gutter’s unit of measure, it is not possible for line +numbers in blockquotes to hang outside a document’s overall left +margin and be reliably flush with the line numbers of paragraph +text. Conseqently, line numbers in blockquotes hang to the +left of the blockquote, separated from the blockquote by the +<kbd><gutter></kbd> argument. +</p> + +<p> +If you’d like to change the gutter for blockquotes line-numbered in +this way, invoke +<span class="pre-in-pp"> + .NUMBER_BLOCKQUOTE_LINES +</span> +with a digit representing the number of +<a href="definitions.html#figurespace">figure spaces</a> +you’d like between the line numbers and the blockquoted text, like +this: +<br/> +<span class="pre-in-pp"> + .NUMBER_BLOCKQUOTE_LINES 1 +</span> + +With the above, line numbers in blockquotes (and only blockquotes) +will have a gutter of 1 figure space. +</p> + +<p> +If you are using "line numbering style" for footnotes +(<a href="#footnote-marker-style">FOOTNOTE_MARKER_STYLE <kbd>LINE</kbd>)</a>, +you may not wish to have blockquotes <i>visibly</i> line-numbered, +but still want to embed footnotes inside blockquotes. In order to +do that, mom allows you to say +<span class="pre-in-pp"> + .NUMBER_BLOCKQUOTE_LINES SILENT +</span> +When you invoke <kbd>.NUMBER_BLOCKQUOTE_LINES SILENT</kbd>, +mom continues to increment line numbers while blockquotes are being +output, but they won’t appear in the output copy. (Compare +this with mom’s default behaviour of <i>suspending</i> +incrementing of line numbers during the output of blockquotes.) +This allows you to embed line-numbered footnotes inside blockquotes +and have the line number label in the footnote come out sensibly. +</p> + +<p> +Once having turned NUMBER_BLOCKQUOTE_LINES on, you may disable it +with +<span class="pre-in-pp"> + .NUMBER_BLOCKQUOTE_LINES OFF +</span> +(or <kbd>QUIT, END, X,</kbd> etc). +</p> + +<h4 id="number-lines-control-case" class="docs" style="margin-top: -.25em;">3. Numbering QUOTE and BLOCKQUOTE lines on a case by case basis</h4> + +<p> +Sometimes, you may want quotes or blockquotes to have a different +line numbering scheme from the one used in the rest of the document. +Or, you may want line numbering enabled only inside a particular +quote or blockquote. A common reason for this would be if you were +using the +<a href="#quote">QUOTE</a> +macro to insert lines of programming code into a document. +</p> + +<p> +To enable line numbering within quotes or blockquotes on a case by +case basis, simply invoke +<a href="#number-lines">NUMBER_LINES</a> +with the arguments you need immediately after entering +<kbd><a href="#quote">.QUOTE</a></kbd> +or +<kbd><a href="#blockquote">.BLOCKQUOTE</a></kbd>. +(<a href="number-quote-lines">NUMBER_QUOTE_LINES</a> +and/or +<a href="number-blockquote-lines">NUMBER_BLOCKQUOTE_LINES</a> +should be turned off if you’re doing this.) The quote +or blockquote will then be line-numbered according to your +specifications: the starting line number of the quote or blockquote +will be the one you give as a first argument to NUMBER_LINES; which +lines to number will be the value you pass to <kbd>which lines +to number</kbd> (defaults to <kbd>1</kbd>); line numbers will +hang to the left of the quote or blockquote, separated from the +quote or blockquote by <kbd>gutter</kbd> (defaults to <kbd>2</kbd>). +</p> + +<p> +As soon as QUOTE or BLOCKQUOTE is turned off, line numbering ceases, +not only with respect to subsequent paragraph text (if they are +not being line-numbered), but also for any subsequent invocation +of <kbd>.QUOTE</kbd> or <kbd>.BLOCKQUOTE</kbd>. In other words, +you must re-enable quote or blockquote line-numbering inside every +instance of QUOTE or BLOCKQUOTE when line-numbering either of them +on a case by case basis. +</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> + +<p> +Footnotes can be sly little beasts, though. If you’re writing +a document that’s footnote-heavy, you might want to read the +following. +</p> + +<h3 id="footnote-behaviour" class="docs">Footnote behaviour</h3> + +<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. The amount of whitespace +varies 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> +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>X, QUIT, EXIT</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> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +Exceptionally, you may encounter problems +with footnotes inside quotes and blockquotes that cross a page or +column. See +<a href="#break-quote">BREAK_QUOTE</a> +for a solution. +</p> +</div> + +<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>QUIT, END, 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><indent value></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 INDENT (i.e. <kbd>OFF, +QUIT, END, 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>QUIT, END, 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 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</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>. +</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>END, QUIT, +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> + +<h4 id="footnotes-by-linenumber" class="docs" style="margin-top: -.25em;">4. Footnotes by line number</h4> + +<p> +<kbd>.FOOTNOTE_MARKER_STYLE 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 terminating the text line before it +with</i> <kbd>\c</kbd>, at the appropriate place in running text. +</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>\*[FN-MARK]</kbd>. For the terminating line number of the +range, you need only invoke <kbd>.FOOTNOTE</kbd>, (again, without +attaching <kbd>\c</kbd> to the text line before it). Mom is smart +enough to figure out that where <kbd>.FOOTNOTE</kbd> was invoked +represents the terminating line number. Range-numbered footnotes +are always output on the page where <kbd>.FOOTNOTE</kbd> was +invoked, not the page where <kbd>\*[FN-MARK]</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> + +<h5 id="footnote-linenumber-brackets" class="docs" style="margin-top: -.25em;">Footnote line number brackets</h5> + +<p> +Mom, by default, puts footnote line numbers inside square +brackets. The style of the brackets may be changed with the macro, +FOOTNOTE_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="footnote-linenumber-separator" class="docs" style="margin-top: -.25em;">FOOTNOTE_LINENUMBER_SEPARATOR</h5> + +<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. The macro to do this is +FOOTNOTE_LINENUMBER_SEPARATOR, which takes, as its single argument, +the separator you want. For safety and consistency’s sake, +always enclose the argument in double-quotes. +</p> + +<p> +The separator can be composed of any valid groff character, +or any combination of characters. +</p> + +<p> +<b>A word of caution:</b> when using a separator, mom doesn’t +insert a space after the separator. Hence, if you want the 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: -.25em;">RUN-ON FOOTNOTES</h5> + +<p> +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. on a line by +themselves. Rather, each footnote is separated from the footnote +before it by a space, so that the footnotes on any given page +form a continuous block, like lines in a paragraph. The macro +to get mom to run footnotes on is <kbd>.FOOTNOTES_RUN_ON</kbd>. +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> + +<p> +The usual reason for wanting run-on footnotes is that you’re +using them to hold many, short references. (See +<a href="refer.html#top">here</a> +for instructions on using the groff program, <kbd>refer</kbd>, to +set up references.) +</p> + +<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_SPACE</h4> + +<p> +If you’d like a little extra space between footnotes, you can +have mom put it in for you by invoking <kbd>.FOOTNOTE_SPACE</kbd> +with an argument representing the amount of extra space you’d +like. The argument to FOOTNOTE_SPACE 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_SPACE 3p +</span> +</p> + +<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, QUIT, 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">PRINTSTYLES</a>. +</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-spacing">A note on endnotes spacing</a></li> + <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 +<kbd><a href="#endnote-marker-style">ENDNOTE_MARKER_STYLE</a></kbd> +is <kbd>NUMBER</kbd> (which marks 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>, + 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> + +<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, double-underscored head, “ENDNOTES”. +Underneath—flush left, bold, and underscored—she prints +the document title (or, in the case of chapters, the chapter +number or title). She then prints the endnotes. Each endnote is +identified by its appropriate number, in bold, right aligned to two +placeholders. The text of the endnotes themselves is indented to +the right of the numbers. +</p> + +<p> +If the endnotes are grouped together at the end of a collated +document, each section of the document that contains endnotes is +identified by its own unique title (or chapter number or title), +bold, flush left, and underscored. +</p> + +<p> +Of course, all the defaults, as well as the overall style of the +endnotes page, 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-spacing" class="docs">A note on endnotes spacing</h3> + +<p> +On the endnotes page(s), each new endnote is separated from the +previous endnote by a full line space. This can result in a bottom +margin that hangs, and is the one instance, other than the use of +<a href="#pp-space">PARA_SPACE</a>, +where mom allows unequal bottom alignment of pages. Should you wish +to correct this, by adding or subtracting small amounts of space +between endnotes that appear together on an endnotes page, make the +adjustment (with +<a href="typesetting.html#ald">ALD</a>, +<a href="typesetting.html#rld">RLD</a> +or +<a href="typesetting.html#space">SPACE</a>) +<i>at the end of each endnote</i> (i.e. just before invoking +<a href="#endnote"><kbd>.ENDNOTE OFF</kbd></a>) +rather than at the top. +</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, QUIT, END, 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> (mom’s default), 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 <i>after</i> <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 <b>QUIT, END, X,</b> 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. +</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="#singlespace-endnotes">Singlespace endnotes (TYPEWRITE only)</a></li> + <li><a href="#endnote-para-indent">Paragraph indenting</a></li> + <li><a href="#endnote-para-space">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-main-title"><b>Endnotes' first-page title control</b></a> + <ul style="margin-left: -.5em;"> + <li><a href="#endnote-string">Title string</a></li> + <li><a href="#endnote-string-control">Title string control macros and defaults</a></li> + <li><a href="#endnote-string-placement">Title string placement</a></li> + <li><a href="#endnote-string-underline">Title string underscoring</a></li> + <li><a href="#endnote-string-caps">Title 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> + <li><a href="#endnote-title-underscore">Document-identification string underscoring</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>. +</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 14 points, 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> + +<!-- -SINGLESPACE_ENDNOTES- --> + +<h5 id="singlespace-endnotes" class="docs" style="margin-top: -.5em; 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, QUIT, Q, 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;">• 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> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +Each endnote itself is always separated from any previous endnote +by a line space. ENDNOTE_PARA_SPACE refers only to paragraphs that +appear within each discrete endnote. +</p> +</div> + +<!-- -ENDNOTES_NO_COLUMNS- --> + +<h5 id="endnotes-no-columns" class="docs" style="margin-top: -.5em; 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, QUIT, Q, 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-main-title" class="docs">4. Endnotes' first-page title control</h4> + +<!-- -ENDNOTE_STRING- --> + +<h5 id="endnote-string" class="docs" style="margin-top: 1em; margin-bottom: .5em; margin-left: .5em;">• Title string</h5> + +<div class="box-macro-args"> +Macro: <b>ENDNOTE_STRING</b> <kbd class="macro-args">"<head to print at the top of endnotes>"</kbd> +</div> + +<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>.ENDNOTE_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>.ENDNOTE_STRING</kbd> with a blank argument (either two +double-quotes side by side—<kbd>""</kbd>—or no +argument at all). +</p> + +<!-- -ENDNOTE_STRING_CONTROL- --> + +<h5 id="endnote-string-control" class="docs" style="margin-top: -.5em; margin-bottom: .5em; margin-left: .5em;">• 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>. +</p> +<span class="pre defaults"> +.ENDNOTE_STRING_FAMILY default = prevailing document family; default is Times Roman +.ENDNOTE_STRING_FONT default = bold +.ENDNOTE_STRING_SIZE* default = +1 +.ENDNOTE_STRING_QUAD default = centred + +*Relative to the size of the endnotes text (set with ENDNOTE_PT_SIZE) +</span> +</div> + +<!-- -ENDNOTE_STRING_ADVANCE- --> + +<h5 id="endnote-string-placement" class="docs" style="margin-top: -1em; margin-bottom: .5em; margin-left: .5em;">• Title string placement</h5> + +<div class="box-macro-args"> +Macro: <b>ENDNOTE_STRING_ADVANCE</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 measusure</a> +</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>.ENDNOTE_STRING_ADVANCE</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"> + .ENDNOTE_STRING_ADVANCE 1.5i +</span> +</p> + +<!-- -ENDNOTE_STRING_UNDERLINE- --> + +<h5 id="endnote-string-underline" class="docs" style="margin-top: -1em; margin-bottom: .5em; margin-left: .5em;">• Title string underscoring</h5> + +<div class="box-macro-args"> +Macro: <b>ENDNOTE_STRING_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>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>.ENDNOTE_STRING_UNDERSCORE</kbd> +will place a single rule underneath the endnotes page title. Invoked +with the argument, <kbd>DOUBLE</kbd>, ENDNOTE_STRING_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 ENDNOTE_STRING_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"> + .ENDNOTE_STRING_UNDERSCORE 1 + - turn underscoring on; set the rule weight to 1 point + + .ENDNOTE_STRING_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 + + .ENDNOTE_STRING_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 underunderscore at the default + + .ENDNOTE_STRING_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 ENDNOTE_STRING_UNDERSCORE is used in +this way. +</p> + +<p> +Mom’s default is to double-underscore the title with 1/2-point +rules placed 2 points apart and 2 points below the baseline of the +title. +</p> + +<!-- -ENDNOTE_STRING_CAPS- --> + +<h5 id="endnote-string-caps" class="docs" style="margin-top: -.5em; margin-bottom: .5em; margin-left: .5em;">• Title string capitalization</h5> + +<div class="box-macro-args"> +Macro: <b>ENDNOTE_STRING_CAPS</b> <kbd class="macro-args">toggle</kbd> +</div> + +<p> +Invoked by itself, <kbd>.ENDNOTE_STRING_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 +<kbd><a href="#endnote-string">ENDNOTE_STRING</a></kbd> +is in caps/lower case and ENDNOTE_STRING_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>. +</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_QUAD default = left + +*Relative to the size of the endnotes text (set with ENDNOTE_PT_SIZE) +</span> +</div> + +<!-- -ENDNOTE_TITLE_UNDERLINE- --> + +<h5 id="endnote-title-underscore" class="docs" style="margin-top: -1.25em; margin-bottom: .5em; margin-left: .5em;">• Endnotes document-identification underscoring</h5> + +<div class="box-macro-args"> +Macro: <b>ENDNOTE_TITLE_UNDERSCORE</b> <kbd class="macro-args">[DOUBLE] [<underline weight> [<underline gap> [<distance between double rules]]] | <none> | <anything></kbd> +</div> + +<p class="alias" style="margin-bottom: 0;"> +<i>Alias:</i> <b>ENDNOTE_TITLE_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>.ENDNOTE_TITLE_UNDERSCORE</kbd> +will place a single rule underneath the document identification +string. Invoked with the argument <kbd>DOUBLE</kbd>, +ENDNOTE_TITLE_UNDERSCORE will double-underscore the string. Invoked +with any other non-numeric argument, (e.g. <kbd>OFF, NO, X</kbd>, +etc.) the macro disables underscoring of the string. +</p> + +<p> +In addition, you can use ENDNOTE_TITLE_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"> + .ENDNOTE_TITLE_UNDERSCORE 1 + - turn underscoring on; set the rule weight to 1 point + + .ENDNOTE_TITLE_UNDERSCORE 1 3p + - turn underscoring on; set the rule weight to 1 point; set + the gap between the string and the underscore to 3 points + + .ENDNOTE_TITLE_UNDERSCORE DOUBLE .75 3p + - turn double-underscoring on; set the rule weight to 3 points + + .ENDNOTE_TITLE_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 string 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> +</p> + +<p> +Note, from the above, that in all instances, underscoring (single or +double) is enabled whenever ENDNOTE_TITLE_UNDERSCORE is used in this +way. +</p> + +<p> +Mom’s default is to single-underscore the string with a +1/2-point rule placed 2 points below its baseline. +</p> + +<!-- -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">LINE | NUMBER</kbd> +</div> + +<p> +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>, <i>without terminating the text line before +it with</i> <kbd>\c</kbd>, at the appropriate place in running +text. +</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>\*[EN-MARK]</kbd>. For the terminating line number of the +range, you need only invoke <kbd>.ENDNOTE</kbd>, (again, without +attaching <kbd>\c</kbd> to the text line before it). Mom is smart +enough to figure out that where <kbd>.ENDNOTE</kbd> is invoked +represents the terminating line number. +</p> + +<h5 id="endnote-linenumber-gap" class="docs" style="margin-top: -.5em; 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> +Given the impossibility of knowing, in advance, the string length +of all the line numbers or ranges of line numbers that will be used +in endnotes (the string length of “12” is two; the string length of +“12-15” is 5), mom cannot “hang” line +numbers and guarantee that they, and the endnote text, will align in +a visually pleasing manner. Consequently, mom sets the entirety of +line-numbered endnotes completely flush left, including the line +numbers themselves. The line numbers (by default, enclosed in +square brackets) are separated from the beginning of each endnote +by a gap, so that a line-numbered endnote looks approximately like +this: +<br/> +<span class="pre-in-pp"> + [1-2] Notwithstanding, Frye later asserts that Christianity + is "a ghost with the chains of a foul historical record of + cruelty clanking behind it." +</span> +You can change the size of the gap with the macro, +ENDNOTE_LINENUMBER_GAP, which 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> +The default gap for both +<a href="docprocessing.html#printstyle">PRINTSTYLE TYPESET</a> +and +<a href="docprocessing.html#printstyle">PRINTSTYLE TYPEWRITE</a> +is 1.5 +<a href="definitions.html#em">ems</a>. +</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 the document(s). +</p> +<span class="pre defaults"> +.ENDNOTE_NUMBER_FAMILY default = prevailing document family; default is Times Roman +.ENDNOTE_NUMBER_FONT default = bold +.ENDNOTE_NUMBER_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, 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> +The macros to alter this behaviour are +</p> +<ul style="margin-top: -.5em; margin-left: -.5em;"> + <li><a href="#endnote-numbers-align-right">ENDNOTE_NUMBERS_ALIGN_RIGHT</a></li> + <li><a href="#endnote-numbers-align-left">ENDNOTE_NUMBERS_ALIGN_LEFT</a></li> +</ul> + +<!-- -ENDNOTE_NUMBERS_ALIGN_RIGHT- --> + +<div id="endnote-numbers-align-right" class="box-macro-args"> +Macro: <b>ENDNOTE_NUMBERS_ALIGN_RIGHT</b> <kbd class="macro-args"><number of placeholders></kbd> +</div> + +<p> +ENDNOTE_NUMBERS_ALIGN_RIGHT takes one (non-optional) argument: the +number of placeholders to reserve for right alignment of endnote +numbers. +</p> + +<p> +For example, if you have fewer than ten endnotes, you might want to do +<br/> +<span class="pre-in-pp"> + .ENDNOTE_NUMBERS_ALIGN_RIGHT 1 +</span> +which would ensure that the endnote numbers hang, but are all flush +with the page’s left margin. If, god help you, you have over a hundred +endnotes, you’d want to do +<br/> +<span class="pre-in-pp"> + .ENDNOTE_NUMBERS_ALIGN_RIGHT 3 +</span> +to ensure that the numbers hang and are properly right-aligned. +</p> + +<!-- -ENDNOTE_NUMBERS_ALIGN_LEFT- --> + +<div id="endnote-numbers-align-left" class="box-macro-args"> +Macro: <b>ENDNOTE_NUMBERS_ALIGN_LEFT</b> +</div> + +<p> +If you don’t want the endnote numbers to hang and right-align, +invoke <kbd>.ENDNOTE_NUMBERS_ALIGN_LEFT</kbd>, which doesn’t +require any argument. This disables hanging and right-alignment of +endnote numbers, so that the example +<a href="#endnote-numbering-alignment-example">above</a> +comes out like this: +<br/> +<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> +</p> + +<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>—initialize margin notes</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>. +</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 center 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, sucessfully 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> <i>must</i> 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 ] +<left-width> +<right-width> +<gutter> +<family+font> +<point-size> +<lead> +<colour> +<hyphenation-flags> +</span> + +<p style="margin-top: 1.25em;"> +Before you enter your first margin note, you must initialize +<i>all</i> the parameters associated with margin notes with MN_INIT. +If you forget to do so, mom will issue a warning and abort. +</p> + +<p> +The argument list is quite long; an explanation of each argument +follows. Any argument whose value you want to be the default must +be entered as <kbd>""</kbd> (i.e. two double-quotes with +no space between them). Defaults for each argument are given in the +explanations below. +</p> + +<h4 class="docs arg-list">Argument 1: <kbd style="color: #302419;">[ RAGGED | SYMMETRIC ]</kbd></h4> + +<p> +If the first argument is <kbd>RAGGED</kbd>, both left and +right margin notes will be flush left. If the first argument +is <kbd>SYMMETRIC</kbd> left margin notes will be set flush +<i>right</i>, and right margin notes will be set 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, or given as <kbd>""</kbd>, +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">Argument 2: <kbd style="color: #302419;"><left-width></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">Argument 3: <kbd style="color: #302419;"><right-width></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">Argument 4: <kbd style="color: #302419;"><gutter></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">Argument 5: <kbd style="color: #302419;"><font></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 TR. If you want Palatino +Medium Italic, the argument must be PI. The default is the same +family+font combo used for a document’s paragraph text. +</p> + +<h4 class="docs arg-list">Argument 6: <kbd style="color: #302419;"><point size></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">Argument 7: <kbd style="color: #302419;"><lead></kbd></h4> + +<p> +The +<a href="definitions.html#leading">leading</a> +of margin notes. <kbd><lead></kbd> uses +<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 leading +as is used for paragraph text (i.e. the document’s base +leading). If you want the default, you may, for convenience +and clarity, give the word, <kbd>DOC</kbd>, to this argument, +instead of <kbd>""</kbd> (two double-quotes). Like the +double-quotes, it indicates that the leading should be the same as +the document’s base leading. +</p> + +<h4 class="docs arg-list">Argument 8: <kbd style="color: #302419;"><colour></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">Argument 9: <kbd style="color: #302419;"><hyphenation-flags></kbd></h4> + +<p> +A number telling groff how you want margin notes +hyphenated. +<br/> +<span class="pre-in-pp"> + 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>QUIT, END, 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>FINIS control macros + <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 color</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="#toc">.TOC</a></kbd> +or +<kbd><a href="#endnotes">.ENDNOTES</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> +</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> +or +<kbd><a href="#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-string" class="docs">Changing the FINIS string</h3> + +<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, i.e. +<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- --> + +<h3 id="finis-string-caps" class="docs">Automatic capitalization of the FINIS string</h3> + +<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- --> + +<h3 id="finis-color" class="docs">Changing the FINIS colour</h3> + +<p> +Invoking the control macro, <kbd>.FINIS_COLOR</kbd>, with a +pre-defined (or “initalized”) color 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>\*[<colorname>]</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> + +<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: Inserting images</a></td> +</tr> +</table> + +</div> + +<div class="bottom-spacer"><br/></div> + +</body> +</html> +<!-- vim: fileencoding=utf-8: nomodified: --> |