groff-commit
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

[Groff-commit] groff/contrib/mom/momdoc appendices.html color....


From: Peter Schaffter
Subject: [Groff-commit] groff/contrib/mom/momdoc appendices.html color....
Date: Wed, 18 Aug 2010 22:45:37 +0000

CVSROOT:        /sources/groff
Module name:    groff
Changes by:     Peter Schaffter <PTPi>  10/08/18 22:45:36

Added files:
        contrib/mom/momdoc: appendices.html color.html cover.html 
                            definitions.html docelement.html 
                            docprocessing.html goodies.html 
                            graphical.html headfootpage.html images.html 
                            inlines.html intro.html letters.html 
                            macrolist.html rectoverso.html refer.html 
                            reserved.html stylesheet.css 
                            tables-of-contents.html toc.html 
                            typesetting.html using.html 

Log message:
        Complete overhaul of documentation; added new files.

CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/mom/momdoc/appendices.html?cvsroot=groff&rev=1.19
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/mom/momdoc/color.html?cvsroot=groff&rev=1.13
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/mom/momdoc/cover.html?cvsroot=groff&rev=1.15
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/mom/momdoc/definitions.html?cvsroot=groff&rev=1.17
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/mom/momdoc/docelement.html?cvsroot=groff&rev=1.36
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/mom/momdoc/docprocessing.html?cvsroot=groff&rev=1.37
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/mom/momdoc/goodies.html?cvsroot=groff&rev=1.27
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/mom/momdoc/graphical.html?cvsroot=groff&rev=1.7
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/mom/momdoc/headfootpage.html?cvsroot=groff&rev=1.21
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/mom/momdoc/images.html?cvsroot=groff&rev=1.1
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/mom/momdoc/inlines.html?cvsroot=groff&rev=1.25
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/mom/momdoc/intro.html?cvsroot=groff&rev=1.20
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/mom/momdoc/letters.html?cvsroot=groff&rev=1.16
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/mom/momdoc/macrolist.html?cvsroot=groff&rev=1.17
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/mom/momdoc/rectoverso.html?cvsroot=groff&rev=1.14
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/mom/momdoc/refer.html?cvsroot=groff&rev=1.11
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/mom/momdoc/reserved.html?cvsroot=groff&rev=1.39
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/mom/momdoc/stylesheet.css?cvsroot=groff&rev=1.1
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/mom/momdoc/tables-of-contents.html?cvsroot=groff&rev=1.1
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/mom/momdoc/toc.html?cvsroot=groff&rev=1.37
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/mom/momdoc/typesetting.html?cvsroot=groff&rev=1.27
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/mom/momdoc/using.html?cvsroot=groff&rev=1.14

Patches:
Index: appendices.html
===================================================================
RCS file: appendices.html
diff -N appendices.html
--- /dev/null   1 Jan 1970 00:00:00 -0000
+++ appendices.html     18 Aug 2010 22:45:35 -0000      1.19
@@ -0,0 +1,819 @@
+<?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 -- Appendices</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="reserved.html#top">Next: Reserved 
words</a></td>
+</tr>
+</table>
+
+<h1 id="appendices" class="docs">Appendices</h1>
+
+<div style="width: 54%; margin: auto;">
+<ul class="no-enumerator">
+  <li><a href="#moredoc">Notes on the documentation</a></li>
+  <li><a href="#fonts">Adding PostScript fonts to groff</a>
+  <ul style="margin-left: -.5em;">
+    <li><a href="#howto">How to create a PostScript font for use with 
groff</a></li>
+  </ul></li>
+  <li><a href="#codenotes">Some reflections on mom</a></li>
+  <li><a href="#contact">Contact the author</a></li>
+</ul>
+</div>
+
+<div class="rule-medium"><hr/></div>
+
+<h2 id="moredoc" class="docs">Notes on the documentation</h2>
+
+<p>
+Some mom users are sure to ask: &#8220;Why is the documentation in
+html?  If mom&#8217;s so great, why not pdfs to show her off?  And
+if groff&#8217;s so great, why not write a man page?&#8221;
+</p>
+
+<p>
+Valid questions, to be sure, and mom has answers.  (Okay&mdash;I
+have answers, but I speak for mom.)
+</p>
+
+<p>
+The documentation is in html because I still find it the best tool
+for navigating lengthy manuals.  Html, with its anchors and links,
+came into being precisely so people could do something they&#8217;d
+never been able to with the printed word: instantly track down
+internal and external references in a document.
+</p>
+
+<p>
+It&#8217;s essential that people reading mom&#8217;s documentation
+never have difficulty finding precisely the macro they need for a
+particular task.  Equally, when reading up on a macro, they should
+never be presented with terms or other macro names for which they
+cannot instantly find accurate explanations.  Short of having
+written the documentation in TeX for the info browser (and TeX bloat
+is one of the reasons I prefer to typeset with groff), I can think
+of no better way to achieve the kind of truly useful documentation I
+wanted than html.
+</p>
+
+<div class="rule-medium"><hr/></div>
+
+<!-- ===================================================================== -->
+
+<h2 id="fonts" class="docs">Adding PostScript fonts to groff</h2>
+
+<div class="box-tip">
+<p class="tip">
+Robert Valiant has set up a web page containing information,
+instructions and strategies for adding PostScript and TrueType fonts
+to groff for use with mom.  The page is directed at Debian GNU/Linux
+users, but knowledgable users of other GNU/Linux distributions
+should have no difficulty adapting it to their needs.  The site is
+located at
+<br/>
+<span class="pre-in-pp" style="display:block; margin-bottom: -1em;">
+  <a 
href="http://russia.shaps.hawaii.edu/software/software.html";>http://russia.shaps.hawaii.edu/software/software.html</a>
+</span>
+</p>
+</div>
+
+<div id="small-note" class="box-tip">
+<p class="tip">
+<span class="note">Note:</span>
+The term <kbd>&lt;prefix&gt;</kbd> in this section refers
+to the directory in which groff is installed, typically
+something like <kbd>/usr/share/groff/&lt;version&gt;</kbd>
+(for distro-specific, pre-compiled groff packages) or
+<kbd>/usr/local/share/groff/&lt;version&gt;</kbd> (if you&#8217;ve
+built groff from source).
+</p>
+</div>
+
+<p>
+Groff comes with a small library of PostScript
+<a href="definitions.html#family">families</a>
+(see the
+<a href="typesetting.html#family">FAMILY</a>
+macro for a list).  The families have four
+<a href="definitions.html#font">fonts</a>
+associated with them.  These fonts are a combination of
+<a href="definitions.html#weight">weight</a>
+and
+<a href="definitions.html#shape">shape</a>:
+<br/>
+<span class="pre-in-pp">
+  R  (Roman, usually Medium weight),
+  I  (Italic, usually Medium weight),
+  B  (Bold, usually Roman shape) and
+  BI (Bold Italic)
+</span>
+If you work with mom a lot, you&#8217;ll find, sooner or later, that these
+families and their associated fonts aren&#8217;t sufficient.  You&#8217;ll
+want to supplement them, either with more fonts for the families
+already provided&mdash;<i>Damn!  I need Helvetica Bold Condensed
+Italic!</i>&mdash;or with entire new families.
+</p>
+
+<p>
+Without going into the gory details (yet), while it&#8217;s true
+that adding fonts to groff is a relatively straightforward process,
+extending existing families or adding new ones requires some
+planning.
+</p>
+
+<p>
+The traditional approach to extending groff families has been to
+create new families for non-default weights and shapes (e.g.  Light,
+which is a weight; Condensed, which is a shape), then to associate
+them with groff&#8217;s predefined <b>R, I, B</b> and <b>BI</b> font
+styles.  An example of this can be seen in the groff PostScript
+font library itself (&lt;prefix&gt;/font/devps/): there&#8217;s one
+&#8220;family&#8221; for Helvetica (<b>HR</b>, <b>HI</b>, <b>HB</b>,
+<b>HBI</b>) and another for Helvetica Narrow (<b>HNR</b>,
+<b>HNI</b>, <b>HNB</b>, <b>HNBI</b>).
+</p>
+
+<p>
+The difficulty with this approach is that typographers tend to
+think of families as referring to the entire set of font weights
+and shapes associated with a particular family name.  For example,
+when a typesetter says &#8220;the Helvetica family&#8221;, s/he is
+including the
+<a href="definitions.html#weight">weights</a>
+Helvetica Thin, Helvetic Light, Helvetica Regular, Helvetica Bold,
+Helvetica Heavy, etc, and all their associated
+<a href="definitions.html#shape">shapes</a>
+(Roman, Italic, Condensed, Narrow, Extended, Outline, etc).
+</p>
+
+<p>
+Thus, intuitively, when a typesetter gives mom a
+<kbd>.FAM(ILY)&nbsp;H</kbd> directive, s/he reasonably expects that
+any subsequent <kbd>.FT</kbd> directive will access the desired font
+from the Helvetica family&mdash;without the need to state explicitly
+both family and font to <kbd>.FT</kbd>, as it is explained one can
+do in the
+<a href="typesetting.html#family">FAMILY</a>
+and
+<a href="typesetting.html#font">FT</a>
+sections of these documents.
+</p>
+
+<p>
+If one had, say, the fonts, Helvetica Light Roman and Helvetica
+Light Italic as well as Helvetica Light Condensed Roman and
+Helvetica Light Condensed Italic, the established groff approach
+would require two &#8220;partial&#8221; families: HLR/HLI and
+HLCDR/HLCDI.  Accessing these family/font combos routinely
+throughout a document would then require changing family
+(with <kbd>.FAM(ILY)</kbd>) and selecting the desired font
+(with <kbd>.FT&nbsp;R</kbd> or <kbd>.FT&nbsp;I</kbd>), or
+passing <kbd>.FT</kbd> the lengthy family+fontname (.e.g.
+<kbd>.FT&nbsp;HLCDI</kbd>).
+</p>
+
+<p>
+Fortunately, groff provides a mechanism whereby it&#8217;s possible
+to extend the basic <b>R</b>, <b>I</b>, <b>B</b> and <b>BI</b> fonts
+(&#8220;styles&#8221; in groff-speak) so that one can, in fact,
+create extensive type families, and access all the fonts in them
+with <kbd>.ft</kbd> (groff) or <kbd>.FT</kbd> (mom).
+</p>
+
+<p>
+Mom uses this mechanism to offer, in addition to groff&#8217;s
+default PostScript font styles, the following:
+</p>
+
+<div class="examples-container" style="padding-bottom: 1em;">
+<div id="style-extensions" style="width: 53%; float: left;">
+<span class="pre">
+L     =  Light Roman
+LI    =  Light Italic
+LCD   =  Light Condensed Roman
+LCDI  =  Light Condensed Italic
+LEX   =  Light Extended Roman
+LEXI  =  Light Extended Italic
+CD    =  Medium/Book Condensed Roman
+CDI   =  Medium/Book Condensed Italic
+EX    =  Medium/Book Extended Roman
+EXI   =  Medium/Book Extended Italic
+DB    =  DemiBold Roman
+DBI   =  DemiBold Italic
+BCD   =  Bold Condensed Roman
+BCDI  =  Bold Condensed Italic
+BEX   =  Bold Extended Roman
+</span>
+</div>
+<span class="pre">
+BEXI   =  Bold Extended Italic
+HV     =  Heavy Roman
+HVI    =  Heavy Italic
+HVCD   =  Heavy Condensed Roman
+HVCDI  =  Heavy Condensed Italic
+HVEX   =  Heavy Extended Roman
+HVEXI  =  Heavy Extended Italic
+BL     =  Black Roman
+BLI    =  Black Italic
+BLCD   =  Black Condensed Roman
+BLCDI  =  Black Condensed Italic
+BLEX   =  Black Extended Roman
+BLEXI  =  Black Extended Italic
+UBL    =  Ultra-Black Roman
+UBLI   =  Ultra-Black Italic
+</span>
+</div>
+
+<p style="clear: both;">
+Thus, with mom, if you&#8217;ve installed, say, some extra
+Helvetica fonts and named them according to the convention
+<kbd>&lt;F&gt;&lt;S&gt;</kbd> (where <kbd>&lt;F&gt;</kbd> means
+family and <kbd>&lt;S&gt;</kbd> means font style), once having
+entered
+<br/>
+<span class="pre-in-pp" style="margin-bottom: -1em;">
+  .FAMILY H
+</span>
+or
+<span class="pre-in-pp" style="margin-top: -.5em;">
+  .FAM H
+</span>
+you can access any of those Helvetica fonts simply by passing the
+correct argument to
+<a href="typesetting.html#font">FT</a>.
+from the list, above.
+</p>
+
+<p>
+For example, if you were working in Medium Roman
+(<kbd>.FT&nbsp;R</kbd>) and you needed Medium Condensed Italic for a
+while (assuming it&#8217;s installed), you&#8217;d just type
+<br/>
+<span class="pre-in-pp">
+  .FT CDI
+</span>
+to access the Medium Condensed Italic font from the Helvetica
+family.
+</p>
+
+<p>
+Mom&#8217;s list of font styles doesn&#8217;t pretend to be
+exhaustive, but rather tries to cover the basic weight/shape
+combinations likely to be found in any reasonably complete type
+family.
+</p>
+
+<p>
+The actual extension names are arbitrary and can be used in a
+flexible manner.  For example, if you create a family that has a
+DemiBold font (<b>DB</b>) but no Bold font (<b>B</b>), you might
+find it more convenient to give the DemiBold font the extension
+&#8220;<b>B</b>&#8221;.  Equally, if the family has an ExtraBold
+font, you might find it more convenient to use the extension
+&#8220;<b>HV</b>&#8221; (Heavy).
+</p>
+
+<p id="register-style">
+However, you may, at needs, want to add to mom&#8217;s list of font
+styles.  You can do this by editing the file, om.tmac (typical
+location: <kbd>&lt;prefix&gt;tmac/om.tmac</kbd>).  Near the top,
+you&#8217;ll see lines of the form
+<br/>
+<span class="pre-in-pp">
+  .sty \n[.fp] L       \" Light Roman
+  .sty \n[.fp] LI      \" Light Italic
+  .sty \n[.fp] LCD     \" Light Condensed Roman
+</span>
+Simply add your new font style by imitating what you see, above,
+and plugging in your new font style (having, of course, first
+created the font, correctly named, in groff&#8217;s PostScript font
+directory; see
+<a href="#howto">How to create a PostScript font for use with groff</a>).
+</p>
+
+<p>
+For example, if you already have some fonts from the Univers family
+installed and have called the family <b>UN</b>, you might decide at
+some point to add the Bold Outline font (<b>UNBO</b>).  In which
+case, you&#8217;d add
+<br/>
+<span class="pre-in-pp">
+  .sty \n[.fp] BO      \" Bold Outline
+</span>
+to the <kbd>.sty&nbsp;\n[.fp]&nbsp; &lt;font style&gt;</kbd> list
+in om.tmac.
+</p>
+
+<div class="box-important">
+<p class="tip">
+<span class="important">Important:</span>
+Be careful that any styles you add do not conflict with
+<i>family</i> names that already exist.  &#8220;<b>C</b>&#8221;,
+for example, conflicts with the Courier family (<b>CR</b>,
+<b>CI</b>, <b>CB</b>, <b>CI</b>).  Were you to create a font
+style &#8220;<b>C</b>&#8221;, thinking that <kbd>.FT&nbsp;C</kbd>
+would give you access to font style once you&#8217;d given a
+<kbd>.FAM(ILY)</kbd> directive, you&#8217;d get a nasty surprise:
+your type would come out in Courier Roman!
+</p>
+</div>
+
+<div class="box-tip">
+<p class="tip">
+<span class="note">Note:</span>
+Mom&#8217;s font extensions are not &#8220;user-space&#8221;
+controllable via a macro.  If you&#8217;ve been using groff for
+a long time, and have already rolled your own solution to adding
+PostScript families, fonts, weights, shapes, etc. to groff, you may
+find that mom&#8217;s font extensions conflict with your own scheme.
+Should that be the case, comment out the <kbd>.sty&nbsp;\n[.fp] &lt;font
+style&gt;</kbd> lines found near the top of the <kbd>om.tmac</kbd>
+file.
+</p>
+</div>
+
+<div class="rule-medium"><hr/></div>
+
+<h2 id="howto" class="docs">How to create a PostScript font for use with 
groff</h2>
+
+<p>
+These instructions aren&#8217;t meant to cover all possibilities, merely
+to present one way of making PostScript families/fonts available to
+groff and mom.
+</p>
+
+<p>
+GNU/Linux distributions being what they are, directory locations may
+differ and the presence of some executables can&#8217;t be guaranteed.
+I run a Debian system.  The instructions reflect that.  Users of
+other distros will have to interpret them according to the way their
+distro operates.
+</p>
+
+<h3 class="docs appendices">1. What you need before you start</h3>
+
+<ul style="margin-top: 1em; margin-left: -.5em;">
+  <li>groff, version 1.18 or higher<br/>
+      (Debian package: groff)
+  </li>
+  <li>a full installation of ghostscript and associated tools<br/>
+      (suggested Debian package: ghostscript-x)
+  </li>
+  <li>a library of PostScript fonts<br/>
+      (suggest Debian packages: gsfonts, gsfonts-x11, gsfonts-other)
+  </li>
+  <li>a utility for converting TrueType fonts to Type1 fonts<br/>
+      (Debian package: ttf2pt1)
+  </li>
+  <li>a font manager<br/>
+      (Debian packages: defoma, psfontmgr)
+  </li>
+  <li>perl<br/>
+      (Debian package: perl)
+   </li>
+</ul>
+
+<p style="margin-top: -.5em;">
+A reasonably complete installation of any major GNU/Linux distro
+should already have these on your system, except perhaps for the
+utility to convert TrueType fonts to Type1 fonts (<b>ttf2pt2</b>).
+</p>
+
+<h3 class="docs appendices">2. Initial preparation (you only need do this 
once)</h3>
+
+<ol style="margin-left: -.5em;">
+  <li>If you don&#8217;t already have one, create a directory in
+      your home directory to hold new fonts.  Any directory name
+      will do.  I use <kbd>~/Fonts</kbd>, with subdirectories for
+      <kbd>Type1</kbd>, <kbd>TrueType</kbd> and <kbd>Groff</kbd>
+      fonts. Thus,
+      <br/>
+      <span class="pre-in-pp">
+  ~/Fonts/Type1
+  ~/Fonts/TrueType
+  ~/Fonts/Groff
+      </span>
+  </li>
+  <li id="site-font" style="margin-top: -2em;">Locate the groff
+      directory, <kbd>site-font</kbd>.  The exact location is
+      difficult to predict, owing to differences between distros and
+      whether you&#8217;re using a pre-packaged groff or have built
+      it from source.  Some typical locations are:
+      <br/>
+      <span class="pre-in-pp" style="margin-bottom: -2em;">
+  /usr/share/groff
+  /usr/local/share/groff
+  /etc/groff
+      </span>
+      If you can&#8217;t find the site-font directory, locate
+      groff&#8217;s <kbd>site-tmac</kbd> directory, and, as
+      root, create site-font in the same directory as the
+      one that holds site-tmac.  E.g., if you find site-tmac
+      in <kbd>/usr/share/groff</kbd>, create site-font in
+      <kbd>/usr/share/groff</kbd>.
+  </li>
+  <li style="margin-top: .5em;">Locate the file
+      <kbd>&lt;prefix&gt;/font/devps/generate/textmap</kbd> and
+      symlink it to the name <kbd>textmap</kbd> in the directory
+      that contains your personal collection of PostScript fonts.
+      (See the
+      <a href="#small-note">note</a>,
+      above, for the meaning of <kbd>&lt;prefix&gt;</kbd>).  On my
+      system, at the time of writing, <kbd>&lt;prefix&gt;</kbd>
+      is
+      <br/>
+      <span class="pre-in-pp" style="margin-bottom: -2em;">
+  /usr/local/share/groff/1.20.1/
+      </span>
+      therefore, I symlink it in <kbd>~/Fonts/Type1/</kbd> with
+      <br/>
+      <span class="pre-in-pp">
+ ln -s /usr/local/share/groff/1.20.1/font/devps/generate/textmap textmap
+      </span>
+  </li>
+  <li style="margin-top: -2em;">Locate the file
+      <kbd>&lt;prefix&gt;/font/devps/text.enc</kbd> and
+      symlink it to the name <kbd>text.enc</kbd> in your personal
+      font directory.  On my system, in <kbd>~/Fonts/Type1/</kbd>
+      <br/>
+      <span class="pre-in-pp">
+  ln -s /usr/local/share/groff/1.19.2/font/devps/text.enc text.enc
+      </span>
+  </li>
+  <li style="margin-top: -2em;">Make sure you know which
+      directory holds your PostScript fonts.  You&#8217;ll need the
+      information later.  On a Debian box, a typical location is
+      <kbd>/usr/share/fonts/type1/gsfonts</kbd>
+  </li>
+</ol>
+
+<h3 class="docs appendices">3. Font creation/installation</h3>
+
+<ol style="margin-left: -.5em/">
+  <li>Acquire the font as either Type1 (.pfb) or TrueType (.ttf).</li>
+  <li style="margin-top: .5em;">Place the font in your personal font 
directory; for me,
+      that&#8217;s
+      <br/>
+      <span class="pre-in-pp" style="margin-bottom: -2.5em;">
+  ~/Fonts/Type1
+      </span>
+      or
+      <br/>
+      <span class="pre-in-pp" style="margin-top: -.5em; margin-bottom: -2em;">
+  ~/Fonts/TrueType
+      </span>
+  </li>
+  <li>In your personal font directory, run one of the following.
+  <ul style="margin-left: -1.5em;">
+    <li style="margin-top: .5em;">for <b>Type1 fonts</b>:
+        <br/>
+        <span class="pre-in-pp" style="margin-bottom: -2em;">
+  getafm fontfilename.pfb | gsnd - > fontfilename.afm
+        </span>
+       <i>(This generates something called
+       an .afm (Adobe Font Metrics) file from the .pfb file, which is required 
to
+       create PostScript fonts for groff.)</i>
+      </li>
+      <li style="margin-top: .5em;">for <b>TrueType fonts</b>:
+        <br/>
+        <span class="pre-in-pp" style="margin-bottom: -2em;">
+  ttf2pt1 \-b fontfilename.ttf
+        </span>
+        <i>(For TrueType fonts, this generates a PostScript .pfb file
+         as well as an .afm file.)</i>
+      </li>
+  </ul></li>
+  <li style="margin-top: .5em;">Still in your personal font directory, run
+      <br/>
+      <span class="pre-in-pp" style="margin-bottom: -2em;">
+  afmtodit -e text.enc fontfilename.afm textmap &lt;GROFF_FONTNAME&gt;
+      </span>
+      <p id="groff-font-name" style="margin-top: .25em;">
+      Q: <i>How do I choose a</i> <kbd>GROFF_FONTNAME</kbd><i>?</i>
+      </p>
+
+      <p>
+      A: Start by considering the
+      <a href="definitions.html#family">family</a>
+      to which the font belongs.  If you&#8217;re adding to a family
+      that already exists in groff&#8217;s
+      <kbd>&lt;prefix&gt;/font/devps</kbd> directory, that will be
+      the first part of the font name.  (See
+      <a href="typesetting.html#family">here</a>
+      for a list of families already installed, along with their
+      groff names.)  Add to that name the appropriate weight/style
+      extension, listed
+      <a href="#style-extensions">here</a>.
+      </p>
+      
+      <p>
+      For example, if you&#8217;re adding Helvetica Light Roman,
+      your <kbd>GROFF_FONTNAME</kbd> would be <kbd>HL</kbd>.
+      If you&#8217;re adding Helvetica Light Italic, your
+      <kbd>GROFF_FONTNAME</kbd> would be <kbd>HLI</kbd>.
+      </p>
+
+      <p>
+      If you&#8217;re adding a font not already in groff&#8217;s
+      PostScript families, first choose a meaningful name for the
+      <a href="definitions.html#family">family</a>
+      to which the font belongs.  The name can be anything you like.
+      If, for example, the family is Garamond, you could choose
+      <kbd>GARAMOND</kbd>, <kbd>GARA</kbd>, <kbd>GD</kbd>, or even
+      just plain G as the family name.  Then tack on the appropriate
+      style/weight extension.  Thus, if you were installing Garamond
+      Bold Condensed Italic and had chosen <kbd>GD</kbd> as the
+      family name for Garamond, your <kbd>GROFF_FONTNAME</kbd> would
+      be <kbd>GDBCDI</kbd>.
+      </p>
+
+      <p>
+      In mom, you can then access the Garamond family with
+      <kbd>.FAM GD</kbd>, and the Bold Condensed Italic font wth
+      <kbd>.FT&nbsp;BCDI</kbd>.
+      </p>
+
+      <div class="box-tip">
+      <p class="tip">
+      <span class="note">Note:</span>
+      The family name need not be in upper case, and there&#8217;s
+      no limit to the length of the name.  &#8220;Garamond&#8221;,
+      for example, could be the name you give the Garamond
+      family.  In fact, you might find it preferable, since a) you
+      wouldn&#8217;t have to remember how you&#8217;d named the
+      family, and b) should you be scanning your
+      <a href="#site-font">site-font directory</a>,
+      something like GaramondBCDI will be more meaningful than,
+      say, GDBCDI.
+      </p>
+      </div>
+  </li>
+  <li>Copy or move <kbd>GROFF_FONTNAME</kbd> to your
+      <a href="#site-font">site-font directory</a>,
+      or change to the site-font directory and make a symlink to
+      <kbd>GROFF_FONTNAME</kbd> in your personal directory.
+  </li>
+  <li style="margin-top: .5em;">Copy or move the .pfb file to the directory 
that
+      holds your PostScript fonts, or change to that directory and
+      make a symlink to the .pfb file in your personal directory.
+  </li>
+</ol>
+
+<p>
+Written out in full, adding fonts looks like a lot of work.  It
+isn&#8217;t.  Basically, it&#8217;s just:
+</p>
+<ul style="margin-top: -.5em;">
+  <li>generate an .afm (and .pfb if the font is TrueType)</li>
+  <li>create the groff font</li>
+  <li>put the groff font in<kbd> &lt;prefix&gt;/font/devps</kbd></li>
+  <li>put the .pfb file (the actual font) with your other PostScript fonts</li>
+</ul>
+
+<p>
+After you&#8217;ve done it a couple of times, it all makes sense
+and is really quite easy.  Not to mention that once you understand
+the process, you can write a bash script to automate the process.
+Here&#8217;s an example, which you can adapt to your own needs.
+The script, for installing TrueType fonts, requires an argument (the
+.ttf filename), then prompts for a family directory name (e.g.
+AmericanTypewriter or Futura) and a name to give the groff font
+(see
+<a href="#groff-font-name">here</a>
+for suggestions concerning groff font naming.)  The script assumes a
+<kbd>~/Font</kbd> directory with subdirectories <kbd>Type1</kbd>,
+<kbd>TrueType</kbd> and <kbd>Groff</kbd>.
+</p>
+
+<div class="examples" style="margin-bottom: 0px;">Code:</div> 
+<div class="box-code" style="width: 726px; max-width: 726px; height: 400px; 
overflow: auto;">
+<span class="pre" style="color: #302419;">
+#!/bin/sh
+#
+# Converts .ttf file to .pfb and generates .afm
+# Moves the .afm and .pfb to $HOME/Fonts/Type1
+# Generates a groff font from the .afm file and installs it
+# in $HOME/Fonts/Groff
+# Symlinks the groff font to groff's site-font/devps directory
+# Symlinks the .afm and .pfb to /usr/share/fonts/type1/gsfonts
+#
+
+FONT=`basename $1 .ttf`
+FONTDIR="$HOME/Fonts/TrueType"
+T1_FONTDIR="$HOME/Fonts/Type1"
+GS_FONTDIR="/usr/share/fonts/type1/gsfonts"
+GROFF_SITE_FONTDIR="/usr/local/share/groff/site-font/devps"
+GROFF_FONTS="$HOME/Fonts/Groff"
+TEXTMAP="$T1_FONTDIR/textmap"
+TEXTENC="$T1_FONTDIR/text.enc"
+
+echo -n "Family directory name: "
+read FAMILYDIR
+
+if [ ! -d "$T1_FONTDIR/$FAMILYDIR" ] ; then
+  echo "Creating $FAMILYDIR in $T1_FONTDIR"
+  mkdir $T1_FONTDIR/$FAMILYDIR
+fi
+
+echo -n "Groff name for this font: "
+read FONTNAME
+
+echo "Creating .pfb and .afm files from $FONT.ttf"
+(ttf2pt1 \-b $FONT.ttf)
+
+echo "Moving .afm and .pfb file to $T1_FONTDIR/$FAMILYDIR.."
+mv $FONT.afm $T1_FONTDIR/$FAMILYDIR
+mv $FONT.pfb $T1_FONTDIR/$FAMILYDIR
+
+echo "Changing to $T1_FONTDIR/$FAMILYDIR.."
+cd $T1_FONTDIR/$FAMILYDIR
+
+echo "Creating $FONTNAME.."
+afmtodit -e $TEXTENC $T1_FONTDIR/$FAMILYDIR/$FONT.afm $TEXTMAP $FONTNAME
+mv -i $FONTNAME $GROFF_FONTS
+echo "Linking $FONTNAME in $GROFF_SITE_FONTDIR.."
+sudo ln -s $GROFF_FONTS/$FONTNAME $GROFF_SITE_FONTDIR/$FONTNAME
+
+echo "Linking $FONT.pfb and $FONT.afm in $GS_FONTDIR.."
+cd $GS_FONTDIR
+sudo ln -s $T1_FONTDIR/$FAMILYDIR/$FONT.afm $FONT.afm
+sudo ln -s $T1_FONTDIR/$FAMILYDIR/$FONT.pfb $FONT.pfb
+
+echo "Font installation complete"
+
+exit 0
+</span>
+</div>
+
+<div class="rule-medium" style="margin-top: 2em;"><hr/></div>
+
+<!-- ===================================================================== -->
+
+<h2 id="codenotes" class="docs">Some reflections on mom</h2>
+
+<p>
+If, as Eric Raymond asserts, open source begins with a programmer
+scratching a personal itch, then mom can truly be called open
+source.
+</p>
+
+<p>
+Mom had her origins in a library of groff routines I wrote over
+the years to handle various aspects of typesetting and document
+processing that weren&#8217;t adequately covered by ms, me, mm, and
+friends.  Typically, I&#8217;d use the library to cobble together
+macro sets for new challenges as they came my way.
+</p>
+
+<p>
+As a writer living in a perpetual state of penury, all the computers
+I&#8217;ve ever owned have been hand-me-downs&mdash;several
+generations out-of-date and resource challenged.  Disk space has
+always been an issue, as has processor speed and available RAM.  One
+of the reasons I run GNU/Linux rather than the offering from Redmond
+is that it has helped enormously to get the most out of my poor
+little boxes.
+</p>
+
+<p>
+In Linux-land (all Unix variants, in fact), the choice of
+typesetting systems basically comes down to groff or TeX.  Both are
+wonderful&mdash;monumental achievements if you ask me&mdash;and both
+have their own particular strengths.  However, for people in my
+financial position (and there are millions of us around the globe,
+in both developed and developing countries), TeX and groff have one
+big difference: size.  TeX is huge.  Even its most ardent supporters
+agree it suffers from bloat, on top of being complex and unwieldy to
+manage.  Groff is tiny by comparison, occupying minimal disk space
+and having only a small memory footprint while at the same time
+being flexible and powerful, typographically speaking.  Back in the
+Jurassic Period, I ran it successfully on a 386 with 8 megs of RAM
+and a 250 meg hard disk.
+</p>
+
+<p>
+However, groff has always had a liability: it&#8217;s incredibly geeky.
+Owing to its very long history, it&mdash;and its &#8220;power users&#8221;
+&mdash;seem to have remained stuck in a time warp.  The canonical  macro 
packages
+still look as they did back in those decades when memory was exorbitantly
+expensive and every byte mattered.
+</p>
+
+<p>
+For some time now, groff users and macro writers have had the option
+to use &#8220;long&#8221; names for macros (i.e. longer than two
+letters, the original limit), yet have mostly chosen not to.  With
+long names, it&#8217;s possible to create macro sets that are
+humanly readable and easy to interpret, encouraging development and
+evolution.  What&#8217;s more, the macros themselves need not be
+terse, intimidating, and easily forgotten 1- or 2-letter commands
+inserted in the body of a document.  They can be sensible and
+helpful to everyone, groff newbies and old hands alike.
+</p>
+
+<p>
+Mom&#8217;s macro file, om.tmac, uses long names, aliases, and a
+host of other groff goodies that have become part of the whole
+groff picture under the unflagging guidance of groff&#8217;s
+current maintainer, Werner Lemberg.  The function of nearly
+every macro, number register and string can be infered simply
+from its name.  The file is heavily commented.  A consistent, if
+idiosyncratic, indenting style is used as well, significantly
+improving readability.  Anyone wanting to futz around with
+mom&#8217;s macros should be able to do so with a minimum of head
+scratching.
+</p>
+
+<div class="box-tip">
+<p class="tip">
+<span class="note">Addendum:</span>
+As of version 1.4-a, the main macro file, om.tmac, is now stripped
+of comments when groff is built from sources. om.tmac in the sources
+themselves still contains the comments, as do the tarballs posted on
+mom&#8217;s homepage.
+</p>
+</div>
+
+<div class="rule-medium"><hr/></div>
+
+<!-- ===================================================================== -->
+
+<h2 id="contact" class="docs">Contact the author</h2>
+
+<p>
+If you have any questions or comments about mom,
+suggestions to make, criticisms to offer, or bugs to report, use the
+groff mailing list at
+<a href="mailto:address@hidden";>address@hidden</a>
+(subscription information available
+<a href="http://ffii.org/mailman/listinfo/groff/";>here</a>)
+or contact me, Peter Schaffter,  directly at of the following
+address:
+<br/>
+<span class="pre-in-pp">
+  
&#112;&#101;&#116;&#101;&#114;&#64;&#115;&#99;&#104;&#97;&#102;&#102;&#116;&#101;&#114;&#46;&#99;&#97;
+</span>
+Please include the word &#8220;mom&#8221; or &#8220;groff&#8221; in the
+Subject: line of any message sent to my personal address, or you
+risk the wrath of my implacable spam filters. :)
+</p>
+
+<p>
+If you want to visit mom&#8217;s website, you&#8217;ll find a link
+to it at
+<br/>
+<span class="pre-in-pp">
+  http://www.schaffter.ca
+</span>
+The site contains links to some of my fiction, all of which was
+typeset with mom and groff.
+</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="reserved.html">Next: 
Reserved words</a></td>
+</tr>
+</table>
+
+</div>
+
+<div class="bottom-spacer"><br/></div>
+
+</body>
+</html>
+<!-- vim: fileencoding=utf-8: nomodified: -->

Index: color.html
===================================================================
RCS file: color.html
diff -N color.html
--- /dev/null   1 Jan 1970 00:00:00 -0000
+++ color.html  18 Aug 2010 22:45:35 -0000      1.13
@@ -0,0 +1,506 @@
+<?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 -- Colour</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="graphical.html#top">Next: Graphical 
objects</a></td>
+</tr>
+</table>
+
+<h1 class="docs">Coloured text</h1>
+
+<div style="text-align: center;">
+<a href="#index-color">List of color macros</a>
+</div>
+
+<div class="rule-medium"><hr/></div>
+
+<h2 class="docs">Introduction</h2>
+
+<p>
+Mom&#8217;s support for coloured text is straightforward.  You begin
+by telling mom about the colours you want with
+<kbd><a href="#newcolor">NEWCOLOR</a></kbd>
+or
+<kbd><a href="#xcolor">XCOLOR</a></kbd>.
+Afterward, any time you want text to be coloured, you either colour
+it with an
+<a href="definitions.html#inlines">inline escape</a>
+that contains the colour name (e.g. <kbd>\*[red]</kbd>
+or <kbd>\*[blue]</kbd>) or invoke the macro,
+<kbd><a href="#color">COLOR</a></kbd>,
+with the name of the colour you want.
+</p>
+
+<p id="color-example">
+For example, say you want to have the name &#8220;Jack&#8221; in the
+sentence &#8220;All work and no play makes Jack a dull boy&#8221;
+appear in yellow.  You'd begin by telling mom about the colour,
+yellow.  There are two ways of doing this; see
+<kbd><a href="#newcolor">NEWCOLOR</a></kbd>
+and
+<kbd><a href="#xcolor">XCOLOR</a></kbd>
+for a full explanation of the difference between the two.
+</p>
+
+<p>
+If you use XCOLOR, you'd enter this:
+<br/>
+<span class="pre-in-pp">
+  .XCOLOR yellow
+</span>
+If you use NEWCOLOR, you might enter:
+<br/>
+<span class="pre-in-pp">
+  .NEWCOLOR yellow RGB #FFFF00
+</span>
+</p>
+
+<p id="color-example2" style="margin-top: -1em;">
+After &#8220;defining&#8221; (or &#8220;initializing&#8221;) the
+colour &#8220;yellow&#8221;, you'd colourize the name, Jack, either
+with an inline escape
+<br/>
+<span class="pre-in-pp">
+  All work and no play makes \*[yellow]Jack\*[black] a dull boy.
+</span>
+or with the
+<kbd><a href="#color">COLOR</a></kbd>
+macro
+<br/>
+<span class="pre-in-pp">
+  All work and no play makes
+  .COLOR yellow
+  Jack
+  .COLOR black
+  a dull boy.
+</span>
+Notice, in both examples, that a) you have to set the colour back
+to black after &#8220;Jack&#8221;, and b) you don&#8217;t have to
+define or intialize the colour, black. Mom predefines it for you.
+</p>
+
+<p>
+For information on using colour during
+<a href="docprocessing.html#intro-macros-docprocessing">document 
processing</a>,
+see
+<a href="docprocessing.html#color">Colour support in document processing</a>.
+</p>
+
+<div class="box-tip">
+<p class="tip">
+<span class="note">Note:</span>
+Mom&#8217;s colour support is for text only.  She doesn&#8217;t
+support &#8220;fill&#8221; (or &#8220;background&#8221;) colour for
+solid, enclosed graphical objects (polygons, ellipses) drawn with
+groff&#8217;s <kbd>\D</kbd>
+<a href="definitions.html#inlines">inline escapes</a>,
+although you may give a colour as one of the arguments to
+mom&#8217;s &#8220;box&#8221; and &#8220;circle&#8221; macros,
+<a href="graphical.html#dbx">DBX</a>
+and
+<a href="graphical.html#dcl">DCL</a>
+when the first argument to these macros is <kbd>SOLID</kbd>.
+</p>
+</div>
+
+<div class="box-tip">
+<p class="tip">
+<span class="experts">Experts:</span>
+If you&#8217;re accustomed to using groff&#8217;s
+<kbd>.defcolor</kbd> to define colours, and groff&#8217;s inline
+<kbd>\m[&lt;colorname&gt;]</kbd> to call them, you may continue to
+do so without confusing mom.
+</p>
+</div>
+
+<div class="macro-list-container">
+<h3 id="index-color" class="macro-list">Coloured text macros</h3>
+
+<ul class="macro-list">
+  <li><a href="#newcolor">NEWCOLOR</a></li>
+  <li><a href="#xcolor">XCOLOR</a></li>
+  <li><a href="#color">COLOR</a></li>
+  <li><a href="#color-inline">\*[&lt;colorname&gt;]</a> (inline escape)</li>
+</ul>
+</div>
+
+<div class="rule-medium" style="margin-bottom: 1.5em;"><hr/></div>
+
+<!-- -NEWCOLOR- -->
+
+<div class="macro-id-overline">
+<h3 id="newcolor" class="macro-id">Creating (initializing) a colour with 
NEWCOLOR</h3>
+</div>
+
+<div class="box-macro-args">
+Macro: <b>NEWCOLOR</b> <kbd class="macro-args">&lt;colour name&gt; [&lt;colour 
scheme&gt;] &lt;colour components&gt;</kbd>
+</div>
+
+<p>
+NEWCOLOR lets you create a colour, rather like an artist mixing
+paint on a palette.  The colour isn&#8217;t used immediately;
+NEWCOLOR merely tells mom how to mix the colour when you need it.
+If you haven&#8217;t invoked <kbd>.NEWCOLOR</kbd> (or
+<kbd><a href="#xcolor">.XCOLOR</a></kbd>),
+mom doesn&#8217;t have a clue what you mean when you reference a
+colour (with
+<a href="#color">COLOR</a>
+or
+<a href="#color-inline"><kbd>\*[&lt;color name&gt;]</kbd></a>).
+</p>
+
+<p>
+The first argument to NEWCOLOR is a name for your colour.  It
+can be anything you like&mdash;provided it&#8217;s just one word
+long&mdash;and can be caps, lower case, or any combination of the
+two.
+</p>
+
+<p>
+The second argument, which is entirely optional, is the
+&#8220;colour scheme&#8221; you want mom to use when mixing the
+colour.  Valid arguments are
+<br/>
+<span class="pre-in-pp">
+  RBG   (3 components: red green blue)
+  CYM   (3 components: cyan yellow magenta)
+  CMYK  (4 components: cyan magenta yellow black)
+  GRAY  (1 component)
+</span>
+If you omit the second argument, mom assumes you
+want RGB.
+</p>
+
+<p>
+The final argument is the components of your colour.  This can be
+hexadecimal string starting with a pound sign (<kbd>#</kbd>) (for
+colour values in the 0-255 range) or two pound signs (<kbd>##</kbd>)
+(for colour values in the 0-65535 range), or it can be a series of
+decimal digits, separated by spaces, one digit per component, with
+the argument enclosed in double quotes.  (If this is all gibberish
+to you, see
+<a href="#color-tip">Tips for newbies</a>.)
+</p>
+
+<p>
+Thus, to tell mom about a colour named &#8220;YELLOW&#8221;, you
+could enter one of the following:
+<br/>
+<span class="pre-in-pp">
+  .NEWCOLOR YELLOW #FFFF00         \"or ##FFFFFFFF0000 or "1 1 0"
+  .NEWCOLOR YELLOW RGB #FFFF00     \"or ##FFFFFFFF0000 or "1 1 0"
+  .NEWCOLOR YELLOW CYM #00FF00     \"or ##0000FFFF0000 or "0 1 0"
+  .NEWCOLOR YELLOW CYMK #00FF0000  \"or ##0000FFFF00000000 or "1 1 0"
+</span>
+After you've told mom about a colour, you can then get her to set
+text in that colour either with the
+<a href="definitions.html#inlines">inline escape</a>,
+<a href="#color-inline"><kbd>\*[&lt;colorname&gt;]</kbd></a>,
+or the macro,
+<a href="#color">COLOR</a>.
+(See the
+<a href="#color-example">example</a>,
+above.)
+</p>
+
+<div class="box-tip">
+<p class="tip-top">
+<span class="note">Note:</span>
+The colorname you give to NEWCOLOR may be used with groff&#8217;s
+<kbd>\m[&lt;colorname&gt;]</kbd> inline escape (the <kbd>\m</kbd>
+escape is used to set text and rule colours).  Thus, assuming
+a colorname &#8220;blueblack&#8221; set with NEWCOLOR,
+<kbd>\*[blueblack]</kbd> and <kbd>\m[blueblack]</kbd> are
+equivalent.  Furthermore, the colorname can be given as an argument
+to <b>groff</b>&#8217;s
+<a href="definitions.html#primitives">primitive</a>
+request, <kbd>.gcolor</kbd> (which does the same thing as
+<kbd>\m[&lt;colorname&gt;]</kbd>).
+</p>
+
+<p class="tip-bottom">
+Equally, the colorname may be used with
+<kbd>\M[&lt;colorname&gt;]</kbd> and <kbd>.fcolor</kbd>, which set
+the &#8220;fill&#8221; colour for solid graphical objects.
+</p>
+</div>
+
+<div class="box-tip">
+<p id="color-tip" class="tip-top">
+<span class="tip">Tips for newbies:</span>
+Colour manipulation can be tremendously confusing if you don&#8217;t
+have a background in graphic arts or computing.  My advice, if color
+intimidates you, is to stick to using mom&#8217;s default RGB colour
+scheme, and to fire up a color chooser that gives you the RGB values
+you want for the colour you select.  Plug those values into the
+components argument to NEWCOLOR, and you&#8217;ll get the colour
+you want.  Both the KDE and gnome desktops have colour selectors
+that provide you with the shorter RGB hexadecimal string.  If
+you&#8217;re not running KDE or gnome, the X utility, xcolorsel,
+provides you with a similar functionality, although it only provides
+RGB values for 256 pre-defined colours.  If you use xcolorsel, be
+sure to click the button &#8220;Display format&#8221; and select
+&#8220;8 bit truncated rgb&#8221;.
+</p>
+
+<p class="tip-bottom">
+Alternatively, you can use mom&#8217;s simpler
+<kbd><a href="#xcolor">XCOLOR</a></kbd>
+macro to initialize one of the 256 pre-defined X colours by
+supplying the name of the color as an argument.
+</p>
+</div>
+
+<!-- -XCOLOR- -->
+
+<div class="macro-id-overline">
+<h3 id="xcolor" class="macro-id">Initializing a colour with XCOLOR</h3>
+</div>
+
+<div class="box-macro-args">
+Macro: <b>XCOLOR</b> <kbd class="macro-args">&lt;X colorname&gt; 
[&lt;alias&gt;]</kbd>
+</div>
+
+<p class="requires">
+<kbd style="font-style: normal">&lt;X colorname&gt;</kbd> <i>must be all one 
word, all lower case.</i>
+<br/>
+(See
+<a href="#xcolor-names" style="font-style: normal;">Finding X color names</a>
+for how to get a list of valid colour names.)
+</p>
+
+<p>
+XCOLOR is similar to NEWCOLOR in that it tells mom to initialize a
+colour, but it&#8217;s easier to use.  All you have to do is pass
+it, as an argument, the valid name of one of the 256 pre-defined
+X colours.  The name must be all one word, and, breaking with mom
+policy, it must be entered in lower case.
+</p>
+
+<p>
+For example, if you want to intialize the X colour, coral, all you
+have to do is enter
+<br/>
+<span class="pre-in-pp">
+  .XCOLOR coral
+</span>
+Afterwards
+<br/>
+<span class="pre-in-pp">
+  .COLOR coral
+</span>
+
+will colourize subsequent text coral until you instruct mom to
+return to black, or some other pre-defined, initialized colour.
+(The
+<a href="definitions.html#inlines">inline escape</a>
+<kbd>\*[coral]</kbd> will equally colourize text coral after you've
+initialized the colour with XCOLOR.)
+</p>
+
+<p>
+The downside of XCOLOR is that you can&#8217;t create custom
+colours.  This restriction, however, is mitigated by the fact that
+for many users, 256 colours is more than enough to play around with.
+</p>
+
+<p>
+While some X colours have fanciful names (peachpuff, papayawhip,
+thistle, snow), many are self-explanatory and self-descriptive
+in ordinary colour terms. &#8220;blue&#8221; is pure (rgb)
+blue, &#8220;green&#8221; is pure (rgb) green, and so on.
+Furthermore, for many X colors, there exist four variants, each
+representing increasingly darker shades of the same colour.
+For example, &#8220;blue1&#8221; is a relatively bright blue;
+&#8220;blue2&#8221;, &#8220;blue3&#8221; and &#8220;blue4&#8221; are
+increasingly darker shades.  For that reason, you may find XCOLOR is
+a better choice than NEWCOLOR when it comes to initializing common
+colors.
+</p>
+
+<p>
+The whimsical nature of X colour names sometimes makes for names
+that are long to type in, e.g. &#8220;mediumspringgreen&#8221;.  The
+optional second argument to XCOLOR allows you to come up with more
+convenient name by which to reference the colour.  For example, you
+could enter
+<br/>
+<span class="pre-in-pp">
+  .XCOLOR mediumspringgreen mygreen
+</span>
+or
+<span class="pre-in-pp">
+  .XCOLOR mediumspringgreen MYGREEN
+</span>
+so that whenever you want text mediumspringgreen-ed, you
+can use either <kbd>.COLOR mygreen</kbd> (or
+<kbd>.COLOR MYGREEN</kbd>) or the inline escape
+<kbd>\*[mygreen]</kbd> (or <kbd>\*[MYGREEN]</kbd>.)
+</p>
+
+<h3 id="xcolor-names" class="docs">Finding X color names</h3>
+
+<p>
+There are two ways of finding the names of the pre-defined X
+colours.  One is to consult the file, rgb.txt, included with all
+X11 installations.  The location of the file on a Debian GNU/Linux
+distribution is typically /etc/X11/rgb.txt.  Other distributions and
+other X installations may have the file in another location.  The
+file lists the colour names, but doesn&#8217;t show you what the
+colours actually look like.
+</p>
+
+<p>
+A better way to get the colour names, as well as to see what the
+colours look like, is to fire up a colour chooser (like xcolorsel)
+that both lists the colour names and shows a swatch of the colour
+as well.
+</p>
+
+<p>
+Whichever method you use to find X color names, remember that the
+names, passed as arguments to XCOLOR, must be all one word, all in
+lower case.
+</p>
+
+<div class="box-tip">
+<p class="tip-top">
+<span class="note">Note:</span>
+Both the colorname and the alias you give to XCOLOR may be
+used with groff&#8217;s <kbd>\m[&lt;colorname&gt;]</kbd>
+inline escape (the <kbd>\m</kbd> escape is used to set
+text and rule colours).  Thus, assuming an X-colorname
+&#8220;mediumspringgreen&#8221; set with XCOLOR, and an alias,
+&#8220;mygreen&#8221;, <kbd>\*[mediumspringgreen]</kbd>,
+<kbd>\m[mediumspringgreen]</kbd>, <kbd>\*[mygreen]</kbd> and
+<kbd>\m[mygreen]</kbd> are all equivalent.  Furthermore, both the
+colorname and the alias can be given as an argument to groff&#8217;s
+<a href="definitions.html#primitives">primitive</a>
+request, <kbd>.gcolor</kbd> (which does the same thing as
+<kbd>\m[&lt;colorname&gt;]</kbd>).
+</p>
+
+<p class="tip-bottom">
+The colorname initialized with XCOLOR <i>but not the
+alias</i> may also be used with groff&#8217;s inline escape,
+<kbd>\M[&lt;colorname&gt;]</kbd>, and the corresponding primitive,
+<kbd>.fcolor</kbd>, both of which set the &#8220;fill&#8221; colour
+for solid graphical objects.  If you need a colour initialized with
+XCOLOR for <kbd>\M</kbd> or <kbd>.fcolor</kbd>, you MUST give the
+full colorname; the alias won&#8217;t work.
+</p>
+</div>
+
+<!-- -COLOR- -->
+
+<div class="macro-id-overline">
+<h3 id="color" class="macro-id">Invoking a color</h3>
+</div>
+
+<div class="box-macro-args">
+Macro: <b>COLOR</b> <kbd class="macro-args">&lt;colorname&gt;</kbd>
+</div>
+
+<p id="color-inline" class="requires" style="font-style: normal;">
+Inline: <kbd>\*[&lt;colorname&gt;]</kbd>
+</p>
+
+<p>
+Once you've told mom about a colour (via
+<a href="#newcolor">NEWCOLOR</a>
+or
+<a href="#xcolor">XCOLOR</a>,
+you use either the macro, COLOR, or the
+<a href="definitions.html#inlines">inline escape</a>,
+<kbd>\*[&lt;colorname&gt;]</kbd>, to cause mom to
+set subsequent text in that colour.  See the
+<a href="#color-example2">example</a>,
+above, which shows both in action.
+</p>
+
+<div class="box-tip">
+<p class="tip-top">
+<span class="note">Note:</span>
+You can use the <kbd>\*[&lt;colorname&gt;]</kbd> inline escape in
+any
+<a href="docprocessing.html#top">document processing</a>
+macro that takes a
+<a href="definitions.html#stringargument">string argument</a>.
+However, you must remember to reset the colour at the end of the
+argument (typically with <kbd>\*[black]</kbd>) unless you want all
+subsequent invocations of that particular macro to be colourized.
+</p>
+
+<p>
+Furthermore, if you use <kbd>\*[&lt;colorname&gt;]</kbd> in the
+string argument passed to
+<a href="docelement.html#head">HEAD</a>,
+<a href="docelement.html#subhead">SUBHEAD</a>
+or
+<a href="docelement.html#parahead">PARAHEAD</a>,
+and you've requested that any of these types of heads be numbered,
+the numbers themselves will not be coloured, only the text you
+passed the macro.  If you wish the numbers to be colourized as well,
+you must explicitly tell mom that you wish all of the head(s),
+subhead(s) or parahead(s), including the numbers, colourized by
+invoking the appropriate
+<a href="docelement.html#docelement-control">control macro</a>.
+</p>
+
+<p class="tip-bottom">
+For colorizing underscored text, see
+<a href="goodies.html#underscore-color">Colorizing underscored text</a>
+in the notes at the end of
+<a href="goodies.html#underscore">UNDERSCORE</a>.
+</p>
+</div>
+
+<div class="rule-long"><hr/></div>
+
+<!-- Navigation links -->
+<table style="width: 100%; margin-top: 12px;">
+<tr>
+  <td style="width: 33%;"><a href="toc.html">Back to Table of Contents</a></td>
+  <td style="width: 33%; text-align: center;"><a href="#top">Top</a></td>
+  <td style="width: 33%; text-align: right;"><a 
href="graphical.html#top">Next: Graphical objects</a></td>
+</tr>
+</table>
+
+</div>
+
+<div class="bottom-spacer"><br/></div>
+
+</body>
+</html>
+<!-- vim: fileencoding=utf-8: nomodified: -->

Index: cover.html
===================================================================
RCS file: cover.html
diff -N cover.html
--- /dev/null   1 Jan 1970 00:00:00 -0000
+++ cover.html  18 Aug 2010 22:45:35 -0000      1.15
@@ -0,0 +1,633 @@
+<?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, creating cover pages</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="tables-of-contents.html#top">Next: 
Tables of contents</a></td>
+</tr>
+</table>
+
+<h1 class="docs">Creating cover pages</h1>
+
+<div style="width: 63%; margin: auto;">
+<ul class="no-enumerator">
+  <li><a href="#cover-intro">Introduction to cover pages</a>
+  <ul style="margin-left: -.5em; list-style-type: disc;">
+    <li><a href="#important-note">Important note</a></li>
+    <li><a href="#desc">Description of cover pages</a></li>
+    <li><a href="#pagination">Headers/footers/pagination and cover 
pages</a></li>
+    <li><a href="#design">Designing your own cover pages</a></li>
+  </ul></li>
+  <li><a href="#index-covers">Cover and document cover macros</a>
+  <ul style="margin-left: -.5em; list-style-type: disc;">
+    <li><a href="#cover">COVER / DOC_COVER</a>
+    <ul style="margin-left: -.5em; list-style-type: circle;">
+      <li><a href="#required-arg">The required argument</a></li>
+      <li><a href="#chapter">How the CHAPTER argument and friends work</a></li>
+      <li><a href="#optional-args">The optional arguments</a></li>
+      <li><a href="#doctype">What the DOCTYPE argument means</a></li>
+      <li><a href="#blankpage">What the BLANKPAGE argument means</a></li>
+    </ul></li>
+  </ul></li>
+  <li><a href="#on-off">Enabling/disabling automatic generation of cover 
pages</a></li>
+  <li><a href="#cover-control">Control macros for covers and doc 
covers</a></li>
+</ul>
+</div>
+
+<div class="rule-medium"><hr/></div>
+
+<h2 id="cover-intro" class="docs">Introduction to cover pages</h2>
+
+<p>
+Though identical in treatment, mom provides two kinds of cover
+pages: section cover pages (which I shall refer to simply as
+cover pages) and document cover pages (&#8221;doc
+covers&#8221;).
+</p>
+
+<p>
+A doc cover is what you&#8217;d most likely use at the start of a
+collated document, where you might want the name of the complete
+document, the author(s) and the copyright line to appear.  Another
+place you might use a doc cover is for a novel, where you want the
+title of the novel, not the chapter title or chapter number, as the
+first cover page.
+</p>
+
+<p>
+A cover is what you&#8217;d use for pages that separate sections
+of a collated document, i.e. title pages.  A cover page (but not a
+doc cover) in a collated document could, for example, simply read:
+&#8221;PART 1&#8221;.
+</p>
+
+<p>
+In non-collated documents (say, an essay) you can use either a cover
+or doc cover to generate the cover sheet.
+</p>
+
+<p>
+In addition, nothing prevents you from generating both a doc cover
+and a cover for every document in a collated document.  Or you can
+selectively disable the automatic generation of either doc covers or
+covers in a collated document on-the-fly.
+</p>
+
+<div id="important-note" class="box-important">
+<p class="tip">
+<span class="important">Important note:</span>
+Automatic generation of covers or doc covers after the first one(s)
+only takes place if you are working with collated documents.  Mom
+provides no mechanism for saying &#8221;print a section cover
+here even though I'm still working on the same (non-collated)
+document.&#8221;
+</p>
+</div>
+
+<h3 id="desc" class="docs">Description of cover pages</h3>
+
+<p>
+By default, mom typesets covers and doc covers  identically to
+<a href="definitions.html#docheader">docheaders</a>
+(see
+<a href="docprocessing.html#docheader-control">How to change the look of 
docheaders</a>
+for a description of what a docheader looks like).  The only
+differences are
+</p>
+<ul style="margin-top: -.5em;  margin-bottom: -.5em;">
+  <li>the position on the page where the information is output</li>
+  <li>the (optional) addition of copyright and miscellaneous information</li>
+  <li>there&#8217;s no running text underneath</li>
+</ul>
+
+<p>
+You tell mom what you want to appear on cover pages through the
+arguments you pass to
+<a href="#cover">COVER</a>
+and/or
+<a href="#cover">DOC_COVER</a>.
+Provided you have already given mom the appropriate reference macros
+(e.g.
+<a href="docprocessing.html#title">TITLE</a>
+or
+<a href="docprocessing.html#author">AUTHOR</a>),
+she will output covers and doc covers identically to how she
+would output docheaders containing the same information.
+</p>
+
+<p>
+By default, mom starts covers and doc covers one-third of the way
+down the page.  This can be changed through the use of the control
+macros COVER_ADVANCE / DOC_COVER_ADVANCE.
+</p>
+
+<p>
+If you request copyright information (and have already given mom the
+reference macro,
+<a href="docprocessing.html#copyright">COPYRIGHT</a>),
+she sets it, by default, in a smaller
+<a href="definitions.html#ps">point size</a>
+in the bottom right hand corner of the cover or doc cover.  The
+position, as well as all of the standard typesetting parameters, can be
+altered via control macros.
+</p>
+
+<p>
+Similarly, if you request miscellaneous information (and have
+already given mom the reference macro,
+<a href="docprocessing.html#misc">MISC</a>),
+she sets it, by default, in a smaller point size in the bottom left
+hand corner of the cover or doc cover.  As with the copyright, the
+position and type specs can be altered via control macros.
+</p>
+
+<h3 id="pagination" class="docs">Headers/footers/pagination and cover 
pages</h3>
+
+<p>
+Mom does not set any
+<a href="definitions.html#header">headers</a>
+or
+<a href="definitions.html#footer">footers</a>
+on cover pages.  Neither does she set any page numbers.  From
+the point of view of pagination, covers and doc covers are by
+default considered &#8221;null&#8221; pages.  If you wish them to
+be included in the pagination scheme (even though no page numbers
+appear), you must tell mom that&#8217;s what you want with the
+macros DOC_COVERS_COUNT_PAGES and/or COVERS_COUNT_PAGES.
+</p>
+
+<h3 id="design" class="docs">Designing your own cover pages</h3>
+
+<p>
+Finally, if you want to design your own cover page(s), you can
+always typeset them (using the
+<a href="typesetting.html#macros-typesetting">typesetting macros</a>),
+invoke
+<a href="typesetting.html#newpage"><kbd>.NEWPAGE</kbd></a>,
+set up your document (see
+<a href="docprocessing.html#docprocessing-tut">Tutorial &ndash; Setting up a 
mom document</a>),
+and lastly invoke
+<a href="docprocessing.html#start"><kbd>.START</kbd></a>.
+The cover page, and any typesetting commands on it, will have no
+effect on mom&#8217;s processing of the document after you invoke
+<kbd><a href="docprocessing.html#START">.START</a></kbd>.
+</p>
+
+<div class="macro-list-container">
+<h3 id="index-covers" class="macro-list">Cover and document cover macros</h3>
+<ul class="macro-list">
+  <li><a href="#cover">COVER and DOC_COVER</a>
+  <ul style="margin-left: -.5em; list-style-type: disc;">
+    <li><a href="#required-and-optional-args">Required and optional 
arguments</a></li>
+  </ul></li>
+  <li><a href="#on-off">Enabling/disabling automatic generation of cover 
pages</a>
+  <ul style="margin-left: -.5em; list-style-type: disc;">
+    <li><a href="#covers">COVERS</a></li>
+    <li><a href="#doc-covers">DOC_COVERS</a></li>
+  </ul></li>
+  <li><a href="#cover-control">Control macros for covers and doc 
covers</a></li>
+</ul>
+</div>
+
+<!-- -COVER- -->
+
+<div class="macro-id-overline">
+<h3 id="cover" class="macro-id">COVER and DOC_COVER</h3>
+</div>
+
+<div class="box-macro-args">
+Macro: <b>COVER</b> <kbd class="macro-args">(see required and optional 
arguments, below)</kbd>
+</div>
+
+<div id="doc-cover" class="box-macro-args" style="margin-top: 1em;">
+Macro: <b>DOC_COVER</b> <kbd class="macro-args">(see required and optional 
arguments, below)</kbd>
+</div>
+
+<div id="required-and-optional-args" style="margin-top: 1em; padding-bottom: 
3px; white-space: nowrap; overflow: auto;">
+<b><a href="#required-arg">Required argument:</a></b> <kbd 
class="macro-args">TITLE | DOCTITLE | COVERTITLE | CHAPTER | CHAPTER_TITLE | 
CHAPTER+TITLE</kbd>
+</div>
+
+<div style="margin-top: .5em; padding-bottom: 3px; white-space: nowrap; 
overflow: auto;">
+<b><a href="#optional-args">Optional arguments:</a></b> <kbd 
class="macro-args">[ SUBTITLE AUTHOR DOCTYPE COPYRIGHT MISC BLANKPAGE ]</kbd>
+</div>
+
+<div class="box-tip">
+<p class="tip">
+<span class="note">Note:</span>
+These macros should be placed in the
+&#8220;style-sheet&#8221; section of your document setup (see
+<a href="docprocessing.html#docprocessing-tut">Tutorial &ndash; Setting up a 
mom document</a>),
+i.e. after PRINTSTYLE (and/or DOCTYPE and/or COPYSTYLE), but before START.
+</p>
+</div>
+
+<p style="margin-top: -.25em;">
+COVER and DOC_COVER behave identically.  The reason mom provides
+two macros for cover page generation is so that you can have two
+different kinds of covers with different information on each.
+</p>
+
+<p>
+Imagine, for a moment, you&#8217;ve written a document comprised of
+three sections.  When you
+<a href="rectoverso.html#collate">COLLATE</a>
+the document for output, you could use DOC_COVER to generate a cover
+page that contained the name of the entire document, your (the
+author&#8217;s) name, and perhaps the copyright date.  Subsequently,
+you could use COVER, after each <kbd>.COLLATE</kbd> but before each
+<kbd><a href="docprocessing.html#start">.START</a></kbd>,
+to generate a cover page (or cover &#8221;sheet&#8221;, if you
+prefer) containing just the name of the section.
+</p>
+
+<h4 id="required-arg" class="docs" style="margin-top: -.5em;">The required 
argument</h4>
+
+<p>
+Both COVER and DOC_COVER, whenever invoked, require a first
+argument, as listed above.  This first argument will become the
+first bit of information mom prints on the cover or doc cover (i.e.
+the title).
+</p>
+
+<p>
+In order for the information to appear, you must, of course, have
+given mom the appropriate
+<a href="docprocessing.html#reference-macros">reference macro</a>.
+A list of first arguments with their equivalent reference macros follows.
+</p>
+
+<dl style="margin-top: -.5em;">
+  <dt class="no-italic"><kbd>TITLE</kbd></dt>
+  <dd>
+  &ndash; means the argument you gave to <a 
href="docprocessing.html#title">TITLE</a>
+  </dd>
+  <dt class="no-italic"><kbd>DOCTITLE</kbd></dt>
+  <dd>
+  &ndash; means the argument you gave to <a 
href="docprocessing.html#doc-title">DOCTITLE</a>
+  </dd>
+  <dt class="no-italic"><kbd>COVERTITLE</kbd></dt>
+  <dd>
+  &ndash; means the argument you gave to <a 
href="docprocessing.html#covertitle">COVERTITLE</a>
+  or
+  <a href="docprocessing.html#doc-covertitle">DOC_COVERTITLE</a>
+  </dd>
+  <dt class="no-italic"><kbd>CHAPTER, CHAPTER_TITLE, CHAPTER+TITLE</kbd></dt>
+  <dd>
+  &ndash; see below, <i>How the CHAPTER argument and friends work</i>
+  </dd>
+</dl>
+
+<h5 id="chapter" class="docs" style="margin-top: -.5em; text-transform: 
none;">How the CHAPTER argument and friends work</h5>
+
+<p>
+<span style="display: block; margin-bottom: -1.25em; font-weight: 
bold;">&bull;&nbsp;CHAPTER</span>
+<br/>
+The <kbd>CHAPTER</kbd> argument will print the
+<a href="docprocessing.html#chapter-string">CHAPTER_STRING</a>
+concatenated with the chapter number you gave to
+<a href="docprocessing.html#chapter">CHAPTER</a>.
+For example, assuming a vanilla setup for your chapter:
+<br/>
+<span class="pre-in-pp" style="color: #64614a;">
+  .CHAPTER 1
+  .CHAPTER_TITLE "The Bonny Blue Yonder"
+  <span style="color: #941614;">.COVER CHAPTER</span>  \"(or <span 
style="color: #941614;">.DOC_COVER CHAPTER</span>)
+</span>
+will print (and only print)
+<br/>
+<span class="pre-in-pp">
+  Chapter 1
+</span>
+</p>
+
+<p style="margin-top: -1em;">
+<span style="display: block; margin-bottom: -1.25em; font-weight: 
bold;">&bull;&nbsp;CHAPTER_TITLE</span>
+<br/>
+The <kbd>CHAPTER_TITLE</kbd> argument will print the chapter title
+you gave to
+<a href="docprocessing.html#chapter-title">CHAPTER_TITLE</a>.
+For example, assuming a vanilla setup for your chapter:
+<br/>
+<span class="pre-in-pp" style="color: #64614a;">
+  .CHAPTER 1
+  .CHAPTER_TITLE "The Bonny Blue Yonder"
+  <span style="color: #941614;">.COVER CHAPTER_TITLE</span>  \"(or <span 
style="color: #941614;">.DOC_COVER CHAPTER_TITLE</span>)
+</span>
+will print (and only print)
+<br/>
+<span class="pre-in-pp">
+    The Bonny Blue Yonder
+</span>
+</p>
+
+<p style="margin-top: -1em;">
+<span style="display: block; margin-bottom: -1.25em; font-weight: 
bold;">&bull;&nbsp;CHAPTER+TITLE</span>
+<br/>
+The <kbd>CHAPTER+TITLE</kbd> argument will print both the
+concatenated chapter string+number and the chapter title.  For
+example, assuming a vanilla setup for your chapter:
+<br/>
+<span class="pre-in-pp" style="color: #64614a;">
+  .CHAPTER 1
+  .CHAPTER_TITLE "The Bonny Blue Yonder"
+  <span style="color: #941614;">.COVER CHAPTER+TITLE</span> \"(or <span 
style="color: #941614;">.DOC_COVER CHAPTER+TITLE</span>)
+</span>
+will print
+<br/>
+<span class="pre-in-pp">
+        Chapter 1
+  The Bonny Blue Yonder
+</span>
+</p>
+
+<h4 id="optional-args" class="docs" style="margin-top: -1em;">The optional 
arguments</h4>
+
+<p>
+The remainder of the arguments to COVER and
+DOC_COVER are optional.  They refer specifically to
+the information you gave the
+<a href="docprocessing.html#reference-macros">reference macros</a>
+bearing the same name as the arguments.
+</p>
+
+<p>
+You may enter as many or as few as you would like to see on your
+cover or doc cover.  The only hitch is&mdash;pay attention,
+class&mdash;they must be entered in the order given above.
+For example, if you want <kbd>TITLE</kbd>, <kbd>AUTHOR</kbd>,
+<kbd>COPYRIGHT</kbd> and <kbd>MISC</kbd>
+<br/>
+<span class="pre-in-pp">
+    .COVER TITLE AUTHOR COPYRIGHT MISC
+</span>
+
+is correct, while
+<br/>
+<span class="pre-in-pp">
+    .COVER TITLE AUTHOR MISC COPYRIGHT
+</span>
+
+is not.
+</p>
+
+<h5 id="doctype" class="docs" style="text-transform: none; margin-top: 
-.5em;">What the DOCTYPE argument means</h5>
+
+<p>
+When you pass COVER or DOC_COVER
+the argument, <kbd>DOCTYPE</kbd>, it refers to the argument you gave
+to
+<a href="docprocessing.html#doctype">DOCTYPE</a>&nbsp;<kbd>NAMED</kbd>.
+For example, if, in your
+<a href="docprocessing.html#docstyle-macros">docstyle macros</a>
+you gave a
+<br/>
+<span class="pre-in-pp">
+    .DOCTYPE NAMED "Abstract"
+</span>
+the argument, <kbd>DOCTYPE</kbd>, given to the COVER or DOC_COVER
+macros, would mean that you wanted the word, Abstract, to appear on
+the cover or doc cover underneath the title and/or author(s), just
+as it would in the
+<a href="docprocessing.html#docheader">docheader</a>.
+</p>
+
+<h5 id="blankpage" class="docs" style="text-transform: none; margin-top: 
-.5em;">What the BLANKPAGE argument means</h5>
+
+<p>
+If the final argument to DOC_COVER or COVER is <kbd>BLANKPAGE</kbd>,
+mom will insert a blank page after the doc cover or cover.  This is
+particularly useful if you intend to print your document two-sided,
+since, in two-sided printing, there may be instances where you do
+not want text on the reverse side of cover or title pages.
+</p>
+
+<p>
+If you enable DOC_COVERS_COUNT_PAGES and/or COVERS_COUNT_PAGES, the
+blank page will be taken into account in the pagination scheme,
+though no page number appears on it.  Otherwise, blank pages are
+invisible to mom's pagination.
+</p>
+
+<!-- -ENABLING/DISABLING- -->
+
+<div class="macro-id-overline">
+<h3 id="on-off" class="macro-id">Enabling/disabling automatic generation of 
cover pages</h3>
+</div>
+
+<div id="covers" class="box-macro-args">
+Macro: <b>COVERS</b> <kbd class="macro-args">&lt;toggle&gt;</kbd>
+</div>
+
+<div id="doc-covers" class="box-macro-args" style="margin-top: 1em;">
+Macro: <b>DOC_COVERS</b> <kbd class="macro-args">&lt;toggle&gt;</kbd>
+</div>
+
+<p>
+By default, if you give mom a
+<a href="#cover">COVER</a>
+or
+<a href="#doc-cover">DOC_COVER</a>
+directive, she will print the cover or doc cover.  In a document
+that contains sections, articles or chapters formerly treated as
+&#8221;one-off&#8217;s&#8221; but now being
+<a href="rectoverso.html#collate-intro">collated</a>,
+such behaviour may not be desirable.
+</p>
+
+<p>
+Mom lets you selectively enable or disable the generation of covers
+and/or doc covers with the toggle macros, COVERS and DOC_COVERS.
+Because they&#8217;re toggle macros, simply invoking them by
+themselves enables automatic cover or doc cover generation, while
+invoking them with any argument at all (<kbd>OFF, QUIT, X</kbd>,
+etc) disables cover or doc cover generation.
+</p>
+
+<div class="box-tip">
+<p class="tip">
+<span class="note">Note:</span>
+You must place these macros prior to any instance of
+<a href="docprocessing.html#start">START</a>.
+Since they&#8217;re &#8221;on&#8221; by default, there&#8217;s no
+need to use them if you want covers.  However, if you don&#8217;t,
+especially in the kind of scenario described above, the best place
+to put them (most likely with an <kbd>OFF, NO, X</kbd>, etc. argument),
+is immediately after the first invocation of START.  By doing so,
+you ensure they meet the requirement of preceding all subsequent
+instances of START.
+</p>
+</div>
+
+<div class="rule-short"><hr/></div>
+
+<h2 id="cover-control" class="macro-group">Control macros for covers and doc 
covers</h2>
+
+<p>
+The default typographic appearance of the items on a cover or doc
+cover is identical to that of the items in a
+<a href="definitions.html#docheader">docheader</a>.
+(See
+<a href="docprocessing.html#docheader-desc">Docheader description</a>
+for a description of the defaults.)
+</p>
+
+<p>
+<a href="docprocessing.html#copyright">COPYRIGHT</a>
+and
+<a href="docprocessing.html#misc">MISC</a>,
+which do not appear in docheaders, have the following default
+characteristics:
+</p>
+<ul style="margin-top: -.5em; margin-bottom: -.5em;">
+  <li>the COPYRIGHT line is set in the bottom right hand corner
+      of the page, 2
+      <a href="definitions.html#ps">point sizes</a>
+      smaller than the size of
+      <a href="definitions.html#running">running text</a>
+  </li>
+  <li>MISC lines are set in the bottom left hand
+      corner of the page, in the same family, font and point size
+      as the copyright line.
+  </li>
+</ul>
+
+<p>
+The defaults for the entirety of covers and doc covers, and all the
+elements thereon, can be changed with control macros whose defaults
+and arguments are identical to the corresponding control macros
+governing docheaders.  The only difference is the name by which you
+invoke them.
+</p>
+
+<p>
+A complete list of cover and doc cover control macros follows.
+Please refer to
+<a href="docprocessing.html#index-docheader-control">docheader control</a>
+in order to get the defaults and any special instructions for usage.
+</p>
+
+<h3 id="index-cover-control" class="docs" style="margin-bottom: .25em;">Cover 
/ doc cover control macros and defaults</h3>
+
+<div class="defaults-container" style="padding-bottom: 8px;">
+
+<span class="pre defaults">
+COVER_ADVANCE  DOC_COVER_ADVANCE -+
+COVER_FAMILY   DOC_COVER_FAMILY   | like
+COVER_LEAD     DOC_COVER_LEAD     | DOCHEADER_&lt;spec&gt;
+COVER_QUAD     DOC_COVER_QUAD    -+
+
+COVER_TITLE_FAMILY  DOC_COVER_TITLE_FAMILY -+
+COVER_TITLE_FONT    DOC_COVER_TITLE_FONT    | like
+COVER_TITLE_COLOR   DOC_COVER_TITLE_COLOR   | TITLE_&lt;spec&gt;
+COVER_TITLE_SIZE    DOC_COVER_TITLE_SIZE   -+
+
+COVER_CHAPTER_TITLE_FAMILY  DOC_COVER_CHAPTER_TITLE_FAMILY -+
+COVER_CHAPTER_TITLE_FONT    DOC_COVER_CHAPTER_TITLE_FONT    | like
+COVER_CHAPTER_TITLE_COLOR   DOC_COVER_CHAPTER_TITLE_COLOR   | 
CHAPTER_TITLE_&lt;spec&gt;
+COVER_CHAPTER_TITLE_SIZE    DOC_COVER_CHAPTER_TITLE_SIZE   -+
+
+COVER_SUBTITLE_FAMILY  DOC_COVER_SUBTITLE_FAMILY -+
+COVER_SUBTITLE_FONT    DOC_COVER_SUBTITLE_FONT    | like
+COVER_SUBTITLE_COLOR   DOC_COVER_SUBTITLE_COLOR   | SUBTITLE_&lt;spec&gt;
+COVER_SUBTITLE_SIZE    DOC_COVER_AUTHOR_SIZE     -+
+
+COVER_ATTRIBUTE_COLOR  DOC_COVER_ATTRIBUTE_COLOR - like ATTRIBUTE_COLOR
+ - the macro, ATTRIBUTE_STRING, controls the attribution string
+   for both docheaders and cover pages; cover pages have no
+   separate ATTRIBUTE_STRING macro
+
+COVER_AUTHOR_FAMILY  DOC_COVER_AUTHOR_FAMILY -+
+COVER_AUTHOR_FONT    DOC_COVER_AUTHOR_FONT    | like
+COVER_AUTHOR_COLOR   DOC_COVER_AUTHOR_COLOR   | AUTHOR_&lt;spec&gt;
+COVER_AUTHOR_SIZE    DOC_COVER_AUTHOR_SIZE   -+
+
+COVER_DOCTYPE_FAMILY  DOC_COVER_DOCTYPE_FAMILY -+
+COVER_DOCTYPE_FONT    DOC_COVER_DOCTYPE_FONT    | like
+COVER_DOCTYPE_COLOR   DOC_COVER_DOCTYPE_COLOR   | DOCTYPE_&lt;spec&gt;
+COVER_DOCTYPE_SIZE    DOC_COVER_DOCTYPE_SIZE   -+
+
+COVER_COPYRIGHT_FAMILY  DOC_COVER_COPYRIGHT_FAMILY -+
+COVER_COPYRIGHT_FONT    DOC_COVER_COPYRIGHT_FONT    |
+COVER_COPYRIGHT_COLOR   DOC_COVER_COPYRIGHT_COLOR   | like any of the above
+COVER_COPYRIGHT_SIZE    DOC_COVER_COPYRIGHT_SIZE    |
+COVER_COPYRIGHT_QUAD    DOC_COVER_COPYRIGHT_QUAD   -+
+  - copyright quad sets both the position on the page and the quad
+    direction and can be either L (left) or R (right); default is right
+
+COVER_MISC_FAMILY  DOC_COVER_MISC_FAMILY -+
+COVER_MISC_FONT    DOC_COVER_MISC_FONT    |
+COVER_MISC_COLOR   DOC_COVER_MISC_COLOR   | like any of the above
+COVER_MISC_SIZE    DOC_COVER_MISC_SIZE    |
+COVER_MISC_QUAD    DOC_COVER_MISC_QUAD   -+
+  - misc quad sets both the position on the page and the quad
+    direction and can be either L (left) or R (right); default is left
+
+COVER_UNDERLINE    DOC_COVER_UNDERLINE - like DOCTYPE_UNDERLINE
+  - cover underline controls underlining of the argument given to
+    DOCTYPE NAMED "&lt;name&gt;" only
+
+COVER_COUNTS_PAGES DOC_COVER_COUNTS_PAGES
+ - whether to consider cover pages in the pagination scheme; the
+   default is to ignore them
+ - see Note
+</span>
+</div>
+
+<p style="margin-top: -2em;">
+<b>Note:</b>
+<br/>
+COVER_COUNTS_PAGES and DOC_COVER_COUNTS_PAGES are toggle macros,
+hence invoking them by themselves means that mom will consider
+covers and doc covers in the pagination scheme; invoking them with
+any argument (<kbd>OFF, NO, X</kbd>, etc.) means they are ignored.
+The default is to ignore them.
+</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="tables-of-contents.html">Next: Tables of contents</a></td>
+</tr>
+</table>
+
+</div>
+
+<div class="bottom-spacer"><br/></div>
+
+</body>
+</html>
+<!-- vim: fileencoding=utf-8: nomodified: -->

Index: definitions.html
===================================================================
RCS file: definitions.html
diff -N definitions.html
--- /dev/null   1 Jan 1970 00:00:00 -0000
+++ definitions.html    18 Aug 2010 22:45:35 -0000      1.17
@@ -0,0 +1,976 @@
+<?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 -- Definitions and Terms</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="using.html#top">Next: Using 
mom</a></td>
+  </tr>
+  </table>
+
+<h1 id="terms" class="docs">Definitions of terms used in this manual</h1>
+
+<p>
+I use a number of typesetting-specific and groff-specific terms
+throughout this documentation, as well as a few terms that apply
+to mom herself.  To make life easier, I&#8217;ll explain
+them here.  Refer back to this section should you encounter a word
+or concept you&#8217;re not familiar with.
+</p>
+
+<div class="rule-short" style="margin-top: 18px; margin-bottom: 
28px;"><hr/></div>
+
+<div class="col-1-definitions">
+  <table class="definitions">
+    <tr><th class="definitions">Typesetting terms</th></tr>
+    <tr> 
+      <td>
+        <a href="#ascender">Ascender</a><br/>
+        <a href="#baseline">Baseline</a><br/>
+        <a href="#ballotbox">Ballot box</a><br/>
+        <a href="#bullet">Bullet</a><br/>
+        <a href="#capheight">Cap-height</a><br/>
+        <a href="#descender">Descender</a><br/>
+        <a href="#discretionaryhyphen">Discretionary hyphen</a><br/>
+        <a href="#dropcap">Drop cap</a><br/>
+        <a href="#em">Em/en</a><br/>
+        <a href="#family">Family</a><br/>
+        <a href="#figurespace">Figure space/Digit space</a><br/>
+        <a href="#fixedwidthfont">Fixed width font</a><br/>
+        <a href="#fixedwidthspace">Fixed width space</a><br/>
+        <a href="#font">Font</a><br/>
+        <a href="#force">Force justify</a><br/>
+        <a href="#just">Justify/justification</a><br/>
+        <a href="#gutter">Gutter</a><br/>
+        <a href="#kern">Kerning</a><br/>
+        <a href="#kernunit">Kern Units</a><br/>
+        <a href="#leading">Lead/leading</a><br/>
+        <a href="#leader">Leaders</a><br/>
+        <a href="#ligatures">Ligature</a><br/>
+        <a href="#picaspoints">Picas/Points</a><br/>
+        <a href="#ps">Point Size</a><br/>
+        <a href="#quad">Quad</a><br/>
+        <a href="#rag">Rag</a><br/>
+        <a href="#shape">Shape</a><br/>
+        <a href="#solid">Solid/set solid</a><br/>
+        <a href="#trackkerning">Track kerning/Line kerning</a><br/>
+        <a href="#unbreakablespace">Unbreakable space</a><br/>
+        <a href="#weight">Weight</a><br/>
+        <a href="#wordspace">Word space</a><br/>
+        <a href="#xheight">x-height</a><br/>
+      </td>
+    </tr>
+  </table>
+</div>
+
+<div class="col-2-definitions">
+  <table class="definitions">
+    <tr><th class="definitions">Groff terms</th></tr>
+    <tr> 
+      <td>
+        <a href="#alias">Alias</a><br/>
+        <a href="#arguments">Arguments</a><br/>
+        <a href="#commentlines">Comment lines</a><br/>
+        <a href="#controllines">Control Lines</a><br/>
+        <a href="#filled">Filled lines</a><br/>
+        <a href="#inlines">Inline escapes</a><br/>
+        <a href="#inputline">Input line</a><br/>
+        <a href="#macros">Macros</a><br/>
+        <a href="#units">Machine units</a><br/>
+        <a href="#numericargument">Numeric argument</a><br/>
+        <a href="#outputline">Output line</a><br/>
+        <a href="#primitives">Primitives</a><br/>
+        <a href="#stringargument">String Argument</a><br/>
+        <a href="#unitofmeasure">Unit of measure</a><br/>
+        <a href="#zerowidthcharacter">Zero-width character</a><br/>
+      </td>
+    </tr>
+  </table>
+</div>
+
+<div class="col-3-definitions">
+  <table class="definitions">
+    <tr><th class="definitions">Mom terms</th></tr>
+    <tr>
+      <td>
+        <a href="#blockquote">Blockquote</a><br/>
+        <a href="#controlmacro">Control macro</a><br/>
+        <a href="#docheader">Docheader</a><br/>
+        <a href="#epigraph">Epigraph</a><br/>
+        <a href="#footer">Footer</a><br/>
+        <a href="#head">Head</a><br/>
+        <a href="#header">Header</a><br/>
+        <a href="#linebreak">Linebreak</a><br/>
+        <a href="#parahead">Paragraph head</a><br/>
+        <a href="#quote">Quote</a><br/>
+        <a href="#running">Running text</a><br/>
+        <a href="#subhead">Subhead</a><br/>
+        <a href="#toggle">Toggle</a><br/>
+      </td>
+    </tr>
+  </table>
+</div>
+
+<h3 id="typesetting-terms" class="docs">Typesetting terms</h3>
+<dl>
+  <dt id="ascender">Ascender</dt>
+  <dd>
+  The portion of a letter that extends above the bowl.  For
+  example, the letters a, c, and e have no ascenders.  The letters
+  b, d, and h do.
+  </dd>
+
+  <dt id="baseline">Baseline</dt>
+  <dd>
+  The imaginary line on which the bottoms of capital letters and
+  the bowls of lower case letters rest.
+  </dd>
+  
+  <dt id="ballotbox">Ballot box</dt>
+  <dd>
+  An unfilled square, usually
+  <a href="#capheight">cap-height</a>
+  in size, typically placed beside items in a checklist.
+  </dd>
+  
+  <dt id="bullet">Bullet</dt>
+  <dd>
+  A small, filled circle typically found beside items or points in
+  a list.
+  </dd>
+  
+  <dt id="capheight">Cap-height</dt>
+  <dd>
+  The height of the tallest capital letter in a given
+  <a href="#font">font</a>
+  at the current
+  <a href="#ps">point size</a>.
+  </dd>
+  
+  <dt id="descender">Descender</dt>
+  <dd>
+  The portion of a letter that extends beneath the
+  <a href="#baseline">baseline</a>
+  (j, q, y are letters with descenders).
+  </dd>
+  
+  <dt id="discretionaryhyphen">Discretionary hyphen</dt>
+  <dd>
+  A symbol inserted between two syllables of a word that indicates
+  to a typesetting program the valid hyphenation points in the
+  word.  Normally, if hyphenation is turned on, groff knows where
+  to hyphenate words.  However, hyphenation being what it is
+  (in English, at any rate), groff doesn&#8217;t always get it right.
+  Discretionary hyphens make sure it does.  In the event that the
+  word doesn&#8217;t need to be hyphenated at all, groff leaves them
+  alone.  In groff, the discretionary hyphen is entered with
+  
+  <span class="pre" style="margin-bottom: -2em;">
+  \%  (backslash followed by a percent)
+  </span>
+  </dd>
+  
+  <dt id="dropcap">Drop cap</dt>
+  <dd>
+  A large, usually upper-case letter that introduces the first
+  paragraph of a document or section thereof.  The top of the
+  drop cap usually lines up with the top of the first line of the
+  paragraph, and typically &#8220;drops&#8221; several lines lower.
+  Text adjacent to the drop cap is indented to the right of the
+  letter until the bottom of the drop cap is reached, at which
+  point text reverts to the left margin.
+  </dd>
+  
+  <dt id="em">Em/en</dt>
+  <dd>
+  An em is a relative measurement equal to the width of the
+  letter M at a given
+  <a href="#ps">point size</a>
+  in a given
+  <a href="#font">font</a>.
+  Since most Ms are designed square, an em is usually (but
+  sometimes erroneously) considered to be the same size as the
+  current point size (i.e. if the point size of the type is 12,
+  one em equals 12 points).  An en is equal to the width of a
+  letter N (historically 2/3 of an em, although groff treats an en
+  as 1/2 of an em).  Typically, ems and ens are used to measure
+  indents, or to define the length of dashes (long hyphens).
+  </dd>
+  
+  <dt id="family">Family</dt>
+  <dd>
+  The collective name by which a collection of
+  <a href="#font">fonts</a>
+  are known, e.g.  Helvetica, Times Roman, Garamond.
+  </dd>
+  
+  <dt id="figurespace">Figure space/Digit space</dt>
+  <dd>
+  A
+  <a href="#fixedwidthspace">fixed width space</a>
+  that has the width of one digit.  Used for aligning numerals in,
+  say, columns or numbered lists.  In groff, the figure space is
+  entered with
+  
+  <span class="pre" style="margin-bottom: -2em;">
+  \0  (backslash followed by a zero)
+  </span>
+  </dd>
+  
+  <dt id="fixedwidthfont">Fixed width font</dt>
+  <dd>
+  A family or font in which every character occupies exactly the
+  same amount of vertical space on the line.  Courier is the
+  best-known, if not the most elegant, fixed-width font.
+  </dd>
+
+  <dt id="fixedwidthspace">Fixed width space</dt>
+  <dd>
+  Equal to
+  <a href="#wordspace">word space</a>,
+  but does not expand or contract when text is
+  <a href="#just">justified</a>.
+  In groff, fixed width space is entered with
+  
+  <span class="pre" style="margin-bottom: -2em;">
+  \&lt;space&gt; (backslash followed by hitting the spacebar)
+  </span>
+  </dd>
+  
+  <dt id="font">Font</dt>
+  <dd>
+  The specific
+  <a href="#weight">weight</a>
+  and
+  <a href="#shape">shape</a>
+  of type within a
+  <a href="#family">family</a>,
+  e.g. light, medium, bold (which are weights), and roman, italic,
+  condensed (which are shapes).  By default, groff knows of four
+  fonts within its default set of families: R (medium roman), I
+  (medium italic), B (bold roman) and BI (bold italic).
+  Mom considerably extends this very basic list.
+  </dd>
+  
+  <dt id="force">Force justify</dt>
+  <dd>
+  Sometimes, in
+  <a href="#just">justified</a>
+  text, a line needs to be broken short of the right margin.
+  Force justifying means telling a typesetting program (like
+  groff) that you want the line broken early AND that you want the
+  line&#8217;s word spacing stretched to force the line flush with the
+  right margin.
+  </dd>
+  
+  <dt id="gutter">Gutter</dt>
+  <dd>
+  The vertical whitespace separating columns of type.
+  </dd>
+  
+  <dt id="just">Justify/justification</dt>
+  <dd>
+  Lines of type are justified when they&#8217;re flush at both the left
+  and right margins.  Justification is the act of making both
+  margins flush.  Some people use the terms "left justified" and
+  "right justified" to mean type where only the left (or right)
+  margins align.  I don&#8217;t.  See
+  <a href="#quad">quad</a>.
+  </dd>
+  
+  <dt id="kern">Kerning</dt>
+  <dd>
+  Moving pairs of letters closer together to remove excess
+  whitespace between them.  In the days before phototypesetting,
+  type was set from small, rectangular blocks of wood or metal,
+  each block having exactly one letter.  Because the edge of
+  each block determined the edge of each letter, certain letter
+  combinations (TA, for example) didn&#8217;t fit together well and had
+  to be mortised by hand to bring them visually closer.  Modern
+  typesetting systems usually take care of kerning automatically,
+  but they&#8217;re far from perfect.  Professional typesetters still
+  devote a lot of time to fitting letters and punctuation together
+  properly.
+  </dd>
+  
+  <dt id="kernunit">Kern Units</dt>
+  <dd>
+  A relative distance equal to 1/36 of the current
+  <a href="#ps">point size</a>.
+  Used between individual letters
+  for
+  <a href="#kern">kerning</a>.
+  Different typesetting systems use different values (1/54 is
+  popular), and sometimes call kern units by a different name.
+  </dd>
+  
+  <dt id="leading">Lead/leading</dt>
+  <dd>
+  The distance from the
+  <a href="#baseline">baseline</a>
+  of one line of type to the line of type immediately beneath
+  it.  Pronounced "ledding."  Also called line spacing.  Usually
+  measured in
+  <a href="#picaspoints">points</a>.
+  
+  <p>
+  <em>In case you&#8217;re interested...</em> In previous centuries,
+  lines of type were separated by thin strips of&mdash;you guessed
+  it&mdash;lead.  Lines of type that had no lead between them were said
+  to be &#8220;set solid.&#8221; Once you began separating them with
+  strips of lead, they were said to be &#8220;leaded&#8221;, and the
+  spacing was expressed in terms of the number of
+  <a href="#picaspoints">points</a>
+  of lead.  For this reason, &#8220;leading&#8221; and &#8220;line
+  spacing&#8221; aren&#8217;t, historically speaking, synonymous.
+  If type was set 10 on 12, for example, the leading was 2
+  points, not 12.  Nowadays, however, the two terms are used
+  interchangeably to mean the distance from baseline to baseline.
+  </p>
+
+  </dd>
+  
+  <dt id="leader">Leaders</dt>
+  <dd>
+  Single characters used to fill lines, usually to their end.  So
+  called because they &#8220;lead&#8221; the eye from one element
+  of the page to another.  For example, in the following (brief)
+  Table of Contents, the periods (dots) are leaders.
+  
+  <span class="pre" style="margin-bottom: -2em;">
+  Foreword............... 2
+  Chapter 1.............. 5
+  Chapter 2.............. 38
+  Chapter 3.............. 60
+  </span>
+  </dd>
+  
+  <dt id="ligatures">Ligature</dt>
+  <dd>
+  Ligatures are letters joined together to form a single
+  character.  The commonest are fi, fl, ff, ffi and ffl.  Others
+  are ae and oe.  Occasionally, one sees an st ligature, but this
+  is archaic and quite rare.
+  </dd>
+  
+  <dt id="picaspoints">Picas/Points</dt>
+  <dd>
+  There are twelve points in a pica, and six picas in an inch
+  (hence 72 points to the inch).  In the same way that gem-dealers
+  have always used their own system of measurement for weight
+  (carats), typographers have always used their own system of
+  measurement for type.
+  </dd>
+  
+  <dt id="ps">Point Size</dt>
+  <dd>
+  The nominal size of type, measured in
+  <a href="#picaspoints">points</a>
+  from the bottom of the longest
+  <a href="#descender">descender</a>
+  to the top of the highest
+  <a href="#ascender">ascender</a>.
+  In reality, type is always fractionally smaller than its point
+  size.
+  </dd>
+  
+  <dt id="quad">Quad</dt>
+  <dd>
+  When only one margin of type is flush, lines of type are quadded
+  in the direction of the flush margin.  Therefore, quad left
+  means the left margin is flush, the right isn&#8217;t.  Quad right
+  means the right margin is flush, the left isn&#8217;t.  Quad centre
+  means neither the left nor the right margin is flush; rather,
+  lines of type are quadded on both sides so that type appears
+  centred on the page.
+  </dd>
+  
+  <dt id="rag">Rag</dt>
+  <dd>
+  Describes a margin that isn&#8217;t flush.  Rag right means the right
+  margin isn&#8217;t flush.  Rag left means the left margin isn&#8217;t flush.
+  The expression "flush left/rag right" is sometimes used to
+  describe type that is
+  <a href="#quad">quadded</a>
+  left.
+  </dd>
+  
+  <dt id="shape">Shape</dt>
+  <dd>
+  The degree of slant and/or the width of characters.
+  (Technically speaking, this is not a proper typesetting term;
+  however, it may help clarify some concepts presented in these
+  documents.)
+  
+  <p>
+  Some typical shapes are:
+  </p>
+
+  <ul style="margin-top: -.5em; margin-bottom: -.5em">
+      <li>&#8220;Roman&#8221;, which has no slant, and has letterforms of
+          average width</li>
+      <li>&#8220;Italic&#8221;, which is slanted, and has letterforms
+          of average width</li>
+      <li>&#8220;Condensed&#8221;, which has no slant, but has
+          letterforms narrower than the average represented by Roman</li>
+      <li>&#8220;Condensed Italic&#8221;, which is slanted, with letterforms 
narrower
+          than average</li>
+  </ul>
+
+  <p>
+  The term
+  <a href="#font">font</a>,
+  as it is used in these documents, refers to a combination of
+  <a href="#weight">weight</a>
+  and shape.
+  </p>
+
+  </dd>
+  
+  <dt id="solid">Solid/set solid</dt>
+  <dd>
+  When no
+  <a href="#leading">lead</a>
+  is added between lines of type (i.e. the
+  <a href="#ps">point size</a>
+  and linespacing are the same), the lines are said to be &#8220;set
+  solid.&#8221;
+  </dd>
+  
+  <dt id="trackkerning">Track kerning/Line kerning</dt>
+  <dd>
+  Sometimes, it&#8217;s advantageous to increase or decrease the amount
+  of space between every letter in a line by an equal (usually
+  small) amount, in order to fit more (or fewer) characters on the
+  line.  The correct term is letter spacing, but track kerning and
+  line kerning (and sometimes, just "kerning") have come to mean
+  the same thing.
+  </dd>
+  
+  <dt id="unbreakablespace">Unbreakable space</dt>
+  <dd>
+  Equal to
+  <a href="#wordspace">word space</a>,
+  however words separated by an unbreakable space will always be
+  kept together on the same line.  Expands and contracts like word
+  space.  Useful for proper names, which one should, whenever
+  possible, avoid splitting onto two lines.  In groff, unbreakable
+  space is entered with
+  
+  <span class="pre" style="margin-bottom: -2em;">
+   \~  (backslash followed by a tilde)
+  </span>
+  </dd>
+  
+  <dt id="weight">Weight</dt>
+  <dd>
+  The thickness of the strokes of letterforms.  Medium and Book
+  have average thicknesses and are the weights used for most
+  of the text in books, magazines, newspapers, etc.  Light has
+  strokes slightly thinner than Medium or Book, but is still
+  acceptable for most text.  Semibold, Bold, Heavy and Black all
+  have strokes of increasing thickness, making them suitable for
+  heads, subheads, headlines and the like.
+  </dd>
+  
+  <dt id="wordspace">Word space</dt>
+  <dd>
+  The amount of whitespace between words.  When text is
+  <a href="#just">justified</a>,
+  word space expands or contracts to make the margins flush.
+  </dd>
+  
+  <dt id="xheight">x-height</dt>
+  <dd>
+  The height of a lower case letter x in a given font at a given
+  point size.  Generally used to mean the average height of the
+  bowl of lower case letters.
+  </dd>
+</dl>
+
+<h3 id="groff-terms" class="docs">Groff terms</h3>
+
+<dl>
+  <dt id="alias">Alias</dt>
+  <dd>
+  A
+  <a href="#macros">macro</a>
+  invoked by a name different from its &#8220;official&#8221;
+  name.  For example, the official name of the macro to change
+  <a href="#family">family</a>
+  is <kbd>FAMILY</kbd>.  Its alias is <kbd>FAM</kbd>.
+  Aliases may be created for any macro (via the
+  <a href="goodies.html#alias"><kbd>ALIAS</kbd></a>
+  macro) provided the alias uses a name not already taken by the
+  mom macros or one of the groff
+  <a href="#primitives">primitives</a>.
+  For a complete list of words or names you must not use, see the
+  <a href="reserved.html#reserved">list of reserved words</a>.
+  </dd>
+  
+  <dt id="arguments">Arguments</dt>
+  <dd>
+  Parameters or information needed by a
+  <a href="#macros">macro</a>
+  to do its job.  For example, in the macro
+  
+  <span class="pre" style="margin-bottom: -2em;">
+  .PT_SIZE 12
+  </span>
+  
+  <kbd>12</kbd> is the argument.  In the macro
+  
+  <span class="pre" style="margin-bottom: -2em;">
+  .QUAD LEFT
+  </span>
+  
+  <kbd>LEFT</kbd> is the argument.  Arguments are separated from
+  macros by spaces.  Some macros require several arguments; each
+  is separated by a space.
+  </dd>
+  
+  <dt id="commentlines">Comment Lines</dt>
+  <dd>
+  <a href="#inputline">Input lines</a>
+  introduced with the comment character
+  
+  <span class="pre" style="margin-bottom: -2em;">
+  \#  (backslash followed by the pound sign)
+  </span>
+  
+  When processing output, groff silently ignores everything on a
+  line that begins with the comment character.
+  </dd>
+  
+  <dt id="controllines">Control Lines</dt>
+  <dd>
+  Instructions to groff that appear on a line by themselves, which
+  means that &#8220;control lines&#8221; are either
+  <a href="#macros">macros</a>
+  or groff
+  <a href="#primitives">primitives</a>.
+  Control lines begin with a period or, occasionally, an apostrophe.
+  </dd>
+  
+  <dt id="filled">Filled lines/fill mode</dt>
+  <dd>
+  Automatic
+  <a href="#just">justification</a>
+  or
+  <a href="#quad">quadding</a>.
+  In fill mode, the ends of lines as they appear in your text
+  editor are ignored.  Instead, words from adjoining
+  <a href="#inputline">input lines</a>
+  are added one at a time to the output line until no more words
+  fit.  Then, depending whether text is to be
+  <a href="#just">justified</a>
+  or
+  <a href="#quad">quadded</a>
+  (left, right, or centre), and depending on whether automatic
+  hyphenation is turned on, groff attempts to hyphenate the last
+  word, or, barring that, spreads and breaks the line (when
+  justification is turned on) or breaks and quads the line (when
+  quadding is turned on).
+  
+  <p>
+  Nofill mode (non-filled text) means that groff respects the ends
+  of lines exactly as they appear in your text editor.
+  </p>
+
+  </dd>
+  
+  <dt id="inlines">Inline escapes</dt>
+  <dd>
+  Instructions issued to groff that appear as part of an
+  <a href="#inputline">input line</a>
+  (as opposed to
+  <a href="#macros">macros</a>,
+  which must appear on a line by themselves).  Inline escapes are
+  always introduced by the backslash character.  For example,
+  
+  <span class="pre" style="margin-bottom: -2em;">
+  A line of text with the word T\*[BU 2]oronto in it
+  </span>
+  
+  contains the inline escape <kbd>\*[BU 2]</kbd> (which means
+  &#8220;move the letter &#8216;o&#8217; 2
+  <a href="#kernunit">kern units</a>
+  closer to the letter &#8216;T&#8217;&#8221;).
+  
+  <p style="margin-bottom: -2em;">
+  Mom&#8217;s inline escapes always take the form
+  <kbd>\*[&lt;ESCAPE&gt;]</kbd>, where <kbd>ESCAPE</kbd> is
+  composed of capital letters, sometimes followed immediately by a
+  digit, sometimes followed by a space and a
+  <a href="#numericargument">numeric argument</a>.
+  Groff&#8217;s escapes begin with the backslash
+  character but typically have no star and are in lower case.  For
+  example, the mom escapes to move forward 6
+  points on a line are either
+  
+  <span class="pre" style="margin-bottom: -2em;">
+  \*[FP6]&nbsp;&nbsp;or&nbsp;&nbsp;\*[FWD 6p]
+  </span>
+  
+  while the groff escape for the same thing is
+  
+  <span class="pre" style="margin-bottom: -2em;">
+  \h&#8217;6p&#8217;
+  </span>
+  </p>
+
+  </dd>
+  
+  <dt id="inputline" style="margin-top: -1em;">Input line</dt>
+  <dd>
+  A line of text as it appears in your text editor.
+  </dd>
+  
+  <dt id="macros">Macros</dt>
+  <dd>
+  Instructions embedded in a document that determine how groff
+  processes the text for output. mom&#8217;s macros
+  always begin with a period, on a line by themselves, and must
+  be typed in capital letters.  Typically, macros contain complex
+  commands issued to groff&mdash;behind the scenes&mdash;via
+  groff
+  <a href="#primitives">primitives</a>.
+  </dd>
+  
+  <dt id="units">Machine units</dt>
+  <dd>
+  A machine unit is 1/1000 of a
+  <a href="#picaspoints">point</a>
+  when the groff device is ps. (&#8220;ps&#8221; means
+  &#8220;PostScript&#8221;&mdash;the default device for
+  which groff prepares output, and the device for which
+  mom was specifically designed.)
+  </dd>
+  
+  <dt id="numericargument">Numeric argument</dt>
+  <dd>
+  An
+  <a href="#arguments">argument</a>
+  that has the form of a digit.  Numeric arguments can be built
+  out of arithmetic expressions using +, -, *, and / for plus,
+  minus, times, and divided-by respectively.  If a numeric
+  argument requires a
+  <a href="#unitofmeasure">unit of measure</a>,
+  a unit of measure must be appended to <em>every</em> digit in
+  the argument.  For example:
+  
+  <span class="pre" style="margin-bottom: -2em;">
+  .ALD 1i-1v
+  </span>
+  
+  <div class="box-important" style="margin-right: 2.5em;">
+    <p class="tip">
+    <span class="important">IMPORTANT:</span> groff does not
+    respect the order of operations, but rather evaluates
+    arithmetic expressions from left to right.  Parentheses must
+    be used to circumvent this peculiarity.  Not to worry, though.
+    The likelihood of more than just the occasional plus or minus
+    sign when using mom&#8217;s macros is slim.
+    </p>
+  </div>
+  </dd>
+  
+  <dt id="outputline">Output line</dt>
+  <dd>
+  A line of text as it appears in output copy.
+  </dd>
+  
+  <dt id="primitives">Primitives</dt>
+  <dd>
+  The lowercase instructions, introduced with a period, that groff
+  uses as its native command language, and out of which macros
+  are built.  The majority of groff&#8217;s primitive requests are two
+  letters long.
+  </dd>
+  
+  <dt id="stringargument">String Argument</dt>
+  <dd>
+  Technically, any
+  <a href="#arguments">argument</a>
+  that is not numeric.  In this documentation, string argument
+  means an argument that requires the user to input text.  For
+  example, in the
+  <a href="#macros">macro</a>
+  
+  <span class="pre" style="margin-bottom: -2em;">
+  .TITLE "My Pulitzer Novel"
+  </span>
+  
+  <kbd>"My Pulitzer Novel"</kbd> is a string argument.
+  
+  <p>
+  Because string arguments must be enclosed by double-quotes, you
+  can&#8217;t use double-quotes as part of the string argument.  If you
+  need double-quotes to be part of a string argument, use the
+  <a href="#inlines">inline escapes</a>
+  <kbd>\(lq</kbd> and <kbd>\(rq</kbd> (leftquote and
+  rightquote respectively) in place of the double-quote character
+  (<kbd>"</kbd>).
+  </p>
+
+  </dd>
+  
+  <dt id="unitofmeasure">Unit of measure</dt>
+  <dd>
+  The single letter after a
+  <a href="#numericargument">numeric argument</a>
+  that tells mom what measurement scale the
+  argument should use.  Common valid units are:
+  
+  <span class="pre" style="margin-bottom: -2em;">
+  i (inches)
+  p (points)
+  P (Picas)
+  c (centimetres)
+  m (ems)
+  n (ens)
+  u (machine units)
+  v (the current leading [line space])
+  </span>
+
+  <p style="margin-top: -1em;">
+  Units of measure must come immediately after the numeric
+  argument (i.e. with no space between the argument and the unit
+  of measure), like this:
+  
+  <span class="pre" style="margin-bottom: -2em;">
+  .ALD 2v
+  .LL  39P
+  .IL  1i
+  </span>
+  
+  The above example advances 2 line spaces and sets the line
+  length to 39 picas with a left indent of 1 inch.
+  </p>
+  
+  <div class="box-important" style="margin-right: 2.5em;">
+    <p class="tip">
+    <span class="important">IMPORTANT:</span>
+    Most mom macros that set the size or measure of something must
+    be given a unit of measure since most of the macros do not have
+    default units of measure.  There are a couple of exceptions,
+    the most notable of which are <kbd>PT_SIZE</kbd> and
+    <kbd class="bold">LS</kbd>.  Both use
+    <a href="#picaspoints">points</a>
+    as the default unit of measure, which means you don&#8217;t have to
+    append &#8220;p&#8221; to their argument.
+    </p>
+  </div>
+  
+  <p>
+  You can enter decimal values for any unit of measure.  Different
+  units may be combined by adding them together (e.g. 1.5i+2m,
+  which gives a measure of 1-1/2 inches plus 2 ems).
+  </p>
+  
+  <div class="box-tip" style="margin-right: 2.5em;">
+    <p class="tip">
+    <span class="note">Note:</span>
+    a pica is composed of 12 points, therefore 12.5 picas is 12
+    picas and 6 points, not 12 picas and 5 points.  If you want 12
+    picas and 5 points, you have to enter the measure as 12P+5p.
+    </p>
+  </div>
+
+  </dd>
+  
+  <dt id="zerowidthcharacter">Zero-width character</dt>
+  <dd>
+  The
+  <a href="#inlines">inline escape</a>
+  that allows you to print a literal period, apostrophe and, if
+  <a href="#outputline">output lines</a>
+  are
+  <a href="#filled">filled</a>,
+  a space that falls at the beginning of an
+  <a href="#inputline">input line</a>.
+  It looks like this:
+  
+  <span class="pre" style="margin-bottom: -2em;">
+  \&amp; (backslash followed by an ampersand)
+  </span>
+  
+  Normally, groff interprets a period (or an apostrophe) at the
+  beginning of an input line as meaning that what follows is a
+  <a href="#controllines">control line</a>.
+  In fill modes, groff treats a space at the beginning of an input
+  line as meaning &#8220;start a new line and put a space at the
+  beginning of it.&#8221; If you want groff to interpret periods
+  and apostrophes at the beginning of input lines literally (i.e.
+  print them), or spaces at the beginning of input lines as just
+  garden variety word spaces, you must start the line with the
+  zero-width character.
+  </dd>
+</dl>
+
+<h3 id="mom-terms" class="docs">Mom terms</h3>
+<dl>
+  <dt id="blockquote">Blockquote</dt>
+  <dd>
+  Cited material other than
+  <a href="#quote">quotes</a>.
+  Typically set at a smaller point size than paragraph text,
+  indented from the left and right margins.  Blockquotes are
+  <a href="#filled">filled</a>.
+  </dd>
+  
+  <dt id="controlmacro">Control macro</dt>
+  <dd>
+  Macros used in
+  <a href="docprocessing.html#docprocessing">document processing</a>
+  to control/alter the appearance of document elements (e.g.
+  heads, quotes, footnotes,
+  <a href="#header">headers</a>,
+  etc.).
+  </dd>
+  
+  <dt id="docheader">Document header/docheader</dt>
+  <dd>
+  Document information (title, subtitle, author, etc) output at
+  the top of page one.
+  </dd>
+  
+  <dt id="epigraph">Epigraph</dt>
+  <dd>
+  A short, usually cited passage that appears at the beginning of
+  a chapter, story, or other document.
+  </dd>
+  
+  <dt id="footer">Footer/page footer</dt>
+  <dd>
+  Document information (frequently author and title) output in
+  the bottom margin of pages <em>after</em> page one.  Not to be
+  confused with footnotes, which are considered part of
+  <a href="#running">running text</a>.
+  </dd>
+  
+  <dt id="head">Head</dt>
+  <dd>
+  A title that introduces a major section of a document.
+  </dd>
+  
+  <dt id="header">Header/page header</dt>
+  <dd>
+  Document information (frequently author and title) output in the
+  top margin of pages <em>after</em> page one.
+  
+  <div class="box-tip" style="margin-right: 2.5em;">
+    <p class="tip">
+    <span class="note">Note:</span> In terms of content and style,
+    headers and
+    <a href="#footer">footers</a>
+    are the same; they differ only in their placement on the page.
+    In most places in this documentation, references to the content
+    or style of headers applies equally to footers.
+    </p>
+  </div>
+
+  </dd>
+  
+  <dt id="linebreak">Linebreak/author linebreak</dt>
+  <dd>
+  A gap in the vertical flow of
+  <a href="#running">running text</a>,
+  frequently set off by typographic symbols such as asterisks or
+  daggers.  Used to indicate a shift in the content of a document
+  (e.g. a scene change in a short story).  Also commonly called a
+  scene break or a section break.
+  </dd>
+  
+  <dt id="parahead">Paragraph head</dt>
+  <dd>
+  A title joined to the body of a paragraph; hierarchically one
+  level beneath
+  <a href="#subhead">subheads</a>.
+  </dd>
+  
+  <dt id="quote">Quote</dt>
+  <dd>
+  A quote, to mom, is a line-for-line setting
+  of quoted material (e.g. poetry, song lyrics, or a snippet of
+  programming code).  You don&#8217;t have to use
+  <a href="typesetting.html#br"><kbd>BR</kbd></a>
+  with quotes.
+  </dd>
+  
+  <dt id="running">Running text</dt>
+  <dd>
+  In a document formatted with mom, running
+  text means text that forms the body of the document, including
+  elements such as heads and subheads.
+  <a href="#docheader">Docheaders</a>,
+  <a href="#header">headers</a>,
+  <a href="#footer">footers</a>
+  and page numbers are not part of running text.
+  </dd>
+  
+  <dt id="subhead">Subhead</dt>
+  <dd>
+  A title used to introduce secondary sections of a document;
+  hierarchically one level beneath sections introduced by
+  <a href="#head">heads</a>.
+  </dd>
+  
+  <dt id="toggle">Toggle</dt>
+  <dd>
+  A macro or tag that, when invoked without an argument, begins
+  something or turns a feature on, and, when invoked with ANY
+  argument, ends something or turns a feature off.  See
+  <a href="intro.html#toggle-example">Example 3</a>
+  of the section
+  <a href="intro.html#macro-args">How to read macro arguments</a>.
+  </dd>
+</dl>
+
+<div class="rule-long"><hr/></div>
+
+<!-- Navigation links -->
+<table style="width: 100%;">
+  <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="using.html#top">Next: 
Using mom</a></td>
+</tr>
+</table>
+
+</div>
+
+<div class="bottom-spacer"><br/></div>
+
+</body>
+</html>
+<!-- vim: fileencoding=utf-8: nomodified:-->

Index: docelement.html
===================================================================
RCS file: docelement.html
diff -N docelement.html
--- /dev/null   1 Jan 1970 00:00:00 -0000
+++ docelement.html     18 Aug 2010 22:45:35 -0000      1.36
@@ -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 &ndash; 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&#8217;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: &#8220;This is a paragraph; this is a subhead; this is a
+footnote,&#8221; and so on.
+</p>
+
+<p>
+The list of tags is actually quite small&mdash;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&#8217;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&#8217;s style affects all subsequent invocations
+of the tag.
+</p>
+
+<h2 id="docelement-control" class="docs">Control macros &ndash; 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&mdash;should you wish.  At
+a bare minimum, all tags have macros to change mom&#8217;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&#8217;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&#8217;s control macro, or toggling a particular
+feature of the tag on or off.
+</p>
+
+<p>
+And don&#8217;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&#8217;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>+&lt;n&gt;</kbd> or <kbd>-&lt;n&gt;</kbd> where
+&lt;n&gt; 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&#8217;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 &#8220;initialized&#8221;) 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&#8217;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&#8217;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&#8217;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&#8217;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 &#8220;blocks.&#8221;
+</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">&lt;toggle&gt; | [ BLOCK ]</kbd>
+</div>
+
+<p>
+EPIGRAPH is a toggle, used like this:
+<br/>
+<span class="pre-in-pp">
+  .EPIGRAPH
+  &lt;text of epigraph&gt;
+  .EPIGRAPH OFF
+</span>
+<kbd>OFF</kbd>, above, could be anything&mdash;say, <kbd>Q</kbd> or
+<kbd>X</kbd>&mdash;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&mdash;including the first&mdash;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 &#8220;block&#8221; 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&#8217;s one of most powerful, yet simplest to use&mdash;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&#8217;t recommend using this macro with
+<a href="typesetting.html#printstyle">PRINTSTYLE TYPEWRITE</a>.)
+</p>
+
+<p>
+Note that mom does not provide &#8220;orphan control&#8221; 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&#8217;s simplistic orphan control will
+break these one-liners&mdash;if they fall at the bottom of the
+page&mdash;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&#8217;re writing and editing
+drafts of a document (particularly stories and chapters) is a
+text file cluttered up with <kbd>.PP</kbd>&#8217;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&#8217;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&#8217;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&#8217;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>\*[&lt;colorname&gt;]</kbd></a>,
+<i>after</i> <kbd>.PP</kbd>.  The colour must be one pre-defined (or
+&#8220;initialized&#8221;) 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&#8217;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
+  &lt;first paragraph&gt;
+  .HEAD "Monty Python"
+  .SUBHEAD "The Origins of Spam"
+  .PP
+  &lt;second paragraph&gt;
+</span>
+the first paragraph will be blue, the head and subhead will be in
+the document&#8217;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
+&#8220;initialized&#8221;) 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&#8217;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&#8217;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&#8217;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&#8217;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&#8217;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&mdash;or, in this documentation, just
+&#8220;heads&#8221;&mdash;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&#8217;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">&quot;&lt;text of head&gt;&quot; [ 
&quot;&lt;2nd line&gt;&quot; [ &quot;&lt;3rd line&gt;&quot; ... ] ]</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&#8217;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&#8217;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&#8217;re unhappy with
+mom&#8217;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&#8217;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 &lt;weight&gt; [&lt;gap&gt;]
+</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&#8217;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&#8217;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&#8217;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&#8217;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&#8217;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 &#8220;1&#8221;,
+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 &#8220;6&#8221; and subsequent heads will
+be numbered in ascending order from &#8220;6&#8221;.
+</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>&#8217;s
+or
+<a href="inlines.html#inline-vertical-groff">groff</a>&#8217;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&#8217;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&#8217;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">&quot;&lt;text of 
subhead&gt;&quot; [ &quot;&lt;2nd line&gt;&quot; [ &quot;&lt;3rd line&gt;&quot; 
... ] ]</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&#8217;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&#8217;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 &#8220;1&#8221;,
+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 &#8220;4&#8221; and subsequent
+subheads will be numbered in ascending order from &#8220;4&#8221;.
+</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
+&#8220;first&#8221; 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&#8217;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&#8217;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
+  &lt;text&gt;
+</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">&quot;&lt;text of 
parahead&gt;&quot;</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&#8217;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&#8217;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&#8217;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&#8217;s relative to
+PP_INDENT.)
+</p>
+
+<div class="box-tip">
+<p class="tip">
+<span class="note">Note:</span>
+Paragraph heads in &#8220;first paragraphs&#8221;, 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&#8217;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&#8217;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&#8217;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&#8217;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 &#8220;1&#8221;,
+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 &#8220;7&#8221; and subsequent
+paraheads will be numbered in ascending order from &#8220;7&#8221;.
+</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">&lt;none&gt; | 
&lt;chapter number as digit&gt; | &lt;anything&gt;</kbd>
+</div>
+
+<p>
+If you&#8217;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&#8217;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&#8217;t
+(say you&#8217;ve called your chapter &#8220;One&#8221; instead of
+&#8220;1&#8221;), 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&#8217;ve (temporarily) turned off the prefixing of chapter
+numbers.  Thus, even if you call your chapters &#8220;One&#8221;,
+&#8220;Two&#8221;, &#8220;Three&#8221; instead of &#8220;1&#8221;,
+&#8220;2&#8221;, &#8220;3&#8221;, 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 &lt;chapter number&gt;
+</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&mdash;in the case of collated
+documents&mdash;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&#8217;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&#8217;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 (&#8220;author linebreaks&#8221;, &#8220;section
+breaks&#8221;) 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">[ &lt;character&gt; ] [ 
&lt;iterations&gt; [ &lt;vertical adjustment&gt; ] ]</kbd>
+</div>
+
+<p class="alias" style="margin-bottom: 0;">
+<i>Alias:</i> <b>SECTION_CHAR</b>
+</p>
+<p class="requires">
+&bull;&nbsp;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&#8217;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&#8217;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">&lt;color name&gt;</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 &#8220;initialized&#8221;) 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.&mdash;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&#8217;s thinking
+&#8220;quotes from poetry or song lyrics&#8221;, 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&#8217;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&#8217;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&#8217;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&#8217;t want the behaviour described above (i.e. you
+don&#8217;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&#8217;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&nbsp;OFF</kbd> (or
+<kbd>QUIT, END, X</kbd>, etc).
+</p>
+
+<p class="tip-bottom">
+If you don&#8217;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&#8217;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&#8217;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&#8217;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&#8217;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&#8217;d rather she didn&#8217;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&#8217;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&#8217;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&#8217;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&#8217;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&mdash;including the first&mdash;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&#8217;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&#8217;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&#8217;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&#8217;s document processing macros; it can be used for
+&#8220;manually&#8221; 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&#8217;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&#8217;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&#8217;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&#8217;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&#8217;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&nbsp;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&#8217;t
+  seem to get everything done I want.
+  o an hour&#8217;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&nbsp;OFF</kbd> (you may prefer to use
+<kbd>.LIST&nbsp;BACK</kbd>) takes you back to the previous depth
+(or level) of list, with that list&#8217;s enumerator and indent
+intact.  The final <kbd>.LIST&nbsp;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&lt;n&gt; | roman&lt;n&gt; | USER &lt;string&gt;] [ 
&lt;separator&gt; | &lt;user-defined enumerator&gt; ] [ &lt;prefix&gt; ] [ 
&lt;off&gt; ]</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&#8217;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&#8217;ll discuss them one at a time here.
+</p>
+<h3 class="docs">The first argument &ndash; 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&lt;n&gt;</kbd> (for uppercase roman numerals),
+<kbd>roman&lt;n&gt;</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&lt;n&gt;</kbd> and
+<kbd>roman&lt;n&gt;</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&mdash;with a message &mdash; if you don&#8217;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&#8217;d like the
+enumerator to look like.
+</p>
+
+<p>
+For example, if you want a list enumerated
+with <kbd>=&gt;</kbd>,
+<br/>
+<span class="pre-in-pp">
+  .LIST USER =&gt;
+  .ITEM
+  A list item
+</span>
+
+will produce
+<br/>
+<span class="pre-in-pp">
+  =&gt; 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 &ndash; separator style</h3>
+
+<p>
+If you choose <kbd>DIGIT</kbd>, <kbd>ALPHA</kbd>, <kbd>alpha</kbd>,
+<kbd>ROMAN&lt;n&gt;</kbd>, or <kbd>roman&lt;n&gt;</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&lt;n&gt;</kbd> and <kbd>roman&lt;n&gt;</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&#8217;d prefer, say, digits with right-parenthesis separators
+instead of the default period, you&#8217;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 &ndash; 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&lt;n&gt;</kbd> or
+<kbd>roman&lt;n&gt;</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&#8217;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&#8217;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 &ndash; 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&lt;n&gt;</kbd>,
+<kbd>roman&lt;n&gt;</kbd> or <kbd>USER</kbd> (e.g.
+<kbd>LIST&nbsp;OFF</kbd> or <kbd>LIST&nbsp;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&nbsp;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&nbsp;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&#8217;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&#8217;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&#8217;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&#8217;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 &ndash; 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&#8217;s enumerator &ndash; 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&#8217;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&#8217;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&mdash;before <kbd>.ITEM</kbd>&mdash;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&#8217;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 &ndash; 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&#8217;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>&lt;n&gt;</kbd> argument appended to <kbd>ROMAN&lt;n&gt;</kbd>
+or <kbd>roman&lt;n&gt;</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&#8217;d like the roman numerals to line
+up flush right (i.e. be padded "left"), simply
+invoke <kbd>.PAD_LIST_DIGITS&nbsp;LEFT</kbd> after
+<kbd>.LIST&nbsp;ROMAN&lt;n&gt;</kbd> or
+<kbd>.LIST&nbsp;roman&lt;n&gt;</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 &ndash; 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&#8217;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">&lt;start number&gt; [ 
&lt;which lines to number&gt; [ &lt;gutter&gt; ] ]</kbd>
+</div>
+
+<div class="box-macro-args" style="margin-top: 1em;">
+Macro: <b>NUMBER_LINES</b>  <kbd class="macro-args">&lt;anything&gt; | 
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>&lt;which lines to number&gt;</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>&lt;start number&gt;</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>&lt;gutter&gt;</kbd>, tells mom how much
+space to put between the line numbers and the running text.
+<kbd>&lt;gutter&gt;</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&#8217;s default gutter is two figure spaces.  If
+you&#8217;d like a wider gutter, say, four figures spaces, you&#8217;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>&lt;gutter&gt;</kbd>, you cannot skip
+the <kbd>&lt;which lines to number&gt;</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&nbsp;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&mdash;say
+you want to reset the line number to <kbd>1</kbd>&mdash;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&#8217;t care.
+  </li>
+  <li style="margin-top: .25em;">If you&#8217;re collating documents with
+      <a href="rectoverso.html#collate">COLLATE</a>,
+      you should re-invoke, at a minimum,
+      <kbd>.NUMBER_LINES&nbsp;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&#8217;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&#8217;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&#8217;s
+restriction on accepting only the figure space as the line number
+gutter&#8217;s unit of measure, it is not possible for line numbers
+in quotes to hang outside a document&#8217;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>&lt;gutter&gt;</kbd> argument.
+</p>
+
+<p>
+If you&#8217;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&#8217;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&#8217;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&nbsp;SILENT
+</span>
+When you invoke <kbd>.NUMBER_QUOTE_LINES&nbsp;SILENT</kbd>,
+mom continues to increment line numbers while quotes are being
+output, but they won&#8217;t appear in the output copy.  (Compare
+this with mom&#8217;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&#8217;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&#8217;s restriction of accepting only the figure space as the
+line number gutter&#8217;s unit of measure, it is not possible for line
+numbers in blockquotes to hang outside a document&#8217;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>&lt;gutter&gt;</kbd> argument.
+</p>
+
+<p>
+If you&#8217;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&#8217;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&nbsp;SILENT
+</span>
+When you invoke <kbd>.NUMBER_BLOCKQUOTE_LINES&nbsp;SILENT</kbd>,
+mom continues to increment line numbers while blockquotes are being
+output, but they won&#8217;t appear in the output copy.  (Compare
+this with mom&#8217;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&#8217;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
+  &lt;footnote about who the hell is Schelling&gt;
+  .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&#8217;t fit on the page...
+Even if you&#8217;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&#8217;re writing
+a document that&#8217;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&#8217;ll
+usually opt for ample over cramped.  The last lines of footnotes are
+always flush with the document&#8217;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&#8217;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&#8217;s marked in the document
+body with a star) and the page it&#8217;s deferred to has its own
+footnotes, mom separates the deferred footnote from the page&#8217;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&#8217;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&#8217;s no confusion and mom doesn&#8217;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&#8217;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&#8217;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&nbsp;OFF</kbd> (or <kbd>X, QUIT, EXIT</kbd>, etc).
+</p>
+
+<p>
+Obviously, deferred footnotes aren&#8217;t an issue if you request
+numbered footnotes that increase incrementally throughout the whole
+document&mdash;yet another convenience mom has thought of.
+</p>
+
+<p>
+While mom&#8217;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&#8217;ll have a gaping hole at the bottom
+of the page.  It&#8217;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">&#8220;Fill&#8221; modes &ndash; JUSTIFY, 
or QUAD LEFT | CENTER | RIGHT</a></li>
+  <li><a href="#fn-and-punct-nofill">&#8220;No-fill&#8221; modes &ndash; LEFT, 
CENTER, RIGHT</a></li>
+</ol>
+
+<h4 id="fn-and-punct-fill" class="docs">1. &#8220;Fill&#8221; modes &ndash; 
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&nbsp;OFF</kbd> is to input it as if it&#8217;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&nbsp;OFF</kbd> is a period (dot).  You
+<b><i>must</i></b> begin such lines with <kbd>\&amp;.</kbd>, like
+this:
+<br/>
+<span class="pre-in-pp">
+  ...end of sentence\c
+  .FOOTNOTE
+  A footnote line.
+  .FOOTNOTE OFF
+  \&amp;.  A new sentence...
+</span>
+If you omit the <kbd>\&amp;.</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. &#8220;No-fill&#8221; modes 
&ndash; 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&nbsp;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&nbsp;OFF</kbd> to
+begin on a new output line.  This is accomplished by passing
+<kbd>.FOOTNOTE&nbsp;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&#8217;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&#8217;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&#8217;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">&lt;toggle&gt; [ BREAK | BR ] | INDENT 
LEFT | RIGHT | BOTH &lt;indent value&gt;</kbd>
+</div>
+
+<p class="requires">
+&bull;&nbsp;<kbd>&lt;indent value&gt;</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&#8217;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&#8217;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&nbsp;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&nbsp;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> &ndash; on or off</li>
+  <li><a href="#footnote-marker-style">Footnote marker style</a> &ndash; 
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> &ndash; line-numbered 
footnotes only</li>
+  </ul></li>
+  <li><a href="#reset-footnote-number">Reset footnote number</a> &ndash; 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> &ndash; on or off</li>
+  <li><a href="#footnote-rule-length">Footnote rule length</a> &ndash; length 
of footnote separator rule</li>
+  <li><a href="#footnote-rule-weight">Footnote rule weight</a> &ndash; 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 &ndash; FOOTNOTE_MARKERS</h4>
+
+<p>
+If you don&#8217;t want footnote markers, in either the body of
+the document or beside footnote entries themselves, toggle them
+off with <kbd>.FOOTNOTE_MARKERS&nbsp;OFF</kbd> (or <kbd>END, QUIT,
+X</kbd>...).  This means, of course, that you&#8217;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 &ndash; 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&#8217;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.&nbsp;[5-11]&nbsp;),
+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&#8217;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&#8217;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&#8217;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&#8217;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&#8217;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&#8217;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 &ndash; 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&nbsp;PAGE</kbd> tells mom to start every
+page&#8217;s footnote numbering at 1.
+</p>
+
+<h4 id="footnote-space" class="docs" style="margin-top: -.25em;">6. 
Inter-footnote spacing &ndash; FOOTNOTE_SPACE</h4>
+
+<p>
+If you&#8217;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&#8217;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 &ndash; FOOTNOTE_RULE</h4>
+
+<p>
+If you don&#8217;t want a footnote separator rule, toggle it off with
+<kbd>.FOOTNOTE_RULE&nbsp;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 &ndash; 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 &ndash; FOOTNOTE_RULE_WEIGHT</h4>
+
+<p>
+If you want to change the weight (&#8220;thickness&#8221;) 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&#8217;s default footnote rule weight is 1/2 point.  If
+you&#8217;d like a 1-point rule instead,<br/>
+<span class="pre-in-pp">
+  .FOOTNOTE_RULE_WEIGHT 1
+</span>
+is how you&#8217;d get it.
+</p>
+
+<h4 id="footnote-rule-adj" class="docs" style="margin-top: -.25em;">10. Adjust 
vertical position of footnote separator rule &ndash; 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&#8217;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&#8217;t
+look jammed together.  If you&#8217;d prefer a different vertical
+adjustment, invoke <kbd>.FOOTNOTE_RULE_ADJ</kbd> with the
+amount you&#8217;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&#8217;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>&mdash;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
+  &lt;endnote about who the hell is Schelling&gt;
+  .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&nbsp;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, &#8220;ENDNOTES&#8221;.
+Underneath&mdash;flush left, bold, and underscored&mdash;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">&lt;toggle&gt; [ 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&#8217;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&#8217;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&nbsp;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&#8217;ll use ENDNOTES at the end of a document.  If
+it&#8217;s a single (i.e. not collated) document, mom will print
+the endnotes pertaining to it.  If it&#8217;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&#8217;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&#8217;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> &ndash; 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;">&bull;&nbsp;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;">&bull;&nbsp;Base point size</h5>
+
+<div class="box-macro-args">
+Macro: <b>ENDNOTE_PT_SIZE</b> <kbd class="macro-args">&lt;base type size of 
endnotes&gt;</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;">&bull;&nbsp;Leading</h5>
+
+<div class="box-macro-args">
+Macro: <b>ENDNOTE_LEAD</b> <kbd class="macro-args">&lt;base leading of 
endnotes&gt; [ ADJUST ] </kbd>
+</div>
+
+<p class="requires">
+&bull;&nbsp;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&nbsp;OFF</kbd> command, she
+will still, by default, adjust endnote leading.  You <i>must</i>
+enter <kbd>.ENDNOTE_LEAD&nbsp;&lt;lead&gt;</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;">&bull;&nbsp;Singlespace endnotes 
(TYPEWRITE only)</h5>
+
+<div class="box-macro-args">
+Macro: <b>SINGLESPACE_ENDNOTES</b> <kbd class="macro-args">&lt;toggle&gt;</kbd>
+</div>
+
+<p>
+If your 
+<a href="docprocessing.html#printstyle">PRINTSTYLE</a>
+is <kbd>TYPEWRITE</kbd> and you use TYPEWRITE&#8217;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&#8217;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;">&bull;&nbsp;Paragraph indenting</h5>
+
+<div class="box-macro-args">
+Macro: <b>ENDNOTE_PARA_INDENT</b> <kbd class="macro-args">&lt;amount to indent 
first line of paragraphs in endnotes&gt;</kbd>
+</div>
+
+<p class="requires">
+&bull;&nbsp;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;">&bull;&nbsp;Paragraph spacing</h5>
+
+<div class="box-macro-args">
+Macro: <b>ENDNOTE_PARA_SPACE</b> <kbd class="macro-args">&lt;toggle&gt;</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;">&bull;&nbsp;Turning off column mode 
during endnotes output</h5>
+
+<div class="box-macro-args">
+Macro: <b>ENDNOTES_NO_COLUMNS</b> <kbd class="macro-args">&lt;toggle&gt;</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&#8217;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;">&bull;&nbsp;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;">&bull;&nbsp;Setting the first page 
number of endnotes</h5>
+
+<div class="box-macro-args">
+Macro: <b>ENDNOTES_FIRST_PAGENUMBER</b> <kbd class="macro-args">&lt;page # 
that appears on page 1 of endnotes&gt;</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&#8217;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;">&bull;&nbsp;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">&lt;toggle&gt;</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&#8217;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;">&bull;&nbsp;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&#8217;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;">&bull;&nbsp;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
+&#8220;Endnotes&#8221; 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;">&bull;&nbsp;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&#8217;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;">&bull;&nbsp;Allow headers on endnotes 
pages</h5>
+
+<div class="box-macro-args">
+Macro: <b>ENDNOTES_ALLOWS_HEADERS</b> <kbd class="macro-args">&lt;none&gt; | 
ALL</kbd>
+</div>
+
+<p>
+By default, if HEADERS are on, mom prints page headers on all
+endnotes pages except the first.  If you don&#8217;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;">&bull;&nbsp;Title string</h5>
+
+<div class="box-macro-args">
+Macro: <b>ENDNOTE_STRING</b> <kbd class="macro-args">&quot;&lt;head to print 
at the top of endnotes&gt;&quot;</kbd>
+</div>
+
+<p>
+By default, mom prints the word &#8220;ENDNOTES&#8221; 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&#8217;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&mdash;<kbd>&quot;&quot;</kbd>&mdash;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;">&bull;&nbsp;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;">&bull;&nbsp;Title string placement</h5>
+
+<div class="box-macro-args">
+Macro: <b>ENDNOTE_STRING_ADVANCE</b> <kbd class="macro-args">&lt;distance from 
top of page&gt;</kbd>
+</div>
+
+<p class="requires">
+&bull;&nbsp;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&#8217;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&#8217;d like the title placed.
+</p>
+
+<p>
+The argument requires a unit of measure, so if you&#8217;d like the title
+to appear 1-1/2 inches from the top edge of the page, you&#8217;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;">&bull;&nbsp;Title string 
underscoring</h5>
+
+<div class="box-macro-args">
+Macro: <b>ENDNOTE_STRING_UNDERSCORE</b> <kbd class="macro-args">[DOUBLE] 
[&lt;underscore weight&gt; [&lt;underscore gap&gt; [&lt;distance between double 
rules]]] | &lt;none&gt; | &lt;anything&gt;</kbd>
+</div>
+
+<p class="alias" style="margin-bottom: 0;">
+<i>Alias:</i> <b>ENDNOTE_STRING_UNDERLINE</b>
+</p>
+
+<p class="requires">
+&bull;&nbsp;The argument
+<span style="font-style: normal"><kbd>&lt;underscore weight&gt;</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&#8217;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;">&bull;&nbsp;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&#8217;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&#8217;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;">&bull;&nbsp;Document-identification title 
string(s)</h5>
+
+<div class="box-macro-args">
+Macro: <b>ENDNOTE_TITLE</b> <kbd class="macro-args">&quot;&lt;title to 
identify a document in endnotes&gt;&quot;</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&#8217;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&#8217;t want any identifying title, invoke
+<kbd>.ENDNOTE_TITLE</kbd> with a blank argument, either two
+double-quotes side by side (<kbd>&quot;&quot;</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&#8217;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;">&bull;&nbsp;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;">&bull;&nbsp;Endnotes 
document-identification underscoring</h5>
+
+<div class="box-macro-args">
+Macro: <b>ENDNOTE_TITLE_UNDERSCORE</b> <kbd class="macro-args">[DOUBLE] 
[&lt;underline weight&gt; [&lt;underline gap&gt; [&lt;distance between double 
rules]]] | &lt;none&gt; | &lt;anything&gt;</kbd>
+</div>
+
+<p class="alias" style="margin-bottom: 0;">
+<i>Alias:</i> <b>ENDNOTE_TITLE_UNDERLINE</b>
+</p>
+
+<p class="requires">
+&bull;&nbsp;The argument
+<span style="font-style: normal"><kbd>&lt;underscore weight&gt;</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&#8217;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;">&bull;&nbsp;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&#8217;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.&nbsp;[5-11]&nbsp;),
+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;">&bull;&nbsp;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">&lt;size of 
gap&gt;</kbd>
+</div>
+
+<p class="requires">
+&bull;&nbsp;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 &#8220;12&#8221; is two; the string length of
+&#8220;12-15&#8221; is 5), mom cannot &#8220;hang&#8221; 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&#8217;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;">&bull;&nbsp;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> (&#8220;round&#8221; 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;">&bull;&nbsp;Separator after endnote 
line numbers instead of brackets</h5>
+
+<div class="box-macro-args">
+Macro: <b>ENDNOTE_LINENUMBER_SEPARATOR</b> <kbd 
class="macro-args">&lt;character&gt;</kbd>
+</div>
+
+<p>
+If you don&#8217;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&#8217;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&#8217;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;">&bull;&nbsp;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;">&bull;&nbsp;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">&lt;number 
of placeholders&gt;</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&#8217;s left margin.  If, god help you, you have over a hundred
+endnotes, you&#8217;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&#8217;t want the endnote numbers to hang and right-align,
+invoke <kbd>.ENDNOTE_NUMBERS_ALIGN_LEFT</kbd>, which doesn&#8217;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>&mdash;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 &#8220;flow&#8221; of a
+document by summarizing the subject of a portion of text.  Sometimes
+they&#8217;re comments to yourself in a draft copy.
+</p>
+
+<p>
+The margin notes macros and routines in om.tmac (mom) are
+&#8220;mommified&#8221; 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 &#8220;initialize&#8221; 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&#8217;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 &#8220;shift&#8221; 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&#8217;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&#8217;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 &#8220;flow&#8221; onto the next page.  If
+it is a &#8220;left&#8221; margin note, it will continue in the
+left margin.  If it is a &#8220;right&#8221; 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 &#8220;direction&#8221;
+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&#8217;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">&lt;arguments (see 
list)&gt;</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 ]
+&lt;left-width&gt;
+&lt;right-width&gt;
+&lt;gutter&gt;
+&lt;family+font&gt;
+&lt;point-size&gt;
+&lt;lead&gt;
+&lt;colour&gt;
+&lt;hyphenation-flags&gt;
+</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>&quot;&quot;</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:&nbsp;&nbsp;<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>&quot;&quot;</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:&nbsp;&nbsp;<kbd style="color: 
#302419;">&lt;left-width&gt;</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:&nbsp;&nbsp;<kbd style="color: 
#302419;">&lt;right-width&gt;</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:&nbsp;&nbsp;<kbd style="color: 
#302419;">&lt;gutter&gt;</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:&nbsp;&nbsp;<kbd style="color: 
#302419;">&lt;font&gt;</kbd></h4>
+
+<p>
+The family+font for margin notes.  Yes, that&#8217;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&#8217;s paragraph text.
+</p>
+
+<h4 class="docs arg-list">Argument 6:&nbsp;&nbsp;<kbd style="color: 
#302419;">&lt;point size&gt;</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&#8217;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:&nbsp;&nbsp;<kbd style="color: 
#302419;">&lt;lead&gt;</kbd></h4>
+
+<p>
+The
+<a href="definitions.html#leading">leading</a>
+of margin notes.  <kbd>&lt;lead&gt;</kbd> uses
+<a href="definitions.html#picaspoints">points</a>
+as its unit of measure, so don&#8217;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&#8217;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>&quot;&quot;</kbd> (two double-quotes).  Like the
+double-quotes, it indicates that the leading should be the same as
+the document&#8217;s base leading.
+</p>
+
+<h4 class="docs arg-list">Argument 8:&nbsp;&nbsp;<kbd style="color: 
#302419;">&lt;colour&gt;</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:&nbsp;&nbsp;<kbd style="color: 
#302419;">&lt;hyphenation-flags&gt;</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&#8217;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.
+                  &mdash; END &mdash;
+</span>
+</p>
+
+<p>
+If you&#8217;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&#8217;t use FINIS, and you don&#8217;t want
+<a href="definitions.html#footer">footers</a>
+(if they&#8217;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&#8217;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&#8217;s in French, you&#8217;d do
+<br/>
+<span class="pre-in-pp">
+    .FINIS_STRING "FIN"
+</span>
+Double-quotes must enclose the macro&#8217;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&#8217;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&#8217;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 &#8220;initalized&#8221;) 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>\*[&lt;colorname&gt;]</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: -->

Index: docprocessing.html
===================================================================
RCS file: docprocessing.html
diff -N docprocessing.html
--- /dev/null   1 Jan 1970 00:00:00 -0000
+++ docprocessing.html  18 Aug 2010 22:45:35 -0000      1.37
@@ -0,0 +1,3601 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+This file is part of groff, the GNU roff type-setting system.
+
+Copyright (C) 2004, 2005, 2010, 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, Introduction and Setup</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="docelement.html#top">Next: The 
document element tags</a></td>
+</tr>
+</table>
+
+<h1 class="docs">Document processing with mom</h1>
+
+<div style="text-align: center;">
+<ul class="no-enumerator" style="margin-left: -2.5em;">
+  <li><a href="#defaults">Document defaults</a></li>
+  <li><a href="#leading-note">Important note on leading/spacing and bottom 
margins</a></li>
+  <li><a href="#shim">The SHIM macro</a></li>
+</ul>
+</div>
+
+<div class="rule-medium"><hr/></div>
+
+<h2 id="toc-doc-processing" class="docs" style="text-align: center;">Table of 
contents</h2>
+
+<div id="docprocessing-mini-toc" style="font-size: 90%; 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="#docprocessing-intro">Introduction</a></h3>
+<h3 class="toc toc-docproc-header" style="margin-top: .5em;"><a 
class="header-link" href="#setup">Document setup</a></h3>
+<ul class="toc-docproc" style="margin-top: .5em;">
+  <li><a href="#docprocessing-tut"><b>Tutorial &ndash; Setting up a mom 
document</b></a></li>
+  <li><a href="#reference-macros"><b>The reference macros</b></a>
+  <ul class="toc-docproc">
+    <li><a href="#title">TITLE</a></li>
+    <li><a href="#doc-title">DOCTITLE</a></li>
+    <li><a href="#subtitle">SUBTITLE</a></li>
+    <li><a href="#author">AUTHOR</a></li>
+    <li><a href="#chapter">CHAPTER</a></li>
+    <li><a href="#chapter-title">CHAPTER_TITLE</a></li>
+    <li><a href="#draft">DRAFT</a></li>
+    <li><a href="#revision">REVISION</a></li>
+    <li><a href="#copyright">COPYRIGHT</a></li>
+    <li><a href="#misc">MISC</a></li>
+    <li><a href="#covertitle">COVERTITLE</a></li>
+    <li><a href="#doc-covertitle">DOC_COVERTITLE</a></li>
+  </ul></li>
+  <li><a href="#docstyle-macros"><b>The docstyle macros</b></a>
+  <ul class="toc-docproc">
+    <li><a href="#doctype">DOCTYPE</a></li>
+    <li><a href="#printstyle">PRINTSTYLE</a></li>
+    <li><a href="#copystyle">COPYSTYLE</a></li>
+  </ul></li>
+</ul>
+<h3 class="toc toc-docproc-header"><a class="header-link" 
href="#start-macro">Initiate document processing</a></h3>
+<ul class="toc-docproc" style="margin-top: .5em;">
+  <li><a href="#start"><b>The START macro</b></a></li>
+</ul>
+<h3 class="toc toc-docproc-header"><a class="header-link" 
href="#style-before-start">Establishing type and formatting<br/><span 
style="display: block; margin-top: -.3em;">parameters before 
START</span></a></h3>
+<ul class="toc-docproc" style="margin-top: .5em;">
+  <li><a href="#type-before-start"><b>Behaviour of the typesetting macros 
before START</b></a>
+  <ul class="toc-docproc">
+    <li><a href="docprocessing.html#include">Including (sourcing) style sheets 
and files</a></li>
+    <li><a href="#color">Initializing colours</a></li>
+  </ul></li>
+</ul>
+</div>
+<div class="mini-toc-col-2" style="margin-top: -.5em;">
+<br/>
+<ul class="toc-docproc" style="margin-top: .5em;">
+  <li><a href="#doc-lead-adjust"><b>Adjust linespacing to fill pages</b></a>
+  <ul class="toc-docproc">
+    <li><a href="#doc-lead-adjust">DOC_LEAD_ADJUST</a></li>
+    <li><a href="#shim">SHIM</a> &ndash; the macro to get document leading 
back on track</li>
+  </ul></li>
+  <li><a href="#docheader"><b>Managing the document header</b></a>
+  <ul class="toc-docproc">
+    <li><a href="#docheader">DOCHEADER</a></li>
+    <li><a href="#docheader-control">Docheader control</a>
+    <ul class="toc-docproc">
+      <li><a href="#docheader-desc">Docheader description</a></li>
+      <li><a href="#index-docheader-control">Macro list</a></li>
+    </ul></li>
+  </ul></li>
+  <li><a href="#columns-intro"><b>Setting documents in columns</b></a>
+  <ul class="toc-docproc">
+    <li><a href="#columns">COLUMNS</a></li>
+    <li><a href="#breaking-columns">Breaking columns manually</a>
+    <ul class="toc-docproc">
+      <li><a href="#col-next">COL_NEXT</a></li>
+      <li><a href="#col-break">COL_BREAK</a></li>
+    </ul></li>
+  </ul></li>
+</ul>
+<h3 class="toc toc-docproc-header"><a class="header-link" 
href="#style-after-start">Changing basic type and formatting<br/><span 
style="display: block; margin-top: -.3em;">parameters after 
START</span></a></h3>
+<ul class="toc-docproc" style="margin-top: .5em;">
+  <li><a href="#behaviour"><b>Behaviour of the typesetting macros during 
document processing</b></a></li>
+  <li><a href="docprocessing.html#index-doc-param"><b>Post-START global style 
change macros</b></a>
+  <ul class="toc-docproc">
+    <li><a href="#doc-left-margin">DOC_LEFT_MARGIN</a></li>
+    <li><a href="#doc-right-margin">DOC_RIGHT_MARGIN</a></li>
+    <li><a href="#doc-line-length">DOC_LINE_LENGTH</a></li>
+    <li><a href="#doc-family">DOC_FAMILY</a></li>
+    <li><a href="#doc-pt-size">DOC_PT_SIZE</a></li>
+    <li><a href="#doc-lead">DOC_LEAD</a></li>
+    <li><a href="#doc-lead-adjust">DOC_LEAD_ADJUST</a></li>
+    <li><a href="#doc-quad">DOC_QUAD</a></li>
+  </ul></li>
+</ul>
+</div>
+</div>
+
+<div class="rule-medium" style="clear: both;"><hr/></div>
+
+<!-- ==================================================================== -->
+
+<h2 id="docprocessing-intro" class="docs">Introduction to document 
processing</h2>
+
+<p>
+Document processing with mom uses markup tags to identify document elements
+such as heads, paragraphs, and so on.  The tags are, of course,
+macros, but with sensible, readable names that make them easy
+to grasp and easy to remember.  (And don&#8217;t forget: if you
+don&#8217;t like the &#8220;official&#8221; name of a tag &mdash;
+too long, cumbersome to type in, not &#8220;intuitive&#8221; enough
+&mdash; you can change it with the
+<a href="goodies.html#alias">ALIAS</a>
+macro.)
+</p>
+
+<p>
+In addition to the tags themselves, mom has an extensive array of
+macros that control how they look and behave.
+</p>
+
+<p>
+Setting up a mom doc is a simple, four-part procedure.  You
+begin by entering information about the document itself (title,
+subtitle, author, etc.).  Next, you tell mom what kind of document
+you&#8217;re creating (e.g. chapter, letter, abstract, etc...) and
+what kind of output you want (typeset, typewritten, draft-style,
+etc).  Thirdly, you make as many or as few changes to mom&#8217;s
+default behaviour as you wish.  Lastly, you invoke the
+<kbd><a href="#start">START</a></kbd>
+macro.  Voilà!  You&#8217;re ready to write.
+</p>
+
+<!-- ==================================================================== -->
+
+<h2 id="defaults" class="docs">Document defaults</h2>
+
+<p>
+As is to be expected, mom has defaults for everything.  If you want
+to know a particular default, read about it in the description of
+the pertinent tag.
+</p>
+
+<p>
+I fear the following may not be adequately covered in the
+documentation, so just in case:
+</p>
+<ul style="margin-top: -.5em; margin-bottom: .5em;">
+  <li>the paper size is 8.5x11 inches</li>
+  <li>the left and right margins are 1-inch</li>
+  <li>the top and bottom margins for document text are plus/minus
+      visually 1-inch
+  </li>
+  <li>pages are numbered; the number appears centred, at the
+      bottom, surrounded by hyphens ( e.g. -6- )
+  </li>
+  <li>the first page of a document begins with a
+      <a href="definitions.html#docheader">document header</a>
+  </li>
+  <li>subsequent pages have
+      <a href="definitions.html#header">page headers</a>
+      with a rule underneath
+  </li>
+</ul>
+
+<!-- ==================================================================== -->
+
+<h2 id="leading-note" class="docs">Important note on leading/spacing and 
bottom margins</h2>
+
+<p>
+Mom takes evenly-aligned bottom margins in
+<a href="definitions.html#running">running text</a>
+very seriously.  Only under a very few (exceptional) circumstances
+will she allow a bottom margin to &#8220;hang&#8221; (i.e. to fall
+short).
+</p>
+
+<p>
+In order to ensure even bottom margins, mom uses the
+&#8220;base&#8221; document
+<a href="definitions.html#leading">leading</a>
+in effect <i>at the start of running text on each page</i> (i.e.
+the leading used in paragraphs) to calculate the spacing of every
+document element.  Prior to invoking
+<a href="#start">START</a>,
+this is set with the
+<a href="typesetting.html#macros-typesetting">typesetting macro</a>
+<a href="typesetting.html#leading">LS</a>,
+afterwards with the document
+<a href="definitions.html#controlmacro">control macro</a>
+<a href="#doc-lead">DOC_LEAD</a>.
+</p>
+
+<p>
+Because mom relies so heavily on the base document
+leading, any change to the leading or spacing on a page will almost
+certainly have undesirable consequences on that page&#8217;s bottom margin
+unless the change is fully compensated for elsewhere on the page.
+</p>
+
+<p>
+In other words, if you add a few points of space somewhere on a page,
+you must subtract the same number of points somewhere else on that
+same page, and vice versa.
+</p>
+
+<p>
+If it&#8217;s a question of adding or subtracting full
+line spaces between or within document elements, you
+can do so by using the &#8220;<kbd>v</kbd>&#8221; <a
+href="definitions.html#unitofmeasure">unit of measure</a> with
+whatever spacing macro you choose &mdash;
+<a href="typesetting.html#ald">ALD</a>,
+<a href="typesetting.html#rld">RLD</a>,
+<a href="typesetting.html#space">SPACE</a>
+&mdash; and mom won&#8217;t object.  &#8220;<kbd>v</kbd>&#8221; means
+&#8220;the current leading&#8221;, so she isn&#8217;t confused by it.  And
+since &#8220;<kbd>v</kbd>&#8221; accepts decimal fractions, you can 
add/subtract
+half linespaces and quarter linespaces with &#8220;<kbd>v</kbd>&#8221; as well,
+<i>provided you compensate for the fractional linespace somewhere
+else on the page</i>.
+</p>
+
+<p>
+If all this seems like too much work, mom provides a special macro
+to get you out of trouble if you&#8217;ve played around with leading
+and/or spacing.  The macro is called SHIM (like those little pieces
+of wood carpenters use to get their work even, level and snug), and
+it&#8217;s described below.
+</p>
+
+<!-- -SHIM- -->
+
+<div class="macro-id-overline">
+<h3 id="shim" class="macro-id">SHIM</h3>
+</div>
+
+<div class="box-macro-args">
+Macro: <b>SHIM</b>
+</div>
+
+<p>
+SHIM doesn&#8217;t take any argument.  Use it whenever you&#8217;ve played
+around with the
+<a href="definitions.html#leading">leading</a>
+or spacing on a page and you need to get mom&#8217;s document
+leading back on track.
+</p>
+
+<p>
+For example, say you want to insert a picture into a document with
+the special groff macro, PSPIC (see <kbd>man groff-tmac</kbd> for
+usage).
+</p>
+
+<p>
+Pictures aren&#8217;t usually conveniently sized in multiples of
+document leading, which means that when you insert the picture, you
+disrupt mom&#8217;s ordered placement of baselines on the page.
+This will certainly result in a bottom margin that doesn&#8217;t
+match the bottom margins of your document&#8217;s other pages.
+</p>
+
+<p>
+The solution is to insert SHIM after the picture,
+like this:
+<br/>
+<span class="pre-in-pp">
+  &lt;some lines of text&gt;
+  .PSPIC &lt;full path to picture&gt;
+  .SHIM
+  &lt;more lines of text&gt;
+</span>
+</p>
+
+<p>
+SHIM instructs mom to insert as much or a little space after the
+picture as is needed to ensure that the baseline of the next
+<a href="definitions.html#outputline">output line</a>
+falls where mom would have put it had you not disrupted the normal
+flow of output lines with the picture.
+</p>
+
+<p>
+And say, on previewing the above example, you find that the picture
+doesn&#8217;t centre nicely between the lines of text, you can
+always do
+<br/>
+<span class="pre-in-pp">
+  &lt;some lines of text&gt;
+  .RLD 3p
+  .PSPIC &lt;full path to picture&gt;
+  .SHIM
+  &lt;more lines of text&gt;
+</span>
+to raise the picture slightly (reverse lead 3 points; see
+<a href="typesetting.html#rld">RLD</a>),
+and still have SHIM ensure that text underneath falls exactly where
+it&#8217;s supposed to.
+</p>
+
+<div class="box-tip">
+<p class="tip">
+<span class="note">Note:</span>
+For information on disabling the automatic shimming of quotes and
+blockquotes during document processing, see
+<a href="docelement.html#no-shim">here</a>.
+</p>
+</div>
+
+<div class="rule-short"><hr/></div>
+
+<!-- ==================================================================== -->
+
+<h2 id="setup" class="docs" style="margin-bottom: .5em;">Preliminary document 
setup</h2>
+
+<div class="examples-container" style="margin-bottom: 1.5em;">
+<h3 id="docprocessing-tut" class="docs">Tutorial &ndash; Setting up a mom 
document</h3>
+
+<p style="margin-top: 1em;">
+There are four parts to setting up a mom doc (three, actually,
+with one optional).  Before we proceed, though, be reassured that
+something as simple as
+<br/>
+<span class="pre-in-pp">
+  .TITLE     "By the Shores of Lake Attica"
+  .AUTHOR    "Rosemary Winspeare"
+  .PRINTSTYLE TYPESET
+  .START
+</span>
+produces a beautifully typeset 8.5x11 document, with a
+<a href="definitions.html#docheader">docheader</a>
+at the top of page 1,
+<a href="definitions.html#header">page headers</a>
+with the title and author on subsequent pages, and page numbers at
+the bottom of each page.  In the course of the document, heads,
+subheads, citations, quotes, epigraphs, and so on, all come out
+looking neat, trim, and professional.
+</p>
+
+<p>
+For the purposes of this tutorial, we&#8217;re going to set up
+a short story&mdash;<i>My Pulitzer Winner</i>&mdash;by Joe Blow.
+Thankfully, we don&#8217;t have to look at story itself, just the
+setup.  Joe wants the document
+</p>
+<ul style="margin-top: -.5em; margin-bottom: -.5em;">
+  <li>to be draft 7, revision 39;</li>
+  <li>to use the &#8220;default&#8221; style of document formatting:</li>
+  <li>to print as draft-style output (instead of &#8220;final&#8221; copy 
output);</li>
+  <li>to be typeset, in Helvetica, 12 on 14,
+      <a href="definitions.html#rag">rag-right</a>;
+  </li>
+  <li>to have <a href="definitions.html#footer">footers</a>
+      instead of
+      <a href="definitions.html#header">headers</a>;
+  </li>
+  <li>to use a single asterisk for
+      <a href="definitions.html#linebreak">author linebreaks</a>.
+  </li>
+</ul>
+
+<p>
+Joe Blow has no taste in typography.  His draft won&#8217;t look
+pretty, but this is, after all, a tutorial; we&#8217;re after
+examples, not beauty.
+</p>
+
+<h4 class="docs" style="margin-top: -.5em;">Step 1</h4>
+
+<p style="margin-bottom: -.5em;">
+The first step in setting up any document is giving mom some
+reference information.  The reference macros are:
+</p>
+<div style="width: 50%; float: left;">
+<ul>
+  <li>TITLE</li>
+  <li>DOCTITLE</li>
+  <li>COVERTITLE</li>
+  <li>DOC_COVERTITLE</li>
+  <li>SUBTITLE</li>
+  <li>AUTHOR</li>
+  <li>CHAPTER &ndash; the chapter number</li>
+</ul>
+</div>
+<div>
+<ul>
+  <li>DRAFT &ndash; the draft number</li>
+  <li>REVISION &ndash; the revision number</li>
+  <li>COPYRIGHT &ndash; only used on cover pages</li>
+  <li>MISC &ndash; only used on cover pages</li>
+  <li>COVER_TITLE &ndash; only on cover pages; only if needed</li>
+  <li>DOC_COVER_TITLE &ndash; only on document cover pages; only if needed</li>
+</ul>
+</div>
+
+<p style="margin-top: -.5em; clear: both;">
+You can use as many or as few as you wish, although at a minimum,
+you&#8217;ll probably fill in TITLE (unless the document&#8217;s a
+letter) and AUTHOR.  Order doesn&#8217;t matter.  You can separate
+the
+<a href="definitions.html#arguments">arguments</a>
+from the macros by any number of spaces.  The following are what
+you&#8217;d need to start Joe Blow&#8217;s story.
+<br/>
+<span class="pre-in-pp">
+  .TITLE    "My Pulitzer Winner"
+  .AUTHOR   "Joe Blow"
+  .DRAFT     7
+  .REVISION  39
+</span>
+</p>
+
+<h4 class="docs" style="margin-top: -1.5em;">Step 2</h4>
+
+<p>
+Once you&#8217;ve given mom the reference information she needs, you
+tell her how you want your document formatted.  What kind of
+document is it?  Should it be typeset or typewritten?  Is this a
+final copy (for the world to see) or just a draft?  Mom calls
+the macros that answer these questions &#8220;the docstyle
+macros.&#8221; They are:
+</p>
+<ul style="margin-top: -.5em; margin-bottom: -.5em;">
+  <li>DOCTYPE&mdash;the type of document (default, chapter, user-defined, 
letter)</li>
+  <li>PRINTSTYLE&mdash;typeset or typewritten</li>
+  <li>COPYSTYLE &mdash;draft or final copy</li>
+</ul>
+
+<p>
+Mom has defaults for DOCTYPE and COPYSTYLE; if they&#8217;re what
+you want, you don&#8217;t need to include them here.  However,
+PRINTSTYLE has no default and must be present in every formatted
+document.  If you omit it, mom won&#8217;t process the document
+AND she&#8217;ll complain (both to stderr and as a single printed
+sheet with a warning).  Moms&mdash;they can be so annoying
+sometimes. &lt;sigh&gt;
+</p>
+
+<p>
+Adding to what we already have, the next bit of setup for Joe
+Blow&#8217;s story looks like this:
+<br/>
+<span class="pre-in-pp">
+    .TITLE    "My Pulitzer Winner"
+    .AUTHOR   "Joe Blow"
+    .DRAFT     7
+    .REVISION  39
+    \#
+    .DOCTYPE     DEFAULT \"Superfluous; mom uses DOCTYPE DEFAULT by default
+    .PRINTSTYLE  TYPESET
+    .COPYSTYLE   DRAFT
+</span>
+Notice the use of the
+<a href="definitions.html#commentlines">comment line</a>
+( <kbd>\#</kbd> ), a handy way to keep groups of macros visually
+separated for easy reading in a text editor.
+</p>
+
+<h4 class="docs" style="margin-top: -.5em; margin-bottom: -.5em;">Step 3</h4>
+
+<p>
+This step&mdash;completely optional&mdash;is where you, the
+user, take charge.  Mom has defaults for <i>everything</i>, but
+who&#8217;s ever satisfied with defaults?  Use any of the
+<a href="typesetting.html#macros-typesetting">typesetting macros</a>
+here to change mom&#8217;s document defaults (paper size, margins,
+family, point size, line space, rag, etc), or any of the document
+processing macros that set/change/control the appearance of document
+elements.  Think of this as the &#8220;style-sheet &#8221; section
+of a document.  And please note: you MUST give mom a
+<a href="#printstyle">PRINTSTYLE</a>
+directive <i>before</i> making any such changes.
+</p>
+
+<p>
+Joe Blow wants his story printed in Helvetica, 12 on 14, rag right,
+with
+<a href="definitions.html#footer">page footers</a>
+instead of
+<a href="definitions.html#header">page headers</a>
+and a single asterisk for the
+<a href="definitions.html#linebreak">linebreak</a>
+character.  None of these requirements conforms to mom&#8217;s
+defaults for the chosen PRINTSTYLE (TYPESET), so we change them
+here.  The setup for Joe Blow&#8217;s story now looks like this:
+<br/>
+<span class="pre-in-pp">
+  .TITLE    "My Pulitzer Winner"
+  .AUTHOR   "Joe Blow"
+  .DRAFT     7
+  .REVISION  39
+  \#
+  .DOCTYPE     DEFAULT
+  .PRINTSTYLE  TYPESET
+  .COPYSTYLE   DRAFT
+  \#
+  .FAMILY  H
+  .PT_SIZE 12
+  .LS      14
+  .QUAD    LEFT    \"i.e. rag right
+  .FOOTERS
+  .LINEBREAK_CHAR *
+</span>
+</p>
+
+<h4 class="docs" style="margin-top: -1.5em; margin-bottom: -.5em;">Step 4</h4>
+
+<p>
+The final step in setting up a document is telling mom to start
+document processing.  It&#8217;s a no-brainer, just the single
+macro, START.  Other than PRINTSTYLE, it&#8217;s the only macro
+required for document processing (although I can&#8217;t guarantee
+you&#8217;ll like the results of using just the two).
+</p>
+
+<p>
+Here&#8217;s the complete setup for <i>My Pulitzer Winner</i>:
+<br/>
+<span class="pre-in-pp">
+  .TITLE    "My Pulitzer Winner"
+  .AUTHOR   "Joe Blow"
+  .DRAFT     7
+  .REVISION  39
+  \#
+  .DOCTYPE     DEFAULT
+  .PRINTSTYLE  TYPESET
+  .COPYSTYLE   DRAFT
+  \#
+  .FAMILY   H
+  .PT_SIZE  12
+  .LS       14
+  .QUAD     LEFT    \"i.e. rag right
+  .FOOTERS
+  .LINEBREAK_CHAR *
+  \#
+  .START
+</span>
+As pointed out earlier, Joe Blow is no typographer.  Given that all he
+needs is a printed draft of his work, a simpler setup would have been:
+<br/>
+<span class="pre-in-pp">
+  .TITLE    "My Pulitzer Winner"
+  .AUTHOR   "Joe Blow"
+  .DRAFT     7
+  .REVISION  39
+  \#
+  .PRINTSTYLE  TYPEWRITE
+  .COPYSTYLE   DRAFT
+  \#
+  .START
+</span>
+<kbd>.PRINTSTYLE&nbsp;TYPEWRITE</kbd>, above, means that Joe&#8217;s
+work will come out &#8220;typewritten, double-spaced&#8221;,
+making the blue-pencilling he (or someone else) is sure to do much
+easier (which is why many publishers and agents still insist on
+typewritten, double-spaced copy).
+</p>
+
+<p>
+When J. Blow stops re-writing and decides to print off a final,
+typeset copy of his work for the world to see, he need only make two
+changes to the (simplified) setup:
+<br/>
+<span class="pre-in-pp">
+  .TITLE    "My Pulitzer Winner"
+  .AUTHOR   "Joe Blow"
+  .DRAFT     7
+  .REVISION  39
+  \#
+  .PRINTSTYLE  TYPESET  \"first change
+  .COPYSTYLE   FINAL    \"second change
+  \#
+  .START
+</span>
+In the above, <kbd>.DRAFT&nbsp;7,&nbsp;.REVISION 39,</kbd> and
+<kbd>.COPYSTYLE FINAL</kbd> are actually superfluous.  The draft
+and revision numbers aren&#8217;t used when COPYSTYLE is FINAL,
+and <b>COPYSTYLE FINAL</b> is mom&#8217;s default unless you tell
+her otherwise.
+</p>
+
+<p>
+BUT... to judge from the number of drafts already,
+J. Blow may very well decide his &#8220;final&#8221; version still
+isn&#8217;t up to snuff.  Hence, he might as well leave in the
+superfluous macros.  That way, when draft 7, rev. 62 becomes draft
+8, rev. 1, he&#8217;ll be ready to tackle his Pulitzer winner again.
+</p>
+</div>
+
+<div class="rule-short"><hr/></div>
+
+<!-- ======================================================================== 
-->
+
+<h2 id="reference-macros" class="macro-group">The reference macros</h2>
+
+<p>
+The reference macros give mom the meta-information she needs to
+generate
+<a href="definitions.html#docheader">docheaders</a>,
+<a href="definitions.html#header">page headers</a>,
+and
+<a href="cover.html#cover-top">covers</a>.
+They must go at the top of any file that uses mom&#8217;s document
+processing macros.
+</p>
+
+<div class="macro-list-container">
+<h3 id="index-reference" class="macro-list">Reference macros</h3>
+
+<ul class="macro-list">
+  <li><a href="#title">TITLE</a> &ndash; title of a story, article, etc</li>
+  <li><a href="#doc-title">DOCTITLE</a> &ndash; title of a book, or any 
collated document</li>
+  <li><a href="#subtitle">SUBTITLE</a></li>
+  <li><a href="#author">AUTHOR</a></li>
+  <li><a href="#chapter">CHAPTER</a> &ndash; the chapter number
+  <ul>
+    <li class="sublist"><a href="#chapter-string">CHAPTER_STRING</a> &ndash; 
&#8220;Chapter&#8221;, &#8220;CHAPTER&#8221;, &#8220;Chapître&#8221;, etc</li>
+  </ul></li>
+  <li><a href="#chapter-title">CHAPTER_TITLE</a></li>
+  <li><a href="#draft">DRAFT</a>
+  <ul>
+    <li class="sublist"><a href="#draft-string">DRAFT_STRING</a> &ndash; 
&#8220;Draft&#8221;, &#8220;DRAFT&#8221;, &#8220;Jet&#8221;, etc</li>
+  </ul></li>
+  <li><a href="#revision">REVISION</a>
+  <ul>
+    <li class="sublist"><a href="#revision-string">REVISION_STRING</a> &ndash; 
&#8220;Revision&#8221;, &#8220;Rev.&#8221;, &#8220;Révision&#8221;, etc</li>
+  </ul></li>
+  <li><a href="#copyright">COPYRIGHT</a></li>
+  <li><a href="#misc">MISC</a></li>
+  <li><a href="#covertitle">COVERTITLE</a> &ndash; frontispiece, title page, 
etc</li>
+  <li><a href="#doc-covertitle">DOC_COVERTITLE</a> &ndash; book cover, 
collated document cover, etc</li>
+</ul>
+</div>
+
+<!-- -TITLE- -->
+
+<div class="macro-id-overline">
+<h3 id="title" class="macro-id">TITLE</h3>
+</div>
+
+<div class="box-macro-args">
+Macro: <b>TITLE</b> <kbd>&quot;&lt;title string&gt;&quot; [&quot;&lt;2nd 
line&gt;&quot; [&quot;&lt;3rd line&gt;&quot; ... ] ]</kbd> 
+</div>
+<p class="requires">
+&bull;&nbsp;Arguments must be enclosed in double-quotes
+</p>
+
+<p>
+The title string can be caps or caps/lower-case; it&#8217;s up to you.  In
+<a href="#printstyle">PRINTSTYLE TYPESET</a>,
+the title will appear in the
+<a href="definitions.html#docheader">docheader</a>
+exactly as you typed it.  However, mom converts the title to all
+caps in
+<a href="definitions.html#header">page headers</a>
+unless you turn that feature off (see
+<a href="headfootpage.html#_caps">HEADER_&lt;POSITION&gt;_CAPS</a>).
+In
+<a href="#printstyle">PRINTSTYLE TYPEWRITE</a>,
+the title always gets converted to caps.
+</p>
+
+<p>
+TITLE accepts multiple arguments, each surrounded by double-quotes.
+Each argument is printed on a separate line, permitting you to
+create multi-line titles in your docheaders.
+</p>
+
+<div class="box-tip">
+<p class="tip">
+<span class="note">Note:</span>
+If your <kbd><a href="#doctype">DOCTYPE</a></kbd> is CHAPTER, TITLE
+should be the title of the opus, not &#8220;CHAPTER whatever&#8221;.
+</p>
+</div>
+
+<!-- -DOCTITLE- -->
+
+<div class="macro-id-overline">
+<h3 id="doc-title" class="macro-id">DOCUMENT TITLE</h3>
+</div>
+
+<div class="box-macro-args">
+Macro: <b>DOCTITLE</b> <kbd class="macro-args">&quot;&lt;overall document 
title&gt;&quot; [&quot;&lt;2nd line&gt;&quot; [&quot;&lt;3rd line&gt;&quot; ... 
] ]</kbd> 
+</div>
+<p class="requires">
+&bull;&nbsp;Arguments must be enclosed in double-quotes
+</p>
+
+<div class="box-tip">
+<p class="tip">
+<span class="note">Note:</span>
+This macro should be used only if your <a
+href="#doctype">DOCTYPE</a> is <kbd>DEFAULT</kbd> (which is
+mom&#8217;s default).  If your DOCTYPE is CHAPTER, use
+<a href="#title">TITLE</a>
+to set the overall document title for cover pages, document cover
+pages, and page headers or footers.
+</p>
+</div>
+
+<p style="margin-top: -.5em;">
+When you&#8217;re creating a single document, say, an essay or a
+short story, you have no need of this macro.
+<a href="#title">TITLE</a>
+takes care of all your title needs.
+</p>
+
+<p>
+However if you&#8217;re 
+<a href="rectoverso.html#collate">collating</a>
+a bunch of documents together, say, to print out a report containing
+many articles with different titles, or a book of short stories with
+different authors, you need DOCTITLE.
+</p>
+
+<p>
+DOCTITLE tells mom the title of the complete document (as opposed to
+the title of each article or entitled section).
+</p>
+
+<p>
+The doctitle string can be caps or caps/lower-case; it&#8217;s up to
+you.  In
+<a href="#printstyle">PRINTSTYLE TYPESET</a>,
+by default, the doctitle appears in the rightmost position of
+<a href="definitions.html#header">page headers</a>,
+all in caps unless you turn that feature off (see
+<a href="headfootpage.html#_caps">HEADER_&lt;POSITION&gt;_CAPS</a>).
+In
+<a href="#printstyle">PRINTSTYLE TYPEWRITE</a>,
+the doctitle always gets converted to caps.
+</p>
+
+<p>
+DOCTITLE accepts multiple arguments, each surrounded
+by double-quotes.  Each argument is printed on a separate line,
+permitting you to create multi-line document titles for use on
+<a href="cover.html#cover">Covers</a>
+and/or
+<a href="cover.html#doc-cover">Doc covers</a>.
+</p>
+
+<div class="box-tip">
+<p class="tip">
+<span class="note">Note:</span>
+If your
+<a href="#doctype">DOCTYPE</a>
+is CHAPTER, you don&#8217;t need DOCTITLE.  TITLE takes care of
+everything.
+</p>
+</div>
+
+<!-- -SUBTITLE- -->
+
+<div class="macro-id-overline">
+<h3 id="subtitle" class="macro-id">SUBTITLE</h3>
+</div>
+
+<div class="box-macro-args">
+Macro: <b>SUBTITLE</b> <kbd class="macro-args">[COVER | DOC_COVER] 
&quot;&lt;subtitle&gt;&quot; [&quot;&lt;2nd line&gt;&quot; [&quot;&lt;3rd 
line&gt;&quot; ... ] ]</kbd> 
+</div>
+<p class="requires">
+&bull;&nbsp;String arguments must be enclosed in double-quotes
+</p>
+
+<p>
+The subtitle string can be caps or caps/lower-case.  I recommend
+caps/lower case.
+</p>
+
+<p>
+SUBTITLE accepts multiple arguments, each surrounded
+by double-quotes.  Each argument is printed on a separate line,
+permitting you to create multi-line subtitles.
+</p>
+
+<p>
+If the optional argument, <kbd>COVER</kbd> or <kbd>DOC_COVER</kbd>,
+is given to SUBTITLE, the remaining string
+arguments represent the subtitle that will appear on cover or
+document cover pages (see the
+<a href="cover.html#cover-intro">Introduction to cover pages</a>
+for a description of the difference between &#8220;document
+covers&#8221; and &#8220;covers&#8221;).  Thus, it is possible to have
+differing subtitles appear on the document cover, the cover
+(&#8220;title&#8221;) page, and in the document header.  An extreme
+example would be:
+<br/>
+<span class="pre-in-pp">
+  .SUBTITLE "The Docheader Subtitle"
+  .SUBTITLE DOC_COVER "The Document Cover Subtitle"
+  .SUBTITLE COVER "The Cover Subtitle"
+</span>
+The first invocation of <kbd>.SUBTITLE</kbd> establishes the
+subtitle that appears in the docheader at the top of the first page
+of a document.  The second invocation establishes the subtitle that
+appears on the document cover; the third establishes the subtitle
+that appears on the cover (&#8220;title&#8221;) page.
+</p>
+
+<p>
+If you don&#8217;t require differing subtitles for doc cover and cover
+pages, <kbd>.SUBTITLE</kbd>, without the optional first argument, is
+sufficient, provided you give the word, <kbd>SUBTITLE</kbd>, as an
+argument to the macro
+<a href="cover.html#doc-cover">DOC_COVER</a>
+or
+<a href="cover.html#cover">COVER</a>
+</p>
+
+<!-- -AUTHOR- -->
+
+<div class="macro-id-overline">
+<h3 id="author" class="macro-id">AUTHOR</h3>
+</div>
+
+<div class="box-macro-args">
+Macro: <b>AUTHOR</b> <kbd class="macro-args">[COVER | DOC_COVER] 
&quot;&lt;author&gt;&quot; [ &quot;&lt;author2&gt;&quot; 
[&quot;&lt;author3&gt;&quot; ... ] ]</kbd>
+</div>
+
+<p class="alias" style="margin-bottom: 0;">
+<i>Alias:</i> <b>EDITOR</b>
+</p>
+<p class="requires">
+&bull;&nbsp;String arguments must be enclosed in double-quotes
+</p>
+
+<p>
+Each author string can hold as many names as you like, e.g.
+<br/>
+<span class="pre-in-pp" style="margin-bottom: -1em;">
+  .AUTHOR "Joe Blow"
+</span>
+or
+<br/>
+<span class="pre-in-pp" style="margin-top: -.5em;">
+  .AUTHOR "Joe Blow, Jane Doe" "John Hancock"
+</span>
+Mom prints each string that&#8217;s enclosed in double-quotes on a
+separate line in the
+<a href="definitions.html#docheader">docheader</a>,
+however only the first string appears in
+<a href="definitions.html#header">page headers</a>.
+If you want mom to put something else in the author part of page
+headers (say, just the last names of a document&#8217;s two
+authors), redefine the appropriate part of the header (see
+<a href="headfootpage.html#header-control">header/footer control</a>).
+</p>
+
+<p>
+The strings can be caps or caps/lower-case.  I recommend caps/lower
+case.
+</p>
+
+<p>
+If the optional argument, <kbd>COVER</kbd> or <kbd>DOC_COVER</kbd>,
+is given to AUTHOR, the remaining string arguments represent the
+author(s) that will appear on cover or document cover pages (see the
+<a href="cover.html#cover-intro">Introduction to cover pages</a>
+for a description of the difference between &#8220;document
+covers&#8221; and &#8220;covers&#8221;).  Thus, it is possible
+to have differing authors on the document cover, the cover
+(&#8220;title&#8221;) page, in the document first-page header and
+subsequent page headers/footers.  An example might be:
+<br/>
+<span class="pre-in-pp">
+  .AUTHOR "Joe Blow"
+  .EDITOR DOC_COVER "John Smith" "and" "Jane Doe"  \" EDITOR is an alias for 
AUTHOR
+  .AUTHOR COVER "Joe Blow" "(assisted by Jane Doe)"
+</span>
+The first invocation of <kbd>.AUTHOR</kbd> establishes the author
+that appears in the docheader at the top of the first page of
+a document and in subsequent page headers/footers.  The second
+invocation establishes the authors (editors, in this instance) that
+appear on the document cover; the third establishes the author(s)
+that appear(s) on the cover (&#8220;title&#8221;) page.
+</p>
+
+<p>
+If you don&#8217;t require differing authors for doc cover and cover
+pages, <kbd>.AUTHOR</kbd>, without the optional first argument, is
+sufficient, provided you give the word, <kbd>AUTHOR</kbd> as an
+argument to the macro
+<a href="cover.html#doc-cover">DOC_COVER</a>
+or
+<a href="cover.html#cover">COVER</a>
+</p>
+
+<!-- -CHAPTER- -->
+
+<div class="macro-id-overline">
+<h3 id="chapter" class="macro-id">CHAPTER</h3>
+</div>
+
+<div class="box-macro-args">
+Macro: <b>CHAPTER</b> <kbd class="macro-args">&lt;chapter number&gt;</kbd>
+</div>
+
+<p>
+The chapter number can be in any form you like&mdash;a digit, a roman
+numeral, a word.  If you choose
+<a href="#doctype">DOCTYPE CHAPTER</a>,
+mom prints whatever argument you pass CHAPTER beside the word,
+&#8220;Chapter&#8221;, as a single line
+<a href="definitions.html#docheader">docheader</a>.
+She also puts the same thing in the middle of
+<a href="definitions.html#header">page headers</a>.
+</p>
+
+<p>
+Please note that if your argument to CHAPTER runs to more than one
+word, you must enclose the argument in double-quotes.
+</p>
+
+<p>
+If you&#8217;re not using DOCTYPE CHAPTER, the macro can
+be used to identify any document as a chapter <i>for the purpose of
+prepending a chapter number to numbered head elements</i>, provided
+you pass it a
+<a href="definitions.html#numericargument">numeric argument</a>.
+See
+<a href="docelement.html#prefix-chapter-number">PREFIX_CHAPTER_NUMBER</a>.
+</p>
+
+<!-- -CHAPTER_STRING- -->
+
+<h3 id="chapter-string" class="docs">Chapter string</h3>
+
+<p>
+If you&#8217;re not writing in English, you can ask mom to use the
+word for &#8220;chapter&#8221; in your own language by telling her
+what it is with the CHAPTER_STRING macro, like this:
+<br/>
+<span class="pre">
+  .CHAPTER_STRING "Chapître"
+</span>
+</p>
+
+<p>
+You can also use CHAPTER_STRING if you want
+&#8220;CHAPTER&#8221; (all caps) instead of &#8220;Chapter&#8221;
+(caps/lowercase) in the doc- and page-headers.
+</p>
+
+<!-- -CHAPTER_TITLE- -->
+
+<div class="macro-id-overline">
+<h3 id="chapter-title" class="macro-id">CHAPTER_TITLE</h3>
+</div>
+
+<div class="box-macro-args">
+Macro: <b>CHAPTER_TITLE</b>  <kbd class="macro-args">&quot;&lt;chapter 
title&gt;&quot; [&quot;&lt;2nd line&gt;&quot; [&quot;&lt;3rd line&gt;&quot; ... 
] ]</kbd> 
+</div>
+<p class="requires">
+&bull;&nbsp;Arguments must be enclosed in double-quotes
+</p>
+
+<p>
+If, either in addition to or instead of &#8220;Chapter
+&lt;n&gt;&#8221; appearing at the top of chapters, you want your
+chapter to have a title, use CHAPTER_TITLE, with your title enclosed
+in double-quotes, like this:
+<br/>
+<span class="pre">
+  .CHAPTER_TITLE "The DMCA Nazis"
+</span>
+</p>
+
+<p>
+CHAPTER_TITLE accepts multiple arguments, each surrounded by
+double-quotes.  Each argument is printed on a separate line,
+permitting you to create multi-line chapter titles in your
+docheaders.
+</p>
+
+<p>
+If you&#8217;ve used
+<a href="#chapter">CHAPTER</a>
+to give the chapter a number, both &#8220;Chapter &lt;n&gt;&#8221;
+and the chapter title will appear at the top of the chapter, like
+this:
+<br/>
+<span class="pre-in-pp">
+       Chapter 1
+    The DMCA Nazis
+</span>
+In such a case, by default, only the chapter&#8217;s title will appear in
+the
+<a href="definitions.html#header">page headers</a>,
+not &#8220;Chapter &lt;n&gt;&#8221;.
+</p>
+
+<p>
+If you omit CHAPTER when setting up your reference macros, only the
+title will appear, both at the top of page one and in subsequent
+page headers.
+</p>
+
+<p>
+The style of the chapter title can be altered by
+<a href="docelement.html#docelement-control">control macros</a>,
+e.g. CHAPTER_TITLE_FAMILY, CHAPTER_TITLE_FONT, etc.  The default
+family, font and point size are Times Roman, Bold Italic, 4 points
+larger than
+<a href="definitions.html#running">running text</a>.
+</p>
+
+<!-- -DRAFT- -->
+
+<div class="macro-id-overline">
+<h3 id="draft" class="macro-id">DRAFT</h3>
+</div>
+
+<div class="box-macro-args">
+Macro: <b>DRAFT</b> <kbd class="macro-args">&lt;draft number&gt;</kbd>
+</div>
+
+<p>
+DRAFT only gets used with
+<a href="#copystyle">COPYSTYLE&nbsp;DRAFT</a>.
+If the COPYSTYLE is FINAL (the default), mom ignores DRAFT.  DRAFT
+accepts both alphabetic and numeric arguments, hence it&#8217;s
+possible to do either
+<br/>
+<span class="pre">
+  .DRAFT 2
+     or
+  .DRAFT Two
+</span>
+</p>
+
+<p>
+Mom prints the argument to <kbd>.DRAFT</kbd> (i.e. the draft number)
+beside the word &#8220;Draft&#8221; in the middle part of
+<a href="definitions.html#header">page headers</a>.
+</p>
+
+<div class="box-tip">
+<p class="tip">
+<span class="note">A small word of caution:</span>
+If your argument to <kbd>.DRAFT</kbd> is more than one word long,
+you must enclose the argument in double-quotes.
+</p>
+</div>
+
+<p>
+You may, if you wish, invoke <kbd>.DRAFT</kbd> without an
+argument, in which case, no draft number will be printed beside
+&#8220;Draft&#8221; in headers or footers.
+</p>
+
+<!-- -DRAFT_STRING- -->
+
+<h3 id="draft-string" class="docs">The draft string</h3>
+
+<p>
+If you&#8217;re not writing in English, you can ask mom
+to use the word for &#8220;draft&#8221; in your own language by
+telling her what it is with the DRAFT_STRING macro,
+like this:
+<br/>
+<span class="pre">
+  .DRAFT_STRING "Jet"
+</span>
+</p>
+
+<p>
+Equally, DRAFT_STRING can be used to roll your own solution to
+something other than the word &#8220;Draft.&#8221; For example, you
+might want &#8220;Trial run alpha-three&#8221; to appear in the
+headers of a draft version.  You&#8217;d accomplish this by doing
+<br/>
+<span class="pre">
+  .DRAFT alpha-three
+  .DRAFT_STRING "Trial run"
+</span>
+</p>
+
+<p>
+If you wanted only &#8220;Trial run&#8221; to appear, entering
+<kbd>.DRAFT</kbd> without an argument as well as
+<kbd>.DRAFT_STRING&nbsp;"Trial&nbsp;run"</kbd> is how you&#8217;d do it.
+</p>
+
+<div class="box-tip">
+<p class="tip">
+<span class="note">Note:</span>
+If you define both a blank <kbd>.DRAFT</kbd> and a blank
+<kbd>.DRAFT_STRING</kbd>, mom skips the draft field in headers
+entirely.  If this is what you want, this is also the only way
+to do it.  Simply omitting invocations of <kbd>.DRAFT</kbd> and
+<kbd>.DRAFT_STRING</kbd> will result in mom using her default, which
+is to print &#8220;Draft &lt;number&gt;&#8221;.
+</p>
+</div>
+
+<!-- -REVISION- -->
+
+<div class="macro-id-overline">
+<h3 id="revision" class="macro-id">REVISION</h3>
+</div>
+
+<div class="box-macro-args">
+Macro: <b>REVISION</b> <kbd class="macro-args">&lt;revision number&gt;</kbd>
+</div>
+
+<p>
+REVISION only gets used with
+<a href="#copystyle">COPYSTYLE DRAFT</a>.
+If the COPYSTYLE is FINAL (the default), mom ignores the REVISION
+macro. REVISION accepts both alphabetic and numeric arguments, hence
+it&#8217;s possible to do either
+<br/>
+<span class="pre" style="margin-bottom: -1em;">
+  .REVISION 2
+</span>
+or
+<span class="pre" style="margin-top: -.5em;">
+  .REVISION Two
+</span>
+</p>
+
+<p>
+Mom prints the revision number beside the shortform
+&#8220;Rev.&#8221; in the middle part of
+<a href="definitions.html#header">page headers</a>.
+</p>
+
+<div class="box-tip">
+<p class="tip">
+<span class="note">A small word of caution:</span>
+If your argument to <kbd>.REVISION</kbd> is more than one word long,
+you must enclose the argument in double-quotes.
+</p>
+</div>
+
+<p>
+You may, if you wish, invoke <kbd>.REVISION</kbd> without an
+argument, in which case, no revision number will be printed beside
+&quot;Rev.&quot; in headers or footers.
+</p>
+
+<!-- -REVISION_STRING- -->
+
+<h3 id="revision-string" class="docs">The revision string</h3>
+
+<p>
+If you&#8217;re not writing in English, you can ask mom
+to use the word for &#8220;revision,&#8221; or a shortform
+thereof, in your own language by telling her what it is with the
+REVISION_STRING macro, like this:
+<br/>
+<span class="pre">
+  .REVISION_STRING "Rév."
+</span>
+</p>
+
+<p>
+Additionally, you may sometimes want to make use of mom&#8217;s
+<a href="#copystyle">COPYSTYLE DRAFT</a>
+but not actually require any draft information.  For example,
+you might like mom to indicate only the revision number of
+your document.  The way to do that is to define an empty
+<kbd>.DRAFT</kbd> and <kbd>.DRAFT_STRING</kbd> in addition to
+<kbd>.REVISION</kbd>, like this:
+<br/>
+<span class="pre">
+  .DRAFT
+  .DRAFT_STRING
+  .REVISION 2
+</span>
+</p>
+
+<p>
+Equally, if you want to roll your own solution to what revision
+information appears in headers, you could do something like this:
+<br/>
+<span class="pre">
+  .DRAFT
+  .DRAFT_STRING
+  .REVISION "two-twenty-two"
+  .REVISION_STRING "Revision"
+</span>
+</p>
+
+<p>
+The above, naturally, has no draft information.  If you want to roll
+your own <kbd>.DRAFT</kbd> and/or <kbd>.DRAFT_STRING</kbd> as well,
+simply supply arguments to either or both.
+</p>
+
+<!-- -COPYRIGHT- -->
+
+<div class="macro-id-overline">
+<h3 id="copyright" class="macro-id">COPYRIGHT</h3>
+</div>
+
+<div class="box-macro-args">
+Macro: <b>COPYRIGHT</b> <kbd class="macro-args">[COVER | DOC_COVER] 
&quot;&lt;copyright info&gt;&quot;</kbd>
+</div>
+
+<p class="requires">
+&bull;&nbsp;Argument must be enclosed in double-quotes
+</p>
+
+<p>
+The argument passed to COPYRIGHT is only used on cover or doc cover
+pages, and then only if the argument COPYRIGHT is passed to
+<a href="cover.html#cover">COVER</a>
+or
+<a href="cover.html#doc-cover">DOC_COVER</a>.
+Do not include the copyright symbol in the argument passed to
+COPYRIGHT; mom puts it in for you.
+</p>
+
+<p>
+If the optional argument, <kbd>COVER</kbd> or <kbd>DOC_COVER</kbd>,
+is given to COPYRIGHT, the string argument represents the copyright
+information that will appear on cover or document cover pages (see
+the
+<a href="cover.html#cover-intro">Introduction to cover pages</a>
+for a description of the difference between &#8220;document
+covers&#8221; and &#8220;covers&#8221;).  Thus, it is possible to
+have differing copyright information on the document cover and on
+the cover (&#8220;title&#8221;) page.  An example might be:
+<br/>
+<span class="pre-in-pp">
+  .COPYRIGHT DOC_COVER "2010 John Smith and Jane Doe"
+  .COPYRIGHT COVER "2008 Joe Blow"
+</span>
+The first invocation of <kbd>.COPYRIGHT</kbd> establishes the
+copyright information that appears on the document cover; the second
+establishes the copyright information that appears on the cover
+(&#8220;title&#8221;) page.
+</p>
+
+<p>
+If you don&#8217;t require differing copyright information for
+doc cover and cover pages, <kbd>.COPYRIGHT</kbd>, without the
+optional first argument, is sufficient, provided you give the word,
+<kbd>COPYRIGHT</kbd>, as an argument to the macro
+<a href="cover.html#doc-cover">DOC_COVER</a>
+or
+<a href="cover.html#cover">COVER</a>
+</p>
+
+<!-- -MISC- -->
+
+<div class="macro-id-overline">
+<h3 id="misc" class="macro-id">MISC</h3>
+</div>
+
+<div class="box-macro-args">
+Macro: <b>MISC</b> <kbd class="macro-args">[COVER | DOC_COVER] 
&quot;&lt;argument 1&gt;&quot; [&quot;&lt;argument 2&gt;&quot; 
&quot;&lt;argument 3&gt;&quot; ...]</kbd>
+</div>
+
+<p class="requires">
+&bull;&nbsp;String arguments must be enclosed in double-quotes
+</p>
+
+<p>
+The argument(s) passed to MISC are only used on cover or doc cover
+pages, and then only if the argument <kbd>MISC</kbd> is passed to
+<a href="cover.html#cover">COVER</a>
+or
+<a href="cover.html#doc-cover">DOC_COVER</a>.
+MISC can contain any information you like.  Each argument appears on
+a separate line at the bottom of the cover or doc cover page.
+</p>
+
+<p>
+For example, if you&#8217;re submitting an essay where the prof has
+requested that you include the course number, his name and the date,
+you could do
+<br/>
+<span class="pre-in-pp">
+  .MISC "Music History 101" "Professor Hasbeen" "Dec. 24, 2010"
+</span>
+and the information would appear on the essay&#8217;s cover page.
+</p>
+
+<p>
+If the optional argument, <kbd>COVER</kbd> or <kbd>DOC_COVER</kbd>,
+is given to MISC, the string arguments represent the miscellaneous
+information that will appear on cover or document cover pages (see
+the
+<a href="cover.html#cover-intro">Introduction to cover pages</a>
+for a description of the difference between &#8220;document
+covers&#8221; and &#8220;covers&#8221;).  Thus, it is possible to
+have differing miscellaneous information on the document cover and
+on the cover (&#8220;title&#8221;) page.  An example might be:
+<br/>
+<span class="pre">
+  .MISC DOC_COVER "Music History 101" "Professor Hasbeen"
+  .MISC COVER "Spring Term Paper"
+</span>
+</p>
+
+<p>
+The first invocation of <kbd>.MISC</kbd> establishes the
+miscellaneous information that appears on the document cover; the
+second establishes the miscellaneous information that appears on the
+cover (&#8220;title&#8221;) page.
+</p>
+
+<p>
+If you don&#8217;t require differing miscellaneous information
+for doc cover and cover pages, <kbd>.MISC</kbd>, without the
+optional first argument, is sufficient, provided you give the word
+&#8220;MISC&#8221; as an argument to the macro
+<a href="cover.html#doc-cover">DOC_COVER</a>
+or
+<a href="cover.html#cover">COVER</a>
+</p>
+
+<!-- -COVER_TITLE- -->
+
+<div class="macro-id-overline">
+<h3 class="macro-id">COVERTITLE &amp; DOC_COVERTITLE</h3>
+</div>
+
+<div id="covertitle" class="box-macro-args">
+Macro: <b>COVERTITLE</b> <kbd class="macro-args">&quot;&lt;user defined cover 
page title&gt;&quot; [&quot;&lt;2nd line&gt;&quot; [&quot;&lt;3rd 
line&gt;&quot; ... ] ]</kbd> 
+</div>
+<p class="requires">
+&bull;&nbsp;Arguments must be enclosed in double-quotes
+</p>
+
+<div id="doc-covertitle" class="box-macro-args">
+Macro: <b>DOC_COVERTITLE</b> <kbd class="macro-args">&quot;&lt;user defined 
document cover page title&gt;&quot; [&quot;&lt;2nd line&gt;&quot; 
[&quot;&lt;3rd line&gt;&quot; ... ] ]</kbd> 
+</div>
+<p class="requires">
+&bull;&nbsp;Arguments must be enclosed in double-quotes
+</p>
+
+<p>
+The arguments passed to COVERTITLE or DOC_COVERTITLE are only
+used on cover or doc cover pages, and then only if the argument
+COVERTITLE is passed to
+<a href="cover.html#cover">COVER</a>
+or
+<a href="cover.html#doc-cover">DOC_COVER</a>.
+</p>
+
+<p>
+The only time you require a COVERTITLE or DOC_COVERTITLE is when
+none of the required first arguments to COVER or DOC_COVER fits
+your needs for the title you want to appear on cover (or doc cover)
+pages.
+</p>
+
+<p>
+COVERTITLE and DOC_COVERTITLE accept multiple arguments, each
+surrounded by double-quotes.  Each argument is printed on a separate
+line, permitting you to create multi-line titles on your cover
+and/or doc cover pages.
+</p>
+
+<div class="rule-short"><hr/></div>
+
+<!-- ======================================================================== 
-->
+
+<h2 id="docstyle-macros" class="macro-group">The docstyle macros</h2>
+
+<p>
+The docstyle macros tell mom what type of document you&#8217;re
+writing, whether you want the output typeset or &#8220;typewritten,
+double-spaced&#8221;, and whether you want a draft copy (with draft
+and revision information in the headers) or a final copy.
+</p>
+
+<div class="macro-list-container">
+<h3 id="index-docstyle" class="macro-list">Docstyle macros</h3>
+<ul class="macro-list">
+  <li><a href="#doctype">DOCTYPE</a>
+  <ul class="sublist"> 
+    <li><a href="#doctype-underline">DOCTYPE_UNDERLINE</a> &ndash; control 
DOCTYPE <kbd>NAMED</kbd> underlining</li>      
+  </ul></li>
+  <li><a href="#printstyle">PRINTSTYLE</a> &ndash; non-optional macro required 
for document processing
+  <ul class="sublist" style="line-height: 140%;">
+    <li><a href="#typeset-defaults">Defaults for PRINTSTYLE TYPESET</a></li>
+    <li><a href="#typewrite-defaults">Defaults for PRINTSTYLE TYPEWRITE</a>
+    <ul class="sublist sub">
+      <li><a href="#typewrite-control">PRINTSTYLE TYPEWRITE control macros</a> 
&ndash; underlining</li>
+    </ul></li>
+  </ul></li>
+  <li><a href="#copystyle">COPYSTYLE</a></li>
+</ul>
+</div>
+
+<!-- -DOCTYPE- -->
+
+<div class="macro-id-overline">
+<h3 id="doctype" class="macro-id">DOCTYPE</h3>
+</div>
+
+<div class="box-macro-args">
+Macro: <b>DOCTYPE</b> <kbd class="macro-args">DEFAULT | CHAPTER | NAMED 
&quot;&lt;name&gt;&quot; | LETTER</kbd>
+</div>
+
+<p>
+The arguments <kbd>DEFAULT,</kbd> <kbd>CHAPTER</kbd> and
+<kbd>NAMED</kbd> tell mom what to put in the
+<a href="definitions.html#docheader">docheader</a>
+and
+<a href="definitions.html#header">page headers</a>.
+<kbd>LETTER</kbd> tells her that you want to write a letter.
+</p>
+
+<p>
+Mom&#8217;s default DOCTYPE is <kbd>DEFAULT</kbd>.  If that&#8217;s
+what you want, you don&#8217;t have to give a DOCTYPE command.
+</p>
+
+<p>
+<kbd>DEFAULT</kbd> prints a
+<a href="definitions.html#docheader">docheader</a>
+containing the title, subtitle and author information given to the
+<a href="#reference-macros">reference macros</a>,
+and page headers with the author and title.  (See
+<a href="headfootpage.html#header-style">Default specs for headers</a>
+for how mom outputs each part of the page header.)
+</p>
+
+<p>
+<kbd>CHAPTER</kbd> prints &#8220;Chapter &lt;n&gt;&#8221; in place
+of a
+<a href="definitions.html#docheader">docheader</a>
+(&lt;n&gt; is what you gave to the
+<a href="#reference-macros">reference macro</a>,
+<kbd><a href="#chapter">CHAPTER</a></kbd>).
+If you give the chapter a title with
+<a href="#chapter-title">CHAPTER TITLE</a>,
+mom prints &#8220;Chapter &lt;n&gt;&#8221; and the
+title underneath.  If you omit the
+<a href="#chapter">CHAPTER</a>
+reference macro but supply a
+<a href="#chapter-title">CHAPTER_TITLE</a>,
+mom prints only the chapter title.
+</p>
+
+<div class="box-tip">
+<p class="tip">
+<span class="note">Note:</span>
+For backward compatibility with pre-1.1.5 versions of mom, you can
+also supply a chapter title by omitting the CHAPTER reference macro
+and supplying a chapter title with
+<a href="#chapter-string">CHAPTER_STRING</a>.)
+</p>
+</div>
+
+<p>
+The page headers in DOCTYPE <kbd>CHAPTER</kbd> contain the author,
+the title of the book (which you gave with
+<a href="#title">TITLE</a>),
+and &#8220;Chapter &lt;n&gt;&#8221; (or the chapter title).  See
+<a href="headfootpage.html#header-style">Default Specs for Headers</a>
+for mom&#8217;s default type parameters for each part of
+the page header.
+</p>
+
+<p>
+<kbd>NAMED</kbd> takes an additional argument: a name for this
+particular kind of document (e.g. outline, synopsis, abstract,
+memorandum), enclosed in double-quotes. <kbd>NAMED</kbd> is
+identical to <kbd>DEFAULT</kbd> except that mom prints the argument
+to <kbd>NAMED</kbd> beneath the
+<a href="definitions.html#docheader">docheader</a>,
+as well as in page headers.
+(See
+<a href="headfootpage.html#header-style">Default specs for headers</a>
+for how mom outputs each part of the page header.)
+</p>
+
+<p>
+Additionally, if you wish the name of this particular kind of
+document to be coloured, you can pass DOCTYPE <kbd>NAMED</kbd> a
+third (optional) argument: the name of a colour pre-defined (or
+&#8220;initialized&#8221;) with
+<a href="color.html#newcolor">NEWCOLOR</a>
+or
+<a href="color.html#xcolor">XCOLOR</a>.
+For example, if you have a doctype named &#8220;Warning&#8221;,
+and you&#8217;d like &#8220;Warning&#8221; to be in red, assuming you&#8217;ve
+pre-defined (or &#8220;initialized&#8221;) the color, red, this is
+what the DOCTYPE entry would look like:
+<br/>
+<span class="pre">
+  .DOCTYPE NAMED "Warning" red
+</span>
+</p>
+
+<div class="box-tip" style="margin-top: 1.5em;">
+<h3 id="doctype-underline" class="docs control">How to control DOCTYPE NAMED 
underlining</h3>
+
+<p style="tip">
+By default, the string passed to DOCTYPE <kbd>NAMED</kbd> is
+underlined in the docheader, and on document-cover pages and cover
+(&#8220;title&#8221;) pages.  (See the
+<a href="cover.html#intro">Introduction to covers</a>
+for the difference between &#8220;doc cover&#8221; and
+&#8220;cover&#8221; pages.)
+</p>
+
+<p>
+Formerly, this underlining was carved in stone.  As of version 1.5
+of mom, you can use the macro DOCTYPE_UNDERLINE to set the weight of
+the underline and its distance from where the doctype-name appears
+in the docheader (doc covers and covers handle underlining of the
+doctype-name differently; see
+<a href="cover.html#cover-underline">COVER_UNDERLINE</a>),
+or simply toggle doctype underlining on or off.  Mom&#8217;s default
+is to underline the doctype-name.
+</p>
+
+<p>
+The order of arguments is <kbd>weight</kbd>, optionally followed by
+<kbd>gap</kbd>, where &#8220;gap&#8221; is the distance from the
+<a href="definitions.html#baseline">baseline</a>
+of the doctype-name to the underline.
+</p>
+
+<p>
+The <kbd>weight</kbd> argument is given 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&#8217;s
+default for DOCTYPE <kbd>NAMED</kbd> underlining is 1/2 point.
+</p>
+
+<p>
+The <kbd>gap</kbd> argument can be given using any unit of measure,
+and must have the unit of measure appended to the argument.
+The distance of the gap is measured from the baseline of the
+DOCTYPE <kbd>NAMED</kbd> name to the upper edge of the underline.
+Mom&#8217;s default gap for named-doctype underlining is 2 points.
+</p>
+
+<p>
+As an example, supposed you want the doctype-name underlined in the
+docheader with a 2-point rule separated from the head by 3 points.
+The way to accomplish it is:
+<br/>
+<span class="pre-in-pp">
+  .DOCTYPE_UNDERLINE 2 3p
+</span>
+If you wanted the same thing, but were content with mom&#8217;s
+default gap of 2 points,
+<br/>
+<span class="pre-in-pp">
+  .DOCTYPE_UNDERLINE 4
+</span>
+would do the trick.
+</p>
+
+<p>
+If you merely want to toggle the underlining of
+the doctype-name in docheaders on or off, invoke
+<kbd>.DOCTYPE_UNDERLINE</kbd> by itself to turn the underlining on,
+or <kbd>.DOCTYPE_UNDERLINE&nbsp;OFF</kbd> (or NO, X, etc.)
+</p>
+
+<p class="tip-bottom">
+Please note that if you supply a weight to DOCTYPE_UNDERLINE, and
+optionally a gap, you also turn the underlining of the doctype-name
+in docheaders on; if this is not what you want, you must turn the
+underlining off manually afterwards.
+</p>
+</div>
+
+<p>
+<kbd>LETTER</kbd> tells mom you&#8217;re writing a letter.  See the
+section
+<a href="letters.html#letters">Writing Letters</a>
+for instructions on using mom to format letters.
+</p>
+
+<!-- -PRINTSTYLE- -->
+
+<div class="macro-id-overline">
+<h3 id="printstyle" class="macro-id">PRINTSTYLE</h3>
+</div>
+
+<div class="box-macro-args">
+Macro: <b>PRINTSTYLE</b> <kbd class="macro-args">TYPESET | TYPEWRITE [ 
SINGLESPACE ]</kbd>
+</div>
+
+<p class="requires">
+&bull;&nbsp;Required for document processing
+<br/>
+Must come before any changes to default document style
+</p>
+
+<p>
+PRINTSTYLE tells mom whether to typeset a document, or to print it
+out &#8220;typewritten, doubled-spaced&#8221;.
+</p>
+
+<div class="box-important">
+<p class="tip-top">
+<span class="important">Important:</span>
+<b>This macro may not be omitted.</b> In order for document
+processing to take place, mom requires a PRINTSTYLE.  If you
+don&#8217;t give one, mom will warn you on stderr and print a single
+page with a nasty message.
+</p>
+
+<p class="tip-bottom">
+Furthermore, PRINTSTYLE must come before any changes to mom&#8217;s
+default typestyle parameters.  (This applies primarily to, but is by
+no means restricted to, PRINTSTYLE <kbd>TYPESET</kbd>.) PRINTSTYLE
+sets up complete templates that include default papersize, margins,
+family, fonts, point sizes, and so on.  Therefore, changes to any
+aspect of document style must come afterwards.
+</p>
+</div>
+
+<p>
+<kbd>TYPESET</kbd>, as the argument implies, typesets
+documents (by default in Times Roman; see
+<a href="#typeset-defaults">TYPESET defaults</a>).
+You have full access to all the
+<a href="typesetting.html#macros-typesetting">typesetting macros</a>
+as well as the
+<a href="definitions.html#style-control">style control macros</a>
+of document processing.
+</p>
+
+<p>
+As mentioned above, PRINTSTYLE <kbd>TYPESET</kbd> must come before
+any changes to mom&#8217;s default typographic settings.  For
+example,
+<br/>
+<span class="pre-in-pp">
+  .PAPER A4
+  .LS 14
+  .PRINTSTYLE TYPESET
+</span>
+will not changes mom&#8217;s default paper size to A4,
+nor her default document leading 14 points, whereas
+<br/>
+<span class="pre-in-pp">
+  .PRINTSTYLE TYPESET
+  .PAPER A4
+  .LS 14
+</span>
+will.
+</p>
+
+<p>
+With <kbd>TYPEWRITE</kbd>, mom does her best to reproduce the look
+and feel of typewritten, double-spaced copy (see
+<a href="#typewrite-defaults">TYPEWRITE defaults</a>).
+<a href="docelement.html#docelement-control">Control macros</a>
+and
+<a href="typesetting.html#intro-macros-typesetting">typesetting macros</a>
+that alter family, font, point size, and
+<a href="definitions.html#leading">leading</a>
+are (mostly) ignored.  An important exception is
+<a href="headfootpage.html#hdrftr-global-size">HEADER_SIZE</a>
+(and, by extension, FOOTER_SIZE), which allows you to reduce the
+point size of headers/footers should they become too crowded.  Most
+of mom&#8217;s inlines affecting the appearance of type are also
+ignored
+(<kbd><a href="inlines.html#inline-size-mom">\*S[&lt;size&gt;]</a></kbd>
+is an exception; there may be a few others).
+</p>
+
+<p>
+In short, <kbd>TYPEWRITE</kbd> never produces effects
+other than those available on a typewriter.  Don&#8217;t be fooled
+by how brainless this sounds; mom is remarkably sophisticated when
+it comes to conveying the typographic sense of a document within the
+confines of <kbd>TYPEWRITE</kbd>.
+</p>
+
+<p>
+The primary uses of <kbd>TYPEWRITE</kbd> are: outputting hard
+copy drafts of your work (for editing) and producing documents
+for submission to publishers and agents who (wisely) insist on
+typewritten, double-spaced copy.  To get a nicely typeset version of
+work that&#8217;s in the submission phase of its life (say, to show
+fellow writers for critiquing), simply change <kbd>TYPEWRITE</kbd>
+to <kbd>TYPESET</kbd> and print out a copy.
+</p>
+
+<p>
+If, for some reason, you would prefer the output of
+<kbd>TYPEWRITE</kbd> single-spaced, pass PRINTSTYLE
+<kbd>TYPEWRITE</kbd> the optional argument, <kbd>SINGLESPACE</kbd>.
+</p>
+
+<div class="box-tip">
+<p class="tip">
+<span class="note">Note:</span>
+If you absolutely must have a leading other than typewriter double-
+or singlespaced, the only way to get it is with the
+<a href="#doc-lead">DOC_LEAD</a>
+macro, and then only if DOC_LEAD is set <i>before</i> you invoke the
+<a href="#start">START</a>
+macro.
+</p>
+</div>
+
+<div class="defaults-container">
+<h3 id="typeset-defaults" class="docs defaults" style="margin-top: 
0;">PRINTSTYLE TYPESET defaults</h3>
+<span class="pre defaults">
+  Family            = Times Roman
+  Point size        = 12.5
+  Paragraph leading = 16 points, adjusted
+  Fill mode         = justified
+  Hyphenation       = enabled
+                      max. lines = 2
+                      margin = 36 points
+                      interword adjustment = 1 point
+  Kerning           = enabled
+  Ligatures         = enabled
+  Smartquotes       = enabled
+  Word space        = groff default
+  Sentence space    = 0
+</span>
+</div>
+
+<div class="defaults-container">
+<h3 id="typewrite-defaults" class="docs defaults" style="margin-top: 
0;">PRINTSTYLE TYPEWRITE defaults</h3>
+<span class="pre defaults">
+  Family            = Courier
+  Italics           = underlined
+  Point size        = 12
+  Paragraph leading = 24 points, adjusted; 12 points for SINGLESPACE
+  Fill mode         = left
+  Hyphenation       = disabled
+  Kerning           = disabled
+  Ligatures         = disabled
+  Smartquotes       = disabled
+  Word space        = groff default
+  Sentence space    = groff default
+  Columns           = ignored
+</span>
+</div>
+
+<div class="box-tip" style="margin-top: 1.5em;">
+<h3 id="typewrite-control" class="docs control">PRINTSTYLE TYPEWRITE control 
macros (underlining)</h3>
+
+<p>
+In PRINTSTYLE <kbd>TYPEWRITE</kbd>, mom, by default, underlines
+anything that looks like italics.  This includes the
+<a href="typesetting.html#slant-inline"><kbd>\*[SLANT]</kbd></a>
+<a href="definitions.html#inlines">inline escape</a>
+for pseudo-italics.
+</p>
+
+<p>
+If you&#8217;d prefer that mom were less bloody-minded
+about pretending to be a typewriter (i.e. you&#8217;d like italics and
+pseudo-italics to come out as italics), use the control macros
+<br/>
+<span class="pre-in-pp">
+  .ITALIC_MEANS_ITALIC
+</span>
+and
+<span class="pre-in-pp">
+  .SLANT_MEANS_SLANT
+</span>
+Neither requires an argument.
+</p>
+
+<p>
+Although it&#8217;s unlikely, should you wish to reverse
+the sense of these macros in the midst of a document,
+<kbd>.UNDERLINE_ITALIC</kbd> and <kbd>.UNDERLINE_SLANT</kbd> restore
+underlining of italics and pseudo-italics.
+</p>
+
+<p>
+Additionally, by default, mom underlines
+<a href="definitions.html#quotes">quotes</a>
+(but not
+<a href="definitions.html#blockquotes">blockquotes</a>)
+in PRINTSTYLE <kbd>TYPEWRITE</kbd>.  If you don&#8217;t like this
+behaviour, turn it off with
+<br/>
+<span class="pre">
+  .UNDERLINE_QUOTES OFF
+</span>
+</p>
+
+<p>
+To turn underlining of quotes back on, use UNDERLINE_QUOTES without
+an argument.
+</p>
+
+<p class="tip-bottom">
+While most of the
+<a href="docelement.html#docelement-control">control macros</a>
+have no effect on <b>PRINTSTYLE TYPEWRITE</b>, there
+is an important exception:
+<a href="headfootpage.html#hdrftr-global-size">HEADER_SIZE</a>
+(and by extension, FOOTER_SIZE).  This is
+particularly useful for reducing the point size of
+headers/footers should they become crowded (quite likely to
+happen if the title of your document is long and your
+<kbd><a href="#copystyle">COPYSTYLE</a></kbd>
+is DRAFT).
+</p>
+</div>
+
+<!-- -COPYSTYLE- -->
+
+<div class="macro-id-overline">
+<h3 id="copystyle" class="macro-id">COPYSTYLE</h3>
+</div>
+
+<div class="box-macro-args">
+Macro: <b>COPYSTYLE</b> <kbd class="macro-args">DRAFT | FINAL</kbd>
+</div>
+
+<p>
+Mom&#8217;s default COPYSTYLE is <kbd>FINAL</kbd>, so you
+don&#8217;t have to use this macro unless you want to.
+</p>
+
+<p>
+COPYSTYLE <kbd>DRAFT</kbd> exhibits the following behaviour:
+</p>
+<ol style="margin-top: -.5em;">
+  <li>Documents start on page 1, whether or not you
+      request a different starting page number with
+      <a href="headfootpage.html#pagenumber">PAGENUMBER</a>.
+  </li>
+  <li>Page numbers are set in lower case roman numerals.</li>
+  <li>The draft number supplied by 
+      <a href="#draft">DRAFT</a>
+      and a revision number, if supplied with 
+      <a href="#revision">REVISION</a>
+      (see
+      <a href="#reference-macros">reference macros</a>),
+      appear in the centre part of
+      <a href="definitions.html#header">page headers</a>
+      (or footers, depending on which you&#8217;ve selected) along with
+      any other information that normally appears there.
+  </li>
+</ol>
+
+<div class="box-important">
+<p class="tip">
+<span class="important">Important:</span>
+If you define your own centre part for page headers with
+<a href="headfootpage.html#hdrftr-center">HEADER_CENTER</a>,
+no draft and/or revision number will appear there.  If you want
+draft and revision information in this circumstance, use
+<a href="headfootpage.html#draft-with-pagenumber">DRAFT_WITH_PAGENUMBER</a>.
+</p>
+</div>
+
+<p>
+COPYSTYLE <kbd>FINAL</kbd> differs from <kbd>DRAFT</kbd> in that:
+</p>
+<ol style="margin-top: -.5em;">
+  <li>It respects the starting page number you give the document.</li>
+  <li>Page numbers are set in normal (Arabic) digits.</li>
+  <li>No draft or revision number appears in the page headers.</li>
+</ol>
+
+<div class="box-tip">
+<p id="copystyle-note" class="tip">
+<span class="note">Note:</span>
+The centre part of page headers can get crowded, especially with
+<a href="docprocessing.html#doctype">DOCTYPE <kbd>CHAPTER</kbd></a>
+and
+<a href="docprocessing.html#doctype">DOCTYPE <kbd>NAMED</kbd></a>,
+when the COPYSTYLE is <kbd>DRAFT</kbd>.  Three mechanisms are
+available to overcome this problem.  One is to reduce the overall
+size of headers (with
+<a href="headfootpage.html#hdrftr-global-size">HEADER_SIZE</a>).
+Another, which only works with
+<a href="docprocessing.html#printstyle">PRINTSTYLE <kbd>TYPESET</kbd></a>,
+is to reduce the size of the header&#8217;s centre part only (with
+<a href="headfootpage.html#_size">HEADER_CENTER_SIZE</a>).
+And finally, you can elect to have the draft/revision information
+attached to page numbers instead of having it appear in the centre
+of page headers (see
+<a href="headfootpage.html#draft-with-pagenumber">DRAFT_WITH_PAGENUMBER</a>).
+</p>
+</div>
+
+<div class="rule-short"><hr/></div>
+
+<!-- ======================================================================== 
-->
+
+<h2 id="start-macro" class="macro-group">Initiate document processing</h2>
+
+<p>
+In order to use mom&#8217;s document element macros (tags), you have
+to tell her you want them.  The macro to do this is
+<a href="#start">START</a>.
+</p>
+
+<p>
+START collects the information you gave mom in the setup section at
+the top of your file (see
+<a href="#docprocessing-tut">Tutorial &ndash; Setting up a mom document</a>),
+merges it with her defaults, sets up headers and page numbering,
+and prepares mom to process your document using the document
+element tags.  No document processing takes place until you invoke
+<kbd>.START</kbd>.
+</p>
+
+<!-- -START- -->
+
+<div class="macro-id-overline">
+<h3 id="start" class="macro-id">START</h3>
+</div>
+
+<div class="box-macro-args">
+Macro: <b>START</b>
+</div>
+<p class="requires">
+&bull;&nbsp;Required for document processing
+</p>
+
+<p>
+START takes no arguments.  It simply instructs mom to begin document
+processing.  If you don&#8217;t want document processing (i.e. you
+only want the
+<a href="typesetting.html#macros-typesetting">typesetting macros</a>),
+don&#8217;t use START.
+</p>
+
+<p>
+At a barest minimum before START, you must enter a
+<a href="#printstyle">PRINTSTYLE</a>
+command.
+</p>
+
+<div class="rule-short"><hr/></div>
+
+<!-- ======================================================================== 
-->
+
+<h2 id="style-before-start" class="macro-group">Establishing type and 
formatting parameters before START</h2>
+
+<p>
+In the third (optional) part of setting up a document (see
+<a href="#docprocessing-tut">Tutorial &ndash; Setting up a mom document</a>),
+you can use the
+<a href="typesetting.html">typesetting macros</a>
+to change mom&#8217;s document-wide defaults for margins,
+line length, family, base point size,
+<a href="definitions.html#leading">leading</a>,
+and justification style.
+</p>
+
+<p>
+Two additional style concerns have to be addressed here (i.e. in
+macros before
+<a href="#start">START</a>):
+changes to the
+<a href="definitions.html#docheader">docheader</a>,
+and whether you want you want the document&#8217;s nominal leading
+adjusted to fill pages fully to the bottom margin.
+</p>
+
+<div class="macro-list-container" style="margin-top: 2em;">
+<h3 id="index-style-before-start" class="macro-list">Type &amp; formatting 
parameters before START</h3>
+<ul class="macro-list">
+  <li><a href="#type-before-start">Behaviour of the typesetting macros before 
START</a>
+  <ul class="sublist" style="line-height: 120%; margin-bottom: .25em;">
+    <li><a href="#meanings">List of meanings</a></li>
+    <li><a href="#lrc-note">Special note on LEFT, RIGHT and CENTER</a></li>
+    <li><a href="#include">Including (sourcing) style sheets and files</a></li>
+    <li><a href="#color">Initializing colors</a></li>
+  </ul></li>
+  <li><a href="#doc-lead-adjust">DOC_LEAD_ADJUST</a> &ndash; adjust 
linespacing to fill pages and align bottom margins</li>
+  <li><a href="#docheader">DOCHEADER</a>
+  <ul class="sublist" style="line-height: 120%;">
+    <li><a href="#docheader-control">Docheader control</a></li>
+  </ul></li>
+  <li><a href="#columns">COLUMNS</a>
+  <ul class="sublist" style="line-height: 120%;">
+    <li><a href="#col-next">COL_NEXT</a></li>
+    <li><a href="#col-break">COL_BREAK</a></li>
+  </ul></li>
+</ul>
+</div>
+
+<h3 id="type-before-start" class="docs">Behaviour of the typesetting macros 
before START</h3>
+
+<p>
+From time to time (or maybe frequently), you&#8217;ll want the
+overall look of a document to differ from mom&#8217;s defaults.
+Perhaps you&#8217;d like her to use a different
+<a href="definitions.html#family">family</a>,
+or a different overall
+<a href="definitions.html#leading">leading</a>,
+or have different left and/or right page margins.
+</p>
+
+<p>
+To accomplish such alterations, use the appropriate
+<a href="typesetting.html#macros-typesetting">typesetting macros</a>
+(listed below) after
+<a href="#printstyle">PRINTSTYLE</a>
+and before
+<a href="#start">START</a>.
+</p>
+
+<p>
+More than one user has, quite understandably, not fully grasped the
+significance of the preceding sentence.  The part they&#8217;ve missed is
+<i>after</i> PRINTSTYLE.
+</p>
+
+<p>
+Changes to any aspect of the default look and/or formatting of a mom
+document must come after PRINTSTYLE.  For example, it might seem
+natural to set up page margins at the very top of a document with
+<br/>
+<span class="pre-in-pp">
+  .L_MARGIN 1i
+  .R_MARGIN 1.5i
+</span>
+However, when you invoke <kbd>.PRINTSTYLE</kbd>, those margins
+will be overridden.  The correct place to set margins&mdash;and
+all other changes to the look of a document&mdash;is <i>after</i>
+PRINTSTYLE.
+</p>
+
+<div class="box-tip">
+<p class="tip">
+<span class="note">Note:</span>
+Don&#8217;t use the macros listed in
+<a href="#doc-param-macros">Changing document-wide typesetting parameters 
after START</a>
+prior to START; they are exclusively for use
+afterwards.
+</p>
+</div>
+
+<div id="meanings" class="defaults-container">
+<h3 class="docs defaults" style="margin-top: 0;">Meanings</h3>
+<p style="margin-left: 9px; margin-top: -.25em;">
+When used before START, the
+<a href="typesetting.html#macros-typesetting">typesetting macros</a>,
+below have the following meanings:
+<br/>
+<span class="pre">
+  L_MARGIN       Left margin of pages, including headers/footers
+  R_MARGIN       Right margin of pages, including headers/footers
+  T_MARGIN       The point at which running text (i.e. not
+                 headers/footers or page numbers) starts on each
+                 page
+  B_MARGIN*      The point at which running text (i.e. not
+  (see note)     headers/footers or page numbers) ends on each page
+
+  PAGE           If you use PAGE, its final four arguments have the
+                 same meaning as L_ R_ T_ and B_MARGIN (above).
+
+  LL             The line length for everything on the page;
+                 equivalent to setting the right margin with
+                 R_MARGIN
+  FAMILY         The family of all type in the document
+  PT_SIZE        The point size of type in paragraphs; mom uses
+                 this to calculate automatic point size changes
+                 (e.g. for heads, footnotes, quotes, headers, etc)
+  LS/AUTOLEAD**  The leading used in paragraphs; all leading and
+                 spacing of running text is calculated from this
+
+  QUAD/JUSTIFY   Affects paragraphs only
+  LEFT***        No effect
+  RIGHT***       No effect
+  CENTER***      No effect
+
+------
+  *See <a href="headfootpage.html#footer-margin">FOOTER MARGIN AND BOTTOM 
MARGIN</a> for an important warning
+ **See <kbd><a href="#doc-lead-adjust">DOC_LEAD_ADJUST</a></kbd>
+***See <a href="#lrc-note">Special note</a>
+</span>
+</p>
+</div>
+
+<p>
+Other macros that deal with type style, or refinements thereof
+(<b>KERN, LIGATURES, HY, WS, SS,</b> etc.), behave normally.
+It is not recommended that you set up tabs or indents prior to
+START.
+</p>
+
+<p>
+If you want to change any of the basic parameters (above)
+<i>after</i> START and have them affect a document globally (as if
+you&#8217;d entered them <i>before</i> START), you must use the macros
+listed in
+<a href="#doc-param-macros">Changing document-wide style parameters after 
START</a>.
+</p>
+
+<h4 id="lrc-note" class="docs">Special note on LEFT, RIGHT and CENTER prior to 
START</h4>
+
+<p>
+In a word, these three macros have no effect on document processing
+when invoked prior to START.
+</p>
+
+<p>
+All mom&#8217;s document element tags (PP, HEAD, BLOCKQUOTE,
+FOOTNOTE, etc.) except
+<a href="docelement.html#quote">QUOTE</a>
+set a
+<a href="definitions.html#filled">fill mode</a>
+as soon as they&#8217;re invoked.  If you wish to turn fill mode off
+for the duration of any tag (with
+<a href="typesetting.html#lrc">LEFT, RIGHT or CENTER</a>)
+you must do so immediately after invoking the tag.  Furthermore,
+the change affects <i>only</i> the current invocation of the tag.
+Subsequent invocations of the same tag for which you want the same
+change require that you invoke <kbd>.LEFT</kbd>, <kbd>.RIGHT</kbd>
+or <kbd> CENTER</kbd> immediately after every invocation of the tag.
+</p>
+
+<!-- -INCLUDE- -->
+
+<h4 id="include" class="docs">Including (sourcing) style sheets and files</h4>
+
+<p>
+If you routinely make the same changes to mom&#8217;s defaults in
+order to create similar documents in a similar style&mdash;in other
+words, you need a template&mdash; you can create style-sheet files
+and include, or "source", them into your mom documents with the
+macro, INCLUDE.  The right place for such style sheets is after
+<a href="#printstyle">PRINTSTYLE</a>
+and before
+<a href="#start">START</a>.
+</p>
+
+<p>
+Say, for example, in a particular kind of document, you always
+want main heads set in Helvetica Bold Italic, flush left,
+with no underscore.  You&#8217;d create a file, let&#8217;s call it
+<kbd>head-template</kbd>, in which you&#8217;d place the pertinent HEAD
+control macros.
+<br/>
+<span class="pre-in-pp">
+  .HEAD_FAMILY    H
+  .HEAD_FONT      BI
+  .HEAD_QUAD      L
+  .HEAD_UNDERLINE OFF
+</span>
+Then, in the preliminary document set-up section of your main file,
+you&#8217;d include the style sheet, or template, like this:
+<br/>
+<span class="pre-in-pp">
+  .TITLE      "Sample Document
+  .AUTHOR     "Joe Blow
+  .PRINTSTYLE TYPESET
+  \#
+  .INCLUDE    head-template
+  \#
+  .START
+</span>
+
+The blank comment lines ( <kbd>\#</kbd> ) aren&#8217;t required, but
+they do make your file(s) easier to read.
+</p>
+
+<p>
+If the file to be included is in the same directory as the file
+you&#8217;re working, you simply enter the filename after
+<kbd>.INCLUDE</kbd>.  If the file&#8217;s in another directory, you must
+provide a full path name to it.  For example, if you&#8217;re working in
+a directory called <kbd>/home/joe/stories</kbd> and your
+style-sheet is in <kbd>/home/joe/style-sheets</kbd>, the above
+example would have to look like this:
+<br/>
+<span class="pre-in-pp">
+  .TITLE      "Sample Document
+  .AUTHOR     "Joe Blow
+  .PRINTSTYLE TYPESET
+  \#
+  .INCLUDE    /home/joe/style-sheets/head-template
+  \#
+  .START
+</span>
+</p>
+
+<p>
+INCLUDE is not restricted to style sheets or templates.  You can
+include any file at any point into a document, provided the file
+contains only text and valid groff or mom formatting commands.
+Neither is INCLUDE restricted to use with mom&#8217;s document
+processing macros.  You can use it in plain typeset documents as
+well.
+</p>
+
+<div class="box-tip">
+<p class="tip">
+<span class="experts">Experts:</span>
+INCLUDE is an alias for the groff request, <kbd>.so</kbd>.  Mix 'n'
+match with impunity.
+</p>
+</div>
+
+<!-- -COLOUR- -->
+
+<h4 id="color" class="docs">Initializing colours</h4>
+
+<p>
+Although it doesn&#8217;t really matter where you define/initialize
+colours for use in document processing (see
+<a href="color.html#newcolor">NEWCOLOR</a>
+and
+<a href="color.html#xcolor">XCOLOR</a>
+in the section
+<a href="color.html#color-intro">Coloured text</a>),
+I recommend doing so before you begin document processing with
+<kbd><a href="#start">START</a></kbd>.
+</p>
+
+<p>
+The macro,
+<a href="color.html#color">COLOR</a>,
+and the
+<a href="definitions.html#inlines">inline escape</a>,
+<a href="color.html#color-inline"><kbd>\[&lt;colorname&gt;]</kbd></a>,
+can be used at any time during document processing for occasional
+colour effects.  However, consistent and reliable colourizing of
+various document elements (the docheader, heads, linebreaks,
+footnotes, pagenumbers, and so on) must be managed through the use
+of the
+<a href="docelement.html#docelement-control">document element control 
macros</a>.
+</p>
+
+<div class="box-tip">
+<p class="tip">
+<span class="note">Note:</span>
+If you plan to have mom generate a
+<a href="docelement.html#toc">table of contents</a>,
+do not embed colour
+<a href="definitions.html#inlines">inline escapes</a>
+(<a href="color.html#color-inline"><kbd>\[&lt;colorname&gt;]</kbd></a>)
+in the
+<a href="definitions.html#stringargument">string arguments</a>
+given to any of the
+<a href="docprocessing.html#reference-macros">reference macros</a>,
+nor in the string arguments given to
+<a href="docelement.html#head">HEAD</a>,
+<a href="docelement.html#subhead">SUBHEAD</a>
+or
+<a href="docelement.html#parahead">PARAHEAD</a>.
+Use, rather, the
+<a href="definitions.html#controlmacro">control macros</a>
+mom provides to automatically colourize these
+elements.
+</p>
+</div>
+
+<!-- -DOC LEAD ADJUST- -->
+
+<div class="macro-id-overline">
+<h3 id="doc-lead-adjust" class="macro-id">Adjust linespacing to fill pages and 
align bottom margins</h3>
+</div>
+
+<div class="box-macro-args">
+Macro: <b>DOC_LEAD_ADJUST</b> <kbd class="macro-args">toggle</kbd>
+</div>
+
+<p class="requires">
+&bull;&nbsp;Must come after
+<a href="typesetting.html#ls"><span class="normal">LS</span></a>
+or
+<a href="typesetting.html.#autoloead"><span class="normal">AUTOLEAD</span></a>
+and before
+<a href="#start"><span class="normal">START</span></a>
+</p>
+
+<p>
+DOC_LEAD_ADJUST is a special macro to adjust document
+<a href="definitions.html#leading">leading</a>
+so that bottom margins fall precisely where you expect.
+</p>
+
+<p>
+When you invoke <kbd>.DOC_LEAD_ADJUST</kbd>, mom takes the number
+of lines that fit on the page at your requested leading, then
+incrementally adds
+<a href="definitions.html#units">machine units</a>
+to the leading until the maximum number of lines at the new leading
+that fit on the page coincides perfectly with the bottom margin of
+<a href="definitions.html#running">running text</a>.
+</p>
+
+<p>
+In most instances, the difference between the requested lead and
+the adjusted lead is unnoticeable, and since in almost all cases
+adjusted leading is what you want, it&#8217;s mom&#8217;s default
+and you don't have to invoke it explicitly.
+</p>
+
+<p>
+However, should you not want adjusted document leading, you must
+turn it off manually, like this:
+<br/>
+<span class="pre">
+  .DOC_LEAD_ADJUST OFF
+</span>
+</p>
+
+<p>
+If you set the document leading prior to START with
+<a href="typesetting.html#leading">LS</a>
+or
+<a href="typesetting.html#autolead">AUTOLEAD</a>,
+DOC_LEAD_ADJUST&nbsp;<kbd>OFF</kbd> must come afterwards, like
+this:
+<br/>
+<span class="pre-in-pp">
+  .LS 12
+  .DOC_LEAD_ADJUST OFF
+</span>
+In this scenario, the maximum number of lines that fit on a page at
+a
+<a href="definitions.html#leading">leading</a>
+of 12
+<a href="definitions.html#picaspoints">points</a>
+determine where mom ends a page.  The effect will be that last lines
+usually fall (slightly) short of the &#8220;official&#8221; bottom
+margin.
+</p>
+
+<p>
+In
+<a 
href="docprocessing.html#printstyle">PRINTSTYLE</a>&nbsp;<kbd>TYPEWRITE</kbd>,
+the leading is always adjusted and can&#8217;t be turned off.
+</p>
+
+<div class="box-tip">
+<p class="tip-top">
+<span class="note">Note:</span>
+DOC_LEAD_ADJUST, if used, must be invoked after
+<a href="typesetting.html#leading">LS</a>
+or
+<a href="typesetting.html#autolead">AUTOLEAD</a>
+and before
+<a href="#start">START</a>.
+</p>
+
+<p class="tip-bottom">
+<span class="additional-note">Additional note:</span>
+Even if you disable DOC_LEAD_ADJUST, mom will still adjust the
+leading of endnotes pages and toc pages.  See
+<a href="docelement.html#endnote-lead">ENDNOTE_LEAD</a>
+and
+<a href="docelement.html#toc-lead">TOC_LEAD</a>
+for an explanation of how to disable this default behaviour.
+</p>
+</div>
+
+<!-- -DOCHEADER- -->
+
+<div class="macro-id-overline">
+<h3 id="docheader" class="macro-id">Managing the docheader</h3>
+</div>
+
+<div class="box-macro-args">
+Macro: <b>DOCHEADER</b> <kbd class="macro-args">&lt;toggle&gt; [ distance to 
advance from top of page ]</kbd>
+</div>
+
+<p class="requires">
+&bull;&nbsp;Must come before
+<a href="#start"><span class="normal">START</span></a>; <kbd><span 
class="normal">distance</span></kbd> requires a <a 
href="definitions.html#unitofmeasure">unit of measure</a>
+</p>
+
+<p>
+By default, mom prints a
+<a href="definitions.html#docheader">docheader</a>
+on the first page of any document (see
+<a href="#docheader-desc">below</a>
+for a description of the docheader).  If you don&#8217;t want a docheader,
+turn it off with
+<br/>
+<span class="pre-in-pp">
+  .DOCHEADER OFF
+</span> 
+DOCHEADER is a toggle macro, so the argument doesn&#8217;t
+have to be OFF; it can be anything you like.
+</p>
+
+<p>
+If you turn the docheader off, mom, by default, starts
+the running text of your document on the same top
+<a href="definitions.html#baseline">baseline</a>
+as all subsequent pages.  If you&#8217;d like her to start at a different
+vertical position, give her the distance you&#8217;d like as a second
+argument.
+<br/>
+<span class="pre-in-pp">
+  .DOCHEADER OFF 1.5i
+</span>
+This starts the document 1.5 inches from the top of the page PLUS
+whatever spacing adjustment mom has to make in order to ensure that
+the first baseline of running text falls on a &#8220;valid&#8221;
+baseline (i.e. one that ensures that the bottom margin of the first
+page falls where it should).  The distance is measured from the top
+edge of the paper to the
+<a href="definitions.html#baseline">baseline</a>
+of the first line of type.
+</p>
+
+<div class="box-tip">
+<p class="tip">
+<span class="tip">Tip:</span>
+Since no document processing happens until you invoke
+<a href="#start"><kbd>.START</kbd></a>&mdash;including
+anything to do with docheaders&mdash;you can
+typeset your own docheader prior to START (if
+you don&#8217;t like the way mom does things) and use
+<kbd>.DOCHEADER&nbsp;OFF</kbd> with its optional distance
+argument to ensure that the body of your document starts where
+you want.  You can even insert a PostScript image file (see <a
+href="docelement.html#pspic">PSPIC)</a>.
+</p>
+</div>
+
+<!-- DOCHEADER CONTROL -->
+
+<h3 id="docheader-control" class="docs">Docheader control: How to change the 
look of docheaders</h3>
+
+<p>
+In
+<a href="#printstyle">PRINTSTYLE <kbd>TYPEWRITE</kbd></a>,
+the look of docheaders is carved in stone.  In
+<a href="#printstyle">PRINTSTYLE <kbd>TYPESET</kbd></a>,
+however, you can make a lot of changes.  Macros that alter
+docheaders must come before
+<a href="#start">START</a>.
+</p>
+
+<h4 id="docheader-desc" class="docs">Docheader description</h4>
+
+<p>
+A typeset docheader has the following characteristics:
+</p>
+<div class="box-code" style="margin-left: 24px;">
+<span class="pre" style="color: #302419;">
+    TITLE       bold, 3.5 points larger than running text (not necessarily 
caps)
+   Subtitle     medium, same size as running text
+      by        medium italic, same size as running text
+   Author(s)    medium italic, same size as running text
+
+(Document type) bold italic, underscored, 3 points larger than running text
+
+</span>
+</div>
+
+<p>
+Or, if the
+<a href="#doctype">DOCTYPE</a>
+is <kbd>CHAPTER</kbd>,
+</p>
+<div class="box-code" style="margin-left: 24px;">
+<span class="pre" style="color: #302419;">
+ Chapter &lt;n&gt;   bold, 4 points larger than running text
+Chapter Title  bold italic, 4 points larger than running text
+
+</span>
+</div>
+
+<p>
+The
+<a href="definitions.html#family">family</a>
+is the prevailing family of the whole document.  Title, subtitle,
+author and document type are what you supply with the
+<a href="#reference-macros">reference macros</a>.
+Any you leave out will not appear; mom will compensate:
+
+</p>
+
+<div class="box-tip">
+<p class="tip">
+<span class="note">Note:</span>
+If your DOCTYPE is <kbd>CHAPTER</kbd> and you have both &#8220;Chapter
+&lt;n&gt;&#8221; and a &#8220;Chapter Title&#8221; (as above), mom
+inserts a small amount of whitespace between them, equal to
+one-quarter of the <a href="definitions.html#leading">leading</a> in
+effect.  If this doesn&#8217;t suit you, you can alter the space by
+including the
+<a href="definitions.html#inlines">inline escapes</a>,
+<a href="inlines.html#up"><kbd>\*[UP]</kbd></a>
+or
+<a href="inlines.html#down"><kbd>\*[DOWN]</kbd></a>,
+in the argument you pass to
+<a href="#chapter-title">CHAPTER_TITLE</a>,
+like this:
+<br/>
+<span class="pre-in-pp" style="margin-bottom: -1em;">
+  .CHAPTER_TITLE "\*[DOWN 2p]Why Not Patent Calculus?"
+</span>
+or
+<span class="pre-in-pp" style="margin-top: -.5em;">
+  .CHAPTER_TITLE "\*[UP 2p]Why Not Patent Calculus?"
+</span>
+</p>
+</div>
+
+<div class="macro-list-container">
+<h3 id="index-docheader-control" class="macro-list">Docheader control</h3>
+<ol class="macro-list">
+  <li><a href="#change-start">Change the starting position of the 
docheader</a></li>
+  <li><a href="#docheader-quad">Change quad direction the entire 
docheader</a></li>
+  <li><a href="#docheader-family">Change the family of the entire 
docheader</a></li>
+  <li><a href="#change-family">Change the family of individual docheader 
elements</a></li>
+  <li><a href="#change-font">Change the font of individual docheader 
elements</a></li>
+  <li><a href="#change-size">Adjust the size of docheader elements</a></li>
+  <li><a href="#adjust-leading">Adjust the docheader leading</a></li>
+  <li><a href="#docheader-color">Change the colour of the entire 
docheader</a></li>
+  <li><a href="#change-color">Change the colour of the individual docheader 
elements</a></li>
+  <li><a href="#change-attribute">Change the attribution string 
(&#8220;by&#8221;)</a></li>
+</ol>
+</div>
+
+<h4 id="change-start" class="docs">1. Change the starting position of the 
docheader</h4>
+
+<p>
+By default, a docheader starts on the same
+<a href="definitions.html#baseline">baseline</a>
+as
+<a href="definitions.html#running">running text</a>.
+If you&#8217;d like it to start somewhere else, use the macro,
+DOCHEADER_ADVANCE, and give it the distance you want (measured from
+the top edge of the paper to the first baseline of the docheader),
+like this:
+<br/>
+<span class="pre-in-pp">
+    .DOCHEADER_ADVANCE 4P
+</span>
+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
+<a href="headfootpage.html#headers">HEADERS</a>
+are <kbd>OFF</kbd>, mom&#8217;s normal top margin for
+<a href="definitions.html#running">running text</a>
+(7.5
+<a href="definitions.html#picaspoints">picas</a>)
+changes to 6 picas (visually approx. 1 inch).  Since the first
+baseline of the docheader falls on the same baseline as the first
+line of running text (on pages after page 1), you might find the
+docheaders a bit high when headers are off.  Use DOCHEADER_ADVANCE
+to place them where you want.
+</p>
+</div>
+
+<h4 id="docheader-quad" class="docs">2. Change the quad direction of the 
docheader</h4>
+
+<p>
+By default, mom centers the docheader.  If you&#8217;d prefer to
+have your docheaders set flush left or right, or need to restore
+the default centering, invoke <kbd>.DOCHEADER_QUAD</kbd> with the
+quad direction you want, either <kbd>LEFT</kbd> (or <kbd>L</kbd>),
+<kbd>RIGHT</kbd> (or <kbd>R</kbd>) or <kbd>CENTER</kbd> (or
+<kbd>C</kbd>).
+</p>
+
+<h4 id="docheader-family" class="docs">3. Change the family of the entire 
docheader</h4>
+
+<p>
+By default, mom sets the docheader in the same
+family used for 
+<a href="definitions.html#running">running text</a>.
+If you&#8217;d prefer to have your docheaders set in a different
+family, invoke <kbd>.DOCHEADER_FAMILY</kbd> with the family you
+want.  The argument to DOCHEADER_FAMILY is the same as for
+<a href="typesetting.html#family">FAMILY</a>.
+</p>
+
+<p>
+For example, mom&#8217;s default family for running text is Times
+Roman.  If you&#8217;d like to keep that default, but have the
+docheaders set entirely in Helvetica,
+<br/>
+<span class="pre-in-pp">
+  .DOCHEADER_FAMILY H
+</span>
+is how you&#8217;d do it.
+</p>
+
+<p>
+Please note that if you use DOCHEADER_FAMILY, you can still alter
+the family of individual parts of the docheader with the macros
+listed
+<a href="#change-family">here</a>.
+</p>
+
+<h4 id="change-family" class="docs">4. Change the family of individual 
docheader elements</h4>
+
+<p>
+The following macros let you change the
+<a href="definitions.html#family">family</a>
+of each docheader element separately:
+</p>
+<ul style="list-style-type: none; margin: -.5em;">
+  <li>Macro: <b>TITLE_FAMILY</b> <kbd 
class="macro-args">&lt;family&gt;</kbd></li>
+  <li>Macro: <b>CHAPTER_TITLE_FAMILY</b> <kbd 
class="macro-args">&lt;family&gt;</kbd></li>
+  <li>Macro: <b>SUBTITLE_FAMILY</b> <kbd 
class="macro-args">&lt;family&gt;</kbd></li>
+  <li>Macro: <b>AUTHOR_FAMILY</b> <kbd 
class="macro-args">&lt;family&gt;</kbd></li>
+  <li>Macro: <b>DOCTYPE_FAMILY</b> <kbd class="macro-args">&lt;family&gt;</kbd>
+      (if <a href="#doctype">DOCTYPE</a> is <kbd>NAMED</kbd>)
+  </li>
+</ul>
+
+<p>
+Simply pass the appropriate macro the family you want, just as you
+would with
+<a href="typesetting.html#family">FAMILY</a>.
+</p>
+
+<h4 id="change-font" class="docs">5. Change the font of individual docheader 
elements</h4>
+
+<p>
+The following macros let you change the
+<a href="definitions.html#font">font</a>
+of each docheader element separately:
+</p>
+<ul style="list-style-type: none; margin: -.5em;">
+  <li>Macro: <b>TITLE_FONT</b> <kbd class="macro-args">R | B | I | 
BI</kbd></li>
+  <li>Macro: <b>CHAPTER_TITLE_FONT</b> <kbd class="macro-args">R | B | I | 
BI</kbd></li>
+  <li>Macro: <b>SUBTITLE_FONT</b> <kbd class="macro-args">R | B | I | 
BI</kbd></li>
+  <li>Macro: <b>AUTHOR_FONT</b> <kbd class="macro-args">R | B | I | 
BI</kbd></li>
+  <li>Macro: <b>DOCTYPE_FONT</b> <kbd class="macro-args">R | B | I | BI</kbd>
+      (if <a href="#doctype">DOCTYPE</a> is <kbd>NAMED</kbd>)
+  </li>
+</ul>
+
+<p>
+Simply pass the appropriate macro the font you want. <kbd>R, B,
+I</kbd> and <kbd>BI</kbd> have the same meaning as they do for
+<a href="typesetting.html#font">FT</a>.
+</p>
+
+<h4 id="change-size" class="docs">6. Adjust the size of individual docheader 
elements</h4>
+
+<p>
+The following macros let you adjust the point size of each docheader
+element separately.
+</p>
+
+<p>
+Mom calculates the point size of docheader elements from the point
+size of paragraphs in running text, so you must prepend a + or -
+sign to the argument.  Points is assumed as the
+<a href="definitions.html#unitofmeasure">unit of measure</a>,
+so there&#8217;s no need to append a unit to the argument.
+Fractional point sizes are allowed.
+</p>
+
+<ul style="list-style-type: none; margin: -.5em;">
+  <li>Macro: <b>TITLE_SIZE</b> <kbd class="macro-args">&lt;+/-points&gt;</kbd>
+      <br/>
+      &nbsp;&nbsp;&nbsp;default = +3.5 (+4 if docheader title is &quot;Chapter 
&lt;n&gt;&quot;)
+  </li>
+  <li>Macro: <b>.CHAPTER_TITLE_SIZE</b> <kbd 
class="macro-args">&lt;+/-points&gt;</kbd>
+      <br/>
+      &nbsp;&nbsp;&nbsp;default = +4
+  </li>
+  <li>Macro: <b>.SUBTITLE_SIZE</b> <kbd 
class="macro-args">&lt;+/-points&gt;</kbd>
+      <br/>
+      &nbsp;&nbsp;&nbsp;default = +0
+  </li>
+  <li>Macro: <b>.AUTHOR_SIZE</b> <kbd 
class="macro-args">&lt;+/-points&gt;</kbd>
+      <br/>
+      &nbsp;&nbsp;&nbsp;default = +0
+  </li>
+  <li>Macro: <b>.DOCTYPE_SIZE</b> <kbd 
class="macro-args">&lt;+/-points&gt;</kbd>
+      (if <a href="#doctype">DOCTYPE</a> is <kbd>NAMED</kbd>)
+      <br/>
+      &nbsp;&nbsp;&nbsp;default = +3
+  </li>
+</ul>
+
+<p>
+Simply pass the appropriate macro the size adjustment you want.
+</p>
+
+<h4 id="adjust-leading" class="docs">7. Adjust the docheader leading</h4>
+
+<p>
+The
+<a href="definitions.html#leading">leading</a>
+of docheaders is the same as running text.  If you&#8217;d like your
+docheaders to have a different leading, say, 2 points more than the
+lead of running text, use:
+<br/>
+<span class="pre-in-pp">
+  .DOCHEADER_LEAD +2
+</span>
+Since the leading of docheaders is calculated from the lead of running
+text, a + or - sign is required before the argument (how much to add
+or subtract from the lead of running text).  No 
+<a href="definitions.html#unitofmeasure">unit of measure</a>
+is required; points is assumed.
+</p>
+
+<h4 id="docheader-color" class="docs">8. Change the colour of the entire 
docheader</h4>
+
+<p>
+If you want to colourize the entire docheader:
+<br/>
+<span class="pre-in-pp">
+  .DOCHEADER_COLOR <kbd class="macro-args">&lt;color name&gt;</kbd>
+</span>
+You must pre-define (or &#8220;initialize&#8221;) the colour with
+<a href="color.html#newcolor">NEWCOLOR</a>
+or
+<a href="color.html#xcolor">XCOLOR</a>.
+</p>
+
+
+<h4 id="change-color" class="docs">9. Change the colour of the docheader 
elements individually</h4>
+
+<p>
+The following macros let you change the colour of each
+docheader element separately.  You must pre-define (or
+&#8220;initialize&#8221;) the colour with
+<a href="color.html#newcolor">NEWCOLOR</a>
+or
+<a href="color.html#xcolor">XCOLOR</a>.
+</p>
+<ul style="list-style-type: none; margin: -.5em;">
+  <li>Macro: <b>TITLE_COLOR</b> <kbd 
class="macro-args">&lt;colorname&gt;</kbd></li>
+  <li>Macro: <b>CHAPTER_TITLE_COLOR</b> <kbd 
class="macro-args">&lt;colorname&gt;</kbd>
+  <ul style="list-style-type: disc; margin-left: -.5em;">
+    <li>Note: <b>CHAPTER_TITLE_COLOR</b> is needed only if you supply both a
+        <a href="#chapter">CHAPTER</a>
+        reference macro and a
+        <a href="#chapter-title">CHAPTER_TITLE</a>
+        macro.  Otherwise, TITLE_COLOR takes care of colorizing the
+        chapter header.
+    </li>
+  </ul></li>
+  <li>Macro: <b>SUBTITLE_COLOR</b> <kbd 
class="macro-args">&lt;colorname&gt;</kbd></li>
+  <li>Macro: <b>ATTRIBUTE_COLOR</b> <kbd 
class="macro-args">&lt;colorname&gt;</kbd>
+      (the &#8220;by&#8221; string preceding author[s] name[s])
+  </li>
+  <li>Macro: <b>AUTHOR_COLOR</b> <kbd 
class="macro-args">&lt;colorname&gt;</kbd></li>
+  <li>Macro: <b>DOCTYPE_COLOR</b> <kbd class="macro-args"> 
&lt;colorname&gt;</kbd>
+      (if <a href="#doctype">DOCTYPE</a> is <kbd>NAMED</kbd>)
+  </li>
+</ul>
+
+<p>
+It is not recommended that you embed colour (with the
+<a href="definitions.html#inlines">inline escape</a>,
+<a href="color.html#color-inline"><kbd>\*[&lt;colorname&gt;]</kbd></a>)
+in the strings passed to TITLE, CHAPTER_TITLE, SUBTITLE, AUTHOR or
+the name you give DOCTYPE <kbd>NAMED</kbd>.  The strings passed to
+these macros are used to generate page
+<a href="definitions.html#header">headers</a>
+and
+<a href="definitions.html#footer">footers</a>,
+with the result that an embedded colour will cause the string to be
+colourized in headers and/or footers as well.  (If you want headers
+or footers colourized, or parts thereof, use the header/footer
+control macros.)
+</p>
+
+<h4 id="change-attribute" class="docs">10. Change the attribution string 
(&#8220;by&#8221;)</h4>
+
+<p>
+If you&#8217;re not writing in English, you can change what mom
+prints where &#8220;by&#8221; appears in docheaders.  For example,
+<br/>
+<span class="pre-in-pp">
+  .ATTRIBUTE_STRING "par"
+</span>
+changes &#8220;by&#8221; to &#8220;par&#8221;.  ATTRIBUTE_STRING
+can also be used, for example, to make the attribution read
+&quot;Edited by&quot;.
+</p>
+
+<p>
+If you don&#8217;t want an attribution string at all, simply pass
+ATTRIBUTE_STRING an empty argument, like this:
+<br/>
+<span class="pre-in-pp">
+  .ATTRIBUTE_STRING ""
+</span>
+Mom will deposit a blank line where the attribution string normally
+appears.
+</p>
+
+<p>
+If the optional argument, <kbd>COVER</kbd> or <kbd>DOC_COVER</kbd>,
+is given to ATTRIBUTE_STRING, the string argument represents the
+attribution string that will appear on cover or document cover pages
+(see the
+<a href="cover.html#cover-intro">Introduction to cover pages</a>
+for a description of the difference between &#8220;document
+covers&#8221; and &#8220;covers&#8221;).  Thus, it is possible to
+have different attribution strings on the document cover page, the
+cover (&#8220;title&#8221;) page, and in the first-page docheader.
+An extreme example would be:
+<br/>
+<span class="pre-in-pp">
+  .ATTRIBUTE_STRING ""
+  .ATTRIBUTE_STRING DOC_COVER "Edited by"
+  .ATTRIBUTE_STRING COVER "by"
+</span>
+The first invocation of <kbd>.ATTRIBUTE_STRING</kbd> establishes a
+blank attribution string that will be incorporated in the first-page
+docheader.  The second will print &#8220;Edited by&#8221; on the
+document cover; the third will print &#8220;by&#8221; on the cover
+(&#8220;title&#8221;) page.
+</p>
+
+<p>
+If you don&#8217;t require differing attribute strings for
+doc cover pages, cover pages, or the first-page docheader,
+<kbd>.ATTRIBUTE_STRING</kbd>, without either of the optional first
+arguments, is sufficient.
+</p>
+
+<div class="box-tip">
+<p class="tip">
+<span class="note">Note:</span>
+The type specs for the attribution line in docheaders are the
+same as for the author line.  Although it&#8217;s highly unlikely
+you&#8217;ll want the attribution line in a different family, font,
+or point size, you can make such changes using
+<a href="definitions.html#inlines">inline escapes</a>
+in the argument to ATTRIBUTE_STRING.  For example,
+<br/>
+<span class="pre-in-pp">
+  .ATTRIBUTE_STRING "\f[HBI]\*[SIZE -2p] by \*[SIZE +2p]\*[PREV]"
+</span>
+would set &#8220;by&#8221; in Helvetica bold italic, 2 points
+smaller than normal.
+</p>
+</div>
+
+<div class="rule-short"><hr/></div>
+
+<!-- -COLUMNS- -->
+
+<h2 id="columns-intro" class="docs">Setting documents in columns</h2>
+
+<p>
+Setting documents in columns is easy with mom.  All you have to do
+is is say how many columns you want and how much space you want
+between them (the
+<a href="definitions.html#gutter">gutters</a>).
+That&#8217;s it. Mom takes care of everything else, from soup to
+nuts.
+</p>
+
+<h3 class="docs">Some words of advice</h3>
+
+<p>
+If you want your type to achieve a pleasing
+<a href="definitions.html#just">justification</a>
+or
+<a href="definitions.html#rag">rag</a>
+in columns, reduce the point size of type (and probably the
+<a href="definitions.html#leading">leading</a>
+as well).  Mom&#8217;s default document point size is 12.5, which
+works well across her default 39
+<a href="definitions.html#picaspoints">pica</a>
+full page line length, but with even just two columns on a page, the
+default point size is awkward to work with.
+</p>
+
+<p>
+Furthermore, you&#8217;ll absolutely need to reduce the indents for
+<a href="docelement.html#epigraph-control">epigraphs</a>,
+<a href="docelement.html#quote-general">quotes</a>,
+and
+<a href="docelement.html#blockquote-general">blockquotes</a>
+(and probably the
+<a href="docelement.html#para-indent">paragraph first-line indent</a>
+as well).
+</p>
+
+<!-- -COLUMN- -->
+
+<div class="macro-id-overline">
+<h3 id="columns" class="macro-id">COLUMNS</h3>
+</div>
+
+<div class="box-macro-args">
+Macro: <b>COLUMNS</b> <kbd class="macro-args">&lt;number of columns&gt; 
&lt;width of gutters&gt;</kbd>
+</div>
+
+<p class="requires">
+&bull;&nbsp;Should be the last macro before START
+<br/>
+
+<i>The second argument requires a <a 
href="definitions.html#unitofmeasure">unit of measure</a></i>
+</p>
+
+<p>
+COLUMNS takes two arguments: the number of columns you want on
+document pages, and the width of the
+<a href="definitions.html#gutter">gutter</a>
+between them.  For example, to set up a page with two columns
+separated by an 18 point gutter, you&#8217;d do
+<br/>
+<span class="pre-in-pp">
+  .COLUMNS 2 18p
+</span>
+Nothing to it, really.  However, as noted above, COLUMNS should
+always be the last document setup macro prior to
+<a href="#start">START</a>.
+</p>
+
+<div class="box-tip">
+<p class="tip">
+<span class="note">Note:</span>
+Mom ignores columns completely
+when the
+<a href="#printstyle">PRINTSTYLE</a>
+is <kbd>TYPEWRITE</kbd>.  The notion of typewriter-style
+output in columns is just too ghastly for her to bear.
+</p>
+</div>
+
+<h3 class="docs">Using tabs when COLUMNS are enabled</h3>
+
+<p>
+Mom&#8217;s tabs (both
+<a href="typesetting.html#typesetting-tabs">typesetting tabs</a>
+and
+<a href="typesetting.html#string-tabs">string tabs</a>)
+behave as you&#8217;d expect during document processing, even
+when COLUMNS are enabled.  Tab structures set up during document
+processing carry over from page to page and column to column.
+</p>
+
+<!-- -BREAKING COLUMNS- -->
+
+<h3 id="breaking-columns" class="docs">Breaking columns manually</h3>
+
+<p>
+Mom takes care of breaking columns when they reach the bottom
+margin of a page.  However, there may be times you want to break
+the columns yourself.  There are two macros for breaking columns
+manually: COL_NEXT and COL_BREAK.
+</p>
+
+<div id="col-next" class="box-macro-args">
+Macro: <b>COL_NEXT</b>
+</div>
+
+<p>
+<kbd>.COL_NEXT</kbd> breaks the line just before it,
+<a href="definitions.html#quad">quads</a>
+it left (assuming the type is justified or quad left), and moves over
+to the top of the next column.  If the column happens to be the last
+(rightmost) one on the page, mom starts a new page
+at the &quot;column 1&quot; position.  This is the macro to use when
+you want to start a new column after the end of a paragraph.
+</p>
+
+<div id="col-break" class="box-macro-args">
+Macro: <b>COL_BREAK</b>
+</div>
+
+<p>
+<kbd>.COL_BREAK</kbd> is almost the same as <kbd>.COL_NEXT</kbd>,
+except that instead of breaking and quadding the line preceding it,
+mom breaks and spreads it (see
+<a href="typesetting.html#spread">SPREAD</a>).
+Use this macro whenever you need to start a new column in the middle
+of a paragraph.
+</p>
+
+<div class="box-important">
+<p class="tip">
+<span class="important">Warning:</span>
+If you need COL_BREAK in the middle of a blockquote or (god help
+you) an epigraph, you must do the following in order for COL_BREAK
+to work:
+<br/>
+<span class="pre-in-pp">
+  .SPREAD
+  \!.COL_BREAK
+</span>
+</p>
+</div>
+
+<div class="rule-short"><hr/></div>
+
+<!-- ======================================================================== 
-->
+
+<!-- *** -->
+
+
+<h2 id="style-after-start" class="macro-group">Changing basic type and 
formatting parameters after START</h2>
+
+<ul id="changing-basic-type">
+  <li><a href="#behaviour">Behaviour of the typesetting macros during document 
processing</a>
+  <ul style="margin-left: -.5em;">
+    <li><a href="#behaviour-specific">Effect of specific typesetting 
macros</a></li>
+  </ul></li>
+  <li><a href="#tb-margins">Top and bottom margins in document 
processing</a></li>
+  <li><a href="#space">Inserting space at the top of a new page</a>
+  <ul style="margin-left: -.5em;">
+    <li><a href="#add-space">ADD_SPACE</a></li>
+  </ul></li>
+</ul>
+
+<div class="rule-medium"><hr/></div>
+
+<h3 id="behaviour" class="docs">Behaviour of the typesetting macros during 
document processing</h3>
+
+<p>
+During document processing, most of the
+<a href="typesetting.html#macros-typesetting">typesetting macros</a>
+affect type in the document globally.  For example, if you turn
+kerning off, pairwise kerning is disabled not only in paragraphs,
+but also in headers, footers, quotes, and so on.
+</p>
+
+<p>
+Typesetting macros that alter margins and line lengths affect
+<a href="definitions.html#running">running text</a>
+globally (or at least try to), but leave headers/footers and
+footnotes alone.  (To indent footnotes, see the full explanation of
+the
+<a href="docelement.html#footnote">FOOTNOTE</a>
+macro.)
+</p>
+
+<p>
+Mom&#8217;s tabs (both
+<a href="typesetting.html#typesetting-tabs">typesetting tabs</a>
+and
+<a href="typesetting.html#string-tabs">string tabs</a>)
+behave as expected in running text during document processing.  Tab
+structures that do not exceed the line length of running text are
+preserved sensibly from page to page, and, if
+<a href="docprocessing.html#columns">COLUMNS</a>
+are enabled, from column to column.
+</p>
+
+<p>
+Some typesetting macros, however, when used during document
+processing, behave in special ways.  These are the macros that deal
+with the basic parameters of type style: horizontal and vertical
+margins, line length,
+<a href="definitions.html#family">family</a>,
+<a href="definitions.html#font">font</a>,
+<a href="definitions.html#ps">point size</a>,
+<a href="definitions.html#leading">leading</a>,
+and
+<a href="definitions.html#quad">quad</a>.
+</p>
+
+<p>
+Mom assumes that any changes to these parameters stem from a
+temporary need to set type in a style different from that provided
+by mom&#8217;s
+<a href="docelement.html#index-docelement">document element tags</a>.
+In other words, you need to do a bit of creative typesetting in the
+middle of a document.
+</p>
+
+<p>
+The following lists those typesetting macros whose behaviour during
+document processing requires some explanation.
+(Please refer to
+<a href="#tb-margins">Top and bottom margins in document processing</a>
+for information on how mom interprets
+<a href="typesetting.html#t-margin">T_MARGIN</a>
+and
+<a href="typesetting.html#b-margin">B_MARGIN</a>
+in document processing.  Additionally, see
+<a href="#add-space">ADD_SPACE</a>
+if you encounter the problem of trying to get mom to put space at
+the tops of pages after the first.)
+</p>
+<div id="behaviour-specific" class="box-code" style="margin-left: 24px;">
+<span class="pre" style="color: #302419;">
+  MACRO       EFFECT DURING DOCUMENT PROCESSING
+  -----       ---------------------------------
+
+  L_MARGIN    &bull;The left margin of all running text
+               assumes the new value.
+
+              &bull;The line length remains unaltered.
+
+              &bull;The header and footer left margin
+               remain at the current document default.
+
+              (You won&#8217;t use this often by itself.  Most
+               likely, you&#8217;ll use it in combination with
+               R_MARGIN or LL.)
+
+  R_MARGIN    &bull;The right margin of all running text
+               assumes the new value.  In other words,
+               the line length is altered.
+
+              &bull;The header and footer right margin
+               remain at the current document default.
+
+  LL          &bull;The line length of all running text
+               is set to the new value.
+
+              &bull;The header and footer line length remain
+               at the current document default.
+
+  FAMILY      &bull;Changes family for the duration of the
+               current tag only.  As soon as another document
+               element tag is invoked, the family reverts to
+               the current default for the new tag.
+
+  FT          &bull;Changes font for the duration of the
+               current tag only.  As soon as another document
+               element tag is entered, the font reverts
+               to the current default for the new tag.
+
+               N.B. &mdash; \&bull;[SLANT] and \&bull;[BOLDER] affect
+               paragraph text, and remain in effect for all
+               paragraphs until turned off.  If you want to
+               use them in a macro that takes a string
+               argument, include the escape in the string.
+               \&bull;[COND] and \&bull;[EXT] behave similarly.
+
+  PT_SIZE     &bull;Changes point size for the duration of the
+               current tag only.  As soon as another document
+               element tag is entered, the point size reverts
+               to the current document default for the new
+               tag.
+
+  LS          &bull;Changes line space for the duration of the
+               current tag only.  As soon as another document
+               element tag is entered, the line space reverts
+               to the current document default for the new
+               tag.
+
+               Using LS to temporarily change leading within
+               a document will almost certainly result in a
+               bottom margin that doesn&#8217;t align with
+               the bottom margin of subsequent pages.  You&#8217;ll
+               need to use the SHIM macro to get mom back on
+               track when you&#8217;re ready to return to the
+               document&#8217;s default leading.
+
+  QUAD        &bull;Changes quad for the duration of the
+               current tag only.  As soon as another document
+               element tag is entered, the quad reverts to
+               the current document default for the new
+               tag.
+
+               N.B. &mdash; Line-for-line quadding macros
+               (LEFT, CENTER, RIGHT) are also temporary,
+               overridden by the QUAD value of any subsequent
+               document element tag.
+</span>
+</div>
+
+<h3 id="tb-margins" class="docs" style="margin-top: 1.5em;">Top and bottom 
margins in document processing</h3>
+
+<p>
+Normally, mom establishes the top and bottom
+margins of
+<a href="definitions.html#running">running text</a>
+in documents from the values of <b>HEADER_MARGIN +
+HEADER_GAP</b> and <b>FOOTER_MARGIN + FOOTER_GAP</b>
+respectively.  However, if you invoke
+<a href="typesetting.html#t-margin">T_MARGIN</a>
+or
+<a href="typesetting.html#b-margin">B_MARGIN</a>
+either before or after
+<a href="docelement.html#start">START</a>,
+they set the top and bottom margins of running text irrespective of
+HEADER_GAP and FOOTER_GAP.
+</p>
+
+<p>
+Put another way, in document processing, T_MARGIN
+and B_MARGIN set the top and bottom margins of
+running text, but have no effect on the placement of
+<a href="definitions.html#header">headers</a>,
+<a href="definitions.html#footer">footers</a>,
+or page numbers.
+</p>
+
+<!-- ==================================================================== -->
+
+<h3 id="space" class="docs">Inserting space at the top of a new page</h3>
+
+<p>
+Occasionally, you may want to insert space before the start of
+<a href="definitions.html#running">running text</a>
+on pages after the first.
+</p>
+
+<p>
+You might have tried using
+<a href="typesetting.html#ald">ALD</a>
+or
+<a href="typesetting.html#space">SPACE</a>
+and found it did nothing.  This is because mom normally inhibits
+any extra space before the start of running text on pages after the
+first.
+</p>
+
+<p>
+If you need the space, you must use the macro, ADD_SPACE, in
+conjuction with
+<a href="typesetting.html#newpage">NEWPAGE</a>.
+</p>
+
+<!-- -ADD_SPACE- -->
+
+<div class="macro-id-overline">
+<h3 id="add-space" class= "macro-id">ADD_SPACE</h3>
+</div>
+
+<div class="box-macro-args">
+Macro: <b>ADD_SPACE</b> <kbd class="macro-args">&lt;amount of space&gt;</kbd>
+</div>
+
+<p class="requires">
+&bull;&nbsp;Requires a <a href="definitions.html#unitofmeasure">unit of 
measure</a>
+</p>
+
+<p>
+ADD_SPACE takes as its single argument the distance
+you want mom to advance from the normal
+baseline position at the top of any page after the first
+(i.e. the one on which the docheader is normally printed).  A
+<a href="definitions.html#unitofmeasure">unit of measure</a> is
+required.
+</p>
+
+<p>
+For example, say you wanted to insert 2 inches of space before the
+start of
+<a href="definitions.html#running">running text</a>
+on a page other than the first.  You&#8217;d accomplish it with
+<br/>
+<span class="pre-in-pp">
+  .NEWPAGE
+  .ADD_SPACE 2i
+</span>
+which would terminate your current page, break to a new page, print
+the header (assuming headers are on) and insert 2 inches of space
+before the start of running text.
+</p>
+
+<p>
+Since adding space in this way is almost sure to disrupt mom&#8217;s
+ability to guarantee perfectly flush bottom margins, I highly
+recommend using the
+<a href="docprocessing.html#shim">SHIM</a>
+macro immediately after ADD_SPACE.
+</p>
+
+<!-- *** -->
+<h2 id="intro-doc-param" class="macro-group">Changing basic type and 
formatting parameters after START</h2>
+
+<p>
+In the normal course of things, you establish the basic type
+parameters of a document prior to invoking
+<a href="#start">START</a>,
+using the
+<a href="typesetting.html#macros-typesetting">typesetting macros</a>
+(<b>L_MARGIN, FAMILY, PT_SIZE, LS,</b> etc).  After
+START, you <i>must</i> use the following macros to make
+global changes to the basic type parameters of a document.
+</p>
+
+<div class="macro-list-container">
+<h3 id="index-doc-param" class="macro-list">Post-START global style change 
macros</h3>
+<ul class="macro-list">
+  <li><a href="#doc-left-margin">DOC_LEFT_MARGIN</a></li>
+  <li><a href="#doc-right-margin">DOC_RIGHT_MARGIN</a></li>
+  <li><a href="#doc-line-length">DOC_LINE_LENGTH</a></li>
+  <li><a href="#doc-family">DOC_FAMILY</a></li>
+  <li><a href="#doc-pt-size">DOC_PT_SIZE</a></li>
+  <li><a href="#doc-lead">DOC_LEAD</a></li>
+  <li><a href="#doc-lead-adjust">DOC_LEAD_ADJUST</a></li>
+  <li><a href="#doc-quad">DOC_QUAD</a></li>
+</ul>
+</div>
+
+<!-- -DOC_LEFT_MARGIN -->
+
+<div class="macro-id-overline">
+<h3 id="doc-left-margin" class="macro-id">DOC_LEFT_MARGIN</h3>
+</div>
+
+<div class="box-macro-args">
+Macro: <b>DOC_LEFT_MARGIN</b> <kbd class="macro-args">&lt;left margin&gt;</kbd>
+</div>
+
+<p class="requires">
+&bull;&nbsp;Requires a <a href="definitions.html#unitofmeasure">unit of 
measure</a>
+</p>
+
+<h4 class="docs doc-param-macros">Arguments and behaviour</h4>
+
+<ul class="doc-param-macros">
+  <li>the argument is the same as for
+      <a href="typesetting.html#l-margin">L_MARGIN</a>
+  </li>
+  <li>changes all left margins to the new value</li>
+  <li>the line length remains the same (i.e. the right margin
+      shifts when you change the left margin)
+  </li>
+</ul>
+
+<!-- -DOC_RIGHT_MARGIN -->
+
+<div class="macro-id-overline">
+<h3 id="doc-right-margin" class="macro-id">DOC_RIGHT_MARGIN</h3>
+</div>
+
+<div class="box-macro-args">
+Macro: <b>DOC_RIGHT_MARGIN</b> <kbd class="macro-args">&lt;right 
margin&gt;</kbd>
+</div>
+
+<p class="requires">
+&bull;&nbsp;Requires a <a href="definitions.html#unitofmeasure">unit of 
measure</a>
+</p>
+
+<h4 class="docs doc-param-macros">Arguments and behaviour</h4>
+
+<ul class="doc-param-macros">
+  <li>the argument is the same as for
+      <a href="typesetting.html#r-margin">R_MARGIN</a>
+  </li>
+  <li>changes all right margins, including
+      <a href="definitions.html#docheader">docheaders</a>,
+      headers (or footers) and page numbering to the new value;
+      for changing the right margin of
+      <a href="definitions.html#running">running text</a>
+      only, use
+      <a href="typesetting.html#r-margin">R_MARGIN</a>
+      (see
+      <a href="#behaviour">typesetting macros during
+      document processing</a>,
+      entry for R_MARGIN)
+  </li>
+  <li>all mom commands that include a right indent calculate
+      the indent from the new value
+  </li>
+</ul>
+
+<!-- -DOC_RIGHT_MARGIN -->
+
+<div class="macro-id-overline">
+<h3 id="doc-line-length" class="macro-id">DOC_LINE_LENGTH</h3>
+</div>
+
+<div class="box-macro-args">
+Macro: <b>DOC_LINE_LENGTH</b> <kbd class="macro-args">&lt;length&gt;</kbd>
+</div>
+
+<p class="requires">
+&bull;&nbsp;Requires a <a href="definitions.html#unitofmeasure">unit of 
measure</a>
+</p>
+
+<h4 class="docs doc-param-macros">Arguments and behaviour</h4>
+
+<ul class="doc-param-macros">
+  <li>the argument is the same as for
+      <a href="typesetting.html#linelength">LL</a>
+  </li>
+  <li>exactly equivalent to changing the right margin with
+      DOC_RIGHT_MARGIN (see
+      <a href="#doc-right-margin">above</a>);
+      for changing the line length of
+      <a href="definitions.html#running">running text</a>
+      only, use
+      <a href="typesetting.html#linelength">LL</a>
+      (see
+      <a href="#behaviour">typesetting macros during document processing</a>,
+      entry for LL)
+  </li>
+</ul>
+
+<!-- -DOC_FAMILY- -->
+
+<div class="macro-id-overline">
+<h3 id="doc-family" class="macro-id">DOC_FAMILY</h3>
+</div>
+
+<div class="box-macro-args">
+Macro: <b>DOC_FAMILY</b> <kbd class="macro-args">&lt;family&gt;</kbd>
+</div>
+
+<h4 class="docs doc-param-macros" style="margin-top: 1em;">Arguments and 
behaviour</h4>
+
+<ul class="doc-param-macros">
+  <li>the argument is the same as for
+      <a href="typesetting.html#family">FAMILY</a>
+  </li>
+  <li>globally changes the type family for
+  <ul>
+    <li style="margin-left: -.5em;">the <a 
href="definitions.html#docheader">docheader</a></li>
+    <li style="margin-left: -.5em;">all <a 
href="docelement.html#index-docelement">document element tags</a>, including 
footnotes</li>
+    <li style="margin-left: -.5em;"><a href="definitions.html#header">headers 
and/or footers</a></li>
+    <li style="margin-left: -.5em;"><a 
href="docelement.html#number-lines-intro">line numbering</a></li>
+    <li style="margin-left: -.5em;"><a 
href="headfootpage.html#pagination">page numbering</a></li>
+  </ul></li>
+  <li>does <i>not</i> change the family of
+  <ul>
+      <li><a href="cover.html#doc-cover">document cover pages</a></li>
+      <li><a href="cover.html#cover">cover pages</a></li>
+      <li><a href="docelement.html#endnote-intro">endnotes pages</a></li>
+      <li><a href="docelement.html#toc-intro">table of contents</a></li>
+  </ul></li>
+  <li>any page elements (e.g. headers page numbers, footnotes) whose
+      families you wish to remain at their old values must be
+      reset with the appropriate
+      <a href="docelement.html#docelement-control">control macros</a>
+  </li>
+</ul>
+
+<!-- -DOC_PT_SIZE- -->
+
+<div class="macro-id-overline">
+<h3 id="doc-pt-size" class="macro-id">DOC_PT_SIZE</h3>
+</div>
+
+<div class="box-macro-args">
+Macro: <b>DOC_PT_SIZE</b> <kbd class="macro-args">&lt;point size&gt;</kbd>
+</div>
+
+<p class="requires">
+&bull;&nbsp;Does not require a <a href="definitions.html#unitofmeasure">unit 
of measure</a>; points is assumed
+</p>
+
+<h4 class="docs doc-param-macros">Arguments and behaviour</h4>
+
+<ul class="doc-param-macros">
+  <li>the argument is the same as for
+      <a href="typesetting.html#ps">PT_SIZE</a>,
+      and refers to the point size of type in paragraphs
+  </li>
+  <li>all automatic point size changes (heads, quotes,
+      footnotes, headers, etc.) are affected by the new size;
+      anything you do not want affected must be reset to
+      its former value (see the Control Macros section of
+      the pertinent document element for instructions on
+      how to do this)
+  </li>
+</ul>
+
+<!-- -DOC_LEAD- -->
+
+<div class="macro-id-overline">
+<h3 id="doc-lead" class="macro-id">DOC_LEAD</h3>
+</div>
+
+<div class="box-macro-args">
+Macro: <b>DOC_LEAD</b> <kbd class="macro-args">&lt;points&gt; [ ADJUST ]</kbd>
+</div>
+
+<p class="requires">
+&bull;&nbsp;Does not require a <a href="definitions.html#unitofmeasure">unit 
of measure</a>; points is assumed
+</p>
+
+<h4 class="docs doc-param-macros">Arguments and behaviour</h4>
+
+<ul class="doc-param-macros">
+  <li>the argument is the same as for
+      <a href="typesetting.html#leading">LS</a>,
+      and refers to the
+      <a href="definitions.html#lead">leading</a>
+      of paragraphs
+  </li>
+  <li>because paragraphs will have a new leading, the leading and
+      spacing of most running text is influenced by the new value
+  </li>
+  <li>epigraphs and footnotes remain unaffected;
+      if you wish to change their leading, use
+      <a href="docelement.html#epigraph-autolead">EPIGRAPH_AUTOLEAD</a>
+      and
+      <a href="docelement.html#footnote-autolead">FOOTNOTE_AUTOLEAD</a>.
+  </li>
+  <li>the optional argument <kbd>ADJUST</kbd> performs
+      leading adjustment as explained in
+      <a href="#doc-lead-adjust">DOC_LEAD_ADJUST</a>
+  </li>
+</ul>
+
+<div class="box-important">
+<p class="tip">
+<span class="important">Important:</span>
+Do not use DOC_LEAD in the middle of a page!  It should always and
+only be invoked immediately prior to a new page, like this:
+<br/>
+<span class="pre-in-pp">
+  .DOC_LEAD &lt;new value&gt;
+  .NEWPAGE
+</span>
+</p>
+</div>
+
+<div class="box-tip">
+<p class="tip">
+<span class="note">Note:</span>
+Even if you don&#8217;t pass DOC_LEAD the optional argument
+<kbd>ADJUST</kbd>, mom will still adjust the leading of endnotes
+pages and toc pages.  See
+<a href="docelement.html#endnote-lead">ENDNOTE_LEAD</a>
+and
+<a href="docelement.html#toc-lead">TOC_LEAD</a>
+for an explanation of how to disable this default behaviour.
+</p>
+</div>
+
+<!-- -DOC_QUAD- -->
+
+<div class="macro-id-overline">
+<h3 id="doc-quad" class="macro-id">DOC_QUAD</h3>
+</div>
+
+<div class="box-macro-args">
+Macro: <b>DOC_QUAD</b> <kbd class="macro-args">L | R | C | J</kbd>
+</div>
+
+<h4 class="docs doc-param-macros" style="margin-top: 1em;">Arguments and 
behaviour</h4>
+
+<ul class="doc-param-macros">
+  <li>the arguments are the same as for
+      <a href="typesetting.html#quad">QUAD</a>
+  </li>
+  <li>affects paragraphs, epigraphs and footnotes; does not
+      affect blockquotes
+  </li>
+</ul>
+
+<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: 24%; text-align: center;"><a href="#top">Top</a></td>
+  <td style="width: 43%; text-align: right;"><a 
href="docelement.html#top">Next: The document element tags</a></td>
+</tr>
+</table>
+
+</div>
+
+<div class="bottom-spacer"><br/></div>
+
+</body>
+</html>
+<!-- vim: fileencoding=utf-8: nomodified: -->

Index: goodies.html
===================================================================
RCS file: goodies.html
diff -N goodies.html
--- /dev/null   1 Jan 1970 00:00:00 -0000
+++ goodies.html        18 Aug 2010 22:45:35 -0000      1.27
@@ -0,0 +1,1503 @@
+<?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 -- Goodies</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="inlines.html#top">Next: Inline 
escapes</a></td>
+</tr>
+</table>
+
+<h1 id="goodies" class="docs">Goodies</h1>
+
+<p>
+The macros in this section are a collection of useful (and sometimes
+nearly indispensable) routines to simplify typesetting.
+</p>
+
+<div id="goodies-macros-mini-toc" style="margin-top: -1em; font-size: 95%;">
+<div class="mini-toc-col-1">
+<ul class="no-enumerator">
+<li class="list-head-goodies"><a href="#alias">ALIAS</a> <span 
class="normal-smaller">&ndash; rename macros</span></li>
+<li class="list-head-goodies"><a href="#silent">SILENT</a> <span 
class="normal-smaller">&ndash; &#8220;hide&#8221; input lines from 
output</span></li>
+<li class="list-head-goodies"><a href="#trap">TRAP</a> <span 
class="normal-smaller">&ndash; suspend/re-invoke traps</span></li>
+<li class="list-head-goodies"><a href="#smartquotes">SMARTQUOTES</a> <span 
class="normal-smaller">&ndash; convert typewriter doublequotes to proper 
doublequotes</span></li>
+<li class="list-head-goodies"><a href="#caps">CAPS</a> <span 
class="normal-smaller">&ndash; convert to upper case</span></li>
+<li class="list-head-goodies"><a href="#string">STRING</a> <span 
class="normal-smaller">&ndash; user-definable strings</span></li>
+<li class="list-head-goodies"><a href="#esc-char">ESC_CHAR</a> <span 
class="normal-smaller">&ndash; change the escape character to something other 
than a backslash</span></li>
+<li class="list-head-goodies"><a href="#sizespecs">SIZESPECS</a> <span 
class="normal-smaller">&ndash; get cap-height, x-height and descender depth of 
a font</span></li>
+<li class="list-head-goodies no-anchor"><span style="font-size: 
90%;">Underscoring/underlining</span>
+<ul class="sublist">
+  <li class="list-head-goodies text-color"><a 
href="#underscore">UNDERSCORE</a> <span class="normal-smaller">&ndash; single 
underscore</span>
+  <ul class="sublist sub">
+    <li class="list-head-goodies text-color"><a 
href="#underscore-weight">Controlling the weight of underscores</a></li>
+    <li class="list-head-goodies text-color"><a 
href="#underscore-color">Colorizing underscores</a></li>
+    <li class="list-head-goodies text-color"><a href="#underscore-notes">Notes 
on underscoring</a></li>
+  </ul></li>
+  <li class="list-head-goodies text-color"><a 
href="#underscore2">UNDERSCORE2</a> <span class="normal-smaller">&ndash; double 
underscore</span></li>
+  <li class="list-head-goodies text-color"><a href="#underline">UNDERLINE</a> 
<span class="normal-smaller">&ndash; fixed-width fonts only</span>
+  <ul class="sublist sub">
+    <li class="list-head-goodies text-color"><a href="#ul">\*[UL]</a> <span 
class="normal-sub-sub">&ndash; inline escape to underline; fixed-width fonts 
only</span></li>
+  </ul></li>
+</ul></li>
+<li class="list-head-goodies no-anchor"><span style="font-size: 
90%;">Padding</span>
+<ul class="sublist">
+  <li class="list-head-goodies text-color"><a href="#pad">PAD</a> <span 
class="normal-smaller">&ndash; insert equalized space into lines</span>
+  <ul class="sublist sub">
+    <li class="list-head-goodies text-color"><a 
href="#pad-marker">PAD_MARKER</a> <span class="normal-sub-sub">&ndash; 
change/set the marker used with PAD</span></li>
+  </ul></li>
+</ul></li>
+</ul>
+</div>
+<div class="mini-toc-col-2">
+<ul class="no-enumerator">
+<li class="list-head-goodies no-anchor"><span style="font-size: 
90%;">Leaders</span>
+<ul class="sublist">
+  <li class="list-head-goodies text-color"><a href="#leader">\*[LEADER]</a> 
<span class="normal-smaller">&ndash; inline escape to add leaders to a 
line</span></li>
+  <li class="list-head-goodies text-color"><a 
href="#leader-character">LEADER_CHARACTER</a> <span 
class="normal-smaller">&ndash; change/set the leader character</span></li>
+</ul></li>
+<li class="list-head-goodies no-anchor"><span style="font-size: 90%;">Drop 
caps</span>
+<ul class="sublist">
+  <li class="list-head-goodies text-color"><a href="#dropcap">DROPCAP</a> 
<span class="normal-smaller">&ndash; set a drop cap</span></li>
+  <li class="list-head-goodies text-color" style="list-style-type: none;"><a 
href="#dropcap-support"><span class="normal-smaller" style="font-weight: 
bold;">Support macros for DROPCAP</span></a>
+  <ul class="sublist sub">
+    <li class="list-head-goodies text-color"><a 
href="#dropcap-family">DROPCAP_FAMILY</a> <span class="normal-sub-sub">&ndash; 
change drop cap family</span></li>
+    <li class="list-head-goodies text-color"><a 
href="#dropcap-font">DROPCAP_FONT</a> <span class="normal-sub-sub">&ndash; 
change drop cap font</span></li>
+    <li class="list-head-goodies text-color"><a 
href="#dropcap-adjust">DROPCAP_ADJUST</a> <span class="normal-sub-sub">&ndash; 
alter size of drop cap</span></li>
+    <li class="list-head-goodies text-color"><a 
href="#dropcap-color">DROPCAP_COLOR</a> <span class="normal-sub-sub">&ndash; 
change colour of drop cap</span></li>
+    <li class="list-head-goodies text-color"><a 
href="#dropcap-gutter">DROPCAP_GUTTER</a> <span class="normal-sub-sub">&ndash; 
change space between drop cap and running text</span></li>
+  </ul></li>
+</ul></li>
+<li class="list-head-goodies text-color no-anchor"><span style="font-size: 
90%;">Superscripts</span>
+<ul class="sublist">
+  <li class="list-head-goodies text-color"><a href="#sup">\*[SUP]</a> <span 
class="normal-smaller">&ndash; inline escape to set superscripts</span>
+  <ul class="sublist sub">
+    <li class="list-head-goodies text-color"><a 
href="#sup-raise">SUPERSCRIPT_RAISE_AMOUNT</a> <span 
class="normal-sub-sub">(control superscript raise amount</span></li>
+    <li class="list-head-goodies text-color"><a 
href="#cond-or-ext-sup">\*[CONDSUP]</a> <span class="normal-sub-sub">&ndash; 
condensed superscripts</span></li>
+    <li class="list-head-goodies text-color"><a 
href="#cond-or-ext-sup">\*[EXTSUP]</a> <span class="normal-sub-sub">&ndash; 
extended superscripts</span></li>
+  </ul></li>
+</ul></li>
+</ul>
+</div>
+</div>
+
+<div class="rule-medium" style="padding-bottom: 1em;"><hr/></div>
+
+<!-- -ALIAS- -->
+
+<div class="macro-id-overline">
+<h3 id="alias" class="macro-id">Rename macros</h3>
+</div>
+
+<div class="box-macro-args">
+Macro: <b>ALIAS</b> <kbd class="macro-args">&lt;new name&gt; &lt;old 
name&gt;</kbd>
+</div>
+
+<p>
+The ALIAS macro may well be your best friend.  With it, you can
+change the name of a macro to anything you like (provided the new
+name is not already being used by mom; see the
+<a href="reserved.html#reserved">list of reserved words</a>).
+</p>
+
+<p>
+Groff has always been a bit intimidating for new users because
+its standard macro packages use very terse macro names.  Mom
+doesn&#8217;t like people to feel intimidated; she wants them
+to feel welcome.  Consequently, she tries for easy-to-grasp,
+self-explanatory macro names.  However, mom knows that people have
+their own ways of thinking, their own preferences, their own habits.
+Some of her macro names may not suit you; they might be too long,
+or aren&#8217;t what you automatically think of when you want to do
+a particular thing, or might conflict with habits you've developed
+over the years.
+</p>
+
+<p>
+If you don&#8217;t like one of mom&#8217;s macro names, say,
+PAGEWIDTH, change it, like this:
+<br/>
+<span class="pre-in-pp">
+  .ALIAS PW PAGEWIDTH
+         |      |
+    new--+      +--official
+    name             name
+</span>
+The first argument to ALIAS is the new name you want for a macro.
+The second is the &#8220;official&#8221; name by which the macro is
+normally invoked.  After ALIAS, either can be used.
+</p>
+
+<p>
+Note that in ALIAS, you do NOT include the period (dot) that
+precedes the macro when it&#8217;s a
+<a href="definitions.html#controllines">control line</a>.
+</p>
+
+<div class="box-tip">
+<p class="tip">
+<span class="tip">Tip:</span>
+A particularly good candidate for ALIAS is the macro,
+<a href="typesetting.html#ps">PT_SIZE</a>.
+A more natural name for it (at least to old-school phototypesetters)
+would simply be PS, but PS conflicts with the <b>eqn</b> equation
+preprocessor and thus mom uses the longer form.  However, if
+you&#8217;re not using <b>eqn</b>, you can happily rename PT_SIZE to
+PS:
+<br/>
+<span class="pre-in-pp">
+  .ALIAS PS PT_SIZE
+</span>
+</p>
+</div>
+
+<div class="box-tip">
+<p class="tip">
+<span class="note">Note:</span>
+If you use ALIAS a lot, and always for the same things, consider
+creating an aliases file of the form
+<br/>
+<span class="pre-in-pp">
+  .ALIAS &lt;new name&gt; &lt;old name&gt;
+  .ALIAS &lt;new name&gt; &lt;old name&gt;
+  .ALIAS &lt;new name&gt; &lt;old name&gt;
+  ...etc
+</span>
+Put the file someplace convenient and source it (include it) at the
+beginning of your documents with the
+<a href="docprocessing.html#include">INCLUDE</a>
+macro.  Assuming that you've created an aliases file called
+<b>mom-aliases</b> in your home directory under a directory called
+<b>Mom</b>, you'd source it by placing
+<br/>
+<span class="pre-in-pp">
+  .INCLUDE /home/&lt;username&gt;/Mom/mom-aliases
+</span>
+at the top of your documents.
+</p>
+
+<p class="tip-bottom">
+If you share documents that make use of an alias file, remember that
+other people don&#8217;t have the file.  Paste the whole thing at
+the top of your documents, please.
+</p>
+</div>
+
+<div class="box-tip">
+<p class="tip">
+<span class="experts">Experts:</span>
+ALIAS is an alias of <kbd>.als</kbd>.  You can use either, or mix
+'n' match with impunity.
+</p>
+</div>
+
+<!-- -SILENT- --> 
+<div class="macro-id-overline">
+<h3 id="silent" class="macro-id">Hide input lines from output</h3>
+</div>
+
+<div class="box-macro-args">
+ Macro: <b>SILENT</b> <kbd class="macro-args">toggle</kbd>
+</div>
+
+<p class="alias" style="margin-bottom: 0;">
+<i>Alias:</i> <b>COMMENT</b>
+</p>
+
+<p>
+Sometimes, you want to &#8220;hide&#8221;
+<a href="definitions.html#inputline">input lines</a>
+from final output.  This is most likely to be the case when setting
+up string tabs (see the
+<a href="typesetting.html#string-tabs-tut">quickie tutorial on string tabs</a>
+for an example), but there are other places where you might want
+input lines to be invisible as well.  Any place you don&#8217;t want
+input lines to appear in the output, use the SILENT macro.
+</p>
+
+<p>
+SILENT is a toggle.  Invoking it without an argument turns it on;
+any argument turns it off.  E.g.,
+<br/>
+<span class="pre-in-pp">
+  .SILENT
+  A line of text
+  .SILENT OFF
+</span>
+The line &#8220;A line of text&#8221; will not appear in the
+output copy.
+</p>
+
+<p>
+SILENT is aliased as COMMENT.  If you want to insert non-printing
+comments into your documents, you may prefer this.
+</p>
+
+<div class="box-tip">
+<p class="tip">
+<span class="tip">Tip:</span>
+SILENT does not automatically break an
+<a href="definitions.html#inputline">input line</a>
+(see
+<a href="typesetting.html#br">BR</a>)
+when you&#8217;re in one of the
+<a href="definitions.html#filled">fill modes</a>
+(<a href="typesetting.html#justify">JUSTIFY</a>
+or
+<a href="typesetting.html#quad">QUAD L | R | C | J</a>).
+The same applies to tabs
+(<a href="typesetting.html#tab-set">typesetting</a>
+or
+<a href="typesetting.html#st">string</a>)
+to which you've passed the J or QUAD argument.  You must insert
+<kbd>.BR</kbd> yourself, or risk a portion of your text
+disappearing into a black hole.
+</p>
+</div>
+
+<!-- -TRAP- -->
+
+<div class="macro-id-overline">
+<h3 id="trap" class="macro-id">Suspend/re-invoke traps</h3>
+</div>
+
+<div class="box-macro-args">
+Macro: <b>TRAP</b> <kbd class="macro-args">toggle</kbd>
+</div>
+
+<p>
+Traps are vertical positions on the output page at which you or
+mom have instructed groff to start doing something automatically.
+Commonly, this is near the bottom of the page, where automatic
+behind-the-scenes processing is needed in order for one page to
+finish and another to start.
+</p>
+
+<p>
+Sometimes, traps get sprung when you don&#8217;t want them.  If this
+happens, surround just the offending macros and input lines with
+<br/>
+<span class="pre-in-pp">
+    .TRAP OFF
+    ...
+    .TRAP
+</span>
+TRAP is a toggle, therefore any argument turns it off (i.e. suspends
+the trap), and no argument turns it (back) on.
+</p>
+
+<!-- -SMARTQUOTES- -->
+
+<div class="macro-id-overline">
+<h3 id="smartquotes" class="macro-id">Convert typewriter doublequotes to 
proper doublequotes</h3>
+</div>
+
+<div class="box-macro-args">
+Macro: <b>SMARTQUOTES</b> <kbd class="macro-args">[&lt;off&gt;] [ ,, | 
&gt;&gt; | &lt;&lt; ]</kbd>
+</div>
+
+<span style="margin-left: .5em">or</span>
+
+<div class="box-macro-args">
+Macro: <b>SMARTQUOTES</b> <kbd class="macro-args">DA | DE | ES | FR | IT | NL 
| NO | PT | SV</kbd>
+</div>
+
+<p>
+If you invoke SMARTQUOTES without an argument, mom converts all
+instances of the inch-mark, (<kbd>"</kbd>), also called
+a doublequote, into the appropriate instances of true Anglo-American
+open-and close-doublequotes.  (See
+<a href="#sq-international">Internationalization</a>
+for how to get SMARTQUOTES to behave correctly for non-English
+quoting styles.)
+</p>
+
+<p>
+Typographically, there is a difference between the inch-mark and
+quotation marks&mdash;a BIG difference.  Sadly, typewriters and computer
+keyboards supply only one: the inch-mark.  While using inches for
+doublequotes is, and always has been, acceptable in typewriter-style
+copy, it has never been, and, God willing, never will be acceptable in
+typeset copy.  Failure to turn inches into quotes is the first thing
+a professional typesetter notices in documents prepared by amateurs.
+And you don&#8217;t want to look like an amateur, do you?
+</p>
+
+<h3 id="sq-international" class="docs">Internationalization</h3>
+<p>
+If you invoke SMARTQUOTES with one of the optional arguments
+(<kbd>,,</kbd> or <kbd>&gt;&gt;</kbd>
+or <kbd>&lt;&lt;</kbd>) you can use
+<kbd>&quot;</kbd> (i.e. the inch-mark/doublequotes key)
+as &#8220;cheap&#8221; open-and close-quotes when inputting text in
+a language other than English, and have mom convert them, on output,
+into the chosen open-and close-quote style.
+</p>
+
+<p>
+<kbd>,,</kbd> opens quotes with &#8220;lowered
+doublequotes&#8221; and closes them with &#8220;raised
+doublequotes&#8221;, as in this ascii approximation:
+<br/>
+<span class="pre-in-pp">
+  ,,Hilfe !``
+</span>
+
+<kbd>&gt;&gt;</kbd> opens quotes with guillemets
+pointing to the right, and closes them with guillemets pointing to
+the left, as in this ascii approximation:
+<br/>
+<span class="pre-in-pp">
+  &gt;&gt;Zurück !&lt;&lt;
+</span>
+<kbd>&lt;&lt;</kbd> opens quotes with guillemets
+pointing to the left, and closes them with guillemets pointing to
+the right, as in this ascii approximation:
+<br/>
+<span class="pre-in-pp">
+  &lt;&lt;Mais monsieur! Je ne suis pas ce genre de fille!&gt;&gt;
+</span>
+Please note: the above arguments to SMARTQUOTES are literal
+ASCII characters. <kbd>,,</kbd> is two commas;
+<kbd>&lt;&lt;</kbd> is two less-than signs;
+<kbd>&gt;&gt;</kbd> is two greater-than signs.
+</p>
+
+<p>
+Alternatively, you can pass SMARTQUOTES the two-letter, ISO 639
+abbreviation for the language you&#8217;re writing in, and mom will
+output the correct quotes.
+<br/>
+<span class="pre-in-pp">
+  .SMARTQUOTES DA     = Danish      &gt;&gt;text&lt;&lt;
+  .SMARTQUOTES DE     = German      ,,text``
+  .SMARTQUOTES ES     = Spanish     ``text´´
+  .SMARTQUOTES FR     = French      &lt;&lt; text &gt;&gt;
+  .SMARTQUOTES IT     = Italian     &lt;&lt; text &gt;&gt;
+  .SMARTQUOTES NL     = Dutch       ´´text´´
+  .SMARTQUOTES NO     = Norwegian   &lt;&lt;text&gt;&gt;
+  .SMARTQUOTES PT     = Portuguese  &lt;&lt;text&gt;&gt;
+  .SMARTQUOTES SV     = Swedish     &gt;&gt;text&gt;&gt;
+</span>
+</p>
+
+<p>
+Turn SMARTQUOTES off by passing it any argument not in the argument
+list (e.g. OFF, QUIT, X, etc.)
+</p>
+
+<p>
+If you&#8217;re using the
+<a href="docprocessing.html#docprocessing">document processing macros</a>
+with
+<a href="docprocessing.html#printstyle">PRINTSTYLE TYPESET</a>,
+SMARTQUOTES is on by default (in the Anglo-American style); with
+<a href="docprocessing.html#printstyle">PRINTSTYLE TYPEWRITE</a>,
+it&#8217;s off by default (and should probably stay that way).
+</p>
+
+<p>
+Finally, if you&#8217;re fussy about the kerning of quote marks in
+relation to the text they surround, or have special quoting needs,
+you have to enter quote marks by hand using groff&#8217;s native
+<a href="definitions.html#inlines">inline escapes</a>
+for special characters (see <kbd>man groff-char</kbd>
+for a complete list of special characters).  Entering quote marks
+this way allows you to use mom&#8217;s
+<a href="inlines.html#inline-kerning-mom">inline kerning escapes</a>
+to fine-tune the look of quotes.
+</p>
+
+<div class="box-tip">
+<p class="tip">
+<span class="note">Note:</span>
+SMARTQUOTES does not work on single quotes, which most people
+input with the apostrophe (found at the right-hand end of the
+&#8220;home row&#8221; on a QWERTY keyboard).  Groff will interpret
+all instances of the apostrophe as an apostrophe, making the symbol
+useless as an open-single-quote.  For open single quotes, input
+the backtick character typically found under the tilde on most
+keyboards.  (Pour nous autres, &#8220;backtick&#8221; veut dire
+l&#8217;accent grave.)  Here&#8217;s an example of correct input
+copy with single quotes:
+<br/>
+<span class="pre-in-pp">
+  "But she said, `I don&#8217;t want to!'"    
+</span>
+</p>
+
+<p class="tip-bottom" style="margin-top: -1em;">
+<span class="additional-note">Additional note:</span>
+Whether or not you have SMARTQUOTES turned on, get into the habit of
+entering the foot-and inch-marks, when you need them, with the
+<a href="definitions.html#inlines">inline escapes</a>
+<kbd>\*[FOOT]</kbd> and
+<kbd>\*[INCH]</kbd>, instead of
+<kbd>'</kbd> and <kbd>"</kbd>.
+</p>
+</div>
+
+<!-- -CAPS- -->
+
+<div class="macro-id-overline">
+<h3 id="caps" class="macro-id">Convert to upper case</h3>
+</div>
+
+<div class="box-macro-args">
+Macro: <b>CAPS</b> <kbd class="macro-args">toggle</kbd>
+</div>
+
+<p>
+CAPS converts all lower case letters to upper case.
+Primarily, it&#8217;s a support macro used by the
+<a href="docprocessing.html#docprocessing">document processing macros</a>,
+but you may find it helpful on occasion. CAPS is a toggle, therefore
+no argument turns it on, any argument (OFF, QUIT, X, etc.) turns
+it off.
+<br/>
+<span class="pre-in-pp">
+  .CAPS
+  All work and no play makes Jack a dull boy.
+  .CAPS OFF
+</span>
+
+produces, on output
+<br/>
+<span class="pre-in-pp">
+  ALL WORK AND NO PLAY MAKES JACK A DULL BOY.
+</span>
+If you wish to capitalise a section of type inline, use the
+<a href="definitions.html#inlines">inline escapes</a>,
+<a href="inlines.html#uc-lc"><kbd>\*[UC]...\*[LC]</kbd></a>
+like this:
+<br/>
+<span class="pre-in-pp">
+  All work \*[UC]and\*[LC] no play makes Jack a dull boy.
+</span>
+
+The above produces, on output
+<br/>
+<span class="pre-in-pp">
+  All work AND no play makes Jack a dull boy.
+</span>
+</p>
+
+<!-- -STRING- -->
+
+<div class="macro-id-overline">
+<h3 id="string" class="macro-id">User-defined strings</h3>
+</div>
+
+<div class="box-macro-args">
+Macro: <b>STRING</b> <kbd class="macro-args">&lt;name&gt; &lt;what you want in 
the string&gt;</kbd>
+</div>
+
+<p>
+You may find sometimes that you have to type out portions of text
+repeatedly.  If you'd like not to wear out your fingers, you can
+define a string that, whenever you call it by name, outputs whatever
+you put into it.
+</p>
+
+<p>
+For example, say you&#8217;re creating a document that repeatedly uses
+the phrase &#8220;the Montreal/Windsor corridor&#8221;.  Instead
+of typing all that out every time, you could define a string, like
+this:
+<br/>
+<span class="pre-in-pp">
+  .STRING mw the Montreal/Windsor corridor
+</span>
+Once a string is defined, you can call it any time with the
+<a href="definitions.html#inlines">inline escape</a>
+<kbd>\*[&lt;stringname&gt;]</kbd>.  Using the example
+string above
+<br/>
+<span class="pre-in-pp">
+  The schedule for trains along \*[mw]:
+</span>
+produces, on output
+<br/>
+<span class="pre-in-pp">
+  The schedule for trains along the Montreal/Windsor corridor:
+</span>
+</p>
+
+<div class="box-tip">
+<p class="tip">
+<span class="note">Note:</span>
+Be very careful not to put any spaces at the ends of strings
+you&#8217;re defining, unless you want them.  Everything after
+the name argument you pass to STRING goes into the string,
+including trailing spaces.  It&#8217;s a good idea to get into the
+habit of using groff&#8217;s native commenting mechanism, <kbd
+class="bold">\"</kbd>, immediately following any string definition
+in order to avoid spaces you can&#8217;t see, like this
+<br/>
+<span class="pre-in-pp">
+  .STRING mw the Montreal/Windsor corridor\"
+</span>
+</p>
+</div>
+
+<div class="box-tip">
+<p class="tip">
+<span class="experts">Experts:</span>
+STRING is an alias for
+<b>ds</b>.  You can use either, or mix 'n' match with impunity.
+</p>
+</div>
+
+<!-- -ESC_CHAR- -->
+
+<div class="macro-id-overline">
+<h3 id="esc-char" class="macro-id">Change the escape character</h3>
+</div>
+
+<div class="box-macro-args">
+Macro: <b>ESC_CHAR</b> <kbd class="macro-args">&lt;new character&gt; | 
&lt;anything&gt;</kbd>
+</div>
+
+<p>
+Groff&#8217;s and mom&#8217;s default escape character is
+the backslash.  Sometimes, you may want to include a literal
+backslash in your document.  There are two ways to accomplish
+this.  One is simply to double the backslash character (<kbd
+class="bold">\\</kbd>), which is convenient if you don&#8217;t have
+a lot of backslashes to input.  If you need to input a whole batch
+of backslashes (say, when including code snippets in your document),
+you can use ESC_CHAR to make the change permanent (until you decide
+to restore the escape character to its default, the backslash).
+</p>
+
+<p>
+ESC_CHAR with a single character argument changes the escape
+character to whatever the argument is.  ESC_CHAR with no argument
+restores the escape character to the backslash.
+</p>
+
+
+<div class="box-tip">
+<p class="tip">
+<span class="experts">Experts:</span>
+ESC_CHAR is an alias of <kbd>.ec</kbd>.  Mix 'n' match
+the two with impunity.
+</p>
+</div>
+
+<!-- -SIZESPECS- -->
+
+<div class="macro-id-overline">
+<h3 id="sizespecs" class="macro-id">Get cap-height, x-height and descender 
depth of a font</h3>
+</div>
+
+<div class="box-macro-args">
+Macro: <b>SIZESPECS</b>
+</div>
+
+<p>
+Whenever you need to get the
+<a href="definitions.html#capheight">cap-height</a>,
+<a href="definitions.html#xheight">x-height</a>
+or
+<a href="definitions.html#descender">descender</a>
+depth of type at the current point size, invoke <kbd
+class="bold">.SIZESPECS</kbd>, which takes no argument.
+The dimensions are stored in the string registers
+<b>\*[$CAP_HEIGHT]</b>, <b>\*[$X_HEIGHT]</b> and
+<b>\*[$DESCENDER]</b>, respectively, in
+<a href="definitions.html#units">machine units</a>
+to which the
+<a href="definitions.html#unitofmeasure">unit of measure</a>,
+<b>u</b>, is already appended.
+</p>
+
+<p>
+Thus, if you wanted to advance 2 inches from your current position
+on the page plus the cap-height of the current point size of type
+<br/>
+<span class="pre-in-pp">
+  .PT_SIZE &lt;n&gt;
+  .SIZESPECS
+  .ALD 2i+\*[$CAP_HEIGHT]
+</span>
+would do the trick.
+</p>
+
+<!-- -UNDERSCORE- -->
+
+<div class="macro-id-overline">
+<h3 id="underscore" class="macro-id">Single underscore</h3>
+</div>
+
+<div class="box-macro-args">
+Macro: <b>UNDERSCORE</b> <kbd class="macro-args">[ &lt;distance below 
baseline&gt; ] &quot;&lt;string&gt;&quot;</kbd>
+</div>
+
+<p class="requires">
+&bull;&nbsp;Optional argument requires a <a 
href="definitions.html#unitofmeasure">unit of measure</a>
+</p>
+
+<p>
+By default, UNDERSCORE places an underscore 2 points beneath the
+required
+<a href="definitions.html#stringargument">string argument</a>.
+The string must be enclosed in double-quotes, like this:
+<br/>
+<span class="pre-in-pp">
+  .UNDERSCORE "Unmonitored monopolies breed high prices and poor 
products."&nbsp;
+</span>
+If you wish to change the distance of the rule from the baseline,
+use the optional argumen
+<kbd>&lt;distance&nbsp;below&nbsp;baseline&gt;</kbd>
+(with a unit of measure).
+<br/>
+<span class="pre-in-pp">
+  .UNDERSCORE 3p "Unmonitored monopolies breed high prices and poor 
products."&nbsp;
+</span>
+The above places upper edge of the underscore 3 points below the
+<a href="definitions.html#baseline">baseline</a>.
+</p>
+
+<h3 id="underscore-weight" class="docs">Controlling the weight of 
underscores</h3>
+<p>
+The weight (thickness) of underscores may be controlled with the
+macro, UNDERSCORE_WEIGHT.  Thus, if you want underscores with a
+weight of 1-1/2 points, you'd invoke:
+<br/>
+<span class="pre-in-pp">
+  .UNDERSCORE_WEIGHT 1.5
+</span>
+prior to invoking <kbd>.UNDERSCORE</kbd>.  Every
+subsequent instance of <kbd>.UNDERSCORE</kbd> will use
+this weight.
+</p>
+
+<p>
+Mom&#8217;s default underscore weight is 1/2 point.
+</p>
+
+<div class="box-tip">
+<p class="tip">
+<span class="note">Note:</span>
+UNDERSCORE_WEIGHT also sets the weight of
+<a href="#UNDERSCORE2">double underscores.</a>
+</p>
+</div>
+
+<h3 id="underscore-color" class="docs">Colorizing underscored text</h3>
+<p>
+If you want underscored text to be in a different colour from the
+text around it, use the
+<a href="color.html#color">COLOR</a>
+macro, rather than the
+<a href="color.html#color-inline">inline escape for changing color</a>.
+In other words, assuming your prevailing text color is black and
+you want underscored text in red
+<br/>
+<span class="pre-in-pp">
+  .COLOR red
+  .UNDERSCORE "text to underscore"
+  .COLOR black
+</span>
+rather than
+<br/>
+<span class="pre-in-pp">
+  .UNDERSCORE "\*[red]text to underscore\*[black]"
+</span>
+The latter will render the text in red, and the underscore in black.
+You can use this to create truly rainbow effects if you want, e.g.
+text in red, underscore in blue, and prevailing type in black:
+<br/>
+<span class="pre-in-pp">
+  .UNDERSCORE "\*[red]text to underscore\*[blue]"
+  .COLOR black
+</span>
+</p>
+
+<h3 id="underscore-notes" class="docs">Notes on underscoring</h3>
+<p>
+UNDERSCORE does not work across line breaks in output copy, which is
+to say that you can&#8217;t underscore a multi-line passage simply
+by putting the text of the whole thing in the string you pass to
+UNDERSCORE.  Each
+<a href="definitions.html#outputline">output line</a>
+or portion of an output line you want underscored must be plugged
+separately into UNDERSCORE.  Bear in mind, though, that underscoring
+should at best be an occasional effect in typeset copy.  If you want
+to emphasize an entire passage, it&#8217;s much, much better to
+change fonts (e.g. to italic or bold).
+</p>
+
+<p>
+You can easily and successfully underline entire passages in
+simulated typewriter-style copy (i.e. if your font is a monospaced
+one, like Courier, or you&#8217;re using the document processing
+macro
+<a href="#printstyle">PRINTSTYLE TYPEWRITE</a>),
+with the
+<a href="#underline">UNDERLINE</a>
+macro. UNDERLINE is designed specifically for this purpose, but
+works only with the monspaced fonts.
+</p>
+
+<p>
+Mom doesn&#8217;t always get the position and length of the
+underscore precisely right in
+<a href="definitions.html#just">justified</a>
+copy, although she&#8217;s fine with all the other
+<a href="definitions.html#filled">fill modes</a>,
+as well as with the no-fill modes.  The reason is that when text is
+justified, the word spacing may expand to fill the line, but that
+doesn&#8217;t happen until <i>after</i> the line has been processed
+in all other respects&mdash;including establishing how long to make
+an underscore.  A workaround is to prepend the backslash character
+(<kbd>\</kbd>) to each word space in the string passed
+to UNDERSCORE.  The word spacing of the underscored string may be
+slightly smaller than the word space of the remainder of the line,
+but in most cases, the difference isn&#8217;t visually noticeable.
+</p>
+
+<p>
+UNDERSCORE tends to confuse <b>gxditview</b>, even though the
+output, when printed, looks fine.  Generally, I recommend using
+<b>gv</b> to preview files anyway.  See the section on
+<a href="using.html#using-previewing">previewing</a>.
+</p>
+
+<!-- -UNDERSCORE2- -->
+
+<div class="macro-id-overline">
+<h3 id="underscore2" class="macro-id">Double underscore</h3>
+</div>
+
+<div class="box-macro-args">
+Macro: <b>UNDERSCORE2</b> <kbd class="macro-args">[ &lt;distance below 
baseline&gt; [ &lt;distance between rules&gt; ] ] 
&quot;&lt;string&gt;&quot;</kbd>
+</div>
+
+<p class="requires">
+&bull;&nbsp;Optional arguments require a <a 
href="definitions.html#unitofmeasure">unit of measure</a>
+</p>
+
+<p>
+By default, UNDERSCORE2 places a double underscore 2 points beneath
+the required
+<a href="definitions.html#stringargument">string argument</a>.
+The string must be enclosed in double-quotes, like this:
+<br/>
+<span class="pre-in-pp">
+  .UNDERSCORE2 "Unmonitored monopolies breed high prices and poor products."
+</span>
+The default distance between the two rules is 2 points, measured
+from the bottom edge of the upper rule to the top edge of the lower
+one.
+</p>
+
+<p>
+If you wish to change the distance of the double underscore from the
+<a href="definitions.html#baseline">baseline</a>,
+use the optional argument
+<kbd>&lt;distance&nbsp;below&nbsp;baseline&gt;</kbd>
+(with a unit of measure), e.g.,
+<br/>
+<span class="pre-in-pp">
+  .UNDERSCORE2 3p "Unmonitored monopolies breed high prices and poor products."
+</span>
+which places the upper edge of the first rule of the double
+underscore 3 points below the baseline.
+</p>
+
+<p>
+If you wish to change the distance between the two rules as well,
+use the second optional argument
+<kbd>&lt;distance&nbsp;between&nbsp;rules&gt;</kbd>
+(with a unit of measure).  Be aware that you must give a value for
+the first optional argument if you want to use the second.  The
+distance between the two rules is measured from the bottom edge of
+the upper rule to the top edge of the lower one.
+</p>
+
+<p>
+The weight (thickness) of double underscores may be controlled with
+the macro
+<a href="#underscore-weight">UNDERSCORE_WEIGHT</a>
+(q.v).
+</p>
+
+<div class="box-tip">
+<p class="tip">
+<span class="note">Note:</span>
+The same restrictions and caveats apply to UNDERSCORE2 as to
+UNDERSCORE.  See the
+<a href="#underscore-notes">NOTES</a>
+for UNDERSCORE.
+</p>
+</div>
+
+<!-- -UNDERLINE- -->
+
+<div class="macro-id-overline">
+<h3 id="underline" class="macro-id">Underline text &mdash; monospaced fonts 
only</h3>
+</div>
+
+<div class="box-macro-args">
+Macro: <b>UNDERLINE</b> <kbd class="macro-args">toggle</kbd>
+</div>
+
+<p>
+If your font is monospaced, like Courier, or you&#8217;re using the
+document processing macro
+<a href="#printstyle">PRINTSTYLE TYPEWRITE</a>,
+UNDERLINE allows you to underline words and passages that, in
+typeset copy, would be italicized.  You invoke UNDERLINE as you do
+with all toggle macros &mdash; by itself (i.e. with no argument) to
+initiate underlining, and with any argument (OFF, QUIT, X, etc) to
+turn underlining off.
+</p>
+
+<p>
+When on, UNDERLINE underlines letters, words and numbers, but not
+punctuation or spaces.  This makes for more readable copy than a
+solid underline.
+</p>
+
+<div class="box-tip">
+<p class="tip">
+<span class="note">Note:</span>
+Underlining may also be turned on and off
+<a href="definitions.html#inlines">inline</a>
+with the escapes
+<kbd><a href="#ul">\*[UL]...\*[ULX]</a></kbd>.
+</p>
+</div>
+
+<!-- -UL- -->
+
+<div class="macro-id-overline">
+<h3 id="ul" class="macro-id">Inline escape for underlining &mdash; monospaced 
fonts only</h3>
+</div>
+
+<div class="box-macro-args">
+Inline: <b>\*[UL]...\*[ULX]</b>
+</div>
+
+<p>
+If your font is a monospaced one, like Courier, or you&#8217;re
+using the document processing macro
+<a href="#printstyle">PRINTSTYLE TYPEWRITE</a>,
+<kbd>\*[UL]...\*[ULX]</kbd> underlines words and
+passages that, in typeset copy, would be italicized.
+</p>
+
+<p>
+<kbd>\*[UL]</kbd> underlines all letters, words and numbers
+following it, but not punctuation or spaces.  This makes for more
+readable copy than a solid underline.  When you no longer want
+underlining, <kbd>\*[ULX]</kbd> turns underlining off.
+</p>
+
+<p>
+The macro
+<kbd><a href="#underline">UNDERLINE</a></kbd>
+and the inline escape <kbd>\*[UL]</kbd> are functionally
+identical, hence
+<br/>
+<span class="pre-in-pp">
+  .FAM     C
+  .FT      R
+  .PT_SIZE 12
+  .LS      24
+  .SS      0
+  .QUAD    LEFT
+  Which should I heed?
+  .UNDERLINE
+  Just do it
+  .UNDERLINE OFF
+  or
+  .UNDERLINE
+  just say no?
+  .UNDERLINE OFF
+</span>
+produces the same result as
+<br/>
+<span class="pre-in-pp">
+  .FAM     C
+  .FT      R
+  .PT_SIZE 12
+  .LS      24
+  .SS      0
+  .QUAD    LEFT
+  Which should I heed? \*[UL]Just do it\*[ULX] or \*[UL]just say no?\*[ULX]
+</span>
+</p>
+
+<!-- -PAD- -->
+
+<div class="macro-id-overline">
+<h3 id="pad" class="macro-id">Insert space into lines</h3>
+</div>
+
+<div class="box-macro-args">
+Macro: <b>PAD</b> <kbd class="macro-args">&quot;&lt;string with pad markers 
inserted&gt;&quot; [ NOBREAK ]</kbd>
+</div>
+
+<p>
+With PAD, you can insert proportional amounts of whitespace into a
+line.  The optional <kbd id="nobreak" class="bold">NOBREAK</kbd>
+argument tells mom not to advance on the page after the PAD macro
+has been invoked.
+</p>
+
+<p>
+PAD calculates the difference between the length of text on the line
+and the distance remaining to its end, then inserts the difference
+(as whitespace) at the place(s) you specify.
+</p>
+
+<p>
+Take, for example, the following relatively common typesetting
+situation, found at the bottom of legal agreements:
+<br/>
+<span class="pre">
+  Date             Signature                               |
+</span>
+</p>
+
+<p>
+The person signing the agreement is supposed to fill in the date
+as well as a signature.  Space needs to be left for both, but the
+exact amount is neither known, nor important.  All that matters is
+that there be a little space after Date, and rather more space after
+Signature.  (In the above, <kbd>|</kbd> represents the
+end of the line at the prevailing line length.)
+</p>
+
+<p>
+The
+<a href="goodies.html#pad-marker">pad marker</a>
+(see below) is <kbd>#</kbd> (the pound or number sign
+on your keyboard) and can be used multiple times in a line.  With
+that in mind, here&#8217;s how you'd input the Date/Signature line
+(assuming a length of 30 picas):
+<br/>
+<span class="pre">
+  .LL 30P
+  .PAD "Date#Signature###"
+</span>
+</p>
+
+<p>
+When the line is output, the space remaining on the line, after
+&quot;Date&quot; and &quot;Signature&quot; have been taken into
+account, is split into four (because there are four # signs).  One
+quarter of the space is inserted between Date and Signature, the
+remainder is inserted after Signature.
+</p>
+
+<div class="examples-container">
+<h3 id="pad-example" class="docs notes">Example of PAD usage</h3>
+<p style="margin-top: .5em;">
+One rarely wants merely to insert space in a line; one usually wants
+to fill it with something, hence PAD is particularly useful in
+conjunction with
+<a href="typesetting.html#string-tabs">string tabs</a>.
+The following uses the Date/Signature example, above, but adds
+rules into the whitespace through the use of string tabs and
+mom&#8217;s
+<a href="definitions.html#inlines">inline escape</a>
+<kbd><a href="inlines.html#inline-rule-mom">\*[RULE]</a></kbd>.
+(Instead of <kbd>\*[RULE]</kbd>, groff&#8217;s line
+drawing function,
+<kbd><a 
href="inlines.html#inline-linedrawing-groff">\l'&lt;distance&gt;'</a></kbd>
+could be used.)
+<br/>
+<span class="pre-in-pp">
+  .LL 30P
+  .PAD "Date \*[ST1]#\*[ST1X] Signature \*[ST2]###\*[ST2X]" NOBREAK
+  .ST 1 J
+  .ST 2 J
+  .TAB 1
+  \*[RULE]
+  .TN
+  \*[RULE]
+  .TQ
+</span>
+If you&#8217;re not a typesetter, and if you&#8217;re new to groff,
+the example probably looks like gibberish.  My apologies.  However,
+remember that typesetting is a craft, and without having studied the
+craft, it takes a while to grasp its concepts.
+</p>
+
+<p>
+Basically, what the example does is:
+</p>
+<ol style="margin-top: -.5em; margin-bottom: -.5em;">
+  <li>Pads the Date/Signature line with a shorter space for Date
+     (<kbd>#</kbd>) and a longer space for Signature
+     (<kbd>###</kbd>), encloses the padded space with string tabs
+     markers, and outputs the line without advancing on the page.
+  </li>
+  <li>Sets the quad for the two string tabs (in this instance, justified).
+  </li>
+  <li>Calls the first string tab and draws a rule to its full
+      length.
+  </li>
+  <li>Calls the second tab with
+      <a href="typesetting.html#tn">TN</a>
+      (which moves to tab 2 and stays on the same baseline)
+      then draws a rule to the full length of string tab 2.
+  </li>
+</ol>
+
+<p>
+Often, when setting up string tabs this way, you don&#8217;t want the
+padded line to print immediately.  To accomplish this, use
+<kbd><a href="#silent">SILENT</a></kbd>.
+See the
+<a href="typesetting.html#string-tabs-tut">quickie tutorial on string tabs</a>
+for an example.
+</p>
+</div>
+
+<div class="box-tip">
+<p class="tip-top">
+<span class="note">Note:</span>
+Because the pound sign
+(<kbd>#</kbd>) is used as the pad marker, you
+can&#8217;t use it as a literal part of the pad string.  If you need
+the sign to appear in the text of a padded line, change the pad
+marker with
+<kbd><a href="#pad-marker">PAD_MARKER</a></kbd>.
+Also, be aware that <kbd>#</kbd> as a pad marker
+only applies within the PAD macro; at all other times it prints
+literally, just as you'd expect.
+</p>
+
+<p class="tip-bottom">
+Another important consideration when using PAD is that because the
+string must be enclosed in double-quotes, you can&#8217;t use the
+double-quote (<kbd>"</kbd>) as part of the string.  The
+way to circumvent this is to use the groff
+<a href="definitions.html#inlines">inline escapes</a>
+<kbd>\(lq</kbd> and <kbd>\(rq</kbd>
+(leftquote and rightquote respectively) whenever double-quotes are
+required in the string passed to PAD.
+</p>
+</div>
+
+<!-- -PAD_MARKER- -->
+
+<div class="macro-id-overline">
+<h3 id="pad-marker" class="macro-id">Change/set the marker used with PAD</h3>
+</div>
+
+<div class="box-macro-args">
+Macro: <b>PAD_MARKER</b> <kbd class="macro-args">"&lt;character to use as the 
pad marker&gt;</kbd>
+</div>
+
+<p>
+If you need to change mom&#8217;s default pad marker (<kbd
+class="bold">#</kbd>), either because you want a literal # in
+the padded line, or simply because you want to use another character
+instead, use PAD_MARKER, whose argument is the new pad marker
+character you want.
+<br/>
+<span class="pre-in-pp">
+  .PAD_MARKER @
+</span>
+changes the pad marker to <kbd>@</kbd>.
+</p>
+
+<p>
+Once you've changed the pad marker, the new marker remains in effect
+for every instance of
+<a href="#pad">PAD</a>
+until you change it again (say, back to the pound sign).
+</p>
+
+<!-- -\*[LEADER]- -->
+
+<div class="macro-id-overline">
+<h3 id="leader" class="macro-id">Inline escape to add leaders to a line</h3>
+</div>
+
+<div class="box-macro-args">
+Inline: <b>\*[LEADER]</b>
+</div>
+
+<p>
+Whenever you want to fill a line or tab with
+<a href="definitions.html#leader">leaders</a>,
+use the
+<a href="definitions.html#inlines">inline escape</a>
+<kbd>\*[LEADER]</kbd>.  The remainder of the line or
+tab will be filled with the leader character. Mom&#8217;s default
+leader character is a period (dot), but you can change it to any
+character you like with
+<kbd><a href="#leader-character">LEADER_CHARACTER</a></kbd>.
+</p>
+
+<div class="box-tip">
+<p class="tip-top">
+<span class="note">Note:</span>
+<kbd>\*[LEADER]</kbd> fills lines or tabs right to
+their end.  You cannot insert leaders into a line or tab and have
+text following the leader on the same line or in the same tab.
+Should you wish to achieve such an effect typographically, create
+tabs for each element of the line and fill them appropriately with
+the text and leaders you need.
+<a href="typesetting.html#string-tabs">String tabs</a>
+are perfect for this.  An example follows.
+<br/>
+<span class="pre">
+  .LL 30P
+  .PAD "Date\*[ST1]#\*[ST1X]Signature\*[ST2]###\*[ST2X]"
+  .EL
+  .ST 1 J
+  .ST 2 J
+  .TAB 1
+  \*[LEADER]
+  .TN
+  \*[LEADER]
+  .TQ
+</span>
+</p>
+
+<p class="tip-bottom">
+The PAD line sets the words Date and Signature, and marks string
+tabs around the pad space inserted in the line.  The string tabs are
+then &quot;set&quot;, called, and filled with leaders.  The result
+looks like this:
+<br/>
+<span class="pre" style="margin-bottom: -1em;">
+  Date.............Signature.....................................
+</span>
+</p>
+</div>
+
+<!-- -LEADER_CHARACTER- -->
+
+<div class="macro-id-overline">
+<h3 id="leader-character" class="macro-id">Change/set the leader character</h3>
+</div>
+
+<div class="box-macro-args">
+Macro: <b>LEADER_CHARACTER</b> <kbd class="macro-args">&lt;character&gt;</kbd>
+</div>
+
+<p>
+LEADER_CHARACTER takes one argument: a single character you would
+like to be used for
+<a href="definitions.html#leader">leaders</a>.
+(See
+<kbd><a href="#leader">\*[LEADER]</a></kbd>
+for an explanation of how to fill lines with leaders.)
+</p>
+
+<p>
+For example, to change the leader character from mom&#8217;s
+default (a period) to the underscore character, enter
+<br/>
+<span class="pre-in-pp">
+  .LEADER_CHARACTER _
+</span>
+</p>
+
+<!-- -DROPCAP- -->
+
+<div class="macro-id-overline">
+<h3 id="dropcap" class="macro-id">Drop caps</h3>
+</div>
+
+<div class="box-macro-args">
+Macro: <b>DROPCAP</b> <kbd class="macro-args">&lt;dropcap letter&gt; 
&lt;number of lines to drop&gt; [ COND &lt;percentage&gt; | EXT 
&lt;percentage&gt; ]</kbd>
+</div>
+
+<p>
+The first two arguments to DROPCAP are the letter you want to be the
+<a href="definitions.html#dropcap">drop cap</a>
+and the number of lines you want it to drop.  By default, mom uses
+the current family and font for the drop cap.
+</p>
+
+<p>
+The optional argument (<kbd>COND</kbd> or <kbd>EXT</kbd>) indicates
+that you want the drop cap condensed (narrower) or extended (wider).
+If you use <kbd class="bold">COND</kbd> or <kbd>EXT</kbd>, you must
+follow the argument with the percentage of the letter&#8217;s normal
+width you want it condensed or extended.  No percent sign
+(<kbd>%</kbd>) is required.
+</p>
+
+<p>
+Mom will do her very best to get the drop cap to line up with the
+first line of text indented beside it, then set the correct number
+of indented lines, and restore your left margin when the number of
+drop cap lines has been reached.
+</p>
+
+<p>
+Beginning a paragraph with a drop cap &#8220;T&#8221; looks like this:
+<br/>
+<span class="pre">
+  .DROPCAP T 3 COND 90
+  he thousand injuries of Fortunato I had borne as best I
+  could, but when he ventured upon insult, I vowed revenge.
+  You who so well know the nature of my soul will not suppose,
+  however, that I gave utterance to a threat...
+</span>
+</p>
+
+<p>
+The drop cap, slightly condensed but in the current family and font,
+will be three lines tall, with whatever text fills those three
+lines indented to the right of the letter.  The remainder of the
+paragraph&#8217;s text will revert to the left margin.
+</p>
+
+<div class="box-tip">
+<p class="tip">
+<span class="note">Note:</span>
+When using the
+<a href="docprocessing.html#docprocessing">document processing macro</a>
+<a href="docelement.html#pp">PP</a>,
+DROPCAP only works
+</p>
+<ul style="margin-top: -1em; margin-bottom: 0;">
+  <li>with initial paragraphs (i.e. at the start of the document,
+      or after
+      <a href="docelement.html#head">HEAD</a>),</li>
+  <li>when <kbd>.DROPCAP</kbd> comes immediately after <kbd>.PP</kbd>,</li>
+  <li>the
+      <a href="docprocessing.html#printstyle">PRINTSTYLE</a>
+      is TYPESET.</li>
+</ul>
+<p class="tip-bottom">
+If these conditions aren&#8217;t met, DROPCAP is silently ignored.
+</p>
+</div>
+
+<div class="box-important">
+<p class="tip">
+<span class="important">Warning:</span>
+DROPCAP puts a bit of a strain on resource-challenged systems.  If
+you have such a system and use drop caps extensively in a document,
+be prepared for a wait while mom does her thing.
+</p>
+</div>
+
+<h3 id="dropcap-support" class="docs control-macros-header">Support macros for 
DROPCAP</h3>
+<p>
+Drop caps are the bane of most typesetters&#8217; existence.
+It&#8217;s very difficult to get the size of the drop cap right
+for the number of drop lines, especially if the drop cap is in a
+different family from the prevailing family of running text.  Not
+only that, but there&#8217;s the gutter around the drop cap to take
+into account, plus the fact that the letter may be too wide or too
+narrow to look anything but odd or misplaced.
+</p>
+
+<p>
+Mom solves the last of these problems with the <kbd>COND</kbd> and
+<kbd>EXT</kbd> arguments.  The rest she solves with macros that
+change the default behaviour of DROPCAP, namely
+</p>
+<ul class="no-enumerator" style="margin-top: -.5em; margin-left: -.5em;">
+  <li><a href="#dropcap-family">DROPCAP_FAMILY</a></li>
+  <li><a href="#dropcap-font">DROPCAP_FONT</a></li>
+  <li><a href="#dropcap-color">DROPCAP_COLOR</a></li>
+  <li><a href="#dropcap-adjust">DROPCAP_ADJUST</a></li>
+  <li><a href="#dropcap-gutter">DROPCAP_GUTTER</a></li>
+</ul>
+
+<p style="margin-top: -.5em;">
+These macros must, of course, come before you invoke DROPCAP.
+</p>
+
+<h3 id="dropcap-family" class="control-macro">&bull;&nbsp;DROPCAP_FAMILY</h3>
+<p style="margin-left: .66em;">
+Set the drop cap family by giving DROPCAP_FAMILY the name of the
+family you want, e.g.
+<br/>
+<span class="pre-in-pp">
+  .DROPCAP_FAMILY H
+</span>
+which will set the family to Helvetica for the drop cap only.
+</p>
+
+<h3 id="dropcap-font" class="control-macro">&bull;&nbsp;DROPCAP_FONT</h3>
+<p style="margin-left: .66em;">
+Set the drop cap font by giving DROPCAP_FONT the name of the font
+you want, e.g.
+<br/>
+<span class="pre-in-pp">
+  .DROPCAP_FONT I
+</span>
+which will set the font to italic for the drop cap only.
+</p>
+
+<h3 id="dropcap-adjust" class="control-macro">&bull;&nbsp;DROPCAP_ADJUST</h3>
+<p style="margin-left: .66em;">
+If the size mom calculates for the drop cap isn&#8217;t precisely
+what you want, you can increase or decrease it with DROPCAP_ADJUST,
+like this: e.g.
+<br/>
+<span class="pre-in-pp">
+  .DROPCAP_ADJUST +1
+</span>
+or
+<br/>
+<span class="pre">
+  .DROPCAP_ADJUST -.75
+</span>
+</p>
+
+<p style="margin-left: .66em;">
+DROPCAP_ADJUST only understands
+<a href="definitions.html#picaspoints">points</a>,
+therefore do not append any
+<a href="definitions.html#unitofmeasure">unit of measure</a>
+to the argument.  And always be sure to prepend the plus or
+minus sign, depending on whether you want the drop cap larger or
+smaller.
+</p>
+
+<h3 id="dropcap-color" class="control-macro">&bull;&nbsp;DROPCAP_COLOR</h3>
+<p style="margin-left: .66em;">
+If you'd like your drop cap colourized, simply invoke
+<kbd>.DROPCAP_COLOR&nbsp;&lt;color&gt;</kbd> with the name of a colour you've 
already
+created (&#8220;initialized&#8221;) with
+<a href="color.html#newcolor">NEWCOLOR</a>
+or
+<a href="color.html#xcolor">XCOLOR</a>.
+Only the drop cap will be colourized; all other text will remain at
+the current colour default (usually black).
+</p>
+
+<h3 id="dropcap-gutter" class="control-macro">&bull;&nbsp;DROPCAP_GUTTER</h3>
+<p style="margin-left: .66em;">
+By default, mom puts three points of space between the drop cap
+and the text indented beside it.  If you want another value, use
+DROPCAP_GUTTER (with a unit of measure), like this:
+<br/>
+<span class="pre-in-pp">
+  .DROPCAP_GUTTER 6p
+</span>
+</p>
+
+<!-- -\*[SUP]- -->
+
+<div class="macro-id-overline">
+<h3 id="sup" class="macro-id">Superscript</h3>
+</div>
+
+<div class="box-macro-args">
+Inlines: <kbd>\*[SUP]...\*[SUPX]</kbd>
+</div>
+
+<p>
+Superscripts are accomplished
+<a href="definitions.html#inlines">inline</a>.
+Whenever you need one, typically for numerals, all you need to do is
+surround the superscript with the inlines above. <kbd>\*[SUP]</kbd>
+begins superscripting; <kbd>\*[SUPX]</kbd> turns it off.
+</p>
+
+<p id="cond-or-ext-sup">
+If your running type is
+<a href="typesetting.html#cond-inline">pseudo-condensed</a>
+or
+<a href="typesetting.html#ext-inline">pseudo-extended</a>
+and you want your superscripts to be equivalently pseudo-condensed
+or -extended, use <kbd>\*[CONDSUP]...\*[CONDSUPX]</kbd> or
+<kbd>\*[EXTSUP]...\*[EXTSUPX]</kbd>.
+</p>
+
+<p>
+The superscript inlines are primarily used by the
+<a href="docprocessing.html#docprocessing">document processing macros</a>
+for automatic generation of numbered footnotes.  However, you may
+find them useful for other purposes.
+</p>
+
+<div class="box-tip">
+<p class="tip">
+<span class="note">Note:</span>
+Mom does a pretty fine job of making superscripts look good in any
+font and at any size.  If you&#8217;re fussy, though (and I am),
+about precise vertical placement, kerning, weight, size, and so on,
+you may want to roll your own solution.  And sorry, there&#8217;s
+no mom equivalent for subscripts.  I'm neither a mathematician
+nor a chemist, so I don&#8217;t need them.  Of course, anyone who
+wishes to contribute a subscript routine to mom will receive
+blessings not only in this lifetime, but in all lifetimes to come.
+</p>
+</div>
+
+<h3 id="sup-raise" class="docs">SUPERSCRIPT RAISE AMOUNT</h3>
+<p>
+By default, mom raises superscripts 1/3 of an
+<a href="definitions.html#ems">em</a>
+above the baseline.  If you&#8217;re not happy with this default, you can
+change it by invoking SUPERSCRIPT_RAISE_AMOUNT with
+the amount you want them raised.  A
+<a href="definitions.html#unitofmeasure">unit of measure</a>
+must be appended directly to the amount.  Thus, you want
+superscripts raised by 3
+<a href="definitions.html#picaspoints">points</a>
+instead of 1/3 em, you'd
+do
+<br/>
+<span class="pre-in-pp">
+  .SUPERSCRIPT_RAISE_AMOUNT 3p
+</span>
+and all subsequent superscripts would be raised by 3 points.
+</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="inlines.html#top">Next: 
Inline escapes</a></td>
+</tr>
+</table>
+
+</div>
+
+<div class="bottom-spacer"><br/></div>
+
+</body>
+</html>
+<!-- vim: fileencoding=utf-8: nomodified: -->

Index: graphical.html
===================================================================
RCS file: graphical.html
diff -N graphical.html
--- /dev/null   1 Jan 1970 00:00:00 -0000
+++ graphical.html      18 Aug 2010 22:45:35 -0000      1.7
@@ -0,0 +1,584 @@
+<?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 -- Graphical Objects</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="docprocessing.html#top">Next: 
Document processing</a></td>
+</tr>
+</table>
+
+<h1 class="docs">Graphical objects</h1>
+
+<div style="text-align: center;">
+<ul class="no-enumerator" style="margin-left: -2.5em;">
+  <li><a href="#intro-graphical">Introduction to graphical objects</a></li>
+  <li><a href="#behaviour">Graphical objects behaviour</a></li>
+  <li><a href="#order">Order of arguments</a></li>
+  <li><a href="#index-graphical">Index of graphical objects macros</a></li>
+</ul>
+</div>
+
+<div class="rule-medium"><hr/></div>
+
+<h2 id="intro-graphical" class="docs">Introduction to graphical objects</h2>
+
+<p>
+Groff has a number of
+<a href="definitions.html#inlines">inline escapes</a>
+for drawing rules, polygons, ellipses and splines.  All begin with
+<kbd>\D</kbd> (presumably for &#8220;Draw&#8221;) and are documented
+in the groff info manual:
+<br/>
+<span class="pre-in-pp">
+  info groff => Escape index => \D
+</span>
+The escapes allow you to draw just about any simple graphical object
+you can think of, but owing to their syntax, they&#8217;re not always easy
+to read, which can make tweaking them difficult.  Additionally,
+while they perform in a <i>consistent</i> manner, they don&#8217;t
+always perform in an <i>expected</i> manner.
+</p>
+
+<p>
+Experience shows that the most common graphical elements typesetters
+need are rules (horizontal and vertical), boxes, and circles (or
+ellipses).  For this reason, mom provides macros
+to draw these objects in an easy-to-understand way; the results are
+predictable, and mom&#8217;s syntax makes fixes or tweaks
+painless.
+</p>
+
+<p id="graphical-example">
+For example, if you want to draw a 2-inch square outline box at the left
+margin using groff&#8217;s <kbd>\D</kbd> escapes, it looks like this:
+<br/>
+<span class="pre-in-pp">
+             back up
+               by
+             weight
+            +-------+
+            |       |
+   \D't 500'\h'-500u'\D'p 2i 0 0 2i -2i 0 0 -2i'
+  |       |          |                        |
+  +-------+          +------------------------+
+   set rule          draw box, 1 line at a time
+    weight
+</span>
+
+Obviously, this isn&#8217;t very efficient for something as simple as a
+box.
+</p>
+
+<p>
+Here&#8217;s the same box, drawn with mom&#8217;s box drawing
+macro,
+<kbd><a href="#dbx">DBX</a></kbd>:
+<br/>
+<span class="pre-in-pp">
+  left margin indent--+  +--box width
+                      |  |
+             .DBX .5  0  2i  2i
+                  |          |
+     rule weight--+          +--box depth
+     (in points)
+</span>
+</p>
+
+<p>
+Mom&#8217;s graphical object macros allow&mdash;in fact,
+require&mdash;giving the rule weight (&#8220;thickness&#8221;) for
+the object (or saying that you want it filled), an indent from the
+left margin where the object begins, the dimensions of the object,
+and optionally a colour for the object.
+</p>
+
+<p>
+There are no defaults for the arguments to mom'a graphical object
+macros, which means you must supply the arguments every time you
+invoke them.
+</p>
+
+<div class="box-tip">
+<p class="tip">
+<span class="note">Note:</span>
+As stated above, mom only provides macros for commonly-used
+graphical objects (rules, boxes, circles).  More complex objects
+(polygons, non-straight lines, splines) must be drawn using
+groff&#8217;s <kbd>\D</kbd> escapes.
+</p>
+</div>
+
+<h3 id="behaviour" class="docs">Graphical object behaviour</h3>
+
+<p>
+Mom&#8217;s graphical object macros all behave in the following,
+carved-in-stone ways:
+</p>
+<ol style="margin-top: -.5em; margin-bottom: -.5em;">
+   <li>Objects are drawn from the
+       <a href="definitions.html#baseline">baseline</a>
+       down, including horizontal rules.</li>
+   <li>Objects begin precisely at the left indent supplied as
+       an argument to the macro.</li>
+   <li>Objects are drawn from left to right.</li>
+   <li>Enclosed objects (boxes, circles) are drawn from the
+       perimeter <i>inward</i>.</li>
+   <li>Objects return to their horizontal/vertical point of origin.</li>
+</ol>
+
+<p>
+The consistency means that once you've mastered the very simple
+order of arguments that applies to invoking graphical object
+macros, you can draw objects with full confidence that you know
+exactly where they&#8217;re placed and how much room they
+occupy.  Furthermore, because all return to their point of origin,
+you&#8217;ll know exactly where you are on the page.
+</p>
+
+<h3 id="order" class="docs">Order of arguments</h3>
+
+<p>
+The order of arguments to the graphical object macros is the same
+for every macro:
+</p>
+<ul style="margin-top: -.5em; margin-bottom: -.5em;">
+  <li>the <kbd><span style="text-decoration: underline">W</span></kbd>eight of 
the rule
+  <ul style="margin-left: -.75em;">
+    <li>if the object is enclosed (i.e. is a box or circle), the
+        weight of the rule if you want the object outlined</li>
+    <li>the single word, <kbd>SOLID</kbd>, may be used in place
+        of the <b>weight</b> argument if you want the
+        object filled</li>
+  </ul></li>
+  <li>the <kbd><span style="text-decoration: underline">I</span></kbd>ndent 
from the current left margin at
+      which to begin the object</li>
+  <li>the <kbd><span style="text-decoration: underline">L</span></kbd>ength of 
the object, if applicable</li>
+  <li>the <kbd><span style="text-decoration: underline">D</span></kbd>epth of 
the object, if applicable</li>
+  <li>the <kbd><span style="text-decoration: underline">C</span></kbd>olour of 
the object (optional)</li>
+</ul>
+
+<p>
+A simple mnemonic for the order of arguments is &#8220;<b>WILD
+C</b>ard&#8221;.  If you fix the mnemonic in your brain and apply
+a little judicious reasoning, you&#8217;ll always remember how to
+draw graphical objects.  The &#8220;judicious reasoning&#8221; means
+that, for example, horizontal rules don&#8217;t require a depth and
+vertical rules don&#8217;t require a length.  Thus, in the case of
+drawing a horizontal rule, you supply the macro,
+<kbd><a href="#drh">DRH</a></kbd>,
+with only the arguments (from the mnemonic) that apply: <b>W-I-L</b> (and
+possibly <b>C</b>).
+</p>
+
+<div class="macro-list-container">
+<h3 id="index-graphical" class="macro-list">Graphical objects macros</h3>
+
+<ul class="macro-list">
+  <li><a href="#drh">DRH</a>
+      &ndash; horizontal rules</li>
+  <li><a href="#drv">DRV</a>
+      &ndash; vertical rules</li>
+  <li><a href="#dbx">DBX</a>
+      &ndash; box</li>
+  <li><a href="#dcl">DCL</a>
+      &ndash; circles or ellipses</li>
+</ul>
+</div>
+
+<!-- -DRH- -->
+
+<div class="macro-id-overline">
+<h3 id="drh" class="macro-id">Drawing horizontal rules</h3>
+</div>
+
+<div class="box-macro-args">
+Macro: <b>DRH</b> <kbd class="macro-args">&lt;none&gt; | &lt;weight&gt;  
&lt;indent&gt; &lt;length&gt; [&lt;colour&gt;]</kbd>
+</div>
+
+<p class="requires">
+&bull;&nbsp;The argument to <kbd class="normal">&lt;weight&gt;</kbd> is in
+<a href="definitions.html#picaspoints" class="normal">points</a>,
+but do <span class="normal">NOT</span> append the
+<a href="definitions.html#unitsofmeasure">unit of measure</a>,
+<kbd class="normal">p</kbd>.
+<br/>
+&bull;&nbsp;The arguments, <kbd class="normal">&lt;indent&gt;</kbd> and
+<kbd class="normal">&lt;length&gt;</kbd>, require a unit of measure.
+</p>
+
+<p>
+If all you want is to draw a rule from your current left
+margin to your current right margin (in other words, a &quot;full
+measure&quot; rule), you may invoke <kbd>.DRH</kbd> without any
+arguments.
+</p>
+<div class="box-tip">
+<p class="tip">
+<span class="note">Note:</span>
+DRH is the only graphical object macro that may be invoked
+without arguments.  The weight (&#8220;thickness&#8221;) of
+the rule is determined by the argument you last gave the
+macro, <a href="inlines.html#rule-weight">RULE_WEIGHT</a>.
+DRH, used this way, is exactly equivalent to entering the
+<a href="definitions.html#inlines">inline escape</a>, <a
+href="inlines.html#inline-rule-mom"><kbd>\*[RULE]</kbd></a>.
+</p>
+</div>
+
+<p style="margin-top: -.5em;">
+To draw horizontal rules of a specified length, you must, at
+a minimum, supply DRH with the arguments <kbd>weight,</kbd>
+<kbd>indent</kbd> (measured from the current left margin) and
+<kbd>length</kbd>.
+</p>
+
+<p>
+Optionally, you may give a <kbd>colour</kbd> argument.  The colour
+may be either one defined with
+<a href="color.html#newcolor">NEWCOLOR</a>,
+or a named X-colour inititialized with
+<a href="color.html#xcolor">XCOLOR</a>,
+or an X-colour alias (again, initialized with XCOLOR).
+</p>
+
+<p>
+Say, for example, you want to draw a 1-1/4 point horizontal rule
+that starts 2 picas from the current left margin and runs for 3
+inches.  To do so, you'd invoke <kbd>.DRH</kbd> like this:
+<br/>
+<span class="pre-in-pp">
+      weight  length
+         |      |
+  .DRH 1.25 2P 3i
+            |
+          indent
+</span>
+(Note that the rule weight argument, which is expressed in points,
+must NOT have the unit of measure <kbd>p</kbd> appended to it.)
+</p>
+
+<p>
+If, in addition, you want the rule blue:
+<br/>
+<span class="pre-in-pp">
+  .DRH 1.25 2P 3i blue
+</span>
+</p>
+
+<h3 class="docs">How mom handles the positioning of horizontal rules</h3>
+
+<p>
+Horizontal rules are drawn from left to right, and from the baseline
+down. &#8220;From the baseline down&#8221; means that if you request
+a rule with a weight of four points, the four points of rule fall
+entirely below the baseline.
+</p>
+
+<p>
+Furthermore, after the rule is drawn, mom returns you to the current
+left margin, at the same vertical position on the page as when DRH
+was invoked.  In other words, DRH causes no movement on the page,
+either horizontal or vertical.
+</p>
+
+<!-- -DRV- -->
+
+<div class="macro-id-overline">
+<h3 id="drv" class="macro-id">Drawing vertical rules</h3>
+</div>
+
+<div class="box-macro-args">
+Macro: <b>DRV</b> <kbd class="macro-args">&lt;weight&gt;  &lt;indent&gt; 
&lt;depth&gt; [&lt;colour&gt;]</kbd>
+</div>
+
+<p class="requires">
+&bull;&nbsp;The argument to <kbd class="normal">&lt;weight&gt;</kbd> is in
+<a href="definitions.html#picaspoints" class="normal">points</a>,
+but do <span class="normal">NOT</span> append the
+<a href="definitions.html#unitsofmeasure">unit of measure</a>,
+<kbd class="normal">p</kbd>.
+<br/>
+&bull;&nbsp;The arguments, <kbd class="normal">&lt;indent&gt;</kbd> and
+<kbd class="normal">&lt;depth&gt;</kbd>, require a unit of measure.
+</p>
+
+<p>
+To draw vertical rules of a specified length, you must, at
+a minimum, supply DRV with the arguments <kbd>weight,</kbd>
+<kbd>indent</kbd> (measured from the current left margin) and
+<kbd>depth</kbd>.
+</p>
+
+<p>
+Optionally, you may give a <kbd>colour</kbd> argument.  The colour
+may be either one defined with
+<a href="color.html#newcolor">NEWCOLOR</a>,
+or a named X-colour inititialized with
+<a href="color.html#xcolor">XCOLOR</a>,
+or an X-colour alias (again, initialized with XCOLOR).
+</p>
+
+<p>
+Say, for example, you want to draw a 3/4-point vertical rule that
+starts 19-1/2 picas from the current left margin and has a depth of
+6 centimeters.  To do so, you'd invoke <kbd>.DRV</kbd> like this:
+<br/>
+<span class="pre-in-pp">
+       weight   depth
+         |        |
+  .DRV .75 19P+6p 6c
+             |
+           indent
+</span>
+(Note that the rule weight argument, which is expressed in points,
+must NOT have the unit of measure <kbd>p</kbd> appended to it.)
+</p>
+
+<p>
+If, in addition, you want the rule red:
+<br/>
+<span class="pre-in-pp">
+  .DRV .75 19P+6p 6c red
+</span>
+</p>
+
+<h3 class="docs">How mom handles the positioning of vertical rules</h3>
+
+<p>
+Vertical rules are drawn from the baseline down, and from left to
+right. &quot;Left to right&quot; means that if you request a rule
+with a weight of four points, the four points of rule fall entirely
+to the left of the indent given to DRV.
+</p>
+
+<p>
+Furthermore, after the rule is drawn, mom returns you to the current
+left margin, at the same vertical position on the page as when DRV
+was invoked.  In other words, DRV causes no movement on the page,
+either horizontal or vertical.
+</p>
+
+<!-- -DBX- -->
+
+<div class="macro-id-overline">
+<h3 id="dbx" class="macro-id">Drawing boxes</h3>
+</div>
+
+<div class="box-macro-args">
+Macro: <b>DBX</b> <kbd class="macro-args">&lt; &lt;weight&gt; | SOLID &gt; 
&lt;indent&gt; &lt;length&gt; &lt;depth&gt; [&lt;colour&gt;]</kbd>
+</div>
+
+<p class="requires">
+&bull;&nbsp;The argument to <kbd class="normal">&lt;weight&gt;</kbd> is in
+<a href="definitions.html#picaspoints" class="normal">points</a>,
+but do <span class="normal">NOT</span> append the
+<a href="definitions.html#unitsofmeasure">unit of measure</a>,
+<kbd class="normal">p</kbd>.
+<br/>
+&bull;&nbsp;The arguments, <kbd class="normal">&lt;indent&gt;</kbd>,
+<kbd class="normal">&lt;length&gt;</kbd> and
+<kbd class="normal">&lt;depth&gt;</kbd>, require a unit of measure.
+</p>
+
+<p>
+To draw boxes of specified dimensions, you must, at a minimum,
+supply DBX with the arguments <kbd>weight</kbd> or <kbd>SOLID</kbd>,
+<kbd>indent</kbd> (measured from the current left margin),
+<kbd>length</kbd> and <kbd>depth</kbd>.
+</p>
+
+<p>
+Optionally, you may give a <kbd>colour</kbd> argument.  The colour
+may be either one defined with
+<a href="color.html#newcolor">NEWCOLOR</a>,
+or a named X-colour inititialized with
+<a href="color.html#xcolor">XCOLOR</a>,
+or an X-colour alias (again, initialized with XCOLOR).
+</p>
+
+<p>
+Say, for example, you want to draw a 1/2 point outline box that
+starts one inch from the current left margin and has the dimensions 
+12 picas x 6 picas.  To do so, you'd invoke <kbd>.DBX</kbd> like this:
+<br/>
+<span class="pre-in-pp">
+         indent   depth
+           |        |
+  .DBX .5  1i  12P  6P
+        |       |
+     weight   length
+</span>
+(Note that the box weight argument, which is expressed in points,
+must NOT have the unit of measure <kbd>p</kbd> appended to it.)
+</p>
+
+<p>
+If you want the same box, but solid (&#8220;filled&#8221;) rather
+than drawn as an outline:
+<br/>
+<span class="pre-in-pp">
+  .DBX SOLID 1i 12P 6P
+</span>
+Additionally, if you want the box green:
+<br/>
+<span class="pre-in-pp">
+  .DBX .5 1i 12P 6P green
+   or
+  .DBX SOLID 1i 12P 6P green
+</span>
+</p>
+
+<h3 class="docs">How mom handles the positioning of boxes</h3>
+
+<p>
+Boxes are drawn from the baseline down, from left to right, and
+from the perimeter <i>inward</i>. &#8220;From the perimeter
+inward&#8221; means that if you request a box weight of six points,
+the 6-point rules used to draw the outline of the box fall entirely
+<i>within</i> the dimensions of the box.
+</p>
+
+<p>
+Furthermore, after the box is drawn, mom returns you to the current
+left margin, at the same vertical position on the page as when DBX
+was invoked.  In other words, DBX causes no movement on the page,
+either horizontal or vertical.
+</p>
+
+<!-- -DCL- -->
+
+<div class="macro-id-overline">
+<h3 id="dcl" class="macro-id">Drawing circles (ellipses)</h3>
+</div>
+
+<div class="box-macro-args">
+Macro: <b>DCL</b> <kbd class="macro-args">&lt; &lt;weight&gt; | SOLID &gt; 
&lt;indent&gt; &lt;length&gt; &lt;depth&gt; [&lt;colour&gt;]</kbd>
+</div>
+
+<p class="requires">
+&bull;&nbsp;The argument to <kbd class="normal">&lt;weight&gt;</kbd> is in
+<a href="definitions.html#picaspoints" class="normal">points</a>,
+but do <span class="normal">NOT</span> append the
+<a href="definitions.html#unitsofmeasure">unit of measure</a>,
+<kbd class="normal">p</kbd>.
+<br/>
+&bull;&nbsp;The arguments, <kbd class="normal">&lt;indent&gt;</kbd>,
+<kbd class="normal">length</kbd> and
+<kbd class="normal">&lt;depth&gt;</kbd>, require a unit of measure.
+</p>
+
+<p>
+To draw circles of specified dimensions, you must, at a minimum,
+supply DCL with the arguments <kbd>weight</kbd> or <kbd>SOLID</kbd>,
+<kbd>indent</kbd> (measured from the current left margin),
+<kbd>length</kbd> and <kbd>depth</kbd>.
+</p>
+
+<p>
+Optionally, you may give a <kbd>colour</kbd> argument.  The colour
+may be either one defined with
+<a href="color.html#newcolor">NEWCOLOR</a>,
+or a named X-colour inititialized with
+<a href="color.html#xcolor">XCOLOR</a>,
+or an X-colour alias (again, initialized with XCOLOR).
+</p>
+
+<p>
+Say, for example, you want to draw a 1/2 point outline circle
+(ellipse, actually, in this case) that starts one inch from the
+current left margin and has the dimensions 6 centimeters x 3
+centimeters.  To do so, you'd invoke <kbd>.DCL</kbd> like this:
+<br/>
+<span class="pre-in-pp">
+         indent  depth
+           |       |
+  .DCL .5  1i  6c  3c
+        |      |
+     weight   ength
+</span>
+(Note that the box weight argument, which is expressed in points,
+must NOT have the unit of measure <kbd>p</kbd> appended to it.)
+</p>
+
+<p>
+If you want the same box, but solid (&#8220;filled&#8221;) rather
+than drawn as an outline:
+<br/>
+<span class="pre-in-pp">
+  .DCL SOLID 1i 6c 3c
+</span>
+Additionally, if you want the circle yellow:
+<br/>
+<span class="pre-in-pp">
+  .DCL .5 1i 6c 3c yellow
+   or
+  .DCL SOLID 1i 6c 3c yellow
+</span>
+</p>
+
+<h3 class="docs">How mom handles the positioning of circles (ellipses)</h3>
+
+<p>
+Circles (ellipses) are drawn from the baseline down, from left
+to right, and from the perimeter <i>inward</i>. &#8220;From the
+perimeter inward&#8221; means that if you request a circle weight of
+six points, the 6-point rule used to draw the outline of the circle
+or ellipse falls entirely <i>within</i> the dimensions of the
+circle or ellipse.
+</p>
+
+<p>
+Furthermore, after the circle is drawn, mom returns you to the
+current left margin, at the same vertical position on the page as
+when DCL was invoked.  In other words, DCL causes no movement on the
+page, either horizontal or vertical.
+</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="docprocessing.html#top">Next: Document processing</a></td>
+</tr>
+</table>
+
+</div>
+
+<div class="bottom-spacer"><br/></div>
+
+</body>
+</html>
+<!-- vim: fileencoding=utf-8: nomodified: -->

Index: headfootpage.html
===================================================================
RCS file: headfootpage.html
diff -N headfootpage.html
--- /dev/null   1 Jan 1970 00:00:00 -0000
+++ headfootpage.html   18 Aug 2010 22:45:35 -0000      1.21
@@ -0,0 +1,2181 @@
+<?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, page headers/footers and 
pagination</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="rectoverso.html#top">Next: 
Recto/verso printing, collating</a></td>
+</tr>
+</table>
+
+<h1 class="docs">Page headers/footers, pagination</h1>
+
+<div style="text-align: center;">
+<ul class="no-enumerator" style="margin-left: -2.5em;">
+  <li><a href="#headfootpage-intro">Introduction &ndash; VERY IMPORTANT; read 
me!</a></li>
+  <li> <a href="#pagination-note">An important note on pagination</a></li>
+  <li><a href="#description-general">General description of 
headers/footers</a></li>
+  <li><a href="#header-style">Default specs for headers/footers</a></li>
+  <li><a href="#vertical-spacing">Vertical placement and spacing of 
headers/footers</a></li>
+</ul>
+</div>
+
+<div class="rule-medium"><hr/></div>
+
+<h2 id="toc-doc-head-foot-page" class="docs" style="text-align: center;">Table 
of contents</h2>
+
+<h3 class="toc toc-docproc-header" style="margin-top: 1em;"><a 
class="header-link" href="#headfoot-management">Managing page headers and 
footers</a></h3>
+<ul class="toc-docproc" style="margin-top: .5em;">
+  <li><a href="#headers">HEADERS</a> &ndash; on or off</li>
+  <li><a href="#footers">FOOTERS</a> &ndash; on or off</li>
+  <li><a href="#footer-on-first-page">FOOTER_ON_FIRST_PAGE</a></li>
+</ul>
+<h3 class="toc toc-docproc-header"><a class="header-link" 
href="#headfoot-control">Control macros for headers/footers</a></h3>
+  <ul class="toc-docproc" style="margin-top: .5em;">
+    <li><a href="#index-headfoot-control">Header/footer control macros and 
defaults</a>
+  <ul class="toc-docproc">
+    <li><a href="#hdrftr-strings">Header/footer strings</a>
+    <ul class="toc-docproc">
+      <li><a href="#reserved-strings">Using mom&#8217;s reserved strings in 
header/footer definitions</a> (TITLE, AUTHOR, etc.)</li>
+    </ul></li>
+    <li><a href="#hdrftr-style">Header/footer style</a>
+    <ul class="toc-docproc">
+      <li><a href="#hdrftr-style-global">Global changes</a></li>
+      <li><a href="#hdrftr-style-part">Part-by-part changes</a></li>
+    </ul></li>
+    <li><a href="#hdrftr-vertical">Vertical placement and spacing of 
headers/footers</a>
+    <ul class="toc-docproc">
+      <li><a href="#hdrftr-margin">HEADER_MARGIN&nbsp;/&nbsp;FOOTER_MARGIN</a>
+      <ul class="toc-docproc no-enumerator" style="margin-left: -2em;">
+        <li>&ndash;&nbsp;<a href="#footer-margin">Important: FOOTER_MARGIN and 
bottom margins</a></li>
+      </ul></li>
+    </ul></li>
+    <li><a href="#hdrftr-separator">The header/footer separator rule</a>
+    <ul class="toc-docproc">
+      <li><a href="#hdrftr-rule">HEADER_RULE</a> &ndash; on or off</li>
+      <li><a href="#hdrftr-rule-weight">HEADER_RULE_WEIGHT</a> &ndash; weight 
of the rule</li>
+      <li><a href="#hdrftr-rule-gap">HEADER_RULE_GAP</a> &ndash; distance of 
rule from header/footer</li>
+      <li><a href="#hdrftr-rule-color">HEADER_RULE_COLOR</a> &ndash; colour of 
the header/footer rule</li>
+    </ul></li>
+  </ul></li>
+</ul>
+<h3 class="toc toc-docproc-header"><a class="header-link" 
href="#userdef-hdrftr-rv">User-defined, single string recto/verso 
headers/footers</a></h3>
+<ul class="toc-docproc" style="margin-top: .5em;">
+  <li><a href="#hdrftr-recto">HEADER_RECTO, HEADER_VERSO</a>
+  <ul style="margin-left: -.5em">
+    <li><a href="#userdef-hdrftr">User-defined, single string headers/footers 
(no recto/verso)</a></li>
+    <li><a href="#padding-hdrftr">Padding the header-recto/header-verso 
string</a></li>
+  </ul></li>
+</ul>
+<h3 class="toc toc-docproc-header"><a class="header-link" 
href="#headers-and-footers-intro">Headers and footers on the same page</a></h3>
+<h3 class="toc toc-docproc-header" style="margin-top: .75em;"><a 
class="header-link" href="#pagination-intro">Pagination</a></h3>
+<ul class="toc-docproc" style="margin-top: .5em;">
+  <li><a href="#index-pagination">Pagination macros</a></li>
+  <li><a href="#index-pagination-control">Pagination control macros and 
defaults</a></li>
+</ul>
+<h3 class="toc toc-docproc-header"><a class="header-link" 
href="#blank-pages">Inserting blank pages into a document</a></h3>
+
+<div class="rule-medium" style="margin-top: 1.5em;"><hr/></div>
+
+<h2 id="headfootpage-intro" class="macro-group">Managing page headers and 
footers</h2>
+
+<div id="headerfooter" class="box-tip">
+<p class="tip-top">
+<span class="note">Note:</span>
+Because headers and footers are virtually identical, this
+documentation addresses itself only to headers.  In all cases,
+unless otherwise noted, descriptions of headers describe footers as
+well.
+</p>
+
+<p class="tip-bottom">
+Furthermore, any
+<a href="definitions.html#controlmacro">control macro</a>
+that begins with HEADER_ may be used to control footers, simply by
+replacing HEADER_ with FOOTER_.
+</p>
+</div>
+
+<p style="margin-top: -.75em;">
+<a href="definitions.html#header">Headers</a>
+and
+<a href="definitions.html#footer">footers</a>,
+as defined in the section
+<a href="definitions.html#mom">Mom&#8217;s Document Processing Terms</a>,
+are those parts of a document that contain information about the document
+itself which appear in the margins either above or below
+<a href="definitions.html#running">running text</a>.
+They are, in all respects but two, identical.  The differences are:
+</p>
+<ol style="margin-top: -.5em; margin-bottom: -.5em;">
+  <li>headers appear in the margin <i>above</i> running text while
+      footers appear in the margin <i>beneath</i> running text;
+  </li>
+  <li>the (optional) rule that separates headers from running
+      text appears <i>below</i> the header while
+      the (optional) rule that separates footers from running
+      text appears <i>above</i> the footer.
+  </li>
+</ol>
+
+<div id="pagination-note" class="box-tip" style="margin-top: 1.5em;">
+<p class="tip">
+<span class="note">Note:</span>
+While the single page number that mom generates in either the top
+or bottom margin above or below running text is technically a kind
+of header/footer, mom and this documentation treat it as a separate
+page element.
+</p>
+</div>
+
+<div id="author-note" class="box-tip">
+<p class="tip">
+<span class="note">Author's note:</span>
+Left to their own devices (i.e. if you&#8217;re happy with the way
+mom does things by default), headers are something you never have to
+worry about.  You can skip reading this section entirely.  But if
+you want to change them, be advised that headers have more macros to
+control their appearance than any other document element.  The text
+of this documentation becomes correspondingly dense at this point.
+</p>
+</div>
+
+<h3 id="description-general" class="docs">General description of 
headers/footers</h3>
+
+<p>
+Headers comprise three distinct parts: a left part, a centre part,
+and a right part.  Each part contains text (a &#8220;string&#8221;)
+that identifies some aspect of the document as a whole.
+</p>
+
+<p>
+&#8221;The left part (&#8220;header-left) lines up with the
+document&#8217;s left margin.  The centre part (&#8220;header
+centre&#8220;) is centred on the document&#8217;s line length.
+&#8221;The right part (&#8220;header-right) lines up with the
+document&#8217;s right margin.  Not all parts need contain a string,
+and if you don&#8217;t want headers at all, you can turn them off
+completely.
+</p>
+
+<div class="box-tip">
+<p class="tip">
+<span class="note">Note to groff experts:</span>
+Although mom&#8217;s headers resemble the three-part titles
+generated by <kbd>.tl</kbd>, they&#8217;re in no way related to it,
+nor based upon it. <kbd>.tl</kbd> is not used at all in mom.
+</p>
+</div>
+
+<p>
+Normally, mom fills headers with strings appropriate to the document
+type selected with
+<a href="docprocessing.html#doctype">DOCTYPE</a>.
+You can, however, supply whatever strings you like&mdash;including
+page numbers&mdash;to go in any part of headers.  What&#8217;s more,
+you can set the family, font, size, colour and capitalization style
+(caps or caps/lower-case) for each header part individually.
+</p>
+
+<p>
+By default, mom prints a horizontal rule beneath headers to separate
+them visually from running text.  In the case of footers, the rule
+is above.  You can increase or decrease the space between the header
+and the rule if you like (with
+<kbd><a href="#hdrftr-rule-gap">HEADER_RULE_GAP</a></kbd>),
+or remove it completely.
+</p>
+
+<h3 id="header-style" class="docs">Default specs for headers/footers</h3>
+
+<p>
+Mom makes small type adjustments to each part of the header (left,
+centre, right) to achieve an aesthetically pleasing result.  The
+defaults are listed below.  (The strings mom puts by default in each
+part are explained in
+<a href="docprocessing.html#doctype">DOCTYPE</a>.)
+</p>
+
+<div class="defaults-container" style="padding-bottom: 8px;">
+<p class="defaults" style="padding-top: 6px; padding-bottom: 6px; text-align: 
center;">
+<i>Note:</i> Except for capitalization (all caps or caps/lower-case),
+these defaults apply only to
+<a href="docprocessing.html#printstyle">PRINTSTYLE&nbsp;<kbd>TYPESET</kbd></a>.
+</p>
+<span class="pre defaults">
+TYPE SPEC    HEADER LEFT         HEADER CENTER       HEADER RIGHT
+---------    -----------         -------------       ------------
+Family       document default    document default    document default
+Font         roman               italic              roman
+Colour       (black)             (black)             (black)
+All caps     no                  no                  yes
+Size*        -.5 (points)        -.5 (points)        -2 (points)
+            (-2 if all caps)    (-2 if all caps)    (-.5 if not all caps)
+
+*Relative to the point size of type in paragraphs
+</span>
+</div>
+
+<p style="margin-top: -1.5em;">
+You can, of course, change any of the defaults using the appropriate
+control macros.  And should you wish to design headers from the
+ground up, mom has a special macro,
+<a href="#hdrftr-plain">HEADER_PLAIN</a>,
+that removes all type adjustments to headers.  The straightforward
+type specs for paragraphs are used instead, providing a simple
+reference point for any alterations you want to make to the family,
+font, size and capitalization style of any header part.
+</p>
+
+<h3 id="vertical-spacing" class="docs">Vertical placement and spacing of 
headers/footers</h3>
+
+<p>
+As explained in the section,
+<a href="docprocessing.html#behaviour">Typesetting macros during document 
processing</a>,
+the top and bottom margins of a mom document are the vertical start
+and end positions of
+<a href="definitions.html#running">running text</a>,
+not the vertical positions of headers or footers, which, by definition,
+appear in the margins above (or below) running text.
+</p>
+
+<p>
+The vertical placement of headers is controlled by the macro
+<a href="#hdrftr-margin">HEADER_MARGIN</a>,
+which establishes the
+<a href="definitions.html">baseline</a>
+position of headers relative to the top edge of the page.  The
+header rule, whose position is relative to the header itself, is
+controlled by a separate macro.
+</p>
+
+<p>
+FOOTER_MARGIN is the counterpart to HEADER_MARGIN, and establishes
+the baseline position of footers relative to the bottom edge of the
+page.
+</p>
+
+<p>
+The distance between headers and the start
+of running text can be controlled with the macro,
+<a href="#hdrftr-gap">HEADER_GAP</a>
+(effectively making HEADER_MARGIN + HEADER_GAP the top margin of
+running text unless you give mom a literal top margin (with
+<a href="typesetting.html#t-margin">T_MARGIN</a>),
+in which case she ignores HEADER_GAP and begins the running text at
+whatever top margin you give.
+</p>
+
+<p>
+FOOTER_GAP and
+<a href="typesetting.html#b-margin">B_MARGIN</a>
+work similarly, except they determine where running text <i>ends</i>
+on the page.  (See
+<a href="#footer-margin">Important &ndash; footer margin and bottom margins</a>
+for a warning about possible conflicts between the footer margin and
+the bottom margin.)
+</p>
+
+<p>
+Confused?  Mom apologizes.  It&#8217;s really quite simple.  By
+default, mom sets headers 4-1/2
+<a href="definitions.html#picaspoints">picas</a>
+down from the top of the page and begins the running text 3 picas
+(the HEADER_GAP) beneath that, which means the effective top margin
+of the running text is 7-1/2 picas (visually approx. 1 inch).
+However, if you give mom a literal top margin (with
+<a href="typesetting.html#t-margin">T_MARGIN</a>),
+she ignores the HEADER_GAP and starts the running text at whatever
+top margin you give.
+</p>
+
+<p>
+Footers are treated similarly.  Mom sets footers 3 picas up from the
+bottom of the page, and interrupts the processing of running text 3
+picas (the FOOTER_GAP) above that (again, visually approx. 1 inch).
+However, if you give mom a literal bottom margin (with
+<a href="typesetting.html#b-margin">B_MARGIN</a>),
+she ignores the FOOTER_GAP and interrupts the processing of running
+text at whatever bottom margin you give.
+</p>
+
+<p>
+If mom is paginating your document (she does, by default, at the
+bottom of each page), the vertical spacing and placement of page
+numbers, whether at the top or the bottom of the page, is managed
+exactly as if the page numbers were headers (or footers), and are
+controlled by the same macros.  See
+<a href="#pagination">Pagination control</a>.
+</p>
+
+<div class="rule-short"><hr/></div>
+
+<!-- ======================================================================== 
-->
+
+<h2 id="headfoot-management" class="macro-group">Managing headers/footers</h2>
+
+<p>
+The following are the basic macros for turning
+<a href="definitions.html#header">headers</a>
+or
+<a href="definitions.html#footer">footers</a>
+on or off.  They should be invoked prior to
+<a href="docprocessing.html#start">START</a>.
+</p>
+
+<p>
+By default, mom prints page headers.  If you turn
+them off, she will begin the
+<a href="definitions.html#running">running text</a>
+on each page with a default top margin of 6
+<a href="definitions.html#picaspoints">picas</a>
+unless you have requested a different top margin (with
+<a href="typesetting.html#t-margin">T_MARGIN</a>)
+prior to
+<a href="docprocessing.html#start">START</a>.
+</p>
+
+<div class="box-tip">
+<p class="tip">
+<span class="note">Note:</span>
+<a href="#headers">HEADERS</a>
+and
+<a href="#footers">FOOTERS</a>
+are mutually exclusive.  If headers are on, footers (but not
+bottom-of-page numbering) are automatically turned off.  Equally,
+if footers are on, headers (but not top-of-page numbering) are
+automatically turned off.  Thus, if you&#8217;d prefer footers in a
+document, you need only invoke
+<kbd><a href="#footers">.FOOTERS</a></kbd>;
+there&#8217;s no need to turn headers off first.
+</p>
+</div>
+
+<p>
+If you need both headers and footers, there&#8217;s a special macro,
+<a href="#headers-and-footers">HEADERS_AND_FOOTERS</a>,
+that allows you to set it up.
+</p>
+
+<div class="macro-list-container">
+<h3 id="index-hdrftr" class="macro-list">Header/footer macros</h3>
+<ul class="macro-list">
+  <li><a href="#headers">HEADERS</a> &ndash; on or off</li>
+  <li><a href="#footers">FOOTERS</a> &ndash; on or off</li>
+  <li><a href="#footer-on-first-page">FOOTER_ON_FIRST_PAGE</a></li>
+  <li><a href="#userdef-hdrftr-rv">User-defined, single string recto/verso 
headers/footers</a>
+  <ul>
+    <li><a href="#hdrftr-rectoverso">HEADER_RECTO, HEADER_VERSO</a>
+    <ul style="margin-left: -.5em;">
+      <li><a href="#userdef-hdrftr">User-defined, single string 
headers/footers (no recto/verso)</a></li>
+    </ul></li>
+    <li><a href="#reserved-strings">Using mom&#8217;s reserved strings in 
header/footer definitions</a>
+        (title, author, etc.)
+    </li>
+  </ul></li>
+  <li><a href="#headers-and-footers-intro">HEADERS_AND_FOOTERS</a> &ndash;
+       putting both headers and footers on document pages
+  </li>
+  <li><a href="#headfoot-control">Header and footer control macros</a></li>
+</ul>
+</div>
+
+<!-- -HEADERS- -->
+
+<div class="macro-id-overline">
+<h3 class="macro-id">Headers</h3>
+</div>
+
+<div id="headers" class="box-macro-args">
+Macro: <b>HEADERS</b> <kbd class="macro-args">toggle</kbd>
+</div>
+
+<p>
+<a href="definitions.html#header">Page headers</a>
+are on by default.  If you don&#8217;t want them, turn them off by
+invoking <kbd>.HEADERS</kbd> with any argument (<b>OFF, QUIT,
+END, X...</b>), e.g.
+<br/>
+<span class="pre-in-pp">
+    .HEADERS OFF
+</span>
+</p>
+
+<p>
+<b>NOTE:</b> HEADERS automatically
+disables 
+<a href="definitions.html#footer">footers</a>
+(you can&#8217;t have both), but not the page numbers that normally
+appear at the bottom of the page.
+</p>
+
+<p>
+<b>ADDITIONAL NOTE:</b> If HEADERS
+are OFF, mom&#8217;s normal top
+margin for
+<a href="definitions.html#running">running text</a>
+(7.5
+<a href="definitions.html#picaspoints">picas</a>)
+changes to 6 picas (visually approx. 1 inch).  This does NOT apply
+to the situation where footers have been explicitly turned on
+(with
+<kbd><a href="#footers">FOOTERS</a></kbd>).
+Explicitly invoking footers moves page numbering to the
+top of the page, where its placement and spacing are the same as
+for headers.  (I.e. the top margin of running text remains 7.5
+picas.)
+</p>
+
+<!-- -FOOTERS- -->
+
+<div class="macro-id-overline">
+<h3 id="footers" class="macro-id">Footers</h3>
+</div>
+
+<div class="box-macro-args">
+Macro: <b>FOOTERS</b> <kbd class="macro-args">toggle</kbd>
+</div>
+
+<p>
+<a href="definitions.html#footer">Page footers</a>
+are off by default.  If you want them instead of
+<a href="definitions.html#header">headers</a>
+(you can&#8217;t have both), turn them on by invoking
+<kbd>.FOOTERS</kbd> without an argument, e.g.
+<br/>
+<span class="pre-in-pp">
+    .FOOTERS
+</span>
+</p>
+
+<p>
+FOOTERS automatically disables headers, and
+mom shifts the placement of page numbers from their
+normal position at page bottom to the top of the page.
+</p>
+
+<p>
+<b>NOTE:</b> By default, when footers are on,
+mom does not print a page number on the first
+page of a document, nor on first pages after
+<a href="rectoverso.html#collate">COLLATE</a>.
+If you don&#8217;t want this behaviour, you can change it with
+<kbd><a href="#pagenum-on-first-page">PAGENUM_ON_FIRST_PAGE</a></kbd>.
+</p>
+
+<!-- -FOOTER_ON_FIRST_PAGE- -->
+
+<div class="macro-id-overline">
+<h3 id="footer-on-first-page" class="macro-id">Footer on first page</h3>
+</div>
+
+<div class="box-macro-args">
+Macro: <b>FOOTER_ON_FIRST_PAGE</b> <kbd class="macro-args">toggle</kbd>
+</div>
+
+<p>
+If you invoke
+<a href="#footers"><kbd>.FOOTERS</kbd></a>,
+mom, by default, does not print a footer on the
+first page of the document.  (The
+<a href="definitions.html">docheader</a>
+on page 1 makes it redundant.)  However, should you wish a footer on
+page 1, invoke <kbd>.FOOTER_ON_FIRST_PAGE</kbd> without any argument.
+</p>
+
+<div class="rule-short"><hr/></div>
+
+<h2 id="headfoot-control" class="macro-group">Control macros for 
headers/footers</h2>
+
+<p>
+Virtually every part of headers (and footers; see the note on how
+<a href="#headerfooter">&#8220;headers&#8221; means &#8220;footers&#8221;</a>
+in the
+<a href="#headfootpage-intro">Introduction</a>
+to headers/footers) can be designed to your own specifications.
+</p>
+
+<div class="macro-list-container">
+<h3 id="index-headfoot-control" class="macro-list">Header/footer control 
macros and defaults</h3>
+
+<ol style="margin-top: -1.5em; padding-bottom: 6px;">
+  <li><a href="#hdrftr-strings">Header/footer strings</a>
+  <ul style="margin-left: -.5em;">
+    <li><a href="#hdrftr-left">HEADER_LEFT</a></li>
+    <li><a href="#hdrftr-centre">HEADER_CENTER</a>
+    <ul style="margin-left: -.5em;">
+      <li><a href="#hdrftr-centre-pad">Padding the header-centre 
string</a></li>
+    </ul></li>
+    <li><a href="#hdrftr-right">HEADER_RIGHT</a></li>
+    <li><a href="#reserved-strings">Using mom&#8217;s reserved strings in 
header/footer definitions</a>
+        (e.g. <kbd>\E*[$TITLE]</kbd> when you want
+        <br/>
+        the title, <kbd>\E*[$AUTHOR]</kbd> when you want the author, etc.)
+    </li>
+    <li><a href="#page-number-symbol">Replacing header-left, centre or right 
with the page number</a></li>
+    <li><a href="#page-number-incl">Including the  page number in header-left, 
centre or right</a></li>
+  </ul></li>
+  <li><a href="#hdrftr-style">Header/footer style</a>
+  <ul style="margin-left: -.5em;">
+    <li><a href="#hdrftr-style-global">Global changes</a>
+    <ul style="margin-left: -.5em;">
+      <li><a href="#hdrftr-global-family">HEADER_FAMILY</a> &ndash; family for 
entire header</li>
+      <li><a href="#hdrftr-global-size">HEADER_SIZE</a> &ndash; size for 
entire header</li>
+      <li><a href="#hdrftr-plain">HEADER_PLAIN</a> &ndash; disable default 
adjustments to header parts</li>
+      <li><a href="#hdrftr-color">HEADER_COLOR</a> &ndash; colourize the 
header</li>
+    </ul></li>
+    <li><a href="#hdrftr-style-part">Part-by-part changes</a>
+    <ul style="margin-left: -.5em;">
+      <li><a href="#_family">_FAMILY</a> &ndash; left, centre or right 
family</li>
+      <li><a href="#_font">_FONT</a> &ndash; left, centre or right font</li>
+      <li><a href="#_size">_SIZE</a> &ndash; left, centre or right size</li>
+      <li><a href="#_caps">_CAPS</a> &ndash; left, centre or right all 
caps</li>
+      <li><a href="#_color">_COLOR</a> &ndash; left, centre or right 
colour</li>
+    </ul></li>
+  </ul></li>
+  <li><a href="#hdrftr-vertical">Header/footer vertical placement and 
spacing</a>
+  <ul style="margin-left: -.5em;">
+    <li><a href="#hdrftr-margin">HEADER_MARGIN</a></li>
+    <li><a href="#hdrftr-gap">HEADER_GAP</a></li>
+  </ul></li>
+  <li><a href="#hdrftr-separator">Header/footer separator rule</a>
+  <ul style="margin-left: -.5em;">
+    <li><a href="#hdrftr-rule">HEADER_RULE</a></li>
+    <li><a href="#hdrftr-rule-weight">HEADER_RULE_WEIGHT</a></li>
+    <li><a href="#hdrftr-rule-gap">HEADER_RULE_GAP</a></li>
+    <li><a href="#hdrftr-rule-color">HEADER_RULE_COLOR</a></li>
+  </ul></li>
+</ol>
+</div>
+
+<!-- -HDRFTR_STRINGS- -->
+
+<h4 id="hdrftr-strings" class="docs">1. Header/footer strings</h4>
+
+<div id="hdrftr-left" class="box-macro-args" style="margin-top: 1em;">
+&#8221;Macro: <b>HEADER_LEFT</b> <kbd class="macro-args">&#8220;&lt;text of 
header-left&gt; | #</kbd>
+</div>
+
+<div id="hdrftr-centre" class="box-macro-args" style="margin-top: 1em;">
+&#8221;Macro: <b>HEADER_CENTER</b> <kbd class="macro-args">&#8220;&lt;text of 
header-centre&gt; | #</kbd>
+</div>
+
+<div id="hdrftr-right" class="box-macro-args" style="margin-top: 1em;">
+&#8221;Macro: <b>HEADER_RIGHT</b> <kbd class="macro-args">&#8220;&lt;text of 
header-right&gt; | #</kbd>
+</div>
+
+<p>
+To change the text (the &#8220;string&#8221;) of the left, centre,
+or right part of headers, invoke the appropriate macro, above,
+with the string you want.  For example, mom, by default, prints
+the document&#8217;s author in the header-left position.  If your
+document has, say, two authors, and you want both their names to
+appear header-left, change HEADER_LEFT like this:
+<br/>
+<span class="pre-in-pp">
+  .HEADER_LEFT "R. Stallman, E. Raymond"
+</span>
+</p>
+
+<p>
+Because the arguments to HEADER_LEFT, _CENTER,
+and _RIGHT are
+<a href="definitions.html#stringargument">string arguments</a>,
+they must be enclosed in double-quotes.
+</p>
+
+<div class="box-tip">
+<p class="tip">
+<span class="note">Note:</span>
+Replace HEADER_, above, with FOOTER_ to change the strings in
+footers.
+</p>
+</div>
+
+<h3 id="hdrftr-centre-pad" class="docs">Padding the header/footer centre 
string</h3>
+
+<div class="box-macro-args" style="margin-top: 1em;">
+Macro: <b>HEADER_CENTER_PAD</b> <kbd class="macro-args">LEFT | RIGHT 
&lt;amount of space by which to pad centre string left or right&gt;</kbd>
+</div>
+
+<p class="requires">
+&bull;&nbsp;Requires a <a href="definitions.html#unitofmeasure">unit of 
measure</a>
+</p>
+
+<p>
+By default, mom centres the header-centre string on the line length
+in effect for page headers.
+</p>
+
+<p>
+In some cases, notably when the header-left or header-right
+strings are particularly long, the effect isn&#8217;t pretty.  The
+offendingly long header-left or right crowds, or even overprints,
+the header-centre.  That&#8217;s where HEADER_CENTER_PAD comes
+in.  With a bit of experimentation (yes, you have to preview the
+document), you can use HEADER_CENTER_PAD to move the header-centre
+string left or right until it looks acceptably centred between the
+two other strings.
+</p>
+
+<p>
+For example, say your document is an outline for a novel called
+<i>By the Shores of Lake Attica</i>.  You&#8217;ve told mom you want
+<br/>
+<span class="pre-in-pp">
+  .DOCTYPE NAMED "Outline"
+</span>
+but when you preview your work, you see that &#8220;Outline&#8221;,
+in the centre of the page header, is uncomfortably close to the
+title, which is to the right.  By invoking
+<br/>
+<span class="pre-in-pp">
+  .HEADER_CENTER_PAD RIGHT 3P
+</span>
+you can scoot the word "Outline" over three
+<a href="definitions.html#picaspoints">picas</a>
+<i>to the left</i> (because the padding is added onto the right of the
+string) so that your head looks nicely spaced out.  Invoking
+<kbd>.HEADER_CENTER_PAD</kbd> with the <kbd>LEFT</kbd> argument puts
+the padding on the left side of the string so that it scoots
+right.
+</p>
+
+<p>
+Most reassuring of all is that if you use HEADER_CENTER_PAD
+conjunction with
+<a href="rectoverso.html#recto-verso">RECTO_VERSO</a>,
+mom will pad the centre string appropriately left OR right,
+depending on which page you&#8217;re on, without you having to tell
+her to do so.
+</p>
+
+<h3 id="reserved-strings" class="docs">Using mom&#8217;s reserved strings in 
header/footer definitions</h3>
+
+<p>
+As pointed out in the
+<a href="#author-note">Author&#8217;s note</a>
+in the introduction to headers/footers, headers and footers are
+something you don&#8217;t normally have to worry much about. Mom
+usually knows what to do.
+</p>
+
+<p>
+However, situations do arise where you need to manipulate what goes
+in the header/footer strings, setting and resetting them as you go
+along.
+</p>
+
+<p>
+A case where you might want to do this would be if you want to
+output endnotes at the end of each document in a series of
+<a href="rectoverso.html#collate">collated</a>
+documents, and you want the word "Endnotes" to go in the header
+centre position of the endnotes, but want, say, the
+<a href="docprocessing.html#title">TITLE</a>
+to go back into the centre position for the next output document.
+</p>
+
+<p>
+In scenarios like the above, mom has a number of reserved strings
+you can plug into the HEADER_LEFT, _CENTER and _RIGHT macros.  They
+are:
+<br/>
+<span class="pre-in-pp">
+  \E*[$TITLE]          &mdash;the current argument passed to .TITLE
+  \E*[$DOCTITLE]       &mdash;the current argument passed to .DOCTITLE
+  \E*[$AUTHOR]         &mdash;the current first argument passed to .AUTHOR
+  \E*[$AUTHOR_1...9]   &mdash;the current arguments passed to .AUTHOR
+  \E*[$AUTHORS]        &mdash;a comma-separated concatenated string
+                          of all the current arguments passed to .AUTHOR
+                          (i.e. a list of authors)
+  \E*[$CHAPTER_STRING] &mdash;the current argument passed to .CHAPTER_STRING,
+                          if invoked, otherwise, "Chapter"
+  \E*[$CHAPTER]        &mdash;the current argument (typically a number) passed
+                          to .CHAPTER
+  \E*[$CHAPTER_TITLE]  &mdash;the current argument passed to .CHAPTER_TITLE
+</span>
+Returning to the scenario above, first, you&#8217;d define a centre
+string for the endnotes page:
+<br/>
+<span class="pre-in-pp">
+  .HEADER_CENTER "Endnotes"
+</span>
+Then, you&#8217;d output the endnotes:
+<br/>
+<span class="pre-in-pp">
+  .ENDNOTES
+</span>
+Then, you&#8217;d prepare mom for the next document:
+<br/>
+<span class="pre-in-pp">
+  .COLLATE
+  .TITLE "New Doc Title"
+  .AUTHOR "Josephine Blough"
+</span>
+Then, you&#8217;d redefine the header-centre string using the reserved
+string <kbd>\*[$TITLE]</kbd>, like this:
+<br/>
+<span class="pre-in-pp">
+  .HEADER_CENTER "\E*[$TITLE]"
+</span>
+And last, you&#8217;d do:
+<br/>
+<span class="pre-in-pp">
+  .START
+</span>
+Voilà!  Any argument you pass to
+<a href="docprocessing.html#title">TITLE</a>
+from here on in (say, for subsequent documents) is back in the
+header-centre position.  Here&#8217;s the whole routine again:
+<br/>
+<span class="pre-in-pp">
+  .HEADER_CENTER "Endnotes"
+  .ENDNOTES
+  .COLLATE
+  .TITLE         "New Doc Title"
+  .AUTHOR        "Josephine Blough"
+  .HEADER_CENTER "\E*[$TITLE]"
+  .START
+</span>
+</p>
+
+<p>
+If need be, you can concatenate the strings, as in the following
+example.
+<br/>
+<span class="pre-in-pp">
+  .HEADER_CENTER "\E*[$CHAPTER_STRING] \E*[$CHAPTER]"
+</span>
+which, assuming a <kbd>.CHAPTER_STRING</kbd> of
+<kbd>"Chapter"</kbd> and a <kbd>.CHAPTER</kbd> of
+<kbd>"2"</kbd>, would put &#8220;Chapter 2&#8221; in the
+header-centre position.
+</p>
+
+<h3 id="page-number-symbol" class="docs">Replacing header-left, -centre or 
-right with the page number</h3>
+
+<p>
+If you would like to have the current page number appear in the
+header-left, -centre, or -right position instead of a text string,
+invoke the appropriate macro, above, with the single argument
+<kbd>#</kbd> (the &#8220;number&#8221; or &#8220;pound&#8221; sign).
+Do not surround the pound size with double-quotes, as you would
+normally do if the argument to <kbd>.HEADER_CENTER</kbd> were a
+string.  For example,
+<br/>
+<span class="pre-in-pp">
+  .HEADER_CENTER #
+</span> 
+(notice, no double-quotes) will print the current page number in the
+centre part of headers.
+</p>
+
+<h3 id="page-number-incl" class="docs">Including the page number in 
header-left, -CENTER or -right</h3>
+
+<p>
+If you would like to <i>include</i> the current page number in the
+string you pass to HEADER_LEFT, _CENTER, or _RIGHT, (as
+opposed to replacing the string with the page number), use the
+special
+<a href="definitions.html#inlines">inline escape</a>
+<kbd>\*[PAGE#]</kbd> in the string argument.
+</p>
+
+<p>
+For example, say you have a document that&#8217;s ten pages long,
+and you want header-right to say &#8220;page &lt;whichever&gt; of
+10&#8221;, invoke <kbd>.HEADER_RIGHT</kbd> as follows:
+<br/>
+<span class="pre-in-pp">
+  .HEADER_RIGHT "page \*[PAGE#] of 10"
+</span>
+The header-right of page two will read &#8220;page 2 of 10&#8221;,
+the header-right of page three will read &#8220;page 3 of 10&#8221;,
+and so on.
+</p>
+
+<!-- -HDRFTR_STYLE- -->
+
+<h4 id="hdrftr-style" class="docs">2. Header/footer style</h4>
+
+<h5 id="hdrftr-style-global" class="docs" style="margin-top: 1em;">Global 
changes</h5>
+
+<p style="margin-top: .5em;">
+The following macros allow you to make changes that affect all parts
+of the header at once.
+</p>
+
+<div class="macro-list-container">
+<ul style="padding-top: 6px; padding-bottom: 6px; margin-left: -.5em;">
+  <li><a href="#hdrftr-global-family">HEADER_FAMILY</a></li>
+  <li><a href="#hdrftr-global-size">HEADER_SIZE</a></li>
+  <li><a href="#hdrftr-plain">HEADER_PLAIN</a></li>
+  <li><a href="#hdrftr-color">HEADER_COLOR</a></li>
+</ul>
+</div>
+
+<div id="hdrftr-global-family" class="box-macro-args">
+Macro: <b>HEADER_FAMILY</b> <kbd class="macro-args">&lt;family&gt;</kbd>
+</div>
+
+<p>
+By default, mom uses the default document family for headers.  If
+you would like her to use another
+<a href="definitions.html#family">family</a>
+in headers, invoke <kbd>.HEADER_FAMILY</kbd> with the identifier
+for the family you want.  The argument is the same as for the
+typesetting macro
+<a href="typesetting.html#family">FAMILY</a>.
+</p>
+
+<p>
+Replace HEADER_, above, with FOOTER_ to change the footer family.
+</p>
+
+<div id="hdrftr-global-size" class="box-macro-args">
+Macro: <b>HEADER_SIZE</b> <kbd class="macro-args">&lt;+|-number of 
points&gt;</kbd>
+</div>
+<p class="requires">
+&bull;&nbsp;Argument is relative to the point size of type in paragraphs.
+See
+<span style="font-style: normal;"><a 
href="docelement.html#control-macro-args">Arguments to the control 
macros</a></span>
+for an explanation of how control macros ending in
+_SIZE work.
+</p>
+
+<p>
+By default, mom makes small adjustments to the size of each part
+of a header to achieve an aesthetically pleasing result.  If
+you&#8217;d like her to continue to do so, but would like the
+overall appearance of headers to be a little smaller or a little
+larger, invoke <kbd>.HEADER_SIZE</kbd> with + or - the number of <a
+href="definitions.html#picaspoints">points</a> (fractions allowed)
+by which you want her to in/decrease the size of headers.  For
+example,
+<br/>
+<span class="pre-in-pp">
+  .HEADER_SIZE +.75
+</span>
+increases the size of every part of a header by 3/4 of a point while
+respecting mom&#8217;s own little size changes.
+</p>
+
+<p>
+Replace HEADER_, above, with FOOTER_ to change the footer size.
+</p>
+
+<div class="box-tip">
+<p class="tip">
+<span class="note">Note:</span>
+Normally, macros that control headers have no effect on
+<a href="docprocessing.html#printstyle">PRINTSTYLE <kbd>TYPEWRITE</kbd></a>.
+HEADER_SIZE is an exception.  While all parts of a header in
+PRINTSTYLE&nbsp;<kbd>TYPEWRITE</kbd> are always the same size, you
+can use HEADER_SIZE with PRINTSTYLE&nbsp;<kbd>TYPEWRITE</kbd> to
+reduce the header&#8217;s overall point size.  You&#8217;ll most
+likely require this when the
+<a href="docprocessing.html#copystyle">COPYSTYLE</a>
+is <kbd>DRAFT</kbd>, since portions of the header may overprint if,
+say, the title of your document is very long.
+</p>
+</div>
+
+<div id="hdrftr-color" class="box-macro-args">
+Macro: <b>HEADER_COLOR</b> <kbd class="macro-args">&lt;colorname&gt;</kbd>
+</div>
+
+<p>
+If you want your headers in a colour different from the document
+default (usually black), invoke <kbd>.HEADER_COLOR</kbd> with the
+name of a colour pre-defined (or &#8220;initialized&#8221;) with
+<a href="color.html#newcolor">NEWCOLOR</a>
+or
+<a href="color.html#xcolor">XCOLOR</a>.
+</p>
+
+<p>
+HEADER_COLOR will set all the parts of the header
+plus the header rule in the colour you give it as an argument.  If
+you wish finer control over colour in headers, you can use
+<a href="#_color">HEADER_&lt;POSITION&gt;_COLOR</a>
+to colourize each part of the header separately, as well as
+<a href="#hdrftr-rule-color">HEADER_RULE_COLOR</a>
+to change the colour of the header rule.
+</p>
+
+<p>
+Replace HEADER_, above, with FOOTER_ to colourize footers.
+</p>
+
+<div class="box-macro-args">
+Macro: <b>HEADER_PLAIN</b>
+</div>
+
+<p>
+By default, mom makes adjustments to the font, size, and
+capitalization style of each part of headers to achieve an
+aesthetically pleasing look.  Should you wish to design your own
+headers from the ground up without worrying how changes to the
+various elements of header style interact with mom&#8217;s defaults,
+invoke <kbd>.HEADER_PLAIN</kbd> by itself, with no argument. Mom
+will disable her default behaviour for headers, and reset all
+elements of header style to the same family, font, point size and
+colour as she uses in paragraphs.
+</p>
+
+<p>
+Replace HEADER_, above, with FOOTER_ to disable mom&#8217;s default
+behaviour for the various elements of footer style.
+</p>
+
+<h4 id="hdrftr-style-part" class="docs">3. Part by part changes</h4>
+
+<p>
+When using the following control &#8221;macros, replace
+&#8220;&lt;POSITION&gt; by <b>LEFT, CENTER,</b> or RIGHT as
+appropriate.
+</p>
+
+<div class="macro-list-container">
+<ul style="padding-top: 6px; padding-bottom: 6px; margin-left: -.5em;">
+  <li><a href="#_family">HEADER_&lt;POSITION&gt;_FAMILY</a></li>
+  <li><a href="#_font">HEADER_&lt;POSITION&gt;_FONT</a></li>
+  <li><a href="#_size">HEADER_&lt;POSITION&gt;_SIZE</a></li>
+  <li><a href="#_caps">HEADER_&lt;POSITION&gt;_CAPS</a></li>
+  <li><a href="#_color">HEADER_&lt;POSITION&gt;_COLOR</a></li>
+</ul>
+</div>
+
+<div id="_family" class="box-macro-args">
+Macro: <b>HEADER_&lt;POSITION&gt;_FAMILY</b> <kbd 
class="macro-args">&lt;family&gt;</kbd>
+</div>
+
+<p>
+Use HEADER_&lt;POSITION&gt;_FAMILY to change the
+<a href="definitions.html#family">family</a>
+of any part of headers.  See
+<a href="docelement.html#control-macro-args">Arguments to the control 
macros</a>
+for an explanation of how control macros ending in _FAMILY work.
+</p>
+
+<p>
+Replace HEADER_, above, with FOOTER_ to change a footer part&#8217;s family.
+</p>
+
+<div id="_font" class="box-macro-args">
+Macro: <b>HEADER_&lt;POSITION&gt;_FONT</b> <kbd 
class="macro-args">&lt;font&gt;</kbd>
+</div>
+
+<p>
+Use HEADER_&lt;POSITION&gt;_FONT to change the
+<a href="definitions.html#font">font</a>
+of any part of headers.  See
+<a href="docelement.html#control-macro-args">Arguments to the control 
macros</a>
+for an explanation of how control macros ending in _FONT work.
+</p>
+
+<p>
+Replace HEADER_, above, with FOOTER_ to change a footer part&#8217;s font.
+</p>
+
+<div id="_size" class="box-macro-args">
+Macro: <b>HEADER_&lt;POSITION&gt;_SIZE</b> <kbd 
class="macro-args">&lt;+|-number of points&gt;</kbd>
+</div>
+
+<p>
+Use HEADER_&lt;POSITION&gt;_SIZE to change the size of any part of
+headers (relative to the point size of type in paragraphs).  See
+<a href="docelement.html#control-macro-args">Arguments to the control 
macros</a>
+for an explanation of how control macros ending in _SIZE work.
+</p>
+
+<p>
+Replace HEADER_, above, with FOOTER_ to change a footer part&#8217;s size.
+</p>
+
+<div id="_caps" class="box-macro-args">
+Macro: <b>HEADER_&lt;POSITION&gt;_CAPS</b> <kbd class="macro-args">toggle</kbd>
+</div>
+
+<p>
+HEADER_&lt;POSITION&gt;_CAPS is a
+<a href="definitions.html#toggle">toggle macro</a>.
+If you want any part of headers to be set in all caps, regardless of
+the capitalization of that part&#8217;s string as given to the
+<a href="docprocessing.html#reference-macros">reference macros</a>
+or as defined by you with the
+<a href="#hdrftr-strings">header string control macros</a>,
+simply invoke this macro (using the appropriate position) with no
+argument.  If you wish to turn capitalization off (say, for the
+header-right string that mom capitalizes by default), invoke the
+macro with any argument (e.g. <kbd>OFF, QUIT, END, X</kbd>...).
+</p>
+
+<p>
+Replace HEADER_, above, with FOOTER_ to change a footer part&#8217;s
+capitalization style.
+</p>
+
+<div id="_color" class="box-macro-args">
+Macro: <b>HEADER_&lt;POSITION&gt;_COLOR</b> <kbd 
class="macro-args">&lt;colorname&gt;</kbd>
+</div>
+
+<p>
+HEADER_&lt;POSITION&gt;_COLOR allows you to set a colour for each of
+the three possible parts of a page header separately.  For example,
+say you want the right part of the header (by default, the document
+title) in red, this is how you&#8217;d get it:
+<br/>
+<span class="pre-in-pp">
+  .HEADER_RIGHT_COLOR red
+</span>
+The other parts of the header will be in the default header colour
+(usually black, but that can be changed with
+<a href="#hdrftr-color">HEADER_COLOR</a>).
+</p>
+
+<p>
+Remember that you have to define (or &#8220;initialize&#8221;) a
+colour with
+<a href="color.html#newcolor">NEWCOLOR</a>
+or
+<a href="color.html#xcolor">XCOLOR</a>
+before you can use the colour.
+</p>
+
+<p>
+If you create a
+<a href="#userdef-hdrftr-rv">user-defined header</a>
+with
+<a href="#hdrftr-rectoverso">HEADER_RECTO</a>
+or
+<a href="#hdrftr-rectoverso">HEADER_VERSO</a>,
+and you want various elements within the header to be colourized,
+embed the colours in the string passed to HEADER_RECTO or
+HEADER_VERSO with the
+<a href="color.html#color-inline"><kbd>\*[&lt;colorname&gt;]</kbd></a>
+<a href="definitions.html#inlines">inline escape</a>.
+</p>
+
+<p>
+Replace HEADER_, above, with FOOTER_ to set the colours for the
+various elements of footers.
+</p>
+
+<!-- -HDRFTR_VERTICAL- -->
+
+<h4 id="hdrftr-vertical" class="docs">3. Header/footer vertical placement and 
spacing</h4>
+
+<p>
+See
+<a href="#vertical-spacing">Vertical placement and spacing of 
headers/footers</a>
+for an explanation of how mom deals with
+headers, footers, and top/bottom page margins.
+</p>
+
+<div class="macro-list-container">
+<ul style="padding-top: 6px; padding-bottom: 6px; margin-left: -.5em;">
+  <li><a href="#hdftr_margin">HEADER_MARGIN</a></li>
+  <li><a href="#hdftr_gap">HEADER_GAP</a></li>
+</ul>
+</div>
+
+<!-- -HDRFTR_MARGIN- -->
+
+<div id="hdrftr-margin" class="box-macro-args">
+Macro: <b>HEADER_MARGIN</b> <kbd class="macro-args">&lt;distance to baseline 
of header&gt;</kbd>
+</div>
+
+<p class="requires">
+&bull;&nbsp;Requires a <a href="definitions.html#unitofmeasure">unit of 
measure</a>
+</p>
+
+<p>
+Use HEADER_MARGIN to set the distance from the top edge of the page to the
+<a href="definitions.html#baseline">baseline</a>
+of type in headers.  A unit of measure is required, and decimal
+fractions are allowed.
+</p>
+
+<p>
+Mom&#8217;s default header margin is 4-1/2
+<a href="definitions.html#picaspoints">picas</a>,
+but if you want a different margin, say, 1/2-inch, do
+<br/>
+<span class="pre-in-pp">
+  .HEADER_MARGIN .5i
+</span>
+If your document uses
+<a href="definitions.html#footer">footers</a>,
+replace HEADER_, above, with FOOTER_.  The argument to FOOTER_MARGIN
+is the distance from the bottom edge of the page to the baseline of
+type in footers.  Mom&#8217;s default footer margin is 3
+<a href="definitions.html#picaspoints">picas</a>.
+</p>
+
+<h3 class="docs">Header/footer margins and page numbering</h3>
+
+<p>
+Mom uses HEADER_MARGIN and FOOTER_MARGIN to establish the baseline
+position of page numbers in addition to the baseline position of
+headers and footers proper.
+</p>
+
+<p>
+By default, page numbers appear at the bottom of the page, therefore
+if you want the default position (bottom), but want to change the
+baseline placement, use FOOTER_MARGIN.  Conversely, if page numbers
+are at the top of the page, either because you turned
+<a href="#footers">FOOTERS</a>
+on or because you instructed mom to put them there with
+<a href="#pagenum-pos">PAGENUM_POS</a>,
+you&#8217;d use HEADER_MARGIN to change their baseline placement.
+</p>
+
+<div id="footer-margin" class="box-important" style="padding-bottom: 15px;">
+<p class="tip-top">
+<span class="important" style="display: block; margin-bottom: -1em;">Important 
&ndash; FOOTER_MARGIN and bottom margins</span>
+<br/>
+Mom requires a footer margin (i.e. the distance from the bottom of
+the page at which to place footers) for proper operation, hence she
+sets one, even if you don&#8217;t.  As stated above, her default
+footer margin is 3-picas.
+</p>
+
+<p>
+If you use
+<a href="typesetting.html#b-margin">B_MARGIN</a>
+or
+<a href="typesetting.html#page">PAGE</a>,
+to set a bottom margin for your document (prior to
+<a href="docprocessing.html#start">START</a>)
+and the margin&#8217;s too close to mom&#8217;s default
+footer margin (or a footer margin you set yourself with
+FOOTER_MARGIN), mom will not print your footers; additionally,
+she&#8217;ll give you a warning and some advice on standard error.
+When this happens, you must reset either B_MARGIN or FOOTER_MARGIN
+so there&#8217;s an adequate amount of space for mom to print the
+bottom line of running text and the footer.
+</p>
+
+<p>
+If you see the warning even when footers and/or bottom-of-page page
+numbering are disabled, set a nominal footer margin of 0 prior to
+<a href="docprocessing.html#start">START</a>,
+as in these 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">
+  &lt;reference macros, etc&gt;
+  .PAGINATION    OFF
+  .B_MARGIN      .25i
+  .FOOTER_MARGIN O
+  .START
+</span>
+</div>
+
+<div id="examples-footnotes-2" class="examples-container" style="margin-top: 
1em; padding-bottom: 1em;">
+<div class="examples" style="margin-top: 0;">Example 2</div>
+<span class="pre">
+  &lt;reference macros, etc&gt;
+  .HEADERS       OFF
+  .PAGENUM_POS   TOP RIGHT
+  .B_MARGIN      .25i
+  .FOOTER_MARGIN O
+  .START
+</span>
+</div>
+</div>
+
+<!-- -HDRFTR_GAP- -->
+
+<div id="hdrftr-gap" class="box-macro-args">
+Macro: <b>HEADER_GAP</b> <kbd class="macro-args">&lt;distance from header to 
start of running text&gt;</kbd>
+</div>
+
+<p class="requires">
+&bull;&nbsp;Requires a <a href="definitions.html#unitofmeasure">unit of 
measure</a>
+</p>
+
+<p>
+Use HEADER_GAP to set the distance from the
+<a href="definitions.html#baseline">baseline</a>
+of type in headers to the start of
+<a href="definitions.html#running">running text</a>.
+A unit of measure is required, and decimal fractions are allowed.
+</p>
+
+<p>
+As explained in
+<a href="#vertical-spacing">Vertical placement and spacing of 
headers/footers</a>,
+HEADER_MARGIN + HEADER_GAP determine the default vertical starting
+position of running text on the page unless you have given mom your
+own top margin (with
+<a href="typesetting.html#t-margin">T_MARGIN</a>).
+If you give a top margin, mom ignores HEADER_GAP; running text
+starts at your stated top margin.
+</p>
+
+<p>
+Mom&#8217;s default header gap is 3
+<a href="definitions.html#picaspoints">picas</a>,
+but if you want a different gap, say, 2 centimetres, do
+<br/>
+<span class="pre-in-pp">
+  .HEADER_GAP 2c
+</span>
+</p>
+
+<p>
+If your document uses
+<a href="definitions.html#footer">footers</a>,
+replace HEADER_, above, with FOOTER_.  The argument to FOOTER_GAP
+is the distance from the baseline of type in footers to the last
+baseline of running text on the page.
+</p>
+
+<p>
+As explained in
+<a href="#vertical-spacing">Vertical placement and spacing of 
headers/footers</a>,
+FOOTER_MARGIN + FOOTER_GAP determine the default vertical end
+position of running text on the page unless you have given mom a
+bottom margin (with
+<a href="typesetting.html#b-margin">B_MARGIN</a>).
+If you give a bottom margin, mom ignores FOOTER_GAP; running text
+ends at your stated bottom margin, subject to the restriction outlined
+<a href="#footer-margin">here</a>.
+</p>
+
+<p>
+Mom&#8217;s default footer gap is 3 
+<a href="definitions.html#picaspoints">picas</a>.
+</p>
+
+<div class="box-tip">
+<p class="tip">
+<span class="note">Note:</span>
+Mom uses HEADER_GAP and FOOTER_GAP to establish the start and end
+baseline positions of running text with respect to both headers and
+footers AND page numbers.  If you wish to change the gap between the
+last line of running text and a bottom page number, use FOOTER_GAP.
+If page numbers are at the top of the page, change the gap between
+the number and the first line of running text with HEADER_GAP.
+</p>
+</div>
+
+<!-- -HDRFTR_SEPARATOR- -->
+
+<h4 id="hdrftr-separator" class="docs">4. Header/footer separator rule</h4>
+
+<p>
+The header/footer separator rule is a modest horizontal rule,
+set slightly below the header (or above the footer), that runs
+the length of the
+<a href="definitions.html#header">header</a>
+and helps separate it visually from
+<a href="definitions.html#running">running text</a>.  If
+you don&#8217;t want the rule, you can turn it off.  If you want it,
+but at a different vertical position relative to the header (or
+footer), you can alter its placement.
+</p>
+
+<div class="macro-list-container">
+<ul style="padding-top: 6px; padding-bottom: 6px; margin-left: -.5em;">
+  <li><a href="#hdrftr-rule">HEADER_RULE</a> &ndash; on or off</li>
+  <li><a href="#hdrftr-rule-weight">HEADER_RULE_WEIGHT</a> &ndash; weight of 
the rule</li>
+  <li><a href="#hdrftr-rule-gap">HEADER_RULE_GAP</a> &ndash; distance of rule 
from header</li>
+  <li><a href="#hdrftr-rule-color">HEADER_RULE_COLOR</a> &ndash; color of rule 
header</li>
+</ul>
+</div>
+
+<!-- -HDRFTR_RULE- -->
+
+<div id="hdrftr-rule" class="box-macro-args">
+Macro: <b>HEADER_RULE</b> <kbd class="macro-args">toggle</kbd>
+</div>
+
+<p>
+By default, mom prints a header separator rule underneath headers
+(or above footers). If you don&#8217;t want the rule, turn it off by
+invoking <kbd>.HEADER_RULE</kbd> with any argument (<kbd>OFF, QUIT,
+END, X...</kbd>), e.g.
+<br/>
+<span class="pre-in-pp">
+  .HEADER_RULE OFF
+</span>
+To turn the rule (back) on, invoke <kbd>.HEADER_RULE</kbd>
+without any argument.
+</p>
+
+<div class="box-tip">
+<p class="tip">
+<span class="note">Note:</span>
+Replace HEADER_, above, with FOOTER_ to enable/disable the printing
+of the footer separator rule.  (Most likely, if you&#8217;re using
+<kbd><a href="#footers">FOOTERS</a></kbd>,
+you&#8217;ll want it off.)
+</p>
+</div>
+
+<!-- -HDRFTR_RULE_WEIGHT- -->
+
+<div id="hdrftr-rule-weight" class="box-macro-args">
+Macro: <b>HEADER_RULE_WEIGHT</b> <kbd class="macro-args">&lt;weight in 
points&gt;</kbd>
+</div>
+
+<p class="requires">
+&bull;&nbsp;Argument must <span class="normal">NOT</span> have a <a 
href="definitions.html#unitofmeasure">unit of measure</a> appended
+</p>
+
+<p>
+HEADER_RULE_WEIGHT controls the weight (&#8220;thickness&#8221;) of
+the header rule.  Like
+<a href="inlines.html#rule-weight">RULE_WEIGHT</a>,
+it takes a single argument: the weight of the header rule expressed
+in
+<a href="definitions.html#picaspoints">points</a>
+but without the unit of measure, <kbd>p</kbd>, appended.  The
+argument to HEADER_RULE_WEIGHT must be greater than 0 and less than
+100; decimal fractions are allowed.
+</p>
+
+<p>
+Say, for example, you want a really strong header separator rule.  
+<br/>
+<span class="pre-in-pp">
+  .HEADER_RULE_WEIGHT 4
+</span>
+which sets the separator rule weight to 4 points, is how you&#8217;d do
+it.
+</p>
+
+<p>
+Mom&#8217;s default header rule weight is 1/2 point.
+</p>
+
+<div class="box-tip">
+<p class="tip">
+<span class="note">Note:</span>
+Replace HEADER_, above, with FOOTER_ to set the weight of the footer
+separator rule.
+</p>
+</div>
+
+<!-- -HDRFTR_RULE_GAP- -->
+
+<div id="hdrftr-rule-gap" class="box-macro-args">
+Macro: <b>HEADER_RULE_GAP</b> <kbd class="macro-args">&lt;distance of rule 
beneath header&gt;</kbd>
+</div>
+
+<p class="requires">
+&bull;&nbsp;Requires a <a href="definitions.html#unitofmeasure">unit of 
measure</a>
+</p>
+
+<p>
+HEADER_RULE_GAP is the distance from the
+<a href="definitions.html#baseline">baseline</a>
+of type in headers to the top edge of the rule underneath.  (If
+FOOTER_RULE_GAP, the gap is the distance from the top of the highest
+<a href="definitions.html#ascender">ascender</a>
+to the bottom edge of the rule.)  A unit of measure is required, and
+decimal fractions are allowed.  Please note that HEADER_RULE_GAP has
+no effect on
+<a href="#hdrftr-gap">HEADER_GAP</a>
+(i.e. HEADER_RULE_GAP is NOT added to HEADER_GAP when mom calculates
+the space between headers and the start of
+<a href="definitions.html#running">running text</a>).
+</p>
+
+<p>
+By default, the header rule gap is 4
+<a href="definitions.html#picaspoints">points</a>.
+If you&#8217;d like to change it to, say, 1/4
+<a href="definitions.html#em">em</a>, do
+<br/>
+<span class="pre-in-pp">
+  .HEADER_RULE_GAP .25m
+</span>
+</p>
+
+<div class="box-tip">
+<p class="tip">
+<span class="note">Note:</span>
+Replace HEADER_, above, with FOOTER_ if you&#8217;re using
+<a href="definitions.html#footer">footers</a>
+and want to change the separator rule gap.  In footers, the gap is
+measured from the top of the tallest
+<a href="definitions.html#ascender">ascender</a>
+in the footer.
+</p>
+
+<p class="tip-bottom">
+<span class="additional-note">Additional note:</span>
+When using
+<a href="#hdrftr-recto">FOOTER_RECTO</a>
+and
+<a href="#hdrftr-verso">FOOTER_VERSO</a>,
+make sure that the default size for footers
+(<a href="#footer-global-size">FOOTER_SIZE</a>)
+is set to the largest size of type that will be used in the footer
+or mom may not get the rule gap right.  Inline changes to the size
+of type in FOOTER_RECTO and FOOTER_VERSO should always be negative
+(smaller) than the default.
+</p>
+</div>
+
+<!-- -HDRFTR_RULE_COLOR- -->
+
+<div id="hdrftr-rule-color" class="box-macro-args">
+Macro: <b>HEADER_RULE_COLOR</b> <kbd class="macro-args">&lt;colorname&gt;</kbd>
+</div>
+
+<p>
+If you wish to change the colour of the header rule, invoke
+<kbd>.HEADER_RULE_COLOR</kbd> with the name of a colour pre-defined
+(or &#8220;initialized&#8221;) with
+<a href="color.html#newcolor">NEWCOLOR</a>
+or
+<a href="color.html#xcolor">XCOLOR</a>.
+</p>
+
+<p>
+HEADER_RULE_COLOR overrides the colour set with
+<a href="#hdrftr-color">HDRFTR_COLOR</a>,
+so it&#8217;s possible to have the heads entirely in, say, blue (set
+with HEADER_COLOR), and the header rule in, say, red.
+</p>
+
+<div class="box-tip">
+<p class="tip">
+<span class="note">Note:</span>
+Replace HEADER_, above, with FOOTER_ to change the colour of the
+footer rule.
+</p>
+</div>
+
+<div class="rule-short"><hr/></div>
+
+<!-- -USERDEF_HDRFTR- -->
+
+<h2 id="userdef-hdrftr-rv" class="macro-group">User-defined, single string 
recto/verso headers/footers</h2>
+
+<p>
+Sometimes, you&#8217;ll find you can&#8217;t get mom&#8217;s
+handling of 3-part headers or footers to do exactly what you want in
+the order you want.  This is most likely happen when you want the
+information contained in the headers/footers split over two pages,
+as is often the case with recto/verso documents.
+</p>
+
+<p>
+Say, for example, you want recto page headers to contain a
+document&#8217;s author, centred, and verso page headers to contain
+the document&#8217;s title, also centred, like this:
+<br/>
+<span class="pre-in-pp">
+    +------------------------+   +------------------------+     
+    |         Author         |   |         Title          |     
+    |                        |   |                        |     
+    |                        |   |                        |     
+    |                        |   |                        |     
+    |                        |   |                        |     
+    |                        |   |                        |     
+    |                        |   |                        |     
+    |                        |   |                        |     
+    |                        |   |                        |     
+    |                        |   |                        |     
+    |                        |   |                        |     
+    |                        |   |                        |     
+    |                        |   |                        |     
+    |                        |   |                        |     
+    +------------------------+   +------------------------+     
+</span>
+With mom&#8217;s standard 3-part headers, this isn&#8217;t possible,
+even when
+<a href="rectoverso.html#recto-verso">RECTO_VERSO</a>
+is enabled.  RECTO_VERSO switches the left and right parts of
+headers on alternate pages, but the centre part remains unchanged.
+</p>
+
+<p>
+Any time you need distinctly different headers on alternate pages,
+mom has macros that let you manually design and determine what goes
+into headers on recto pages, and what goes into headers on verso
+pages.  The macros are
+<a href="#hdrftr-recto">HEADER_RECTO</a>
+and
+<a href="#hdrftr-verso">HEADER_VERSO</a>.
+Both allow you to state whether the header is flush left, centred,
+or flush right, and both take a single
+<a href="definitions.html#stringargument">string argument</a>
+with which, by combining text and
+<a href="definitions.html#inlines">inline escapes</a>,
+you can make the headers come out just about any way you want.
+Use of the <kbd>\*[PAGE#]</kbd> escape is permitted in the string
+argument (see
+<a href="#page-number-incl">Including the page number in header-left, -centre 
or -right</a>),
+and, as an added bonus, mom provides a special mechanism whereby
+it&#8217;s possible to
+<a href="#padding-hdrftr">pad</a>
+the string as well.  The padding mechanism lets you create headers
+that contain left, centre and right parts like mom's defaults but
+entirely of your own design.
+</p>
+
+<div class="macro-list-container">
+<ul style="padding-top: 6px; padding-bottom: 6px; margin-left: -.5em;">
+  <li><a href="#hdrftr-recto">HEADER_RECTO</a></li>
+  <li><a href="#hdrftr-verso">HEADER_VERSO</a>
+  <ul style="margin-left: -.5em;">
+    <li><a href="#userdef-hdrftr">User-defined single string headers/footers 
(no recto/verso)</a></li>
+    <li><a href="#padding-hdrftr">Padding the header-recto/header-verso 
string</a></li>
+  </ul></li>
+</ul>
+</div>
+
+<!-- -HDRFTR_RECTOVERSO- -->
+
+<div id="hdrftr-recto" class="box-macro-args">
+Macro: <b>HEADER_RECTO</b> <kbd class="macro-args">LEFT | CENTER | RIGHT [ 
CAPS ] "&lt;header recto string&gt;"</kbd>
+</div>
+
+<div id="hdrftr-verso" class="box-macro-args" style="margin-top: 1em;">
+Macro: <b>HEADER_VERSO</b> <kbd class="macro-args">LEFT | CENTER | RIGHT [ 
CAPS ] "&lt;header verso string&gt;"</kbd>
+</div>
+
+<div id="userdef-hdrftr" class="box-tip" style="margin-top: 1.5em; outline: 
2px dashed #000089; margin-left: 3px; margin-right: 3px;">
+<p class="tip">
+<span class="tip" style="display: block; margin-bottom: -1.25em; color: 
#000056; font-size: 105%;">User-defined single string headers/footers (no 
recto/verso)</span>
+<br/>
+HEADER_RECTO may be used to create user-defined, single string
+headers (or footers, with FOOTER_RECTO), even when recto/verso is
+not enabled (with
+<a href="rectoverso.html#recto-verso">RECTO_VERSO</a>).
+In such cases, the header/footer you create is the one used on
+every page, making HEADER_RECTO your &#8220;I need to design my own
+headers from scratch&#8221; solution.
+</p>
+</div>
+
+<p>
+HEADER_RECTO and HEADER_VERSO behave identically, hence all
+references to HEADER_RECTO in this section also refer to
+HEADER_VERSO.  Furthermore, FOOTER_ can be used instead of HEADER_
+to set up recto/verso footers.
+</p>
+
+<p>
+The first argument to HEADER_RECTO is the direction in which you
+want the header
+<a href="definitions.html#quad">quadded</a>.
+<kbd>L, C</kbd> and <kbd>R</kbd> may be used in place of <kbd>LEFT,
+CENTER</kbd> and <kbd>RIGHT</kbd>.
+</p>
+
+<p>
+The second argument (optional) tells mom to capitalize the text of
+the header. <b>Please note:</b> Do not use <kbd><a
+href="inlines.html#uc-lc">\*[UC]...\*[LC]</a></kbd> inside the
+string passed to HEADER_RECTO.
+</p>
+
+<p>
+The final argument is a string, surrounded by double-quotes,
+containing what you want in the header.  HEADER_RECTO disables
+mom&#8217;s normal 3-part headers, therefore anything you want in
+the headers must be entered by hand in the string, including colours
+(via the
+<a href="definitions.html#inlines">inline escape</a>
+<a href="color.html#color-inline"><kbd>\*[&lt;colorname&gt;]</kbd></a>).
+</p>
+
+<p>
+By default, HEADER_RECTO is set at the same size, and in the same
+family and font, as paragraph text.  The control macros
+<a href="#hdrftr-global-family">HEADER_FAMILY</a>
+and
+<a href="#hdrftr-global-size">HEADER_SIZE</a>
+may be used to change the default family and size.  Changes to the
+font(s) within the string must be accomplished with the
+<a href="definitions.html#inlines">inline escapes</a>
+<kbd>\*[ROM], \*[IT], \*[BD], \*[BDI]</kbd> and
+<kbd>\*[PREV]</kbd> (see
+<a href="inlines.html#inline-fonts-mom">Changing fonts</a>).
+Additional refinements to the style of the header-recto string,
+including horizontal spacing and/or positioning, can also be made
+with inline escapes.
+</p>
+
+<p>
+To include the current page number in the string, use the
+<kbd>\*[PAGE#]</kbd>
+<a href="definitions.html#inlines">inline escape</a>.
+</p>
+
+<h3 id="padding-hdrftr" class="docs">Padding the header-recto/header-verso 
string</h3>
+
+<p>
+You can &#8220;pad&#8221; the header-recto string, a convenience
+you&#8217;ll appreciate in circumstances such as the following.
+<br/>
+<span class="pre-in-pp">
+               VERSO                       RECTO 
+    +------------------------+   +------------------------+     
+    | Author          Page#  |   | Page#            Title |     
+    |                        |   |                        |     
+    |                        |   |                        |     
+    |                        |   |                        |     
+    |                        |   |                        |     
+    |                        |   |                        |     
+    |                        |   |                        |     
+    |                        |   |                        |     
+    |                        |   |                        |     
+    |                        |   |                        |     
+    |                        |   |                        |     
+    |                        |   |                        |     
+    |                        |   |                        |     
+    |                        |   |                        |     
+    +------------------------+   +------------------------+     
+</span>
+</p>
+
+<p>
+There are two steps to padding the string argument passed to HEADER_RECTO
+(if you&#8217;re unsure what padding is, see
+<a href="goodies.html#pad">Insert space into lines</a>).
+</p>
+<ol style="margin-top: -.5em; margin-left: -.5em; margin-bottom: -.5em;">
+  <li>Begin and end the string (inside the double-quotes) with the caret 
character (<kbd>^</kbd>).</li>
+  <li>Enter the pound sign (<kbd>#</kbd>) at any point in the string where you 
want an equalized amount of whitespace inserted.</li>
+</ol>
+
+<p>
+The situation depicted above is accomplished like this:
+<br/>
+<span class="pre-in-pp">
+  .HEADER_RECTO LEFT "^\*[PAGE#]#\E*[$TITLE]^"
+  .HEADER_VERSO LEFT "^\E*[$AUTHOR]#\*[PAGE#]^"
+</span>
+Notice that the quad argument, <kbd>LEFT</kbd>, is used in both
+cases.  When padding a header, it doesn&#8217;t matter which
+quad argument you use, although you must be sure to supply
+one.  Also note that mom does not interpret the <kbd>#</kbd> in
+<kbd>\*[PAGE#]</kbd> as a padding marker (i.e. as a place to insert
+whitespace).
+</p>
+
+<div class="box-important">
+<p class="tip">
+<span class="important">Important:</span>
+The
+<a href="goodies.html#pad-marker">PAD_MARKER</a>
+macro, which changes the default pad marker (<kbd>#</kbd>) used by
+<a href="goodies.html#pad">PAD</a>,
+has no effect on the pad marker used in the HEADER_RECTO string.  If
+you absolutely must have a literal pound sign in your HEADER_RECTO
+string, use the escape sequence for the pound sign
+(&nbsp;<kbd>\[sh]</kbd>&nbsp;) where you want the pound sign to go.
+</p>
+</div>
+
+<!-- -HDRFTR_RECTOVERSO- -->
+
+<h2 id="headers-and-footers-intro" class="macro-group">Headers and footers on 
the same page</h2>
+
+<p>
+Normally, mom prints either a header or a footer, but not both, depending on 
whether
+<a href="docprocessing.html#header">HEADERS</a>
+or
+<a href="docprocessing.html#footer">FOOTERS</a>
+is enabled.  (Page numbering, whether in the top margin
+or the bottom, is not considered a header or a footer.)
+Should you need both headers and footers on the same page, the
+single macro, HEADERS_AND_FOOTERS, is the way to set it up.
+</p>
+
+<div id="headers-and-footers" class="box-macro-args">
+Macro: <b>HEADERS_AND_FOOTERS</b> <kbd class="macro-args">(see 
Invocation)</kbd>
+</div>
+
+<p>
+Invocation:
+<br/>
+<span class="pre-in-pp" style="margin-bottom: -1em;">
+  .HEADERS_AND_FOOTERS \
+  &lt;L | C | R&gt; "&lt;header-recto string&gt;" \
+  &lt;L | C | R&gt; "&lt;footer-recto string&gt;" \
+  &lt;L | C | R&gt; "&lt;header-verso string&gt;" \
+  &lt;L | C | R&gt; "&lt;header-verso string&gt;"
+</span>
+or
+<span class="pre-in-pp" style="margin-top: -.5em;">
+  .HEADERS_AND_FOOTERS &lt;anything&gt;
+</span>
+</p>
+
+<p>
+Unlike the macros,
+<a href="#headers">HEADERS</a>
+and
+<a href="#footers">FOOTERS</a>,
+which are
+<a href="definitions.html#toggle">toggle</a>
+macros, HEADERS_AND_FOOTERS requires that you supply the information
+you want in the headers and footers yourself.  Mom does no automatic
+generation of things like the title and the author in headers and
+footers when you&#8217;re using HEADERS_AND_FOOTERS.  Furthermore,
+style changes&mdash;family, font, pointsize, colour, capitalization,
+etc &mdash;are entirely your responsibility and must be made with
+<a href="definitions.html#inlines">inline escapes</a>
+in the arguments passed to <kbd>&#8220;&lt;recto
+&#8221;header string&gt;&#8220;</kbd>, <kbd>&lt;recto footer
+string&gt;&#8220;</kbd>, etc.  By default, mom sets the headers and
+footers created with HEADERS_AND_FOOTERS in the same family, font,
+point size, capitalization style and colour as
+<a href="definitions.html#running">running text</a>.
+</p>
+
+<p>
+The manner of entering what you want is identical to the way you
+input
+<a href="#userdef-hdrftr-rv">single string headers and footers</a>.
+I suggest reading up on them, as well as looking at the entries,
+<kbd><a href="#hdrftr-rectoverso">HEADER_RECTO</a></kbd>
+and
+<a href="#reserved-strings">Using mom&#8217;s reserved strings in 
header/footer definitions</a>.
+</p>
+
+<p>
+The same
+<a href="#padding-hdrftr">padding mechanism</a>
+used in HEADER_RECTO and HEADER_VERSO is available in the
+<a href="definitions.html#stringargument">string arguments</a>
+passed to HEADERS_AND_FOOTERS, allowing you to simulate two- and
+three-part headers and footers.
+</p>
+
+<p>
+<kbd>L | C | R</kbd> in the arguments to HEADERS_AND_FOOTERS refers
+to whether you want the specific header or footer set flush left,
+centered, or flush right.  (You can also use the longer forms,
+<kbd>LEFT</kbd>, <kbd>CENTER</kbd> and <kbd>RIGHT</kbd>.)  The
+string you give afterwards is whatever text you want, including
+mom&#8217;s
+<a href="#reserved-strings">reserved strings</a>,
+and whatever
+<a href="definitions.html#inlines">inline escapes</a>
+you need to change things like family and font, pointsize, colour,
+etc. as you go along.
+</p>
+
+<p>
+Note the backslashes in the invocation, above.  Every set of
+arguments given this way to HEADERS_AND_FOOTERS <i>except the
+last</i> requires a backslash after it.  The use of backslashes
+isn&#8217;t required if you want to put the entire argument list on
+the same (very long!) line as the macro itself; I recommend sticking
+to the style shown above to keep things manageable.
+</p>
+
+<p>
+If you want to disable having both headers and footers on the same
+page, invoke <kbd>.HEADERS_AND_FOOTERS</kbd> with any argument
+you want (e.g. <kbd>OFF, QUIT, END, X...</kbd>). Mom will restore
+her default behaviour of setting automatically generated page
+headers, with the page number, centered, at the bottom of the
+page.  If you would prefer footers instead of headers after turning
+HEADERS_AND_FOOTERS off, invoke
+<a href="#footers"><kbd>.FOOTERS</kbd></a>
+afterwards.
+</p>
+
+<h4 class="docs" style="margin-bottom: 1em;">Examples of HEADERS_AND_FOOTERS 
usage</h4>
+
+<div id="examples-userdef-hdrftr-1" class="examples-container" 
style="padding-bottom: 0;">
+<div class="examples" style="margin-top: 12px; margin-bottom: 0;">Example 1: 
Header and footer the same on every page</div>
+<span class="pre">
+.HEADERS_AND_FOOTERS \          +-----------------------+
+C "\E*[$TITLE]" \               |         Title         |
+L "^\E*[$AUTHOR]#\*[PAGE#]^"    |                       |
+                                |                       |
+                                |                       |
+                                |                       |
+                                |                       |
+                                |                       |
+                                |                       |
+                                |                       |
+                                |                       |
+                                |                       |
+                                |                       |
+                                |                       |
+                                | Author          Pg. # |
+                                +-----------------------+
+</span>
+
+<p>
+<kbd>\E*[$TITLE]</kbd> and <kbd>\E*[$AUTHOR]</kbd> will print the
+strings you pass to
+<a href="docprocessing.html#title">TITLE</a>
+and
+<a href="docprocessing.html#author">AUTHOR</a>;
+<kbd>\*[PAGE#]</kbd> is how you include the page number in a header
+or footer string.  (For a list of special strings you can use in
+headers and footers, see
+<a href="#reserved-strings">here</a>.)
+</p>
+
+<p>
+You don&#8217;t have to use these special strings.  You can type
+in anything you like.  I&#8217;ve only used them here to show that
+they&#8217;re available.
+</p>
+</div>
+
+<div id="examples-userdef-hdrftr-2" class="examples-container" 
style="margin-top: 1em; padding-bottom: 18px;">
+<div class="examples" style="margin-top: 12px; margin-bottom: 0;">Example 2: 
Different headers and footers on recto/verso pages</div>
+<span class="pre">
+.HEADERS_AND_FOOTERS \
+C "BOOK TITLE" \
+L "^\*[PAGE#]#\E*[$AUTHOR]^" \
+C "Story Title" \
+L "^\E*[$AUTHOR]#\*[PAGE#]^"
+
+        +-----------------------+     +------------------------+
+        |      BOOK TITLE       |     |       Story Title      |
+        |                       |     |                        |
+        |                       |     |                        |
+        |                       |     |                        |
+        |                       |     |                        |
+        |                       |     |                        |
+        |                       |     |                        |
+        |                       |     |                        |
+        |                       |     |                        |
+        |                       |     |                        |
+        |                       |     |                        |
+        |                       |     |                        |
+        |                       |     |                        |
+        | Pg. #          Author |     | Author            Pg.# |
+        +-----------------------+     +------------------------+
+</span>
+</div>
+
+<div class="rule-short" style="margin-top: 1.25em;"><hr/></div>
+
+<!-- ==================================================================== -->
+
+<h2 id="pagination-intro" class="macro-group">Pagination</h2>
+
+<p>
+By default, mom paginates documents.  Page numbers
+appear in the bottom margin of the page, centred between two hyphens.
+As with all elements of mom&#8217;s document processing,
+most aspects of pagination style can be altered to suit your taste
+with control macros.
+</p>
+
+
+<div class="macro-list-container">
+<h3 id="index-pagination" class="macro-list">Pagination macros</h3>
+<ul class="macro-list">
+  <li><a href="#paginate">PAGINATE</a> &ndash; pagination on or off</li>
+  <li><a href="#pagenumber">PAGENUMBER</a> &ndash; user-defined (starting) 
page number</li>
+  <li><a href="#pagenum-style">PAGENUM_STYLE</a> &ndash; digits, roman 
numerals, etc</li>
+  <li><a href="#pagenum-on-first-page">PAGENUM_ON_FIRST_PAGE</a> &ndash; 
applies only when footers are enabled</li>
+  <li><a href="#draft-with-pagenumber">DRAFT_WITH_PAGENUMBER</a> &ndash; 
attach draft/revision information to page numbers</li>
+  <li><a href="#paginate-control">Pagination control macros and 
defaults</a></li>
+</ul>
+</div>
+
+<!-- -PAGINATE- -->
+
+<div id="paginate" class="box-macro-args">
+Macro: <b>PAGINATE</b> <kbd class="macro-args">toggle</kbd>
+</div>
+
+<p class="alias" style="margin-bottom: 0;">
+<i>Alias:</i> <b>PAGINATION</b>
+</p>
+
+<p>
+By default, mom paginates documents (in the bottom margin).  If
+you&#8217;d prefer she not paginate, turn pagination off by invoking
+<kbd>.PAGINATE</kbd> with any argument (<kbd>OFF, NO, QUIT, END,
+X...</kbd>), e.g.
+<br/>
+<span class="pre-in-pp">
+  .PAGINATE NO 
+</span>
+To (re)start pagination, invoke <kbd>.PAGINATE</kbd> without any
+argument.
+</p>
+
+<!-- -PAGENUMBER- -->
+
+<div id="pagenumber" class="box-macro-args">
+Macro: <b>PAGENUMBER</b> <kbd class="macro-args">&lt;number&gt;</kbd>
+</div>
+
+<p>
+As is to be expected, pagination of documents begins at page 1.  If
+you&#8217;d prefer that mom begin with a different number on the
+first page of a document, invoke <kbd>.PAGENUMBER</kbd> with the
+number you want.
+</p>
+
+<p>
+PAGENUMBER need not be used only to give mom a "first page" number.
+It can be used at any time to tell mom what number you want a page
+to have.  Subsequent page numbers will, of course, be incremented by
+1 from that number.
+</p>
+
+<!-- -PAGENUM_STYLE- -->
+
+<div id="pagenum-style" class="box-macro-args">
+Macro: <b>PAGENUM_STYLE</b> <kbd class="macro-args">DIGIT | ROMAN | roman | 
ALPHA | alpha</kbd>
+</div>
+
+<p>
+PAGENUM_STYLE lets you tell mom what kind of page numbering you
+want.
+<br/>
+<span class="pre-in-pp">
+  DIGIT   Arabic digits (1, 2, 3...)
+  ROMAN   upper case roman numerals (I, II, III...)
+  roman   lower case roman numerals (i, ii, iii...)
+  ALPHA   upper case letters (A, B, C...)
+  alpha   lower case letters (a, b, c...)
+</span>
+</p>
+
+<!-- -PAGENUM_ON_FIRST_PAGE- -->
+
+<div id="pagenum-on-first-page" class="box-macro-args">
+Macro: <b>PAGENUM_ON_FIRST_PAGE</b> <kbd class="macro-args">toggle</kbd>
+</div>
+
+<p>
+This macro applies only if you&#8217;ve enabled
+<a href="#footers">FOOTERS</a>.
+If FOOTERS are on, mom automatically places page numbers at the tops
+of pages except on the first page of a document (or on first pages
+after
+<a href="rectoverso.html#collate">COLLATE</a>).
+If you&#8217;d like the page number to appear on &#8220;first&#8221; pages
+when footers are on, invoke
+<br/>
+<span class="pre-in-pp">
+  .PAGENUM_ON_FIRST_PAGE
+</span>
+with no argument.  Any other argument turns the feature off
+(<kbd>OFF, QUIT, END, X</kbd>, etc).
+</p>
+
+<p>
+As with most of the
+<a href="definitions.html#controlmacro">control macros</a>,
+PAGENUM_ON_FIRST_PAGE can be invoked at any time, meaning that if
+you don&#8217;t want a page number on the very first page of a
+document, but do want one on pages that appear after COLLATE, omit
+it before the first
+<a href="docprocessing.html#start">START</a>
+of the document, then invoke it either just before or after your
+first COLLATE.
+</p>
+
+<!-- -DRAFT_WITH_PAGENUMBER- -->
+
+<div id="draft-with-pagenumber" class="box-macro-args">
+Macro: <b>DRAFT_WITH_PAGENUMBER</b>
+</div>
+
+<p>
+Sometimes, in
+<a href="docprocessing.html#copystyle">COPYSTYLE <kbd>DRAFT</kbd></a>,
+the CENTER part of page headers gets overcrowded because of
+the draft and revision information that go there by default.
+DRAFT_WITH_PAGENUMBER is one way to fix the problem.
+</p>
+
+<p>
+Invoked without an argument, <kbd>.DRAFT_WITH_PAGENUMBER</kbd>
+removes draft/revision information from the page headers and
+attaches it instead to the document&#8217;s page numbering, in the
+form
+<br/>
+<span class="pre-in-pp">
+  Draft #, Rev. # / &lt;pagenumber&gt;
+</span>
+If you have not supplied mom with a draft number (with
+<a href="docprocessing.html#draft">DRAFT</a>)
+DRAFT_WITH_PAGENUMBER will assume &#8220;Draft 1&#8220;, and will
+print it before the page number.
+</p>
+
+<p>
+See the note in
+<a href="docprocessing.html#copystyle-note">COPYSTYLE <kbd>DRAFT</kbd>
+</a>
+for other ways of dealing with crowded page headers when formatting
+draft-style copy.
+</p>
+
+<!-- -PAGINATE_CONTROL- -->
+
+<div class="macro-list-container">
+<h3 id="index-pagination-control" class="macro-list">Pagination control macros 
and defaults</h3>
+
+<ol style="margin-top: -1.5em; padding-bottom: 6px;">
+  <li><a href="#paginate-general">Family/font/size/colour</a></li>
+  <li><a href="#pagenum-pos">Page number position (vertical and 
horizontal)</a></li>
+  <li><a href="#pagenum-hyphens">Enclose page numbers with hyphens (on or 
off)</a></li>
+</ol>
+</div>
+
+<h4 id="paginate-general" class="docs">1. Page number 
family/font/size/colour</h4>
+
+<div class="defaults-container" style="margin-top: 1em; padding-bottom: 8px;">
+<p class="defaults" style="padding-top: 6px;">
+See
+<a href="docelement.html#control-macro-args">Arguments to the control 
macros</a>.
+</p>
+<span class="pre defaults">
+.PAGENUM_FAMILY default = prevailing document family; default is Times Roman
+.PAGENUM_FONT   default = roman
+.PAGENUM_SIZE   default = 0 (i.e. same size as paragraph text)
+.PAGENUM_COLOR  default = black
+</span>
+</div>
+
+<h4 id="pagenum-pos" class="docs" style="margin-top: -1em;">2. Page number 
position</h4>
+
+<div class="box-macro-args" style="margin-top: 1em;">
+Macro: <b>PAGENUM_POS</b> <kbd class="macro-args">TOP | BOTTOM&nbsp;&nbsp;LEFT 
| CENTER | RIGHT</kbd>
+</div>
+
+<p>
+Use PAGENUM_POS to change the default position of automatic page
+numbering. PAGENUM_POS requires <i>two</i> arguments: a vertical
+position (<kbd>TOP</kbd> or <kbd>BOTTOM</kbd>) and a horizontal
+position (<kbd>LEFT</kbd> or <kbd>CENTER</kbd> or <kbd>RIGHT</kbd>).
+</p>
+
+<p>
+For example, if you turn both
+<a href="definitions.html#header">headers</a>
+and
+<a href="definitions.html#footer">footers</a> 
+off (with <kbd>.HEADERS&nbsp;OFF</kbd> and
+<kbd>.FOOTERS&nbsp;OFF</kbd>) and you want mom to number your pages
+at the top right position, enter
+<br/>
+<span class="pre-in-pp">
+  .PAGENUM_POS TOP RIGHT
+</span>
+</p>
+
+<h4 id="pagenum-hyphens" class="docs" style="margin-top: -1em;">3. Enclose 
page numbers with hyphens (on or off)</h4>
+
+<div class="box-macro-args" style="margin-top: 1em;">
+Macro: <b>PAGENUM_HYPHENS</b> <kbd class="macro-args">toggle</kbd>
+</div>
+
+<p>
+By default, mom encloses page numbers between hyphens.  If you
+don&#8217;t want this behaviour, invoke the macro PAGENUM_HYPHENS
+with any argument (<kbd>OFF, QUIT, END, X</kbd>, etc), like this:
+<br/>
+<span class="pre-in-pp">
+  .PAGENUM_HYPHENS OFF
+</span>
+If, for some reason, you want to turn page number hyphens back
+on, invoke the macro without an argument.
+</p>
+
+<!-- -BLANK_PAGE- -->
+
+<h2 id="blank-pages" class="macro-group">Inserting blank pages into a 
document</h2>
+
+<div class="box-macro-args">
+Macro: <b>BLANKPAGE</b> <kbd class="macro-args">&lt;# of blank pages to 
insert&gt; &lt;NULL&gt;</kbd>
+</div>
+
+<p>
+This one does exactly what you&#8217;d expect&mdash;inserts a blank
+page into the document.  Unless you give the optional argument,
+<kbd>NULL</kbd>, mom silently increments the page number of every
+blank page and keeps track of
+<a href="rectoverso.html#recto-verso">recto/verso</a>
+stuff, but otherwise does nothing.  It&#8217;s up to you, the user,
+to figure out what to do with this feature.  However, it&#8217;s
+worth noting that without it, inserting completely blank pages,
+to use a vernacular Québécois phrase, <i>c'est pas
+évident</i>. (Somewhere between <i>it isn&#8217;t easy, it
+isn&#8217;t obvious</i> and <i>it isn&#8217;t fun</i>).
+</p>
+
+<p>
+The required argument to BLANK_PAGE is the number of blank pages to
+insert.  The argument is not optional, hence even if you only want
+one blank page, you have to tell mom:
+<br/>
+<span class="pre-in-pp">
+  .BLANKPAGE 1
+</span>
+The optional argument, <kbd>NULL</kbd>, allows you to output the
+specified number of pages without mom incrementing the page number
+for each blank page.  She will, however, continue to keep track
+of which pages are recto/verso if recto/verso printing has been
+enabled.
+</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: 24%; text-align: center;"><a href="#top">Top</a></td>
+  <td style="width: 42%; text-align: right;"><a href="rectoverso.html">Next: 
Recto/verso printing, collating</a></td>
+</tr>
+</table>
+
+</div>
+
+<div class="bottom-spacer"><br/></div>
+
+</body>
+</html>
+<!-- vim: fileencoding=utf-8: nomodified: -->

Index: images.html
===================================================================
RCS file: images.html
diff -N images.html
--- /dev/null   1 Jan 1970 00:00:00 -0000
+++ images.html 18 Aug 2010 22:45:35 -0000      1.1
@@ -0,0 +1,136 @@
+<?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 -- Inserting images into mom documents</title>
+  <link rel="stylesheet" type="text/css" href="stylesheet.css" />
+</head>
+
+<body style="background-color: #f5faff;">
+
+<!-- ==================================================================== -->
+
+<div id="top" class="page">
+
+<!-- Navigation links -->
+<table style="width: 100%;">
+<tr>
+  <td><a href="toc.html">Back to Table of Contents</a></td>
+  <td style="text-align: right;"><a href="headfootpage.html#top">Next: Page 
headers/footers, pagination</a></td>
+</tr>
+</table>
+
+<h1 class="docs">Inserting images into a document</h1>
+
+<p>
+You can insert images into a document by using the PSPIC
+macro. PSPIC isn&#8217;t actually part of mom; it comes packaged
+with groff itself.  Images must be in PostScript format, either
+straight .ps or .eps (Encapsulated PostScript).  If you have the
+ImageMagick suite of programmes installed on your system, a simple way
+to convert most image formats to .eps is with <kbd>convert</kbd>, at
+the command line, as in this jpg&nbsp;=>&nbsp;eps example:
+<br/>
+<span class="pre-in-pp">
+  convert &lt;filename&gt;.jpg &lt;filename&gt;.eps 
+</span>
+There have been reports of trouble with PostScript level 2 images,
+so don&#8217;t save your images in this format.
+</p>
+
+<!-- -PSPIC- -->
+
+<div class="macro-id-overline">
+<h3 id="pspic" class= "macro-id">PSPIC</h3>
+</div>
+
+<div class="box-macro-args">
+Macro: <b>PSPIC</b> <kbd class="macro-args">[ -L | -R | -I &lt;n&gt; ] 
&lt;file&gt; [ width [ height ] ]</kbd>
+</div>
+
+<p>
+<kbd>man groff-tmac</kbd> contains the documentation for PSPIC, but
+I&#8217;ll repeat it here with a few modifications for clarity.
+</p>
+
+<div class="examples-container">
+<h3 id="groff-tmac" class="docs" style="margin-top: .5em;">From groff-tmac</h3>
+<p style="margin-top: .5em; margin-bottom: .5em;">
+<kbd>&lt;file&gt;</kbd> is the name of the file containing the
+image; <kbd>width</kbd> and <kbd>height</kbd> give the desired
+width and height of the image as you wish it to appear within the
+document.  The width and height arguments may have
+<a href="definitions.html#unitofmeasure">units of measure</a>
+attached; the default unit of measure is
+<kbd>i</kbd>.  PSPIC will scale the graphic
+uniformly in the x and y directions so that it is no more than
+<kbd>width</kbd> wide and <kbd>height</kbd> high.  By default, the
+graphic will be horizontally centered.  The <kbd>-L</kbd> and
+<kbd>-R</kbd> options cause the graphic to be left-aligned and
+right-aligned, respectively.  The <kbd>-I</kbd> option causes
+the graphic to be indented by <kbd>&lt;n&gt;</kbd>;  the default unit of
+measure is <kbd>m</kbd>
+(<a href="definitions.html#em">ems</a>).
+</p>
+</div>
+
+<p>
+Unless you&#8217;re a PostScript whiz and have futzed around with
+bounding boxes and whatnot, it&#8217;s unlikely that your image will
+occupy an easily predictable and precise amount of space on the
+page.  This is particularly significant when it comes to the amount
+of vertical space occupied by the image.  A certain amount of
+manual tweaking of the vertical placement of the image will
+probably be required, via the
+<a href="typesetting.html#ald">ALD</a>
+and
+<a href="typesetting.html#rld">RLD</a>
+macros.
+</p>
+
+<p>
+Additionally, images inserted into
+<a href="definitions.html#running">running text</a>
+will almost certainly disrupt the baseline placement of running
+text.  In order to get mom back on track after
+invoking <kbd>.PSPIC</kbd>, I strongly recommend using the
+<a href="docprocessing.html#shim">SHIM</a>
+macro so that the bottom margin of running text falls where it
+should.
+</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: 20%; text-align: center;"><a href="#top">Top</a></td>
+  <td style="width: 46%; text-align: right;"><a href="headfootpage.html">Next: 
Page headers/footers, pagination</a></td>
+</tr>
+</table>
+
+</div>
+
+<div class="bottom-spacer"><br/></div>
+
+</body>
+</html>
+<!-- vim: fileencoding=utf-8: nomodified: -->

Index: inlines.html
===================================================================
RCS file: inlines.html
diff -N inlines.html
--- /dev/null   1 Jan 1970 00:00:00 -0000
+++ inlines.html        18 Aug 2010 22:45:35 -0000      1.25
@@ -0,0 +1,1076 @@
+<?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 -- Inline escapes</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="color.html#top">Next: Coloured 
text</a></td>
+</tr>
+</table>
+
+<h1 id="inline-escapes" class="docs">Inline escapes</h1>
+
+<div style="text-align: center;">
+<a href="#index-inlines">List of inline escapes</a>
+</div>
+
+<div class="rule-medium"><hr/></div>
+
+<h2 id="intro-inlines" class="docs">Introduction</h2>
+<p>
+Inline escapes, as described in the
+<a href="definitions.html#inlines">groff terms</a>
+section of this manual, are typesetting commands that appear in text
+<a href="definitions.html#inputline">input lines</a>,
+as opposed to macros and other
+<a href="definitions.html#controllines">control lines</a>
+that must appear on lines by themselves.
+</p>
+
+<p>
+Aside from altering type parameters within a line, inlines also tell
+groff about special characters&mdash;em-dashes, bullets,
+<a href="definitions.html#figurespace">figure/digit-width spaces</a>,
+and so on.  It is beyond the scope of this manual to provide
+a complete list of groff&#8217;s inline functions and special
+characters.  I recommend having a look at the
+<a href="intro.html#canonical">canonical reference materials</a>
+should you need more information than is contained herein.
+</p>
+
+<p>
+In groff, the escape character is the backslash (<kbd>\</kbd>).
+Groff interprets everything following the backslash as instructions,
+not literal text, until the escape sequence is complete.  Should
+you need the actual backslash character as part of a line of text,
+simply enter it twice (<kbd>\\</kbd>).  Groff understands that this
+means "please print a backslash character."
+</p>
+
+<p>
+You can also use <kbd>\e</kbd> to print a literal backslash, or use
+<a href="goodies.html#esc-char">ESC_CHAR</a> to change the escape
+character to something other than the backslash, which lets you
+use a single backslash as a literal backslash.
+</p>
+
+<p>
+Groff has a number of ways of recognizing what constitutes a
+complete escape sequence.  This is both a boon and a curse; some
+escape sequences have no terminating delimiter and consequently
+become difficult to distinguish from real input text.  Others
+require the use of an opening parenthesis with no corresponding
+closing parenthesis.  Still others need to be enclosed in square
+brackets.
+</p>
+
+<p>
+Mom recognizes that certain escapes get used more often than others.
+For these, she has a consistent input style that takes the form
+<kbd>\*[...]</kbd>, which makes them stand out well from the text of
+your documents.  These escapes are the ones listed under
+<a href="#inlines-mom">Mom&#8217;s personal inline escapes</a>.
+</p>
+
+<p>
+Despite mom&#8217;s best intentions, there are still
+a number of typesetting functions that can only be accomplished
+with groff&#8217;s native inline escapes.  I've listed the ones that
+strike me as essential, but there are many others.  If you want
+to know what they are, please read the
+<a href="intro.html#canonical">canonical reference materials</a>
+pertaining to groff.
+</p>
+
+<div class="box-tip">
+<p class="tip">
+<span class="tip">Helpful bit of information:</span>
+Inline escapes can be used in
+<a href="docprocessing.html#docprocessing">document processing macros</a>
+that take
+<a href="definitions.html#stringargument">string arguments</a>.
+</p>
+</div>
+
+<div class="macro-list-container">
+<h3 id="index-inlines" class="macro-list">List of inline escapes</h3>
+
+<ul class="macro-list">
+<li id="inlines-mom"><a href="#inlines-mom-top">Mom&#8217;s personal inline 
escapes</a>
+<ul class="no-enumerator" style="margin-left: -1.5em;">
+  <li><a href="#inline-fonts-mom">Changing fonts</a></li>
+  <li><a href="#inline-size-mom">Changing point size</a></li>
+  <li><a href="#uc-lc">Capitalise a section of type</a></li>
+  <li><a href="#inline-kerning-mom">Pairwise kerning</a></li>
+  <li><a href="#inline-horizontal-mom">Horizontal movement</a></li>
+  <li><a href="#inline-vertical-mom">Vertical movement</a></li>
+  <li><a href="#inline-b-mom">Terminate a line without advancing on the 
page</a></li>
+  <li><a href="#tb-plus-mom">Call the next sequential tab without advancing on 
the page</a></li>
+  <li><a href="#inline-rule-mom">Full measure rules</a>
+  <ul class="sublist" style="font-size: 100%;">
+    <li><a href="#rule-weight">Macro to control the weight of rules</a></li>
+  </ul></li>
+</ul></li>
+<li id="inlines-groff"><a href="#inlines-groff-top">Commonly-used groff inline 
escapes</a>
+<ul class="no-enumerator" style="margin-left: -1.5em;">
+  <li><kbd>\f</kbd>&nbsp;<a href="#inline-fonts-groff">Font control</a></li>
+  <li><kbd>\h</kbd>&nbsp;<a href="#inline-horizontal-groff">Inline horizontal 
motions</a></li>
+  <li><kbd>\v</kbd>&nbsp;<a href="#inline-vertical-groff">Inline vertical 
motions</a></li>
+  <li><kbd>\w</kbd>&nbsp;<a href="#inline-stringwidth-groff">String width 
function</a></li>
+  <li><kbd>\l</kbd>&nbsp;<a href="#inline-linedrawing-groff">Horizontal line 
drawing function</a></li>
+  <li style="margin-left: 1.6em;"><a href="#inline-characters-groff">Special 
characters</a></li>
+</ul></li>
+</ul>
+</div>
+
+<div class="rule-medium"><hr/></div>
+
+<!-- -INLINE_FONTS_MOM- -->
+
+<h2 id="inlines-mom-top" class="macro-group">Mom&#8217;s personal inline 
escapes</h2>
+
+<h3 id="inline-fonts-mom" class="docs">Changing fonts</h3>
+
+<p>
+Mom provides five escapes for changing fonts inline:
+<br/>
+<span class="pre-in-pp">
+  \*[ROM]   Change to the medium roman font
+  \*[IT]    Change to the medium italic font
+  \*[BD]    Change to the bold roman font
+  \*[BDI]   Change to the bold italic font
+  \*[PREV]  Revert to the previous font (once only)*
+</span>
+</p>
+
+<div class="box-tip">
+<p class="tip">
+<span class="note">Note:</span>
+<kbd>\*[PREV]</kbd> does not operate "stack style".  It returns
+to the previous font once only, and afterwards has no effect.  In
+other words, in the case of <kbd>\*[PREV]\*[PREV]</kbd>, only the
+first <kbd>\*[PREV]</kbd> is respected; the second one is silently
+ignored.
+</p>
+</div>
+
+<p>
+These escapes are provided for merely for convenience, legibility,
+and consistency when typesetting with mom.  For more complete and
+flexible inline font control, please see
+<a href="#inline-fonts-groff">font control with <kbd>\f</kbd></a>.
+</p>
+
+<div class="box-notes">
+<h3 id="inlines-docprocessing-fonts" class="docs notes">Notes concerning 
document processing</h3>
+<p style="margin-top: .5em;">
+If you&#8217;re using the
+<a href="docprocessing.html#docprocessing">document processing macros</a>,
+inline font changes remain in effect only for the duration of the
+current document element tag.
+</p>
+
+<p class="tip-bottom">
+Additionally, if you&#8217;re designing your own
+<a href="headfootpage.html#headfootpage-intro">HEADERS or FOOTERS</a>
+and want to use mom&#8217;s inline escapes for changing fonts as
+part of the the left, centre and/or right strings, or in the strings
+for
+<a href="headfootpage.html#hdrftr-rectoverso">recto</a>
+and/or
+<a href="headfootpage.html#hdrftr-rectoverso">verso</a>
+HEADERS or FOOTERS, or in the strings passed to
+<a href="headfootpage.html#headers-and-footers">HEADERS_AND_FOOTERS</a>,
+you must enter the inlines beginning with <kbd>\E*</kbd>
+rather than just <kbd>\*</kbd>, e.g. <kbd>\E*[BD]</kbd>.
+</p>
+</div>
+
+<!-- -INLINE_SIZE_MOM- -->
+
+<h3 id="inline-size-mom" class="docs">Changing point size</h3>
+<p>
+Mom has two inline escapes for changing point size:
+<br/>
+<span class="pre-in-pp">
+  \*[SIZE &lt;size&gt;]
+</span>
+and
+<br/>
+<span class="pre-in-pp">
+  \*S[&lt;size&gt;]
+</span>
+where &#8220;size&#8221; is the new size you want.  You can use
+either; they behave exactly the same way.  For example, to change
+the point size of type inline to 12 points, you could enter either
+<br/>
+<span class="pre-in-pp">
+  \*[SIZE 12]
+</span>
+or
+<br/>
+<span class="pre-in-pp">
+  \*S[12]
+</span>
+</p>
+
+<p>
+The advantage of the first form is that it&#8217;s easy to remember,
+and follows mom&#8217;s usual inline syntax.  The advantage of the
+second is that it&#8217;s more concise.
+</p>
+
+<p>
+Notice that in both cases, the new size does not require a
+<a href="definitions.html#unitofmeasure">unit of measure</a>;
+<a href="definitions.html#picaspoints">points</a>
+is assumed.  However, a unit of measure may be appended to the size
+if that&#8217;s what you wish.  Fractional sizes are, of course,
+allowed.
+</p>
+
+<p>
+The size given to <kbd>\*[SIZE&nbsp;&lt;size&gt;]</kbd> or
+<kbd>\*S[&lt;size&gt;]</kbd> may be expressed in plus or minus
+terms, which can be very useful.  In the following examples, the
+word &#8220;mom&#8221; will be output 2 points larger than the point
+size of the rest of the line.
+<br/>
+<span class="pre-in-pp">
+  While she isn't perfect, \*S[+2]mom\*S[-2] isn't half bad.
+  While she isn't perfect, \*[SIZE +2]mom\*[SIZE -2] isn't half bad.
+</span>
+</p>
+
+<div class="box-notes">
+<h3 id="inline-docprocessing-ps" class="docs notes">NOTE CONCERNING DOCUMENT 
PROCESSING</h3>
+<p style="margin-top: .5em;">
+If you&#8217;re using the
+<a href="docprocessing.html#docprocessing">document processing macros</a>
+and wish to design your own
+<a href="headfootpage.html#headfootpage-intro">HEADERS or FOOTERS</a>
+using mom&#8217;s inline escape for changing point size as part of
+the left, centre and/or right strings, or in the strings for
+<a href="headfootpage.html#hdrftr-rectoverso">recto</a>
+and/or
+<a href="headfootpage.html#hdrftr-rectoverso">verso</a>
+HEADERS or FOOTERS, or in the strings passed to
+<a href="headfootpage.html#headers-and-footers">HEADERS_AND_FOOTERS</a>,
+you <i>must</i> use the form <kbd>\*S[&lt;n&gt;]</kbd>
+and enter the inline beginning with <kbd>\E*</kbd>, like this:
+<kbd>\E*S[&lt;+|-&gt;&lt;n&gt;]</kbd>.
+</p>
+
+<p class="tip-bottom">
+<span class="additional-note">Additional note:</span>
+If you&#8217;re accustomed to groff&#8217;s usual way of handling
+inline size requests <kbd>(\sN, \s±N, \s(NN, \s±(NN, \s[NNN],
+\s±[NNN]),</kbd> feel free to continue with your old habits.  Mom
+doesn&#8217;t care.
+</p>
+</div>
+
+<!-- -CAPITALISATION- -->
+
+<h3 id="uc-lc" class="docs">Capitalise a section of type</h3>
+<p>
+If you need to capitalise a region of type inline, bracket the
+region of type with the inline escapes, <kbd>\*[UC]</kbd> (Upper Case)
+and <kbd>\*[LC]</kbd> (Lower Case), like this:
+<br/>
+<span class="pre-in-pp">
+  All work \*[UC]and\*[LC] no play makes Jack a dull boy.
+</span>
+The above produces, on output
+<br/>
+<span class="pre-in-pp">
+  All work AND no play makes Jack a dull boy.
+</span>
+</p>
+
+<div class="box-tip">
+<p class="tip">
+<span class="note">Note:</span>
+<kbd>\*[UC]</kbd> and <kbd>\*[LC]</kbd> must not be used inside the
+<a href="definitions.html#stringargument">string arguments</a>
+passed to the
+<a href="headfootpage.html#hdrftr-strings">HEADER_&lt;POSITION&gt;</a>
+macro.  Instead, use the control macro
+<a href="headfootpage.html#_caps">HEADER_&lt;POSITION&gt;_CAPS.</a>
+For
+<a href="headfootpage.html#hdrftr-rectoverso">HEADER_RECTO</a>
+(or _VERSO) or
+<a href="headfootpage.html#hdrftr-rectoverso">FOOTER_RECTO</a>
+(or _VERSO), supply the <kbd>CAPS</kbd> option to the appropriate
+macro.
+</p>
+</div>
+
+<!-- -INLINE_KERNING_MOM- -->
+
+<h3 id="inline-kerning-mom" class="docs">Pairwise kerning</h3>
+<p>
+Pairwise kerning means moving specific letter pairs closer
+together or further apart (see
+<a href="definitions.html#kern">Typesetting terms, kerning</a>
+for more details).
+</p>
+
+<p>
+Mom permits inline pairwise kerning through the use of the inline
+escapes
+<br/>
+<span class="pre-in-pp">
+  \*[BU &lt;n&gt;]&nbsp;Closes the space between letters (Back Units).
+  \*[FU &lt;n&gt;]&nbsp;Opens the space between letters (Forward Units).
+</span>
+&#8220;<b>&lt;n&gt;</b>&#8221; is the number of
+<a href="definitions.html#kernunit">kern units</a>
+by which to close or open the space between letters.
+</p>
+
+<p>
+For example,
+<br/>
+<span class="pre-in-pp">
+  THE HUMAN COST OF COMMODIF\*[FU 1]YING FRESH W\*[BU 4]A\*[BU 5]TER
+</span>
+moves the letter Y in &#8220;COMMODIFYING&#8221; one kern unit away from
+the letter F, and the letter A in &#8220;WATER&#8221; four kern units
+closer to the letter W.  Additionally, the letter T in "WATER" is
+moved five kern units closer to the letter A.
+</p>
+
+<p>
+For backward compatibility, the forms
+<br/>
+<span class="pre-in-pp">
+  \*[BU1]...\*[BU36]&nbsp;Move backward 1...36 <a 
href="definitions.html#kernunit">kern units</a>
+  \*[FU1]...\*[FU36]&nbsp;Move forward  1...36 <a 
href="definitions.html#kernunit">kern units</a>
+</span>
+also exist (i.e. with no space before the number of kern units desired,
+up to a limit of 36).
+</p>
+
+<div class="box-notes">
+<h3 id="inlines-docprocessing-kerning" class="docs notes">Notes concerning 
document processing</h3>
+<p style="margin-top: .5em;">
+If you&#8217;re using the
+<a href="docprocessing.html#docprocessing">document processing macros</a>
+and wish to design your own
+<a href="headfootpage.html#headfootpage-intro">HEADERS or FOOTERS</a>
+using mom&#8217;s inline escapes for kerning as part of the left,
+centre and/or right strings, or in the strings for
+<a href="headfootpage.html#hdrftr-rectoverso">recto</a>
+and/or
+<a href="headfootpage.html#hdrftr-rectoverso">verso</a>
+HEADERS or FOOTERS, or in the strings passed to
+<a href="headfootpage.html#headers-and-footers">HEADERS_AND_FOOTERS</a>,
+you <i>must</i> use the forms <kbd>\E*[BU&lt;n&gt;]</kbd>
+and <kbd>\E*[FU&lt;n&gt;]</kbd> (i.e. with no space), and enter the
+inline beginning with <kbd>\E*</kbd> rather than just <kbd>\*</kbd>,
+e.g. <kbd>\E*[BU4]</kbd>.
+</p>
+ 
+<p class="tip-bottom">
+<span class="additional-note">Additional note:</span>
+Using the <kbd>BU</kbd> or <kbd>FU</kbd> escapes between characters
+pairs that are already automatically kerned (see
+<a href="typesetting.html#kern">KERN</a>)
+disables the automatic
+kerning and uses the value you give to BU or FU instead.
+</p>
+</div>
+
+<!-- -INLINE_HORIZONTAL_MOM- -->
+
+<h3 id="inline-horizontal-mom" class="docs">Horizontal inline movement</h3>
+<p>
+Sometimes, you may need to insert a specified amount amount of white
+space into an
+<a href="definitions.html#outputline">output line</a>,
+or&mdash;occasionally&mdash;back up to a previous position on an
+<a href="definitions.html#inputline">output</a>
+line in order to create special typographic effects.
+</p>
+
+<p>
+Mom&#8217;s inline escapes for these horizontal movements are
+<br/>
+<span id="bck" class="pre-in-pp">
+  \*[BCK &lt;n unit&gt;]&nbsp;&nbsp;Move backward inline the specified number 
of
+                    <a href="definitions.html#unitofmeasure">units of 
measure</a>; decimal fractions are allowed.
+</span>
+and
+<span id="fwd" class="pre-in-pp">
+  \*[FWD &lt;n unit&gt;]&nbsp;&nbsp;Move forward inline the specified number of
+                    <a href="definitions.html#unitofmeasure">units of 
measure</a>; decimal fractions are allowed.
+</span>
+</p>
+
+<p>
+For example,
+<br/>
+<span class="pre-in-pp">
+    1.\*[FWD 12p]The Free Trade Play-Offs: WalMart 100, Mexico 0
+</span>
+puts 12 points of space between <kbd>1.</kbd> and
+<kbd>The</kbd>.
+</p>
+
+<div class="box-tip">
+<p class="tip">
+<span class="note">Note:</span>
+For backward compatibility, the forms
+<br/>
+<span class="pre-in-pp">
+  \*[BP.25]...\*[BP12.75]&nbsp;Move backward .25...12.75 points
+  \*[FP.25]...\*[FP12.75]&nbsp;Move forward  .25...12.75 points
+</span>
+also exist (i.e. with no space before the digit and points being
+the unit of measure, hence no unit of measure required).  Both
+accept quarter points, so it&#8217;s possible to do, for example,
+<kbd>\*[FP.5]</kbd> or <kbd>\*[BP1.25]</kbd> up to a limit
+of 12.75 points.
+</p>
+</div>
+
+<div class="box-notes">
+<h3 id="inlines-docprocessing-horizontal" class="docs notes">Note concerning 
document processing</h3>
+<p style="margin-top: .5em; padding-bottom: .5em;">
+If you&#8217;re using the
+<a href="docprocessing.html#docprocessing">document processing macros</a>
+and wish to design your own
+<a href="headfootpage.html#headfootpage-intro">HEADERS or FOOTERS</a>
+using mom&#8217;s inline escapes for horizontal movements as part of
+the left, centre and/or right strings, or in the strings for
+<a href="headfootpage.html#hdrftr-rectoverso">recto</a>
+and/or
+<a href="headfootpage.html#hdrftr-rectoverso">verso</a>
+HEADERS or FOOTERS, or in the strings passed to
+<a href="headfootpage.html#headers-and-footers">HEADERS_AND_FOOTERS</a>,
+you <i>must</i> use the forms <kbd>\E*[BP&lt;n&gt;]</kbd>
+and <kbd>\E*[FP&lt;n&gt;]</kbd> (i.e. with no space), and enter the
+inline beginning with <kbd>\E*</kbd> rather than just <kbd>\*</kbd>,
+e.g. <kbd>\E*[BP.755]</kbd>.
+</p>
+</div>
+
+<!-- -INLINE_VERTICAL_MOM- -->
+
+<h3 id="inline-vertical-mom" class="docs">Vertical inline movement</h3>
+<p>
+If you need to move portions of type up or down on a line, mom
+provides the following inline escapes:
+<br/>
+<span id="down" class="pre-in-pp">
+  \*[DOWN &lt;n unit&gt;]&nbsp;Move down inline the specified number of
+                    <a href="definitions.html#unitofmeasure">units of 
measure</a>
+
+  <span id="up">\*[UP &lt;n unit&gt;]&nbsp;Move up inline the specified number 
of
+                  <a href="definitions.html#unitofmeasure">units of 
measure</a></span>
+</span>
+For example,
+<br/>
+<span class="pre-in-pp">
+  Tel: 905\*[UP 1p]-\*[DOWN 1p]4072
+</span>
+moves the hyphen in the telephone number up by 1 point, then
+moves back down by the same amount.
+</p>
+
+<div class="box-tip">
+<p class="tip">
+<span class="note">Note:</span>
+<kbd>\*[UP]</kbd> and <kbd>\*[DOWN]</kbd> do not work in conjunction
+with the inline escape,
+<kbd><a href="#inline-rule-mom">\*[RULE]</a></kbd>.
+</p>
+
+<p>
+<span class="additional-note">Additional note:</span>
+For backward compatibility, the following are also available:
+<br/>
+<span class="pre-in-pp">
+  \*[ALD.25]...\*[ALD12.75]   Advance lead .25...12.75 points (move downward)
+  \*[RLD.25]...\*[RLD12.75]   Reverse lead .25...12.75 points (move upward)
+</span>
+</p>
+
+<p class="tip-bottom">
+Both <kbd>\*[ALD]</kbd> and <kbd>\*[RLD]</kbd> work in points, hence
+you mustn&#8217;t use a unit of measure.
+</p>
+</div>
+
+<div class="box-notes">
+<h3 id="inline-docprocessing-vertical" class="docs notes">Note concerning 
document processing</h3>
+<p style="margin-top: .5em; padding-bottom: .5em;">
+If you&#8217;re using the
+<a href="docprocessing.html#docprocessing">document processing macros</a>
+and wish to design your own
+<a href="headfootpage.html#headfootpage-intro">HEADERS or FOOTERS</a>
+using mom&#8217;s inline escapes for vertical movements as part of
+the left, centre and/or right strings, or in the strings for
+<a href="headfootpage.html#hdrftr-rectoverso">recto</a>
+and/or
+<a href="headfootpage.html#hdrftr-rectoverso">verso</a>
+HEADERS or FOOTERS, or in the strings passed to
+<a href="headfootpage.html#headers-and-footers">HEADERS_AND_FOOTERS</a>,
+you <i>must</i> use the forms <kbd>\E*[ALD&lt;n&gt;]</kbd>
+and <kbd>\E*[RLD&lt;n&gt;]</kbd> (i.e. with no space), and enter the
+inline beginning with <kbd>\E*</kbd> rather than just <kbd>\*</kbd>,
+e.g. <kbd>\E*[ALD.5]</kbd>.
+</p>
+</div>
+
+<!-- -INLINE_B_MOM- -->
+
+<h3 id="inline-b-mom" class="docs">Terminate a line without advancing on the 
page</h3>
+<p>
+Sometimes, you want mom to break a line but not advance on the page.
+See
+<a href="typesetting.html#el-example">here</a>
+for an example of when you might want to do this.
+</p>
+
+<p>
+In versions of mom prior to 1.2-f, this was accomplished through the
+use of the
+<a href="typesetting.html#el">EL</a>
+macro.  As of 1.2-f, you can, if you prefer, accomplish the same
+thing by using the inline escape, <kbd>\*[B]</kbd>.  Simply attach
+the escape to the end of any input line.  Using the example given in
+the document entry for EL, you'd use <kbd>\*[B]</kbd> like this:
+<br/>
+<span class="pre-in-pp">
+  .LEFT
+  .LS 12.5
+  A line of text.\*[B]
+  .ALD 24p
+  The next line of text.
+</span>
+
+<kbd>\*[B]</kbd> works reliably regardless of the current
+<a href="definitions.html#filled">fill mode</a>.
+</p>
+
+<!-- -INLINE_TB+_MOM- -->
+
+<h3 id="tb-plus-mom" class="docs">Call the next sequential tab without 
advancing on the page</h3>
+<p>
+Sometimes, you want mom to move to the next tab in sequence (e.g.
+from TAB 1 to TAB 2, or TAB 8 to TAB 9) without mom advancing on the
+page.  (See the NOTE
+<a href="typesetting.html#note-tn">here</a>
+if you&#8217;re not clear how mom manages tabs and linebreaks.)
+</p>
+
+<p>
+In versions of mom prior to 1.2-f, this was accomplished through the
+use of
+<a href="typesetting.html#tn">TN</a>.
+As of 1.2-f, you can, if you prefer, accomplish the same thing by
+using the inline escape, <kbd>\*[TB+]</kbd>.  Simply attach the
+escape to the end of any input line in a tab, like this:
+<br/>
+<span class="pre-in-pp">
+  .TAB 1
+  Some text\*[TB+]  \" This line is in tab 1
+  Some more text    \" This line is in tab 2, on the same baseline as tab 1
+</span>
+
+<kbd>\*[TB+]</kbd> works reliably regardless of the current
+<a href="definitions.html#filled">fill mode</a>.
+</p>
+
+<!-- -INLINE_RULE_MOM- -->
+
+<h3 id="inline-rule-mom" class="docs">Full measure rules</h3>
+<p>
+I find I often need rules drawn to the full measure of the current line
+or tab length.  The official way to do this is <kbd>\l'\n[.lu]'</kbd>,
+which is annoying to type, and doesn&#8217;t mean a whole heck of a lot if
+you&#8217;re new to groff.  The inline, <kbd>\*[RULE]</kbd>, is a simple
+replacement for <kbd>\l'\n[.lu]'</kbd>.  Use it whenever you need
+a rule drawn to the full measure of the current line or tab length, for
+example:
+<br/>
+<span class="pre-in-pp">
+  .LL 6P
+  \*[RULE]
+</span>
+
+The above draws a rule the full measure of the 6-pica line length.
+For another way to draw full measure rules, see the macro,
+<a href="graphical.html#drh">DRH</a>.
+</p>
+
+<p>
+<kbd>\*[RULE]</kbd> must appear on an
+<a href="definitions.html#inputline">input line</a>
+by itself, and always causes a break when entered after a normal
+input line of text.  It does not, however, deposit a break when used
+immediately after a macro.
+</p>
+
+<p>
+The weight of the rule drawn with <kbd>\*[RULE]</kbd> is controlled
+with the macro
+<a href="#rule-weight">RULE_WEIGHT</a>.
+Mom&#8217;s default is 1/2 point.
+</p>
+
+<div class="box-tip">
+<p class="tip">
+<span class="note">Note:</span>
+<kbd>\*[RULE]</kbd> draws the rule to the full measure, hence it
+cannot be used to fill the remainder of a partial line with a rule
+in this way:
+<br/>
+<span class="pre-in-pp">
+  Signature__________________________________________
+</span>
+If you wish to accomplish this effect, you have to use
+<kbd>\*[RULE]</kbd> in conjunction with the
+<a href="goodies.html#pad">PAD</a>
+macro and
+<a href="typesetting.html#string-tabs">string tabs</a>.
+(See the
+<a href="goodies.html#pad-example">example</a>
+provided with PAD.)
+<a name="RULE_EXCEPTION"></a>
+</p>
+
+<p>
+Please also note that the inline escapes
+<a href="#up"><kbd>\*[UP]</kbd></a>
+and
+<a href="#down"><kbd>\*[DOWN]</kbd></a>
+cannot be used in conjunction with <kbd>\*[RULE]</kbd>.
+</p>
+
+<p>This <i>doesn&#8217;t</i> work:
+<br/>
+<span class="pre-in-pp">
+  \*[DOWN 2p]\*[RULE]\*[UP 2p]
+</span>
+whereas this does:
+<br/>
+<span class="pre-in-pp">
+  .ALD 2p
+  \*[RULE]
+  .RLD 2p
+</span>
+</p>
+
+<p class="tip-bottom">
+See groff&#8217;s
+<a href="#inline-linedrawing-groff">Horizontal line drawing function</a>
+for more information on drawing horizontal rules.
+</p>
+</div>
+
+<!-- -RULE_WEIGHT- -->
+
+<div id="rule-weight" class="box-macro-args">
+Macro: <b>RULE_WEIGHT</b> <kbd>&lt;weight in points&gt;</kbd>
+</div>
+
+<p class="requires">
+&bull;&nbsp;Must <span class="normal">not</span> have a
+<a href="definitions.html#unitofmeasure">unit of measure</a>
+appended.
+<br/>
+&nbsp;&nbsp;Argument must be greater than 0 and less than 100; decimal
+fractions are allowed.
+</p>
+
+<p>
+RULE_WEIGHT allows you to tell mom how heavy (in other words, how
+&#8220;thick&#8221;) you want the rules drawn with the inline
+escape,
+<a href="#inline-rule-mom"><kbd>\*[RULE]</kbd></a>.
+It takes a single argument: the weight of the rule in
+<a href="definitions.html#picaspoints">points</a>
+<i>but without the</i>
+<a href="definitions.html#unitofmeasure">unit of measure</a>
+<kbd>p</kbd> <i>attached</i>.  Thus, to set the weight of rules
+drawn with <kbd>\*[RULE]</kbd> to 1-1/4 points, you'd do
+<br/>
+<span class="pre-in-pp">
+  .RULE_WEIGHT 1.25
+</span>
+</p>
+
+<p>
+RULE_WEIGHT also sets the weight of rules drawn
+with
+<a href="graphical.html#drh"><kbd>.DRH</kbd></a>
+when DRH is not given any arguments.
+</p>
+
+<div class="rule-medium"><hr/></div>
+
+<!-- -INLINE_FONT_GROFF- -->
+
+<h2 id="inlines-groff-top" class="macro-group">Commonly-used groff inline 
escapes</h2>
+
+<h3 id="inline-fonts-groff" class="docs">Font control (<kbd 
style="text-transform: none">\f</kbd>)</h3>
+
+<p>
+Groff&#8217;s basic mechanism for inline font control is the escape
+<kbd>\f[&lt;font&gt;]</kbd>. 
+<br/>
+<span class="pre-in-pp">
+  \f[R]   Change to the medium roman font  (equivalent to mom's \*[ROM])
+  \f[I]   Change to the medium italic font (equivalent to mom's \*[IT])
+  \f[B]   Change to the bold roman font    (equivalent to mom's \*[BD])
+  \f[BI]  Change to the bold italic font   (equivalent to mom's \*[BDI])
+  \f[P]   Revert to the previous font      (equivalent to mom's \*[PREV])
+</span>
+</p>
+
+<p>
+<kbd>\f[&lt;font&gt;]</kbd> can be used with any valid
+<a href="definitions.html#font">font style</a>
+registered with groff.  (See
+<a href="appendices.html#style-extensions">here</a>
+for a list of pre-registered font styles provided by mom).
+</p>
+
+<p>
+<kbd>\f[&lt;font&gt;]</kbd> can also take a complete valid
+family+font name combo.  This is especially useful should you
+need to change both family and font inline.  For example, if your
+prevailing family and font are Times Roman and you want a few words
+in Courier Bold Italic, you could do this:
+<br/>
+<span class="pre-in-pp">
+  .FAM T
+  .FT  R
+  The command \f[CBI]ls -l\f[P] gives a "long" directory listing.
+</span>
+The Unix command <kbd>ls -l</kbd> will appear in Courier Bold Italic
+in a line that is otherwise in Times Roman.
+</p>
+
+<!-- -INLINE_HORIZONTAL_GROFF- -->
+
+<h3 id="inline-horizontal-groff" class="docs">Inline horizontal motions (<kbd 
style="text-transform: none;">\h</kbd>)</h3>
+
+<p>
+Whenever you need to move forward or backward on a line, use the
+inline
+<br/>
+<span class="pre-in-pp">
+  \h'&lt;distance&gt;'
+</span>
+In order to avoid unpleasant surprises, always append a
+<a href="definitions.html#unitofmeasure">unit of measure</a>
+to <kbd>&lt;distance&gt;</kbd>.  For example,
+<br/>
+<span class="pre-in-pp">
+  \h'1.25i'
+</span>
+moves you 1.25 inches to the right (forward) of the horizontal
+position on the current
+<a href="definitions.html#outputline">output line</a>.
+</p>
+
+<div class="box-tip">
+<p class="tip">
+<span class="note">Note:</span>
+<kbd>\h'&lt;distance&gt;'</kbd> is exactly equivalent to
+<a href="#fwd"><kbd>\*[FWD n&lt;unit&gt;]</kbd></a>.
+</p>
+</div>
+
+<p>
+To move backwards by the same amount, do
+<br/>
+<span class="pre-in-pp">
+  \h'-1.25i'
+</span>
+</p>
+
+<div class="box-tip">
+<p class="tip" style="margin-top: -1em;">
+<span class="note">Note:</span>
+<kbd>\h'-&lt;distance&gt;'</kbd> is exactly equivalent to
+<a href="#bck"><kbd>\*[BCK n&lt;unit&gt;]</kbd></a>.
+</p>
+</div>
+
+<!-- -INLINE_VERTICAL_GROFF- -->
+
+<h3 id="inline-vertical-groff" class="docs">Inline vertical motions (<kbd 
style="text-transform: none;">\v</kbd>)</h3>
+
+<p>
+If you need to raise or lower type on a line (say, for sub- or
+superscripts, or any other special effect), use
+<br/>
+<span class="pre-in-pp">
+  \v'&lt;distance&gt;'
+</span>
+In order to avoid unpleasant surprises, always append a
+<a href="definitions.html#unitofmeasure">unit of measure</a>
+to <kbd>&lt;distance&gt;</kbd>.  For example, 
+<br/>
+<span class="pre-in-pp">
+  \v'.6m'
+</span>
+moves you (approx.) 2/3 of an
+<a href="definitions.html#em">em</a>
+downward on the current
+<a href="definitions.html#outputline">output line</a>.
+</p>
+
+<div class="box-tip">
+<p class="tip">
+<span class="note">Note:</span>
+<kbd>\v'&lt;distance&gt;'</kbd> is exactly equivalent to
+<a href="#down"><kbd>\*[DOWN n&lt;unit&gt;]</kbd></a>.
+</p>
+</div>
+
+<p style="margin-top: -.5em;">
+To move upward an equivalent amount, do
+<br/>
+<span class="pre-in-pp">
+  \v'-.6m'
+</span>
+</p>
+
+<div class="box-tip" style="margin-top: -1em;">
+<p class="tip">
+<span class="note">Note:</span>
+<kbd>\v'&lt;-distance&gt;'</kbd> is exactly equivalent to
+<a href="#up"><kbd>\*[UP n&lt;unit&gt;]</kbd></a>.
+</p>
+</div>
+
+<div class="box-important">
+<p class="tip">
+<span class="important">Important:</span>
+The vertical motion of <kbd>\v</kbd> affects ONLY type on the
+current
+<a href="definitions.html#outputline">output line</a>.
+When groff breaks the output line, the effect of
+<kbd>\v</kbd> is cancelled; the baseline of the next output line
+is where it would be if you hadn&#8217;t used <kbd>\v</kbd>.
+</p>
+</div>
+
+<div class="box-tip">
+<p class="tip">
+<span class="tip">Tip:</span>
+When using <kbd>\v</kbd> for occasional effects in a line,
+don&#8217;t forget to reverse it when you've done what you want to
+do.  Otherwise, the remaining type will be set too high (if you
+used <kbd>\v</kbd> with the minus sign) or too low (if you used
+<kbd>\v</kbd> without the minus sign).
+</p>
+</div>
+
+<!-- -INLINE_STRINGWIDTH_GROFF- -->
+
+<h3 id="inline-stringwidth-groff" class="docs">String width function (<kbd 
style="text-transform: none;">\w</kbd>)</h3>
+
+<p>
+In the context of mom, the string width inline
+<kbd>\w'&lt;string&gt;'</kbd> primarily serves to let you establish the
+horizontal measure of something (e.g. indents) based on the length
+of a bit of text.  For example, if you want a left indent the length
+of the word &#8220;Examples:&#8221; plus a space, you can set it with
+the <kbd>\w</kbd> inline escape:
+<br/>
+<span class="pre-in-pp">
+  .IL "\w'Examples: '"
+</span>
+</p>
+
+<div class="box-tip" style="margin-top: -1em;">
+<p class="tip">
+<span class="note">Note:</span>
+Whenever you pass <kbd>\w'string'</kbd>
+to a macro that normally requires a
+<a href="definitions.html#unitofmeasure">unit of measure</a>,
+<i>do NOT add a unit of measure to the</i>
+<kbd>\w'string'</kbd> <i>argument.</i>
+</p>
+
+<p class="tip-bottom">
+Furthermore, if the string is composed of several words separated
+by spaces, you MUST surround the whole escape with double quotes,
+as in the example above.
+</p>
+</div>
+
+<!-- -INLINE_LINEDRAWING_GROFF- -->
+
+<h3 id="inline-linedrawing-groff" class="docs">Horizontal line drawing 
function (<kbd style="text-transform: none;">\l</kbd>)</h3>
+
+<p>
+The <kbd>\l'distance'</kbd> inline allows you to draw a horizontal
+rule of the specified distance.  You must supply a
+<a href="definitions.html#unitofmeasure">unit of measure</a>.
+Therefore, to set a 3-pica rule into a line of text, you'd do
+<br/>
+<span class="pre-in-pp">
+  A line of text with a superfluous \l'3P' 3-pica rule in it.
+</span>
+<kbd>\l'3P'</kbd>, above, not only draws the rule, but advances 3
+picas horizontally as well, just as you'd expect.
+</p>
+
+<p>
+For an easy way of drawing rules to the full measure of the current
+line or tab length, see
+<a href="#inline-rule-mom">Full measure rules</a>.
+</p>
+
+<p>
+The weight (thickness) of rules varies according to the point
+size in effect when you invoke <kbd>\l</kbd>, but you can&#8217;t fix
+the weight with any real precision.  A point size of 12 produces
+a tastefully moderate rule weight of between one-half and one
+point (depending on your printer).
+</p>
+
+<div class="box-tip">
+<p class="tip">
+<span class="note">Note:</span>
+Besides <kbd>\l</kbd>, <b>groff</b> provides a number of more
+sophisticated &#8220;drawing&#8221; escapes.  It is well beyond
+the scope of this documentation to demonstrate their usage; see
+<br/>
+<span class="pre-in-pp">
+  info groff =&gt; Escape index =&gt; \D
+</span>
+for directions concerning their use.  The drawing escapes can be a
+bit unwieldy, so mom provides &#8220;user-friendly&#8221; macros for
+the
+<a href="graphical.html#top">graphical objects</a>
+most commonly enountered in typesetting: horizontal and vertical
+rules, boxes, and circles (ellipses).
+</p>
+
+<p class="tip-bottom">
+Additionally, groff comes with two &#8220;preprocessors&#8221; that
+let you create ruled tables and vector diagrams (line drawings):
+<b>tbl</b> and <b>pic</b>.  The documentation for <b>tbl</b> can be
+downloaded from
+<br/>
+  <a style="display: inline-block; margin-left: 2em; margin-top: .5em; 
margin-bottom: .5em" 
href="http://cm.bell-labs.com/cm/cs/doc/76/tbl.ps.gz";>http://cm.bell-labs.com/cm/cs/doc/76/tbl.ps.gz</a>
+<br/>
+and <b>pic</b> from
+<br/>
+  <a style="display: inline-block; margin-left: 2em; margin-top: .5em; 
margin-bottom: .5em" 
href="http://www.kohala.com/start/troff/gpic.raymond.ps";>http://www.kohala.com/start/troff/gpic.raymond.ps</a>
+<br/>
+Both are powerful tools, but they can be nasty to learn&mdash;at
+first, anyway.  You may prefer to use a vector drawing program
+to create diagrams and tables; inserting the results into a
+document is easy enough with <kbd>.PSPIC</kbd> (consult
+<kbd>man groff-tmac</kbd> for information on this indispensable and
+easy-to-use macro).
+</p>
+</div>
+
+<!-- -INLINE_CHARACTERS_GROFF- -->
+
+<h3 id="inline-characters-groff" class="docs">Special characters and 
symbols</h3>
+<p>
+Here follows a short list of commonly-used special characters
+available via inline escapes.  If you&#8217;re not sure of the
+meaning of some of these characters, consult the
+<a href="definitions.html#top">Definitions of Terms</a>.
+</p>
+
+<p>
+For a complete list of special characters and glyphs (i.e. just
+about anything you'd ever want to appear on the printed page,
+including mathematical symbols, accented characters, unusual
+ligatures and letters unique to various European languages), consult
+<kbd>man groff-char</kbd>.
+</p>
+
+<span class="pre">
+  CHARACTER                   ESCAPE SEQUENCE
+  ---------                   ---------------
+  Comment line                \# or .\"
+  Fixed-width space           \&lt;space&gt; (ie backslash followed by a space)
+  Unbreakable space           \~
+  Digit-width (figure) space  \0
+  Zero-width character        \&amp;
+  Discretionary hyphen        \%
+  Backslash                   \\ or \e
+  Plus&#47;minus (arithmetic)     \(+-
+  Subtract (arithmetic)       \(mi
+  Multiply (arithmetic)       \(mu
+  Divide (arithmetic)         \(di
+  Em-dash                     \(em
+  En-dash                     \(en
+  Left double-quote           \(lq
+  Right double-quote          \(rq
+  Bullet                      \(bu
+  Ballot box                  \(sq
+  One-quarter                 \(14
+  One-half                    \(12
+  Three-quarters              \(34
+  Degree sign                 \(de
+  Dagger                      \(dg
+  Foot mark                   \(fm
+  Cent sign                   \(ct
+  Registered trademark        \(rg
+  Copyright                   \(co
+  Section symbol              \(se
+</span>
+<br/>
+
+<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="color.html#top">Next: 
Coloured text</a></td>
+</tr>
+</table>
+
+</div>
+
+<div class="bottom-spacer"><br/></div>
+
+</body>
+</html>
+<!-- vim: fileencoding=utf-8: nomodified: -->

Index: intro.html
===================================================================
RCS file: intro.html
diff -N intro.html
--- /dev/null   1 Jan 1970 00:00:00 -0000
+++ intro.html  18 Aug 2010 22:45:35 -0000      1.20
@@ -0,0 +1,526 @@
+<?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>What is mom?</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="definitions.html#top">Next: 
Definitions</a></td>
+  </tr>
+  </table>
+
+<h1 id="intro" class="docs">What is mom?</h1>
+
+<div style="text-align: center;">
+<ul class="no-enumerator" style="margin-left: -2.5em;">
+  <li ><a href="#intro-intro">Who is mom meant for?</a></li>
+  <li ><a href="#intro-typesetting">Typesetting with mom</a></li>
+  <li ><a href="#intro-docprocessing">Document processing with mom</a></li>
+  <li ><a href="#intro-philosophy">Mom&#8217;s philosophy</a></li>
+  <li ><a href="#intro-documentation">A note on mom&#8217;s 
documentation</a></li>
+  <li ><a href="#canonical">Canonical reference materials</a></li>
+  <li ><a href="#macro-args">How to read macro arguments</a></li>
+</ul>
+</div>
+
+<div class="rule-short" style="margin-top: 18px;"><hr/></div>
+
+<h2 id="intro-intro" class="docs">Who is mom meant for?</h2>
+
+<p>
+Mom (&#8220;my own macros&#8221;, &#8220;my other macros&#8221;,
+&#8220;maximum overdrive macros&#8221;...) is a macro set for
+groff, designed to format documents for PostScript output.
+She&#8217;s aimed at three kinds of users:
+</p>
+
+<ol style="margin-top: -.5em; margin-bottom: -.5em;">
+  <li>Typesetters who suspect groff might be &#8220;the right
+      tool for the job&#8221; but who are
+      frustrated/intimidated by groff&#8217;s terse, geeky,
+      not-always-typographically-intuitive
+      <a href="definitions.html#primitives">primitives</a>;
+  </li>
+  <li>Non-scientific writers (novelists, short story writers,
+      journalists, students) who just want their work to
+      look good;
+  </li>
+  <li>Newbies to computer typesetting, document processing or
+      groff who need a well-documented macro set to help them get
+      started.
+  </li>
+</ol>
+
+<p>
+As might be inferred from the above, mom is two macro packages in
+one: a set of typesetting macros, and a set of document formatting
+macros.  The typesetting macros govern the physical aspects
+of page layout and provide sane, comprehensible control over
+typographic refinements.  The document formatting macros let you
+focus on a document&#8217;s content and logical structure without
+worrying about typesetting or page layout at all.
+</p>
+
+<p>
+Because mom provides both typesetting and document formatting
+macros, it&#8217;s safe to say she blurs the distinction
+between document processing and document design.  While
+her basic document style come with pretty spiffy defaults
+(okay&mdash;change &#8220;spiffy&#8221; to &#8220;typographically
+professional&#8221;), you can easily control how all the various
+document elements look: titles, page headers and footers, page
+numbering, heads, subheads, footnotes and so on can be made to
+come out exactly the way you want.  And should you need precise
+typographic control over elements in a document that fall outside
+the range of mom&#8217;s document element tags, you don&#8217;t
+have to read up on groff
+<a href="definitions.html#primitives">primitives</a>
+in order to accomplish what you want; the typesetting macros take
+care of that.
+</p>
+
+<h2 id="intro-typesetting" class="docs">Typesetting with mom</h2>
+
+<p>
+Mom&#8217;s typesetting macros control the basic parameters
+of type: margins, line length, type family, font, point size,
+linespacing, and so on.  In addition, they allow you to move
+around on the page horizontally and vertically, and to set up
+tabs, indents, and columns.  Finally, they let you adjust such
+typographic details as justification style, letter spacing, word
+spacing, hyphenation, and kerning.
+</p>
+
+<p>
+In terms of typographic control, these macros resemble
+the commands used on dedicated typesetting computers like
+Compugraphics and Linotronics.  Most of them simply give access
+to groff&#8217;s typesetting primitives in a way that&#8217;s
+consistent and easy to use.  A few of them (tabs and indents,
+for example) handle fundamental typesetting requirements in ways
+radically different from groff primitives.
+</p>
+
+<p>
+With mom&#8217;s typesetting macros, you can, if you wish, create
+individual output pages that you design from the ground up.
+Provided you have not signalled to mom that you want document
+processing (via the
+<kbd><a href="docprocessing.html#start">START</a></kbd>
+macro; see below), every macro is a literal command that remains
+in effect until you modify it or turn it off.  This means that if
+you want to create flyers, surveys, tabulated forms, curricula
+vitae and so on, you may do so in the good old-fashioned way: one
+step at a time with complete control over every element on the
+page.
+</p>
+
+<p>
+Years of reading various mailing lists dealing with computer
+typesetting (groff, TeX, and friends) have convinced me that no
+program can ever replace the human eye and human input when it
+comes to high quality typesetting.  As of this writing, a thread
+on the subject of &#8220;micro typography&#8221; in groff has been
+going on for nearly a month.  The reason for the lengthy thread
+is obvious; words and punctuation on the printed page are too
+variable, too fluid, to be rendered flawlessly by any algorithm,
+no matter how clever.  (For whatever it&#8217;s worth, a similar
+problem exists with engraving musical scores by computer.)
+</p>
+
+<p>
+Mom does not try to solve the problems posed by things like
+hanging punctuation, left-margin adjustments for upper case
+letters like T and W, and so on.  She merely tries to provide
+tools that allow knowledgeable typesetters to come up with
+solutions to these problems in ways that are easier and more
+intuitive than manipulating groff at the
+<a href="definitions.html#primitives">primitive</a>
+level.  As a professional typesetter of more than two decades, and
+a writer, I have encountered few situations that cannot be handled
+by mom&#8217;s typesetting macros.
+</p>
+
+<p>
+Author&#8217;s note: One area where groff itself needs serious
+rethinking is in the matter of an algorithm that takes into
+account both word and letter spacing when
+<a href="definitions.html#just">justifying</a>
+lines.  At present, only word spacing is adjusted, requiring what
+I consider an unnecessary amount of user intervention whenever
+letter spacing is required.
+</p>
+
+<h2 id="intro-docprocessing" class="docs">Document processing with mom</h2>
+
+<p>
+Mom&#8217;s document processing macros let you format documents
+without having to worry about the typographic details.  In this
+respect, mom is similar to other groff macro packages, as well as
+to html and LaTeX.  Where mom differs is in the degree of control
+you have over the look and placement of the various elements of
+a document.  For example, if you don&#8217;t want your heads
+underlined, or you want them bigger/smaller, or you&#8217;d prefer
+them to be in a different font, or you&#8217;d rather they were
+flush left instead of centred, you can make the changes easily
+and have them apply to the whole document.  Temporary and one-off
+changes are easy, too.
+</p>
+
+<p>
+Mom has some nifty features other macro sets don&#8217;t provide.
+For example, you can switch between draft-style and final-copy
+output.  If you regularly make submissions to publishers and
+editors who insist on "typewritten, double-spaced," there&#8217;s
+a special macro&mdash;
+<a href="docprocessing.html#printstyle"><kbd>PRINTSTYLE 
TYPEWRITE</kbd></a>&mdash;
+that changes typeset documents into ones that would make your
+high-school typing teacher proud.  Footnotes, endnotes, tables of
+contents, multiple columns, nested lists, recto/verso printing and
+user designable headers and footers are also part of the fun.
+</p>
+
+<h2 id="intro-philosophy" class="docs">Mom&#8217;s philosophy</h2>
+
+<p>
+Formatting documents should be easy, from soup to nuts.  Writers
+need to focus on what they&#8217;re writing, not on how it looks.
+From the moment you fire up an editor to the moment you add
+"FINIS" to your opus, nothing should interfere with the flow of
+your words.  The commands needed to format your work should be
+easy to remember, comprehensible, and stand out well from the
+text.  There shouldn&#8217;t be too much clutter.  Your documents
+should be as readable inside a text editor as they are on the
+printed page.
+</p>
+
+<p>
+Unfortunately, in computerland, &#8220;easy,&#8221;
+&#8220;comprehensible,&#8221; and &#8220;readable&#8221; often
+mean &#8220;you&#8217;re stuck with what you get.&#8221; No
+document formatting system can give you exactly what you want all
+the time, every time.  Documents, it seems, always need to be
+tweaked, either to satisfy a typographic whim or to clarify some
+aspect of their content.
+</p>
+
+<p>
+Groff has traditionally solved the problem of formatting vs.
+tweaking by requiring users of the common macro packages (mm, ms,
+me and their offspring) to resort to groff
+<a href="definitions.html#primitives">primitives</a>
+and
+<a href="definitions.html#inlines">inline escapes</a>
+for their special typesetting needs.  Not to put too fine a
+point on it, groff primitives tend toward the abstruse, and most
+inline escapes are about as readable in-line as an encrypted
+password.  This does not make for happy-camper writers, who either
+find themselves stuck with a document formatting style they
+don&#8217;t really like, or are forced to learn groff from the
+ground up&mdash;a daunting task, to say the least.
+</p>
+
+<p>
+Mom aims to make creating documents a simple matter, but with
+no corresponding loss of user control.  The document processing
+macros provide an excellent set of defaults, but if something is
+not to your liking, you can change it.  And in combination with
+the typesetting macros, you have all the tools you need to massage
+passages and tweak pages until they look utterly professional.
+</p>
+
+<p>
+One rarely hears the term &#8220;user interface&#8221; in
+conjunction with document processing.  Since formatting takes
+place inside a text editor, little thought is given to the
+look and feel of the formatting commands.  Mom attempts to
+rectify this by providing users with a consistent, readable
+&#8220;coding&#8221; style.  Most of the macros (especially in
+the document processing set) have humanly-readable names.  Not
+only does this speed up learning the macros, it makes the sense
+of what&#8217;s going on in a document, typographically and
+structurally, easier to decipher.
+</p>
+
+<p>
+Mom does not try to be all things to all people.  In contrast to
+the normal groff philosophy, she does not try to produce output
+that looks good no matter where it&#8217;s displayed.  She&#8217;s
+designed for printed output, although with
+<a href="docprocessing.html#printstyle"><kbd>PRINTSTYLE TYPEWRITE</kbd></a>
+she produces acceptable terminal copy.  She makes no attempt to be
+compatible with older versions of troff.
+</p>
+
+<p>
+One special feature in mom&#8217;s design is the attention she
+pays to aligning the bottom margins of every page.  Nothing
+screams shoddy in typeset documents louder than bottom margins
+that wander, or, in typesetter jargon, &#8220;hang.&#8221; There
+are, of course, situations where whitespace at the bottom of a
+page may be desirable (for example, you wouldn&#8217;t want a head
+to appear at the bottom of the page without some text underneath
+it), but in all cases where hanging bottom margins can be avoided,
+mom does avoid them, by clever adjustments to leading (&#8220;line
+spacing&#8221;) and the spacing between different elements on the
+page.
+</p>
+
+<h2 id="intro-documentation" class="docs">A note on mom&#8217;s 
documentation</h2>
+
+<p>
+Writing documentation is tough, no doubt about it.  One is never
+quite sure of the user&#8217;s level of expertise.  Is s/he new
+to the application, new to its underlying protocols and programs,
+new to the operating system, new to computers?  At some point, one
+has to decide whom the documentation is for.  Making the wrong
+decision can mean the difference between a program that gets used
+and a program that gets tossed.
+</p>
+
+<p>
+Mom&#8217;s documentation assumes users know their way around
+their own operating system (basic file management, how to invoke
+commands, how to use a text editor, etc).  I use GNU/Linux,
+and while the documentation may exhibit a GNU/Linux bias, mom
+and groff can, in fact, be used on a variety of other popular
+operating systems, including the one from Redmond, Virginia, USA.
+</p>
+
+<p>
+The documentation further assumes they at least know what groff
+is, even if they don&#8217;t know much about it.  Lastly,
+it assumes that everyone&mdash;groff newbies and experts
+alike&mdash;learns faster from a few well-placed examples than
+from manpage-style reference docs.  What mom&#8217;s documentation
+doesn&#8217;t assume is that you know everything&mdash;not about
+groff, not about typesetting, not about document processing.  Even
+experts have odd lacunae in their knowledge base.  Therefore,
+whenever I suspect that a term or procedure will cause head
+scratching, I offer an explanation.  And when explanations
+aren&#8217;t enough, I offer examples.
+</p>
+
+<h2 id="canonical" class="docs">Canonical reference materials</h2>
+
+<p>
+The canonical reference materials for groff are
+<strong>cstr54</strong> (a downloadable PostScript copy of which
+is available
+<a href="http://www.kohala.com/start/troff/";>here</a>)
+and the <strong>troff</strong> and <strong>groff_diff</strong>
+manpages.  Another excellent source of information (maybe the best)
+is the groff info pages, available by typing
+<kbd>info groff</kbd>
+at the command line (assuming you have the TeXinfo standalone
+browser installed on your system, which is standard for most
+GNU/Linux distributions).  And for inputting special characters,
+see <kbd>man groff_char</kbd>.
+</p>
+
+<p style="margin-top: 24px;">
+I&#8217;ve tried to avoid reiterating the information contained
+in these documents; however, in a few places, this has proved
+impossible.  But be forewarned: I have no qualms about
+sidestepping excruciating completeness concerning groff usage;
+I&#8217;m more interested in getting mom users up and running.
+<i>Mea culpa.</i>
+</p>
+
+<div class="box-tip">
+<p class="tip-top" style="padding-bottom: 9px;">
+<b>Note:</b> Mom&#8217;s macro file (om.tmac) is heavily
+commented.  Each macro is preceded by a description of its
+arguments, function and usage, which may give you information in
+addition to what&#8217;s contained in this documentation.
+</p>
+</div>
+
+<div class="box-tip">
+<p class="tip-top" style="padding-bottom: 9px; text-indent: 0px;">
+<strong>Addendum:</strong> As of version 1.4-a, the main macro
+file, om.tmac, is now stripped of comments when groff is built
+from sources. om.tmac in the sources themselves still contains
+the comments, as do the tarballs posted on mom&#8217;s homepage.
+</p>
+</div>
+
+<div class="rule-short" style="padding-top: 6px; padding-bottom: 
3px;"><hr/></div>
+
+<h2 id="macro-args" class="docs">How to read macro arguments</h2>
+
+<p>
+The concise descriptions of macros in this documentation typically
+look like this:
+</p>
+
+<div class="box-macro-args">
+Macro: <b>MACRO_NAME</b> <kbd class="macro-args">arguments</kbd>
+</div>
+
+<p>
+<kbd>arguments</kbd> lists the macro&#8217;s
+arguments using conventions that should be familiar to anyone who
+has ever read a manpage.  Briefly:
+</p>
+
+<ol>
+  <li>Macro arguments are separated from each other by spaces.</li>
+  <li>If an argument is surrounded by chevrons
+      (<kbd>&lt;&nbsp;&gt;</kbd>), it&#8217;s a description
+      of the argument, not the argument itself.
+  </li>
+  <li>If an argument begins with or is surrounded by double-quotes, the
+      double quotes MUST be included in the argument.
+  </li>
+  <li>If the user has a choice between several arguments, each of the
+      choices is separated by the pipe character
+      (<kbd>|</kbd>), which means &#8220;or.&#8221;
+  </li>
+  <li>Arguments that are optional are surrounded by square brackets.</li>
+  <li><kbd>&lt;off&gt;</kbd> in an argument list means that any
+      argument other than those in the argument list turns the
+      macro off.
+  </li>
+</ol>
+
+<h3 id="toggle-macro" class="docs">Toggle macros</h3>
+
+<p>
+Some macros don&#8217;t require an argument.  They simply start
+something.  When you need to turn them off, the same macro with
+<em>any</em> argument will do the trick.  That&#8217;s right:
+<em>any</em> argument (in caps, lowercase or a mixture
+thereof).  This permits choosing whatever works for you:
+<kbd>OFF, end, Quit, Q, X</kbd>...  Hell, it
+could even be <kbd>I_love_mom</kbd>.
+</p>
+
+<p>
+Since these macros toggle things on and off, the argument list
+simply reads <kbd>toggle</kbd>.
+</p>
+
+<div id="examples" class="examples-container">
+<h2 class="docs" style="margin-top: .5em;">Examples</h2>
+
+<div class="examples">Example 1: An argument requiring double-quotes</div>
+
+<div class="box-macro-args" style="max-width: 684px;">
+Macro: <b>TITLE</b> <kbd class="macro-args">&quot;&lt;title of 
document&gt;&quot;</kbd>
+</div>
+
+<p>
+The required argument to TITLE is the title of your document.
+Since it&#8217;s surrounded by double-quotes, you must include
+them in the argument, like this:
+<br/>
+<span class="pre-in-pp">
+  .TITLE "My Pulitzer Novel"
+</span>
+</p>
+
+<div class="examples" style="margin-top: -1em;">Example 2: A macro with 
required and optional arguments</div>
+
+<div class="box-macro-args"  style="width: 684px;">
+Macro: <b>TAB_SET</b> <kbd class="macro-args">&lt;tab number&gt;  
&lt;indent&gt;  &lt;length&gt;  [ L | R | C | J [ QUAD ] ]&nbsp;</kbd>
+</div>
+
+<p>
+The first required argument is a number that identifies the tab
+(say, "3").  The second required argument is an indent from the
+left margin (say, 6 picas).  The third required argument is the
+length of the tab (say, 3 picas).  Therefore, at a minimum, when
+using this macro, you would enter:
+<br/>
+<span class="pre-in-pp">
+  .TAB_SET 3 6P 3P
+</span>
+The remaining two arguments are optional.  The first is a
+single letter, either <kbd>L, R, C</kbd> or
+<kbd>J</kbd>.  The second, which is itself
+optional after <kbd>L, R, C</kbd> or
+<kbd>J</kbd>, is the word <kbd>QUAD</kbd>.
+Therefore, depending on what additional information you wish to
+pass to the macro, you could enter:
+<br/>
+<span class="pre-in-pp">
+  .TAB_SET 3 6P 3P L
+</span>
+or
+<br/>
+<span class="pre-in-pp">
+  .TAB_SET 3 6P 3P L QUAD
+</span>
+</p>
+
+<div id="toggle-example" class="examples" style="margin-top: -1em;">Example 3: 
A sample toggle macro:</div>
+
+<div class="box-macro-args" style="max-width: 684px;">
+Macro: <b>QUOTE</b> <kbd class="macro-args">toggle</kbd>
+</div>
+
+<p>
+<kbd>QUOTE</kbd> begins a section of quoted text
+in a document and doesn&#8217;t require an argument.  When the
+quote&#8217;s finished, you have to tell mom it&#8217;s done.
+<span class="pre">
+  .QUOTE
+  So runs my dream, but what am I?
+  An infant crying in the night
+  An infant crying for the light
+  And with no language but a cry.
+  .QUOTE OFF
+</span>
+</p>
+
+<p>
+  Alternatively, you could have turned the quote off with
+  <kbd>END</kbd>, or <kbd>X</kbd>, or something else.
+  </p>
+</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="definitions.html#top">Next: Definitions</a></td>
+</tr>
+</table>
+
+</div>
+
+<div class="bottom-spacer"><br/></div>
+
+</body>
+</html>
+<!-- vim: fileencoding=utf-8: nomodified: -->

Index: letters.html
===================================================================
RCS file: letters.html
diff -N letters.html
--- /dev/null   1 Jan 1970 00:00:00 -0000
+++ letters.html        18 Aug 2010 22:45:36 -0000      1.16
@@ -0,0 +1,567 @@
+<?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 -- Writing letters</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="macrolist.html#top">Next: Quick 
reference guide</a></td>
+</tr>
+</table>
+
+<h1 class="docs">Writing letters</h1>
+
+<h2 id="letters-intro" class="docs">Introduction</h2>
+
+<p>
+Mom&#8217;s simple but effective letter-writing macros are a subset
+of the
+<a href="docprocessing.html#docprocessing">document processing macros</a>,
+designed to ease the creation of correspondence.
+</p>
+
+<p>
+Because the letter macros are a subset of the document processing
+macros, you can use
+<a href="definitions.html#controlmacro">control macros</a>
+to design correspondence to your own specifications.  However,
+mom makes no pretence of providing complete design flexibility in
+the matter of letters, which are, after all, simple communicative
+documents whose only real style requirements are that they be neat
+and professional-looking.
+</p>
+
+<div class="examples-container" style="margin-top: 1.5em; margin-bottom: 
1.5em;">
+<h3 id="tutorial" class="docs">Tutorial &ndash; writing letters</h3>
+
+<p>
+Mom letters begin, like all mom-processed documents, with
+<a href="docprocessing.html#reference-macros">reference macros</a>
+(in this case,
+<a href="docprocessing.html#author">AUTHOR</a>),
+a
+<a href="docprocessing.html#doctype">DOCTYPE</a>
+(LETTER, obviously), the essential
+<a href="docprocessing.html#printstyle">PRINTSTYLE</a>
+macro, and
+<a href="docprocessing.html#start">START</a>,
+like this:
+<br/>
+<span class="pre-in-pp">
+  .AUTHOR    "Yannick P. Guique"
+  .DOCTYPE    LETTER
+  .PRINTSTYLE TYPESET
+  .START
+</span>
+PRINTSTYLE, above, could also be <kbd>TYPEWRITE</kbd>. Mom has no
+objection to creating letters that look like they were typed on an
+Underwood by a shapely secretary with 1940s gams.
+</p>
+
+<p>
+After the START macro, you enter headers pertinent to your letter:
+the date, the addressee (in business correspondence, typically both
+name and address), the addresser (that&#8217;s you; in business
+correspondence, typically both name and address), and a greeting
+(in full, e.g. &#8220;Dear Mr. Smith,&#8221; or &#8220;Dear
+Mr. Smith:&#8221;).
+</p>
+
+<p>
+The macros for entering the headers are simple (they&#8217;re not even
+<a href="definitions.html#toggle">toggles</a>):
+<br/>
+<span class="pre-in-pp">
+  .DATE
+  .TO
+  .FROM
+  .GREETING
+</span>
+You may enter them in any order you like, except for GREETING, which
+must come last.  Mom ignores any headers you omit and spaces the
+letter&#8217;s opening according to what you do include.  See
+<a href="#letters-defaults">Default for letters</a>
+to find out how mom formats the headers.
+</p>
+
+<p>
+(In pre 1.1.7-a releases of mom, the order of entering headers was
+fixed at the above.  This has been changed, although if you do
+follow the above order, mom will continue to behave exactly as she
+did in pre 1.1.7-a.)
+</p>
+
+<p>
+Once you&#8217;ve filled in what you need to get a letter started,
+simply type the letter, introducing each and every paragraph,
+including the first, with the
+<a href="docelement.html#pp">PP</a>
+macro.
+</p>
+
+<p>
+At the end of the letter, should you wish a closing (&#8220;Yours
+truly,&#8221; &#8220;Sincerely,&#8221; &#8220;Hugs and
+kisses&#8221;), invoke the macro, <kbd>.CLOSING</kbd>, on a line
+by itself, and follow it with the text of the closing. <b>N.B.</b>
+Don&#8217;t put your name here; mom supplies it automatically from
+<a href="docprocessing.html#author">AUTHOR</a>),
+with enough space to leave room for your signature.  If you omit the
+closing, mom simply adds your name (from AUTHOR), again with enough
+space for your signature.
+</p>
+
+<p>
+Assuming our tutorial letter is for business correspondence,
+here&#8217;s what the complete letter looks like.
+<br/>
+<span class="pre-in-pp">
+  .AUTHOR    "Yannick P. Guique"
+  .DOCTYPE    LETTER
+  .PRINTSTYLE TYPESET
+  .START
+  .DATE
+  August 25, 2010
+  .TO
+  GUILLAUME BARRIÈRES
+  Minidoux Corporation
+  5000 Pannes Drive
+  Redmond, Virginia
+  .FROM
+  Y.P. GUIQUE
+  022 Umask Road
+  St-Sauveur-en-dehors-de-la-mappe, Québec
+  .GREETING
+  Dear Mr. Barrières,
+  .PP
+  It has come to my attention that you have once again been
+  lobbying the US government to prohibit the use of open source
+  software by endeavouring to outlaw so-called "warranty
+  free" applications.
+  .PP
+  I feel it is my duty to inform you that the success of your
+  operating system relies heavily on open source programs and
+  protocols, notably TCP/IP.
+  .PP
+  Therefore, in the interests of your corporation&#8217;s fiscal health,
+  I strongly advise that you withdraw support for any US
+  legislation that would cripple or render illegal open source
+  development.
+  .CLOSING
+  Sincerely,
+</span>
+This produces a letter with headers that follow the North American
+standard for business correspondence.  If you&#8217;d prefer another style
+of correspondence, for example, British, you&#8217;d set up the same
+letter like this:
+<br/>
+<span class="pre-in-pp">
+  .AUTHOR    "Yannick P. Guique"
+  .DOCTYPE    LETTER
+  .PRINTSTYLE TYPESET
+  .START
+  .FROM
+  .RIGHT
+  Y.P. GUIQUE
+  022 Umask Road
+  St-Sauveur-en-dehors-de-la-mappe, Québec
+  .TO
+  GUILLAUME BARRIÈRES
+  Minidoux Corporation
+  5000 Pannes Drive
+  Redmond, Virginia
+  .DATE
+  .RIGHT
+  August 25, 2004
+  .GREETING
+  Dear Mr. Barrières,
+</span>
+Notice the use of <kbd>.RIGHT</kbd> after <kbd>.FROM</kbd> and
+<kbd>.DATE</kbd> in this example, used to change the default quad
+for these macros.
+</p>
+</div>
+
+<h2 id="letters-defaults" class="docs">Mom&#8217;s default letter style</h2>
+
+<p>
+In letters, if the order of header macros is
+</p>
+<ol style="margin-top: -.5em;">
+  <li><kbd>.DATE</kbd></li>
+  <li><kbd>.TO</kbd>&nbsp;&nbsp;(the addressee)</li>
+  <li><kbd>.FROM</kbd>&nbsp;&nbsp;(the addresser)</li>
+  <li><kbd>.GREETING</kbd>&nbsp;&nbsp;(&#8220;Dear Whoever,&#8221; &#8220;To 
Whom It May Concern,&#8221; etc.)</li>
+</ol>
+<p style="margin-top: -.5em;">
+mom sets
+</p>
+<ul style="margin-top: -.5em;">
+  <li>the date flush right, page right, at the top of page one,
+      with a gap of two linespaces underneath
+  </li>
+  <li>the addressee (<kbd>.TO</kbd>) in a block flush left, page
+      left, with a gap of one linespace underneath
+  </li>
+  <li>the addresser (<kbd>.FROM</kbd>) in a block flush left, page
+      left, with a gap of one linespace underneath
+  </li>
+  <li>the greeting flush left, with a gap of one linespace
+      underneath
+  </li>
+</ul>
+<p style="margin-top: -.5em;">
+which is the standard for North American business correspondence.
+</p>
+
+<p>
+If you switch the order of <kbd>.DATE</kbd>, <kbd>.TO</kbd> and/or
+<kbd>.FROM</kbd>, mom sets all the headers
+flush left, with a gap of one linespace underneath each.  (The
+default left quad of any header can be changed by invoking the
+<kbd>.RIGHT</kbd> macro, on a line by itself, immediately before
+inputting the text of the header.)
+</p>
+
+<p>
+Following the headers, mom sets
+</p>
+<ul style="margin-top: -.5em;">
+  <li>the body of the letter justified</li>
+  <li>in multi-page letters:
+  <ul style="margin-left: -.5em;">
+    <li>a footer indicating there&#8217;s a next page (of the form 
<kbd>.../#</kbd>)</li>
+    <li>the page number at the top of every page after page one</li>
+  </ul></li>
+  <li>the closing/signature lines flush left, indented halfway across the 
page</li>
+</ul>
+
+<p>
+Other important style defaults are listed below, and may be changed
+via the
+<a href="typesetting.html#top">typesetting macros</a>
+or the document processing
+<a href="definitions.html#controlmacro">control macros</a>
+prior to
+<a href="docprocessing.html#start">START</a>.
+Assume that any style parameter not listed below is the same as for
+any document processed with
+<a href="docprocessing.html#typeset-defaults">PRINTSTYLE <kbd>TYPESET</kbd></a>
+or
+<a href="docprocessing.html#typewrite-defaults">PRINTSTYLE 
<kbd>TYPEWRITE</kbd></a>.
+</p>
+
+<div class="defaults-container" style="padding-bottom: 8px;">
+<span class="pre defaults">
+  PARAMETER                 PRINTSTYLE TYPESET         PRINTSTYLE TYPEWRITE
+
+  Paper size                8.5 x 11 inches            8.5 x 11 inches
+  Left/right margins        1.125 inches               1.125 inches
+  Header margin             3.5 picas                  3.5 picas
+   (for page numbers)
+  Header gap                3 picas                    3 picas
+   (for page numbers)
+  Family                    Times Roman                Courier
+  Font                      roman                      roman
+  Point size                12                         12
+  Line space                13.5                       12 (i.e. singlespaced)
+  Paragraph indent          3 ems                      3 picas
+  Spaced paragraphs         yes                        no
+  Footers*                  yes                        yes
+  Footer margin             3 picas                    3 picas
+  Footer gap                3 picas                    3 picas
+  Page numbers              top, centred               top, centred
+
+  *Footers contain a &quot;next page&quot; number of the form .../#
+</span>
+</div>
+
+<div class="rule-medium"><hr/></div>
+
+
+<div class="macro-list-container">
+<h3 id="index-letters-macros" class="macro-list">The letter macros</h3>
+<p style="margin-left: 9px; margin-top: -1.5em;">
+All letter macros must come after
+<a href="docprocessing.html#start">START</a>,
+except NO_SUITE, which must come after
+<a href="docprocessin.html#start">PRINTSTYLE</a>
+and before
+<a href="docprocessing.html#start">START</a>.
+</p>
+
+<ul class="macro-list" style="margin-top: -.75em;">
+  <li><a href="#date">DATE</a></li>
+  <li><a href="#to">TO</a></li>
+  <li><a href="#from">FROM</a></li>
+  <li><a href="#greeting">GREETING</a></li>
+  <li><a href="#closing">CLOSING</a>
+  <ul style="margin-left: -.5em;">
+    <li><a href="#closing-indent">CLOSING_INDENT</a></li>
+    <li><a href="#signature-indent">SIGNATURE_INDENT</a></li>
+  </ul></li>
+  <li><a href="#no-suite">NO_SUITE</a> &ndash; turn the &#8220;next 
page&#8221; footer off</li>
+</ul>
+</div>
+
+<!-- -DATE- -->
+
+<div id="date" class="box-macro-args">
+Macro: <b>DATE</b>
+</div>
+
+<p>
+Invoke <kbd>.DATE</kbd> on a line by itself, with the date
+underneath, like this:
+<br/>
+<span class="pre-in-pp">
+  .DATE
+  October 31, 2012
+</span>
+If you wish to change the default quad direction for the date,
+enter <kbd>.LEFT</kbd> or <kbd>.RIGHT</kbd>, on a line by itself,
+immediately after <kbd>.DATE</kbd>.
+</p>
+
+<p>
+If you wish to insert additional space between the date and any
+letter header that comes after it, do so after inputting the date,
+not at the top of the next header macro, like this:
+<br/>
+<span class="pre-in-pp">
+  .DATE
+  October 31, 2012
+  .SPACE  \"Or, more simply, .SP
+</span>
+If you wish to remove the default space,
+<br/>
+<span class="pre-in-pp">
+  .SPACE -1v  \"Or, more simply, .SP -1v
+</span>
+will do the trick.
+</p>
+
+<!-- -TO- -->
+
+<div id="to" class="box-macro-args">
+Macro: <b>TO</b>
+</div>
+
+<p>
+Invoke <kbd>.TO</kbd> on a line by itself, with the name and address
+of the addressee underneath, like this:
+<br/>
+<span class="pre-in-pp">
+  .TO
+  JOHN SMITH
+  10 Roberts Crescent
+  Bramladesh, Ont.
+</span>
+If you wish to change the default quad direction for the address,
+enter <kbd>.LEFT</kbd> or <kbd>.RIGHT</kbd>, on a line by itself,
+immediately after <kbd>.TO</kbd>.
+</p>
+
+<p>
+If you wish to insert additional space between the address and
+any letter header that comes after it, do so after inputting the
+address, not at the top of the next header macro, like this:
+<br/>
+<span class="pre-in-pp">
+  .TO
+  JOHN SMITH
+  10 Roberts Crescent
+  Bramladesh, Ont.
+  .SPACE  \"Or, more simply, .SP
+</span>
+If you wish to remove the default space,
+<br/>
+<span class="pre-in-pp">
+  .SPACE -1v  \"Or, more simply, .SP -1v
+</span>
+will do the trick.
+</p>
+
+<!-- -FROM- -->
+
+<div id="from" class="box-macro-args">
+Macro: <b>FROM</b>
+</div>
+
+<p>
+Invoke <kbd>.FROM</kbd> on a line by itself, with the name and
+address of the addresser underneath, like this:
+<br/>
+<span class="pre-in-pp">
+  .FROM
+  JOE BLOW
+  15 Brunette Road
+  Ste-Vieille-Andouille, Québec
+</span>
+If you wish to change the default quad direction for the address,
+enter <kbd>.LEFT</kbd> or <kbd>.RIGHT</kbd>, on a line by itself,
+immediately after <kbd>.FROM</kbd>.
+</p>
+
+<p>
+If you wish to insert additional space between the address and
+any letter header that comes after it, do so after inputting the
+address, not at the top of the next header macro, like this:
+<br/>
+<span class="pre-in-pp">
+  .FROM
+  JOE BLOW
+  15 Brunette Road
+  Ste-Vieille-Andouille, Québec
+  .SPACE  \"Or, more simply, .SP
+</span>
+If you wish to remove the default space,
+<br/>
+<span class="pre-in-pp">
+  .SPACE -1v  \"Or, more simply, .SP -1v
+</span>
+will do the trick.
+</p>
+
+<!-- -GREETING- -->
+
+<div id="greeting" class="box-macro-args">
+Macro: <b>GREETING</b>
+</div>
+
+<p>
+Invoke <kbd>.GREETING</kbd> on a line by itself, with the full
+salutation you want for the letter underneath, like this:
+<br/>
+<span class="pre-in-pp">
+  .GREETING
+  Dear Mr. Smith,
+</span>
+</p>
+
+<!-- -CLOSING- -->
+
+<div id="closing" class="box-macro-args">
+Macro: <b>CLOSING</b>
+</div>
+
+<p>
+Invoke <kbd>.CLOSING</kbd> on a line by itself after the body of
+the letter, with the closing you&#8217;d like (e.g. &#8220;Yours
+truly,&#8221;) underneath, like this:
+<br/>
+<span class="pre-in-pp">
+  .CLOSING
+  Yours truly,
+</span>
+</p>
+
+<div class="box-tip" style="background-color: #E3D2B1;">
+<p class="tip">
+<span class="tip" style="display: inline-block; padding-bottom: .5em; color: 
#000056;">CLOSING control macros and defaults</span>
+<br/>
+Two macros control the behaviour of <kbd>.CLOSING</kbd>:
+</p>
+<ul style="margin-top: -1.25em;">
+  <li>CLOSING_INDENT</li>
+  <li>SIGNATURE_SPACE</li>
+</ul>
+
+<p id="closing-indent" style="margin-top: -.25em;">
+The first, CLOSING_INDENT, indicates the distance from the left
+margin you&#8217;d like to have your closing indented.  It takes a
+single
+<a href="definitions.html#numericargument">numeric argument</a>
+and must have a
+<a href="definitions.html#unitofmeasure">unit of measure</a>
+appended to it, unless you want an indent of 0 (zero).  Mom&#8217;s
+default is one half the width of the letter&#8217;s line length
+(i.e. halfway across the page).  If you wanted, instead, an indent of
+6
+<a href="definitions.html#picaspoints">picas</a>,
+you&#8217;d do it like this:
+<br/>
+<span class="pre-in-pp">
+  .CLOSING_INDENT 6P
+</span>
+Or, if you wanted to have no indent at all:
+<br/>
+<span class="pre-in-pp">
+  .CLOSING_INDENT 0
+</span>
+</p>
+
+<p id="signature-space" style="margin-top: -1.25em;">
+The second, SIGNATURE_SPACE, controls how much room to leave for the
+signature.  It takes a single
+<a href="definitions.html#numericargument">numeric argument</a>
+and must have a
+<a href="definitions.html#unitofmeasure">unit of measure</a>
+appended to it.  Mom&#8217;s default is 3 line spaces, but if you
+wanted to change that to, say, 2 line spaces, you&#8217;d do:
+<br/>
+<span class="pre-in-pp">
+  .SIGNATURE_SPACE 2v
+</span>
+</p>
+</div>
+
+<!-- -NO_SUITE- -->
+
+<div class="box-macro-args" style="margin-top: 2em;">
+Macro: <b>NO_SUITE</b>
+</div>
+
+<p>
+If you don&#8217;t want mom to print a &#8220;next page&#8221;
+number at the bottom of multi-page letters, invoke
+<kbd>.NO_SUITE</kbd>, on a line by itself, prior to
+<a href="docprocessing.html#start">START</a>.
+</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="macrolist.html">Next: 
Quick reference guide</a></td>
+</tr>
+</table>
+
+</div>
+
+<div class="bottom-spacer"><br/></div>
+
+</body>
+</html>
+<!-- vim: fileencoding=utf-8: nomodified: -->

Index: macrolist.html
===================================================================
RCS file: macrolist.html
diff -N macrolist.html
--- /dev/null   1 Jan 1970 00:00:00 -0000
+++ macrolist.html      18 Aug 2010 22:45:36 -0000      1.17
@@ -0,0 +1,1280 @@
+<?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 -- Quick reference guide</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="appendices.html#top">Next: 
Appendices</a></td>
+</tr>
+</table>
+
+<h1 class="docs">Quick reference guide</h1>
+
+<p>
+Once you know your way around mom, you may find this guide
+preferable to using the Table of Contents.  It lists mom&#8217;s
+major user-space macros.  The links point to references found
+elsewhere in the documentation.
+</p>
+
+
+<div class="macro-list-container" style="padding-left: 9px; padding-right: 
9px; padding-bottom: 1px;">
+<h2 class="docs" style="text-align: center; padding-top: 15px;">Index to the 
quick reference guide</h2>
+<div style="width: 50%; float: left; margin-right: 9px;">
+<h3 class="docs" style="margin-top: 1.25em;">TYPESETTING MACROS</h3>
+<ul style="margin-top: .5em; margin-left: 0; padding-left: 0; list-style-type: 
none;">
+  <li><a href="#qr-1">Paper size, margins, line length</a></li>
+  <li><a href="#qr-2">Family, font, point size</a></li>
+  <li><a href="#qr-3">Font modifications</a></li>
+  <li><a href="#qr-4">Linespacing (leading)</a></li>
+  <li><a href="#qr-5">Justification, quad, breaking lines</a></li>
+  <li><a href="#qr-6">Hyphenation</a></li>
+  <li><a href="#qr-7">Word and sentence spacing</a></li>
+  <li><a href="#qr-8">Kerning, ligatures, smartquotes</a></li>
+  <li><a href="#qr-9">Horizontal/vertical motions, columns</a></li>
+  <li><a href="#qr-10">Indents</a></li>
+  <li><a href="#qr-11">Tabs</a></li>
+  <li><a href="#qr-12">Underscoring, underlining</a></li>
+  <li><a href="#qr-13">Superscipts</a></li>
+  <li><a href="#qr-14">Nested lists</a></li>
+  <li><a href="#qr-15">Colour</a></li>
+  <li><a href="#qr-16">Dropcaps</a></li>
+  <li><a href="#qr-17">Utilities</a></li>
+  <li><a href="#qr-18">Graphical Objects</a></li>
+</ul>
+<h3 class="docs" style="margin-top: -.5em;">DOCUMENT PROCESSING MACROS</h3>
+<ul style="margin-top: .5em; margin-left: 0; padding-left: 0; list-style-type: 
none;">
+  <li><a href="#qr-19">Reference macros</a></li>
+  <li><a href="#qr-20">General document formatting directives</a></li>
+  <li><a href="#qr-21">Line numbering</a></li>
+  <li><a href="#qr-22">Set documents in columns</a></li>
+  <li><a href="#qr-23">TYPEWRITE control macros</a></li>
+  <li><a href="#qr-24">Initiate document processing</a></li>
+</ul>
+</div>
+<ul style="margin-top: 1.75em; margin-left: 0; padding-left: 0; 
list-style-type: none;">
+  <li><a href="#qr-25">Epigraphs</a></li>
+  <li><a href="#qr-26">Main heads</a></li>
+  <li><a href="#qr-27">Subheads</a></li>
+  <li><a href="#qr-28">Paragraph heads</a></li>
+  <li><a href="#qr-19">Reference macros</a></li>
+  <li><a href="#qr-29">Paragraphs</a></li>
+  <li><a href="#qr-30">Quotes (line for line quotes)</a> </li>
+  <li><a href="#qr-31">Blockquotes (cited passages of text)</a></li>
+  <li><a href="#qr-32">Code snippets (inserting bits of programming 
code)</a></li>
+  <li><a href="#qr-33">Author linebreaks (section breaks)</a></li>
+  <li><a href="#qr-34">Document termination string</a></li>
+  <li><a href="#qr-35">Footnotes</a></li>
+  <li><a href="#qr-36">Endnotes</a></li>
+  <li><a href="#qr-37">Margin notes</a></li>
+  <li><a href="#qr-38">Bibliographic references</a></li>
+  <li><a href="#qr-39">Tables of contents</a></li>
+  <li><a href="#qr-40">Letter (correspondence) macros</a></li>
+  <li><a href="#qr-41">Changing global print style parameters after<br/><span 
style="margin-left: 1.25em;">START</span></a></li>
+  <li><a href="#qr-42">Managing a document&#8217;s first-page header<br/><span 
style="margin-left: 1.25em;">(the &#8220;docheader&#8221;)</span></a></li>
+  <li><a href="#qr-43">Managing page headers and footers</a></li>
+  <li><a href="#qr-44">Recto/verso page headers and footers</a></li>
+  <li><a href="#qr-45">Pagination</a></li>
+  <li><a href="#qr-46">Document and section cover (title) pages</a></li>
+  <li><a href="#qr-47">Utilities</a></li>
+</ul>
+</div>
+
+<h2 class="docs">Quick reference guide</h2>
+
+<div style="display: inline-block; margin-top: 1em; margin-bottom: .5em; 
border-bottom: 2px solid #302419;"><kbd>TYPESETTING MACROS</kbd></div>
+
+<table class="quick-ref">
+<tr>
+<th id="qr-1" class="quick-ref" colspan="2" >+++ Paper size, margins, line 
length</th>
+</tr>
+<tr>
+<td><a href="typesetting.html#paper">PAPER</a></td><td>-- set common paper 
sizes (letter, A4, etc)</td>
+</tr>
+<tr>
+<td><a href="typesetting.html#pagewidth">PAGEWIDTH</a></td><td>-- set a custom 
page width</td>
+</tr>
+<tr>
+<td><a href="typesetting.html#pagelength">PAGELENGTH</a></td><td>-- set a 
custom page length</td>
+</tr>
+<tr>
+<td><a href="typesetting.html#page">PAGE</a></td><td>-- set explicit page 
dimensions and margins</td>
+</tr>
+<tr>
+<td><a href="typesetting.html#t-margin">T_MARGIN</a></td><td>-- set a top 
margin</td>
+</tr>
+<tr>
+<td><a href="typesetting.html#b-margin">B_MARGIN</a></td><td>-- set a bottom 
margin</td>
+</tr>
+<tr>
+<td><a href="typesetting.html#l-margin">L_MARGIN</a></td><td>-- set a left 
margin (page offset)</td>
+</tr>
+<tr>
+<td><a href="typesetting.html#r-margin">R_MARGIN</a></td><td>-- set a right 
margin</td>
+</tr>
+<tr>
+<td><a href="typesetting.html#linelength">LL</a></td><td>-- set a line 
length</td>
+</tr>
+</table>
+
+<table class="quick-ref">
+<tr><th id="qr-2" class="quick-ref" colspan="2">+++ Family, font, point 
size</th></tr>
+<tr>
+<td><a href="typesetting.html#family">FAMILY</a></td><td>-- set the family of 
type</td>
+</tr>
+<tr>
+<td><a href="typesetting.html#font">FT</a></td><td>-- set the font style 
(roman, italic, etc)</td>
+</tr>
+<tr>
+<td><a href="typesetting.html#fallback-font">FALLBACK_FONT</a></td><td>-- 
establish a fallback font (for missing fonts)</td>
+</tr>
+<tr>
+<td><a href="typesetting.html#ps">PT_SIZE</a></td><td>-- set the point 
size</td>
+</tr>
+<tr>
+<td><a href="inlines.html#inline-size-mom">\*[SIZE n]</a></td><td>-- change 
the point size inline</td>
+</tr>
+</table>
+
+<table class="quick-ref">
+<tr>
+<th id="qr-3" class="quick-ref" colspan="2" >+++ Font modifications</th>
+</tr>
+<tr><td style="padding-left: 0;">Pseudo italic</td></tr>
+<tr>
+<td><a href="typesetting.html#setslant">SETSLANT</a></td><td>-- set the degree 
of slant</td>
+</tr>
+<tr>
+<td><a href="typesetting.html#slant-inline">\*[SLANT]</a></td><td>-- invoke 
pseudo italic inline</td>
+</tr>
+<tr>
+<td><a href="typesetting.html#slant-inline">\*[SLANTX]</a></td><td>-- off 
pseudo italic inline</td>
+</tr>
+<tr><td style="padding-left: 0;">Pseudo bold</td></tr>
+<tr>
+<td><a href="typesetting.html#setbolder">SETBOLDER</a></td><td>-- set the 
amount of emboldening</td>
+</tr>
+<tr>
+<td><a href="typesetting.html#bolder-inline">\*[BOLDER]</a></td><td>-- invoke 
pseudo bold inline</td>
+</tr>
+<tr>
+<td><a href="typesetting.html#bolder-inline">\*[BOLDERX]</a></td><td>-- off 
pseudo bold inline</td>
+</tr>
+<tr><td style="padding-left: 0;">Pseudo condensed</td></tr> 
+<tr>
+<td><a href="typesetting.html#condense">CONDENSE</a></td><td>-- set the amount 
to pseudo condense</td>
+</tr>
+<tr>
+<td><a href="typesetting.html#cond-inline">\*[COND]</a></td><td>-- invoke 
pseudo condensing inline</td>
+</tr>
+<tr>
+<td><a href="typesetting.html#cond-inline">\*[CONDX]</a></td><td>-- off pseudo 
condensing inlines</td>
+</tr>
+<tr><td style="padding-left: 0;">Pseudo extended</td></tr>
+<tr>
+<td><a href="typesetting.html#extend">EXTEND</a></td><td>-- set the amount to 
pseudo extend</td>
+</tr>
+<tr>
+<td><a href="typesetting.html#ext-inline">\*[EXT]</a></td><td>-- invoke pseudo 
extending inline</td>
+</tr>
+<tr>
+<td><a href="typesetting.html#ext-inline">\*[EXTX]</a></td><td>-- off pseudo 
condensing inlinee</td>
+</tr>
+</table>
+
+<table class="quick-ref">
+<tr>
+<th id="qr-4" class="quick-ref" colspan="2" >+++ Linespacing (leading)</th>
+</tr>
+<tr>
+<td><a href="typesetting.html#leading">LS</a></td><td>-- set the linespacing 
(leading)</td>
+</tr>
+<tr>
+<td><a href="typesetting.html#autolead">AUTOLEAD</a></td><td>-- set the 
linespacing relative to the point size</td>
+</tr>
+</table>
+
+<table class="quick-ref">
+<tr>
+<th id="qr-5" class="quick-ref" colspan="2" >+++ Justification, quad 
direction, line-by-line setting, breaking lines</th>
+</tr>
+<tr>
+<td><a href="typesetting.html#justify">JUSTIFY</a></td><td>-- justify text to 
both margins</td>
+</tr>
+<tr>
+<td><a href="typesetting.html#quad">QUAD</a></td><td>-- "justify" text left, 
centre, or right</td>
+</tr>
+<tr>
+<td><a href="typesetting.html#lrc">LEFT</a></td><td>-- set line-by-line quad 
left</td>
+</tr>
+<tr>
+<td><a href="typesetting.html#lrc">CENTER</a></td><td>-- set line-by-line quad 
centre</td>
+</tr>
+<tr>
+<td><a href="typesetting.html#lrc">RIGHT</a></td><td>-- set line-by-line quad 
right</td>
+</tr>
+<tr>
+<td><a href="typesetting.html#br">BR</a></td><td>-- break a justified line</td>
+</tr>
+<tr>
+<td><a href="typesetting.html#spread">SPREAD</a></td><td>-- force justify a 
line</td>
+</tr>
+<tr>
+<td><a href="typesetting.html#el">EL</a></td><td>-- break a line without 
advancing on the page</td>
+</tr>
+</table>
+
+<table class="quick-ref">
+<tr>
+<th id="qr-6" class="quick-ref" colspan="2" >+++ Hyphenation</th>
+</tr>
+<tr>
+<td><a href="typesetting.html#hy">HY</a></td><td>-- automatic hyphenation on 
or off</td>
+</tr>
+<tr>
+<td><a href="typesetting.html#hy-set">HY_SET</a></td><td>-- set automatic 
hyphenation parameters</td>
+</tr>
+</table>
+
+<table class="quick-ref">
+<tr>
+<th id="qr-7" class="quick-ref" colspan="2" >+++ Word and sentence spacing</th>
+</tr>
+<tr>
+<td><a href="typesetting.html#ws">WS</a></td><td>-- set the minimum word space 
size</td>
+</tr>
+<tr>
+<td><a href="typesetting.html#ss">SS</a></td><td>-- set the sentence space 
size</td>
+</tr>
+</table>
+
+<table class="quick-ref">
+<tr>
+<th id="qr-8" class="quick-ref" colspan="2" >+++ Kerning, ligatures, 
smartquotes</th>
+</tr>
+<tr>
+<td><a href="typesetting.html#kern">KERN</a></td><td>-- automatic character 
pair kerning on or off</td>
+</tr>
+<tr>
+<td><a href="inlines.html#inline-kerning-mom">\*[BU n]</a></td><td>-- move 
characters pairs closer together inline</td>
+</tr>
+<tr>
+<td><a href="inlines.html#inline-kerning-mom">\*[FU n]</a></td><td>-- move 
character pairs further apart inline</td>
+</tr>
+<tr>
+<td><a href="typesetting.html#rw">RW</a></td><td>-- uniformly reduce space 
between characters (tighten)</td>
+</tr>
+<tr>
+<td><a href="typesetting.html#ew">EW</a></td><td>-- uniformly increase space 
between characters (loosen)</td>
+</tr>
+<tr>
+<td><a href="typesetting.html#br-at-line-kern">BR_AT_LINE_KERN</a></td><td>-- 
break previous line every time RW or EW is invoked</td>
+</tr>
+<tr>
+<td><a href="typesetting.html#ligatures">LIGATURES</a></td><td>-- automatic 
generation of ligatures on or off</td>
+</tr>
+<tr>
+<td><a href="goodies.html#smartquotes">SMARTQUOTES</a></td><td>-- smartquoting 
on or off</td>
+</tr>
+</table>
+
+<table class="quick-ref">
+<tr>
+<th id="qr-9" class="quick-ref" colspan="2" >+++ Horizontal and vertical 
movements, columnar setting</th>
+</tr>
+<tr>
+<td><a href="typesetting.html#ald">ALD</a></td><td>-- move downards on the 
page</td>
+</tr>
+<tr>
+<td><a href="typesetting.html#rld">RLD</a></td><td>-- move upwards on the 
page</td>
+</tr>
+<tr>
+<td><a href="typesetting.html#space">SPACE</a></td><td>-- insert space between 
lines on a page</td>
+</tr>
+<tr>
+<td><a href="inlines.html#down">\*[DOWN n]</a></td><td>-- temporarily move 
downwards in a line</td>
+</tr>
+<tr>
+<td><a href="inlines.html#up">\*[UP n]</a></td><td>-- temporarily move upwards 
in a line</td>
+</tr>
+<tr>
+<td><a href="inlines.html#fwd">\*[FWD n]</a></td><td>-- move forward in a 
line</td>
+</tr>
+<tr>
+<td><a href="inlines.html#bck">\*[BCK n]</a></td><td>-- move backwards in a 
line</td>
+</tr>
+<tr>
+<td><a href="typesetting.html#mco">MCO</a></td><td>-- multiple columns on</td>
+</tr>
+<tr>
+<td><a href="typesetting.html#mcr">MCR</a></td><td>-- recto vertical position 
of column start</td>
+</tr>
+<tr>
+<td><a href="typesetting.html#mcx">MCX</a></td><td>-- multiple columns off, 
advance past longest column</td>
+</tr>
+</table>
+
+<table class="quick-ref">
+<tr>
+<th id="qr-10" class="quick-ref" colspan="2" >+++ Indents</th>
+</tr>
+<tr>
+<td><a href="typesetting.html#il">IL</a></td><td>-- set and turn on a left 
indent</td>
+</tr>
+<tr>
+<td><a href="typesetting.html#ir">IR</a></td><td>-- set and turn on a right 
indent</td>
+</tr>
+<tr>
+<td><a href="typesetting.html#ib">IB</a></td><td>-- set and turn on indents 
both left and right</td>
+</tr>
+<tr>
+<td><a href="typesetting.html#iq">IQ</a></td><td>-- quit (exit) all 
indents</td>
+</tr>
+<tr>
+<td><a href="typesetting.html#ti">TI</a></td><td>-- set and turn on a 
temporary (one line) indent</td>
+</tr>
+<tr>
+<td><a href="typesetting.html#hi">HI</a></td><td>-- set and turn on a hanging 
indent</td>
+</tr>
+<tr>
+<td><a href="typesetting.html#iq">ILX</a></td><td>-- left indents off</td>
+</tr>
+<tr>
+<td><a href="typesetting.html#iq">IRX</a></td><td>-- right indents off</td>
+</tr>
+<tr>
+<td><a href="typesetting.html#iq">IBX</a></td><td>-- both left and right 
indents off</td>
+</tr>
+</table>
+
+<table class="quick-ref">
+<tr>
+<th id="qr-11" class="quick-ref" colspan="2" >+++ Tabs</th>
+</tr>
+<tr>
+<td><a href="typesetting.html#tab-set">TAB_SET</a></td><td>-- set up a 
typesetting tab</td>
+</tr>
+<tr>
+<td><a href="typesetting.html#tab">TAB &lt;n&gt;</a></td><td>-- call tab 
&lt;n&gt;</td>
+</tr>
+<tr>
+<td><a href="typesetting.html#tq">TQ</a></td><td>-- quit (exit) tabs</td>
+</tr>
+<tr>
+<td><a href="typesetting.html#inline-st">\*[STn]...\*[STnX]</a></td><td>-- 
string tabs (mark tab positions inline)</td>
+</tr>
+<tr>
+<td><a href="typesetting.html#tn">TN</a></td><td>-- move to tab &lt;n+1&gt; 
without advancing on the page</td>
+</tr>
+<tr>
+<td><a href="typesetting.html#st">ST</a></td><td>-- set quad/fill for string 
tabs</td>
+</tr>
+</table>
+
+<table class="quick-ref">
+<tr>
+<th id="qr-12" class="quick-ref" colspan="2" >+++ Underscoring, 
underlining</th>
+</tr>
+<tr>
+<td><a href="goodies.html#underscore">UNDERSCORE</a></td><td>-- underscore</td>
+</tr>
+<tr>
+<td><a href="goodies.html#UNDERSCORE2">UNDERSCORE2</a></td><td>-- double 
underscore</td>
+</tr>
+<tr>
+<td><a href="goodies.html#underline">UNDERLINE</a></td><td>-- underline (fixed 
width fonts only)</td>
+</tr>
+<tr>
+<td><a href="goodies.html#ul">\*[UL]...\*[ULX]</a></td><td>-- invoke underling 
inline (fixed width fonts only)</td>
+</tr>
+</table>
+
+<table class="quick-ref">
+<tr>
+<th id="qr-13" class="quick-ref" colspan="2" >+++ Superscipts</th>
+</tr>
+<tr>
+<td><a href="goodies.html#sup">\*[SUP]...\*[SUPX]</a></td><td>-- superscript 
(inline)</td>
+</tr>
+<tr>
+<td><a href="goodies.html#sup">\*[CONDSUP]...\*[CONDSUPX]</a></td><td>-- 
pseudo-condensed superscript (inline)</td>
+</tr>
+<tr>
+<td><a href="goodies.html#sup">\*[EXTSUP]...\*[EXTSUPX]</a></td><td>-- pseudo 
extended supercript (inline)</td>
+</tr>
+<tr>
+<td><a href="goodies.html#sup-raise">SUPERSCRIPT_RAISE_AMOUNT</a></td><td>-- 
vertical offset of superscripts</td>
+</tr>
+</table>
+
+<table class="quick-ref">
+<tr>
+<th id="qr-14" class="quick-ref" colspan="2" >+++ Nested lists</th>
+</tr>
+<tr>
+<td><a href="docelement.html#list">LIST</a></td><td>-- begin a list</td>
+</tr>
+<tr>
+<td><a href="docelement.html#item">ITEM</a></td><td>-- begin an item in a 
list</td>
+</tr>
+<tr>
+<td><a href="docelement.html#shift-list">SHIFT_LIST</a></td><td>-- change the 
indent of a list</td>
+</tr>
+<tr>
+<td><a href="docelement.html#reset-list">RESET_LIST</a></td><td>-- clear and 
reset a list&#8217;s enumerator</td>
+</tr>
+<tr>
+<td><a href="docelement.html#pad-list-digits">PAD_LIST_DIGITS</a></td><td>-- 
space to leave for digits in a digit-enumerated list</td>
+</tr>
+</table>
+
+<table class="quick-ref">
+<tr>
+<th id="qr-15" class="quick-ref" colspan="2" >+++ Colour</th>
+</tr>
+<tr>
+<td><a href="color.html#newcolor">NEWCOLOR</a></td><td>-- initialize (define) 
a colour</td>
+</tr>
+<tr>
+<td><a href="color.html#color">COLOR</a></td><td>-- begin using an initialized 
colour</td>
+</tr>
+<tr>
+<td><a href="color.htmlxcolor">XCOLOR</a></td><td>-- initialize a "named" X 
colour</td>
+</tr>
+<tr>
+<td><a href="color.html#color-inline">\*[&lt;colorname&gt;]</a></td><td>-- 
begin using an initialized colour inline</td>
+</tr>
+</table>
+
+<table class="quick-ref">
+<tr>
+<th id="qr-16" class="quick-ref" colspan="2" >+++ Dropcaps</th>
+</tr>
+<tr>
+<td><a href="goodies.html#dropcap">DROPCAP</a></td><td>-- set a dropcap</td>
+</tr>
+<tr>
+<td><a href="goodies.html#dropcap-family">DROPCAP_FAMILY</a></td><td>-- set a 
dropcap&#8217;s family</td>
+</tr>
+<tr>
+<td><a href="goodies.html#dropcap-font">DROPCAP_FONT</a></td><td>-- set a 
dropcap&#8217;s font style</td>
+</tr>
+<tr>
+<td><a href="goodies.html#dropcap-color">DROPCAP_COLOR</a></td><td>-- set a 
dropcap&#8217;s colour</td>
+</tr>
+<tr>
+<td><a href="goodies.html#dropcap-adjust">DROPCAP_ADJUST</a></td><td>-- adjust 
size of a dropcap</td>
+</tr>
+<tr>
+<td><a href="goodies.html#dropcap-gutter">DROPCAP_GUTTER</a></td><td>-- adjust 
space between a dropcap and regular text</td>
+</tr>
+</table>
+
+<table class="quick-ref">
+<tr>
+<th id="qr-17" class="quick-ref" colspan="2" >+++ Utilities</th>
+</tr>
+<tr>
+<td><a href="goodies.html#alias">ALIAS</a></td><td>-- give a macro a new 
name</td>
+</tr>
+<tr>
+<td><a href="goodies.html#caps">CAPS</a></td><td>-- set type all caps</td>
+</tr>
+<tr>
+<td><a href="goodies.html#silent">COMMENT</a></td><td>-- silently embed 
comments in a document</td>
+</tr>
+<tr>
+<td><a href="goodies.html#esc-char">ESC_CHAR</a></td><td>-- change the default 
escape character</td>
+</tr>
+<tr>
+<td><a href="goodies.html#leader">\*[LEADER]</a></td><td>-- insert leaders at 
the end of a line</td>
+</tr>
+<tr>
+<td><a href="goodies.html#leader-character">LEADER_CHARACTER</a></td><td>-- 
change the character used for leaders</td>
+</tr>
+<tr>
+<td><a href="typesetting.html#newpage">NEWPAGE</a></td><td>-- break to a new 
page</td>
+</tr>
+<tr>
+<td><a href="goodies.html#pad">PAD</a></td><td>-- insert equalized regions of 
whitespace into a line</td>
+</tr>
+<tr>
+<td><a href="goodies.html#pad-marker">PAD_MARKER</a></td><td>-- change the pad 
marker</td>
+</tr>
+<tr>
+<td><a href="inlines.html#inline-rule-mom">\*[RULE]</a></td><td>-- draw a full 
measure rule</td>
+</tr>
+<tr>
+<td><a href="goodies.html#sizespecs">SIZESPECS</a></td><td>-- get font's 
cap-height, x-height and descender depth</td>
+</tr>
+<tr>
+<td><a href="goodies.html#silent">SILENT</a></td><td>-- output processing off 
or on</td>
+</tr>
+<tr>
+<td><a href="goodies.html#trap">TRAP</a></td><td>-- enable or disable page 
position traps</td>
+</tr>
+</table>
+
+<table class="quick-ref">
+<tr>
+<th id="qr-18" class="quick-ref" colspan="2" >+++ Graphical objects</th>
+</tr>
+<tr>
+<td><a href="graphical.html#drh">DRH</a></td><td>-- draw a horizontal rule</td>
+</tr>
+<tr>
+<td><a href="graphical.html#drv">DRV</a></td><td>-- draw a vertical rule</td>
+</tr>
+<tr>
+<td><a href="graphical.html#dbx">DBX</a></td><td>-- draw a box</td>
+</tr>
+<tr>
+<td><a href="graphical.html#dcl">DCL</a></td><td>-- draw a circle 
(ellipse)</td>
+</tr>
+<tr>
+<td><a href="inlines.html#rule-weight">RULE_WEIGHT</a></td><td>-- set weight 
of rules drawn with \*[RULE]</td>
+</tr>
+<tr>
+<td><a href="docelement.html#pspic">PSPIC</a></td><td>-- insert a PostScript 
image</td>
+</tr>
+</table>
+
+<div style="display: inline-block; margin-top: 1em; margin-bottom: .5em; 
border-bottom: 2px solid #302419;"><kbd>DOCUMENT PROCESSING MACROS</kbd></div>
+
+<table class="quick-ref">
+<tr>
+<th id="qr-19" class="quick-ref" colspan="2" >+++ Reference macros</th>
+</tr>
+<tr>
+<td><a href="docprocessing.html#title">TITLE</a></td><td>-- document title</td>
+</tr>
+<tr>
+<td><a href="docprocessing.html#doctitle">DOCTITLE</a></td><td>-- overall 
document title (if different from TITLE)</td>
+</tr>
+<tr>
+<td><a href="docelement.html#endnote-title">ENDNOTE_TITLE</a></td><td>-- 
document/chapter identification string for endnotes</td>
+</tr>
+<tr>
+<td><a href="docprocessing.html#chapter">CHAPTER</a></td><td>-- chapter 
number</td>
+</tr>
+<tr>
+<td><a href="docprocessing.html#chapter">CHAPTER_TITLE</a></td><td>-- chapter 
title</td>
+</tr>
+<tr>
+<td><a href="docprocessing.html#draft-string">CHAPTER_STRING</a></td><td>-- 
what to use in place of &#8220;Chapter&#8221;</td>
+</tr>
+<tr>
+<td><a href="docprocessing.html#subtitle">SUBTITLE</a></td><td>-- document 
subtitle</td>
+</tr>
+<tr>
+<td><a href="docprocessing.html#author">AUTHOR</a></td><td>-- document 
author(s)</td>
+</tr>
+<tr>
+<td><a href="docprocessing.html#covertitle">DOC_COVERTITLE</a></td><td>-- 
document title cover</td>
+</tr>
+<tr>
+<td><a href="docprocessing.html#covertitle">COVERTITLE</a></td><td>-- section 
cover title</td>
+</tr>
+<tr>
+<td><a href="docprocessing.html#covertitle">COPYRIGHT</a></td><td>-- 
copyright</td>
+</tr>
+<tr>
+<td><a href="docprocessing.html#covertitle">MISC</a></td><td>-- miscellaneous 
cover information</td>
+</tr>
+<tr>
+<td><a href="docprocessing.html#draft">DRAFT</a></td><td>-- document&#8217;s 
draft number</td>
+</tr>
+<tr>
+<td><a href="docprocessing.html#draft-string">DRAFT_STRING</a></td><td>-- what 
to use in place of &#8220;Draft&#8221;</td>
+</tr>
+<tr>
+<td><a href="docprocessing.html#revision">REVISION</a></td><td>-- 
document&#8217;s revision number</td>
+</tr>
+<tr>
+<td><a 
href="docprocessing.html#revision-string">REVISION_STRING</a></td><td>-- what 
to use in place of &#8220;Revision&#8221;</td>
+</tr>
+</table>
+
+<table class="quick-ref">
+<tr>
+<th id="qr-20" class="quick-ref" colspan="2" >+++ General document formatting 
directives</th>
+</tr>
+<tr>
+<td><a href="docprocessing.html#doctype">DOCTYPE</a></td><td>-- general 
document type</td>
+</tr>
+<tr>
+<td><a href="docprocessing.html#copystyle">COPYSTYLE</a></td><td>-- draft or 
final copy</td>
+</tr>
+<tr>
+<td><a href="docprocessing.html#printstyle">PRINTSTYLE</a></td><td>-- typeset 
or &#8220;typewritten&#8221;</td>
+</tr>
+</table>
+
+<table class="quick-ref">
+<tr>
+<th id="qr-21" class="quick-ref" colspan="2" >+++ Line numbering</th>
+</tr>
+<tr>
+<td><a href="docelement.html#number-lines">NUMBER_LINES</a></td><td>-- 
automatic line numbering on or off</td>
+</tr>
+<tr>
+<td><a href="docelement.html#number-lines-control">Control macros</a></td>
+</tr>
+<tr>
+<td><a 
href="docelement.html#number-quote-lines">&nbsp;NUMBER_QUOTE_LINES</a></td><td>--
 numbering of QUOTE lines on or off</td>
+</tr>
+<tr>
+<td><a 
href="docelement.html#number-blockquote-lines">&nbsp;NUMBER_BLOCKQUOTE_LINES</a></td><td>--
 numbering of BLOCKQUOTE lines on or off</td>
+</tr>
+</table>
+
+<table class="quick-ref">
+<tr>
+<th id="qr-22" class="quick-ref" colspan="2" >+++ Set documents in columns</th>
+</tr>
+<tr>
+<td><a href="docprocessing.html#columns">COLUMNS</a></td>
+</tr>
+<tr>
+<td><a href="docprocessing.html#col-next">COL_NEXT</a></td>
+</tr>
+<tr>
+<td><a href="docprocessing.html#col-break">COL_BREAK</a></td>
+</tr>
+</table>
+
+<table class="quick-ref">
+<tr>
+<th id="qr-23" class="quick-ref" colspan="2" >+++ TYPEWRITE control macros</th>
+</tr>
+<tr>
+<td><a 
href="docprocessing.html#typewrite-control">UNDERLINE_ITALIC</a></td><td>--  
underlining of italics on</td>
+</tr>
+<tr>
+<td><a 
href="docprocessing.html#underline-quotes">UNDERLINE_QUOTES</a></td><td>--  
underlining of QUOTEs on or off</td>
+</tr>
+<tr>
+<td><a 
href="docprocessing.html#typewrite-control">ITALIC_MEANS_ITALIC</a></td><td>--  
use real italics (not underlining)</td>
+</tr>
+<tr>
+<td><a 
href="docprocessing.html#typewrite-control">UNDERLINE_SLANT</a></td><td>--  
underlining of pseudo-italics on</td>
+</tr>
+<tr>
+<td><a 
href="docprocessing.html#typewrite-control">SLANT_MEANS_SLANT</a></td><td>--  
use pseudo italics (not underlining)</td>
+</tr>
+</table>
+
+<table class="quick-ref">
+<tr>
+<th id="qr-24" class="quick-ref" colspan="2" >+++ Initiate document 
processing</th>
+</tr>
+<tr>
+<td><a href="docprocessing.html#start">START</a></td><td>-- begin document 
processing</td>
+</tr>
+</table>
+
+<table class="quick-ref">
+<tr>
+<th id="qr-25" class="quick-ref" colspan="2" >+++ Epigraphs</th>
+</tr>
+<tr>
+<td><a href="docelement.html#epigraph">EPIGRAPH</a></td><td>-- set an epigraph 
underneath the docheader</td>
+</tr>
+<tr>
+<td><a href="docelement.html#epigraph-control">Control macros</a></td><td>-- 
change default style of epigraphs</td>
+</tr>
+</table>
+
+<table class="quick-ref">
+<tr>
+<th id="qr-26" class="quick-ref" colspan="2" >+++ Main heads</th>
+</tr>
+<tr>
+<td><a href="docelement.html#head">HEAD</a></td><td>-- set a main head</td>
+</tr>
+<tr>
+<td><a href="docelement.html#head-general">Control macros</a></td><td>-- 
change default style of heads</td>
+</tr>
+<tr>
+<td><a href="docelement.html#head-space">&nbsp;HEAD_SPACE</a></td><td>-- 
control vertical space around heads</td>
+</tr>
+<tr>
+<td><a href="docelement.html#number-heads">&nbsp;NUMBER_HEADS</a></td><td>-- 
number heads</td>
+</tr>
+<tr>
+<td><a 
href="docelement.html#prefix-chapter-number">&nbsp;PREFIX_CHAPTER_NUMBER</a></td><td>--
 prefix chapter number to head numbers</td>
+</tr>
+<tr>
+<td><a 
href="docelement.html#reset-head-number">&nbsp;RESET_HEAD_NUMBER</a></td><td>-- 
reset head number to "1"</td>
+</tr>
+</table>
+
+<table class="quick-ref">
+<tr>
+<th id="qr-27" class="quick-ref" colspan="2" >+++ Subheads</th>
+</tr>
+<tr>
+<td><a href="docelement.html#subhead">SUBHEAD</a></td><td>-- set a subhead</td>
+</tr>
+<tr>
+<td><a href="docelement.html#subhead-general">Control macros</a></td><td>-- 
change default style of subheads</td>
+</tr>
+<tr>
+<td><a 
href="docelement.html#number-subheads">&nbsp;NUMBER_SUBHEADS</a></td><td>-- 
number subheads</td>
+</tr>
+<tr>
+<td><a 
href="docelement.html#prefix-chapter-number">&nbsp;PREFIX_CHAPTER_NUMBER</a></td><td>--
 prefix chapter number to subhead numbers</td>
+</tr>
+<tr>
+<td><a 
href="docelement.html#reset-subhead-number">&nbsp;RESET_SUBHEAD_NUMBER</a></td><td>--
 reset subhead number to "1"</td>
+</tr>
+</table>
+
+<table class="quick-ref">
+<tr>
+<th id="qr-28" class="quick-ref" colspan="2" >+++ Paragraph heads</th>
+</tr>
+<tr>
+<td><a href="docelement.html#parahead">PARAHEAD</a></td><td>-- set a paragraph 
head</td>
+</tr>
+<tr>
+<td><a href="docelement.html#parahead-general">Control macros</a></td><td>-- 
change default style of paraheads</td>
+</tr>
+<tr>
+<td><a 
href="docelement.html#number-paraheads">&nbsp;NUMBER_PARAHEADS</a></td><td>-- 
number paraheads</td>
+</tr>
+<tr>
+<td><a 
href="docelement.html#prefix-chapter-number">&nbsp;PREFIX_CHAPTER_NUMBER</a></td><td>--
 prefix chapter number to parahead numbers</td>
+</tr>
+<tr>
+<td><a 
href="docelement.html#reset-parahead-number">&nbsp;RESET_PARAHEAD_NUMBER</a></td><td>--
 reset parahead number to "1"</td>
+</tr>
+</table>
+
+<table class="quick-ref">
+<tr>
+<th id="qr-29" class="quick-ref" colspan="2" >+++ Paragraphs</th>
+</tr>
+<tr>
+<td><a href="docelement.html#pp">PP</a></td><td>-- set a paragraph</td>
+</tr>
+<tr>
+<td><a href="docelement.html#pp-control">Control macros</a></td><td>-- 
managing paragraph style concerns</td>
+</tr>
+<tr>
+<td><a href="docelement.html#pp-font">&nbsp;PP_FONT</a></td><td>-- globally 
change font of regular paragraphs</td>
+</tr>
+<tr>
+<td><a href="docelement.html#para-indent">&nbsp;PARA_INDENT</a></td><td>-- set 
the paragraph first-line indent</td>
+</tr>
+<tr>
+<td><a 
href="docelement.html#indent-first-paras">&nbsp;INDENT_FIRST_PARAS</a></td><td>--
 indenting of paragraph first-lines on or off</td>
+</tr>
+<tr>
+<td><a href="docelement.html#pp-space">&nbsp;PARA_SPACE</a></td><td>-- 
linespace between paragraphs on or off</td>
+</tr>
+</table>
+
+<table class="quick-ref">
+<tr>
+<th id="qr-30" class="quick-ref" colspan="2" >+++ Quotes (line for line 
verbatim quotes)</th>
+</tr>
+<tr>
+<td><a href="docelement.html#quote">QUOTE</a></td><td>-- set quoted text line 
for line </td>
+</tr>
+<tr>
+<td><a href="docelement.html#quote-general">Control macros</a></td><td>-- 
change default style of quotes</td>
+</tr>
+<tr>
+<td><a 
href="docelement.html#always-fullspace-quotes">&nbsp;ALWAYS_FULLSPACE_QUOTES</a></td><td>--
 control vertical space around quotes</td>
+</tr>
+<tr>
+<td><a href="docelement.html#break-quote">&nbsp;BREAK_QUOTE</a></td><td>-- 
deprecated</td>
+</tr>
+</table>
+
+<table class="quick-ref">
+<tr>
+<th id="qr-31" class="quick-ref" colspan="2" >+++ Blockquotes (cited passages 
of text)</th>
+</tr>
+<tr>
+<td><a href="docelement.html#blockquote">BLOCKQUOTE</a></td><td>-- set longer 
passages of cited text</td>
+</tr>
+<tr>
+<td><a href="docelement.html#blockquote-general">Control macros</a></td><td>-- 
change default style of blockquotes</td>
+</tr>
+<tr>
+<td><a 
href="docelement.html#always-fullspace-quotes">&nbsp;ALWAYS_FULLSPACE_BLOCKQUOTES</a></td><td>--
 control vertical space around quotes</td>
+</tr>
+<tr>
+<td><a 
href="docelement.html#break-quote">&nbsp;BREAK_BLOCKQUOTE</a></td><td>-- 
deprecated</td>
+</tr>
+</table>
+
+<table class="quick-ref">
+<tr>
+<th id="qr-32" class="quick-ref" colspan="2" >+++ Code snippets</th>
+</tr>
+<tr>
+<td><a href="docelement.html#code">CODE</a></td><td>-- set a code snippet</td>
+</tr>
+<tr>
+<td><a href="docelement.html#code-control">Control macros</a></td><td>-- 
change default style of code snippets</td>
+</tr>
+<tr>
+<td><a href="docelement.html#code-general">&nbsp;General</a></td><td>-- 
family, font, and colour</td>
+</tr>
+<tr>
+<td><a href="docelement.html#code-size">&nbsp;CODE_SIZE</a></td><td>-- code 
size as a percentage of prevailing text</td>
+</tr>
+</table>
+
+<table class="quick-ref">
+<tr>
+<th id="qr-33" class="quick-ref" colspan="2" >+++ Author linebreaks (section 
breaks)</th>
+</tr>
+<tr>
+<td><a href="docelement.html#linebreak">LINEBREAK</a></td><td>-- insert an 
author linebreak (section break)</td>
+</tr>
+<tr>
+<td><a href="docelement.html#linebreak-control">Control macros</a></td><td>-- 
change default style of linebreaks</td>
+</tr>
+<tr>
+<td><a 
href="docelement.html#linebreak-char">&nbsp;LINEBREAK_CHAR</a></td><td>-- 
character to use for author linebreaks</td>
+</tr>
+<tr>
+<td><a 
href="docelement.html#linebreak-color">&nbsp;LINEBREAK_COLOR</a></td><td>-- 
colour of author linebreak character</td>
+</tr>
+</table>
+
+<table class="quick-ref">
+<tr>
+<th id="qr-34" class="quick-ref" colspan="2" >+++ Document termination 
string</th>
+</tr>
+<tr>
+<td><a href="docelement.html#finis">FINIS</a></td><td>-- insert a document 
termination string (e.g. --END--)</td>
+</tr>
+<tr>
+<td><a href="docelement.html#finis-control">Control macros</a></td><td>-- 
change default style finis string</td>
+</tr>
+<tr>
+<td><a href="docelement.html#finis-string">&nbsp;FINIS_STRING</a></td><td>-- 
set the document termination string</td>
+</tr>
+<tr>
+<td><a href="docelement.html#finis-color">&nbsp;FINIS_COLOR</a></td><td>-- set 
the document termination string colour</td>
+</tr>
+</table>
+
+<table class="quick-ref">
+<tr>
+<th id="qr-35" class="quick-ref" colspan="2" >+++ Footnotes</th>
+</tr>
+<tr>
+<td><a href="docelement.html#footnote">FOOTNOTE</a></td><td>-- set a 
footnote</td>
+</tr>
+<tr>
+<td><a href="docelement.html#footnote-general">Control macros</a></td><td>-- 
change default style of footnotes</td>
+</tr>
+<tr>
+<td><a 
href="docelement.html#footnote-markers">&nbsp;FOOTNOTE_MARKERS</a></td><td>-- 
footnote markers on or off</td>
+</tr>
+<tr>
+<td><a 
href="docelement.html#footnote-marker-style">&nbsp;FOOTNOTE_MARKER_STYLE</a></td><td>--
 type of footnote marker to use</td>
+</tr>
+<tr>
+<td><a 
href="docelement.html#reset-footnote-number">&nbsp;RESET_FOOTNOTE_NUMBER</a></td><td>--
 reset footnote numbering</td>
+</tr>
+<tr>
+<td><a href="docelement.html#footnote-rule">&nbsp;FOOTNOTE_RULE</a></td><td>-- 
footnote separator rule on or off</td>
+</tr>
+<tr>
+<td><a 
href="docelement.html#footnote-rule-adj">&nbsp;FOOTNOTE_RULE_ADJ</a></td><td>-- 
adjust vertical position of footnote rule</td>
+</tr>
+<tr>
+<td><a 
href="docelement.html#footnote-rule-length">&nbsp;FOOTNOTE_RULE_LENGTH</a></td><td>--
 adjust length of footnote rule</td>
+</tr>
+<tr>
+<td style="vertical-align: top;"><a 
href="docelement.html#footnotes-run-on">&nbsp;FOOTNOTES_RUN_ON</a></td>
+  <td>-- instruct footnotes to be continuous (i.e. not to<br />
+&nbsp;&nbsp;&nbsp;begin on a new line; only for use with footnotes<br />
+&nbsp;&nbsp;&nbsp;identified by document line number)</td>
+</tr>
+</table>
+
+<table class="quick-ref">
+<tr>
+<th id="qr-36" class="quick-ref" colspan="2" >+++ Endnotes</th>
+</tr>
+<tr>
+<td><a href="docelement.html#endnote">ENDNOTE</a></td><td>-- set an 
endnote</td>
+</tr>
+<tr>
+<td style="vertical-align: top;"><a 
href="docelement.html#EN-mark">\*[EN-MARK]</a></td>
+  <td>-- mark initial line of a range of line numbers<br />
+&nbsp;&nbsp;&nbsp;(for use with line numbered endnotes)</td>
+</tr>
+<tr>
+<td><a href="docelement.html#endnotes">ENDNOTES</a></td><td>-- output 
endnotes</td>
+</tr>
+<tr>
+<td><a href="docelement.html#endnote-control">Control macros</a></td><td>-- 
change just about anything to do with endnotes</td>
+</tr>
+</table>
+
+<table class="quick-ref" style="margin-top: -.5em; margin-left: 1em;">
+<tr>
+<td><a href="docelement.html#endnotes-general">General style control</a></td>
+</tr>
+<tr>
+<td><a href="docelement.html#endnotes-pagination">Pagination</a></td>
+</tr>
+<tr>
+<td><a href="docelement.html#endnotes-header-control">Header/footer 
control</a></td>
+</tr>
+<tr>
+<td><a href="docelement.html#endnotes-main-title">Title control</a></td>
+</tr>
+<tr>
+<td><a href="docelement.html#endnotes-main-title">Document/section 
identification control</a></td>
+</tr>
+<tr>
+<td><a href="docelement.html#endnotes-numbering">Identification style</a></td>
+</tr>
+</table>
+
+<table class="quick-ref">
+<tr>
+<th id="qr-37" class="quick-ref" colspan="2" >+++ Margin notes</th>
+</tr>
+<tr>
+<td><a href="docelement.html#mn-init">MN_INIT</a></td><td>-- initialize margin 
notes</td>
+</tr>
+<tr>
+<td><a href="docelement.html#mn">MN</a></td><td>-- set a margin note</td>
+</tr>
+</table>
+
+<table class="quick-ref">
+<tr>
+<th id="qr-38" class="quick-ref" colspan="2" >+++ Bibliographic references</th>
+</tr>
+<tr>
+<td><a href="refer.html#ref">REF</a></td><td>-- begin a reference</td>
+</tr>
+<tr>
+<td><a href="refer.html#footnote-refs">FOOTNOTE_REFS</a></td><td>-- place 
references in footnotes</td>
+</tr>
+<tr>
+<td><a href="refer.html#endnote-refs">ENDNOTE_REFS</a></td><td>-- place 
references in endnotes</td>
+</tr>
+<tr>
+<td><a href="refer.html#bracket-refs">REF( / REF)</a></td><td>-- put 
parentheses around embedded references</td>
+</tr>
+<tr>
+<td><a href="refer.html#bracket-refs">REF[ / REF]</a></td><td>-- put square 
brackets around embedded references</td>
+</tr>
+<tr>
+<td><a href="refer.html#bracket-refs">REF{ / REF}</a></td><td>-- put curly 
braces around mbedded references</td>
+</tr>
+<tr>
+<td><a href="refer.html#bibliography">BIBLIOGRAPHY</a></td><td>-- output a 
bibliography</td>
+</tr>
+<tr>
+<td><a href="refer.html#biblio-control">Control macros</a></td><td>-- change 
just about anything to do with bibliographies</td>
+</tr>
+</table>
+
+<table class="quick-ref" style="margin-top: -.5em; margin-left: 1em;">
+<tr>
+<td><a href="refer.html#bibliography-type">BIBLIOGRAPHY_TYPE</a>&nbsp;-- 
"plain" or enumerated list</td>
+</tr>
+<tr>
+<td><a href="refer.html#biblio-general">General style control</a></td>
+</tr>
+<tr>
+<td><a href="refer.html#biblio-header-control">Header/footer control</a></td>
+</tr>
+<tr>
+<td><a href="refer.html#biblio-main-title">Main head control</a></td>
+</tr>
+</table>
+
+<table class="quick-ref">
+<tr>
+<th id="qr-39" class="quick-ref" colspan="2" >+++ Tables of contents</th>
+</tr>
+<tr>
+<td><a href="docelement.html#toc">TOC</a></td><td>-- output a table of 
contents</td>
+</tr>
+<tr>
+<td><a href="docelement.html#toc-control">Control macros</a></td><td>-- change 
just about anything to do with tables of contents</td>
+</tr>
+</table>
+
+<table class="quick-ref" style="margin-top: -.5em; margin-left: 1em;">
+<tr>
+<td><a href="docelement.html#toc-general">General style control</a></td>
+</tr>
+<tr>
+<td><a href="docelement.html#toc-pagenumbering">Page numbering</a></td>
+</tr>
+<tr>
+<td><a href="docelement.html#toc-header">Title control</a></td>
+</tr>
+<tr>
+<td><a href="docelement.html#toc-style">Changing the style of the different 
table of contents entry types</a></td>
+</tr>
+<tr>
+<td><a href="docelement.html#toc-additional">Additional table of contents 
control macros</a></td>
+</tr>
+</table>
+
+<table class="quick-ref">
+<tr>
+<th id="qr-40" class="quick-ref" colspan="2" >+++ Letter (correspondence) 
macros</th>
+</tr>
+<tr>
+<td><a href="letters.html#date">DATE</a></td><td>-- letter&#8217;s date</td>
+</tr>
+<tr>
+<td><a href="letters.html#from">FROM</a></td><td>-- letter&#8217;s 
addresser</td>
+</tr>
+<tr>
+<td><a href="letters.html#to">TO</a></td><td>-- letter&#8217;s addressee</td>
+</tr>
+<tr>
+<td><a href="letters.html#greeting">GREETING</a></td><td>-- letter&#8217;s 
salutation</td>
+</tr>
+<tr>
+<td><a href="letters.html#closing">CLOSING</a></td><td>-- letter&#8217;s 
closing salutation</td>
+</tr>
+<tr>
+<td><a href="letters.html#closing-indent">CLOSING_INDENT</a></td><td>-- 
indentation of the closing salutation</td>
+</tr>
+<tr>
+<td><a href="letters.html#signature-space">SIGNATURE_SPACE</a></td><td>-- room 
to leave for the signature</td>
+</tr>
+<tr>
+<td><a href="letters.html#no-suite">NO_SUITE</a></td><td>-- printing of 
&quot;next page number&quot; off or on</td>
+</tr>
+</table>
+
+<table class="quick-ref">
+<tr>
+<th id="qr-41" class="quick-ref" colspan="2" >+++ Changing global print style 
parameters after START</th>
+</tr>
+<tr>
+<td><a 
href="docprocessing.html#doc-left-margin">DOC_LEFT_MARGIN</a></td><td>-- left 
margin of everything on the page</td>
+</tr>
+<tr>
+<td><a 
href="docprocessing.html#doc-right-margin">DOC_RIGHT_MARGIN</a></td><td>-- 
right margin of everything on the page</td>
+</tr>
+<tr>
+<td><a 
href="docprocessing.html#doc-line-length">DOC_LINE_LENGTH</a></td><td>-- 
document&#8217;s base line length</td>
+</tr>
+<tr>
+<td><a href="docprocessing.html#doc-family">DOC_FAMILY</a></td><td>-- 
document&#8217;s base family</td>
+</tr>
+<tr>
+<td><a href="docprocessing.html#doc-pt-size">DOC_PT_SIZE</a></td><td>-- 
document&#8217;s base point size</td>
+</tr>
+<tr>
+<td><a href="docprocessing.html#doc-lead">DOC_LEAD</a></td><td>-- 
document&#8217;s base lead</td>
+</tr>
+<tr>
+<td><a href="docprocessing.html#doc-quad">DOC_QUAD</a></td><td>-- 
document&#8217;s base quad directions</td>
+</tr>
+</table>
+
+<table class="quick-ref">
+<tr>
+<th id="qr-42" class="quick-ref" colspan="2" >+++ Managing a document&#8217;s 
first-page header</th>
+</tr>
+<tr>
+<td><a href="docprocessing.html#docheader">DOCHEADER</a></td><td>-- document 
first-page header on or off</td>
+</tr>
+<tr>
+<td><a href="docprocessing.html#docheader-control-index">Control 
macros</a></td><td>-- change default style of docheader elements</td>
+</tr>
+</table>
+
+<table class="quick-ref">
+<tr>
+<th id="qr-43" class="quick-ref" colspan="2" >+++ Managing page headers and 
footers</th>
+</tr>
+<tr>
+<td><a href="headfootpage.html#headers">HEADERS</a></td><td>-- page headers on 
or off</td>
+</tr>
+<tr>
+<td><a href="headfootpage.html#footers">FOOTERS</a></td><td>-- page footers on 
or off</td>
+</tr>
+<tr>
+<td style="vertical-align: top;"><a 
href="headfootpage.html#headers-and-footers">HEADERS_AND_FOOTERS</a></td><td>-- 
enable generation of both headers and footers</td>
+</tr>
+<tr>
+<td><a href="headfootpage.html#index-reference">Control macros</a></td>
+</tr>
+</table>
+
+<table class="quick-ref" style="margin-top: -.5em; margin-left: 1em;">
+<tr>
+<td><a href="headfootpage.html#strings">Strings</a></td><td>-- 
left-right-center strings</td>
+</tr>
+<tr>
+<td><a href="headfootpage.html#style">Style</a></td><td>-- change style 
defaults for headers and/or footers</td>
+</tr>
+<tr>
+<td><a href="headfootpage.html#global">Global</a></td><td>-- global style 
changes</td>
+</tr>
+<tr>
+<td><a href="headfootpage.html#part-by-part">Part-by-part</a></td><td>-- 
part-by-part style changes</td>
+</tr>
+<tr>
+<td><a href="headfootpage.html#vertical">Vertical placement</a></td><td>-- 
adjust postion of headers and/or footers</td>
+</tr>
+<tr>
+<td><a href="headfootpage.html#separator-rule">Separator rule</a></td><td>-- 
manage the header/footer separator rule</td>
+</tr>
+</table>
+
+<table class="quick-ref">
+<tr>
+<th id="qr-44" class="quick-ref" colspan="2" >+++ Recto/verso page headers and 
footers</th>
+</tr>
+<tr>
+<td><a href="rectoverso.html#recto-verso">RECTO_VERSO</a></td><td>-- 
recto/verso headers and/or footers on or off</td>
+</tr>
+<tr>
+<td><a href="rectoverso.html#switch-hdrftr">SWITCH_HEADERS</a></td><td>-- 
switch recto or verso header</td>
+</tr>
+<tr>
+<td><a href="rectoverso.html#switch-hdrftr">SWITCH_FOOTERS</a></td><td>-- 
switch recto or verso footer</td>
+</tr>
+<tr>
+<td><a href="headfootpage.html#hdrftr-rectoverso">HEADER_RECTO</a></td><td>-- 
string that constitutes a recto header</td>
+</tr>
+<tr>
+<td><a href="headfootpage.html#hdrftr-rectoverso">HEADER_VERSO</a></td><td>-- 
string that constitutes a verso header</td>
+</tr>
+<tr>
+<td><a href="headfootpage.html#hdrftr-rectoverso">FOOTER_RECTO</a></td><td>-- 
string that constitutes a recto footer</td>
+</tr>
+<tr>
+<td><a href="headfootpage.html#hdrftr-rectoverso">FOOTER_VERSO</a></td><td>-- 
string that constitutes a recto footer</td>
+</tr>
+</table>
+
+<table class="quick-ref">
+<tr>
+<th id="qr-45" class="quick-ref" colspan="2" >+++ Pagination</th>
+</tr>
+<tr>
+<td><a href="headfootpage.html#paginate">PAGINATE</a></td><td>-- pagination on 
or off</td>
+</tr>
+<tr>
+<td><a href="headfootpage.html#paginate-control">Control macros</a></td><td>-- 
change default style for pagination</td>
+</tr>
+<tr>
+<td><a href="headfootpage.html#pagenumber">&nbsp;PAGENUMBER</a></td><td>-- 
user-defined (starting) page number</td>
+</tr>
+<tr>
+<td><a 
href="headfootpage.html#pagenum-style">&nbsp;PAGENUM_STYLE</a></td><td>-- 
digits, roman numerals, etc</td>
+</tr>
+<tr>
+<td><a 
href="headfootpage.html#pagenum-on-first-page">&nbsp;PAGENUM_ON_FIRST_PAGE</a></td><td>--
 when footers are enabled</td>
+</tr>
+<tr>
+<td style="vertical-align: top;"><a 
href="headfootpage.html#draft-with-pagenumber">&nbsp;DRAFT_WITH_PAGENUMBER</a></td><td>--
 attach draft/revision information to page<br />
+&nbsp;&nbsp;&nbsp;numbers</td>
+</tr>
+</table>
+
+<table class="quick-ref">
+<tr>
+<th id="qr-46" class="quick-ref" colspan="2" >+++ Document and section cover 
(title) pages</th>
+</tr>
+<tr>
+<td><a href="cover.html#cover">COVER</a></td><td>-- information to include in 
a section cover</td>
+</tr>
+<tr>
+<td><a href="cover.html#cover">DOC_COVER</a></td><td>-- information to include 
in a document cover</td>
+</tr>
+<tr>
+<td><a href="cover.html#on-off">COVERS</a></td><td>-- printing of section 
covers on or off</td>
+</tr>
+<tr>
+<td><a href="cover.html#on-off">DOC_COVERS</a></td><td>-- printing of document 
covers on or off</td>
+</tr>
+<tr>
+<td><a href="cover.html#cover-control-index">Control macros</a></td><td>-- 
change style defaults for covers</td>
+</tr>
+</table>
+
+<table class="quick-ref">
+<tr>
+<th id="qr-47" class="quick-ref" colspan="2" >+++ Utilities</th>
+</tr>
+<tr>
+<td><a href="docprocessing.html#add-space">ADD_SPACE</a></td><td>-- add space 
to the top of a page</td>
+</tr>
+<tr>
+<td><a href="docelement.html#blank-page">BLANKPAGE</a></td><td>-- output one 
or more blank pages</td>
+</tr>
+<tr>
+<td><a 
href="docprocessing.html#doc-lead-adjust">DOC_LEAD_ADJUST</a></td><td>-- adjust 
document linespacing (lead) to fill pages</td>
+</tr>
+<tr>
+<td><a href="rectoverso.html#collate">COLLATE</a></td><td>-- join documents or 
chapters of a document together</td>
+</tr>
+<tr>
+<td><a href="docprocessing.html#shim">SHIM</a></td><td>-- move vertical 
position to next valid baseline</td>
+</tr>
+</table>
+
+<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="appendices.html">Next: 
Appendices</a></td>
+</tr>
+</table>
+
+</div>
+
+<div class="bottom-spacer"><br/></div>
+
+</body>
+</html>
+<!-- vim: fileencoding=utf-8: nomodified: -->

Index: rectoverso.html
===================================================================
RCS file: rectoverso.html
diff -N rectoverso.html
--- /dev/null   1 Jan 1970 00:00:00 -0000
+++ rectoverso.html     18 Aug 2010 22:45:36 -0000      1.14
@@ -0,0 +1,339 @@
+<?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 -- Recto/verso printing, collating</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="cover.html#top">Next: Cover 
pages</a></td>
+</tr>
+</table>
+
+<h1 class="docs">Recto/verso printing, collating</h1>
+
+<div style="width: 37%; margin: auto;">
+<ul class="no-enumerator" style="margin-left: -1em;">
+  <li><a href="#rectoverso-intro">Introduction to recto/verso printing</a>
+  <ul style="margin-left: -.5em; list-style-type: disc;">
+    <li><a href="#rectoverso-list">Macro list</a></li>
+  </ul></li>
+  <li><a href="#collate-intro">Introduction to collating</a>
+  <ul style="margin-left: -.5em; list-style-type: disc;">
+    <li><a href="#collate">The COLLATE macro</a></li>
+  </ul></li>
+</ul>
+</div>
+
+<div class="rule-medium"><hr/></div>
+
+<h2 id="rectoverso-intro" class="docs">Introduction to recto/verso 
printing</h2>
+
+<p>
+Recto/verso printing allows you to set up a mom document in such
+a way that it can be printed on both sides of a printer sheet and
+subsequently bound.
+</p>
+
+<p>
+With recto/verso, mom automatically takes control of the following
+aspects of alternating page layout:
+</p>
+<ul style="margin-top: -.5em; margin-left: -.5em; margin-bottom: -.5em;">
+  <li>switching left and right margins (if they&#8217;re not equal)</li>
+  <li>switching the left and right parts of the default 3-part
+      <a href="definitions.html#header">headers</a>
+      or
+      <a href="definitions.html#footer">footers</a>
+      (see the
+      <a href="headfootpage.html#description-general">General description of 
headers</a>)
+  </li>
+  <li>switching
+      <a href="headfootpage.html#hdrftr-rectoverso">HEADER_RECTO</a>
+      and
+      <a href="headfootpage.html#hdrftr-rectoverso">HEADER_VERSO</a>
+      if user-defined, single string recto/verso headers
+      or footers are used in place of the default 3-part
+      headers or footers
+  </li>
+  <li>switching the page number position (if page numbers are not centred)</li>
+</ul>
+
+<p>
+It is beyond the scope of this documentation to cover the different
+ways in which you can make your printer print on both sides of
+a sheet.  A simple but effective method for those of us with
+&#8220;dumb&#8221; printers is to open the document (after
+it&#8217;s been processed into PostScript by groff&mdash;see
+<a href="using.html#using-invoking">How to invoke groff with mom</a>)
+in <b>gv</b> (ghostview), click the &#8220;odd pages&#8221; icon,
+then click &#8220;Print Marked&#8220;.  After printing is complete,
+rearrange the sheets appropriately, put them back in your printer,
+and have <b>gv</b> print the &#8220;even pages&#8220;.  If you
+prefer to work from the command line, check out the man pages for
+<kbd>pstops</kbd> and <kbd>psbook</kbd>.  There are other programs
+out there as well to help with two-sided printing.
+</p>
+
+<div class="macro-list-container">
+<h3 id="rectoverso-list" class="macro-list">Recto/verso macros</h3>
+<ul class="macro-list">
+  <li><a href="#recto-verso">RECTO_VERSO</a></li>
+  <li><a href="#switch-hdrftr">SWITCH_HEADERS (also FOOTERS)</a>
+      &ndash; switch starting position of the header parts (left and right)
+  </li>
+</ul>
+</div>
+
+<!-- -RECTO_VERSO- -->
+
+<div id="recto-verso" class="box-macro-args">
+Macro: <b>RECTO_VERSO</b>
+</div>
+
+<p>
+If you want mom to set up alternating pages for recto/verso
+printing, simply invoke RECTO_VERSO, with no argument, anywhere in
+your document (most likely before
+<a href="docprocessing.html#start">START</a>).
+</p>
+
+<div class="box-tip">
+<p class="tip-top">
+<span class="note">Note:</span>
+Recto/verso always switches the left and right parts of
+<a href="definitions.html#header">headers</a>
+or
+<a href="definitions.html#footer">footers</a>
+on odd/even pages.  However, it only switches the left and right
+margins if the margins aren&#8217;t equal.  Consequently, it is
+your responsibility to set the appropriate differing left and right
+margins with
+<a href="typesetting.html#l-margin">L_MARGIN</a>
+and
+<a href="typesetting.html#r-margin">R_MARGIN</a>
+(prior to
+<a href="docprocessing.html#start">START</a>)
+or with
+<a href="docprocessing.html#doc-left-margin">DOC_LEFT_MARGIN</a>
+and
+<a href="docprocessing.html#doc-right-margin">DOC_RIGHT_MARGIN</a>
+(before or after START).
+</p>
+
+<p class="tip-bottom">
+Equally, recto/verso only switches the page number position if page
+numbers aren&#8217;t centred, which means you have to set the page
+number position with
+<a href="headfootpage.html#pagenum-pos">PAGENUM_POS</a>
+(before or after START).
+</p>
+</div>
+
+<!-- -SWITCH_HDRFTR- -->
+
+<div id="switch-hdrftr" class="box-macro-args" style="margin-top: 1em;">
+Macro: <b>SWITCH_HEADERS</b>
+</div>
+
+<p>
+SWITCH_HEADERS switches the location of the header left string
+(by default, the author) and the header right string (by default,
+the document title).  If you don&#8217;t like mom&#8217;s default
+placement of author and title, use SWITCH_HEADERS to reverse it.
+</p>
+
+<p>
+SWITCH_HEADERS can also be useful in conjunction with
+<a href="#recto-verso">RECTO_VERSO</a>.
+The assumption of RECTO_VERSO is that the first page of a document
+(i.e. recto/odd) represents the norm for header-left and header-right,
+meaning that the second (and all subsequent verso/even) pages of the
+document will reverse the order of header-left and header-right.
+</p>
+
+<p>
+If mom&#8217;s behaviour in this matter is not what you want, simply
+invoke SWITCH_HEADERS on the first page of your recto/verso document
+to reverse her default treatment of header parts.  The remainder of
+your document (with respect to headers) will come out as you want.
+</p>
+
+<div class="rule-medium"><hr/></div>
+
+<!-- ===================================================================== -->
+
+<h2 id="collate-intro" class="docs">Introduction to collating</h2>
+
+<p>
+Many people wisely keep chapters of a long work in separate
+files, previewing or printing them as needed during the draft
+phase.  However, when it comes to the final version, mom requires
+a single, collated file in order to keep track of page numbering
+and recto/verso administration, generating tables of contents and
+endnotes, ensuring that
+<a href="definitions.html#docheader">docheaders</a>
+get printed correctly, and a host of other details.
+</p>
+
+<p>
+The COLLATE macro, which can be used with any
+<a href="docprocessing.html#doctype">DOCTYPE</a>
+except <kbd>LETTER</kbd>, lets you glue mom-formatted text files
+together.  You need only concatenate chapters into a single file
+(most likely with the <kbd>cat</kbd> command), put <kbd>.COLLATE</kbd> at the 
end of each
+concatenated chapter, follow it with the
+<a href="docprocessing.html#reference-macros">reference macros</a>
+needed for the new chapter, e.g.
+<a href="docprocessing.html#chapter">CHAPTER</a>
+or
+<a href="docprocessing.html#chapter-string">CHAPTER_STRING</a>,
+make any pertinent style changes to the upcoming chapter (unlikely,
+but possible), and re-invoke the
+<a href="docprocessing.html#start">START</a>
+macro.  (Most likely, the reference macros and <kbd>.START</kbd> are
+already there.)  Each chapter will begin on a fresh page and behave
+as expected.
+</p>
+
+<p>
+Even if you always work with monolithic, multi-chapter files, every
+chapter and its associated reference macros plus <kbd>.START</kbd>
+still needs to be preceded by a <kbd>.COLLATE</kbd> command.
+</p>
+
+<div class="box-tip">
+<p class="tip">
+<span class="note">Note:</span>
+COLLATE assumes you are collating documents/files with similar
+type-style parameters hence there&#8217;s no need for PRINTSTYLE
+to appear after COLLATE, although if you&#8217;re collating
+documents that were created as separate files, chances are the
+PRINTSTYLE&#8217;s already there.
+</p>
+</div>
+
+<div class="box-tip">
+<p id="caution" class="tip">
+<b>Two words of caution:</b>
+</p>
+<ol style="margin-top: -1.25em; margin-left: -1.25em; padding-bottom: .5em;">
+  <li>Do not collate documents of differing
+      PRINTSTYLES (i.e. don&#8217;t try to
+      collate a <kbd>TYPESET</kbd> document and <kbd>TYPEWRITE</kbd>
+      document).
+  </li>
+  <li>Use <kbd>.DOC_FAMILY</kbd> instead of
+      <kbd>.FAMILY</kbd> if, for some reason, you want to
+      change the family of all the document elements after
+      <kbd>.COLLATE</kbd>. <kbd>.FAMILY</kbd>, by itself, will
+      change the family of paragraph text only.
+  </li>
+</ol>
+</div>
+
+<!-- -COLLATE- -->
+
+<div class="macro-id-overline">
+<h3 id="collate" class="macro-id">collate</h3>
+</div>
+
+<div class="box-macro-args">
+Macro: <b>COLLATE</b>
+</div>
+
+<p>
+The most basic (and most likely) collating situation looks like
+this:
+<br/>
+<span class="pre-in-pp">
+  .COLLATE
+  .CHAPTER 17
+  .START
+</span>
+</p>
+
+<p>
+A slightly more complex version of the same thing, for chapters
+that require their own titles, looks like this:
+<br/>
+<span class="pre-in-pp">
+  .COLLATE
+  .CHAPTER_TITLE "Geek Fatigue: Symptoms and Causes"
+  .START
+</span>
+</p>
+
+<div class="box-tip">
+<p class="tip">
+<span class="tip">Tip:</span>
+If the last
+<a href="definitions.html#outputline">output line</a>
+of a document before COLLATE falls too close to the bottom margin
+for running text, mom may output a blank page with only a header
+or footer between collated documents.  In order to avoid this, I
+recommend always preceding COLLATE with
+<kbd><a href="typesetting.html#el">.EL</a></kbd>,
+like this
+<br/>
+<span class="pre-in-pp">
+  .EL
+  .COLLATE
+</span>
+</p>
+</div>
+
+<div class="box-tip">
+<p class="tip">
+<span class="note">Note:</span>
+See the
+<a href="#caution">two words of caution</a>,
+above.
+</p>
+</div>
+
+<div class="rule-long"><hr/></div>
+
+<!-- Navigation links -->
+<table style="width: 100%; margin-top: 12px;">
+<tr>
+  <td style="width: 33%;"><a href="toc.html">Back to Table of Contents</a></td>
+  <td style="width: 33%; text-align: center;"><a href="#top">Top</a></td>
+  <td style="width: 33%; text-align: right;"><a href="cover.html">Next: Cover 
pages</a></td>
+</tr>
+</table>
+
+</div>
+
+<div class="bottom-spacer"><br/></div>
+
+</body>
+</html>
+<!-- vim: fileencoding=utf-8: nomodified: -->

Index: refer.html
===================================================================
RCS file: refer.html
diff -N refer.html
--- /dev/null   1 Jan 1970 00:00:00 -0000
+++ refer.html  18 Aug 2010 22:45:36 -0000      1.11
@@ -0,0 +1,1853 @@
+<?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, bibliographies and references</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="letters.html#top">Next: Writing 
letters</a></td>
+</tr>
+</table>
+
+<h1 class="docs">Bibliographies and references</h1>
+
+<div style="width: 53%; margin: auto;">
+<ul class="no-enumerator">
+  <li><a href="#intro-ref">Introduction to bibliographies and 
references</a></li>
+  <li><a href="#tutorial-ref">Tutorial &ndash; using mom with 
<kbd>refer</kbd></a>
+  <ul style="margin-left: -.5em; list-style-type: disc;">
+    <li><a href="#db-ref">Creating a <kbd>refer</kbd> database</a></li>
+    <li><a href="#rcommands-ref">Required <kbd>refer</kbd> commands</a></li>
+    <li><a href="#accessing-ref">Accessing references in your 
documents</a></li>
+    <li><a href="#where-ref">Telling mom where to put references</a></li>
+    <li><a href="#biblio-ref">Creating bibliography pages</a></li>
+    <li><a href="#invoking-ref">Invoking groff with mom and 
<kbd>refer</kbd></a></li>
+  </ul></li>
+  <li><a href="#index-ref">Bibliography and reference macros</a>
+  <ul style="margin-left: -.5em; list-style-type: disc;">
+    <li><a href="#biblio-control">Bibliography control macros and 
defaults</a></li>
+  </ul></li>
+</ul>
+</div>
+
+<div class="rule-medium"><hr/></div>
+
+<h2 id="intro-ref" class="docs">Introduction to bibliographies and 
references</h2>
+
+<p>
+Mom provides the ability to automatically format and generate
+bibliography pages, as well as footnote or endnote references, or
+references embedded in the text.  She accomplishes this by working
+in conjunction with a special groff program called
+<kbd>refer</kbd>.
+</p>
+
+<p>
+<kbd>refer</kbd> is, in groff-speak, a pre-processor, which is to
+say that it scans your files, looking for very specific control
+lines (i.e. lines that begin with a dot, the same way macros do).
+If <kbd>refer</kbd> doesn't find them, it can&#8217;t do it&#8217;s
+job and neither can mom.  The scanning is done before any other
+document processing.
+</p>
+
+<p>
+<kbd>refer</kbd> is a program that&#8217;s been around for a
+long time.  It&#8217;s powerful and has many, many features.
+Unfortunately, the manpage (<kbd>man&nbsp;refer</kbd>), while
+complete and accurate, is dense and not a good introduction.
+(It&#8217;s a classic manpage Catch-22: the manpage is useful, but
+only after you know how to use the program.)
+</p>
+
+<p>
+In order to get mom users up and running with <kbd>refer</kbd>,
+this section of mom&#8217;s documentation focuses exclusively, in a
+recipe-like manner, on what you need to know to use <kbd>refer</kbd>
+satisfactorily in conjunction with mom.  The information and
+instructions are not to be taken as a manual or tutorial on full
+<kbd>refer</kbd> usage.  Much has been left out, on purpose.
+</p>
+
+<p>
+If you&#8217;re already a <kbd>refer</kbd> user, the information
+herein will be useful for adapting your current <kbd>refer</kbd>
+usage to mom&#8217;s way of doing things.  If you&#8217;ve never
+used <kbd>refer</kbd>, the information is essential, and, in many
+cases, may be all you need.
+</p>
+
+<p>
+(For the benefit of old groff-hands: <kbd>refer</kbd>
+support in mom is heavily based on the
+<kbd>refer</kbd> module of the &#8220;ms&#8221; macros.  The
+choice was deliberate so that those wishing to play around with
+mom&#8217;s bibliography formatting style would be
+tinkering with the familiar.)
+</p>
+
+<p>
+<kbd>refer</kbd> requires first that you create a
+bibliographic database.  From the information contained in the
+database, mom formats and generates bibliographies
+and references in MLA (Modern Language Association) style.  MLA
+style is clean, contemporary and flexible, and is widely used in the
+humanities, where the range of material that has to be referenced
+can run from simple books to live interviews and film.
+</p>
+
+<p>
+Once you have created your database, you instruct <kbd>refer</kbd>
+(and mom) to access entries in it by supplying keywords associated
+with the entries.  Depending on what you&#8217;ve instructed mom to
+do, she will put the entries&mdash;fully and properly formatted
+with respect to order, punctuation and italicization&mdash;in
+footnotes, endnotes, or a full bibliography.
+</p>
+
+<p>
+I encourage anyone interested in what MLA style looks like&mdash;and, by 
extension, how your bibliographies and references will look
+after mom formats them&mdash;to check out
+<br/>
+<span class="pre-in-pp">
+  http://www.aresearchguide.com/12biblio.html
+</span>
+or any other website or reference book on MLA style.
+</p>
+
+<div class="rule-short"><hr/></div>
+
+<div class="examples-container" style="margin-top: 1.5em; margin-bottom: 
1.5em;">
+<h3 id="tutorial-ref" class="docs">Tutorial &ndash; Using <kbd 
style="font-style: normal; text-transform: none;">refer</kbd> with mom</h3>
+<ol style="margin-top: 1em; margin-left: -1em; margin-bottom: -.5em;">
+  <li><a href="#db-ref">Creating a <kbd>refer</kbd> database</a>
+  <ul style="margin-left: -.5em">
+    <li><a href="#example-refer-database">Example <kbd>refer</kbd> 
database</a></li>
+    <li><a href="#field-identifiers">Meanings of the field identifiers 
(<kbd>%A</kbd>, <kbd>%T</kbd>, etc.)</a></li>
+  </ul></li>
+  <li><a href="#rcommands-ref">Required <kbd>refer</kbd> commands</a>
+  <ul style="margin-left: -.5em">
+    <li><a href="#refer-block1">Required <kbd>refer</kbd> block (embedded 
references)</a></li>
+    <li><a href="#refer-block2">Required <kbd>refer</kbd> block 
(bibliographies)</a></li>
+  </ul></li>
+  <li><a href="#accessing-ref">Accessing references in your documents</a></li>
+  <li><a href="#where-ref">Telling mom where to put references</a></li>
+  <li><a href="#biblio-ref">Creating bibliography pages</a></li>
+  <li><a href="#invoking-ref">Invoking groff with mom and 
<kbd>refer</kbd></a></li>
+</ol>
+
+<h4 id="db-ref" class="docs">1. Creating a refer database</h4>
+
+<p>
+The first step in using <kbd>refer</kbd> with mom is setting
+up your bibliographic database.  The database is a text file
+containing entries for each reference you want to access from your
+mom files.  The file is <i>not</i> a &#8220;mom file&#8221;; it's an
+entirely separate database containing no mom macros.  You may set
+up individual databases for individual documents, or create a large
+database that contains every reference you&#8217;ll ever use.
+</p>
+
+<p>
+Entries (&#8220;records&#8221; in refer-speak) in the database file
+are separated from each other by a single, blank line.  The records
+themselves are composed of single lines (&#8220;fields&#8221;) with
+no blank lines between them.  Each field begins with a percent
+sign and a single letter (the &quot;field identifier&quot;)
+e.g. <kbd>%A</kbd> or <kbd>%T</kbd>.  The letter identifies
+what part of a bibliographic entry the field refers to: Author,
+Title, Publisher, Date, etc.  After the field identifier comes
+a single space, followed by the information appropriate to
+field.  No punctuation should go at the ends of fields; mom adds
+what&#8217;s correct automatically.  Do note, however, that
+author(s) (<kbd>%A</kbd>) requires that you enter the author
+information exactly as you wish it to come out (minus the period),
+including the comma after the first author&#8217;s last name.
+</p>
+
+<p>
+Here&#8217;s an example database containing two records so you can
+visualize what the above paragraph says.
+</p>
+
+<div id="example-refer-database" class="examples" style="margin-top: 
-.5em;">Example <kbd>refer</kbd> database</div>
+<div class="examples-container" style="padding-bottom: 1em;">
+<span class="pre">
+%A Schweitzer, Albert
+%A C.M. Widor
+%T J.S. Bach
+%l Ernest Newman
+%V Vol 2
+%C London
+%I Adam and Charles Black
+%D 1923
+%O 2 vols
+%K bach vol 2
+
+%A Schaffter, Peter
+%T The Schumann Proof
+%C Toronto
+%I RendezVous Press
+%D 2004
+%K schumann schaffter
+</span>
+</div>
+
+<p>
+The order in which you enter fields doesn&#8217;t matter. mom
+and <kbd>refer</kbd> will re-arrange them in the correct order
+for you.  The meaning of the letters follows.  There are, with
+<kbd>refer</kbd>, quite a few&mdash;all uppercase &mdash; which
+have, over time, come to be standard.  Mom respects these.  However,
+she adds to the list (mostly using lowercase letters).
+</p>
+
+<div id="field-identifiers" class="examples" style="margin-top: 
-.5em;">Meanings of the field identifiers</div>
+<div class="examples-container" style="padding-bottom: 1em;">
+<span class="pre">
+%A Author           &ndash; records may contain multiple Author fields,
+                      each beginning with %A, as in the first
+                      entry of the example database, above; mom
+                      and refer will figure out what to do when
+                      there are multiple authors
+%T Title            &ndash; either the primary title (e.g. of a book),
+                      or the title of an article (e.g. within a
+                      book or journal or magazine)
+%B Book title       &ndash; the title of a book when %T contains the
+                      title of an article; otherwise, use %T for
+                      book titles
+%R Report number    &ndash; for technical reports
+%J Journal name     &ndash; the name of a journal or magazine when %T
+                      contains the title of an article
+%E Editor           &ndash; additional editors may be entered on
+                      separate %E lines (like authors); mom and
+                      refer will figure out what to do with them
+                      according to MLA rules
+%e Edition          &ndash; the number or name of a specific edition
+                      (e.g. Second, 2nd, Collector&#8217;s, etc.)
+%V Volume           &ndash; volume number of a journal or series of
+                      books
+%N Journal number   &ndash; journal or magazine number
+%S Series           &ndash; series name for books or journals that are
+                      part of a series
+%C City             &ndash; the city of publication
+%I Publisher        &ndash; the publisher; %I stands for "Issuer"
+%D Publication date
+%P Page number(s)   &ndash; enter page ranges as, e.g., 22-25
+%G Gov&#8217;t.
+   ordering number  &ndash; for government publications
+%O Other            &ndash; additional information or comments you want
+                      to appear at the end of the reference
+%K Keywords         &ndash; any words that will clear up ambiguities
+                      resulting from database entries that
+                      contain, say, the same author or the same
+                      title
+%d original        
+   publication date &ndash; if different from the date of publication
+%a additions        &ndash; for books, any additions to the original
+                      work, such as the preface to a new edition
+                      or a new introduction
+%t reprint title    &ndash; if different from a work&#8217;s original title
+%l translator       &ndash; if the translator is not the editor; if more
+                      than one translator, this field should
+                      contain all the names, with appropriate
+                      punctuation
+%r translator
+   and editor       &ndash; if tr. and ed. are one in the same;
+%s site name        &ndash; for web sites, the site name
+%c content
+   of site          &ndash; for web sites, the content, if unclear
+                      (i.e. advertisement, cartoon, blog)
+%o organization     &ndash; for web sites, the organization, group or
+                      sponsor of the site
+%a access date      &ndash; for a website, the date you accessed it
+%u URL              &ndash; for websites, the full URL of the site
+</span>
+</div>
+
+<div id="ref-disc-hy" class="box-tip">
+<p class="tip-top">
+<span class="tip">Tip:</span>
+If you have automatic hyphenation enabled in your document (you
+probably do), mom will hyphenate your references.  This can be a
+problem because references typically contain several proper names,
+which shouldn&#8217;t be hyphenated.  The solution is to prepend to
+any proper name in your <kbd>refer</kbd> database the groff
+<a href="definitions.html#discretionaryhyphen">discretionary hyphen</a>
+character, <kbd>\%</kbd>, like this:
+<br/>
+<span class="pre-in-pp">
+  %A Hill, \%Reginald
+</span>
+</p>
+
+<p class="tip-bottom" style="margin-top: -1.5em;">
+Alternatively, you can turn hyphenation off entirely in references
+with the macro,
+<kbd><a href="#hyphenate-refs">HYPHENATE_REFS</a></kbd> <kbd>OFF</kbd>.
+</p>
+</div>
+
+<h4 id="rcommands-ref" class="docs">2. Required <kbd>refer</kbd> commands</h4>
+
+<p>
+Having set up your database, you now need to put some
+<kbd>refer</kbd>-specific commands at the top of your mom file.  You
+cannot skip this step, nor can you source these commands with the
+groff
+<a href="definitions.html#primitives">primitive</a>,
+<kbd>.so</kbd> or the mom macro,
+<kbd><a href="docprocessing.html#include">.INCLUDE</a></kbd>.
+They <span style="font-weight: bold; font-style: italic;">must</span>
+appear, exactly as shown, at the top of every file containing 
+references that need to be pre-processed with <kbd>refer</kbd>.
+</p>
+
+<p>
+<kbd>refer</kbd> commands are introduced by a single
+line containing <kbd>.R1</kbd>, and concluded with a single line
+containing <kbd>.R2</kbd>.  What you put between the <kbd>.R1</kbd>
+and <kbd>.R2</kbd> lines are the commands themselves.  The commands
+should be entered one per line, in lowercase letters, <i>with
+no initial period (dot)</i>.
+</p>
+
+<p>
+Here&#8217;s an example:
+<br/>
+<span class="pre-in-pp">
+  .R1
+  no-label-in-text
+  no-label-in-reference
+  .R2
+</span>
+There are an awful lot of <kbd>refer</kbd> commands.  We will focus
+only on those required to get mom cooperating with <kbd>refer</kbd>.
+If you&#8217;re interested, study the <kbd>refer</kbd> manpage to
+discover what other commands are available and how to manipulate
+them.
+</p>
+
+<p>
+At a minimum, all mom files accessing a bibliographic database must
+contain the following <kbd>refer</kbd> commands, exactly as shown:
+</p>
+
+<div id="refer-block1" class="examples" style="margin-top: -.5em;">Required 
<kbd>refer</kbd> block (embedded references)</div>
+<div class="examples-container" style="padding-bottom: 1em;">
+<span class="pre">
+.R1
+no-label-in-text
+no-label-in-reference
+join-authors &quot;, and &quot; &quot;, &quot; &quot;, and &quot;
+database &lt;full path to the database&gt;
+.R2
+</span>
+</div>
+
+<p>
+The first two commands tell <kbd>refer</kbd> to let mom handle
+everything associated with footnote and endnote markers, both in the
+body of the document, and in the footnotes/endnotes themselves.
+</p>
+
+<p>
+The third command is required for mom to handle multiple authors in
+proper MLA style.
+</p>
+
+<p>
+The last command, <kbd>database</kbd>, assumes you have created
+your own database, and do not otherwise have a system-wide
+default database.
+<kbd>&lt;full&nbsp;path&nbsp;to&nbsp;the&nbsp;database&gt;</kbd>
+means the full path <i>including</i> the filename, e.g.
+<kbd>/home/user/refer/my-database.</kbd>
+</p>
+
+<p> If you&#8217;re already a <kbd>refer</kbd> user, feel free to
+enter whatever <kbd>refer</kbd> commands are necessary to
+access the database(s) you want.
+</p>
+
+<p>
+With the above <kbd>refer</kbd> block, you can embed references
+directly into the text of your document, or have them output as
+footnotes or endnotes.  If, on the other hand, you want to collect
+references for output in a bibliography, the block must read:
+</p>
+
+<div id="refer-block2" class="examples" style="margin-top: -.5em;">Required 
<kbd>refer</kbd> block (bibliographies)</div>
+<div class="examples-container" style="padding-bottom: 1em;">
+<span class="pre">
+.R1
+no-label-in-text
+no-label-in-reference
+join-authors ", and " ", " ", and "
+database &lt;full path to the database&gt;
+sort
+accumulate
+.R2
+</span>
+</div>
+
+<h4 id="accessing-ref" class="docs">3. Accessing references in your 
documents</h4>
+
+<p>
+References are accessed by putting keywords, all on one line,
+between the <kbd>refer</kbd> commands, <kbd>.[</kbd> (dot
+left-bracket) and <kbd>.]</kbd> (dot right-bracket).  Both commands
+must appear on separate lines, by themselves, like this:
+<br/>
+<span class="pre-in-pp">
+  .[
+  keyword(s)
+  .]
+</span>
+Keywords are any word, or set of words, that identify a database
+record (i.e. a reference) unambiguously. (<kbd>refer</kbd>
+doesn&#8217;t like ambiguity.)
+</p>
+
+<p>
+If, for example, you want to reference a book by Ray Bradbury,
+and the database contains only one book by Bradbury, a suitable
+keyword would be &#8220;Bradbury&#8221;.  If your database contains
+several books by Bradbury, say, <i>Fahrenheit 451</i> and <i>The
+Martian Chronicles</i>, you could reference them with the keywords,
+&#8220;451&#8221; and &#8220;Martian&#8221;.  If, in addition to
+the two books by Bradbury, you also had one whose title was <i>The
+Martian Mission</i>, suitable keywords to reference <i>The Martian
+Chronicles</i> might be:
+<br/>
+<span class="pre-in-pp">
+  .[                or    .[                   or  .[
+  Bradbury Martian        Bradbury Chronicles      Martian Chronicles
+  .]                      .]                       .]
+</span>
+</p>
+
+<p>
+A special database field identifier, <kbd>%K</kbd>, lets you create
+unique keywords for references.  This can be very handy if you need
+both a &#8220;short&#8221; and a &#8220;long&#8221; reference to the
+same work.  The short reference might be used in footnotes, the long
+one in a bibliography.  Consider the following:
+<br/>
+<span class="pre-in-pp">
+    %A Isherwood, Christopher      %A Isherwood
+    %T Mr. Norris Changes Trains   %T Mr. Norris Changes Trains
+    %d 1935                        %K Nor short
+    %t The Last of Mr. \%Norris
+    %a Intro. Tom Crawford
+    %C New York
+    %I New Directions
+    %D 1945
+    %K Norris
+</span>
+To access the shorter reference, you&#8217;d do
+<br/>
+<span class="pre-in-pp">
+  .[
+  Nor short
+  .]
+</span>
+To access the longer one, you&#8217;d do
+<br/>
+<span class="pre-in-pp">
+  .[
+  Norris
+  .]
+</span>
+</p>
+
+<h4 id="where-ref" class="docs">4. Telling mom where to put references</h4>
+
+<p>
+Mom provides several mechanisms for outputting references where you
+want:
+</p>
+<ul style="margin-top: -.5em; margin-left: -.5em; margin-bottom: -.75em;">
+  <li><a href="#embedded">embedded in the body of the document</a></li>
+  <li><a href="#foot-end">in footnotes or endnotes</a>
+  <ul style="margin-left: -.5em;">
+    <li><a href="#footnotes-recipe">recipe for references in footnotes</a></li>
+    <li><a href="#endnotes-recipe">recipe for references in endnotes</a></li>
+  </ul></li>
+  <li><a href="#bibliographies">collected in a bibliography</a></li>
+</ul>
+
+<h5 id="embedded" class="docs" style="text-transform: none; margin-bottom: 
-1em;">Embedding references in the document body</h5>
+
+<p>
+References may be embedded in the document body, surrounded by
+parentheses, square brackets, or braces.  Use whichever you prefer,
+following the recipes below.
+<br/>
+<span class="pre-in-pp">
+  Parentheses  |  Square brackets  |  Braces
+  ===========  |  ===============  |  ======
+  .REF(        |  .REF[            |  .REF{
+  .[           |  .[               |  .[
+  keyword(s)   |  keyword(s)       |  keyword(s)
+  .]           |  .]               |  .]
+  .REF)        |  .REF]            |  .REF}
+</span>
+</p>
+
+<h5 id="foot-end" class="docs" style="text-transform: none; margin-top: -1em; 
margin-bottom: -1em;">Footnote or endnote references</h5>
+
+<p>
+Most times, you&#8217;ll probably want references in either
+footnotes or endnotes. Mom provides a simple mechanism whereby
+you can choose which, or even switch back and forth.  It&#8217;s
+a two-step process.  First, you instruct mom where you want the
+references to go with either
+<kbd><a href="#footnote-refs">.FOOTNOTE_REFS</a></kbd>
+or
+<kbd><a href="#endnote-refs">.ENDNOTE_REFS</a></kbd>.
+Afterwards, you enclose the <kbd>refer</kbd> commands, <kbd>.[</kbd>
+and <kbd>.]</kbd>, with the mom macro,
+<a href="#ref">REF</a>.
+Depending on which was the last invoked, <kbd>.FOOTNOTE_REFS</kbd> or
+<kbd>.ENDNOTE_REFS</kbd>, references will either go into footnotes or be
+collected for output as endnotes.
+</p>
+
+<p>
+The innate flexibility of this scheme allows you to have both
+footnote references and endnote references in the same document.
+This would be desirable if, say, you wanted truncated 
+references in footnotes, and full references in endnotes.
+</p>
+
+<p id="footnotes-recipe">
+A recipe for footnoted references looks like this:<br/>
+<span class="pre-in-pp">
+  .FOOTNOTE_REFS \"Can be placed anywhere in the file prior to .REF
+  .REF
+  .[
+  keyword(s)
+  .]
+  .REF
+</span>
+The reference between the first and second <kbd>.REF</kbd> will be
+treated as a footnote, as will all subsequent <kbd>.REF</kbd> pairs
+unless you invoke the macro, <kbd>.ENDNOTE_REFS</kbd>.
+There&#8217;s no need to repeat <kbd>.FOOTNOTE_REFS</kbd> if all
+your references are going into footnotes.
+</p>
+
+<div class="box-important">
+<p class="tip">
+<span class="important">Important:</span>
+When FOOTNOTE_REFS are enabled, REF behaves identically to
+<a href="docelement.html#footnote">FOOTNOTE</a>
+with respect to the use of the <kbd>\c</kbd> inline escape.  Please
+read the
+<a href="docelement.html#footnote-note">HYPER IMPORTANT NOTE</a>
+found in the document entry for FOOTNOTE.
+</p>
+</div>
+
+<p id="endnotes-recipe">
+A recipe for endnote references looks like this:
+<br/>
+<span class="pre-in-pp">
+  .ENDNOTE_REFS \"Can be placed anywhere in the file prior to .REF
+  .REF
+  .[
+  keyword(s)
+  .]
+  .REF
+</span>
+The reference between the first and second <kbd>.REF</kbd> will
+be treated as an endnote, as will all subsequent <kbd>.REF</kbd>
+pairs unless you invoke the macro, <kbd>.FOOTNOTE_REFS</kbd>.
+There&#8217;s no need to repeat <kbd>.ENDNOTE_REFS</kbd> if all your
+references are going into endnotes.
+</p>
+
+<div class="box-important">
+<p class="tip">
+<span class="important">Important:</span>
+When ENDNOTE_REFS are enabled, REF behaves identically to
+<a href="docelement.html#footnote">ENDNOTE</a>
+with respect to the use of the <kbd>\c</kbd> inline escape.  Please
+read the
+<a href="docelement.html#endnote-note">HYPER IMPORTANT NOTE</a>
+found in the document entry for ENDNOTE.
+</p>
+</div>
+
+<h5 id="bibliographies" class="docs" style="text-transform: none; 
margin-bottom: -1em;">Collected references (bibliographies)</h5>
+
+<p>
+Sometimes, you may want to embed references in input text near the
+sections of text to which they pertain, but not have them output
+until later (typically, on a bibliography page).  REF is used for
+this, too, but you have to make sure your <kbd>refer</kbd> commands
+block is set up properly at the top of your text file.  The recipe
+for this is:
+<br/>
+<span id="refer-block3" class="pre-in-pp">
+  .R1
+  no-label-in-text
+  no-label-in-reference
+  join-authors &quot;, and &quot; &quot;, &quot; &quot;, and &quot;
+  database &lt;full path to the database&gt;
+  sort
+  accumulate
+  .R2
+</span>
+After this set up, and provided you don&#8217;t issue a
+<kbd>.FOOTNOTE_REFS</kbd> or <kbd>.ENDNOTE_REFS</kbd> command, all
+reference between <kbd>.REF</kbd> pairs will be collected for later
+output in a bibliography.
+</p>
+
+<p>
+As a precaution, mom will issue a message the first time you call
+<kbd>.REF</kbd> if neither FOOTNOTE_REFS nor ENDNOTE_REFS is in
+effect.  If collected references are what you want, and you have set
+up your <kbd>.R1/.R2</kbd> block as above, you may safely ignore
+the message.
+</p>
+
+<div id="limitation" class="box-important">
+<p class="tip">
+<span class="important">LIMITATION:</span> You cannot combine
+&#8220;collected&#8221; references (plain REF)
+with REFs that are instructed to go into
+footnotes (with FOOTNOTE_REFS) or endnotes (with
+ENDNOTE_REFS).  This is a limitation imposed by
+<kbd>refer</kbd>, not mom.
+</p>
+</div>
+
+<h4 id="biblio-ref" class="docs">5. Creating bibliography pages</h4>
+
+<p>
+Bibliographies are processed separately from the main document, like
+endnotes.  And, like endnotes, just about every element on them can
+be designed to your specifications.  (See
+<a href="#biblio-control">Bibliography control macros and defaults</a>.)
+A mom bibliography begins with the macro,
+<kbd><a href="#bibliography">BIBLIOGRAPHY</a></kbd>,
+like this:
+<br/>
+<span class="pre-in-pp">
+  .BIBLIOGRAPHY
+</span>
+Following <kbd>.BIBLIOGRAPHY</kbd>, you have three choices of how to
+proceed:
+</p>
+
+<ol style="margin-top: -.5em; margin-left: -.5em;">
+  <li>
+  If you have elected to have references collected from within the
+  body of a document (see above,
+  <a href="#bibliographies">Collected references [bibliographies]</a>, 
+  for instructions), which assumes you have a <kbd>refer</kbd>
+  command block like the one
+  <a href="#refer-block2">here</a>
+  at the top of your document, you need only do
+  <br/>
+  <span class="pre-in-pp">
+  .BIBLIOGRAPHY
+  .[
+  $LIST$
+  .]
+  </span></li>
+  <li style="margin-top: -2em;">
+  If you want to create the bibliography by hand (which may be the
+  case if you&#8217;ve used footnote and/or endnote references throughout
+  your document; see
+  <a href="#limitation">LIMITATION</a>),
+  follow this recipe.  It assumes you already have a
+  <kbd>refer</kbd> block like the one
+  <a href="#refer-block1">here</a>
+  at the top of your document.
+  <br/>
+  <span class="pre-in-pp">
+  .BIBLIOGRAPHY
+  .R1
+  sort
+  accumulate
+  .R2
+  .[          -+
+  keyword(s)   |
+  .]           | "keyword(s)" are keywords identifying the
+  .[           | particular bibliographic reference you want
+  keyword(s)   | from your database.  Order doesn't matter here;
+  .]           | the refer command, sort, takes care of that.
+  .[           |
+  keyword(s)   |
+  .]          -+
+  .[
+  $LIST$
+  .]
+  </span></li>
+  <li style="margin-top: -2em;">
+  Your final choice is to output your whole database.  Again,
+  assuming you have a <kbd>refer</kbd> block like the one
+  <a href="#refer-block1">here</a>
+  at the top of your file, you need only do:
+  <br/>
+  <span class="pre-in-pp" style="margin-bottom: -2em;">
+  .BIBLIOGRAPHY
+  .R1
+  bibliography &lt;full path to database&gt;
+  .R2
+  </span>
+  If you haven&#8217;t put a <kbd>refer</kbd> block in your
+  file already, you can, in this instance, put one after
+  <kbd>.BIBLIOGRAPHY</kbd>, like this:
+  <br/>
+  <span class="pre-in-pp">
+  .BIBLIOGRAPHY
+  .R1
+  join-authors &quot;, and &quot; &quot;, &quot; &quot;, and &quot;
+  bibliography &lt;full path to database&gt;
+  .R2
+  </span></li>
+</ol>
+
+<p style="margin-top: -3em;">
+Whichever option you choose, mom will output a full bibliography
+page, complete with a title (&#8220;BIBLIOGRAPHY&#8221; by default,
+but that can be changed).
+</p>
+
+<h4 id="invoking-ref" class="docs">6. Invoking groff with mom and refer</h4>
+
+<p>
+So, now you&#8217;ve got a document formatted properly to use
+references processed with <kbd>refer</kbd>, what do you do to output
+the document?
+</p>
+
+<p>
+It&#8217;s simple.  Instead of invoking groff with just the
+<kbd>-mom</kbd> option, as explained
+<a href="using.html#using-invoking">here</a>,
+invoke groff with the <kbd>-R</kbd> option as well, like this:
+<br/>
+<span class="pre-in-pp">
+  groff -R -mom filename
+</span>
+</p>
+</div>
+
+<div class="macro-list-container">
+<h3 id="index-ref" class="macro-list">Bibliography and reference macros</h3>
+<ul class="macro-list">
+  <li><a href="#ref">REF</a> &ndash; begin/end a <kbd>refer</kbd> 
reference</li>
+  <li><a href="#footnote-refs">FOOTNOTE_REFS</a> &ndash; instruct mom to put 
REFs in footnotes</li>
+  <li><a href="#endnote-refs">ENDNOTE_REFS</a> &ndash; instruct mom to put 
REFs in endnotes</li>
+  <li><a href="#bracket-refs">Embed references in the text</a>
+  <ul style="margin-left: -.5em;">
+    <li><a href="#bracket-refs-parens">REF(</a> &ndash; embed a reference in 
the text between parentheses</li>
+    <li><a href="#bracket-refs-brackets">REF[</a> &ndash; embed a reference in 
the text between square brackets</li>
+    <li><a href="#bracket-refs-braces">REF{</a> &ndash; embed a reference in 
the text between braces</li>
+  </ul></li>
+  <li><a href="#indent-refs">INDENT_REFS</a> &ndash; manage the 2nd line 
indent of references, per MLA standards</li>
+  <li><a href="#hyphenate-refs">HYPHENATE_REFS</a> &ndash; enable/disable 
hyphenation of references</li>
+  <li><a href="#bibliography">BIBLIOGRAPHY</a> &ndash; begin a 
bibliography</li>
+  <li><a href="#bibliography-type">BIBLIOGRAPHY_TYPE</a> &ndash; plain, or 
numbered list bibliography</li>
+  <li><a href="#biblio-control">Bibliography control macros and 
defaults</a></li>
+</ul>
+</div>
+
+<!-- -REF- -->
+
+<div class="macro-id-overline">
+<h3 id="ref" class="macro-id">Begin/end a <kbd style="text-transform: 
none;">refer</kbd> reference</h3>
+</div>
+
+<div class="box-macro-args">
+Macro: <b>REF</b>
+</div>
+
+<p>
+The macro, REF, tells mom that what follows is
+<kbd>refer</kbd>-specific, a keyword-identified reference from a
+<kbd>refer</kbd> database.  Depending on whether you&#8217;ve issued
+a
+<kbd><a href="#footnote-refs">.FOOTNOTE_REFS</a></kbd>
+or
+<kbd><a href="#endnote-refs">.ENDNOTE_REFS</a></kbd>
+instruction, REF also tells mom where to place the reference.  If
+FOOTNOTE_REFS, the reference will be formatted and placed in a
+footnote.  If ENDNOTE_REFS, the reference will be collected for
+output as an endnote.  If you have issued neither instruction, the
+reference will be collected for later output, most likely in a
+<a href="#bibliography">bibliography</a>.
+</p>
+
+<p>
+Before you use REF, you must create a <kbd>refer</kbd> block
+containing <kbd>refer</kbd> commands (see
+<a href="#rcommands-ref">Required refer commands</a>
+in the tutorial, above).
+</p>
+
+<p>
+REF usage always looks like this:
+<br/>
+<span class="pre-in-pp">
+  .REF
+  .[
+  keyword(s)
+  .]
+  .REF
+</span>
+Notice that REF &#8220;brackets&#8221; the <kbd>refer</kbd> instructions,
+and never takes an argument.
+</p>
+
+<p>
+What REF really is is a convenience.  One could, for example, put a
+reference in a footnote by doing
+<br/>
+<span class="pre-in-pp">
+  .FOOTNOTE
+  .[
+  keyword(s)
+  .]
+  .FOOTNOTE OFF
+</span>
+However, if you have a lot of references going into footnotes (or
+endnotes), it&#8217;s much shorter to type <kbd>.REF/.REF</kbd>
+than <kbd>.FOOTNOTE/.FOOTNOTE OFF</kbd>.  It also helps you
+distinguish&mdash;visually, in your input file&mdash;between
+footnotes (or endnotes) which are references, and footnotes (or
+endnotes) which are explanatory, or expand on the text.
+</p>
+
+<div class="box-tip">
+<p class="tip-top">
+<span class="note">Note:</span>
+If you&#8217;re using REF to put references in footnotes and your
+footnotes need to be indented, you may (indeed, should) pass REF the
+same arguments used to indent footnotes.  See
+<a href="docelement.html#footnote">FOOTNOTE</a>.
+</p>
+
+<p class="tip-bottom">
+<span class="additional-note">Additional note:</span>
+When REF is used with
+<a href="#footnote-refs">FOOTNOTE_REFS</a>
+or
+<a href="#endnote-refs">ENDNOTE_REFS</a>,
+it behaves identically to
+<a href="docelement.html#footnote">FOOTNOTE</a>
+or
+<a href="docelement.html#footnote">ENDNOTE</a>,
+so please read the HYPER IMPORTANT NOTE found in the document entry
+for
+<a href="docelement.html#footnote-note">FOOTNOTE</a>
+and/or
+<a href="docelement.html#endnote-note">ENDNOTE</a>.
+</p>
+</div>
+
+<!-- -FOOTNOTE_REFS- -->
+
+
+<div class="macro-id-overline">
+<h3 id="footnote-refs" class="macro-id">Instruct mom to put REFs in 
footnotes</h3>
+</div>
+
+<div class="box-macro-args">
+Macro: <b>FOOTNOTE_REFS</b>
+</div>
+
+<p>
+FOOTNOTE_REFS is an instruction to
+<a href="#ref">REF</a>,
+saying, &#8220;put all subsequent references bracketed by the REF
+macro into footnotes.&#8221; You invoke it by itself, with no
+argument.
+</p>
+
+<p>
+When FOOTNOTE_REFS is in effect, regular footnotes, (i.e.
+those introduced with <kbd>.FOOTNOTE</kbd> and terminated with
+<kbd>.FOOTNOTE OFF</kbd>) continue to behave normally.
+</p>
+
+<p>
+You may switch between FOOTNOTE_REFS and
+<a href="#endnote-refs">ENDNOTE_REFS</a>
+at any time.
+</p>
+
+<p>
+If you have a lot of footnote references, and are identifying
+footnotes by line number rather than by markers in the text, you may
+want to enable
+<a href="docelement.html#footnotes-run-on">FOOTNOTES_RUN_ON</a>
+in conjunctions with FOOTNOTE_REFS.
+</p>
+
+<!-- -ENDNOTE_REFS- -->
+
+<div class="macro-id-overline">
+<h3 id="endnote-refs" class="macro-id">Instruct REF to put references in 
endnotes</h3>
+</div>
+
+<div class="box-macro-args">
+Macro: <b>ENDNOTE_REFS</b>
+</div>
+
+<p>
+ENDNOTE_REFS is an instruction to
+<a href="#ref">REF</a>,
+saying, &#8220;add all subsequent references bracketed by the REF
+macro to endnotes.&#8221; You invoke it by itself, with no argument.
+</p>
+
+<p>
+When ENDNOTE_REFS is in effect, mom continues to format regular
+endnotes, (i.e. those introduced with <kbd>.ENDNOTE</kbd> and
+terminated with <kbd>.ENDNOTE OFF</kbd>) in the normal way.
+</p>
+
+<p>
+You may switch between ENDNOTE_REFS and
+<a href="#footnote-refs">FOOTNOTE_REFS</a>
+at any time.
+</p>
+
+<!-- -BRACKET_REFS- -->
+
+<div class="macro-id-overline">
+<h3 id="bracket-refs" class="macro-id">Embed references in the text</h3>
+</div>
+
+<div id="bracket-refs-parens" class="box-macro-args">
+Macro pair: <b>REF(</b>&nbsp;&nbsp;...&nbsp;&nbsp;<b>REF)</b>
+</div>
+
+<div id="bracket-refs-brackets" class="box-macro-args" style="margin-top: 
1em;">
+Macro pair: <b>REF[</b>&nbsp;&nbsp;...&nbsp;&nbsp;<b>REF]</b>
+</div>
+
+<div id="bracket-refs-braces" class="box-macro-args" style="margin-top: 1em;">
+Macro pair: <b>REF{</b>&nbsp;&nbsp;...&nbsp;&nbsp;<b>REF}</b>
+</div>
+
+<p>
+You may sometimes want to embed references directly into the
+body of your document, typically, but not always, inside
+parentheses.  Mom makes this possible through the use of the
+<b>REF&lt;bracket&nbsp;type&gt;</b> macros.
+</p>
+
+<p>
+All three macro pairs, above, are invoked the same way, namely
+by introducing the reference with the first (&#8220;open&#8221;)
+macro of the <b>REF&lt;bracket&nbsp;type&gt;</b>
+pair, and terminating it with the second (&#8220;close&#8221;)
+<b>REF&lt;bracket&nbsp;type&gt;</b> of the pair.  For
+example
+<br/>
+<span class="pre-in-pp">
+  .REF(
+  .[
+  keyword(s)
+  .]
+  .REF)
+</span>
+will embed a reference in the body of your document, surrounded
+by parentheses. <b>.REF[</b>&nbsp;...&nbsp;<b>.REF]</b>
+will surround the reference with square brackets.
+<b>.REF{</b>&nbsp;...&nbsp;<b>.REF}</b> will surround it with curly
+braces.
+</p>
+
+<!-- -INDENT_REFS- -->
+
+<div class="macro-id-overline">
+<h3 id="indent-refs" class="macro-id">Manage the second-line indent of 
references, per MLA standards</h3>
+</div>
+
+<div class="box-macro-args">
+Macro: <b>INDENT_REFS</b> <kbd class="macro-args">FOOTNOTE | ENDNOTE | BIBLIO 
&lt;indent&gt; </kbd>
+</div>
+
+<p class="requires">
+&bull;&nbsp;<kbd style="font-style: normal;">&lt;indent&gt;</kbd> requires a 
<a href="definitions.html#unitofmeasure">unit of measure</a>
+</p>
+
+<p>
+Proper MLA-style references should have their second, and subsequent
+lines, if any, indented.  Since mom formats references in MLA style,
+she automatically indents second lines.  By default, the indent for
+the second line of references, regardless of whether the references
+appear in footnotes, endnotes, or bibliographies, is 1.5
+<a href="definitions.html#em">ems</a>
+for
+<a href="docprocessing.html#printstyle">PRINSTYLE <kbd>TYPESET</kbd></a>
+and 2 ems for
+<a href="docprocessing.html#printstyle">PRINSTYLE <kbd>TYPEWRITE</kbd></a>.
+</p>
+
+<p>
+If you&#8217;d like to change the 2nd-line indent for footnotes,
+endnotes or bibliographies, just invoke <kbd>.INDENT_REFS</kbd>
+with a first argument telling mom for which (footnote, endnote, or
+bibliography) you want the indent changed, and a second argument
+saying what you&#8217;d like the indent to be.  For example, if you
+want the second-line indent of references on a bibliography page to
+be 3
+<a href="definitions.html#picas-points">picas</a>,
+<br/>
+<span class="pre-in-pp">
+  .INDENT_REFS BIBLIO 3P
+</span>
+is how you&#8217;d set it up.
+</p>
+
+<div class="box-tip">
+<p class="tip-top">
+<span class="tip">Tip:</span>
+If you are identifying endnotes by line number
+(<a 
href="docelement.html#endnote-marker-style">ENDNOTE_MARKER_STYLE&nbsp;<kbd>LINE</kbd></a>)
+and have instructed mom to put references bracketed by
+<kbd><a href="#ref">.REF</a></kbd>
+into endnotes (with
+<a href="#endnote-refs">ENDNOTE_REFS</a>),
+you will almost certainly want to adjust the second-line indent for
+references in endnotes, owing to the way mom formats line-numbered
+endnotes.  Study the output of such documents to see whether an
+indent adjustment is required.
+</p>
+
+<p>
+The same advice applies to references in endnotes when you have enabled
+<br/>
+<span class="pre-in-pp">
+  <a 
href="docelement.html#endnote-numbers-align-left">.ENDNOTE_NUMBERS_ALIGN_LEFT</a>
+</span>
+in favour of mom&#8217;s default, which is to align them right.
+Study the output to determine what size of second-line indent works
+best.
+</p>
+
+<p class="tip-bottom">
+<i>(Frankly, endnote references formatted in MLA-style combined with
+left-aligned endnote numbers is a no-win situation, and so is best
+avoided.  Wherever you set the indent, you&#8217;ll end up with the
+endnote numbers appearing to hang into the left margin, so you might
+as well have them hang, as is the case with
+<kbd style="font-style: 
normal;">.ENDNOTE_NUMBERS_ALIGN_RIGHT</kbd>.</i>&nbsp;&nbsp;&ndash;&nbsp;Ed.)
+</p>
+</div>
+
+<!-- -HYPHENATE_REFS- -->
+
+<div class="macro-id-overline">
+<h3 id="hyphenate-refs" class="macro-id">Enable/disable hyphenation of 
references</h3>
+</div>
+
+<div class="box-macro-args">
+Macro: <b>HYPHENATE_REFS</b> <kbd class="macro-args">&lt;toggle&gt;</kbd>
+</div>
+
+<p>
+If you have hyphenation turned on for a document (see
+<a href="typesetting.html#hy">HY</a>),
+and in most cases you probably do, mom will hyphenate references
+bracketed by the
+<a href="#ref">REF</a>
+macro.  Since references typically contain quite a lot of proper
+names, which shouldn&#8217;t be hyphenated, you may want to disable
+hyphenation for references.
+</p>
+
+<p>
+HYPHENATE_REFS is a toggle macro; invoking it by itself will turn
+automatic hyphenation of REF-bracketed references on (the default).
+Invoking it with any other argument (<kbd>OFF, NO, X</kbd>, etc.)
+will disable automatic hyphenation for references bracketed by REF.
+</p>
+
+<p>
+An alternative to turning reference hyphenation off is to prepend
+to selected proper names in your <kbd>refer</kbd> database
+the groff
+<a href="definitions.html#discretionaryhyphen">discretionary hyphen</a>
+character, <kbd>\%</kbd>.  (See
+<a href="#ref-disc-hy">here</a>
+in the tutorial for an example.)
+</p>
+
+<div class="box-tip">
+<p class="tip">
+<span class="note">Note:</span>
+References embedded in the body of a document with
+<kbd><a href="#bracket-refs">.REF &lt;bracket&nbsp;type&gt;</a></kbd>
+are considered part of
+<a href="definitions.html#running">running text</a>,
+and are hyphenated (or not) according to whether hyphenation is
+turned on or off for running text.  Therefore, if you want to
+disable hyphenation for such references, you must do so temporarily,
+with
+<a href="typesetting.html#hy">HY</a>,
+like this:
+<br/>
+<span class="pre-in-pp">
+  .HY OFF
+  .REF(
+  .[
+  keyword(s)
+  .]
+  .REF)
+  .HY
+</span>
+Alternatively, sprinkle your database fields liberally with
+<kbd>\%</kbd>.
+</p>
+</div>
+
+<!-- -BIBLIOGRAPHY- -->
+
+<div class="macro-id-overline">
+<h3 id="bibliography" class="macro-id">Begin a bibliography</h3>
+</div>
+
+<div class="box-macro-args">
+Macro: <b>BIBLIOGRAPHY</b>
+</div>
+
+<p>
+If you want to append a bibliography to your document, all you need
+do is invoke <kbd>.BIBLIOGRAPHY</kbd> at the place you want it.
+<kbd>.BIBLIOGRAPHY</kbd> breaks to a new page, prints the title
+(BIBLIOGRAPHY by default, but that can be changed), and awaits
+<kbd>refer</kbd> instructions.  How to create bibliographies is
+covered in the tutorial section,
+<a href="#biblio-ref">Creating bibliography pages</a>.
+</p>
+
+<p>
+See the
+<a href="#biblio-control">Bibliography control macros and defaults</a>
+for macros to tweak, design and control the appearance of
+bibliography pages.
+</p>
+
+<!-- -BIBLIOGRAPHY_TYPE- -->
+
+<div class="macro-id-overline">
+<h3 id="bibliography-type" class="macro-id">Plain, or numbered list 
bibliography</h3>
+</div>
+
+<div class="box-macro-args">
+Macro: <b>BIBLIOGRAPHY_TYPE</b> <kbd class="macro-args">PLAIN | LIST [ 
&lt;list separator&gt; ] [ &lt;list prefix&gt; ]</kbd>
+</div>
+
+<p>
+Mom offers two styles of bibliography output: plain, or numbered
+list style.  With the argument, <kbd>PLAIN</kbd>, bibliography entries are 
output
+with no enumerators.  With the argument, <kbd>LIST</kbd>, each entry is 
numbered.
+</p>
+
+<p>
+The two optional arguments, <kbd>&lt;list&nbsp;separator&gt;</kbd>
+and <kbd>&lt;list&nbsp;prefix&gt;</kbd> have the same meaning as the
+equivalent arguments to
+<a href="docelement.html#list">LIST</a>
+(i.e. <kbd>&lt;separator&gt;</kbd> and <kbd>&lt;prefix&gt;</kbd>).
+</p>
+
+<p>
+You may enter the BIBLIOGRAPHY_TYPE either before or after
+<kbd>.BIBLIOGRAPHY</kbd>.  It must, however, always come before
+the <kbd>refer</kbd> command to output bibliographies.  (See the
+tutorial section,
+<a href="#biblio-ref">Creating bibliography pages</a>,
+for instructions on how to output bibliographies.)
+</p>
+
+<p>
+Mom&#8217;s default BIBLIOGRAPHY_TYPE is LIST, with a period (dot)
+as the separator, and no prefix.
+</p>
+
+<!-- -BIBLIO_CONTROL- -->
+
+<div class="defaults-container" style="background-color: #ded4bd; border: 
none;">
+<h3 id="biblio-control" class="docs defaults">Bibliography control macros and 
defaults</h3> 
+
+<p style="margin-top: .25em; margin-left: 9px;">
+Mom processes bibliography pages in a manner very similar to the
+way she processes endnotes pages.  The bibliography page control
+macros, therefore, behave in the same way as their endnotes pages
+equivalents.
+</p>
+
+<ol style="margin-top: -.5em; padding-bottom: .5em;">
+  <li><a href="#biblio-general"><b>General bibliography style control</b></a>
+  <ul style="margin-left: -.5em;">
+    <li><a href="#biblio-style">Base family/font/quad</a></li>
+    <li><a href="#biblio-pt-size">Base point size</a></li>
+    <li><a href="#biblio-lead">Leading</a></li>
+    <li><a href="#biblio-spacing">Adjust the space between bibliography 
entries</a></li>
+    <li><a href="#singlespace-biblio">Singlespace bibliographies (for 
TYPEWRITE only)</a></li>
+    <li><a href="#biblio-no-columns">Turning off column mode during 
bibliography output</a></li>
+  </ul></li>
+  <li><a href="#biblio-pagination"><b>Pagination of bibliographies</b></a>
+  <ul style="margin-left: -.5em;">
+    <li><a href="#biblio-pagenum-style">Page numbering style</a></li>
+    <li><a href="#biblio-first-pagenumber">Setting the first page number of 
bibliographies</a></li>
+    <li><a href="#biblio-no-first-pagenum">Omitting a page number on the first 
page of bibliographies</a></li>
+    <li><a href="#suspend-pagination">Suspending pagination during 
bibliography output</a></li>
+  </ul></li>
+  <li><a href="#biblio-header-control"><b>Header/footer control</b></a>
+  <ul style="margin-left: -.5em;">
+    <li><a href="#biblio-modify-hdrftr">Modifying what goes in bibliography 
headers/footers</a></li>
+    <li><a href="#biblio-hdrftr-center">Header/footer centre string when 
doctype is CHAPTER</a></li>
+    <li><a href="#biblio-allows-headers">Allow headers on bibliography 
pages</a></li>
+  </ul></li>
+  <li><a href="#biblio-main-title"><b>Bibliography first-page title 
control</b></a>
+  <ul>
+    <li><a href="#biblio-string">Title string</a></li>
+    <li><a href="#biblio-string-control">Title string control macros and 
defaults</a></li>
+    <li><a href="#biblio-string-placement">Title string placement</a></li>
+    <li><a href="#biblio-string-underline">Title string underscoring</a></li>
+    <li><a href="#biblio-string-caps">Title string capitalization</a></li>
+  </ul></li>
+</ol>
+</div>
+
+<h4 id="biblio-general" class="docs" style="margin-top: -1.5em; margin-bottom: 
.5em;">1. General bibliography page style control</h4>
+
+<h5 id="biblio-style" class="docs" style="margin-top: 0; margin-bottom: .5em; 
margin-left: .5em;">&bull;&nbsp;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">
+.BIBLIOGRAPHY_FAMILY    default = prevailing document family; default is Times 
Roman
+.BIBLIOGRAPHY_FONT      default = roman
+.BIBLIOGRAPHY_QUAD*     default = justified
+
+*Note: BIBLIOGRAPHY_QUAD must be set to either L (LEFT) or J (JUSTIFIED);
+ R (RIGHT) and C (CENTER) will not work.
+</span>
+</div>
+
+<!-- -BIBLIO_PT_SIZE- -->
+
+<h5 id="biblio-pt-size" class="docs" style="margin-top: -1.5em; margin-bottom: 
.5em; margin-left: .5em;">&bull;&nbsp;Base point size</h5>
+
+<div class="box-macro-args">
+Macro: <b>BIBLIOGRAPHY_PT_SIZE</b> <kbd class="macro-args">&lt;base type size 
of bibliography&gt;</kbd>
+</div>
+
+<p>
+Unlike most other control macros that deal with size of document
+elements, BIBLIOGRAPHY_PT_SIZE takes as its argument an absolute
+value, relative to nothing.  Therefore, the argument represents the
+size of bibliography 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">
+  .BIBLIOGRAPHY_PT_SIZE 12
+</span>
+sets the base point size of type on the bibliography page to 12
+points, whereas
+<br/>
+<span class="pre-in-pp">
+  .BIBLIOGRAPHY_PT_SIZE .6i
+</span>
+sets the base point size of type on the bibliography page to 1/6 of an
+inch.
+</p>
+
+<p>
+The type size set with BIBLIOGRAPHY_PT_SIZE is the size of type used
+for the text of the bibliographies, and forms the basis from which
+the point size of other bibliography 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>
+
+<!-- -BIBLIO_LEAD- -->
+
+<h5 id="biblio-lead" class="docs" style="margin-top: -.5em; margin-bottom: 
.5em; margin-left: .5em;">&bull;&nbsp;Leading</h5>
+
+<div class="box-macro-args">
+Macro: <b>BIBLIOGRAPHY_LEAD</b> <kbd class="macro-args">&lt;base leading of 
bibliographies&gt; [ ADJUST ]</kbd>
+</div>
+
+<p class="requires">
+&bull;&nbsp;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, BIBLIOGRAPHY_LEAD takes as its argument an absolute value,
+relative to nothing.  Therefore, the argument represents the
+<a href="definitions.html#leading">leading</a>
+of bibliographies 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">
+  .BIBLIOGRAPHY_LEAD 14
+</span>
+sets the base leading of type on the bibliography page to 14
+points, whereas
+<br/>
+<span class="pre-in-pp">
+  .BIBLIOGRAPHY_LEAD .5i
+</span>
+sets the base leading of type on the bibliography page to 1/2 inch.
+</p>
+
+<p>
+If you want the leading of bibliographies adjusted to fill the page,
+pass BIBLIOGRAPHY_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&nbsp;OFF</kbd> command,
+she will still, by default, adjust bibliography leading.  You
+<i>must</i> enter <kbd>BIBLIOGRAPHY_LEAD&nbsp;&lt;lead&gt;</kbd>
+with no <kbd>ADJUST</kbd> argument to disable this default
+behaviour.
+</p>
+</div>
+
+<!-- -BIBLIO_SPACING- -->
+
+<h5 id="biblio-spacing" class="docs" style="margin-top: -.5em; margin-bottom: 
.5em; margin-left: .5em;">&bull;&nbsp;Adjust the space between bibliography 
entries</h5>
+
+<div class="box-macro-args">
+Macro: <b>BIBLIOGRAPHY_SPACING</b> <kbd class="macro-args">&lt;amount of 
space&gt; </kbd>
+</div>
+
+<p class="requires">
+&bull;&nbsp;Requires a <a href="definitions.html#unitofmeasure">unit of 
measure</a>
+</p>
+
+<p>
+By default, mom inserts a linespace between bibliography entries.
+If you&#8217;d prefer she add a different amount of space, instruct
+her to do so with BIBLIOGRAPHY_SPACING.  Say, for example,
+you&#8217;d prefer only 1/2 linespace,
+<br/>
+<span class="pre-in-pp">
+  .BIBLIOGRAPHY_SPACING .5v
+</span>
+would do the trick.
+</p>
+
+Note:
+<div class="box-tip">
+<p class="tip">
+<span class="note">Note:</span>
+As with endnotes pages, owing to the space inserted between
+bibliography entries, bibliography pages may have hanging
+bottom margins.  Unlike endnotes pages, mom
+is sad to report that there&#8217;s nothing you can do about
+this, except a) pray things work out, or b) set your
+BIBLIOGRAPHY_SPACING to zero.
+</p>
+</div>
+
+<!-- -SINGLESPACE_BIBLIO- -->
+
+<h5 id="singlespace-biblio" class="docs" style="margin-top: -.5em; 
margin-bottom: .5em; margin-left: .5em;">&bull;&nbsp;Singlespace bibliography 
(TYPEWRITE only)</h5>
+
+<div class="box-macro-args">
+Macro: <b>SINGLESPACE_BIBLIOGRAPHY</b> <kbd 
class="macro-args">&lt;toggle&gt;</kbd>
+</div>
+
+<p>
+If your 
+<a href="docprocessing.html#printstyle">PRINTSTYLE</a>
+is <kbd>TYPEWRITE</kbd> and you use TYPEWRITE&#8217;s default
+double-spacing, bibliographies are double-spaced.  If your document
+is single-spaced, bibliographies are single-spaced.
+</p>
+
+<p>
+If, for some reason, you&#8217;d prefer that bibliographies be
+single-spaced in an otherwise double-spaced document (including
+double-spaced
+<a href="rectoverso.html#collate">collated</a>
+documents), invoke <kbd>.SINGLESPACE_BIBLIOGRAPHY</kbd> with with no
+argument.
+</p>
+
+<!-- -BIBLIO_NO_COLUMNS- -->
+
+<h5 id="biblio-no-columns" class="docs" style="margin-top: -.5em; 
margin-bottom: .5em; margin-left: .5em;">&bull;&nbsp;Turning off column mode 
during bibliography output</h5>
+
+<div class="box-macro-args">
+Macro: <b>BIBLIOGRAPHY_NO_COLUMNS</b> <kbd 
class="macro-args">&lt;toggle&gt;</kbd>
+</div>
+
+<p>
+By default, if your document is set in
+<a href="docprocessing.html#columns">columns</a>,
+mom sets the bibliographies in columns, too.  However, if your
+document is set in columns and you&#8217;d like the bibliographies
+not to be, just invoke <kbd>.BIBLIOGRAPHY_NO_COLUMNS</kbd> with
+no argument.  The bibliography pages will be set to the full page
+measure of your document.
+</p>
+
+<p>
+If you output bibliographies 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 BIBLIOGRAPHY_NO_COLUMNS
+turned on.  In such circumstances, you must re-enable
+ENDNOTES_NO_COLUMNS for each separate collated document.
+</p>
+
+<h4 id="biblio-pagination" class="docs" style="margin-bottom: .5em;">2. 
Pagination of bibliographies</h4>
+
+<!-- -BIBLIO_PAGENUM_STYLE- -->
+
+<h5 id="biblio-pagenum-style" class="docs" style="margin-top: 0; 
margin-bottom: .5em; margin-left: .5em;">&bull;&nbsp;Page numbering style</h5>
+
+<div class="box-macro-args">
+Macro: <b>BIBLIOGRAPHY_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 bibliography
+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">
+  .BIBLIOGRAPHY_PAGENUM_STYLE alpha
+</span>
+</p>
+
+<!-- -BIBLIO_FIRST_PAGENUMBER- -->
+
+<h5 id="biblio-first-pagenumber" class="docs" style="margin-top: -.5em; 
margin-bottom: .5em; margin-left: .5em;">&bull;&nbsp;Setting the first page 
number of bibliographies</h5>
+
+<div class="box-macro-args">
+Macro: <b>BIBILOGRAPHY_FIRST_PAGENUMBER</b> <kbd class="macro-args">&lt;page # 
that appears on page 1 of bibliographies&gt;</kbd>
+</div>
+
+<p>
+Use this macro with caution.  If the bibliography for a
+<a href="rectoverso.html#collate">collated</a>
+document is to be output at the document's end,
+BIBLIOGRAPHY_FIRST_PAGENUMBER tells mom what page number to put on
+the first page of the bibliography.
+</p>
+
+<p>
+However, if you're outputting a bibliography at the end of each
+section (chapter, article, etc) of a collated document,
+you have to reset every section&#8217;s first page number after
+<a href="rectoverso.html#collate">COLLATE</a>
+and before
+<a href="docprocessing.html#start">START</a>.
+</p>
+
+<!-- -BIBLIO_NO_FIRST_PAGENUN- -->
+
+<h5 id="biblio-no-first-pagenum" class="docs" style="margin-top: -.25em; 
margin-bottom: .5em; margin-left: .5em;">&bull;&nbsp;Omitting a page number on 
the first page of bibliographies</h5>
+
+<div class="box-macro-args">
+Macro: <b>BIBLIOGRAPHY_NO_FIRST_PAGENUM</b> <kbd 
class="macro-args">&lt;toggle&gt;</kbd>
+</div>
+
+<p>
+This macro is for use only if
+<a href="headfootpage.html#footers">FOOTERS</a>
+are on.  It tells
+<kbd><a href="#bibliography">BIBLIOGRAPHY</a></kbd>
+not to print a page number on the first bibliography page.
+Mom&#8217;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;">&bull;&nbsp;Suspending pagination 
during bibliography 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&#8217;t take an argument.  Invoked
+immediately prior to
+<kbd><a href="#bibliography">BIBLIOGRAPHY</a></kbd>,
+it turns off pagination for the duration of the bibliography.  Mom
+continues, however to increment page numbers silently.
+</p>
+
+<p>
+To restore normal document pagination after bibliographies, invoke
+<kbd>.RESTORE_PAGINATION</kbd> (again, with no argument) immediately
+after you&#8217;ve finished with your bibliography.
+</p>
+
+<h4 id="biblio-header-control" class="docs" style="margin-bottom: .5em;">3. 
Header/footer control</h4>
+
+<h5 id="biblio-modify-hdrftr" class="docs" style="margin-top: 0; 
margin-bottom: .5em; margin-left: .5em;">&bull;&nbsp;Modifying what goes in the 
bibliography header/footer</h5>
+
+<p>
+If you wish to modify what appears in the header/footer that appears
+on bibliography pages, make the changes before you invoke
+<a href="#bibliography"><kbd>.BIBLIOGRAPHY</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 bibliography pages.  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 bibliography pages headers/footers, invoke
+<kbd><a 
href="#bibliography-hdrftr-center">.BIBLIOGRAPHY_HEADER_CENTER</a></kbd>
+with no argument. 
+</p>
+
+<p>
+An important change you may want to make is to put the word
+&#8220;Bibliography&#8221; 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>.BIBLIOGRAPHY</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">BIBLIOGRAPHY_HEADER_CENTER</a>
+for the BIBLIOGRAPHY_HEADER_CENTER to appear.
+</p>
+</div>
+
+<h5 id="biblio-hdrftr-center" class="docs" style="margin-top: 0; 
margin-bottom: .5em; margin-left: .5em;">&bull;&nbsp;Header/footer centre 
string when doctype is CHAPTER</h5>
+
+<div class="box-macro-args">
+Macro: <b>BIBLIOGRAPHY_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 bibliography
+pages, invoke <kbd>.BIBLIOGRAPHY_HEADER_CENTER</kbd> (or
+<kbd>.BIBLIOGRAPHY_FOOTER_CENTER</kbd>) with no argument.
+Mom&#8217;s default is NOT to print the centre string.
+</p>
+
+<p>
+If, for some reason, having enabled the header/footer centre string
+on bibliography pages, you wish to disable it, invoke the same macro
+with any argument (<kbd>OFF, QUIT, Q, X</kbd>...).
+</p>
+
+<h5 id="biblio-allows-headers" class="docs" style="margin-top: -.5em; 
margin-bottom: .5em; margin-left: .5em;">&bull;&nbsp;Allow headers on 
bibliography pages</h5>
+
+<div class="box-macro-args">
+Macro: <b>BIBLIOGRAPHY_ALLOWS_HEADERS</b> <kbd class="macro-args">&lt;none&gt; 
| ALL</kbd>
+</div>
+
+<p>
+By default, if HEADERS are on, mom prints page headers on all
+bibliography pages except the first.  If you don&#8217;t want her to
+print headers on bibliography pages, do
+<br/>
+<span class="pre-in-pp">
+  .BIBLIOGRAPHY_ALLOWS_HEADERS OFF
+</span>
+If you want headers on every page including the first, do
+<br/>
+<span class="pre-in-pp">
+  .BIBLIOGRAPHY_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 bibliography page.
+This is a style convention.  In mom, there is no such beast as
+BIBLIOGRAPHY_ALLOWS_FOOTERS OFF.
+</p>
+</div>
+
+<h4 id="biblio-main-title" class="docs">4. Bibliography first-page title 
control</h4>
+
+<!-- -BIBLIO_STRING- -->
+
+<h5 id="biblio-string" class="docs" style="margin-top: 1em; margin-bottom: 
.5em; margin-left: .5em;">&bull;&nbsp;Title string</h5>
+
+<div class="box-macro-args">
+Macro: <b>BIBLIOGRAPHY_STRING</b> <kbd class="macro-args">&quot;&lt;title to 
print at the top of bibliography pages&gt;&quot;</kbd>
+</div>
+
+<p>
+By default, mom prints the word &#8220;BIBLIOGRAPHY&#8221; as a title
+at the top of the first page of a bibliography.  If you want her to
+print something else, invoke <kbd>.BIBLIOGRAPHY_STRING</kbd> with
+the title you want, surrounded by double-quotes.
+</p>
+
+<p>
+If you don&#8217;t want a title at the top of the first bibliography
+page, invoke <kbd>.BIBLIOGRAPHY_STRING</kbd> with a blank argument
+(either two double-quotes side by
+side&mdash;<kbd>&quot;&quot;</kbd>&mdash;or no argument at all).
+</p>
+
+<!-- -BIBLIO_STRING_CONTROL- -->
+
+<h5 id="biblio-string-control" class="docs" style="margin-top: -.5em; 
margin-bottom: .5em; margin-left: .5em;">&bull;&nbsp;Title 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">
+.BIBLIOGRAPHY_STRING_FAMILY  default = prevailing document family; default is 
Times Roman
+.BIBLIOGRAPHY_STRING_FONT    default = bold
+.BIBLIOGRAPHY_STRING_SIZE*   default = +1
+.BIBLIOGRAPHY_STRING_QUAD    default = centred
+
+*Relative to the size of the bibliography text (set with BIBLIOGRAPHY_PT_SIZE)
+</span>
+</div>
+
+<!-- -BIBLIOGRAPHY_STRING_ADVANCE- -->
+
+<h5 id="biblio-string-placement" class="docs" style="margin-top: -1em; 
margin-bottom: .5em; margin-left: .5em;">&bull;&nbsp;Title string placement</h5>
+
+<div class="box-macro-args">
+Macro: <b>BIBLIOGRAPHY_STRING_ADVANCE</b> <kbd class="macro-args">&lt;distance 
from top of page&gt;</kbd>
+</div>
+
+<p class="requires">
+&bull;&nbsp;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
+bibliographies (typically "BIBLIOGRAPHY") 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&#8217;d prefer another location, higher or lower on the page
+(thereby also raising or lowering the starting position of the
+bibliography itself), invoke <kbd>.BIBLIOGRAPHY_STRING_ADVANCE</kbd>
+with an argument stating the distance from the top edge of the page
+at which you&#8217;d like the title placed.
+</p>
+
+<p>
+The argument requires a unit of measure, so if you&#8217;d like the title
+to appear 1-1/2 inches from the top edge of the page, you&#8217;d tell
+mom about it like this:
+<br/>
+<span class="pre-in-pp">
+  .BIBLIOGRAPHY_STRING_ADVANCE 1.5i
+</span>
+</p>
+
+<!-- -BIBLIO_STRING_UNDERLINE- -->
+
+<h5 id="biblio-string-underline" class="docs" style="margin-top: -1em; 
margin-bottom: .5em; margin-left: .5em;">&bull;&nbsp;Title string 
underscoring</h5>
+
+<div class="box-macro-args">
+Macro: <b>BIBLIOGRAPHY_STRING_UNDERSCORE</b> <kbd class="macro-args">[DOUBLE] 
[&lt;underline weight&gt; [&lt;underline gap&gt; [&lt;distance between double 
rules]]] | &lt;none&gt; | &lt;anything&gt;</kbd>
+</div>
+
+<p class="alias" style="margin-bottom: 0;">
+<i>Alias:</i> <b>BIBLIOGRAPHY_STRING_UNDERLINE</b>
+</p>
+
+<p class="requires">
+&bull;&nbsp;The argument
+<span style="font-style: normal"><kbd>&lt;underscore weight&gt;</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
+</p>
+
+<p>
+Invoked without an argument,
+<kbd>.BIBLIOGRAPHY_STRING_UNDERSCORE</kbd> will place a single rule
+underneath the bibliography's first-page title.  Invoked with the
+argument, <kbd>DOUBLE</kbd>, BIBLIOGRAPHY_STRING_UNDERSCORE will
+double-underscore the thtile.  Invoked with any other non-numeric
+argument, (e.g. <kbd>OFF, NO, X</kbd>, etc.) the macro disables
+underlining of the title.
+</p>
+
+<p>
+In addition, you can use BIBLIOGRAPHY_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">
+  .BIBLIOGRAPHY_STRING_UNDERLINE 1
+      - turn underlining on; set the rule weight to 1 point
+
+  .BIBLIOGRAPHY_STRING_UNDERLINE 1 3p
+      - turn underlining on; set the rule weight to 1 point; set
+        the gap between the string and the underline to 3 points
+  
+  .BIBLIOGRAPHY_STRING_UNDERLINE DOUBLE .75 3p
+      - turn double-underlining on; set the rule weight to 3/4 of
+        a point; set the gap between the string and the upper
+        underline to 3 points; leave the gap between the upper
+        and the lower underline at the default
+  
+  .BIBLIOGRAPHY_STRING_UNDERLINE DOUBLE 1.5 1.5p 1.5p
+      - turn double-underlining on; set the rule weight to 1-1/2
+        points; set the gap between the string and the upper
+        underline to 1-1/2 points; set the gap between the upper
+        and the lower underline to 1-1/2 points
+</span>
+Note, from the above, that in all instances, underscoring (single or
+double) is enabled whenever BIBLIOGRAPHY_STRING_UNDERSCORE is used
+in this way.
+</p>
+
+<p>
+Mom&#8217;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>
+
+<!-- -BIBLIO_STRING_CAPS- -->
+
+<h5 id="biblio-string-caps" class="docs" style="margin-top: -.5em; 
margin-bottom: .5em; margin-left: .5em;">&bull;&nbsp;Title string 
capitalization</h5>
+
+<div class="box-macro-args">
+Macro: <b>BIBLIOGRAPHY_STRING_CAPS</b> <kbd class="macro-args">toggle</kbd>
+</div>
+
+<p>
+Invoked by itself, <kbd>.BIBLIOGRAPHY_STRING_CAPS</kbd> will
+automatically capitalize the bibliography first-page title.  Invoked
+with any other argument, the macro disables automatic capitalization
+of the title.
+</p>
+
+<p>
+If you&#8217;re generating a table of contents, you may want the
+bibliography first-page title to be in caps, but the toc entry in
+caps/lower case.  If the argument to
+<kbd><a href="#bibliography-string">BIBLIOGRAPHY_STRING</a></kbd>
+is in caps/lower case and BIBLIOGRAPHY_STRING_CAPS is
+on, this is exactly what will happen.
+</p>
+
+<p>
+Mom&#8217;s default is to capitalize the bibliography first-page
+title.
+</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="letters.html">Next: 
Writing letters</a></td>
+</tr>
+</table>
+
+</div>
+
+<div class="bottom-spacer"><br/></div>
+
+</body>
+</html>
+<!-- vim: fileencoding=utf-8: nomodified: -->

Index: reserved.html
===================================================================
RCS file: reserved.html
diff -N reserved.html
--- /dev/null   1 Jan 1970 00:00:00 -0000
+++ reserved.html       18 Aug 2010 22:45:36 -0000      1.39
@@ -0,0 +1,2658 @@
+<?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 -- Reserved words (macros, strings, registers)</title>
+  <link rel="stylesheet" type="text/css" href="stylesheet.css" />
+</head>
+
+<body style="background-color: #f5faff;">
+
+<!-- ==================================================================== -->
+
+<div id="top" class="page" style="width: 800px;">
+
+<!-- Navigation links -->
+<table style="width: 100%;">
+<tr>
+  <td><a href="toc.html">Back to Table of Contents</a></td>
+</tr>
+</table>
+
+<h1 id="reserved-words" class="docs">List of reserved words (macros, strings, 
registers)</h1>
+
+<p>
+The following is a list of reserved words used by mom.  Before
+changing the name of any macro or document element tag with
+<a href="goodies.html#ALIAS">ALIAS</a>,
+I strongly recommend doing a search of this page for your proposed
+new name.  If you find it in the left hand column, choose something
+else instead.
+</p>
+
+<p>
+Anyone interested in playing around inside mom&#8217;s macro file
+(om.tmac) will find this list useful as well since it lists all (I
+hope) the macros, strings, diversions, aliases and number registers
+mom uses, along with brief descriptions of their functions.
+</p>
+
+<div class="rule-medium"><hr/></div>
+
+<span class="pre" style="scroll: none;">
+<span style="display: block; text-decoration: underline;">TYPESETTING</span>
+<span style="display: block; margin-top: -1em;">+++MACROS+++</span>
+<span style="display: block; margin-top: -1em; margin-bottom: -1em;">*Page 
layout</span>
+  PAGELENGTH  Page width
+  PAGE        Page width/length; left, right, top, bottom margins
+  PAGEWIDTH   Page width
+  PAPER       Letter, legal, or A4
+  B_MARGIN    Space to leave at page bottom
+  L_MARGIN    Page offset
+  R_MARGIN    Line length as a function of
+                pagewidth minus pageoffset minus rightmargin
+  T_MARGIN    Advance lead from page top
+
+<span style="display: block; margin-top: -.75em; margin-bottom: -1em;">*Page 
control</span>
+  DO_B_MARGIN  Margin at bottom of page; trap-invoked
+  DO_T_MARGIN  Margin at top of page; trap-invoked
+
+<span style="display: block; margin-top: -.75em; margin-bottom: 
-1em;">*Style</span>
+  COLOR          Change color of text to predefined value
+  CONDENSE       Set percentage of pseudo-condense (alias of
+                   CONDENSE_OR_EXTEND)
+  EXTEND         Set percentage of pseudo-extend (alias of
+                   CONDENSE_OR_EXTEND)
+  FAMILY         Family
+  FT             Font
+  FALLBACK_FONT  Font to use whenever FAMILY or FT errors occur
+  LL             Line length
+  LS             Leading (.vs)
+  NEWCOLOR       Define a text color
+  PT_SIZE        Point size
+  SETBOLDER      Set degree of emboldening (pseudo-bold) in units
+  SETSLANT       Set degree of pseudo-italic
+  XCOLOR         Initialize a color from rgb.txt
+
+<span style="display: block; margin-top: -.75em; margin-bottom: 
-1em;">*Autolead</span>
+  AUTOLEAD  Always lead n points more than .PT_SIZE
+
+<span style="display: block; margin-top: -.75em; margin-bottom: -1em;">*Quad, 
fill, justification</span>
+  JUSTIFY  Justified text
+  QUAD     Filled text, left, right, or centre
+
+<span style="display: block; margin-top: -.75em; margin-bottom: -1em;">*Quad, 
no-fill</span>
+  CENTER  Line-for-line, non-filled text, centre
+  LEFT    Line-for-line, non-filled text, left
+  RIGHT   Line-for-line, non-filled text, right
+
+<span style="display: block; margin-top: -.75em; margin-bottom: 
-1em;">*Hyphenation</span>
+  HY      Turn hyphenation on/off, or set LINES, MARGIN, SPACE
+  HY_SET  Set LINES, MARGIN, SPACE in a single command
+
+<span style="display: block; margin-top: -.75em; margin-bottom: 
-1em;">*Advanced style</span>
+  KERN       Turn automatic kerning on or off
+  LIGATURES  Turn ligatures on or off
+  SS         Sentence space control
+  WS         Word space control
+
+<span style="display: block; margin-top: -.75em; margin-bottom: -1em;">*Line 
breaks</span>
+  BR      Alias of br
+  EL      Breaks line but doesn't advance
+  SPACE   Alias of sp
+  SPREAD  Alias of brp
+
+<span style="display: block; margin-top: -.75em; margin-bottom: 
-1em;">*Vertical motions</span>
+  ALD  Advance lead
+  RLD  Reverse lead
+
+<span style="display: block; margin-top: -.75em; margin-bottom: 
-1em;">*Indents</span>
+  HI   Indent hang
+  IB   Indent both
+  IBX  Indent both off
+  IL   Indent left
+  ILX  Indent left off
+  IQ   Indents off
+  IR   Indent right
+  IRX  Indent right off
+  IX   Indents off -- deprecated
+  TI   Indent temporary
+
+<span style="display: block; margin-top: -.75em; margin-bottom: 
-1em;">*Tabs</span>
+  ST       String tab
+  TAB_SET  Tab Set
+  TN       Tab Next
+  TQ       Tab Quit
+
+<span style="display: block; margin-top: -.75em; margin-bottom: 
-1em;">*Columnar tabs</span>
+  MCO      Turn on multi-column mode
+  MCR      Return to top of column
+  MCX      Turn off multi-column mode
+
+<span style="display: block; margin-top: -.75em; margin-bottom: 
-1em;">*Underscore</span>
+  UNDERSCORE   Underscores words or phrases
+  UNDERSCORE2  Double underscores words or phrases
+
+<span style="display: block; margin-top: -.75em; margin-bottom: 
-1em;">*Underline</span>
+  UNDERLINE  Underlines whole passages (Courier only)
+
+<span style="display: block; margin-top: -.75em; margin-bottom: -1em;">*Smart 
Quotes</span>
+  SMARTQUOTES  Turns smart quotes on or off
+
+<span style="display: block; margin-top: -.75em; margin-bottom: 
-1em;">*Graphical objects</span>
+  RULE_WEIGHT      Weight of rules drawn with \*[RULE]
+  DBX              Draw box
+  DCL              Draw circle (ellipse)
+  DRH              Draw horizontal rule
+  DRV              Draw vertical rule
+
+<span style="display: block; margin-top: -.75em; margin-bottom: -1em;">*Misc + 
Support</span>
+  BR_AT_LINE_KERN  Deposit a break before RW and WE
+  CAPS             Convert u/lc to UC
+  COMMENT          Don't print lines till COMMENT OFF (alias of SILENT)
+  DROPCAP_ADJUST   Points (poss. fractional) to add/subtract
+                     from drop caps
+  DROPCAP          Create drop cap
+  DROPCAP_FAMILY   Drop cap family
+  DROPCAP_FONT     Drop cap font
+  DROPCAP_GUTTER   Drop cap gutter
+  DROPCAP_OFF      Support only; restores .in if there was one
+  ESC_CHAR         Alias for .ec
+  EW               Extra white -- loosen overall line kern
+                     (character spacing)
+  LEADER_CHARACTER Sets leader character
+  PAD              Insert padding spaces at marked places
+  PADMARKER        Sets character to use instead of # in PAD
+  PRINT            Simply prints args passed to it; keeps my code
+                     indented nicely
+  RW               Reduce white -- tighten overall line kern
+                     (character spacing)
+  SILENT           Don't print lines till SILENT OFF
+  SIZESPECS        Get cap-height, x-height and descender depth for
+                     current point size
+  SUPERSCRIPT_RAISE_AMOUNT  Change default vertical displacement of 
superscripts
+  TRAP             Turn traps off or on
+
+<span style="display: block; margin-top: -.5em; margin-bottom: 
-2.5em;">+++DIVERSIONS+++</span>
+
+  NO_FLASH    Diverts output of SILENT or COMMENT so they don't print
+  NULL        Diverts SIZESPECS in PRINT_HDRFTR so it doesn't screw up
+                FOOTER and FOOTNOTE processing when FOOTERS are on
+  PAD_STRING  Divert