diff options
| author | PTPi <PTPi> | 2006-08-01 01:14:08 +0000 |
|---|---|---|
| committer | PTPi <PTPi> | 2006-08-01 01:14:08 +0000 |
| commit | c7a82e7c403ac6d34976e9a3bf694f01c88fd2b7 (patch) | |
| tree | a246be6c6f335a2326c5a6edbbc2735e45d4f7fc /contrib/mom | |
| parent | 881943fbf9c5daab7e8637fd9cf74a560a3a90f1 (diff) | |
| download | groff-c7a82e7c403ac6d34976e9a3bf694f01c88fd2b7.tar.gz | |
Re-added documentation files in their new xhtml format. Added a
new file, graphical.html.
Diffstat (limited to 'contrib/mom')
| -rw-r--r-- | contrib/mom/momdoc/appendices.html | 841 | ||||
| -rw-r--r-- | contrib/mom/momdoc/color.html | 493 | ||||
| -rw-r--r-- | contrib/mom/momdoc/cover.html | 646 | ||||
| -rw-r--r-- | contrib/mom/momdoc/definitions.html | 945 | ||||
| -rw-r--r-- | contrib/mom/momdoc/docelement.html | 6937 | ||||
| -rw-r--r-- | contrib/mom/momdoc/docprocessing.html | 3365 | ||||
| -rw-r--r-- | contrib/mom/momdoc/goodies.html | 1435 | ||||
| -rw-r--r-- | contrib/mom/momdoc/graphical.html | 578 | ||||
| -rw-r--r-- | contrib/mom/momdoc/headfootpage.html | 2229 | ||||
| -rw-r--r-- | contrib/mom/momdoc/inlines.html | 1048 | ||||
| -rw-r--r-- | contrib/mom/momdoc/intro.html | 502 | ||||
| -rw-r--r-- | contrib/mom/momdoc/letters.html | 547 | ||||
| -rw-r--r-- | contrib/mom/momdoc/macrolist.html | 458 | ||||
| -rw-r--r-- | contrib/mom/momdoc/rectoverso.html | 289 | ||||
| -rw-r--r-- | contrib/mom/momdoc/refer.html | 1801 | ||||
| -rw-r--r-- | contrib/mom/momdoc/reserved.html | 2664 | ||||
| -rw-r--r-- | contrib/mom/momdoc/toc.html | 447 | ||||
| -rw-r--r-- | contrib/mom/momdoc/typemacdoc.html | 299 | ||||
| -rw-r--r-- | contrib/mom/momdoc/typesetting.html | 5084 | ||||
| -rw-r--r-- | contrib/mom/momdoc/using.html | 283 |
20 files changed, 30891 insertions, 0 deletions
diff --git a/contrib/mom/momdoc/appendices.html b/contrib/mom/momdoc/appendices.html new file mode 100644 index 00000000..0827d5f7 --- /dev/null +++ b/contrib/mom/momdoc/appendices.html @@ -0,0 +1,841 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!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=iso-8859-1"/> +<title>Mom -- Appendices</title> +</head> +<body bgcolor="#dfdfdf"> + +<!-- ==================================================================== --> + +<a name="TOP"></a> + +<p> +<a href="reserved.html#TOP">Next</a> +<a href="macrolist.html#TOP">Prev</a> +<a href="toc.html">Back to Table of Contents</a> +</p> + +<a name="APPENDICES"><h2 align="center"><u>APPENDICES</u></h2></a> + +<ul> + <li><a href="#MOREDOC">Further notes on this documentation</a></li> + <li><a href="#FONTS">Adding PostScript fonts to groff</a></li> + <ul> + <li><a href="#HOWTO">How to create a PostScript font for use with groff</a></li> + </ul> + <li><a href="#CODENOTES">Some reflections on mom, with an apology</a></li> + <li><a href="#CONTACT">Contact the author</a></li> + <li><a href="reserved.html">List of reserved words</a></li> +</ul> + +<a name="MOREDOC"><h2><u>Further notes on this documentation</u></h2></a> + +<p> +Some <strong>mom</strong> users are sure to ask: "Why is this +documentation in html? If <strong>mom</strong>'s so great, why not +typeset the whole thing to show her off? And if groff's so great, +why not write a man page?" +</p> + +<p> +Valid questions, to be sure, and <strong>mom</strong> has +answers. (Okay — I have answers, but I speak for +<strong>mom</strong>.) +</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'd never +been able to with the printed word: instantly track down internal +and external references in a document. +</p> + +<p> +To me, it's essential that people reading <strong>mom</strong>'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> + +<p> +Another reason for html is that working with <strong>mom</strong> +necessarily involves creating files inside a text editor. I use +elvis, a truly fabulous vi clone that does a terrific job of rendering +basic (text only) html. I may have written <strong>mom</strong>, +but I still regularly call on her documentation. Elvis, with its +html capabilities, lets me write and format <strong>mom</strong> +documents AND peruse her documentation, clicking on links as +necessary, without ever leaving the comfy confines of my +text editor. +</p> + +<p> +Not everyone, of course, uses an editor with html capabilities. +For them, firing up a browser is obviously necessary for reading +<strong>mom</strong>'s documentation. Browsers being what they are, +and not everyone on the globe having the cash for muscle machines +to run Galeon, or Konqueror or Mozilla, their browser +needs to be fast and light — and probably "text-only". +</p> + +<p> +Some <strong>mom</strong> users may notice the absence of graphics, +frames, and (for the most part) tables in this documentation. The +reason is simple: text-only browsers. People who, for whatever +reason (choice or necessity), use lynx, or links or w3m to read +the documentation must be able to make sense of it. All of it. +Graphical examples of <strong>mom</strong> in action might have made +some parts of the documentation easier to write, but would have +excluded text-only browser users. And it goes without saying that +the documentation looks fine if you're reading it in a graphical +browser. +</p> + +<hr/> + +<!-- ===================================================================== --> + +<a name="FONTS"><h2><u>Adding PostScript fonts to groff</u></h2></a> + +<p> +Robert Valiant has set up a web page containing information, +instructions and strategies for adding PostScript and TrueType fonts +to <strong>groff</strong>. 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 + +<pre> + <a href="http://russia.shaps.hawaii.edu/software/software.html">http://russia.shaps.hawaii.edu/software/software.html</a> +</pre> +</p> + +<a name="SMALL_NOTE"></a> + +<p> +<em><strong>Small note:</strong> the term</em> +<kbd><prefix></kbd> <em>in this section refers to the +directory in which groff is installed, typically something +like</em> <kbd>/usr/share/groff/<version></kbd> <em>(for +distro-specific, pre-compiled groff packages) or</em> +<kbd>/usr/local/share/groff/<version></kbd> <em>(if you've +built groff from source).</em> +</p> + +<p> +Groff comes with a small library of PostScript +<a href="definitions.html#TERMS_FAMILY">families</a> +(see the +<a href="typesetting.html#FAMILY">FAMILY</a> +macro for a list). The families have four +<a href="definitions.html#TERMS_FONT">fonts</a> +associated with them. These fonts are a combination of +<a href="definitions.html#TERMS_WEIGHT">weight</a> +and +<a href="definitions.html#TERMS_SHAPE">shape</a>: + +<pre> + <strong>R</strong> (Roman, usually Medium weight), + <strong>I</strong> (Italic, usually Medium weight), + <strong>B</strong> (Bold, usually Roman shape) and + <strong>BI</strong> (Bold Italic) +</pre> +</p> + +<p> +If you do a lot of document processing or typesetting with +<strong>mom</strong>, you'll find, sooner or later, that these +families and their associated fonts aren't sufficient. You'll want +to supplement them, either with more fonts for the families already +provided — "Damn! I need Helvetica Bold Condensed +Italic!" — or with entire new families. +</p> + +<p> +Without going into the gory details (yet), while it'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's predefined <strong>R, +I, B</strong> and <strong>BI</strong> font styles. An example +of this can be seen in the groff PostScript font library itself +<nobr>(<prefix>/font/devps/):</nobr> there's one +"family" for Helvetica (HR, HI, HB, HBI) and another for +Helvetica Narrow (HNR, HNI, HNB, HNBI). +</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 +"the Helvetica family", s/he is including the +<a href="definitions.html#TERMS_WEIGHT">weights</a> +Helvetica Thin, Helvetic Light, Helvetica Regular, Helvetica Bold, +Helvetica Heavy, etc, and all their associated +<a href="definitions.html#TERMS_SHAPE">shapes</a> +(Roman, Italic, Condensed, Narrow, Extended, Outline, etc). +</p> + +<p> +Thus, intuitively, when a typesetter gives <strong>mom</strong> a +<kbd>.FAM(ILY)</kbd> directive, s/he reasonably expects that any +subsequent <kbd>.FT</kbd> directive will access the desired font +from the Helvetica family — 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 traditional approach would +require two "partial" 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 <nobr><kbd>.FT R</kbd></nobr> +or <nobr><kbd>.FT I</kbd>),</nobr> or passing <kbd>.FT</kbd> the +lengthy family+fontname (.e.g. <nobr><kbd>.FT HLCDI</kbd>).</nobr> +</p> + +<p> +Fortunately, groff provides a mechanism whereby it's possible to +extend the basic <strong>R, I, B</strong> and <strong>BI</strong> +fonts ("styles" 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> +<strong>Mom</strong> uses this mechanism to offer, in addition to +groff's default PostScript font styles, the following: + +<a name="STYLE_EXTENSIONS"></a> + +<pre> +Mom's extensions to groff's basic font styles +============================================= + + 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 + 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 +</pre> +</p> + +<p> +Thus, with <strong>mom</strong>, if you've installed, say, some +extra Helvetica fonts and named them according to the convention FS +(where "F" means family and "S" means font +style), once having entered + +<pre> + .FAMILY H + or + .FAM H +</pre> + +you can access any of those Helvetica fonts simply by +passing the correct argument from the list above to +<a href="typesetting.html#FONT">FT</a>. +</p> + +<p> +For example, if you were working in Medium Roman +<nobr>(<kbd>.FT R</kbd>)</nobr> and you needed Medium Condensed +Italic for a while (assuming it's installed), you'd just type + +<pre> + .FT CDI +</pre> + +to access the Medium Condensed Italic font from the Helvetica +family. +</p> + +<p> +<strong>Mom</strong>'s list of font styles doesn'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 (DB) but no Bold font (B), you might find it more +convenient to give the DemiBold font the extension "B". +Equally, if the family has an ExtraBold font, you might find it more +convenient to use the extension "HV" (Heavy). +</p> + +<a name="REGISTER_STYLE"></a> + +<p> +However, you may, at needs, want to add to <strong>mom</strong>'s +list of font styles. You can do this by editing the file, om.tmac. +Near the top, you'll see lines of the form + +<pre> + .sty \n[.fp] L \" Light Roman + .sty \n[.fp] LI \" Light Italic + .sty \n[.fp] LCD \" Light Condensed Roman +</pre> +</p> + +<p> +Simply add your new font style by imitating what you see and +plugging in your new font style (having, of course, first created the +font, correctly named, in groff'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 <strong>UN</strong>, +you might decide at some point to add the Bold Outline font +(<strong>UNBO</strong>). In which case, you'd add + +<pre> + .sty \n[.fp] BO \" Bold Outline +</pre> + +to the <nobr><kbd>.sty \n[.fp] <font style></kbd></nobr> list +in om.tmac. +</p> + +<p> +Be careful, though, that any styles you add do not conflict +with <strong><u>family</u></strong> names that already exist. +"C", for example, conflicts with the Courier family +(<strong>CR, CI, CB, CI</strong>). Were you to create a font +style "C", thinking that <nobr><kbd>.FT C</kbd></nobr> +would give you access to font style once you'd given a +<kbd>.FAM(ILY)</kbd> directive, you'd get a nasty surprise: your +type would come out in Courier Roman! +</p> + +<p> +<strong>VERY IMPORTANT NOTE: mom</strong>'s font extensions are +not "user-space" controllable via a macro. If you'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 <strong>mom</strong>'s font extensions +conflict with your own scheme. Should that be the case, comment out +the <nobr><kbd>.sty \n[.fp] <font style></kbd></nobr> lines +found near the top of the <kbd>om.tmac</kbd> file. +</p> + +<a name="HOWTO"><h3><u>How to create a PostScript font for use with groff</u></h3></a> + +<p> +These instructions aren't meant to cover all possibilities, merely +to present one way of making PostScript families/fonts available to +groff and <strong>mom</strong>. +</p> + +<p> +GNU/Linux distributions being what they are, directory locations may +differ and the presence of some executables can'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> + +<h4><u>What you need before you start</u>:</h4> + +<ul> + <li>groff, version 1.18 or higher + <br/> + + (Debian package: groff) + </li> + <li>a full installation of gs and associated tools + <br/> + + (Debian package: gs or gs-gpl or gs-esp or gs-afpl) + </li> + <li>a library of gs fonts + <br/> + + (Debian package: gsfonts) + </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, dfontmgr) + </li> + <li>perl + <br/> + + (Debian package: perl) + </li> +</ul> + +<p> +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. +</p> + +<h4><u>Initial preparation (you only have to do this once)</u>:</h4> + +<ol> + <li>If you don'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 Type1, + TrueType and Groff fonts. + </li> +<a name="SITE-FONT"></a> + <li>Locate the groff directory, site-font. The exact location is + difficult to predict, owing to differences between distros + and whether you're using a pre-packaged groff or have built + it from source. Some typical locations are + <br/><br/> + + <ul> + <li><kbd>/usr/share/groff</kbd></li> + <li><kbd>/usr/local/share/groff</kbd></li> + <li><kbd>/etc/groff</kbd></li> + </ul> + <br/> + + If you can't find the site-font directory, locate + groff's site-tmac 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>Locate the file <kbd><prefix>/font/devps/generate/textmap</kbd> + and symlink it to <kbd>textmap</kbd> in the directory that + contains your personal collection of PostScript fonts. (See the + <a href="#SMALL_NOTE">Small Note</a>, + above, for the meaning of + <nobr><kbd><prefix></kbd>).</nobr> On my system, + at the time of writing, <kbd><prefix></kbd> is + <nobr><kbd>/usr/local/share/groff/1.19.2/</kbd>,</nobr> + therefore, I symlink it in <kbd>~/Fonts/Type1</kbd> with + + <pre> +<kbd>ln -s /usr/local/share/groff/1.19.2/font/devps/generate/textmap textmap</kbd> + </pre> + </li> + <li>Locate the file <kbd><prefix>/font/devps/text.enc</kbd> and + symlink it to <kbd>text.enc</kbd> in your personal font + directory. On my system, in <kbd>~/Fonts/Type1</kbd> + + <pre> +ln -s /usr/local/share/groff/1.19.2/font/devps/text.enc text.enc + </pre> + </li> + <li>Make sure you know which directory/ies holds your gs fonts. + You'll need the information later. On a Debian box, some + typical locations are + <br/><br/> + <ul> + <li><kbd>/usr/lib/ghostscript/fonts</kbd></li> + <li><kbd>/usr/share/ghostscript/fonts</kbd></li> + <li><kbd>/usr/share/fonts/type1/gsfonts</kbd></li> + </ul></li> +</ol> + +<h4><u>Font creation/installation</u>:</h4> + +<ol> + <li>Acquire the font in either Type1 (.pfb) or TrueType (.ttf) format.</li> + <li>Place the font in your personal font directory; for me, + that's <kbd>~/Fonts/Type1</kbd> or <kbd>~/Fonts/TrueType.</kbd> + </li> + <li>In your personal font directory, run one of the following:</li> + <ul> + <li>For Type1 fonts</li> + <ul> + <li><kbd>getafm fontfilename.pfb | gsnd - > fontfilename.afm</kbd> + <br/> + + <em>For Type1 fonts, this will generate something called + an .afm (Adobe Font Metrics) file, which is + required to create PostScript fonts for groff.</em> + </li> + </ul> + <li>For TrueType fonts</li> + <ul> + <li><kbd>ttf2pt1 \-b fontfilename.ttf</kbd> + + <em>For TrueType fonts, this will generate a PostScript + .pfb file as well as an .afm file.</em> + </li> + </ul> + </ul> + <li>Still in your personal font directory, run</li> + <ul> + <li><kbd>afmtodit -e text.enc fontfilename.afm textmap GROFF_FONTNAME</kbd> + <br/><br/> + + Q: <em>How do I choose a GROFF_FONTNAME?</em> + <br/><br/> + + A: Start by considering the + <a href="definitions.html#TERMS_FAMILY">family</a> + to which the font belongs. If you're adding to a family that + already exists in groff's <kbd><prefix>/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>. + <br/><br/> + + For example, if you're adding Helvetica Light Roman, your + GROFF_FONTNAME would be <kbd>HL</kbd>. If you're adding + Helvetica Light Italic, your GROFF_FONTNAME would be + <kbd>HLI</kbd>. + <br/><br/> + + If you're adding a font not already in groff's PostScript + families, first choose a meaningful name for the + <a name="definitions.html#TERMS_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 GARAMOND, GARA, GD, 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 GROFF_FONTNAME would be + <kbd>GDBCDI</kbd>. + <br/><br/> + + In <strong>mom</strong>, you can then access the Garamond + family with <kbd>.FAM GD</kbd>, and the Bold Condensed + Italic font wth <kbd>.FT BCDI</kbd>. + <br/><br/> + + <strong>Note:</strong> The family name need not be in upper + case, and there's no limit to the length of the name. + "Garamond", for example, could be the name you + give the Garamond family. In fact, you might find it + preferable, since a) you wouldn't have to remember how + you'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, <strong>GDBCDI</strong>. + </li> + </ul> + <li>Copy or move GROFF_FONTNAME to your + <a href="#SITE-FONT">site-font directory</a>, + or change to the site-font directory and make a symlink to + GROFF_FONTNAME in your personal directory. + </li> + <li>Copy or move the .pfb file to the directory that + holds your gs fonts, or change to that directory and make a + symlink to the .pfb file in your personal directory. + </li> + <li>Do whatever your system or distro requires in order to + register the new PostScript font (the .pfb file). On a + Debian system, as root, you can run dfontmgr for a + graphical interface that will take care of registering the + font. + </li> +</ol> + +<p> +Written out in full, adding fonts looks like a lot of work. It +isn't. Basically, it's just: + +<ul> + <li>acquire the font</li> + <li>generate an .afm file for the font</li> + <li>create the groff font</li> + <li>put the groff font in<kbd> <prefix>/font/devps</kbd></li> + <li>make sure gs knows about the font</li> +</ul> +</p> + +<p> +After you'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's an example, which you can adapt to your own needs. The +script requires an argument (the .pfb filename), then prompts for +the GROFF_FONTNAME. +</p> + +<pre> +#!/bin/bash +# +# A script for installing Type1 fonts. +# +# Builds .afm files from .pfb files, generates a groff font from the +# .afm file, makes a symlink in /usr/lib/ghostscript/font/ to the +# .pfb file, and a symlink in site-font to the groff font +# + +# .pfb filename, stripped of .pfb extension +FONT=`basename $1 .pfb` + +# Directory holding my personal collection of type1 fonts +FONTDIR="$HOME/Fonts/Type1" + +# Directory holding system ghostscript fonts +GS_FONTDIR="/usr/lib/ghostscript/fonts" + +# Location of site-font/devps +GROFF_SITE_FONTDIR="/usr/local/share/groff/site-font/devps" + +# Personal groff fonts directory +GROFF_FONTS="$HOME/Fonts/Groff" + +# Symlinks to textmap and text.enc +TEXTMAP="$FONTDIR/textmap" +TEXTENC="$FONTDIR/text.enc" + +if [ ! `pwd` = "$FONTDIR" ] ; then + echo "Changing into $FONTDIR directory.." + cd $FONTDIR + sleep 1 +else + sleep 1 +fi + +echo -n "Groff name for this font: " +read FONTNAME +sleep 1 + +echo "Getting .afm.." +getafm $FONT.pfb | gsnd - > $FONT.afm +sleep 1 + +echo "Creating $FONTNAME.." +afmtodit -e $TEXTENC $FONTDIR/$FONT.afm $TEXTMAP $FONTNAME +mv -i $FONTNAME $GROFF_FONTS +sudo ln -s $GROFF_FONTS/$FONTNAME $GROFF_SITE_FONTDIR/$FONTNAME +sleep 1 + +echo "Linking $FONT in $GS_FONTDIR.." +cd $GS_FONTDIR +sudo ln -s $FONTDIR/$FONT.afm $FONT.afm +sudo ln -s $FONTDIR/$FONT.pfb $FONT.pfb +sleep 1 + +# This next bit is Debian specific. If you're not running a +# Debian system, replace it with whatever your distro requires +# in order to register Type1 fonts. + +if [ !`pidof -x /usr/bin/dfontmgr` ] ; then + echo "I will now run dfontmgr so you can register the font." + exec sudo dfontmgr & +else + echo "You may now register the font with dfontmgr." +fi +</pre> + +<hr/> + +<!-- ===================================================================== --> + +<a name="CODENOTES"><h2><u>Some reflections on mom</u></h2></a> + +<p> +<strong>Mom</strong>, as a complete macro set, 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't adequately covered by ms, me, mm, and so +on. Typically, I'd use the library to cobble together macro +sets for new challenges as they came my way. +</p> + +<p> +If, as Eric Raymond asserts, open source begins with a programmer +scratching a personal itch, then <strong>mom</strong> can truly be +called open source, even if, a mere humble set of macros standing on +the shoulders of a giant named troff, she isn't programming at all. +</p> + +<p> +As a writer living in a perpetual state of penury, all the computers +I've ever owned have been hand-me-downs — 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 is that it has helped enormously +to get the most out of my poor little boxes. (It has been pointed +out to me that NetBSD might be an even better choice of operating +systems for computers with limited resources.) +</p> + +<p> +In Linux-land, the choice of typesetting systems basically comes down +to groff or TeX. Both are wonderful — monumental achievements if you +ask me — 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. I've run +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's incredibly geeky. +Owing to its very long history, it — and its "power users" +— have remained stuck in a time warp. Most common macro packages +still look as they did in those decades when memory was exorbitantly +expensive and every byte mattered. Documentation — not always +easy to find — is written as if all readers are computer whizzes, +or at least have a university degree in one of the higher sciences. +</p> + +<p> +By no means a stupid man, nor unfamiliar with the precepts of +programming, I've more than once torn my hair out over the terseness +and ambiguity of groff's documentation. Making sense of certain +primitives has often involved days of testing, interpreting the +documentation instead of just using the primitive. +</p> + +<p> +(ADDENDUM to the previous two paragraphs: A tremendous amount of +effort has gone into creating a groff manual that can be read with +the <strong><kbd>info</kbd></strong> browser, as well as creating +truly useful man pages. The <strong><kbd>info</kbd></strong> manual +is clear and well-written, so my comments are actually out of date. +I leave them in for the benefit of groff newbies, who may still find +the documents a bit intimidating.) +</p> + +<p> +For some time now, groff users and macro writers have had the +option to use "long" names, yet have mostly chosen not to. +With long names, it's possible to create macro sets that are humanly +readable and easy to interpret, encouraging development and evolution. +What'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> +<strong>Mom</strong>'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's current +maintainer, Werner Lemberg. Nearly every macro, number register and +string is "recognisable" simply by 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 <strong>mom</strong>'s macros should be +able to do so with a minimum of head scratching. +</p> + +<p> +<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 <strong>mom</strong>'s +homepage. +</p> + +<hr/> + +<!-- ===================================================================== --> + +<a name="CONTACT"><h2><u>Contact the author</u></h2></a> + +<p> +If you have any questions or comments about <strong>mom</strong>, +suggestions to make, criticisms to offer, or bugs to report, use the +groff mailing list at +<a href="mailto:groff@ffii.org">groff@ffii.org</a> +(subscription information available +<a href="http://ffii.org/mailman/listinfo/groff/">here</a>) +or contact me, Peter Schaffter, directly at one of these +addresses: +</p> + +<p> +<strong><i> pschaffter@magma.ca +<br/> + + ptpi@golden.net</i></strong> +</p> + +<p> +Please include the word "mom" or "groff" 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 <strong>mom</strong>'s homepage, you'll find +it at +</p> + +<p> + <a href="http://faustus.homelinux.org/mom/mom.html"><kbd>http://faustus.homelinux.org/mom/mom.html</kbd></a>. +</p> + +<hr/> + +<p> +<a href="reserved.html#TOP">Next</a> +<a href="macrolist.html#TOP">Prev</a> +<a href="#TOP">Top</a> +<a href="toc.html">Back to Table of Contents</a> +</p> + +</body> +</html> + +<!-- vim: fileencoding=latin1: nomodified: +--> diff --git a/contrib/mom/momdoc/color.html b/contrib/mom/momdoc/color.html new file mode 100644 index 00000000..eafcd6cd --- /dev/null +++ b/contrib/mom/momdoc/color.html @@ -0,0 +1,493 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!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=iso-8859-1"/> +<title>Mom -- Colour</title> +</head> +<body bgcolor="#dfdfdf"> + +<!-- ==================================================================== --> + +<a name="TOP"></a> + +<p> +<a href="docprocessing.html#TOP">Next</a> +<a href="inlines.html#TOP">Prev</a> +<a href="toc.html">Back to Table of Contents</a> +</p> + +<h1 align="center"><a name="COLOR_INTRO"><u>Coloured text</u></a></h1> + +<p> +<a href="#INTRO_COLOR">Introduction to coloured text</a> +<br/> + +<a href="#MACROS_COLOR">Index of colour macros</a> +</p> + +<a name="INTRO_COLOR"><h2><u>Introduction to coloured text</u></h2></a> + +<p> +<strong>Mom</strong>'s support for coloured text is straightforward. +You begin by telling <strong>mom</strong> about the colours you want +with +<a href="#NEWCOLOR">NEWCOLOR</a> +or +<a href="#XCOLOR">XCOLOR</a>. +Afterward, any time you want text to be coloured, you either colour +it with an +<a href="definitions.html#TERMS_INLINES">inline escape</a> +that contains the colour name (e.g. <kbd>\*[red]</kbd> or +<kbd>\*[blue]</kbd>) or invoke the macro, +<a href="#COLOR">COLOR</a>, +with the name of the colour you want. +</p> + +<a name="COLOR_EXAMPLE"></a> + +<p> +For example, say you want to have the name "Jack" in the +sentence "All work and no play makes Jack a dull boy" +appear in yellow. You'd begin by telling <strong>mom</strong> about +the colour, yellow. There are two ways of doing this; see +<a href="#NEWCOLOR">NEWCOLOR</a> +and +<a href="#XCOLOR">XCOLOR</a> +for a full explanation of the difference between the two. +</p> + +<p> +If you use <strong>XCOLOR</strong>, you'd enter this: + +<pre> + .XCOLOR yellow +</pre> +</p> + +<p> +If you use <strong>NEWCOLOR</strong>, you might enter + +<pre> + .NEWCOLOR yellow RGB #FFFF00 +</pre> +</p> + +<a name="COLOR_EXAMPLE2"></a> + +<p> +After "defining" (or "initializing") the colour +"yellow", you'd colourize the name, Jack, either with an +inline escape + +<pre> + All work and no play makes \*[yellow]Jack\*[black] a dull boy. +</pre> + +or with the +<a href="#COLOR">COLOR</a> +macro + +<pre> + All work and no play makes + .COLOR yellow + Jack + .COLOR black + a dull boy. +</pre> +</p> + +<p> +Notice, in both examples, that a) you have to set the colour back +to black after "Jack", and b) you don't have to define +or intialize the colour, black. <strong>Mom</strong> 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> + +<p> +<strong>Please note: Mom</strong>'s colour support is for text only. +She doesn't support "fill" (or "background") +colour for solid, enclosed graphical objects (polygons, ellipses) +drawn with <strong>groff</strong>'s <kbd>\D</kbd> +<a href="definitions.html#TERMS_INLINES">inline escapes</a>, +although you may give a colour as one of the arguments to +<strong>mom</strong>'s "box" and "circle" +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> + +<p> +Please also note that if you're accustomed to using groff's +<kbd>.defcolor</kbd> to define colours, and groff's inline +<kbd>\m[<colorname>]</kbd> to call them, you may continue to +do so without confusing <strong>mom</strong>. +</p> + +<a name="MACROS_COLOR"><h3><u>Index of colour macros</u></h3></a> + +<ul> + <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"><kbd>\*[<colorname>]</kbd></a> inline escape</li> +</ul> + +<!-- -NEWCOLOR- --> + +<hr width="66%" align="left"/> + +<a name="NEWCOLOR"><h3><u>Creating (initializing) a colour with NEWCOLOR</u></h3></a> + +<p> +<nobr>Macro: <strong>NEWCOLOR</strong> <kbd><colour name> [<colour scheme>] <colour components></kbd></nobr> +</p> + +<p> +<strong>NEWCOLOR</strong> lets you create a colour, rather +like an artist mixing paint on a palette. The colour isn't +used immediately; <strong>NEWCOLOR</strong> merely tells +<strong>mom</strong> how to mix the colour when you need it. If you +haven't invoked <kbd>.NEWCOLOR</kbd> (or +<a href="#XCOLOR">XCOLOR</a>), +<strong>mom</strong> doesn't have a clue what you mean when you +reference a colour (with +<a href="#COLOR">COLOR</a> +or +<a href="#COLOR_INLINE"><kbd>\*[<color name>]</kbd></a>). +</p> + +<p> +The first argument to <strong>NEWCOLOR</strong> is a name for your +colour. It can be anything you like — provided it's just one +word long — and can be caps, lower case, or any combination of +the two. +</p> + +<p> +The second argument, which is entirely optional, is the "colour +scheme" you want <strong>mom</strong> to use when mixing the +colour. Valid arguments are + +<pre> + RBG (3 components: red green blue) + CYM (3 components: cyan yellow magenta) + CMYK (4 components: cyan magenta yellow black) + GRAY (1 component) +</pre> + +If you omit the second argument, <strong>mom</strong> assumes you +want <strong>RGB</strong>. +</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 <strong>mom</strong> about a colour named +"YELLOW", you could enter one of the following: + +<pre> + .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" +</pre> +</p> + +<p> +After you've told <strong>mom</strong> about a colour, you can then +get her to set text in that colour either with the +<a href="definitions.html#TERMS_INLINES">inline escape</a>, +<a href="#COLOR_INLINE"><kbd>\*[<colorname>]</kbd></a>, +or the macro, +<a href="#COLOR">COLOR</a>. +(See the +<a href="#COLOR_EXAMPLE">example</a>, +above.) +</p> + +<p> +<strong>Please note:</strong> the colorname you give to +<strong>NEWCOLOR</strong> may be used with <strong>groff</strong>'s +<kbd>\m[<colorname>]</kbd> inline escape (the <kbd>\m</kbd> +escape is used to set text and rule colours). Thus, assuming a +colorname "blueblack" set with <strong>NEWCOLOR</strong>, +<kbd>\*[blueblack]</kbd> and <kbd>\m[blueblack]</kbd> are +equivalent. Furthermore, the colorname can be given as an argument +to <strong>groff</strong>'s +<a href="definitions.html#TERMS_PRIMITIVES">primitive</a> +request, <kbd>.gcolor</kbd> (which does the same thing as +<kbd>\m[<colorname>]</kbd>). +</p> + +<p> +Equally, the colorname may be used with +<kbd>\M[<colorname>]</kbd> and <kbd>.fcolor</kbd>, which set +the "fill" colour for solid graphical objects. +</p> + +<a name="COLOR_TIP"></a> + +<h3><u>Tips for newbies</u></h3> + +<p> +Colour manipulation can be tremendously confusing if you don't have +a background in graphic arts or computing. My advice, if color +intimidates you, is to stick to using <strong>mom</strong>'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 <strong>NEWCOLOR</strong>, +and you'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'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 "Display +format" and select "8 bit truncated rgb". +</p> + +<p> +Alternatively, you can use <strong>mom</strong>'s simpler +<a href="#XCOLOR">XCOLOR</a> +macro to initialize one of the 256 pre-defined X colours by +supplying the name of the color as an argument. +</p> + +<!-- -XCOLOR- --> + +<hr width="33%" align="left"/> + +<a name="XCOLOR"><h3><u>Initializing a colour with XCOLOR</u></h3></a> + +<p> +<nobr>Macro: <strong>XCOLOR</strong> <kbd><X colorname> [<alias>]</kbd></nobr> +<br/> + +<kbd>*<X colorname></kbd> <em>must be all one word, all lower case.</em> +<br/> + +<em>(See</em> +<a href="#XCOLOR_NAMES">Finding X color names</a> +<em>for how to get a list of valid colour names.)</em> +</p> + +<p> +<strong>XCOLOR</strong> is similar to <strong>NEWCOLOR</strong> in +that it tells <strong>mom</strong> to initialize a colour, but it'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 <strong>mom</strong> 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 + +<pre> + .XCOLOR coral +</pre> +</p> + +<p> +Afterwards + +<pre> + .COLOR coral +</pre> + +will colourize subsequent text coral until you instruct +<strong>mom</strong> to return to black, or some other pre-defined, +initialized colour. (The +<a href="definitions.html#TERMS_INLINES">inline escape</a> +<kbd>\*[coral]</kbd> will equally colourize text coral after you've +initialized the colour with <strong>XCOLOR</strong>.) +</p> + +<p> +The downside of <strong>XCOLOR</strong> is that you can'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. "blue" is pure (rgb) blue, +"green" 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, +"blue1" is a relatively bright blue; "blue2", +"blue3" and "blue4" are increasingly darker +shades. For that reason, you may find <strong>XCOLOR</strong> is +a better choice than <strong>NEWCOLOR</strong> 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. "mediumspringgreen". +The optional second argument to <strong>XCOLOR</strong> allows you +to come up with more convenient name by which to reference the +colour. For example, you could enter + +<pre> + .XCOLOR mediumspringgreen mygreen + or + .XCOLOR mediumspringgreen MYGREEN +</pre> + +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> + +<p> +<strong>Please note:</strong> both the colorname and the +alias you give to <strong>XCOLOR</strong> may be used with +<strong>groff</strong>'s <kbd>\m[<colorname>]</kbd> +inline escape (the <kbd>\m</kbd> escape is used to set +text and rule colours). Thus, assuming an X-colorname +"mediumspringgreen" set with <strong>XCOLOR</strong>, and +an alias, "mygreen", <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 +<strong>groff</strong>'s +<a href="definitions.html#TERMS_PRIMITIVES">primitive</a> +request, <kbd>.gcolor</kbd> (which does the same thing as +<kbd>\m[<colorname>]</kbd>). +</p> + +<p> +The colorname initialized with <strong>XCOLOR</strong> +<em><strong><u>but not the alias</u></strong></em> may also +be used with <strong>groff</strong>'s inline escape, +<kbd>\M[<colorname>]</kbd>, and the corresponding primitive, +<kbd>.fcolor</kbd>, both of which set the "fill" colour +for solid graphical objects. If you need a colour initialized with +<strong>XCOLOR</strong> for <kbd>\M</kbd> or <kbd>.fcolor</kbd>, you +<strong>MUST</strong> give the full colorname; the alias won't work. + +</p> +<a name="XCOLOR_NAMES"><h4><u>Finding X color names</u></h4></a> + +<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'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 <strong>XCOLOR</strong>, <em>must</em> +be all one word, all in lower case. +</p> + +<!-- -COLOR- --> + +<hr width="33%" align="left"/> + +<a name="COLOR"><h3><u>Invoking a color</u></h3></a> + +<p> +<nobr>Macro: <strong>COLOR</strong> <kbd><colorname></kbd></nobr> +<br/> + +<a name="COLOR_INLINE"><nobr>Inline: <kbd>\*[<colorname>]</kbd></nobr></a> +</p> + +<a name="COLOR_INLINE"></a> + +<p> +Once you've told <strong>mom</strong> about a colour (via +<a href="#NEWCOLOR">NEWCOLOR</a> +or +<a href="#XCOLOR">XCOLOR</a>, +you use either the macro, <strong>COLOR</strong>, or the +<a href="definitions.html#TERMS_INLINES">inline escape</a>, +<kbd>\*[<colorname>]</kbd>, to cause <strong>mom</strong> to +set subsequent text in that colour. See the +<a href="#COLOR_EXAMPLE2">example</a>, +above, which shows both in action. +</p> + +<p> +<strong>NOTE:</strong> You can use the +<kbd>\*[<colorname>]</kbd> inline escape in any +<a href="docprocessing.html#TOP">document processing</a> +macro that takes a +<a href="definitions.html#TERMS_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>\*[<colorname>]</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 <strong>mom</strong> 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> +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> + +<hr/> + +<p> +<a href="docprocessing.html#TOP">Next</a> +<a href="inlines.html#TOP">Prev</a> +<a href="#TOP">Top</a> +<a href="toc.html">Back to Table of Contents</a> +</p> + +</body> +</html> + +<!-- vim: fileencoding=latin1: nomodified: +--> diff --git a/contrib/mom/momdoc/cover.html b/contrib/mom/momdoc/cover.html new file mode 100644 index 00000000..e219f0b1 --- /dev/null +++ b/contrib/mom/momdoc/cover.html @@ -0,0 +1,646 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!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=iso-8859-1"/> +<title>Mom -- Document processing, creating a cover page</title> +</head> +<body bgcolor="#dfdfdf"> + +<!-- ==================================================================== --> + +<a name="TOP"></a> + +<p> +<a href="refer.html#TOP">Next</a> +<a href="rectoverso.html#TOP">Prev</a> +<a href="toc.html">Back to Table of Contents</a> +</p> + +<a name="COVER_TOP"><h1 align="center"><u>Creating a cover page</u></h1></a> + +<ul> + <li><a href="#COVER_INTRO">Introduction to cover pages</a></li> + <ul> + <li><a href="#PLEASE">Important note — please read</a></li> + <li><a href="#DESC">Description of what mom does on cover pages</a></li> + <li><a href="#PAGINATION">A note on headers/footers and pagination</a></li> + <li><a href="#DESIGN">What to do if you want to design your own cover pages</a></li> + </ul> + <li><a href="#COVER">The cover and document cover macros</a></li> + <ul> + <li><a href="#COVER">COVER/DOC_COVER</a></li> + <ul> + <li><a href="#REQUIRED">The required argument</a></li> + <li><a href="#CHAPTER">How the CHAPTER argument and friends work</a></li> + <li><a href="#OPTIONAL">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> + </ul> + <li><a href="#ON_OFF">Enabling/disabling automatic generation of cover pages</a></li> + <li><a href="#COVER_CONTROL">Control macros — changing the defaults for covers and document covers</a></li> +</ul> + +<a name="COVER_INTRO"><h2><u>Introduction to cover pages</u></h2></a> + +<p> +As of version 1.19 of <strong>mom</strong>, you can now have cover +pages generated automatically. +</p> + +<p> +Though identical in treatment, <strong>mom</strong> provides two +kinds of cover pages: section cover pages (which I shall refer to +simply as "cover pages") and document cover pages +("doc covers"). +</p> + +<p> +A document cover page +(<a href="#DOC_COVER">doc cover</a>) +is what you'd most likely use at the start of a +<a href="rectoverso.html#COLLATE_INTRO">collated</a> +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 section +<a href="#COVER">cover</a> +page is what you'd use for cover pages that separate sections of a +collated document, i.e. title pages. A section cover page (but not +a doc cover page) in a collated document could, for example, simply +read "PART I". +</p> + +<p> +In non-collated documents (say, an essay) you can use either a +section cover (title page) or a doc cover to generate a cover sheet. +</p> + +<p> +In addition, nothing prevents you from generating both a doc cover +page and a section cover page for every document in a collated +document. Or you can selectively disable the automatic generation +of either doc covers or section covers in a collated document +on-the-fly. +</p> + +<p> +<a name="PLEASE"><strong>Important note:</strong></a> +automatic generation of cover or doc cover pages after the first +one(s) only takes place if you are working with collated documents. +<strong>Mom</strong> provides no mechanism for saying "print +a section cover here even though I'm still working on the same +(non-collated) document." +</p> + +<a name="DESC"><h3><u>Description of what mom does on cover pages</u></h3></a> + +<p> +By default, <strong>mom</strong> typesets cover (and doc cover) +pages identically to +<a href="definitions.html#TERMS_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 + +<ul> + <li>the position on the page where the information is output</li> + <li>the (optional) addition of copyright and miscellaneous information</li> + <li>there's no running text underneath</li> +</ul> +</p> + +<p> +You tell <strong>mom</strong> 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 <strong>mom</strong> the +appropriate reference macros (e.g. +<a href="docprocessing.html#TITLE">TITLE</a> +or +<a href="docprocessing.html#AUTHOR">AUTHOR</a>), +she will output cover (and doc cover) pages identically to how she +would output docheaders containing the same information. +</p> + +<p> +By default, <strong>mom</strong> starts cover (and doc cover) pages +one-third of the way down the page. This can be changed through +the use of the control macros +<a href="#COVER_CONTROL_INDEX">COVER_ADVANCE/DOC_COVER_ADVANCE</a>. +</p> + +<p> +If you request copyright information (and have already given +<strong>mom</strong> the reference macro, +<a href="docprocessing.html#COPYRIGHT">COPYRIGHT</a>), +she sets it, by default, in a smaller +<a href="definitions.html#TERMS_PS">point size</a> +in the bottom right hand corner of the cover (or doc cover) page. +The default point size and the position can be controlled with +<a href="#COVER_CONTROL_INDEX">COVER_COPYRIGHT_SIZE/DOC_COVER_COPYRIGHT_SIZE</a> +and +<a href="#COVER_CONTROL_INDEX">COVER_COPYRIGHT_QUAD/DOC_COVER_COPYRIGHT_QUAD</a>. +</p> + +<p> +Similarly, if you request miscellaneous information (and have +already given <strong>mom</strong> 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) page. The default point +size is dependent on +<strong>COVER_COPYRIGHT_SIZE/DOC_COVER_COPYRIGHT_SIZE</strong>, +but the position can be controlled with +<a href="#COVER_CONTROL_INDEX">COVER_MISC_QUAD/DOC_COVER_MISC_QUAD</a>. +</p> + +<a name="PAGINATION"></a> + +<p> +<strong>NOTE: mom</strong> does not set any +<a href="definitions.html#TERMS_HEADER">headers</a> +or +<a href="definitions.html#TERMS_FOOTER">footers</a> +on cover pages. Neither does she set any page numbers. From +the point of view of pagination, cover (and doc cover) pages are +by default considered "null" pages. If you wish them to +be included in the pagination scheme (even though no page numbers +appear), you must tell <strong>mom</strong> that's what you want +with the macros <strong>DOC_COVERS_COUNT_PAGES</strong> and/or +<strong>COVERS_COUNT_PAGES</strong>. +</p> + +<a name="DESIGN"></a> + +<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 <em>in full</em> (see +<a href="docprocessing.html#DOCPROCESSING_TUT">Tutorial — 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 <strong>mom</strong>'s processing of the document itself, +the first page of which, moreover, will be numbered "1" +unless you instruct her otherwise with +<a href="headfootpage.html#PAGENUMBER">PAGENUMBER</a>. +</p> + +<!-- -COVER- --> + +<hr width="66%" align="left"/> + +<a name="COVER"></a> + +<p> +Macro: <strong>COVER</strong> +<br/> + +<a name="DOC_COVER"></a> + +Macro: <strong>DOC_COVER</strong> +<br/> + +<nobr>Required argument: <kbd>TITLE | DOCTITLE | COVERTITLE | CHAPTER | CHAPTER_TITLE | CHAPTER+TITLE</kbd></nobr> +<br/> + +<nobr>Optional arguments: <kbd>[ SUBTITLE AUTHOR DOCTYPE COPYRIGHT MISC BLANKPAGE ]</kbd></nobr> +<br/> + +<em>*Note: these macros should be placed in the +"style-sheet" section of your document setup (see the</em> +<a href="docprocessing.html#DOCPROCESSING_TUT">Tutorial — Setting up a mom document</a>), +<em>i.e. after PRINTSTYLE (and/or DOCTYPE and/or COPYSTYLE), but +before START.</em> +</p> + +<p> +<strong>COVER</strong> and <strong>DOC_COVER</strong> behave +identically. The reason <strong>mom</strong> provides two macros +for automatic 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've written a document comprised of three +sections. When you +<a href="rectoverso.html#COLLATE">COLLATE</a> +the document for output, you could use <kbd>.DOC_COVER</kbd> +to generate a cover page that contained the name of the entire +document, your (the author's) name, and perhaps the copyright date. +Subsequently, you could use <kbd>.COVER</kbd>, after each +<kbd>.COLLATE</kbd> but before each +<a href="docprocessing.html#START">START</a>, +to generate a cover page (or cover "sheet", if you prefer) +containing just the name of the section. +</p> + +<a name="REQUIRED"><h4><u>The required argument</u></h4></a> + +<p> +Both <strong>COVER</strong> and <strong>DOC_COVER</strong>, +whenever invoked, require a first argument, as listed above. +This first argument will become the first bit of information +<strong>mom</strong> prints on the cover (or doc cover) page (i.e. +it will be the "title"). +</p> + +<p> +In order for the information to appear, you must, of course, first +have given <strong>mom</strong> the appropriate +<a href="docprocessing.html#REFERENCE_MACROS">reference macro</a>. +A list of the arguments with their equivalent reference macros follows. +</p> + +<dl> + <dt><kbd>TITLE</kbd></dt> + <dd> + — means the argument you gave to <a href="docprocessing.html#TITLE">TITLE</a> + </dd> + + <dt><kbd>DOCTITLE</kbd></dt> + <dd> + — means the argument you gave to <a href="docprocessing.html#DOCTITLE">DOCTITLE</a> + </dd> + + <dt><kbd>COVERTITLE</kbd></dt> + <dd> + — 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><kbd>CHAPTER, CHAPTER_TITLE, CHAPTER+TITLE</kbd></dt> + <dd> + — see below (How the CHAPTER argument and friends work) + </dd> +</dl> + +<a name="CHAPTER"><h5><u>How the CHAPTER argument and friends work</u></h5></a> + +<p> +<kbd>CHAPTER</kbd>, by itself, will print the +<a href="docprocessing.html#CHAPTER_STRING">CHAPTER_STRING</a> +as well as the chapter number that you gave to +<a href="docprocessing.html#CHAPTER">CHAPTER</a>. +For example, assuming a vanilla setup for your chapter + +<pre> + \# Reference macros + .CHAPTER 1 + .CHAPTER_TITLE "The Bonny Blue Yonder" + <other stuff> + .COVER CHAPTER \" (or .DOC_COVER CHAPTER) + .START +</pre> + +will simply print + +<pre> + Chapter 1 +</pre> +</p> + +<p> +<kbd>CHAPTER_TITLE</kbd> 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 + +<pre> + \# Reference macros + .CHAPTER 1 + .CHAPTER_TITLE "The Bonny Blue Yonder" + <other stuff> + .COVER CHAPTER_TITLE \" (or .DOC_COVER CHAPTER_TITLE) + .START +</pre> + +will simply print + +<pre> + The Bonny Blue Yonder +</pre> +</p> + +<p> +<kbd>CHAPTER+TITLE</kbd> will print <strong>both</strong> the +chapter string + number AND the chapter title. For example, +assuming a vanilla setup for your chapter + +<pre> + \# Reference macros + .CHAPTER 1 + .CHAPTER_TITLE "The Bonny Blue Yonder" + <other stuff> + .COVER CHAPTER+TITLE \" (or .DOC_COVER CHAPTER+TITLE) + .START +</pre> + +will print + +<pre> + Chapter 1 + The Bonny Blue Yonder +</pre> +</p> + +<a name="OPTIONAL"><h4><u>The optional arguments</u></h4></a> + +<p> +The remainder of the arguments to <strong>COVER</strong> and +<strong>DOC_COVER</strong> 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) page. The only hitch is — PAY ATTENTION, +CLASS! — 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> + +<pre> + .COVER TITLE AUTHOR COPYRIGHT MISC +</pre> + +is correct, while + +<pre> + .COVER TITLE AUTHOR MISC COPYRIGHT +</pre> + +is not. +</p> + +<a name="DOCTYPE"><h5><u>What the DOCTYPE argument means</u></h5></a> + +<p> +When you pass <strong>COVER</strong> or <strong>DOC_COVER</strong> +the argument, <kbd>DOCTYPE</kbd>, it refers to the argument you gave +to +<a href="docprocessing.html#DOCTYPE">DOCTYPE</a> <kbd>NAMED</kbd>. +For example, if, in your +<a href="docprocessing.html#DOCSTYLE_MACROS">docstyle macros</a> +you gave a + +<pre> + .DOCTYPE NAMED "Abstract" +</pre> + +the argument, <kbd>DOCTYPE</kbd>, in the <strong>COVER</strong> or +<strong>DOC_COVER</strong> macros, would mean that you wanted the +word, Abstract, to appear on the cover (or doc cover), just as it +would in the +<a href="docprocessing.html#DOCHEADER">docheader</a>. +</p> + +<a name="BLANKPAGE"><h5><u>What the BLANKPAGE argument means</u></h5></a> + +<p> +If the final argument to <strong>DOC_COVER</strong> or +<strong>COVER</strong> is <kbd>BLANKPAGE</kbd>, <strong>mom</strong> +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, no text should appear on the reverse +side of cover or title pages. If <strong>DOC_COVERS_COUNT_PAGES</strong> +and/or <strong>COVERS_COUNT_PAGES</strong> is enabled, the blank +page will be considered in the pagination scheme. +</p> + +<!-- -ENABLING/DISABLING- --> + +<hr width="33%" align="left"/> + +<a name="ON_OFF"></a> + +<p> +<nobr>Macro: <strong>COVERS</strong> <kbd><toggle></kbd></nobr> +<br/> + +<nobr>Macro: <strong>DOC_COVERS</strong> <toggle></nobr> +</p> + +<p> +By default, if you give <strong>mom</strong> a +<a href="#COVER">COVER</a> +or +<a href="#DOC_COVER">DOC_COVER</a> +macro, she will print it. In a document that contains sections, +articles or chapters formerly treated as "one-off's" but +now being +<a href="rectoverso.html#COLLATE_INTRO">collated</a>, +such behaviour may not be desirable. +</p> + +<p> +<strong>Mom</strong> lets you selectively enable or disable the +generation of covers and/or doc covers with the toggle macros +<strong>COVERS</strong> and <strong>DOC_COVERS</strong>. Because +they're toggle macros, simply invoking them by themselves enables +automatic cover (or doc cover) generation, while invoking them with +any argument at all (<strong>OFF, QUIT, X</strong>, etc) disables +cover (or doc cover) generation. +</p> + +<p> +<strong>NOTE:</strong> You must place these macros prior to any +instance of +<a href="docprocessing.html#START">START</a>. +Since they're "on" by default, there's no need to use +them if you want covers. However, if you don't, especially in the +kind of scenario described above, the best place to put them (most +likely with an <strong>OFF, NO, X</strong>, etc. argument), is +immediately after the first invocation of <strong>START</strong>. +By doing so, you ensure they precede all subsequent instances of +<strong>START</strong>. +</p> + +<hr align="left" width="66%"/> + +<a name="COVER_CONTROL"><h3><u>Control macros — changing the defaults for covers and document covers</u></h3></a> + +<p> +The default typographic appearance of the items on a cover (or doc +cover) page is identical to that of the items in a +<a href="definitions.html#TERMS_DOCHEADER">docheader</a>. +(See +<a href="docprocessing.html#DOCHEADER_CONTROL">How to change the look of docheaders</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: + +<ol> + <li>The copyright line is set in the bottom right hand corner + of the page, 2 + <a href="definitions.html#TERMS_PS">point sizes</a> + smaller than the size of + <a href="definitions.html#TERMS_RUNNING">running text</a> + </li> + <li>The "misc" line is set in the bottom left hand + corner of the page, in the same family, font and point size + as the copyright line. + </li> +</ol> +</p> + +<p> +With the exception of the copyright and "misc" lines, the +defaults for the entirety of cover (and doc cover) pages, and all +the elements thereon, can be changed with control macros whose +behaviour and arguments are identical to +<a href="docprocessing.html#DOCHEADER_CONTROL_INDEX">the control macros used for docheaders</a>. +The only difference is the name by which you invoke the control +macro(s). +</p> + +<p> +The complete list of cover (and doc cover) page control macros +follows; please refer to the +<a href="docprocessing.html#DOCHEADER_CONTROL_INDEX">docheader control macros index</a> +in order to understand how to use them. +</p> + +<a name="COVER_CONTROL_INDEX"><h4><u>Index of cover and doc cover control macros</u></h4></a> + +<pre> +<a name="COVER_ADVANCE">.COVER_ADVANCE .DOC_COVER_ADVANCE</a> -+ +<a name="COVER_FAMILY">.COVER_FAMILY .DOC_COVER_FAMILY</a> | like DOCHEADER_ +<a name="COVER_LEAD">.COVER_LEAD .DOC_COVER_LEAD</a> -+ + +.COVER_TITLE_FAMILY .DOC_COVER_TITLE_FAMILY -+ +.COVER_TITLE_FONT .DOC_COVER_TITLE_FONT | like +.COVER_TITLE_COLOR .DOC_COVER_TITLE_COLOR | TITLE_ +.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_ +.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_ +.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_ +.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_ +.COVER_DOCTYPE_SIZE .DOC_COVER_DOCTYPE_SIZE -+ + +.COVER_COPYRIGHT_FAMILY .DOC_COVER_COPYRIGHT_FAMILY -+ +.COVER_COPYRIGHT_FONT .DOC_COVER_COPYRIGHT_FONT | like any +.COVER_COPYRIGHT_COLOR .DOC_COVER_COPYRIGHT_COLOR | of the above +.COVER_COPYRIGHT_SIZE .DOC_COVER_COPYRIGHT_SIZE -+ +.COVER_COPYRIGHT_QUAD .DOC_COVER_COPYRIGHT_QUAD + - the copyright quad can be either L (left) or R (right); default is left + +.COVER_MISC_COLOR .DOC_COVER_MISC_COLOR - like any of the above _COLOR macros +.COVER_MISC_QUAD .DOC_COVER_MISC_QUAD + - the misc quad can be either L (left) or R (right); default is left + - see <a href="#MISC">Notes</a> + +.COVER_UNDERLINE .DOC_COVER_UNDERLINE - like DOCTYPE_UNDERLINE + - see <a href="#UNDERLINE">Notes</a> + +.COVERS_COUNT_PAGES .DOC_COVERS_COUNT_PAGES + - whether to consider cover pages in the pagination scheme; the + default is to ignore them + - see <a href="#COUNT">Notes</a> +</pre> + +<h5><u>Notes</u></h5> + +<a name="MISC"></a> + +<p> +<strong>COVER_MISC</strong> and <strong>DOC_COVER_MISC</strong> +have only two control macros, <strong>_COLOR</strong> and +<strong>_QUAD</strong>. The family, font and size of +the <kbd>MISC</kbd> argument to <strong>COVER</strong> +or <strong>DOC_COVER</strong> are always the same as for +<kbd>COPYRIGHT</kbd>. Should you wish the family, font or size +to be different from <kbd>COPYRIGHT</kbd>, I suggest setting the +type specs for <kbd>COPYRIGHT</kbd> to the ones you want for +<kbd>MISC</kbd>, then altering them for <kbd>COPYRIGHT</kbd> using +<a href="inlines.html#INDEX_INLINES">inline escapes</a> +in the +<a href="definitions.html#TERMS_STRINGARGUMENT">string argument</a> +you pass to the macro, +<a href="docprocessing.html#COPYRIGHT">COPYRIGHT</a>. +(Of course, you could always do the reverse, but if you pass several +arguments to +<a href="docprocessing.html#MISC">MISC</a>, +it's more likely you want to get <strong>MISC</strong> right first.) +</p> + +<a name="UNDERLINE"></a> + +<p> +<strong>COVER_UNDERLINE</strong> and <strong>DOC_COVER_UNDERLINE</strong> +apply only to the doctype-name that appears on covers or doc +covers, and then only if <kbd>DOCTYPE</kbd> is given as one of the +arguments to +<a href="#COVER">COVER</a> +or +<a href="#DOC_COVER">DOC_COVER</a>. It is invoked in exactly the +same way as +<a href="docprocessing.html#DOCTYPE_UNDERLINE">DOCTYPE_UNDERLINE</a>. +</p> + +<a name="COUNT"></a> + +<p> +<strong>COVERS_COUNT_PAGES</strong> and +<strong>DOC_COVERS_COUNT_PAGES</strong> are toggle macros, hence +invoking them by themselves means that <strong>mom</strong> will +consider cover and doc cover pages in the pagination scheme; +invoking them with any argument (<strong>OFF, NO, X</strong>, +etc.) means they are ignored. The default is to ignore them. +</p> + +<hr/> + +<p> +<a href="refer.html#TOP">Next</a> +<a href="rectoverso.html#TOP">Prev</a> +<a href="#TOP">Top</a> +<a href="toc.html">Back to Table of Contents</a> +</p> + +</body> +</html> + +<!-- vim: fileencoding=latin1: nomodified: +--> diff --git a/contrib/mom/momdoc/definitions.html b/contrib/mom/momdoc/definitions.html new file mode 100644 index 00000000..15667ec2 --- /dev/null +++ b/contrib/mom/momdoc/definitions.html @@ -0,0 +1,945 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!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=iso-8859-1"/> +<title>Mom -- Definitions and Terms</title> +</head> +<body bgcolor="#dfdfdf"> + +<!-- ==================================================================== --> + +<a name="TOP"></a> + +<p> +<a href="using.html#TOP">Next</a> +<a href="intro.html#TOP">Prev</a> +<a href="toc.html">Back to Table of Contents</a> +</p> + +<a name="TERMS"><h1 align="center"><u>Definitions of terms used in this manual</u></h1></a> + +<p> +<a href="#TERMS_TYPESETTING">Typesetting Terms</a> +<br/> + +<a href="#TERMS_GROFF">Groff Terms</a> +<br/> + +<a href="#TERMS_MOM">Mom Document Processing Terms</a> +</p> + +<p> +I use a number of typesetting-specific and groff-specific terms +throughout this documentation, as well as a few terms that apply +to <strong>mom</strong> herself. To make life easier, I'll explain +them here. Refer back to this section should you encounter a word +or concept you're not familiar with. +</p> + +<hr/> + +<a name="TERMS_TYPESETTING"><h2><u>Typesetting terms</u></h2></a> + +<ul> + <li><a href="#TERMS_ASCENDER">Ascender</a></li> + <li><a href="#TERMS_BASELINE">Baseline</a></li> + <li><a href="#TERMS_BALLOTBOX">Ballot box</a></li> + <li><a href="#TERMS_BULLET">Bullet</a></li> + <li><a href="#TERMS_CAPHEIGHT">Cap-height</a></li> + <li><a href="#TERMS_DESCENDER">Descender</a></li> + <li><a href="#TERMS_DISCRETIONARYHYPHEN">Discretionary hyphen</a></li> + <li><a href="#TERMS_DROPCAP">Drop cap</a></li> + <li><a href="#TERMS_EM">Em/en</a></li> + <li><a href="#TERMS_FAMILY">Family</a></li> + <li><a href="#TERMS_FIGURESPACE">Figure space/Digit space</a></li> + <li><a href="#TERMS_FIXEDWIDTHFONT">Fixed width font</a></li> + <li><a href="#TERMS_FIXEDWIDTHSPACE">Fixed width space</a></li> + <li><a href="#TERMS_FONT">Font</a></li> + <li><a href="#TERMS_FORCE">Force justify</a></li> + <li><a href="#TERMS_JUST">Justify/justification</a></li> + <li><a href="#TERMS_GUTTER">Gutter</a></li> + <li><a href="#TERMS_KERN">Kerning</a></li> + <li><a href="#TERMS_KERNUNIT">Kern Units</a></li> + <li><a href="#TERMS_LEADING">Lead/leading</a></li> + <li><a href="#TERMS_LEADER">Leaders</a></li> + <li><a href="#TERMS_LIGATURES">Ligature</a></li> + <li><a href="#TERMS_PICASPOINTS">Picas/Points</a></li> + <li><a href="#TERMS_PS">Point Size</a></li> + <li><a href="#TERMS_QUAD">Quad</a></li> + <li><a href="#TERMS_RAG">Rag</a></li> + <li><a href="#TERMS_SHAPE">Shape</a></li> + <li><a href="#TERMS_SOLID">Solid/set solid</a></li> + <li><a href="#TERMS_TRACKKERNING">Track kerning/Line kerning</a></li> + <li><a href="#TERMS_UNBREAKABLESPACE">Unbreakable space</a></li> + <li><a href="#TERMS_WEIGHT">Weight</a></li> + <li><a href="#TERMS_WORDSPACE">Word space</a></li> + <li><a href="#TERMS_XHEIGHT">x-height</a></li> +</ul> + +<dl> + <dt><a name="TERMS_ASCENDER"><em>Ascender</em></a></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><a name="TERMS_BASELINE"><em>Baseline</em></a></dt> + <dd> + The imaginary line on which the bottoms of capital letters and + the bowls of lower case letters rest. + </dd> + + <dt><a name="TERMS_BALLOTBOX"><em>Ballot box</em></a></dt> + <dd> + An unfilled square, usually + <a href="#TERMS_CAPHEIGHT">cap-height</a> + in size, typically placed beside items in a checklist. + </dd> + + <dt><a name="TERMS_BULLET"><em>Bullet</em></a></dt> + <dd> + A small, filled circle typically found beside items or points in + a list. + </dd> + + <dt><a name="TERMS_CAPHEIGHT"><em>Cap-height</em></a></dt> + <dd> + The height of the tallest capital letter in a given + <a href="#TERMS_FONT">font</a> + at the current + <a href="#TERMS_PS">point size</a>. + </dd> + + <dt><a name="TERMS_DESCENDER"><em>Descender</em></a></dt> + <dd> + The portion of a letter that extends beneath the + <a href="#TERMS_BASELINE">baseline</a> + (j, q, y are letters with descenders). + </dd> + + <dt><a name="TERMS_DISCRETIONARYHYPHEN"><em>Discretionary hyphen</em></a></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't always get it right. + Discretionary hyphens make sure it does. In the event that the + word doesn't need to be hyphenated at all, groff leaves them + alone. In groff, the discretionary hyphen is entered with + + <pre> + \% (backslash followed by a percent) + </pre> + + </dd> + + <dt><a name="TERMS_DROPCAP"><em>Drop cap</em></a></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 "drops" 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><a name="TERMS_EM"><em>Em/en</em></a></dt> + <dd> + An em is a relative measurement equal to the width of the + letter M at a given + <a href="#TERMS_PS">point size</a> + in a given + <a href="#TERMS_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><a name="TERMS_FAMILY"><em>Family</em></a></dt> + <dd> + The collective name by which a collection of + <a href="#TERMS_FONT">fonts</a> + are known, e.g. Helvetica, Times Roman, Garamond. + </dd> + + <dt><a name="TERMS_FIGURESPACE"><em>Figure space/Digit space</em></a></dt> + <dd> + A + <a href="#TERMS_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 + + <pre> + \0 (backslash followed by a zero) + </pre> + + </dd> + + <dt><a name="TERMS_FIXEDWIDTHFONT"><em>Fixed width font</em></a></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><a name="TERMS_FIXEDWIDTHSPACE"><em>Fixed width space</em></a></dt> + <dd> + Equal to + <a href="#TERMS_WORDSPACE">word space</a>, + but does not expand or contract when text is + <a href="#TERMS_JUST">justified</a>. + In groff, fixed width space is entered with + + <pre> + \<space> (backslash followed by hitting the the spacebar on your keyboard) + </pre> + + </dd> + + <dt><a name="TERMS_FONT"><em>Font</em></a></dt> + <dd> + The specific + <a href="#TERMS_WEIGHT">weight</a> + and + <a href="#TERMS_SHAPE">shape</a> + of type within a + <a href="#TERMS_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). + <strong>Mom</strong> considerably extends this very basic list. + </dd> + + <dt><a name="TERMS_FORCE"><em>Force justify</em></a></dt> + <dd> + Sometimes, in + <a href="#TERMS_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's word spacing stretched to force the line flush with the + right margin. + </dd> + + <dt><a name="TERMS_GUTTER"><em>Gutter</em></a></dt> + <dd> + The vertical whitespace separating columns of type. + </dd> + + <dt><a name="TERMS_JUST"><em>Justify/justification</em></a></dt> + <dd> + Lines of type are justified when they'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't. See + <a href="#TERMS_QUAD">quad</a>. + </dd> + + <dt><a name="TERMS_KERN"><em>Kerning</em></a></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'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're far from perfect. Professional typesetters still + devote a lot of time to fitting letters and punctuation together + properly. + </dd> + + <dt><a name="TERMS_KERNUNIT"><em>Kern Units</em></a></dt> + <dd> + A relative distance equal to 1/36 of the current + <a href="#TERMS_PS">point size</a>. + Used between individual letters + for + <a href="#TERMS_KERN">kerning</a>. + Different typesetting systems use different values (1/54 is + popular), and sometimes call kern units by a different name. + + <p> + <em><strong>Experts: </strong>A kern unit has nothing to do with + groff machine units.</em> + </p> + </dd> + + <dt><a name="TERMS_LEADING"><em>Lead/leading</em></a></dt> + <dd> + The distance from the + <a href="#TERMS_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="#TERMS_PICASPOINTS">points</a>. + + <p> + <em>In case you're interested...</em> In previous centuries, + lines of type were separated by thin strips of — you guessed + it — lead. Lines of type that had no lead between them were said + to be "set solid." Once you began separating them with + strips of lead, they were said to be "leaded", and the + spacing was expressed in terms of the number of + <a href="#TERMS_PICASPOINTS">points</a> + of lead. For this reason, "leading" and "line + spacing" aren'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><a name="TERMS_LEADER"><em>Leaders</em></a></dt> + <dd> + Single characters used to fill lines, usually to their end. So + called because they "lead" the eye from one element + of the page to another. For example, in the following (brief) + Table of Contents, the periods (dots) are leaders. + + <pre> + Foreword............... 2 + Chapter 1.............. 5 + Chapter 2.............. 38 + Chapter 3.............. 60 + </pre> + + </dd> + + <dt><a name="TERMS_LIGATURES"><em>Ligature</em></a></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><a name="TERMS_PICASPOINTS"><em>Picas/Points</em></a></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><a name="TERMS_PS"><em>Point Size</em></a></dt> + <dd> + The nominal size of type, measured in + <a href="#TERMS_PICASPOINTS">points</a> + from the bottom of the longest + <a href="#TERMS_DESCENDER">descender</a> + to the top of the highest + <a href="#TERMS_ASCENDER">ascender</a>. + In reality, type is always fractionally smaller than its point + size. + </dd> + + <dt><a name="TERMS_QUAD"><em>Quad</em></a></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't. Quad right + means the right margin is flush, the left isn'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><a name="TERMS_RAG"><em>Rag</em></a></dt> + <dd> + Describes a margin that isn't flush. Rag right means the right + margin isn't flush. Rag left means the left margin isn't flush. + The expression "flush left/rag right" is sometimes used to + describe type that is + <a href="#TERMS_QUAD">quadded</a> + left. + </dd> + + <dt><a name="TERMS_SHAPE"><em>Shape</em></a></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: + + <ul> + <li>"Roman", which has no slant, and has letterforms of + average width</li> + <li>"Italic", which is slanted, and has letterforms + of average width</li> + <li>"Condensed", which has no slant, but has + letterforms narrower than the average represented by Roman</li> + <li>"Condensed Italic", which is slanted, with letterforms narrower + than average</li> + </ul> + </p> + + <p> + The term + <a href="#TERMS_FONT">font</a>, + as it is used in these documents, refers to a combination of + <a href="#TERMS_WEIGHT">weight</a> + and shape. + </p> + + </dd> + + <dt><a name="TERMS_SOLID"><em>Solid/set solid</em></a></dt> + <dd> + When no + <a href="#TERMS_LEADING">lead</a> + is added between lines of type (i.e. the + <a href="#TERMS_PS">point size</a> + and linespacing are the same), the lines are said to be "set + solid." + </dd> + + <dt><a name="TERMS_TRACKKERNING"><em>Track kerning/Line kerning</em></a></dt> + <dd> + Sometimes, it'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><a name="TERMS_UNBREAKABLESPACE"><em>Unbreakable space</em></a></dt> + <dd> + Equal to + <a href="#TERMS_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 + + <pre> + \~ (backslash followed by a tilde) + </pre> + + </dd> + + <dt><a name="TERMS_WEIGHT"><em>Weight</em></a></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><a name="TERMS_WORDSPACE"><em>Word space</em></a></dt> + <dd> + The amount of whitespace between words. When text is + <a href="#TERMS_JUST">justified</a>, + word space expands or contracts to make the margins flush. + </dd> + + <dt><a name="TERMS_XHEIGHT"><em>x-height</em></a></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> + +<hr/> + +<a name="TERMS_GROFF"><h2><u>Groff terms</u></h2></a> + +<ul> + <li><a href="#TERMS_ALIAS">Alias</a></li> + <li><a href="#TERMS_ARGUMENTS">Arguments</a></li> + <li><a href="#TERMS_COMMENTLINES">Comment lines</a></li> + <li><a href="#TERMS_CONTROLLINES">Control Lines</a></li> + <li><a href="#TERMS_FILLED">Filled lines</a></li> + <li><a href="#TERMS_INLINES">Inline escapes</a></li> + <li><a href="#TERMS_INPUTLINE">Input line</a></li> + <li><a href="#TERMS_MACROS">Macros</a></li> + <li><a href="#TERMS_UNITS">Machine units</a></li> + <li><a href="#TERMS_NUMERICARGUMENT">Numeric argument</a></li> + <li><a href="#TERMS_OUTPUTLINE">Output line</a></li> + <li><a href="#TERMS_PRIMITIVES">Primitives</a></li> + <li><a href="#TERMS_STRINGARGUMENT">String Argument</a></li> + <li><a href="#TERMS_UNITOFMEASURE">Unit of measure</a></li> + <li><a href="#TERMS_ZEROWIDTHCHARACTER">Zero-width character</a></li> +</ul> + +<dl> + <dt><a name="TERMS_ALIAS"><em>Alias</em></a></dt> + <dd> + A + <a href="#TERMS_MACROS">macro</a> + invoked by a name different from its "official" + name. For example, the official name of the macro to change + <a href="#TERMS_FAMILY">family</a> + is <strong>FAMILY</strong>. Its alias is <strong>FAM</strong>. + Aliases may be created for any macro (via the + <a href="goodies.html#ALIAS">ALIAS</a> + macro) provided the alias uses a name not already taken by the + <strong>mom</strong> macros or one of the groff + <a href="#TERMS_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><a name="TERMS_ARGUMENTS"><em>Arguments</em></a></dt> + <dd> + Parameters or information needed by a + <a href="#TERMS_MACROS">macro</a> + to do its job. For example, in the macro + + <pre> + .PT_SIZE 12 + </pre> + + <kbd>12</kbd> is the argument. In the macro + + <pre> + .QUAD LEFT + </pre> + + <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><a name="TERMS_COMMENTLINES"><em>Comment Lines</em></a></dt> + <dd> + <a href="#TERMS_INPUTLINE">Input lines</a> + introduced with the comment character + + <pre> + \# (backslash followed by the pound sign) + </pre> + + When processing output, groff silently ignores everything on a + line that begins with the comment character. + </dd> + + <dt><a name="TERMS_CONTROLLINES"><em>Control Lines</em></a></dt> + <dd> + Instructions to groff that appear on a line by themselves, which + means that "control lines" are either + <a href="#TERMS_MACROS">macros</a> + or groff + <a href="#TERMS_PRIMITIVES">primitives</a>. + Control lines begin with a period or, occasionally, an apostrophe. + </dd> + + <dt><a name="TERMS_FILLED"><em>Filled lines/fill mode</em></a></dt> + <dd> + Automatic + <a href="#TERMS_JUST">justification</a> + or + <a href="#TERMS_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="#TERMS_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="#TERMS_JUST">justified</a> + or + <a href="#TERMS_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> + <a name="TERMS_NOFILL"></a> + Nofill mode (non-filled text) means that groff respects the ends + of lines as they appear in your text editor. + </p> + + </dd> + + <dt><a name="TERMS_INLINES"><em>Inline escapes</em></a></dt> + <dd> + Instructions issued to groff that appear as part of an + <a href="#TERMS_INPUTLINE">input line</a> + (as opposed to + <a href="#TERMS_MACROS">macros</a>, + which must appear on a line by themselves). Inline escapes are + always introduced by the backslash character. For example, + + <pre> + A line of text with the word T\*[BU 2]oronto in it + </pre> + + contains the inline escape <kbd>\*[BU 2]</kbd> (which means + "move the letter 'o' 2 + <a href="#TERMS_KERNUNIT">kern units</a> + closer to the letter 'T'"). + + <p> + <strong>Mom</strong>'s inline escapes always take the form + <kbd>\*[<ESCAPE>]</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="#TERMS_NUMERICARGUMENT">numeric argument</a>. + <strong>Groff</strong>'s escapes begin with the backslash + character but typically have no star and are in lower case. For + example, the <strong>mom</strong> escapes to move forward 6 + points on a line are either + + <pre> + \*[FP6] or \*[FWD 6p] + </pre> + + while the <strong>groff</strong> escape for the same thing is + + <pre> + \h'6p' + </pre> + </p> + + </dd> + + <dt><a name="TERMS_INPUTLINE"><em>Input line</em></a></dt> + <dd> + A line of text as it appears in your text editor. + </dd> + + <dt><a name="TERMS_MACROS"><em>Macros</em></a></dt> + <dd> + Instructions embedded in a document that determine how groff + processes the text for output. <strong>mom</strong>'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 — behind the scenes — via + groff + <a href="#TERMS_PRIMITIVES">primitives</a>. + </dd> + + <dt><a name="TERMS_UNITS"><em>Machine units</em></a></dt> + <dd> + A machine unit is 1/1000 of a + <a href="#TERMS_PICASPOINTS">point</a> + when the groff device is ps. ("ps" means + "PostScript" — the default device for + which groff prepares output, and the device for which + <strong>mom</strong> was specifically designed.) + </dd> + + <dt><a name="TERMS_NUMERICARGUMENT"><em>Numeric argument</em></a></dt> + <dd> + An + <a href="#TERMS_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="#TERMS_UNITOFMEASURE">unit of measure</a>, + a unit of measure must be appended to <em>every</em> digit in + the argument. For example: + + <pre> + .ALD 1i-1v + </pre> + + <strong>NOTE:</strong> 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 + <strong>mom</strong>'s macros is slim. + </dd> + + <dt><a name="TERMS_OUTPUTLINE"><em>Output line</em></a></dt> + <dd> + A line of text as it appears in output copy. + </dd> + + <dt><a name="TERMS_PRIMITIVES"><em>Primitives</em></a></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's primitive requests are two + letters long. + </dd> + + <dt><a name="TERMS_STRINGARGUMENT"><em>String Argument</em></a></dt> + <dd> + Technically, any + <a href="#TERMS_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="#TERMS_MACROS">macro</a> + + <pre> + .TITLE "My Pulitzer Novel" + </pre> + + <kbd>My Pulitzer Novel</kbd> is a string argument. + + <p> + Because string arguments must be enclosed by double-quotes, you + can'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="#TERMS_INLINES">inline escapes</a> + <strong>\(lq</strong> and <strong>\(rq</strong> (leftquote and + rightquote respectively) in place of the double-quote character + (<strong>"</strong>). + </p> + + </dd> + + <dt><a name="TERMS_UNITOFMEASURE"><em>Unit of measure</em></a></dt> + <dd> + The single letter after a + <a href="#TERMS_NUMERICARGUMENT">numeric argument</a> + that tells <strong>mom</strong> what measurement scale the + argument should use. Common valid units are: + + <pre> + i (inches) + p (points) + P (Picas) + c (centimetres) + m (ems) + n (ens) + v (the current leading (line space)) + </pre> + + <p> + 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: + + <pre> + .ALD 2v + .LL 39P + .IL 1i + </pre> + + The above example advances 2 line spaces and sets the line + length to 39 picas with a left indent of 1 inch. + </p> + + <p> + <strong>IMPORTANT:</strong> Most <strong>mom</strong> macros + that set the size or measure of something MUST be given a + unit of measure. <strong>mom</strong>'s macros do not have + default units of measure. There are a couple of exceptions, + the most notable of which are <strong>PT_SIZE</strong> and + <strong>LS</strong>. Both use + <a href="#TERMS_PICASPOINTS">points</a> + as the default unit of measure, which means you don't have to + append "p" to their argument. + </p> + + <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> + + <p> + <strong>NOTE:</strong> 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> + + </dd> + + <dt><a name="TERMS_ZEROWIDTHCHARACTER"><em>Zero-width character</em></a></dt> + <dd> + The + <a href="#TERMS_INLINES">inline escape</a> + that allows you to print a literal period, apostrophe and, if + <a href="#TERMS_OUTPUTLINE">output lines</a> + are + <a href="#TERMS_FILLED">filled</a>, + a space that falls at the beginning of an + <a href="#TERMS_INPUTLINE">input line</a>. + It looks like this: + + <pre> + \& (backslash followed by an ampersand) + </pre> + + Normally, groff interprets a period (or an apostrophe) at the + beginning of an input line as meaning that what follows is a + <a href="#TERMS_CONTROLLINES">control line</a>. + In fill modes, groff treats a space at the beginning of an input + line as meaning "start a new line and put a space at the + beginning of it." 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> + +<hr/> + +<a name="TERMS_MOM"><h2><u>Mom's Document Processing Terms</u></h2></a> + +<ul> + <li><a href="#TERMS_BLOCKQUOTE">Blockquote</a></li> + <li><a href="#TERMS_CONTROLMACRO">Control macro</a></li> + <li><a href="#TERMS_DOCHEADER">Docheader</a></li> + <li><a href="#TERMS_EPIGRAPH">Epigraph</a></li> + <li><a href="#TERMS_FOOTER">Footer</a></li> + <li><a href="#TERMS_HEAD">Head</a></li> + <li><a href="#TERMS_HEADER">Header</a></li> + <li><a href="#TERMS_LINEBREAK">Linebreak</a></li> + <li><a href="#TERMS_PARAHEAD">Paragraph head</a></li> + <li><a href="#TERMS_QUOTE">Quote</a></li> + <li><a href="#TERMS_RUNNING">Running text</a></li> + <li><a href="#TERMS_SUBHEAD">Subhead</a></li> + <li><a href="#TERMS_TOGGLE">Toggle</a></li> +</ul> +<dl> + <dt><a name="TERMS_BLOCKQUOTE"><em>Blockquote</em></a></dt> + <dd> + Cited material other than + <a href="#TERMS_QUOTE">quotes</a>. + Typically set at a smaller point size than paragraph text, + indented from the left and right margins. Blockquotes are + <a href="#TERMS_FILLED">filled</a>. + </dd> + + <dt><a name="TERMS_CONTROLMACRO"><em>Control macro</em></a></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="#TERMS_HEADER">headers</a>, + etc.). + </dd> + + <dt><a name="TERMS_DOCHEADER"><em>Document header/docheader</em></a></dt> + <dd> + Document information (title, subtitle, author, etc) output at + the top of page one. + </dd> + + <dt><a name="TERMS_EPIGRAPH"><em>Epigraph</em></a></dt> + <dd> + A short, usually cited passage that appears at the beginning of + a chapter, story, or other document. + </dd> + + <dt><a name="TERMS_FOOTER"><em>Footer/page footer</em></a></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="#TERMS_RUNNING">running text</a>. + </dd> + + <dt><a name="TERMS_HEAD"><em>Head</em></a></dt> + <dd> + A title that introduces a major section of a document. + </dd> + + <dt><a name="TERMS_HEADER"><em>Header/page header</em></a></dt> + <dd> + Document information (frequently author and title) output in the + top margin of pages <em>after</em> page one. + + <p> + <strong>NOTE:</strong> In terms of content and style, headers + and + <a href="#TERMS_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> + + </dd> + + <dt><a name="TERMS_LINEBREAK"><em>Linebreak/author linebreak</em></a></dt> + <dd> + A horizontal gap in + <a href="#TERMS_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><a name="TERMS_PARAHEAD"><em>Paragraph head</em></a></dt> + <dd> + A title joined to the body of a paragraph; hierarchically one + level beneath + <a href="#TERMS_SUBHEAD">subheads</a>. + </dd> + + <dt><a name="TERMS_QUOTE"><em>Quote</em></a></dt> + <dd> + A quote, to <strong>mom</strong>, is a line-for-line setting + of quoted material (e.g. poetry, song lyrics, or a snippet of + programming code). You don't have to use + <a href="typesetting.html#BR">BR</a> + with quotes. + </dd> + + <dt><a name="TERMS_RUNNING"><em>Running text</em></a></dt> + <dd> + In a document formatted with <strong>mom</strong>, running + text means text that forms the body of the document, including + elements such as heads and subheads. + <a href="#TERMS_DOCHEADER">Docheaders</a>, + <a href="#TERMS_HEADER">headers</a>, + <a href="#TERMS_FOOTER">footers</a> + and page numbers are NOT part of running text. + </dd> + + <dt><a name="TERMS_SUBHEAD"><em>Subhead</em></a></dt> + <dd> + A title used to introduce secondary sections of a document; + hierarchically one level beneath sections introduced by + <a href="#TERMS_HEAD">heads</a>. + </dd> + + <dt><a name="TERMS_TOGGLE"><em>Toggle</em></a></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> + +<hr/> + +<p> +<a href="using.html#TOP">Next</a> +<a href="intro.html#TOP">Prev</a> +<a href="#TOP">Top</a> +<a href="toc.html">Back to Table of Contents</a> +</p> + +</body> +</html> +<!-- vim: fileencoding=latin1: nomodified: +--> diff --git a/contrib/mom/momdoc/docelement.html b/contrib/mom/momdoc/docelement.html new file mode 100644 index 00000000..2d8d1b3f --- /dev/null +++ b/contrib/mom/momdoc/docelement.html @@ -0,0 +1,6937 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!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=iso-8859-1"/> +<title>Mom -- Document Processing, element tags</title> +</head> +<body bgcolor="#dfdfdf"> + +<!-- ==================================================================== --> + +<a name="TOP"></a> + +<p> +<a href="headfootpage.html#TOP">Next</a> +<a href="docprocessing.html#TOP">Prev</a> +<a href="toc.html">Back to Table of Contents</a> +</p> + +<a name="DOCELEMENT"><h1 align="center"><u>The document element tags</u></h1></a> + +<ul> + <li><a href="#DOCELEMENT_INTRO">Introduction to the document element tags</a></li> + <ul> + <li><a href="#DOCELEMENT_CONTROL">Control macros — changing defaults for document element tags</a></li> + <li><a href="#CONTROL_MACRO_ARGS">Arguments to the control macros</a></li> + <ul> + <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 style</a></li> + <li><a href="#UNDERLINE">Underline style, rule weight</a></li> + </ul> + </ul> + <li><a href="#INDEX_DOCELEMENT">Index of document element tags</a></li> +</ul> + +<a name="DOCELEMENT_INTRO"><h2><u>Introduction to the document element tags</u></h2></a> + +<p> +Once you've completed the setup for a document (see +<a href="docprocessing.html#DOCPROCESSING_TUT">Setting up a mom document</a>), +formatting it is a snap. Simply invoke the appropriate tag for +each document element as you need it. The tags are macros that +tell <strong>mom</strong>, "This is a paragraph, this +is a subhead, this is a footnote," and so on. +</p> + +<p> +The list of tags is actually quite small — ideal for the users +<strong>mom</strong> 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#TERMS_CONTROLMACRO">control macros</a> +for the tag's family, font and point size. Where appropriate, there +are macros to control leading, indents, quad and special features as +well. +</p> + +<p> +<strong>Mom</strong> has tasteful defaults for all the tags, hence +you only use the control macros when you want to change the way she +does things. This is usually done prior to +<a href="docprocessing.html#START">START</a>, +but can, in fact, be done at any time in the course of a document. +Any change to a tag's style affects all subsequent invocations of +the tag. +</p> + +<p> + +<a name="DOCELEMENT_CONTROL"><h3><u>Control macros — changing defaults</u></h3></a> + +</p> + +<p> +The control macros for document processing tags let you +"design" the look of all the parts of your documents +— should you wish. At a bare minimum, all tags have macros to +change <strong>mom</strong>'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 <strong>mom</strong>'s defaults for the tag are. +</p> + +<p> +The control macros may be used at any time during the course of +a document (i.e. before or after +<a href="docprocessing.html#START">START</a>). The changes you +make alter all subsequent invocations of the affected tag until you +make another change, either by passing new arguments to the tag's +control macro, or toggling a particular feature of the tag on or +off. +</p> + +<p> +And don't forget: the +<a href="typesetting.html#MACROS_TYPESETTING">typesetting macros</a> +can be used at any time, including inside +<a href="definitions.html#TERMS_TOGGLE">toggle</a> +tags (affecting only that particular invocation of the tag). +Equally, +<a href="definitions.html#TERMS_INLINES">inline escapes</a> +can be used in tags that take +<a href="definitions.html#TERMS_STRINGARGUMENT">string arguments.</a> +</p> + +<p> +<strong>IMPORTANT NOTE:</strong> The family, font, point size, +colour and leading control macros have no effect in +<a href="docprocessing.html#PRINTSTYLE">PRINTSTYLE TYPEWRITE</a>, +which sets EVERYTHING in Courier roman, 12/24 (i.e. 12-point type on +a linespace of 24 points). +</p> + +<p> +Please also note that the defaults listed with the control macros +apply only to +<a href="docprocessing.html#PRINTSTYLE">PRINTSTYLE TYPESET</a> +unless a default for <strong>TYPEWRITE</strong> is also given. +</p> + +<p> +<strong>A WORD OF ADVICE:</strong> Get familiar with +<strong>mom</strong> at her default settings before exploring the +control macros. Put her through her paces. See how she behaves. +Get to know what she feels like and how she looks, both in your +text editor and on the printed page. Then, if you don't like +something, use this documentation to find the precise macro you need +to change it. There are tons of control macros. Reading up on +them and trying to remember them all might lead you to think that +<strong>mom</strong> is complex and unwieldy, which is not only +untrue, but would offend her mightily. +</p> + +<a name="CONTROL_MACRO_ARGS"><h4><u>Arguments to the control macros</u></h4></a> + +<a name="FAMILY_AND_FONT"><h5><u>Family and font</u></h5></a> + +<p> +The arguments to the control macros that end in +<strong>_FAMILY</strong> or <strong>_FONT</strong> are the same +as for +<a href="typesetting.html#FAMILY">FAMILY</a> +and +<a href="typesetting.html#FONT">FT</a>. +</p> + +<a name="POINT_SIZE"><h5><u>Point size</u></h5></a> + +<p> +Control macros that end in <strong>_SIZE</strong> always take +the form <kbd>+digit</kbd> or <kbd>-digit</kbd> where digit is +the number of +<a href="definitions.html#TERMS_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 + +<pre> + .SUBHEAD_SIZE +1.5 +</pre> +</p> + +<p> +There's no need for a +<a href="definitions.html#TERMS_UNITOFMEASURE">unit of measure</a> +with the <strong>_SIZE</strong> control macros; points is assumed. +</p> + +<a name="COLOR"><h5><u>Colour</u></h5></a> + +<p> +Control macros that end in <strong>_COLOR</strong> take as their +argument a colour name pre-defined (or "initialized") +with +<a href="color.html#NEWCOLOR">NEWCOLOR</a> +or +<a href="color.html#XCOLOR">XCOLOR</a>. +For example, if you want your heads to be red, once you've defined +or initialized the color, red, + +<pre> + .HEAD_COLOR red +</pre> + +will turn your heads red. +</p> + +<a name="LEAD"><h5><u>Lead/linespacing</u></h5></a> + +<p> +Control macros that end in <strong>_AUTOLEAD</strong> take the +same argument as +<a href="typesetting.html#AUTOLEAD">AUTOLEAD</a>, +viz. a digit that represents the number of points to add to the +tag's point size to arrive at its +<a href="definitions.html#TERMS_LEADING">lead</a>. +For example, to set footnotes +<a href="definitions.html#TERMS_SOLID">solid</a>, do + +<pre> + .FOOTNOTE_AUTOLEAD 0 +</pre> +</p> + +<p> +To set footnotes with a 1-point lead (i.e. with the line spacing +one point greater than the footnote's point size), do + +<pre> + .FOOTNOTE_AUTOLEAD 1 +</pre> +</p> + +<a name="CONTROL_INDENTS"><h5><u>Indents</u></h5></a> + +<p> +Except for +<a href="docelement.html#PARA_INDENT">PARA_INDENT</a>, +the argument to the control +macros that end in <strong>_INDENT</strong> can take either a single +digit (whole numbers only; no decimal fractions) with <em>no</em> +<a href="definitions.html#TERMS_UNITOFMEASURE">unit of measure</a> +appended to it, or a digit <em>with</em> a unit of measure appended. +</p> + +<p> +A digit with <em>no</em> unit of measure appended represents by +how much you want your paragraph first-line indents (set with +<strong>PARA_INDENT</strong>) multiplied to achieve the correct +indent for a particular tag. +</p> + +<p> +A digit <em>with</em> a unit of measure appended defines an +absolute indent, relative to nothing. +</p> + +<a name="QUAD"><h5><u>Quad/justification style</u></h5></a> + +<p> +Control macros that end in <strong>_QUAD</strong> take the same +arguments as +<a href="typesetting.html#QUAD">QUAD</a>. +</p> + +<a name="UNDERLINE"><h5><u>Underline style, rule weight</u></h5></a> + +<p> +If <strong>mom</strong> gives the option to underline a document +element, the weight of the underline and its distance from the +<a href="definitions.html#TERMS_BASELINE">baseline</a> +are controlled by macros +that end in <strong>_UNDERLINE</strong>. +</p> + +<p> +Page elements that are separated from +<a href="definitions.html#TERMS_RUNNING">running text</a> +by a rule (i.e. page headers, page footers and footnotes) are +controlled by macros that end in <strong>_RULE_WEIGHT</strong>. +</p> + +<p> +The weight argument to <strong>_UNDERLINE</strong> macros is +the same as the argument to +<a href="inlines.html#RULE_WEIGHT">RULE_WEIGHT</a>, +as is the argument to <strong>_RULE_WEIGHT</strong> macros. +</p> + +<a name="INDEX_DOCELEMENT"><h2><u>Document element tags list</u></h2></a> + +<ul> + <li><a href="#EPIGRAPH_INTRO">Epigraphs</a></li> + <ul> + <li><a href="#EPIGRAPH">EPIGRAPH</a></li> + <li><a href="#EPIGRAPH_CONTROL">Epigrah control</a></li> + </ul> + <li><a href="#PP_INTRO">Paragraphs</a></li> + <ul> + <li><a href="#PP">PP</a></li> + <li><a href="#PP_CONTROL">Paragraph control</a></li> + </ul> + <li><a href="#HEAD_INTRO">Main heads</a></li> + <ul> + <li><a href="#HEAD">HEAD</a></li> + <li><a href="#HEAD_CONTROL">Head control</a></li> + </ul> + <li><a href="#SUBHEAD_INTRO">Subheads</a></li> + <ul> + <li><a href="#SUBHEAD">SUBHEAD</a></li> + <li><a href="#SUBHEAD_CONTROL">Subhead control</a></li> + </ul> + <li><a href="#PARAHEAD_INTRO">Paragraph heads</a></li> + <ul> + <li><a href="#PARAHEAD">PARAHEAD</a></li> + <li><a href="#PARAHEAD_CONTROL">Parahead control</a></li> + </ul> + <li><a href="#LINEBREAK_INTRO">Linebreaks (author linebreaks, section breaks)</a></li> + <ul> + <li><a href="#LINEBREAK">LINEBREAK</a></li> + <li><a href="#LINEBREAK_CHAR">Linebreak character</a></li> + <li><a href="#LINEBREAK_COLOR">Linebreak colour</a></li> + </ul> + <li><a href="#QUOTE_INTRO">Quotes (line for line)</a></li> + <ul> + <li><a href="#QUOTE">QUOTE</a></li> + <li><a href="#QUOTE_CONTROL">Quote control</a></li> + </ul> + <li><a href="#BLOCKQUOTE_INTRO">Blockquotes (cited material)</a></li> + <ul> + <li><a href="#BLOCKQUOTE">BLOCKQUOTE</a></li> + <li><a href="#BLOCKQUOTE_CONTROL">Blockquote control</a></li> + </ul> + <li><a href="#CODE">CODE</a> (inserting code snippets into documents)</li> + <li><a href="#LIST_INTRO">Nested lists</a></li> + <ul> + <li><a href="#LIST">LIST</a></li> + <ul> + <li><a href="#ITEM">ITEM</a></li> + </ul> + <li><a href="#LIST_CONTROL">List control</a></li> + </ul> + <li><a href="#NUMBER_LINES_INTRO">Line numbering</a></li> + <ul> + <li><a href="#NUMBER_LINES">NUMBER_LINES</a></li> + <li><a href="#NUMBER_LINES_CONTROL">Control macros</a></li> + <ul> + <li><a href="#NUMBER_LINES_CONTROL_QUOTE">Line numbering control for QUOTE and BLOCKQUOTE</a></li> + </ul> + </ul> + <li><a href="#FOOTNOTE_INTRO">Footnotes</a></li> + <ul> + <li><a href="#FOOTNOTE">FOOTNOTE</a></li> + <li><a href="#FOOTNOTE_CONTROL">Footnote control</a></li> + </ul> + <li><a href="#ENDNOTE_INTRO">Endnotes</a></li> + <ul> + <li><a href="#ENDNOTE">ENDNOTE</a></li> + <li><a href="#ENDNOTE_CONTROL">Endnote control</a></li> + </ul> + <li><a href="#MARGIN_NOTES_INTRO">Margin notes</a></li> + <ul> + <li><a href="#MN_INIT">MN_INIT</a> — initialize margin notes</li> + <li><a href="#MN">MN</a> — start and end a margin note</li> + </ul> + <li><a href="refer.html#TOP">Bibliographies and references</a></li> + <ul> + <li><a href="refer.html#REF">REF</a></li> + <li><a href="refer.html#ENDNOTE_REFS">ENDNOTE_REFS</a></li> + <li><a href="refer.html#FOOTNOTE_REFS">FOOTNOTE_REFS</a></li> + <li><a href="refer.html#BRACKET_REFS">Embedded references</a></li> + <li><a href="refer.html#BIBLIOGRAPHY">BIBLIOGRAPHY</a></li> + <li><a href="refer.html#BIBLIOGRAPHY_TYPE">BIBLIOGRAPHY_TYPE</a></li> + <li><a href="refer.html#BIBLIO_CONTROL">Bibliography pages style control</a></li> + </ul> + <li><a href="#BLANK_PAGE_TITLE">Blank pages</a></li> + <li><a href="#TOC_INTRO">Tables of contents</a></li> + <ul> + <li><a href="#TOC">TOC</a></li> + <li><a href="#TOC_CONTROL">Table of contents control</a></li> + </ul> + <li><a href="#FINIS_INTRO">Document termination</a></li> + <ul> + <li><a href="#FINIS">FINIS (Document termination)</a></li> + <li><a href="#FINIS_STRING">Changing the FINIS string</a></li> + <li><a href="#FINIS_COLOR">Changing the FINIS colour</a></li> + </ul> + <li><a href="#PSPIC">Inserting images into a document — the PSPIC macro</a></li> +</ul> + +<hr/> + +<!-- ==================================================================== --> + +<a name="EPIGRAPH_INTRO"><h2><u>Epigraphs</u></h2></a> + +<ul> + <li><a href="#EPIGRAPH">Tag: EPIGRAPH</a></li> + <li><a href="#EPIGRAPH_CONTROL">Epigraph control macros</a></li> +</ul> + +<p> +<a href="definitions.html#TERMS_EPIGRAPH">Epigraphs</a> +colour, flavour, or comment on the document they precede. +Typically, they are centred at the top of a document's first page +(underneath the title) and set in a smaller point size than that of +paragraph text. +</p> + +<p> +By default, <strong>mom</strong> sets epigraphs centred and +<a href="definitions.html#TERMS_NOFILL">unfilled</a>; +this lets you input them on a line for line basis. This behaviour +can be changed to accomodate +<a href="definitions.html#TERMS_FILLED">filled</a> +epigraph "blocks." +</p> + +<!-- -EPIGRAPH- --> + +<hr width="66%" align="left"/> + +<a name="EPIGRAPH"></a> + +<p> +<nobr>Macro: <strong>EPIGRAPH</strong> <kbd><toggle> | [ BLOCK ]</kbd></nobr> +</p> + +<p> +<strong>EPIGRAPH</strong> is a toggle, used like this: + +<pre> + .EPIGRAPH + <text of epigraph> + .EPIGRAPH OFF +</pre> +</p> + +<p> +<kbd>OFF</kbd>, above, could be anything — say, <kbd>Q</kbd> +or <kbd>X</kbd> — since any argument other than +<kbd>BLOCK</kbd> turns it off. +</p> + +<p> +If given the argument, <kbd>BLOCK</kbd>, <strong>EPIGRAPH</strong> +sets epigraphs +<a href="definitions.html#TERMS_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 <strong>must</strong> introduce every paragraph +— <u>INCLUDING THE FIRST!!!</u> — with the +<a href="#PP">PP</a> +tag. +</p> + +<p> +<strong>NOTE:</strong> <strong>EPIGRAPH</strong> 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> + +<hr width="33%" align="left"/> + +<a name="EPIGRAPH_CONTROL"><h3><u>Epigraph control macros</u></h3></a> + +<p> +See +<a href="#CONTROL_MACRO_ARGS">Arguments to the control macros</a>. +</p> + +<pre> +.EPIGRAPH_FAMILY default = prevailing document family; default is Times Roman +.EPIGRAPH_FONT default = roman +.EPIGRAPH_SIZE default = -1.5 (points) +.EPIGRAPH_COLOR default = black +.EPIGRAPH_AUTOLEAD default = 2 points + +(The next two apply to "block" style epigraphs only) + +.EPIGRAPH_QUAD default = same as paragraphs +.EPIGRAPH_INDENT* (see below) + +*Indent here refers to the indent from both the left and right margins + that centres the block style epigraph on the page. +</pre> + +<a name="EPIGRAPH_INDENT"><h4><u>Epigraph indent</u></h4></a> + +<p> +Prior to version 1.4-b, <strong>mom</strong> allowed +only the passing of an integer to the macro, +<strong>EPIGRAPH_INDENT</strong>. 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#TERMS_UNITOFMEASURE">unit of measure</a> +to the argument passed to <strong>EPIGRAPH_INDENT</strong>, +thus setting an absolute indent, relative to nothing. The old +behaviour is still respected, though; in other words, if you pass +<strong>EPIGRAPH_INDENT</strong> an integer with no unit of measure +appended, the integer represents the amount by which to multiply +<strong>PARA_INDENT</strong> to arrive at an indent for block style +epigraphs. +</p> + +<p> +Please note that if your <strong>PARA_INDENT</strong> +is <kbd>0</kbd> (i.e. no indenting of the first line of +paragraphs), you <em><strong>must</strong></em> set an +<strong>EPIGRAPH_INDENT</strong> yourself, with a unit of measure +appended to the argument. <strong>Mom</strong> has no default for +<strong>EPIGRAPH_INDENT</strong> if paragraph first lines are not being +indented. +</p> + +<p> +The default value for <strong>EPIGRAPH_INDENT</strong> is 3 (for +<a href="docprocessing.html#PRINTSTYLE">PRINTSTYLE TYPESET</a>) +and 2 (for +<a href="docprocessing.html#PRINTSTYLE">PRINTSTYLE TYPEWRITE</a>). +</p> + +<hr/> + +<!-- ==================================================================== --> + +<a name="PP_INTRO"><h2><u>Paragraphs</u></h2></a> + +<ul> + <li><a href="#PP">Tag: PP</a></li> + <li><a href="#PP_CONTROL">Paragraph control macros</a></li> +</ul> + +<p> +The paragraph macro is the one you use most often. Consequently, +it's one of most powerful, yet simplest to use — just +the letters <strong>PP</strong>. No arguments, nothing. Just +<kbd>.PP</kbd> on a line by itself any time, in any document +element, tells <strong>mom</strong> 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, <strong>mom</strong> 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 +<a href="#PARA_INDENT_FIRST">INDENT_FIRST_PARAS</a>. +</p> + +<p> +In contrast to some other macro sets, <strong>mom</strong> does +not deposit a blank line between paragraphs. If you want her to do +so, use the control macro <strong>PARA_SPACE</strong>. (I don't +recommend using this macro with +<a href="typesetting.html#PRINTSTYLE">PRINTSTYLE TYPEWRITE</a>.) +</p> + +<p> +Note that <strong>mom</strong> does not provide "orphan +control" for paragraphs (i.e. even if only one line of a +paragraph fits at the bottom of a page, she will set it on that +page). The reason for this is that writers of fiction often have +single-line paragraphs (e.g. in dialogue). Groff's simplistic +orphan control will break these one-liners — if they fall at +the bottom of the page — to a new page, which is not what you +want. +</p> + +<p> +<strong>TIP:</strong> The last thing you want while you're writing +and editing drafts of a document (particularly stories and chapters) +is a text file cluttered up with <strong>PP</strong>'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 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 character generated by the tab key +<nobr>( <kbd>^I</kbd> )</nobr> into <kbd>.PP</kbd> (plus a new +line), and pipes the output to groff for processing and printing. +</p> + +<p> +Another solution is to insert a blank line between paragraphs. +The blank lines can then be sedded out at print time as above, or, +more conveniently, you can use the <kbd>.blm</kbd> +<a href="definitions.html#TERMS_PRIMITIVES">primitive</a> +(blank line macro) to instruct groff (and <strong>mom</strong>) +that blank lines should be interpreted as <strong>PP</strong>'s. + +<pre> + .blm PP +</pre> + +tells groff that all blank lines are really the macro <strong>PP</strong>. +</p> + +<!-- -PP- --> + +<hr width="66%" align="left"/> + +<a name="PP"></a> + +<p> +<nobr>Macro: <strong>PP</strong></nobr> +</p> + +<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 <strong>PP</strong> in +<a href="#EPIGRAPH_INTRO">epigraphs</a>, +<a href="#BLOCKQUOTE_INTRO">blockquotes</a> +and +<a href="#FOOTNOTE_INTRO">footnotes</a>. +</p> + +<hr width="33%" align="left"/> + +<a name="PP_CONTROL"><h3><u>Paragraph control macros</u></h3></a> + +<p> +The <strong>PP</strong> 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> + <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> + +<a name="PP_FAMILY"><h4><u>1. Family</u></h4></a> + +<p> +The paragraph +<a href="definitions.html#TERMS_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> +<strong>Mom</strong>'s default paragraph (and document) family +is Times Roman. +</p> + +<a name="PP_FONT"><h4><u>2. Font — PP_FONT</u></h4></a> + +<p> +To change the +<a href="definitions.html#TERMS_FONT">font</a> +used in regular text paragraphs, use <kbd>.PP_FONT</kbd>, +which takes the same argument as +<a href="typesetting.html#FONT">FT</a>. +<strong>PP_FONT</strong> 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> +<strong>Mom</strong>'s default paragraph font is medium roman. +</p> + +<a name="PP_COLOR"><h4><u>3. Paragraph colour</u></h4></a> + +<p> +<strong>Mom</strong> 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#TERMS_INLINE">inline escape</a>, +<a href="color.html#COLOR_INLINE"><kbd>\*[<colorname>]</kbd></a>, +<em>after</em> <kbd>.PP</kbd>. The colour must be one pre-defined +(or "initialized") with +<a href="color.html#NEWCOLOR">NEWCOLOR</a> +or +<a href="color.html#XCOLOR">XCOLOR</a>. +</p> + +<p> +Please note that unless you change the colour back to it's default +(usually black) at the end of the paragraph, all subsequent +paragraphs will be set in the new colour, although most other +elements of your document will continue to be set in the default +colour (usually black). +</p> + +<p> +For example, assuming you have defined the colour, blue, + +<pre> + .PP + .COLOR blue + <first paragraph> + .HEAD "Monty Python" + .SUBHEAD "The Origins of Spam" + .PP + <second paragraph> +</pre> + +the first paragraph will be blue, the head and subhead will be in +the document's default colour (usually black), and the second +paragraph will be in blue. +</p> + +<p> +The one document element that is affected by changing the colour of +paragraphs is +<a href="#PARAHEAD">paraheads</a>, +since paraheads are attached directly to the body of paragraphs. In +other words, if you change the colour of a paragraph and do not +reset the paragraph colour back to its default, subsequent paraheads +will appear in the same colour as your paragraphs unless you have +explicitly told <strong>mom</strong> you want a pre-defined (or +"initialized") color (usually black) for your paraheads. +</p> + +<p> +See the footnote to +<a href="#PARAHEAD_COLOR">PARAHEAD_COLOR</a>. +</p> + +<a name="PP_LEADING"><h4><u>4. Leading</u></h4></a> + +<p> +The paragraph +<a href="definitions.html#TERMS_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#TERMS_HEADER">headers</a> +and +<a href="definitions.html#TERMS_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> + +<p> +<strong>HYPER-IMPORTANT NOTE:</strong> It is extremely unwise to +change paragraph leading with <strong>LS</strong>, as it will, +in all cases, screw up <strong>mom</strong>'s ability to balance +the bottom margin of pages. Should you absolutely need to change +paragraph leading with <strong>LS</strong>, and subsequently want +<strong>mom</strong> to get back on the right leading track, use the +<a href="docprocessing.html#SHIM">SHIM</a> +macro. +</p> + +<p> +<strong>Mom</strong>'s default paragraph leading (document leading) +is 16 points, adjusted to fill the page. +</p> + +<a name="PP_JUST_QUAD"><h4><u>5. Justification/quad</u></h4></a> + +<p> +The justification/quad-direction of regular text paragraphs (i.e. +<a href="definitions.html#TERMS_JUST">justified</a>, +or +<a href="definitions.html#TERMS_FILLED">filled</a> +and +<a href="definitions.html#TERMS_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> +<strong>Mom</strong>'s default justification/quad-direction for +paragraphs is + +<ul> + <li>justified, for + <a href="docprocessing.html#PRINTSTYLE">PRINTSTYLE_TYPESET</a> + </li> + <li>quad left, for + <a href="docprocessing.html#PRINTSTYLE">PRINTSTYLE_TYPEWRITE</a> + </li> +</ul> +</p> + +<a name="PARA_INDENT"><h4><u>6. First-line indent — PARA_INDENT</u></h4></a> + +<p> +The first-line indent of paragraphs is controlled by +<kbd>.PARA_INDENT</kbd>, which takes one argument: the size of +the indent. <strong>PARA_INDENT</strong> may be used before or after +<a href="docprocessing.html#START">START</a>. +A +<a href="definitions.html#TERMS_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#TERMS_EM">ems</a>, do + +<pre> + .PARA_INDENT 4.5m +</pre> +</p> + +<p> +In addition to establishing the basic first line-indent of +paragraphs, <strong>PARA_INDENT</strong> 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 <strong>PARA_INDENT</strong> if +the <strong>_INDENT</strong> control macro for these tags has +no <a href="definitions.html#TERMS_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 <strong>PARA_INDENT</strong> (always 1/2 of +<strong>PARA_INDENT)</strong>), hence they are also affected. +</p> + +<p> +<strong>Mom</strong>'s default <strong>PARA_INDENT</strong> is 2 ems +for +<a href="docprocessing.html#PRINTSTYLE">PRINTSTYLE_TYPESET</a> +and 3 picas (1/2 inch) for +<a href="docprocessing.html#PRINTSTYLE">PRINTSTYLE_TYPEWRITE</a>. +</p> + +<a name="PARA_INDENT_FIRST"><h4><u>7. Indenting initial paragraphs — INDENT_FIRST_PARAS</u></h4></a> + +<p> +By default, <strong>mom</strong> 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. +<a name="INDENT_FIRST_PARAS"></a> +</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>. +<strong>INDENT_FIRST_PARAS</strong> is a toggle macro, therefore +passing it any argument (<strong>OFF, QUIT, Q, X</strong>...) +cancels its effect, meaning that first paragraphs will once again +NOT be indented. +</p> + +<a name="PP_SPACE"><h4><u>8. Spacing paragraphs — PARA_SPACE</u></h4></a> + +<p> +By default, <strong>mom</strong> 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>. +<strong>PARA_SPACE</strong> is a toggle macro, therefore passing +it any argument (<strong>OFF, QUIT, Q, X</strong>...) cancels its +effect, meaning that paragraphs will once again NOT be separated by +a blank line. +</p> + +<p> +<strong>NOTE:</strong> If <strong>PARA_SPACE</strong> is on, +<strong>mom</strong> spaces only those paragraphs that come after +an "initial" paragraph. Initial paragraphs are those +that come immediately after the +<a href="definitions.html#TERMS_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> +Sometimes, you can be fairly deep into a document before using +<strong>PP</strong> for the first time, and when you do, because +<strong>mom</strong> is still waiting for that "initial" +paragraph, she doesn't space it with a blank line, even though +you expect her to. The simple workaround for this is to invoke +<kbd>.PP</kbd> <em>twice</em> (in succession) at the point you +expect the blank line to appear. +</p> + +<hr/> + +<!-- ==================================================================== --> + +<a name="HEAD_INTRO"><h2><u>Main heads</u></h2></a> + +<ul> + <li><a href="#HEAD">Tag: HEAD</a></li> + <li><a href="#HEAD_CONTROL">Head control macros</a></li> +</ul> + +<p> +Main heads — or, in this documentation, just "heads" +— should be used any place you want titles to introduce +major sections of a document. If you wish, <strong>mom</strong> +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 TYPESET</a>, +heads are bold, slightly larger than paragraph text. +</p> + +<p> +If these defaults don't suit you, you can change them with the +head control macros. +</p> + +<!-- -HEAD- --> + +<hr width="66%" align="left"/> + +<a name="HEAD"></a> + +<p> +<nobr>Macro: <strong>HEAD</strong> <kbd>"<text of head>" [ "<2nd line>" [ "<3rd line>" ... ] ]</kbd></nobr> +</p> + +<p> +The argument to <strong>HEAD</strong> 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> + +<p> +<strong>NOTE:</strong> If a head falls near the bottom of an output +page and <strong>mom</strong> is unable to fit the head <em>plus at +least one line of text underneath it</em>, she will set the head at +the top of the next page. +</p> + +<p> +<strong>ADDITIONAL NOTE:</strong> If an +<a href="definitions.html#TERMS_INPUTLINE">input line</a> +in a head (i.e. one of the lines surrounded by double-quotes) has +to be broken by <strong>mom</strong> in order to fit the current +line-length (say, a narrow column measure), the head underline +(underscore) will not behave. You'll recognize the problem as soon +as you preview your document. If you encounter a head that +misbehaves with respect to underlining, the solution is to +supply each line <em>as you want it</em> as a separate argument +(surrounded by double-quotes) to the <strong>HEAD</strong> macro. +</p> + +<p> +For example, if <strong>mom</strong> breaks + +<pre> + .HEAD "This is a very, very, very long head" +</pre> + +into +<pre> + This is a very, very, very + long head +</pre> + +you'll see the misbehaving underscore and should change the +argument to <strong>HEAD</strong> to + +<pre> + .HEAD "This is a very, very very" "long head" +</pre> +</p> + +<hr width="33%" align="left"/> + +<a name="HEAD_CONTROL"><h3><u>Head control macros</u></h3></a> + +<p> +There are, in addition to the usual family/font/size/quad control +macros, a number of macros to manage head numbering, spacing, +underlining, and so on. Check them out if you're unhappy with +<strong>mom</strong>'s defaults. +</p> + +<ol> + <li><a href="#HEAD_GENERAL">Family/font/size/colour/quad</a></li> + <li><a href="#HEAD_CAPS">Caps</a></li> + <li><a href="#HEAD_SPACE">Pre-head space</a></li> + <li><a href="#HEAD_UNDERLINE">Underlining</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> + +<a name="HEAD_GENERAL"><h4><u>1. Family/font/size/colour/quad</u></h4></a> + +<p> +See +<a href="#CONTROL_MACRO_ARGS">Arguments to the control macros</a>. +</p> + +<pre> +.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 +</pre> + +<a name="HEAD_CAPS"><h4><u>2. Capitalizing heads — HEAD_CAPS</u></h4></a> + +<p> +By default, <strong>mom</strong> sets heads in caps, regardless +of the +<a href="definitions.html#TERMS_STRINGARGUMENT">string(s)</a> +you give to +<a href="#HEAD">HEAD</a>. +To change this behaviour, do + +<pre> + .HEAD_CAPS OFF +</pre> +</p> + +<p> +<strong>HEAD_CAPS</strong> is a toggle macro, therefore you can use +any argument you like instead of <strong>OFF</strong> (<strong>END, +QUIT, Q, X</strong>...). To turn <strong>HEAD_CAPS</strong> back +on, simply invoke it without an argument. +</p> + +<a name="HEAD_SPACE"><h4><u>3. Space before heads — HEAD_SPACE</u></h4></a> + +<p> +By default, <strong>mom</strong> deposits 2 blank lines prior to +every head. If you'd prefer just a single blank line, do + +<pre> + .HEAD_SPACE OFF +</pre> +</p> + +<p> +<strong>HEAD_SPACE</strong> is a toggle macro, therefore you can use +any argument you like instead of <strong>OFF</strong> (<strong>END, +QUIT, Q, X</strong>...). To restore the space before heads to 2 +blank lines, invoke <kbd>.HEAD_SPACE</kbd> without an argument. +</p> + +<a name="HEAD_UNDERLINE"><h4><u>4. Underlining heads — HEAD_UNDERLINE</u></h4></a> + +<p> +By default, <strong>mom</strong> underlines heads. To change this +behaviour, do + +<pre> + .HEAD_UNDERLINE OFF +</pre> +</p> + +<p> +<strong>HEAD_UNDERLINE</strong> can be used as a toggle macro, therefore you can +use any argument you like instead of <strong>OFF</strong> (<strong>END, +QUIT, Q, X</strong>...) to turn it off, or invoke it by itself to +turn head underlining on. +</p> + +<p> +As of version 1.5 of <strong>mom</strong>, you can now use +<strong>HEAD_UNDERLINE</strong> to set the weight of the underline +and its distance from the head, in addition to simply toggling head +underlining on or off. The order of arguments is <kbd>weight</kbd>, +optionally followed by <kbd>gap</kbd>, where "gap" is the +distance from the +<a href="definitions.html#TERMS_BASELINE">baseline</a> +of the head 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#TERMS_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. +<strong>Mom</strong>'s default for head underlines 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 head to +the upper edge of the underline. <strong>Mom</strong>'s default +gap for head underlines is 2 points. +</p> + +<p> +As an example, supposed you want your heads underlined with a +4-point rule separated from the head by 3 points. The way to +accomplish that is: + +<pre> + .HEAD_UNDERLINE 4 3p +</pre> + +If you wanted the same thing, but were content with +<strong>mom</strong>'s default gap of 2 points, + +<pre> + .HEAD_UNDERLINE 4 +</pre> + +would do the trick. +</p> + +<p> +Please note that if you supply a weight to +<strong>HEAD_UNDERLINE</strong>, 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> + +<a name="NUMBER_HEADS"><h3><u>5. Number heads — NUMBER_HEADS</u></h3></a> + +<p> +If you'd like your heads numbered, simply invoke +<kbd>.NUMBER_HEADS</kbd> with no argument. <strong>Mom</strong> +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 (<strong>OFF, QUIT, +END, X</strong>...). 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">PREFIX_CHAPTER_NUMBER</a> +if you'd like chapter numbers prepended to the head numbers. +</p> + +<a name="RESET_HEAD_NUMBER"><h4><u>6. Reset head numbering — RESET_HEAD_NUMBER</u></h4></a> + +<p> +Should you wish to reset the head number to "1", invoke +<kbd>.RESET_HEAD_NUMBER</kbd> with no argument. If, for some +reason, you want <strong>mom</strong> 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. + +<pre> + .RESET_HEAD_NUMBER 6 +</pre> + +Your next head will be numbered "6" and subsequent heads will +be numbered in ascending order from "6". +</p> + +<a name="HEAD_INLINES"><h4><u>7. Vertical inline escapes inside heads</u></h4></a> + +<p> +If you need to adjust the +<a href="definitions.html#TERMS_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#TERMS_ASCENDER">ascenders</a> +to line up with the ascenders of +<a href="definitions.html#TERMS_RUNNING">running text</a> +in other columns), you can embed a vertical motion +<a href="definitions.html#TERMS_INLINES">inline escape</a> +(either +<a href="inlines.html#INLINE_VERTICAL_MOM">mom</a>'s +or +<a href="inlines.html#INLINE_VERTICAL_GROFF">groff</a>'s +in the string(s) you pass to <strong>HEAD</strong>. +</p> + +<p> +For example, + +<pre> + .HEAD "\[ALD3]Text of head" + or + .HEAD "\[DOWN 3p]Text of head" +</pre> + +will lower the baseline of the head by three points. Note that +there's no need to reverse the sense of the inline escape. +</p> + +<p> +In the case of heads that run to more than one line, you must embed +the escape in the string for each line, like this: + +<pre> + .HEAD "\[ALD3]First line" "\[ALD3]Next line" + or + .HEAD "\[DOWN 3p]First line" "\[DOWN 3p]Next line" +</pre> +</p> + +<hr/> + +<!-- ==================================================================== --> + +<a name="SUBHEAD_INTRO"><h2><u>Subheads</u></h2></a> + +<ul> + <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, <strong>mom</strong> +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 TYPESET</a>, +they are set bold, slightly larger than paragraph text. In +<a href="docprocessing.html#PRINTSTYLE">PRINTSTYLE TYPEWRITE</a>, +they are underlined. A single linespace precedes them in both +printstyles, and a tiny space adjustment raises them slightly +above text that comes afterwards for greater clarity in +document structuring. +</p> + +<p> +If these defaults don't suit you, you can change them with the +subhead control macros. +</p> + +<!-- -SUBHEAD- --> + +<hr width="66%" align="left"/> + +<a name="SUBHEAD"></a> + +<p> +<nobr>Macro: <strong>SUBHEAD</strong> <kbd>"<text of subhead>" [ "<2nd line>" [ "<3rd line>" ... ] ]</kbd></nobr> +</p> + +<p> +The argument to <strong>SUBHEAD</strong> 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> + +<p> +<strong>NOTE:</strong> If a subhead falls near the bottom of an output +page and <strong>mom</strong> is unable to fit the head <em>plus at +least one line of text underneath it</em>, she will set the subhead +at the top of the next page. +</p> + +<hr width="33%" align="left"/> + +<a name="SUBHEAD_CONTROL"><h3><u>Subhead control macros</u></h3></a> + +<p> +In addition to the usual family/font/size/quad control +macros, there are macros to manage subhead numbering. +</p> + +<ol> + <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> + +<a name="SUBHEAD_GENERAL"><h4><u>1. Family/font/size/quad</u></h4></a> + +<p> +See +<a href="#CONTROL_MACRO_ARGS">Arguments to the control macros</a>. +</p> + +<pre> +.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 +</pre> + +<a name="NUMBER_SUBHEADS"><h4><u>2. Number subheads — NUMBER_SUBHEADS</u></h4></a> + +<p> +If you'd like your subheads numbered, simply invoke +<kbd>.NUMBER_SUBHEADS</kbd> with no argument. <strong>Mom</strong> +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 (<strong>OFF, QUIT, +END, X</strong>...). 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">PREFIX_CHAPTER_NUMBER</a> +if you'd like chapter numbers prepended to the subhead numbers. +</p> + +<a name="RESET_SUBHEAD_NUMBER"><h4><u>3. Reset subhead numbering — RESET_SUBHEAD_NUMBER</u></h4></a> + +<p> +Should you wish to reset the subhead number to "1", invoke +<kbd>.RESET_SUBHEAD_NUMBER</kbd> with no argument. If, for some +reason, you want <strong>mom</strong> 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. + +<pre> + .RESET_SUBHEAD_NUMBER 4 +</pre> + +Your next subhead will be numbered "4" and subsequent +subheads will be numbered in ascending order from "4". +</p> + +<a name="SUBHEAD_INLINES"><h4><u>Vertical inline escapes inside subheads</u></h4></a> + +<p> +See +<a href="#HEAD_INLINES">Vertical inline escapes inside heads</a>. +The information there applies equally to subheads. +</p> + +<hr/> + +<!-- ==================================================================== --> + +<a name="PARAHEAD_INTRO"><h2><u>Paragraph heads</u></h2></a> + +<ul> + <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, +<strong>mom</strong> can number paraheads for you. +</p> + +<p> +By default, paraheads are joined to the body of a paragraph, +slightly indented (provided the paragraph is not a +"first" paragraph as defined in +<a href="#PARA_INDENT_FIRST">Indenting initial paragraphs</a>). +In +<a href="docprocessing.html#PRINTSTYLE">PRINTSTYLE TYPESET</a>, +they are set bold italic, slightly larger than paragraph text. In +<a href="docprocessing.html#PRINTSTYLE">PRINTSTYLE TYPEWRITE</a>, +they are underlined. +</p> + +<p> +If these defaults don't suit you, you can change them with the +parahead control macros. +</p> + +<!-- -PARAHEAD- --> + +<hr width="66%" align="left"/> + +<a name="PARAHEAD"></a> + +<p> +<nobr>Macro: <strong>PARAHEAD</strong> <kbd>"<text of parahead>"</kbd></nobr> +</p> + +<p> +<strong>PARAHEAD</strong> 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> + +<hr width="33%" align="left"/> + +<a name="PARAHEAD_CONTROL"><h3><u>Parahead control macros</u></h3></a> + +<p> +In addition to the family/font/size/colour/indent control macros, +there are macros to manage parahead numbering. +</p> + +<ol> + <li><a href="#PARAHEAD_GENERAL">Family/font/size/color</a></li> + <li><a href="#PARAHEAD_INDENT">Indent</a></li> + <li><a href="#NUMBER_PARAHEADS">Numbering</a></li> + <li><a href="#RESET_PARAHEAD_NUMBER">Reset parahead numbering</a></li> +</ol> + +<p> +<a name="PARAHEAD_GENERAL"><h4><u>1. Family/font/size/colour</u></h4></a> +</p> + +<p> +See +<a href="#CONTROL_MACRO_ARGS">Arguments to the control macros</a>. +</p> + +<pre> +.PARAHEAD_FAMILY default = prevailing document family; default is Times Roman +.PARAHEAD_FONT default = bold italic +.PARAHEAD_SIZE default = +.5 (point) +<a name="PARAHEAD_COLOR">.PARAHEAD_COLOR default = black*</a> + +*If you colourize paragraph text, paraheads will appear in the same +colour as the text unless you explicitly tell mom to colour them +otherwise by invoking .PARAHEAD_COLOR. If you do want paraheads +that are coloured the same as paragraph text, it's generally a good +idea to invoke .PARAHEAD_COLOR anyway (with the same colour used +for paragraph text), just to let mom know. +</pre> + +<a name="PARAHEAD_INDENT"><h4><u>2. Indent</u></h4></a> + +<p> +Unlike other control macros that end in +<a href="#CONTROL_INDENTS"><strong>_INDENT</strong></a>, +the argument to the macro that controls indenting of paragraph heads +(<strong>PARAHEAD_INDENT</strong>) 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#TERMS_UNITOFMEASURE">unit of measure</a>. +For example, to set the paragraph head indent to 2-1/2 picas, you +do: + +<pre> + .PARAHEAD_INDENT 2.5P +</pre> +</p> + +<p> +<strong>Mom</strong>'s default indent for paragraph heads is 1/2 +the first-line indent of normal paragraphs (both printstyles). +However, as stated above, if you choose to change the indent, you +must give an absolute value (unless you're a groff expert and want +to manipulate the number register <kbd>\n[#PP_INDENT]u</kbd> +arithmetically as the argument to <strong>PARAHEAD_INDENT</strong> +for an indent that's relative to <strong>PP_INDENT</strong>.) +</p> + +<p> +<strong>NOTE:</strong> Paragraph heads in "first +paragraphs", as defined in +<a href="#PARA_INDENT_FIRST">Indenting initial paragraphs</a>, +are not indented unless you turn +<a href="#INDENT_FIRST_PARAS">INDENT_FIRST_PARAS</a> +on. +</p> + +<a name="NUMBER_PARAHEADS"><h4><u>3. Number paraheads — NUMBER_PARAHEADS</u></h4></a> + +<p> +If you'd like your paraheads numbered, simply invoke +<kbd>.NUMBER_PARAHEADS</kbd> with no argument. <strong>Mom</strong> +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 (<strong>OFF, QUIT, +END, X</strong>...). Parahead numbering will cease. +</p> + +<p> +See also +<a href="#PREFIX_CHAPTER_NUMBER">PREFIX_CHAPTER_NUMBER</a> +if you'd like chapter numbers prepended to the paragraph head +numbers. +</p> + +<a name="RESET_PARAHEAD_NUMBER"><h4><u>4. Reset paragraph head numbering — RESET_PARAHEAD_NUMBER</u></h4></a> + +<p> +Should you wish to reset the parahead number to "1", invoke +<kbd>.RESET_PARAHEAD_NUMBER</kbd> with no argument. If, for some +reason, you want <strong>mom</strong> 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. + +<pre> + .RESET_PARAHEAD_NUMBER 7 +</pre> +</p> + +<p> +Your next parahead will be numbered "7" and subsequent +paraheads will be numbered in ascending order from "7". +</p> + +<!-- ==================================================================== --> + +<hr width="33%" align="left"/> + +<a name="PREFIX_CHAPTER_NUMBER"></a> + +<p> +<nobr>Macro: <strong>PREFIX_CHAPTER_NUMBER</strong> <kbd><none> | <chapter number as digit> | <anything></kbd></nobr> +</p> + +<p> +If you've requested numbering of heads, subheads and/or paragraph +heads (with +<a href="#NUMBER_HEADS">NUMBER_HEADS</a>, +<a href="#NUMBER_SUBHEADS">NUMBER_SUBHEADS</a> +and/or +<a href="#NUMBER_PARAHEADS">NUMBER_PARAHEADS</a>) +and you'd like <strong>mom</strong>, in addition, to prefix +a chapter number to the numbering scheme, you can do so with +<strong>PREFIX_CHAPTER_NUMBERS</strong>. After you invoke +<kbd>.PREFIX_CHAPTER_NUMBERS</kbd>, <strong>mom</strong> 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), + +<pre> + 1. FIRST MAIN HEAD + ------------------ + +1.1. First Subhead Under Main Head +</pre> + +becomes + +<pre> + 12.1. FIRST MAIN HEAD + --------------------- + +12.1.1. First Subhead Under Main Head +</pre> +</p> + +<p> +When you invoke <kbd>.PREFIX_CHAPTER_NUMBERS</kbd> without an +argument, <strong>mom</strong> checks to see whether the argument +you passed to +<a href="docprocessing.html#CHAPTER">CHAPTER</a> +is a digit. If it is, she immediately starts pre-pending the +current chapter number to numbered head elements. If it isn't +(say you've called your chapter "One" instead of +"1"), <strong>mom</strong> will abort with a request that +you pass <strong>PREFIX_CHAPTER_NUMBER</strong> a digit representing +the current chapter number. +</p> + +<p> +In collated documents, <strong>mom</strong> automatically increments +the digit used by <strong>PREFIX_CHAPTER_NUMBER</strong> by one +(current chapter digit + 1) every time you invoke +<a href="rectoverso.html#COLLATE"><kbd>.COLLATE</kbd></a>, +even if you've (temporarily) turned off the prefixing of chapter +numbers. Thus, even if you call your chapters "One", +"Two", "Three" instead of "1", +"2", "3", <strong>mom</strong> will Do +The Right Thing with respect to numbering head elements in +all collated chapters following the first invocation of +<strong>PREFIX_CHAPTER_NUMBER</strong> (assuming, of course, +that the collated chapters are in incrementing order; if +not, you <em>must</em> must put + +<pre> + .PREFIX_CHAPTER_NUMBER <chapter number> +</pre> + +somewhere after the invocation of <strong>COLLATE</strong> and +before the first numbered head element of each collated document). +</p> + +<p> +<strong>PREFIX_CHAPTER_NUMBER</strong> can be disabled by passing +it any argument other than a digit (e.g. <strong>OFF, QUIT, END, +X</strong>, etc), although, as noted above, <strong>mom</strong> +will keep, and — in the case of collated documents — +increment the chapter number, allowing you to turn prefixing of +chapter numbers to numbered head elements off and on according to +your needs or whims. +</p> + +<p> +<strong>NOTE:</strong> Because +<strong>PREFIX_CHAPTER_NUMBER</strong> takes an (optional) digit +representing the chapter number, it's use need not be restricted to +<a href="docprocessing.html#DOCTYPE">DOCTYPE CHAPTER</a>. +You can use it with any document type. Furthermore, even if your +doctype isn't "CHAPTER", you can identify the document as +a chapter <em>for the purposes of numbering head elements</em> by +invoking the macro, +<a href="docprocessing.html#CHAPTER"><kbd>.CHAPTER</kbd></a>, +with a +<a href="definitions.html#TERMS_NUMERICARGUMENT">numeric argument</a> +in your document setup. +</p> + +<hr/> + +<!-- ==================================================================== --> + +<a name="LINEBREAK_INTRO"><h2><u>Author linebreaks (section breaks)</u></h2></a> + +<ul> + <li><a href="#LINEBREAK">Tag: LINEBREAK</a></li> + <li><a href="#LINEBREAK_CHAR">Linebreak character control macros</a></li> +</ul> + +<p> +By default, <strong>mom</strong> marks +<a href="definitions.html#TERMS_LINEBREAK">author linebreaks</a> +(also called "section breaks") with three centred asterisks. +You can change this behaviour with the linebreak character +<a href="definitions.html#TERMS_CONTROLMACRO">control macro</a>. +</p> + +<!-- -LINEBREAK- --> + +<hr width="66%" align="left"/> + +<a name="LINEBREAK"></a> + +<p> +Macro: <strong>LINEBREAK</strong> +<br/> + +Alias: <strong>SECTION</strong> +</p> + +<p> +<strong>LINEBREAK</strong> takes no arguments. Simply invoke it +(on a line by itself, of course) whenever you want to insert an +author linebreak. The appearance of the linebreak is controlled +by the +<a href="#LINEBREAK_CHAR">LINEBREAK_CHAR</a> +macro. +</p> + +<hr width="33%" align="left"/> + +<a name="LINEBREAK_CHAR"><h4><u>Linebreak character control macro</u></h4></a> + +<p> +<nobr>Macro: <strong>LINEBREAK_CHAR</strong> <kbd>[ <character> ] [ <iterations> [ <vertical adjustment> ] ]</kbd></nobr> +<br/> + +Alias: <strong>SECTION_CHAR</strong> +<br/> + +<em>*The third optional argument requires a +<a href="definitions.html#TERMS_UNITOFMEASURE">unit of measure</a></em>. +</p> + +<p> +<strong>LINEBREAK_CHAR</strong> determines what <strong>mom</strong> +prints when <strong>LINEBREAK</strong> 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]). <strong>Mom</strong> sets the character centred +on the current line length. (See "man groff_char" for a +list of all valid groff characters.) +</p> + +<p> +The second argument is the number of times to repeat the character. +</p> + +<p> +The third argument is a +|-value by which to raise (+) or lower (-) +the character in order to make it appear visually centred between +sections of text. This lets you make vertical adjustments to +characters that don't sit on the +<a href="definitions.html#TERMS_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 <strong>LINEBREAK_CHAR</strong> with no arguments, +sections of text will be separated by two blank lines when you +invoke <kbd>.LINEBREAK</kbd>. +</p> + +<p> +<strong>Mom</strong>'s default for <strong>LINEBREAK_CHAR</strong> is + +<pre> + .LINEBREAK_CHAR * 3 -3p +</pre> + +i.e. three asterisks, lowered 3 points from their normal vertical +position (for +<a href="docprocessing.html#PRINTSTYLE">PRINTSTYLE TYPESET</a>; +the vertical adjustment is -2 points for +</p> +<a href="docprocessing.html#PRINTSTYLE">PRINTSTYLE TYPEWRITE</a>). + +<hr width="33%" align="left"/> + +<a name="LINEBREAK_COLOR"><h4><u>Linebreak colour control macro</u></h4></a> + +<p> +<nobr>Macro: <strong>LINEBREAK_COLOR</strong> <kbd><color name></kbd></nobr> +</p> + +<p> +To change the colour of the linebreak character(s), simply invoke +<kbd>.LINBREAK_COLOR</kbd> with the name of a pre-defined (or +"initialized") colour. +</p> + +<hr/> + +<!-- ==================================================================== --> + +<a name="QUOTE_INTRO"><h2><u>Quotes (line for line)</u></h2></a> + +<ul> + <li><a href="#QUOTE">Tag: QUOTE</a></li> + <li><a href="#QUOTE_CONTROL">Quote control macros</a></li> +</ul> + +<p> +<a href="definitions.html#TERMS_QUOTE">Quotes</a> +are always set in +<a href="definitions.html#TERMS_NOFILL">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 <strong>mom</strong> originally came into being to serve the +needs of creative writers (i.e. novelists, short story writers, etc. +— not to cast aspersions on the creativity of mathematicians +and programmers), she sets quotes in italics +<a href="docprocessing.html#PRINTSTYLE">(PRINTSTYLE TYPESET)</a> +or underlined +<a href="docprocessing.html#PRINTSTYLE">(PRINTSTYLE TYPEWRITE)</a>, +indented from the left margin. Obviously, she's thinking +"quotes from poetry or song lyrics", but with the +<a href="#QUOTE_CONTROL">quote control macros</a> +you can change her defaults so <strong>QUOTE</strong> 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> + +<a name="QUOTE_SPACING"></a> + +<p> +Besides indenting quotes, <strong>mom</strong> further sets them +off from +<a href="definitions.html#TERMS_RUNNING">running text</a> +with a small amount of vertical whitespace top and bottom. In +<a href="docprocessing.html#PRINTSTYLE">PRINTSTYLE TYPEWRITE</a>, +this is always one full linespace. In +<a href="docprocessing.html#PRINTSTYLE">PRINTSTYLE TYPESET</a>, +it's 1/2 of the prevailing +<a href="definitions.html#TERMS_LEADING">leading</a> +if the quote fits fully on the page (i.e. with running text above +and below it), otherwise it's a full linespace either above or below +as is necessary to balance the page to the bottom margin. This +behaviour can be changed with the control macro +<a href="#ALWAYS_FULLSPACE_QUOTES">ALWAYS_FULLSPACE_QUOTES</a>. +</p> + +<p> +<strong>NOTE:</strong> <strong>ALWAYS_FULLSPACE_QUOTES</strong> +applies to both +<a href="#QUOTE">QUOTE</a> +and +<a href="#BLOCKQUOTE">BLOCKQUOTE</a>, +as does the control macro +<a href="#QUOTE_INDENT">QUOTE_INDENT</a>. +</p> + +<p> +<strong>Version 1.3: mom</strong>'s handling of the +vertical whitespace around quotes has changed slightly. In +versions prior to 1.3, it was not possible to alter the +<a href="definitions.html#TERMS_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> +In 1.3 and later, it is possible to change the leading of quotes +and blockquote via the <strong>QUOTE_AUTOLEAD</strong> and +<strong>BLOCKQUOTE_AUTOLEAD</strong> macros. Now, if your quote +(or blockquote) leading differs from the document leading, +<strong>mom</strong> 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 <em>all</em> 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#TERMS_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, works in a line-per-line fashion.) +</p> + +<a name="NO_SHIM"></a> + +<p> +If you don't want the behaviour described above (i.e. you don't want +<strong>mom</strong> shimming [possibly irregularly linespaced] +quotes or blockquotes), issue the macro <kbd>.NO_SHIM</kbd> prior +to invoking <kbd>.QUOTE</kbd> or <kbd>.BLOCKQUOTE</kbd>. +If you've disabled shimming of quotes and blockquotes with +<kbd>.NO_SHIM</kbd> and you want <strong>mom</strong> to return to +her default behaviour in this matter, invoke +<nobr><kbd>.NO_SHIM OFF</kbd></nobr> (or <strong>QUIT, END, X</strong>, etc). +</p> + +<p> +If you don't provide <strong>mom</strong> with a +<strong>QUOTE_AUTOLEAD</strong>, quotes are leaded at the default +for normal running text, meaning that multiple quotes on the same +page are all spaced identically. +</p> + +<!-- -QUOTE- --> + +<hr width="66%" align="left"/> + +<a name="QUOTE"></a> + +<p> +<nobr>Macro: <strong>QUOTE</strong> <kbd>toggle</kbd></nobr> +</p> + +<p> +<strong>QUOTE</strong> is a toggle macro. To begin a section +of quoted text, invoke it with no argument, then type in your +quote. When you're finished, invoke <kbd>.QUOTE</kbd> with any +argument (e.g. OFF, END, X, Q...) to turn it off. Example: + +<pre> + .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 +</pre> +</p> + +<hr width="33%" align="left"/> + +<a name="QUOTE_CONTROL"><h3><u>Quote control macros</u></h3></a> + +<ol> + <li><a href="#QUOTE_GENERAL">Family/font/size/leading/colour/indent</a></li> + <li><a href="#ALWAYS_FULLSPACE_QUOTES">Spacing above and below (typeset only)</a></li> + <li><a href="#UNDERLINE_QUOTES">Underline quotes (typewrite only)</a></li> + <li><a href="#BREAK_QUOTE">Manually break a footnoted quote that crosses pages/columns</a></li> +</ol> + +<a name="QUOTE_GENERAL"><h4><u>1. Family/font/size/colour/indent</u></h4></a> + +<p> +See +<a href="#CONTROL_MACRO_ARGS">Arguments to the control macros</a>. +</p> + +<pre> +.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) +</pre> + +<a name="QUOTE_INDENT"><h5><u>Quote indent</u></h5></a> + +<p> +Prior to version 1.4-b, <strong>mom</strong> 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 +<a href="#PARA_INDENT">PARA_INDENT</a> +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#TERMS_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> + +<p> +Please note that if your <strong>PARA_INDENT</strong> is 0 +(i.e. no indenting of the first line of paragraphs), you +<em><strong>must</strong></em> set a <strong>QUOTE_INDENT</strong> +yourself, with a unit of measure appended to the +argument. <strong>Mom</strong> has no default for +<strong>QUOTE_INDENT</strong> if paragraph first lines are not being +indented. +</p> + +<p> +The default value for <strong>QUOTE_INDENT</strong> is 3 (for +<a href="docprocessing.html#PRINTSTYLE">PRINTSTYLE TYPESET</a>) +and 2 (for PRINTSTYLE +<a href="docprocessing.html#PRINTSTYLE">PRINTSTYLE TYPEWRITE</a>). +</p> + +<p> +<strong>NOTE: QUOTE_INDENT</strong> also sets the indent for +<a href="#BLOCKQUOTE">BLOCKQUOTES</a>. +</p> + +<a name="ALWAYS_FULLSPACE_QUOTES"><h4><u>2. Spacing above and below — ALWAYS_FULLSPACE_QUOTES (typeset only)</u></h4></a> + +<p> +If you'd like <strong>mom</strong> always to put a full linespace +above and below quotes, invoke <kbd>.ALWAYS_FULLSPACE_QUOTES</kbd> +with no argument. If you wish to restore <strong>mom</strong>'s +default behaviour regarding the spacing of quotes (see +<a href="#QUOTE_SPACING">above</a>), +invoke the macro with any argument (<strong>OFF, QUIT, END, +X</strong>...) +</p> + +<p> +<strong>NOTE:</strong> This macro also sets <strong>mom</strong>'s +spacing policy for +<a href="#BLOCKQUOTE_INTRO">blockquotes</a>. +</p> + +<a name="UNDERLINE_QUOTES"><h4><u>3. Underlining — UNDERLINE_QUOTES (typewrite only)</u></h4></a> + +<p> +By default in +<a href="docprocessing.html#PRINTSTYLE">PRINTSTYLE TYPEWRITE</a>, +<strong>mom</strong> underlines quotes. If you'd rather she didn't, +invoke <kbd>.UNDERLINE_QUOTES</kbd> with any argument (<strong>OFF, +QUIT, END, X</strong>...) to disable the feature. Invoke it without +an argument to restore <strong>mom</strong>'s default underlining of +quotes. +</p> + +<p> +If you not only wish that <strong>mom</strong> not underline +quotes, but also that she set them in italic, you must follow each +instance of <strong>QUOTE</strong> with the typesetting macro +<a href="typesetting.html#FONT">FT I</a>. +Furthermore, since <strong>mom</strong> underlines all instances of +italics by default in <strong>PRINTSTYLE TYPEWRITE</strong>, you +must also make sure that <strong>ITALIC_MEANS_ITALIC</strong> is +enabled (see +<a href="docprocessing.html#TYPEWRITE_CONTROL">PRINTSTYLE TYPEWRITE control macros</a>). +</p> + +<a name="BREAK_QUOTE"><h4><u>4. Manually break a footnoted quote — BREAK_QUOTE</u></h4></a> + +<p> +<strong>NOTE:</strong> <em>As of version 1.1.9, the macro</em> +<strong>BREAK_QUOTE</strong> <em>has become obsolete (or, at +least, should have become obsolete.) It remains here for backward +compatibility with documents created prior to 1.1.9, and just in +case despite my efforts to make it obsolete you still encounter +the problem it's supposed to fix. Should you find yourself having +to use</em> <strong>BREAK_QUOTE</strong> <em>while running</em> +<strong>mom</strong> 1.1.9 <em>or higher, please notify me +immediately.</em> +</p> + +<p> +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 <kbd>.BREAK_QUOTE</kbd> 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> +<strong>BREAK_QUOTE</strong> may be used with both quotes and +blockquotes, and hence is aliased as <strong>BREAK_BLOCKQUOTE, +BREAK_CITATION</strong> and <strong>BREAK_CITE</strong>. +</p> + +<hr/> + +<!-- ==================================================================== --> + +<a name="BLOCKQUOTE_INTRO"><h2><u>Blockquotes (cited passages)</u></h2></a> + +<ul> + <li><a href="#BLOCKQUOTE">Tag: BLOCKQUOTE (aliases: CITE, CITATION)</a></li> + <li><a href="#BLOCKQUOTE_CONTROL">BLOCKQUOTE control macros</a></li> +</ul> + +<p> +<strong>BLOCKQUOTES</strong> are used to cite passages from another +author's work. So that they stand out well from +<a href="definitions.html#TERMS_RUNNING">running text</a>, +<strong>mom</strong> 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#TERMS_OUTPUTLINE">Output lines</a> +are +<a href="definitions.html#TERMS_FILLED">filled</a>, +and, by default, +<a href="definitions.html#TERMS_QUAD">quadded</a> +left. +</p> + +<p> +Besides indenting blockquotes, <strong>mom</strong> 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. Be sure to read the section <strong>Version +1.3</strong>.) +</p> + +<!-- -BLOCKQUOTE- --> + +<hr width="66%" align="left"/> + +<a name="BLOCKQUOTE"></a> + +<p> +<nobr>Macro: <strong>BLOCKQUOTE</strong> <kbd>toggle</kbd></nobr> +<br/> + +Aliases: <strong>CITE, CITATION</strong> +</p> + +<p> +<strong>BLOCKQUOTE</strong> is a toggle macro. To begin a cited +passage, invoke the tag with no argument, then type in your quote. +When you're finished, invoke <kbd>.BLOCKQUOTE</kbd> with any +argument (e.g. OFF, END, X, Q...) to turn it off. Example: + +<pre> + .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 + \(emGeorge W. Bush + .BLOCKQUOTE END +</pre> +</p> + +<p> +If the cited passage runs to more than one paragraph, you MUST +introduce each paragraph — <em>including the first!</em> — +with +<a href="#PP">PP</a>. +</p> + +<p> +<strong>NOTE:</strong> The aliases <strong>CITE</strong> +and <strong>CITATION</strong> may be used in place of the +<strong>BLOCKQUOTE</strong> tag, as well as in any of the control +macros that begin with <strong>BLOCKQUOTE_</strong> or end with +<strong>_BLOCKQUOTE</strong>. +</p> + +<hr width="33%" align="left"/> + +<a name="BLOCKQUOTE_CONTROL"><h3><u>Blockquote control macros</u></h3></a> + +<ol> + <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> + +<a name="BLOCKQUOTE_GENERAL"><h4><u>1. Family/font/size/colour/quad/indent</u></h4></a> + +<p> +See +<a href="#CONTROL_MACRO_ARGS">Arguments to the control macros</a>. +</p> + +<pre> +.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) +</pre> + +<a name="BLOCKQUOTE_INDENT"><h5><u>Blockquote indent</u></h5></a> + +<p> +Prior to version 1.4-b, <strong>mom</strong> allowed only the +passing of an integer to the macro, <kbd>.BLOCKQUOTE_INDENT</kbd>. +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 blockquotes (and quotes). +</p> + +<p> +As of version 1.4-b, you can now append a +<a href="definitions.html#TERMS_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 TYPESET</a>) +and 2 (for PRINTSTYLE +<a href="docprocessing.html#PRINTSTYLE">PRINTSTYLE TYPEWRITE</a>). +</p> + +<p> +Please note that if your <strong>PARA_INDENT</strong> +is 0 (i.e. no indenting of the first line of +paragraphs), you <em><strong>must</strong></em> set a +<strong>BLOCKQUOTE_INDENT</strong> yourself, with a unit of measure +appended to the argument. <strong>Mom</strong> has no default for +<strong>BLOCKQUOTE_INDENT</strong> if paragraph first lines are not +being indented. +</p> + +<p> +<strong>NOTE: BLOCKQUOTE_INDENT</strong> also sets the indent for +<a href="#QUOTE">QUOTES</a>. +</p> + +<a name="BQ_ALWAYS_FULLSPACE_QUOTES"><h4><u>2. Spacing above and below — ALWAYS_FULLSPACE_QUOTES (typeset only)</u></h4></a> + +<p> +If you'd like <strong>mom</strong> always to put a +full linespace above and below blockquotes, invoke +<kbd>.ALWAYS_FULLSPACE_QUOTES</kbd> with no argument. If you wish +to restore <strong>mom</strong>'s default behaviour regarding the +spacing of blockquotes (see +<a href="#QUOTE_SPACING">above</a>), +invoke the macro with any argument (<strong>OFF, QUIT, END, +X</strong>...). +</p> + +<p> +<strong>NOTE:</strong> This macro also sets <strong>mom</strong>'s +spacing policy for +<a href="#QUOTE_INTRO">quotes</a>. +</p> + +<hr/> + +<!-- ==================================================================== --> + +<a name="CODE"><h2><u>Inserting code snippets into documents</u></h2></a> + +<p> +<nobr>Macro: <strong>CODE</strong> <kbd>[BR | BREAK | SPREAD] toggle</kbd></nobr> +<br/> + +Inline escape: <strong><kbd>\*[CODE]</kbd></strong> +</p> + +<p> +<strong>CODE</strong> is a convenience macro that facilitates +entering code snippets into documents. Its use is not restricted to +documents created using <strong>mom</strong>'s document processing +macros; it can be used for "manually" typeset documents as +well. +</p> + +<p> +When you invoke <kbd>.CODE</kbd> without an argument, or use the +<a href="definitions.html#TERMS_INLINES">inline escape</a>, +<kbd>\*[CODE]</kbd>, +<strong>mom</strong> changes the font to Courier Roman (a +<a href="definitions.html#TERMS_FIXEDWIDTHFONT">fixed-width font</a>) +and turns +<a href="goodies.html#SMARTQUOTES">SMARTQUOTES</a> +off. Additionally, if you invoke <kbd>.CODE</kbd> inside +<a href="docelement.html#QUOTE">QUOTE</a> +while using +<a href="docprocessing.html#PRINTSTYLE">PRINTSTYLE TYPEWRITE</a> +with the default underlining of quotes turned on, it disables +the underlining for the duration of <strong>CODE</strong>. +</p> + +<p> +Passing any argument other than <kbd>BR</kbd>, <kbd>BREAK</kbd> or +<kbd>SPREAD</kbd> to <kbd>.CODE</kbd> (e.g. <strong>OFF, QUIT, END, +X,</strong> etc.) turns <strong>CODE</strong> off and returns the +family, font, smartquotes and (if applicable) underlining of quotes +to their former state. If you've used the inline escape to +initiate a section of code, <kbd>\*[CODE OFF]</kbd> equally returns +things to their former state. +</p> + +<p> +Please note that <kbd>.CODE</kbd> does <em>not</em> cause a line +break when you're in a +<a href="definitions.html#TERMS_FILLED">fill mode</a> +(i.e. +<a href="typesetting.html#JUSTIFY">JUSTIFY</a> +or +<nobr><a href="typesetting.html#QUAD">QUAD</a> LEFT, CENTER, or RIGHT)</nobr>. +If you want <strong>CODE</strong> to deposit a break, +invoke <kbd>.CODE</kbd> with the argument <kbd>BR</kbd> (or +<kbd>BREAK</kbd>). If, in addition to having <strong>mom</strong> +break the line before <kbd>.CODE</kbd>, you want her to +<a href="definitions.html#TERMS_FORCE">force justify</a> +the line as well, invoke <kbd>.CODE</kbd> with the argument, +<kbd>SPREAD</kbd>. +</p> + +<p> +Please also note that <kbd>BR</kbd>, <kbd>BREAK</kbd> and +<kbd>SPREAD</kbd> must NOT be used with the inline escape, +<kbd>\*[CODE]</kbd>; the assumption behind <kbd>\*[CODE]</kbd> is +that you're inserting a bit of code into a line, not creating a +distinct "code block". +</p> + +<h3><u>Changing the family mom uses for CODE</u></h3> + +<p> +If you'd prefer to have <strong>CODE</strong> automatically +load a fixed-width family other than Courier, invoke the macro, +<kbd>.CODE_FAMILY</kbd> with the name of the fixed-width family you +want. For example, assuming you have a hypothetical fixed-width +family called "Mono" whose <strong>groff</strong> name is +simply "M", + +<pre> + .CODE_FAMILY M +</pre> + +is how you'd tell <strong>mom</strong> to use Mono for +<strong>CODE</strong>, rather than her default, Courier. +(See +<a href="appendices.html#FONTS">Adding PostScript fonts to groff</a> +for information on how you might set up the hypothetical +fixed-width font called "Mono".) +</p> + +<p> +<strong>NOTE</strong>: If your code snippet includes the backslash +character, which is <strong>groff</strong>'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>. +<strong>Mom</strong> has no way of knowing what special characters +you're going to use in code snippets, therefore she cannot +automatically replace the escape character with something else. +</p> + +<hr/> + +<!-- ==================================================================== --> + +<a name="LIST_INTRO"><h2><u>Nested lists</u></h2></a> + +<ul> + <li><a href="#LIST">Tag: LIST</a></li> + <li><a href="#ITEM">Tag: ITEM</a></li> + <li><a href="#LIST_CONTROL">LIST control macros</a></li> +</ul> + +<p> +Lists are points or items of interest or importance that are +separated from +<a href="definitions.html#TERMS_RUNNING">running text</a> +by enumerators. Some typical enumerators are +<a href="definitions.html#TERMS_EM">en-dashes</a>, +<a href="definitions.html#TERMS_BULLET">bullets</a>, +digits and letters. +</p> + +<p> +Setting lists with <strong>mom</strong> is easy. First, you +initialize a list with the <strong>LIST</strong> 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 <nobr><kbd>.LIST OFF</kbd></nobr> (or +<strong>QUIT</strong>, <strong>END</strong>, <strong>BACK</strong>, +etc.) +</p> + +<p> +By default <strong>mom</strong> starts each list with the enumerator +flush with the left margin of running text that comes before it, +like this: + +<pre> + My daily schedule needs organizing. I can't + seem to get everything done I want. + o an hour's worth of exercise + o time to prepare at least one healthy + meal per day + o reading time + o work on mom + o writing + - changes from publisher + - current novel + o a couple of hours at the piano +</pre> +</p> + +<p> +In other words, <strong>mom</strong> 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, <strong>mom</strong> +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 +<nobr><strong>LIST OFF</strong></nobr> (you may prefer to use +<nobr><strong>LIST BACK</strong>)</nobr> takes you back to the +previous depth (or level) of list, with that list's enumerator and +indent intact. The final <nobr><strong>LIST OFF</strong></nobr> +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 +document processing macros or just the typesetting macros. +</p> + +<!-- -LIST- --> + +<hr width="66%" align="left"/> + +<a name="LIST"></a> + +<p> +Macro: <strong>LIST</strong> +<br/> + +<em>Macro arguments:</em> +<br/> + +<kbd><nobr>[ BULLET | DASH | DIGIT | ALPHA | alpha | ROMAN<n> | roman<n> | USER <string>]</nobr> +<br/> + +<nobr>[ <separator> | <user-defined enumerator> ] [ <prefix> ] [ <off> ]</nobr></kbd> +</p> + +<p> +Invoked by itself (i.e. with no argument), <kbd>.LIST</kbd> +initializes a list (with bullets as the default enumerator). +Afterwards, each block of input text preceded by +<a href="#ITEM">.ITEM</a>, +on a line by itself, is treated as a list item. +</p> + +<p> +<strong>NOTE:</strong> 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 <strong>mom</strong>'s default enumerator, +which is a bullet. Within nested lists, <strong>mom</strong> +stores the enumerator, separator and indent for any list you return +<em>backwards</em> to (i.e. with <nobr><strong>LIST OFF</strong>),</nobr> +but does not store any information for lists you move +<em>forward</em> to. +</p> + +<h3><u>The first argument — enumerator style</u></h3> + +<p> +The optional arguments <kbd>BULLET</kbd>, <kbd>DASH</kbd>, +<kbd>DIGIT</kbd> (for Arabic numerals), <kbd>ALPHA</kbd> (for +uppercase letters), <kbd>alpha</kbd> (for lowercase letters), +<kbd>ROMAN<n></kbd> (for uppercase roman numerals), +<kbd>roman<n></kbd> (for lowercase roman numerals) tell +<kbd>mom</kbd> what kind of enumerator to use for a given list. +</p> + +<p> +The arguments, <kbd>ROMAN<n></kbd> and +<kbd>roman<n></kbd>, are special. You must append to +them a digit (arabic, e.g. "1" or "9" or "17") saying how many +items a particular roman-numeralled <strong>LIST</strong> is going +to have. <strong>Mom</strong> requires this information in order to +align roman numerals sensibly, and will abort — with a message +— if you don't provide it. +</p> + +<p> +A roman-numeralled list containing, say, five items, would be set +up like this: + +<pre> + .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 +</pre> +</p> + +<p> +The argument, <kbd>USER</kbd>, lets you make up your own enumerator, +and must be followed by a second argument: what you'd like the +enumerator to look like. For example, if you want a list enumerated +with <kbd>=></kbd>, + +<pre> + .LIST USER => + .ITEM + A list item +</pre> + +will produce + +<pre> + => A list item +</pre> +</p> + +<p> +<strong>Please note:</strong> if the argument to <kbd>USER</kbd> +contains spaces, you must enclose the argument in double quotes. +</p> + +<h3><u>The second argument — separator style</u></h3> + +<p> +If you choose <kbd>DIGIT</kbd>, <kbd>ALPHA</kbd>, <kbd>alpha</kbd>, +<kbd>ROMAN<n></kbd>, or <kbd>roman<n></kbd>, you may +enter the optional argument, <kbd>separator</kbd>, to say what kind +of separator you want after the enumerator. The separator can be +anything you like. The default for <kbd>DIGIT</kbd> is a period +(dot), like this: + +<pre> + 1. A list item +</pre> +</p> + +<p> +The default separator for <kbd>ALPHA</kbd>, <kbd>alpha</kbd>, +<kbd>ROMAN<n></kbd> and <kbd>roman<n></kbd> is a right +parenthesis, like this: + +<pre> + a) An alpha-ed list item + b) A second alpha-ed list item + + or + + i) A roman-ed list item + ii) A second roman-ed item +</pre> +</p> + +<p> +If you'd prefer, say, digits with right-parenthesis separators +instead of the default period, you'd do + +<pre> + .LIST DIGIT ) + .ITEM + A numbered list item +</pre> + +which would produce + +<pre> + 1) A numbered list item +</pre> +</p> + +<p> +<strong>Please note:</strong> <kbd>BULLET</kbd>, <kbd>DASH</kbd> and +<kbd>USER</kbd> do not take a separator. +</p> + +<h3><u>The third argument — prefix style</u></h3> + +<p> +Additionally, you may give a prefix (i.e. a character +that comes <em>before</em> the enumerator) when your +enumerator style for a particular list is <kbd>DIGIT</kbd>, +<kbd>ALPHA</kbd>, <kbd>alpha</kbd>, <kbd>ROMAN<n></kbd> +or <kbd>roman<n></kbd>. In the arguments to +<strong>LIST</strong>, the prefix comes <em>after</em> the +separator, which may seem counter-intuitive, so please be careful. +</p> + +<p> +A prefix can be anything you like. Most likely, you'll want some +kind of open-bracket, such as a left parenthesis. If, for example, +you want a <kbd>DIGIT</kbd> list with the numbers enclosed in +parentheses, you'd enter + +<pre> + .LIST DIGIT ) ( + .ITEM + The first item on the list. + .ITEM + The second item on the list. +</pre> + +which would produce + +<pre> + (1) The first item on the list. + (2) The second item on the list. +</pre> +</p> + +<p> +<strong>Please note:</strong> <kbd>BULLET</kbd>, <kbd>DASH</kbd> and +<kbd>USER</kbd> do not take a prefix. +</p> + +<a name="LIST_EXIT"></a> + +<h3><u>Exiting lists — .LIST OFF/BACK or .QUIT_LISTS</u></h3> + +<p> +Any single argument to <kbd>LIST</kbd> other than +<kbd>BULLET</kbd>, <kbd>DASH</kbd>, <kbd>DIGIT</kbd>, +<kbd>ALPHA</kbd>, <kbd>alpha</kbd>, <kbd>ROMAN<n></kbd>, +<kbd>roman<n></kbd> or <kbd>USER</kbd> (e.g. <nobr><kbd>LIST +OFF</kbd></nobr> or <nobr><kbd>LIST BACK</kbd>)</nobr> takes you out +of the current list. +</p> + +<p> +If you are at the first list-level (or "list-depth"), +<strong>mom</strong> 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, <strong>mom</strong> moves you +<em>back one list-level</em> (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 be be matched by a +corresponding <nobr><kbd>.LIST OFF</kbd></nobr> in order to fully +exit lists. For example, + +<pre> + 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. +</pre> + +is created like this: + +<pre> + 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. +</pre> +</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 <nobr><kbd>.LIST OFF</kbd></nobr> lines +could be replaced with a single <kbd>.QUIT_LISTS</kbd>. +</p> + +<hr width="33%" align="left"/> + +<a name="ITEM"></a> + +<p> +Macro: <strong>ITEM</strong> +</p> + +<p> +After you've initialized a list with +<a href="#LIST">LIST</a>, +precede each item you want in the list with <kbd>.ITEM</kbd>. +<strong>Mom</strong> takes care of everything else with respect to +setting the item appropriate to the list you're in. +</p> + +<p> +In document processing, it is valid to have list items that contain +multiple paragraphs. Simply issue a +<a href="#PP">PP</a> +request for each paragraph <em>following</em> the first item. +I.e., don't do this: + +<pre> + .ITEM + .PP + Some text... + .PP + A second paragraph of text +</pre> + +but rather + +<pre> + .ITEM + Some text... + .PP + A second paragraph of text +</pre> +</p> + +<hr width="33%" align="left"/> + +<a name="LIST_CONTROL"><h3><u>List control macros</u></h3></a> + +<ol> + <li><a href="#SHIFT_LIST">Indenting lists (SHIFT_LIST)</a></li> + <li><a href="#RESET_LIST">Resetting an initialized list's enumerator (RESET_LIST)</a></li> + <li><a href="#PAD_LIST_DIGITS">Padding digit enumerators (PAD_LIST_DIGITS)</a></li> +</ol> + +<a name="SHIFT_LIST"><h4><u>1. Indenting lists — SHIFT_LIST</u></h4></a> + +<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 +<strong>SHIFT_LIST</strong> immediately after +<a href="#LIST">LIST</a>. +<strong>SHIFT_LIST</strong> takes just one argument: the amount by +which you want the list shifted to the right. The argument requires +a +<a href="definitions.html#TERMS_UNITOFMEASURE">unit of measure</a>, +</p> + +<p> +<strong>SHIFT_LIST</strong> applies <em>only</em> to the list you +just initialized with <strong>LIST</strong>. It does not carry +over from one invocation of <strong>LIST</strong> to the next. +However, the indent remains in effect when you <em>return</em> 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#TERMS_PICASPOINTS">points</a>, + +<pre> + 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. +</pre> + +produces (approximately) + +<pre> + 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. +</pre> +</p> + +<a name="RESET_LIST"><h4><u>2. Resetting an initialized list's enumerator — RESET_LIST</u></h4></a> + +<p> +In nested lists, if your choice of list enumerator for a given +level of list is <strong>DIGIT</strong>, <strong>ALPHA</strong>, +<strong>alpha</strong>, <strong>ROMAN</strong> or +<strong>roman</strong>, you may sometimes want to reset the list's +enumerator when you return to that list. Consider the following: + +<pre> + Things to do religiously each and every day: + 1. Take care of the dog + a) walk every day + b) brush once a week + - trim around the eyes every fourth brushing + - don't forget to check nails + 2. Feed the cat + a) soft food on Mon., Wed. and Fri. + b) dry food on Tues., Thurs. and Sat. + c) canned tuna on Sunday +</pre> +</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 +"2. Feed the cat" would be c), d) and e). The +solution, in such a case, is simply to reset the enumerator +— before <kbd>.ITEM</kbd> — with the macro, +<kbd>.RESET_LIST</kbd>. +</p> + +<p> +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#TERMS_NUMERICARGUMENT">numeric argument</a> +representing the starting enumerator for the reset (if different +from "1"), although I can't at present think of a use for this +feature. +</p> + +<a name="PAD_LIST_DIGITS"><h4><u>3. Padding digit enumerators (PAD_LIST_DIGITS)</u></h4></a> + +<h5><u>Arabic digits</u></h5> + +<p> +When your choice of enumerators is <strong>DIGIT</strong> AND the +number of items in the list exceeds nine (9), you have to make a +design decision: should <strong>mom</strong> 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 + +<pre> + 8. List item + 9. List item + 10. List item +</pre> +</p> + +<p> +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 + +<pre> + 8. List item + 9. List item + 10. List item +</pre> +</p> + +<p> +Of course, if the number of items in the list is less than ten +(10), there's no need for <strong>PAD_LIST_DIGITS</strong>. +</p> + +<h5><u>Roman numerals</u></h5> + +<p> +By default, <strong>mom</strong> sets roman numerals in lists +flush left. The <kbd><n></kbd> argument appended to +<kbd>ROMAN<n></kbd> or <kbd>roman<n></kbd> +allows her to calculate how much space to put after each numeral in +order to ensure that the text of items lines up properly. +</p> + +<p> +If you'd like the roman numerals to line up flush right (i.e. +be padded "left"), simply invoke +<nobr><kbd>.PAD_LIST_DIGITS LEFT</kbd></nobr> +after +<nobr><kbd>.LIST ROMAN<n></kbd></nobr> +or +<nobr><kbd>.LIST roman<n></kbd></nobr> +and before <kbd>.ITEM</kbd>. +</p> + +<hr/> + +<!-- -LINE NUMBERING- --> + +<a name="NUMBER_LINES_INTRO"><h2><u>Line numbering</u></h2></a> + +<ul> + <li><a href="#NUMBER_LINES">Macro: NUMBER_LINES</a></li> + <ul> + <li><a href="#LN_CONTROL">Line numbering control (suspend/resume)</a></li> + </ul> + <li><a href="#NUMBER_LINES_CONTROL">Control macros</a> + <ul> + <li><a href="#NUMBER_LINES_CONTROL_QUOTE">Line numbering control macros for quotes and blockquotes</a></li> + </ul></li> +</ul> + +<p> +When you turn line-numbering on, <strong>mom</strong>, by default + +<a name="NUMBER_LINES_DEFAULTS"></a> +<ul> + <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#TERMS_DOCHEADER">docheaders</a> + off (with + <a href="docprocessing.html#DOCHEADER">DOCHEADER</a> <strong>OFF</strong>) + and create your own docheader, <strong>mom</strong> + <em>will</em> line-number your custom docheader + </li> + <li>doesn't touch your line length; line numbers are hung + outside your current left margin (as set with + <a href="typesetting.html#L_MARGIN">L_MARGIN</a>, + <a href="typesetting.html#PAGE">PAGE</a> + or + <a href="docprocessing.html#DOC_LEFT_MARGIN">DOC_LEFT_MARGIN</a>), + regardless of any indents that may be active + </li> + <li>separates line numbers from running text by two + <a href="definitions.html#TERMS_FIGURESPACE">figure spaces</a>. + </li> +</ul> +</p> + +<p> +Line numbering may be enabled and disabled for +<a href="#QUOTE">QUOTE</a> +and/or +<a href="#BLOCKQUOTE">BLOCKQUOTE</a> +in one of three styles. See +<a href="#NUMBER_LINES_CONTROL_QUOTE">Line numbering control macros for quotes and blockquotes</a>. +</p> + +<p> +The first time you invoke +<a href="#NUMBER_LINES"><kbd>.NUMBER_LINES</kbd></a> +you must, at a minimum, tell it what line number you want the +<em>next</em> +<a href="definitions.html#TERMS_OUTPUTLINE">output line</a> +to have. Optional arguments 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#TERMS_RUNNING">running text</a>. +</p> + +<p> +Subsequently, you can turn line-numbering off, either permanently, +or resume it later at a place of your choosing. When you +resume line-numbering, the line numbers pick up where you left off. +</p> + +<!-- -NUMBER_LINES- --> + +<hr width="66%" align="left"/> + +<a name="NUMBER_LINES"></a> + +<p> +<nobr>Macro: <strong>NUMBER_LINES</strong> <kbd><start number> [ <which lines to number> [ <gutter> ] ]</kbd></nobr> +<br/> + +<nobr>Macro: <strong>NUMBER_LINES</strong> <kbd><anything> | RESUME</kbd></nobr> +</p> + +<p> +<strong>NUMBER_LINES</strong> does what it says: prints line +numbers, to the left of +<a href="definitions.html#TERMS_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> +Every time you invoke <kbd>.NUMBER_LINES</kbd>, unless you are +using the argument <strong>OFF</strong> (or <strong>QUIT</strong>, +<strong>END</strong>, <strong>X</strong>, etc.) or <kbd>RESUME</kbd> +you must, at a minimum, pass it one argument, namely the number +(digit) you want the <em>next</em> +<a href="definitions.html#TERMS_OUTPUTLINE">output line</a> +to have. For example, + +<pre> + .NUMBER_LINES 3 +</pre> + +will prepend the number, 3, to the next output line. +</p> + +<p> +Normally, of course, you will number lines of text starting at 1. +All you have to do in that case is ensure that + +<pre> + .NUMBER_LINES 1 +</pre> + +precedes your first line of input text, which will also be the +first line of output text. +</p> + +<p> +You can alter <strong>mom</strong>'s default line numbering +behaviour (see +<a href="#NUMBER_LINES_DEFAULTS">above</a>) +with the optional arguments <kbd><which lines to number></kbd> +and <kbd><gutter></kbd>. +</p> + +<p> +<kbd><which lines to number></kbd> instructs +<kbd>NUMBER_LINES</kbd> to number only certain lines, e.g. every two +lines or every five lines. If you want, say, only every five lines +to have a prepended number, you'd do + +<pre> + .NUMBER_LINES 1 5 +</pre> + +<strong>GOTCHA!</strong> The argument to <kbd><which lines to +number></kbd> only numbers those lines that are multiples of +the argument. Hence, in the above example, line number "1" will +<em>not</em> be numbered, since "1" is not a multiple of "5". +</p> + +<p> +If you wanted line number "1" to be numbered, you'd have to invoke +<kbd>.NUMBER_LINES 1 1</kbd> before the first output line, then +study your <em>output</em> copy and determine where best to insert +the following in your <em>input</em> copy: + +<pre> + .NUMBER_LINES \n(ln 5 +</pre> + +(The escape, <kbd>\n(ln</kbd>, ensures that +<strong>NUMBER_LINES</strong> automatically supplies the correct +value for the first argument, <kbd><start number></kbd>.) +</p> + +<p> +Following this recipe, line number 1 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. +</p> + +<p> +The optional argument, <kbd><gutter></kbd>, tells +<strong>mom</strong> how much space to put between the line numbers +and the running text. +</p> + +<p> +<strong>Note</strong>: when giving a value for +<kbd><gutter></kbd>, you cannot skip the <kbd><which lines +to number></kbd> argument. Either fill in the desired value, or +use two double-quotes ( <kbd>""</kbd> ) to have <strong>mom</strong> +use the value formerly in effect. +</p> + +<p> +<kbd><gutter></kbd> does not require (or even accept) a +<a href="definitions.html#TERMS_UNITOFMEASURE">unit of measure</a>. +The argument you pass to it is the number of +<a href="definitions.html#TERMS_FIGURESPACE">figure spaces</a> +you want between line numbers and running text. +<strong>Mom</strong>'s default gutter is two figure spaces. If +you'd like a wider gutter, say, four figures spaces, you'd do + +<pre> + .NUMBER_LINES 1 1 4 + | + +-- Notice you *must* supply a value + for the 2nd argument in order to supply + a value for the 3rd. +</pre> +</p> + +<p> +After you've set up line-numbering, <strong>NUMBER_LINES</strong> +can be used to control line numbering. +</p> + +<hr width="33%" align="left"/> + +<a name="LN_CONTROL"></a> + +<h3><u>Line-numbering control</u></h3> + +<p> +<nobr><strong>NUMBER_LINES OFF</strong></nobr> (or <strong>END, +QUIT, X,</strong> etc.) turns line-numbering off. +</p> + +<p> +Sometimes, you merely want to suspend line-numbering. In that +case, turn line numbering off with +<nobr><kbd>.NUMBER_LINES OFF</kbd>.</nobr> Later, when you want +it to resume, enter + +<pre> + .NUMBER_LINES RESUME +</pre> + +Line numbering will resume exactly where it left off. If this is +not what you want — say you want to reset the line number to +"1" — simply invoke <kbd>.NUMBER_LINES</kbd> with whatever +arguments are needed for the desired result. +</p> + +<h4><u>Extra Notes:</u></h4> + +<ol> + <li>In document processing, you may invoke <kbd>.NUMBER_LINES</kbd> + either before or after <kbd>.START</kbd>. + <strong>Mom</strong> doesn't care. + </li> + <li>If you're collating documents with + <a href="rectoverso.html#COLLATE">COLLATE</a>, + you should re-invoke, at a minimum, + <nobr><kbd>.NUMBER_LINES 1</kbd></nobr> for each collated + document, in order to ensure that each begins with the + number "1" prepended to the first line (unless, of course, + that is not what you want). + </li> + <li>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 + <strong>NUMBER_LINES</strong> requires this number + as its first argument, in such instances, pass + <strong>NUMBER_LINES</strong> as its first argument the + escape <kbd>\n(ln</kbd>. + <br/><br/> + + 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/><br/> + + <kbd> .NUMBER_LINES \n(ln 5 4</kbd> + <br/><br/> + would do the trick. + </li> + <li>If you're using margin notes in a document, be sure to set + the gutter for margin notes wide enough to allow room for + the line numbers. + </li> + <li><strong>Mom</strong> (groff, actually), only numbers lines + <em>to the left of text</em>. 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#TERMS_GUTTER">gutter(s)</a> + between columns is wide enough to leave room for the + numbers. + </li> +</ol> + +<hr width="33%" align="left"/> + +<a name="NUMBER_LINES_CONTROL"><h3><u>Line numbering control macros</u></h3></a> + +<p> +See +<a href="#CONTROL_MACRO_ARGS">Arguments to the control macros</a>. +</p> + +<pre> +.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 +</pre> + +<a name="NUMBER_LINES_CONTROL_QUOTE"><h3><u>Line numbering control macros for QUOTE and BLOCKQUOTE</u></h3></a> + +<ol> + <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_QUOTES">Setting up line numbering in quotes and blockquotes on a case by case basis</a></li> +</ol> + +<a name="NUMBER_QUOTE_LINES"><h4><u>1. NUMBER_QUOTE_LINES</u></h4></a> + +<p> +If you'd like <strong>mom</strong> 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 <kbd>.NUMBER_QUOTE_LINES</kbd> by itself. +</p> + +<p> +There is a catch with numbering quotes, though. Owing to groff's +restriction of accepting only the figure space as the line number +gutter's unit of measure, it is not possible for line numbers +in quotes to hang outside a document's overall left margin and +be reliably flush with the line numbers of paragraph text. +Conseqently, line numbers in quotes hang to the left of the quote, +separated from the quote by the <kbd><gutter></kbd> argument. +</p> + +<p> +If you'd like to change the gutter for quotes line-numbered in +this way, invoke <kbd>.NUMBER_QUOTE_LINES</kbd> with a digit +representing the number of +<a href="definitions.html#TERMS_FIGURESPACE">figure spaces</a> +you'd like between the line numbers and the quoted text, like this: + +<pre> + .NUMBER_QUOTE_LINES 1 +</pre> +</p> + +<p> +With the above, line numbers in quotes (and only quotes) will have +a gutter of 1 figure space. +</p> + +<p> +If you are using "line numbering style" for footnotes +<nobr>(<a href="#FOOTNOTE_MARKER_STYLE">.FOOTNOTE_MARKER_STYLE</a> <strong>LINE</strong>)</nobr>, +you may not wish to have quotes <em>visibly</em> line-numbered, but +still want to embed footnotes inside quotes. In order to do that, +<strong>mom</strong> allows you to say <kbd>.NUMBER_QUOTE_LINES +SILENT</kbd>. +</p> + +<p> +When you invoke <nobr><kbd>.NUMBER_QUOTE_LINES SILENT</kbd></nobr>, +<strong>mom</strong> continues to increment line numbers while +quotes are being output, but they won't appear in the output copy. +(Compare this with <strong>mom</strong>'s default behaviour of +<em>suspending</em> 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 <strong>NUMBER_QUOTE_LINES</strong> on, you +may disable it with +<nobr><kbd>.NUMBER_QUOTE_LINES OFF</kbd></nobr> +(or <strong>QUIT</strong>, <strong>END</strong>, <strong>X</strong>, +etc). +</p> + +<a name="NUMBER_BLOCKQUOTE_LINES"><h4><u>2. NUMBER_BLOCKQUOTE_LINES</u></h4></a> + +<p> +If you'd like <strong>mom</strong> 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 <kbd>.NUMBER_BLOCKQUOTE_LINES</kbd> by itself. +</p> + +<p> +There is a catch with numbering blockquotes, though. Owing to +groff's restriction of accepting only the figure space as the +line number gutter's unit of measure, it is not possible for line +numbers in blockquotes to hang outside a document's overall left +margin and be reliably flush with the line numbers of paragraph +text. Conseqently, line numbers in blockquotes hang to the +left of the blockquote, separated from the blockquote by the +<kbd><gutter></kbd> argument. +</p> + +<p> +If you'd like to change the gutter for blockquotes line-numbered in +this way, invoke <kbd>.NUMBER_BLOCKQUOTE_LINES</kbd> with a digit +representing the number of +<a href="definitions.html#TERMS_FIGURESPACE">figure spaces</a> +you'd like between the line numbers and the blockquoted text, like +this: + +<pre> + .NUMBER_BLOCKQUOTE_LINES 1 +</pre> + +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 +<nobr>(<a href="#FOOTNOTE_MARKER_STYLE">FOOTNOTE_MARKER_STYLE</a> <strong>LINE</strong>),</nobr> +you may not wish to have blockquotes <em>visibly</em> line-numbered, +but still want to embed footnotes inside blockquotes. In +order to do that, <strong>mom</strong> allows you to say +<kbd>.NUMBER_BLOCKQUOTE_LINES SILENT</kbd>. +</p> + +<p> +When you invoke +<nobr><kbd>.NUMBER_BLOCKQUOTE_LINES SILENT</kbd>,</nobr> +<strong>mom</strong> continues to increment line numbers while +blockquotes are being output, but they won't appear in the output +copy. (Compare this with <strong>mom</strong>'s default behaviour +of <em>suspending</em> 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 <strong>NUMBER_BLOCKQUOTE_LINES</strong> on, +you may disable it with <nobr><kbd>.NUMBER_BLOCKQUOTE_LINES +OFF</kbd></nobr> (or <strong>QUIT</strong>, <strong>END</strong>, +<strong>X</strong>, etc). +</p> + +<a name="NUMBER_LINES_QUOTES"><h4><u>3. Setting up line numbering in quotes and blockquotes on a case by case basis</u></h4></a> + +<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 <kbd>.NUMBER_LINES</kbd>, with the +arguments you need, immediately after entering <kbd>.QUOTE</kbd> +or <kbd>.BLOCKQUOTE</kbd>. (<strong>NUMBER_QUOTE_LINES</strong> +and/or <strong>NUMBER_BLOCKQUOTE_LINES</strong> should be turned +off if you're doing this.) The quote or blockquote will then be +line-numbered according to your specifications: the starting line +number of the quote or blockquote will be the one you give as a +first argument to <strong>NUMBER_LINES</strong>; which lines to +number will be the value you pass to <nobr><kbd><which lines to +number></kbd></nobr> (defaults to "1"); line numbers will hang +to the left of the quote or blockquote, separated from the quote or +blockquote by <kbd><gutter></kbd> (defaults to "2"). +</p> + +<p> +As soon as <strong>QUOTE</strong> or <strong>BLOCKQUOTE</strong> +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 +<strong>QUOTE</strong> or <strong>BLOCKQUOTE</strong> when +line-numbering either of them on a case by case basis. +</p> + +<hr/> + +<!-- ==================================================================== --> + +<a name="FOOTNOTE_INTRO"><h2><u>Footnotes</u></h2></a> + +<ul> + <li><a href="#FOOTNOTE_BEHAVIOUR">Footnote behaviour</a></li> + <ul> + <li><a href="#FN_AND_PUNCT">Footnote markers and punctuation in the running text</a></li> + </ul> + <li><a href="#FOOTNOTE">Tag: FOOTNOTE</a></li> + <li><a href="#FOOTNOTE_CONTROL">FOOTNOTE control macros</a></li> +</ul> + +<p> +For something so complex behind the scenes, footnotes are easy to use. +You just type, for example + +<a name="FOOTNOTE_EXAMPLE"></a> + +<pre> + ...the doctrines of Identity as urged by Schelling\c + .FOOTNOTE + <footnote about who the hell is Schelling> + .FOOTNOTE OFF + were generally the points of discussion presenting the most + of beauty to the imaginative Morella. +</pre> + +and be done with it. +</p> + +<p> +(Note the obligatory use of the <kbd>\c</kbd> +<a href="definitions.html#TERMS_INLINES">inline escape</a>. +It is required when your +<a href="#FOOTNOTE_MARKER_STYLE">FOOTNOTE_MARKER_STYLE</a> +is either <strong>STAR</strong> [star/dagger footnotes] or +<strong>NUMBER</strong> [superscript numbers]; it is NOT to be used +when the <strong>FOOTNOTE_MARKER_STYLE</strong> is +<strong>LINE</strong>, or when footnote markers have been disabled +with +<a href="#FOOTNOTE_MARKERS">.FOOTNOTE_MARKERS</a> +<strong>OFF</strong>.) +</p> + +<p> +<strong>***Version 1.3-d change***</strong> +</p> + +<p> +As of version 1.3-d, the manner of entering the line <em>after</em> +<nobr><kbd>.FOOTNOTE OFF</kbd></nobr> has changed to accommodate +users' differing wishes with respect to the order of punctuation and +footnote markers. Please see +<a href="#FN_AND_PUNCT">Footnote markers and punctuation in the running text</a> +for more information. +</p> + +<p> +<strong>***End of version 1.3-d change***</strong> +</p> + +<p> +After you invoke <kbd>.FOOTNOTE</kbd>, <strong>mom</strong> +takes care of everything: putting footnote markers in the body of +the document, keeping track of how many footnotes are on the page, +identifying the footnotes themselves appropriately, balancing them +properly with the bottom margin, deferring footnotes that don't fit +on the page... Even if you're using +<a href="docprocessing.html#COLUMNS">COLUMNS</a>, +<strong>mom</strong> knows what to do, and Does The Right Thing. +</p> + +<p> +Footnotes can be sly little beasts, though. If you're writing a +document that's footnote-heavy, you might want to read the following. +</p> + +<a name="FOOTNOTE_BEHAVIOUR"><h3><u>Footnote behaviour</u></h3></a> + +<p> +By default, <strong>mom</strong> 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 <strong>mom</strong> 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. <strong>Mom</strong> tries for a nice balance +between too little whitespace and too much, but when push comes to +shove, she'll usually opt for ample over cramped. The last lines of +footnotes are always flush with the document's bottom margin. +</p> + +<a name="FOOTNOTE_RULES"></a> + +<p> +If <strong>mom</strong> sees that a portion of a footnote cannot +be fit on its page, she carries that portion over to the next +page. If an entire footnote can't be fit on its page (i.e. +<strong>FOOTNOTE</strong> 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>, +<strong>mom</strong> will usually opt for deferring the footnote +over to the next page if it allows her to complete the cited text +on one page. +</p> + +<p> +In the unfortunate happenstance that a deferred footnote is the +only footnote on its page (i.e. it's marked in the document body with +a star) and the page it's deferred to has its own footnotes, +<strong>mom</strong> separates the deferred footnote from the page's +proper footnote(s) with a blank line. This avoids the confusion that +might result from readers seeing two footnote entries on the same page +identified by a single star (or the number 1 if you've requested +numbered footnotes that begin at 1 on every page). The blank line +makes it clear that the first footnote entry belongs to the previous +page. +</p> + +<p> +In the circumstance where a deferred footnote is not the only one +on its page, and is consequently marked by something other than a +single star, there's no confusion and <strong>mom</strong> doesn't +bother with the blank line. (By convention, the first footnote on +a page is always marked with a single star, so if readers see, say, +a dagger or double-dagger marking the first footnote entry, they'll +know the entry belongs to the previous page). +</p> + +<p> +Very exceptionally, two footnotes may have to be deferred (e.g. one +occurs on the second to last line of a page, and another on the last +line). In such a circumstance, <strong>mom</strong> does not add +a blank after the second deferred footnote. If you'd like a blank +line separating both deferred footnotes from any footnotes proper to +the page the deferred ones were moved to, add the space manually by +putting a +<a href="typesetting.html#SPACE"><kbd>.SPACE</kbd></a> +command at the end of the footnote text, before <nobr><kbd>.FOOTNOTE +OFF</kbd></nobr> (or <strong>X, QUIT, EXIT, etc...</strong>). +</p> + +<p> +Obviously, deferred footnotes aren't an issue if you request +numbered footnotes that increase incrementally throughout the whole +document — yet another convenience <strong>mom</strong> has +thought of. +</p> + +<p> +While <strong>mom</strong>'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 the page AND that page has some footnotes on it, +<strong>mom</strong> 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, <strong>mom</strong> +will either set the head, with nothing under it but footnotes, or +transfer the head to the next page. Either way, you'll have a +gaping hole at the bottom of the page. It's a sort of typographic +Catch-22, and can only be resolved by you, the writer or formatter +of the document, adjusting the type on the offending page so as to +circumvent the problem. +</p> + +<p> +<strong>NOTE:</strong> 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> + +<a name="FN_AND_PUNCT"><h3><u>Footnote markers and punctuation in the running text</u></h3></a> + +<p> +As of version 1.3-d, the manner of entering the line <em>after</em> +<nobr><strong>.FOOTNOTE OFF</strong></nobr> has changed. +</p> + +<a name="FN_AND_PUNCT_FILL"><h4><u>"Fill" modes — JUSTIFY, or QUAD LEFT | CENTER | RIGHT</u></h4></a> + +<p> +In fill modes, the correct way to enter the line after +<nobr><kbd>.FOOTNOTE OFF</kbd></nobr> is to input it as if it's +literally a continuation of the input line you were entering before +you invoked <kbd>.FOOTNOTE</kbd>. Therefore, if necessary, the +input line may have to begin with space(s) or a punctuation mark, as +in the two following examples. + +<pre> + Example 1 + --------- + A line of text,\c + .FOOTNOTE + A footnote line. + .FOOTNOTE OFF + broken up with a comma. + ^ + (last line begins with a literal space) + + Example 2 + --------- + 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) +</pre> +</p> + +<p> +Example 1 produces, on output + +<pre> + A line of text,* broken up with a comma. +</pre> +</p> + +<p> +Example 2 produces + +<pre> + A line of text*, broken up with a comma. +</pre> +</p> + +<p> +Care must be taken, though, if the punctuation mark that begins the +line after <nobr><strong>FOOTNOTE OFF</strong></nobr> is a period +(dot). You <strong><em>must</em></strong> begin such lines with +<kbd>\&.</kbd>, like this: + +<pre> + end of a sentence\c + .FOOTNOTE + A footnote line. + .FOOTNOTE OFF + \&. A new sentence... +</pre> +</p> + +<p> +If you omit the <kbd>\&.</kbd>, the line will vanish! +</p> + +<p> +<strong>NOTE:</strong> 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> + +<a name="FN_AND_PUNCT_NOFILL"><h4><u>"No-fill" modes — LEFT, CENTER, RIGHT</u></h4></a> + +<p> +In no-fill modes, you must decide a) whether text on the +<em>input</em> line after <nobr><kbd>.FOOTNOTE OFF</kbd></nobr> is +to be joined to the <em>output</em> line before <kbd>.FOOTNOTE</kbd> +was invoked, or b) whether you want the <em>output</em> 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 +<strong>mom</strong> that you want input text after +<nobr><kbd>FOOTNOTE OFF</kbd></nobr> to begin on a new output +line. This is accomplished by passing <nobr><kbd>.FOOTNOTE +OFF</kbd></nobr> (or <strong>QUIT, END, X,</strong> etc) an +additional argument: <kbd>BREAK</kbd> or <kbd>BR</kbd>. +</p> + +<p> +Study the two examples below to understand the difference. + +<pre> + Example 1 — No-fill mode, FOOTNOTE OFF with no BREAK + ----------------------------------------------------- + .LEFT + A line of text\c + .FOOTNOTE + A footnote line + .FOOTNOTE OFF + that carries on after the footnote. +</pre> + +produces, on output + +<pre> + A line of text* that carries on after the footnote. +</pre> + +whereas + +<pre> + Example 2 — No-fill mode, FOOTNOTE OFF with BREAK + -------------------------------------------------- + .LEFT + A line of text\c + .FOOTNOTE + A footnote line + .FOOTNOTE OFF BREAK + that doesn't carry on after the footnote. +</pre> + +produces the following on output: + +<pre> + A line of text* + that doesn't carry on after the footnote. +</pre> +</p> + +<p> +The distinction becomes particularly important if you like to see +punctuation marks come <em>after</em> footnote markers. In no-fill +modes, that's accomplished like this: + +<pre> + .LEFT + A line of text\c + .FOOTNOTE + A footnote line + .FOOTNOTE OFF + , + broken up with a comma. +</pre> +</p> + +<p> +The output of the above looks like this: + +<pre> + A line of text*, + broken up with a comma. +</pre> +</p> + +<p> +<strong>NOTE:</strong> 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> + +<!-- -FOOTNOTE- --> + +<hr width="66%" align="left"/> + +<a name="FOOTNOTE"></a> + +<p> +<nobr>Tag: <strong>FOOTNOTE</strong> <kbd><toggle> [ BREAK | BR ] | INDENT LEFT | RIGHT | BOTH <indent value></kbd></nobr> +<br/> + +<em>*See <a href="#FOOTNOTE_NOTE">HYPER-IMPORTANT NOTE</a>!!!</em> +<br/> + +<kbd><indent value></kbd> <em>requires a +<a href="definitions.html#TERMS_UNITOFMEASURE">unit of measure</a></em> +</p> + +<p> +<strong>FOOTNOTE</strong> 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 <em>other than INDENT</em> +(i.e. <strong>OFF, QUIT, END, X...</strong>) tells <strong>mom</strong> +you're finished. +</p> + +<p> +Footnotes are the only element of +<a href="definitions.html#TERMS_RUNNING">running text</a> +that are not affected by the typesetting +<a href="typesetting.html#INDENTS">indent macros</a>. +In the unlikely event that you want a page's footnotes to line +up with a running indent, invoke <kbd>.FOOTNOTE</kbd> with +the <kbd>INDENT</kbd> argument and pass it an indent direction and +indent value. <kbd>L, R,</kbd> and <kbd>B</kbd> may be used in place +of <kbd>LEFT, RIGHT,</kbd> and <kbd>BOTH</kbd>. <kbd>FOOTNOTE</kbd> +must be invoked with <kbd>.INDENT</kbd> for every footnote you want +indented; <strong>mom</strong> does not save any footnote indent +information from invocation to invocation. +</p> + +<p> +<strong>NOTE:</strong> If a footnote runs to more than one +paragraph(!), <strong>DO NOT</strong> begin the footnote with +the +<a href="#PP">PP</a> +tag. Use <kbd>.PP</kbd> only to introduce subsequent paragraphs. +</p> + +<p> +<a name="FOOTNOTE_NOTE"><strong>HYPER-IMPORTANT NOTE:</strong></a> +The final word on the +<a href="definitions.html#TERMS_INPUTLINE">input line</a> +that comes immediately before <strong>FOOTNOTE</strong> MUST terminate +with a +<a href="typesetting.html#JOIN"><kbd>\c</kbd></a> +inline escape if your +<a href="#FOOTNOTE_MARKER_STYLE">FOOTNOTE_MARKER_STYLE</a> +is either <strong>STAR</strong> or <strong>NUMBER</strong>. +See the +<a href="#FOOTNOTE_EXAMPLE">footnote example</a> +above. +</p> + +<p> +Additionally, in +<a href="definitions.html#TERMS_FILLED">fill</a> +modes +<nobr>(<a href="typesetting.html#JUSTIFY">JUSTIFY</a></nobr> +or +<a href="typesetting.html#QUAD">QUAD</a>), +the line <em>after</em> a <nobr><kbd>.FOOTNOTE OFF</kbd></nobr> +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#TERMS_NOFILL">no-fill</a> +modes, the optional argument <kbd>BREAK</kbd> or +<kbd>BR</kbd> may be used after the <strong>OFF</strong> (or +<strong>QUIT, END, X,</strong> etc.) argument to instruct +<strong>mom</strong> 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> +Do NOT use the <kbd>\c</kbd> inline escape if your +<strong>FOOTNOTE_MARKER_STYLE</strong> is <strong>LINE</strong>, or +if you have disabled footnote markers with +<nobr><a href="#FOOTNOTE_MARKERS"><kbd>.FOOTNOTE_MARKERS</kbd></a> <kbd>OFF</kbd></nobr>. +In these instances, the line after +<nobr><strong>FOOTNOTE OFF</strong></nobr> should be entered normally. +</p> + +<a name="FOOTNOTE_CONTROL"><h3><u>Footnote control macros</u></h3></a> + +<ol> + <li><a href="#FOOTNOTE_GENERAL">Family/font/size/colour/lead/quad</a></li> + <li><a href="#FOOTNOTE_MARKERS">Footnote markers</a> — on or off</li> + <li><a href="#FOOTNOTE_MARKER_STYLE">Footnote marker style</a> — star+dagger, numbered or by line number</li> + <ul> + <li><a href="#FOOTNOTE_LINENUMBER_BRACKETS">FOOTNOTE_LINENUMBER_BRACKETS</a></li> + <li><a href="#FOOTNOTE_LINENUMBER_SEPARATOR">FOOTNOTE_LINENUMBER_SEPARATOR</a></li> + <li><a href="#FOOTNOTES_RUN_ON">FOOTNOTES_RUN_ON</a>— line-numbered footnotes only</li> + </ul> + <li><a href="#RESET_FOOTNOTE_NUMBER">Reset footnote number</a> — set footnote marker number to 1</li> + <li><a href="#FOOTNOTE_SPACE">Inter-footnote spacing</a></li> + <li><a href="#FOOTNOTE_RULE">Footnote rule</a> — on or off</li> + <li><a href="#FOOTNOTE_RULE_LENGTH">Footnote rule length</a> — length of footnote separator rule</li> + <li><a href="#FOOTNOTE_RULE_WEIGHT">Footnote rule weight</a> — weight of footnote separator rule</li> + <li><a href="#FOOTNOTE_RULE_ADJ">Adjust vertical position of footnote separator rule</a></li> +</ol> + +<a name="FOOTNOTE_GENERAL"><h4><u>1. Family/font/size/colour/lead/quad</u></h4></a> + +<p> +See +<a href="#CONTROL_MACRO_ARGS">Arguments to the control macros</a>. +</p> + +<pre> +.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 +</pre> + +<a name="FOOTNOTE_MARKERS"><h4><u>2. Footnote markers — FOOTNOTE_MARKERS</u></h4></a> + +<p> +If you don't want footnote markers, in either the body of +the document or beside footnote entries themselves, toggle +them off with <nobr><kbd>.FOOTNOTE_MARKERS OFF</kbd></nobr> (or +<strong>END, QUIT, X</strong>...). This means, of course, that +you'll have to roll your own. If you want them back on, invoke +<kbd>.FOOTNOTE_MARKERS</kbd> with no argument. Footnote markers are +on by default. +</p> + +<p> +If <strong>FOOTNOTE_MARKERS</strong> are disabled, do NOT use +the <kbd>\c</kbd> inline escape to terminate the line before +<kbd>.FOOTNOTE</kbd>. +</p> + +<a name="FOOTNOTE_MARKER_STYLE"><h4><u>3. Footnote marker style — FOOTNOTE_MARKER_STYLE</u></h4></a> + +<p> +<strong>Mom</strong> 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 <strong>mom</strong> to start each page's footnote numbers at 1 +with <kbd>.RESET_FOOTNOTE_NUMBER</kbd> +(<a href="#RESET_FOOTNOTE_NUMBER">see below</a>.) +</p> + +<a name="FOOTNOTE_LINENUMBERS"></a> + +<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 <strong>FOOTNOTE_MARKER_STYLE LINE</strong>, +<strong>mom</strong> 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>, <em>without terminating +the text line before it with</em> <kbd>\c</kbd>, at the appropriate +place in running text. +</p> + +<p> +If you want a range of line numbers (e.g. [5-11] ), +insert, directly into the first line of the range you want, the +<a href="definitions.html#TERMS_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). +<strong>Mom</strong> 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> + +<a name="FOOTNOTE_LINENUMBER_BRACKETS"></a> + +<p> +<strong>Mom</strong>, by default, puts footnote line numbers inside +square brackets. The style of the brackets may be changed with +the macro, <strong>FOOTNOTE_LINENUMBER_BRACKETS</strong>, 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> + +<a name="FOOTNOTE_LINENUMBER_SEPARATOR"></a> + +<p> +If you don't want the numbers enclosed in brackets, you may tell +<strong>mom</strong> 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 <strong>FOOTNOTE_LINENUMBER_SEPARATOR</strong>, +which takes, as its single argument, the separator you want. For +safety and consistency's sake, ALWAYS enclose the argument in +double-quotes. +</p> + +<p> +The separator can be composed of any valid groff character, or any +combination of characters. <strong>A word of caution:</strong> when +using a separator, <strong>mom</strong> doesn't insert a space +after the separator. Hence, if you want the space (you probably +do), you must make the space part of the argument you pass to +<strong>FOOTNOTE_LINENUMBER_SEPARATOR</strong>. For example, +to get a colon separator with a space after it, you'd do + +<pre> + .FOOTNOTE_LINENUMBER_SEPARATOR ": " +</pre> +</p> + +<a name="FOOTNOTES_RUN_ON"><h5><u>RUN-ON FOOTNOTES</u></h5></a> + +<p> +Finally, if your footnote marker style is <strong>LINE</strong>, you +may instruct <strong>mom</strong> 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 <strong>mom</strong> to run footnotes on is +<kbd>.FOOTNOTES_RUN_ON</kbd>. Invoked by itself, it turns the +feature on. Invoked with any other argument (<strong>OFF</strong>, +<strong>NO</strong>, 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, <strong>mom</strong> will +issue a warning if there's going to be a problem. However, it is +always perfectly safe to enable/disable the feature after +<a href="rectoverso.html#COLLATE">COLLATE</a>. +</p> + +<p> +The usual reason for wanting run-on footnotes is that you're +using them to hold many, short references. (See +<a href="refer.html#TOP">here</a> +for instructions on using the <strong>groff</strong> program, +<strong>refer</strong>, to set up references.) +</p> + +<a name="RESET_FOOTNOTE_NUMBER"><h4><u>4. Reset footnote number — RESET_FOOTNOTE_NUMBER</u></h4></a> + +<p> +<kbd>.RESET_FOOTNOTE_NUMBER</kbd>, by itself, resets +footnote numbering so that the next footnote you enter is +numbered 1. +</p> + +<p> +<nobr><kbd>.RESET_FOOTNOTE_NUMBER PAGE</kbd></nobr> tells +<strong>mom</strong> to start every page's footnote numbering at 1. +</p> + +<a name="FOOTNOTE_SPACE"><h4><u>5. Inter-footnote spacing — FOOTNOTE_SPACE</u></h4></a> + +<p> +If you'd like a little extra space between footnotes, you can have +<strong>mom</strong> put it in for you by invoking +<kbd>.FOOTNOTE_SPACE</kbd> with an argument representing the +amount of extra space you'd like. The argument to +<strong>FOOTNOTE_SPACE</strong> requires a +<a href="definitions.html#TERMS_UNITOFMEASURE">unit of measure</a>. +</p> + +<p> +In the following example, footnotes will be separated from each +other by 3 +<a href="definitions.html#TERMS_PICASPOINTS">points</a>. + +<pre> + .FOOTNOTE_SPACE 3p +</pre> +</p> + +<a name="FOOTNOTE_RULE"><h4><u>6. Footnote rule — FOOTNOTE_RULE</u></h4></a> + +<p> +If you don't want a footnote separator rule, toggle it off with +<nobr><kbd>.FOOTNOTE_RULE OFF</kbd></nobr> (or <strong>END, +QUIT, X</strong>...). Toggle it back on by invoking +<kbd>.FOOTNOTE_RULE</kbd> with no argument. The default is to print +the rule. +</p> + +<a name="FOOTNOTE_RULE_LENGTH"><h4><u>7. Footnote rule length — FOOTNOTE_RULE_LENGTH</u></h4></a> + +<p> +If you want to change the length of the footnote separator rule, +invoke <kbd>.FOOTNOTE_RULE_LENGTH</kbd> with a length, like +this, + +<pre> + .FOOTNOTE_RULE_LENGTH 1i +</pre> + +which sets the length to 1 inch. Note that a +<a href="definitions.html#TERMS_UNITOFMEASURE">unit of measure</a> +is required. The default is 4 +<a href="definitions.html#TERMS_PICASPOINTS">picas</a> +for both +<a href="docprocessing.html#PRINTSTYLE">PRINTSTYLES</a>. +</p> + +<a name="FOOTNOTE_RULE_WEIGHT"><h4><u>8. Footnote rule weight — FOOTNOTE_RULE_WEIGHT</u></h4></a> + +<p> +If you want to change the weight ("thickness") of the +footnote separator rule, invoke <kbd>.FOOTNOTE_RULE_WEIGHT</kbd> +with the desired weight. The weight is measured in +<a href="definitions.html#TERMS_PICASPOINTS">points</a>; +however, do NOT append the +<a href="definitions.html#TERMS_UNITOFMEASURE">unit of measure</a>, +<kbd>p</kbd>, to the argument. +</p> + +<p> +<strong>Mom</strong>'s default footnote rule weight is 1/2 point. +If you'd like a 1-point rule instead, +<pre> + .FOOTNOTE_RULE_WEIGHT 1 +</pre> + +is how you'd get it. +</p> + +<a name="FOOTNOTE_RULE_ADJ"><h4><u>9. Adjust vertical position of footnote separator rule — FOOTNOTE_RULE_ADJ</u></h4></a> + +<p> +The footnote separator rule is a rule whose bottom edge falls +<em>on</em> +the +<a href="definitions.html#TERMS_BASELINE">baseline</a> +(at the footnote +<a href="definitions.html#TERMS_LEADING">leading</a>) +one line above the first line of a page's footnotes. By default, +<strong>mom</strong> raises the rule 3 +<a href="definitions.html#TERMS_PICASPOINTS">points</a> +from the baseline so that the separator and the footnotes don't +look jammed together. If you'd prefer a different vertical +adjustment, invoke <kbd>.FOOTNOTE_RULE_ADJ</kbd> with the +amount you'd like. For example + +<pre> + .FOOTNOTE_RULE_ADJ 4.25p +</pre> + +raises the rule by 4-1/4 points. Note that you can only raise +the rule, not lower it. A +<a href="definitions.html#TERMS_UNITOFMEASURE">unit of measure</a> +is required. +</p> + +<p> +<strong>Tip:</strong> If your document +<a href="definitions.html#TERMS_LEADING">leading</a> +is 2 +<a href="definitions.html#TERMS_PICASPOINTS">points</a> +or less (e.g your +<a href="definitions.html#TERMS_PS">point size</a> +is 10 and your linespacing is 10, 11, or 12), lowering +<strong>mom</strong>'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 to do so. +</p> + +<hr/> + +<!-- ==================================================================== --> + +<a name="ENDNOTE_INTRO"><h2><u>Endnotes</u></h2></a> + +<ul> + <li><a href="#ENDNOTE_BEHAVIOUR">Endnote behaviour</a></li> + <ul> + <li><a href="#ENDNOTE_SPACING">A Note on Endnote Spacing</a></li> + <li><a href="#ENDNOTE_COLUMNS">Endnotes and columnar documents</a></li> + </ul> + <li><a href="#ENDNOTE">Tag: ENDNOTE</a></li> + <li><a href="#ENDNOTES">Macro: ENDNOTES</a> — tell <strong>mom</strong> to output endnotes</li> + <li><a href="#ENDNOTE_CONTROL">ENDNOTES control macros</a></li> +</ul> + +<p> +Embedding endnotes into <strong>mom</strong> 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>. + +<a name="ENDNOTE_EXAMPLE"></a> +<pre> + ...the doctrines of Identity as urged by Schelling\c + .ENDNOTE + <endnote about who the hell is Schelling> + .ENDNOTE OFF + were generally the points of discussion presenting the most + of beauty to the imaginative Morella. +</pre> +</p> + +<p> +As with footnotes, note the obligatory use of the <kbd>\c</kbd> +<a href="definitions.html#TERMS_INLINES">inline escape</a> +when your +<a href="#ENDNOTE_MARKER_STYLE">ENDNOTE_MARKER_STYLE</a> +is <strong>NUMBER</strong> (which marks endnotes references in +<a href="definitions.html#TERMS_RUNNING">running text</a> +with superscript numbers). When the marker style is +<strong>LINE</strong>, you must <em>not</em> use the <kbd>\c</kbd> +escape. +</p> + +<p> +<strong>***Version 1.3-d change***</strong> +</p> + +<p> +As of version 1.3-d, the manner of entering the line <em>after</em> +<nobr><kbd>.ENDNOTE OFF</kbd></nobr> has changed to accommodate +users' differing wishes with respect to the order of punctuation and +endnote markers. <strong>Mom</strong> handles endnotes and footnotes +identically in this regard, so please read the footnote section, +<a href="#FN_AND_PUNCT">Footnote markers and punctuation in the running text</a>, +for an explanation. +</p> + +<p> +<strong>***End version 1.3-d change***</strong> +</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> + <li>When your <strong>ENDNOTE_MARKER_STYLE</strong> is + <strong>NUMBER</strong>, endnotes are always numbered + incrementally, starting at "1". + </li> + <li>Endnotes MUST be output explicitly; <strong>mom</strong> 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 <em>within</em> each endnote, +prior to invoking <kbd>.QUOTE</kbd> or <kbd>.BLOCKQUOTE</kbd>, +and undo them prior to terminating the endnote (i.e. before +<nobr><kbd>.ENDNOTE OFF</kbd>)</nobr>, otherwise the changes will +affect subsequent quotes and blockquotes that appear in the document +body as well. +</p> + +<a name="ENDNOTE_BEHAVIOUR"><h3><u>Endnote behaviour</u></h3></a> + +<p> +When you output endnotes (with +<a href="#ENDNOTES">ENDNOTES</a>), +<strong>mom</strong> finishes processing the last page of your document, +then breaks to a new page for printing the endnotes. If the document +type is +<a href="docprocessing.html#DOCTYPE">CHAPTER</a>, +the centre part of the +<a href="definitions.html#TERMS_HEADER">header</a> +(or footer), which, by default, contains a chapter number or title, +is removed. +</p> + +<p> +By default, <strong>mom</strong> starts the endnotes page with +a bold, centred, double-underlined head, "ENDNOTES". +Underneath — flush left, bold, and underscored — she +prints the document title (or, in the case of chapters, the chapter +number or title). She then prints the endnotes. Each endnote is +identified by its appropriate number, in bold, right aligned to two +placeholders. The text of the endnotes themselves is indented to +the right of the numbers. +</p> + +<p> +If the endnotes are grouped together at the end of a collated document, +each section of the document that contains endnotes is identified by its +own unique title (or chapter number or title), bold, flush left, and +underscored. +</p> + +<p> +Of course, all the defaults, as well as the overall style of the +endnotes page, can be changed with the +<a href="#ENDNOTE_CONTROL">endnote control macros</a>. +The attentive will notice that endnotes have an awful lot of control +macros. This is because endnotes are like a mini-document unto +themselves, and therefore need not be bound by the style parameters of +the body of the document. +</p> + +<a name="ENDNOTE_SPACING"><h3><u>A Note on Endnote Spacing</u></h3></a> + +<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 <strong>mom</strong> 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>) +<em>at the end of each endnote</em> (i.e. just before invoking +<nobr><a href="#ENDNOTE"><kbd>.ENDNOTE OFF</kbd></a>)</nobr> +rather than at the top. +</p> + +<a name="ENDNOTE_COLUMNS"><h3><u>Endnotes and columnar documents</u></h3></a> + +<p> +Formerly (pre 1.1.6), there was no way to set a document in columns +(see +<a href="docprocessing.html#COLUMNS">COLUMNS</a>) +and then turn off column mode for endnotes. As of version 1.1.6, +you may now do so. See +<a href="#ENDNOTES_NO_COLUMNS">ENDNOTES_NO_COLUMNS</a>. +</p> + +<!-- -ENDNOTE- --> + +<hr width="66%" align="left"/> + +<a name="ENDNOTE"></a> + +<p> +<nobr>Macro: <strong>ENDNOTE</strong> <kbd><toggle> [ BREAK | BR ]</kbd></nobr> +<br/> + +<em>*See <a href="#ENDNOTE_NOTE">HYPER-IMPORTANT NOTE</a>!!!</em> +</p> + +<p> +<strong>ENDNOTE</strong> 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. <strong>OFF, +QUIT, END, X...</strong>) tells <strong>mom</strong> that you've +finished the endnote. +</p> + +<p> +<strong>NOTE:</strong> If an endnote runs to more than one +paragraph, <strong>DO NOT</strong> begin the endnote with the +<a href="#PP">PP</a> +tag. Use <strong>PP</strong> only to introduce subsequent +paragraphs. +</p> + +<p> +<a name="ENDNOTE_NOTE"><strong>HYPER-IMPORTANT NOTE:</strong></a> +If your +<a href="#ENDNOTE_MARKER_STYLE">ENDNOTE_MARKER_STYLE</a> +is <strong>NUMBER</strong> (<strong>mom</strong>'s default), the +final word on the +<a href="definitions.html#TERMS_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#TERMS_FILLED">fill</a> +modes +(<a href="typesetting.html#JUSTIFY">JUSTIFY</a> +or +<a href="typesetting.html#QUAD">QUAD</a>, +the line <em>after</em> <nobr><kbd>.ENDNOTE OFF</kbd></nobr> +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#TERMS_NOFILL">no-fill</a> modes, the +optional argument <kbd>BREAK</kbd> or <kbd>BR</kbd> may be used +after the <kbd>OFF</kbd> (or <strong>QUIT, END, X,</strong> etc.) +argument to instruct <strong>mom</strong> 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> +If your <strong>ENDNOTE_MARKER_STYLE</strong> is +<strong>LINE</strong>, do NOT use the <kbd>\c</kbd> escape, and +enter the line after <nobr><kbd>.ENDNOTE OFF</kbd></nobr> +normally. +</p> + +<!-- -ENDNOTES- --> + +<hr width="33%" align="left"/> + +<a name="ENDNOTES"></a> + +<p> +<a name="ENDNOTES">Tag: <strong>ENDNOTES</strong></a> +</p> + +<p> +Unlike footnotes, which <strong>mom</strong> automatically outputs +at the bottom of pages, endnotes must be explicitly output by you, +the user. <strong>ENDNOTES</strong>, by itself (i.e. without any +argument), is the macro to do this. +</p> + +<p> +Typically, you'll use <strong>ENDNOTES</strong> at the end of +a document. If it's a single (i.e. not collated) document, +<strong>mom</strong> will print the endnotes pertaining to it. If +it's a collated document, <strong>mom</strong> 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>. +<strong>Mom</strong> 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 +<strong>mom</strong> collected after the previous invocation. +</p> + +<hr width="33%" align="left"/> + +<a name="ENDNOTE_CONTROL"><h3><u>Endnote control macros</u></h3></a> + +<h4><u>VERY IMPORTANT NOTE!</u></h4> + +<p> +Endnote control macros must always be invoked prior to the first +instance of +<a href="#ENDNOTE"><nobr><kbd>.ENDNOTE / .ENDNOTE OFF</kbd></nobr></a>. +</p> + +<p> +When you embed endnotes in the body of a document, +<strong>mom</strong> collects <em>and processes</em> them for later +outputting (when you invoke +<a href="#ENDNOTES"><kbd>.ENDNOTES</kbd></a>). +By the time you do invoke <kbd>.ENDNOTES</kbd>, it's much too late +to change your mind about how you want them to look. +</p> + +<p> +My advice? If you're planning to change the default appearance of +endnotes pages, set them up prior to +<a href="docprocessing.html#START">START</a>. +</p> + +<ol> + <li><a href="#ENDNOTES_GENERAL"><strong>General endnotes-pages style control</strong></a></li> + <ul> + <li><a href="#ENDNOTE_STYLE">Base family/font/quad for endnotes-pages</a></li> + <li><a href="#ENDNOTE_PT_SIZE">Base point size for the endnotes-pages</a></li> + <li><a href="#ENDNOTE_LEAD">Leading of endnotes-pages</a></li> + <li><a href="#SINGLESPACE_ENDNOTES">Singlespace endnotes (for TYPEWRITE only)</a></li> + <li><a href="#ENDNOTE_PARA_INDENT">Size of paragraph first line indent in multi-paragraph endnotes</a></li> + <li><a href="#ENDNOTE_PARA_SPACE">Inserting space between paragraphs of multi-paragraph endnotes</a></li> + <li><a href="#ENDNOTES_NO_COLUMNS">Turning off column mode during endnotes output</a></li> + <li><a href="#ENDNOTES_PAGINATION">Pagination of endnotes</a></li> + <ul> + <li><a href="#ENDNOTES_PAGENUM_STYLE">Endnotes-pages page numbering style</a></li> + <li><a href="#ENDNOTES_FIRST_PAGENUMBER">Setting the first page number of endnotes pages</a></li> + <li><a href="#ENDNOTES_NO_FIRST_PAGENUM">Omitting a page number on the first page of endnotes</a></li> + </ul> + <li><a href="#SUSPEND_PAGINATION">Suspending pagination of endnotes pages</a></li> + </ul> + <li><a href="#ENDNOTES_HEADER_CONTROL"><strong>Endnotes-page header/footer control</strong></a></li> + <ul> + <li><a href="#ENDNOTES_MODIFY_HDRFTR">Modifying what goes in the endnotes-pages header/footer</a></li> + <li><a href="#ENDNOTES_HDRFTR_CENTER">Enabling a header/footer centre when doctype is CHAPTER</a></li> + <li><a href="#ENDNOTES_ALLOWS_HEADERS">Allow headers on endnotes-pages</a></li> + </ul> + <li><a href="#ENDNOTES_MAIN_TITLE"><strong>Endnotes-page head (i.e. the title at the top) control</strong></a></li> + <ul> + <li><a href="#ENDNOTE_STRING">Creating/modifying the endnotes-page head</a></li> + <li><a href="#ENDNOTE_STRING_CONTROL">Endnotes-page head control</a></li> + <li><a href="#ENDNOTE_STRING_UNDERLINE">Endnotes-page head underlining</a></li> + <li><a href="#ENDNOTE_STRING_CAPS">Endnotes-page head capitalization</a></li> + </ul> + <li><a href="#ENDNOTES_DOC_TITLE"><strong>Endnote document-identification title</strong></a></li> + <ul> + <li><a href="#ENDNOTE_TITLE">Creating/modifying the endnote document-identification title</a></li> + <li><a href="#ENDNOTE_TITLE_CONTROL">Document-identification title control</a></li> + <li><a href="#ENDNOTE_TITLE_UNDERSCORE">Document-identification title underscoring</a></li> + </ul> + <li><a href="#ENDNOTES_NUMBERING"><strong>Endnotes-pages endnote numbering style</strong></a></li> + <ul> + <li><a href="#ENDNOTE_MARKER_STYLE">Endnote marker style</a> — by numbers in the text, or by line number</li> + <ul> + <li><a href="#ENDNOTE_LINENUMBER_GAP">ENDNOTE_LINENUMBER_GAP</a></li> + <li><a href="#ENDNOTE_LINENUMBER_BRACKETS">ENDNOTE_LINENUMBER_BRACKETS</a></li> + <li><a href="#ENDNOTE_LINENUMBER_SEPARATOR">ENDNOTE_LINENUMBER_SEPARATOR</a></li> + </ul> + <li><a href="#ENDNOTE_NUMBER_CONTROL">Endnotes-pages endnote numbering style control</a></li> + <li><a href="#ENDNOTE_NUMBER_ALIGNMENT">Endnote numbering alignment</a></li> + <ul> + <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> + </ul> +</ol> + +<a name="ENDNOTES_GENERAL"><h4><u>1. General endnotes page style control</u></h4></a> + +<a name="ENDNOTE_STYLE"><h5>*<u>Endnote family/font/quad</u></h5></a> + +<p> +See +<a href="#CONTROL_MACRO_ARGS">Arguments to the control macros</a>. +</p> + +<pre> +.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 or J +</pre> + +<!-- -ENDNOTE_PT_SIZE- --> + +<a name="ENDNOTE_PT_SIZE"><h5>*<u>Endnote point size</u></h5></a> + +<p> +<nobr>Macro: <strong>ENDNOTE_PT_SIZE</strong> <kbd><base type size of endnotes></kbd></nobr> +</p> + +<p> +Unlike most other control macros that deal with size of document +elements, <strong>ENDNOTE_PT_SIZE</strong> takes as its argument +an absolute value, relative to nothing. Therefore, the argument +represents the size of endnote type in +<a href="definitions.html#TERMS_PICASPOINTS">points</a>, +unless you append an alternative +<a href="definitions.html#TERMS_UNITOFMEASURE">unit of measure</a>. +For example, + +<pre> + .ENDNOTE_PT_SIZE 12 +</pre> + +sets the base point size of type on the endnotes page to 12 +points, whereas + +<pre> + .ENDNOTE_PT_SIZE .6i +</pre> + +sets the base point size of type on the endnotes page to 1/6 of an +inch. +</p> + +<p> +The type size set with <strong>ENDNOTE_PT_SIZE</strong> 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 TYPESET</a> +is 12.5 points (the same default size used in the body of the +document). +</p> + +<!-- -ENDNOTE_LEAD- --> + +<a name="ENDNOTE_LEAD"><h5>*<u>Endnote lead</u></h5></a> + +<p> +<nobr>Macro: <strong>ENDNOTE_LEAD</strong> <kbd><base leading of endnotes> [ ADJUST ] </kbd></nobr> +<br/> + +<em>*Does not require a <a href="definitions.html#TERMS_UNITOFMEASURE">unit of measure</a>; points is assumed</em> +</p> + +<p> +Unlike most other control macros that deal with leading of document +elements, <strong>ENDNOTE_LEAD</strong> takes as its argument an +absolute value, relative to nothing. Therefore, the argument +represents the +<a href="definitions.html#TERMS_LEADING">leading</a> +of endnotes in +<a href="definitions.html#TERMS_PICASPOINTS">points</a> +unless you append an alternative +<a href="definitions.html#TERMS_UNITOFMEASURE">unit of measure</a>. +For example, + +<pre> + .ENDNOTE_LEAD 14 +</pre> + +sets the base leading of type on the endnotes page to 14 +points, whereas + +<pre> + .ENDNOTE_LEAD .5i +</pre> + +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 +<strong>ENDNOTE_LEAD</strong> 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 TYPESET</a> +is 14 points, adjusted. +</p> + +<p> +<strong>NOTE:</strong> Even if you give <strong>mom</strong> +a <nobr><kbd>.DOC_LEAD_ADJUST OFF</kbd></nobr> command, she +will still, by default, adjust endnote leading. You MUST enter +<nobr><kbd>.ENDNOTE_LEAD <lead></kbd></nobr> with no +<kbd>ADJUST</kbd> argument to disable this default behaviour. +</p> + +<!-- -SINGLESPACE_ENDNOTES- --> + +<a name="SINGLESPACE_ENDNOTES"><h5>*<u>Singlespace endnotes (TYPEWRITE only)</u></h5></a> + +<p> +<nobr>Macro: <strong>SINGLESPACE_ENDNOTES</strong> <kbd><toggle></kbd></nobr> +</p> + +<p> +If your +<a href="docprocessing.html#PRINTSTYLE">PRINTSTYLE</a> +is <strong>TYPEWRITE</strong> and you use TYPEWRITE's default +double-spacing, endnotes are double-spaced. If your document is +single-spaced, endnotes are single-spaced. +</p> + +<p> +If, for some reason, you'd prefer that endnotes be single-spaced +in an otherwise double-spaced document (including double-spaced +<a href="rectoverso.html#COLLATE">collated</a> +documents), invoke <kbd>.SINGLESPACE_ENDNOTES</kbd> 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 +(<strong>OFF, QUIT, Q, X</strong>...). +</p> + +<!-- -ENDNOTE_PARA_INDENT- --> + +<a name="ENDNOTE_PARA_INDENT"><h5>*<u>Endnote paragraph indenting</u></h5></a> + +<p> +<nobr>Macro: <strong>ENDNOTE_PARA_INDENT</strong> <kbd><amount to indent first line of paragraphs in endnotes></kbd></nobr> +<br/> + +<em>*Requires a <a href="definitions.html#TERMS_UNITOFMEASURE">unit of measure</a></em> +</p> + +<p> +<strong>ENDNOTE_PARA_INDENT</strong> 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#TERMS_EM">ems</a> +for +<a href="docprocessing.html#PRINTSTYLE">PRINTSTYLE TYPESET</a>; +1/2 inch for +<a href="docprocessing.html#PRINTSTYLE">PRINTSTYLE TYPEWRITE</a>. +</p> + +<p> +<strong>NOTE:</strong> 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 <strong>ENDNOTE_PARA_INDENT</strong>. +</p> + +<!-- -ENDNOTE_PARA_SPACE- --> + +<a name="ENDNOTE_PARA_SPACE"><h5>*<u>Endnote paragraph spacing</u></h5></a> + +<p> +<nobr>Macro: <strong>ENDNOTE_PARA_SPACE</strong> <kbd><toggle></kbd></nobr> +</p> + +<p> +<strong>ENDNOTE_PARA_SPACE</strong> 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> + +<p> +<strong>NOTE:</strong> Each endnote itself is always +separated from any previous endnote by a line space. +<strong>ENDNOTE_PARA_SPACE</strong> refers only to paragraphs that +appear within each discrete endnote. +</p> + +<!-- -ENDNOTES_NO_COLUMNS- --> + +<a name="ENDNOTES_NO_COLUMNS"><h5>*<u>Turning off column mode during endnotes output</u></h5></a> + +<p> +<nobr>Macro: <strong>ENDNOTES_NO_COLUMNS</strong> <kbd><toggle></kbd></nobr> +</p> + +<p> +By default, if your document is +<a href="docprocessing.html#COLUMNS">set in columns</a>, +<strong>mom</strong> sets the endnotes in columns, too. However, +if your document is set in columns and you'd like the endnotes not +to be, just invoke <kbd>.ENDNOTES_NO_COLUMNS</kbd> with no argument. +The endnotes pages will be set to the full page measure of your +document. +</p> + +<p> +If you output endnotes at the end of each document in a +<a href="rectoverso.html#COLLATE">collated</a> +document set in columns, column mode will automatically +be reinstated for each document, even with +<strong>ENDNOTES_NO_COLUMNS</strong> turned on. In such +circumstances, you must re-enable it for each collated document. +</p> + +<a name="ENDNOTES_PAGINATION"><h5>*<u>Pagination of endnotes</u></h5></a> + +<!-- -ENDNOTES_PAGENUM_STYLE- --> + +<a name="ENDNOTES_PAGENUM_STYLE"><h6><u>Endnotes-pages page numbering style</u></h6></a> + +<p> +<nobr>Macro: <strong>ENDNOTES_PAGENUM_STYLE</strong> <kbd>DIGIT | ROMAN | roman | ALPHA | alpha</kbd></nobr> +</p> + +<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 + +<pre> + .ENDNOTES_PAGENUM_STYLE alpha +</pre> +</p> + +<!-- -ENDNOTES_FIRST_PAGENUMBER- --> + +<a name="ENDNOTES_FIRST_PAGENUMBER"><h6><u>Setting the first page number of endnotes pages</u></h6></a> + +<p> +<nobr>Macro: <strong>ENDNOTES_FIRST_PAGENUMBER</strong> <kbd><page # that appears on page 1 of endnotes></kbd></nobr> +</p> + +<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, <strong>ENDNOTES_FIRST_PAGENUMBER</strong> tells +<strong>mom</strong> what page number to put on the first page of +the endnotes. +</p> + +<p> +If you set <strong>ENDNOTES_FIRST_PAGENUMBER</strong> in collated +documents where the endnotes are output after each separate doc, +you have to reset every separate document's first page number after +<a href="rectoverso.html#COLLATE">COLLATE</a> +and before +<a href="docprocessing.html#START">START</a>. +</p> + +<!-- -ENDNOTES_NO_FIRST_PAGENUN- --> + +<a name="ENDNOTES_NO_FIRST_PAGENUM"><h6><u>Omitting a page number on the first page of endnotes</u></h6></a> + +<p> +<nobr>Macro: <strong>ENDNOTES_NO_FIRST_PAGENUM</strong> <kbd><toggle></kbd></nobr> +</p> + +<p> +This macro is for use only if <strong>FOOTERS</strong> are on. It +tells +<a href="#ENDNOTES">ENDNOTES</a> +not to print a page number on the first endnotes page. +<strong>Mom</strong>'s default is to print the page number. +</p> + +<!-- -SUSPEND_PAGINATION- --> + +<a name="SUSPEND_PAGINATION"><h6><u>Suspending pagination of endnotes pages</u></h6></a> + +<p> +Macro: <strong>SUSPEND_PAGINATION</strong> +<br/> + +Macro: <strong>RESTORE_PAGINATION</strong> +</p> + +<p> +<strong>SUSPEND_PAGINATION</strong> doesn't take an argument. +Invoked immediately prior to +<a href="#ENDNOTES">ENDNOTES</a>, +it turns off endnotes pages pagination. <strong>Mom</strong> +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> + +<a name="ENDNOTES_HEADER_CONTROL"><h4><u>2. Endnotes-page header/footer control</u></h4></a> + +<p> +<a name="ENDNOTES_MODIFY_HDRFTR"></a> +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 CHAPTER</a>, +<strong>mom</strong> prints the same header or footer used +throughout the document on the endnotes page(s). Chapters get +treated differently in that, by default, <strong>mom</strong> 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 <em>not</em> want <strong>mom</strong> to remove +the centre string from the endnotes page(s) headers/footers, invoke +<a href="#ENDNOTES_HDRFTR_CENTER"><kbd>.ENDNOTES_HEADER_CENTER</kbd></a> +with no argument. +</p> + +<p> +An important change you may want to make is to put the word +"Endnotes" in the header/footer centre position. +To do so, do + +<pre> + .HEADER_CENTER "Endnotes" + or + .FOOTER_CENTER "Endnotes" +</pre> + +prior to invoking <kbd>.ENDNOTES</kbd>. If your +<a href="docprocessing.html#DOCTYPE">DOCTYPE</a> +is <strong>CHAPTER</strong>, you must also invoke +<a href="#ENDNOTES_HDRFTR_CENTER">ENDNOTES_HEADER_CENTER</a> +for the <strong>HEADER_CENTER</strong> to appear. +</p> + +<a name="ENDNOTES_HDRFTR_CENTER"><h5>*<u>Endnotes page(s) header/footer centre string</u></h5></a> + +<p> +<nobr>Macro: <strong>ENDNOTES_HEADER_CENTER</strong> <kbd>toggle</kbd></nobr> +</p> + +<p> +If your +<a href="docprocessing.html#DOCTYPE">DOCTYPE</a> +is <strong>CHAPTER</strong> and you want <strong>mom</strong> +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. +<strong>Mom</strong>'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 (<strong>OFF, QUIT, Q, X</strong>...). +</p> + +<a name="ENDNOTES_ALLOWS_HEADERS"><h5>*<u>Allow headers on endnotes-pages</u></h5></a> + +<p> +<nobr>Macro: <strong>ENDNOTES_ALLOWS_HEADERS</strong> <kbd><none> | ALL</kbd></nobr> +</p> + +<p> +By default, if <strong>HEADERS</strong> are on, <strong>mom</strong> +prints page headers on all endnotes pages except the first. If you +don't want her to print headers on endnotes pages, do + +<pre> + .ENDNOTES_ALLOWS_HEADERS OFF +</pre> +</p> + +<p> +If you want headers on every page <em>including the first</em>, do + +<pre> + .ENDNOTES_ALLOWS_HEADERS ALL +</pre> +</p> + +<p> +<strong>NOTE:</strong> If <strong>FOOTERS</strong> are on, +<strong>mom</strong> prints footers on every endnotes page. This is +a style convention. In <strong>mom</strong>, there is no such beast +as <strong>ENDNOTES_ALLOWS_FOOTERS OFF</strong>. +</p> + +<a name="ENDNOTES_MAIN_TITLE"><h4><u>3. Endnotes first page header (title) control</u></h4></a> + +<!-- -ENDNOTE_STRING- --> + +<a name="ENDNOTE_STRING"><h5>*<u>Endnotes first page header (title) string</u></h5></a> + +<p> +<nobr>Macro: <strong>ENDNOTE_STRING</strong> <kbd>"<head to print at the top of endnotes>"</kbd></nobr> +</p> + +<p> +By default, <strong>mom</strong> prints the word +"ENDNOTES" as a head at the top of the first page +of endnotes. If you want her to print something else, invoke +<kbd>.ENDNOTE_STRING</kbd> with the endnotes-page head you want, +surrounded by double-quotes. If you don't want a head at the top +of the first endnotes-page, invoke <kbd>.ENDNOTE_STRING</kbd> with +a blank argument (either two double-quotes side by side — +<kbd>""</kbd> — or no argument at all). +</p> + +<!-- -ENDNOTE_STRING_CONTROL- --> + +<a name="ENDNOTE_STRING_CONTROL"><h5>*<u>Endnotes first page header (title) control</u></h5></a> + +<p> +See +<a href="#CONTROL_MACRO_ARGS">Arguments to the control macros</a>. +</p> + +<pre> +.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) +</pre> + +<!-- -ENDNOTE_STRING_ADVANCE- --> + +<a name="ENDNOTE_STRING_ADVANCE"><h5>*<u>Endnotes first page header (title) placement</u></h5></a> + +<p> +<nobr>Macro: <strong>ENDNOTE_STRING_ADVANCE</strong> <kbd><distance from top of page></kbd></nobr> +<br/> + +<em>*Argument requires a <a href="definitions.html#TERMS_UNITOFMEASURE">unit of measusure</a></em> +</p> + +<p> +By default, <strong>mom</strong> places the title (the docheader, as +it were) of endnotes pages (typically "ENDNOTES") on the same +<a href="definitions.html#TERMS_BASELINE">baseline</a> +that is used for the start of +<a href="definitions.html#TERMS_RUNNING">running text</a>. +If you'd prefer another location, higher or lower on the page +(thereby also raising or lowering the starting position of the +endnotes themselves), invoke <kbd>.ENDNOTE_STRING_ADVANCE</kbd> +with an argument stating the distance <em>from the top edge of the +page</em> at which you'd like the title placed. +</p> + +<p> +The argument requires a unit of measure, so if you'd like the title +to appear 1-1/2 inches from the top edge of the page, you'd tell +<strong>mom</strong> about it like this: + +<pre> + .ENDNOTE_STRING_ADVANCE 1.5i +</pre> +</p> + +<!-- -ENDNOTE_STRING_UNDERLINE- --> + +<a name="ENDNOTE_STRING_UNDERLINE"><h5>*<u>Endnotes first page header (title) underlining</u></h5></a> + +<p> +<nobr>Macro: <strong>ENDNOTE_STRING_UNDERLINE</strong> <kbd>[DOUBLE] [<underline weight> [<underline gap> [<distance between double rules]]] | <none> | <anything></kbd></nobr> +<br/> + +Alias: <strong>ENDNOTE_STRING_UNDERSCORE</strong> +<br/> + +<em>*The argument</em> <kbd><underline weight></kbd> <em>must</em> NOT <em>have the</em> <a href="definitions.html#TERMS_UNITOFMEASURE">unit of measure</a>, <kbd>p</kbd>, <em>appended to it</em> +</p> + +<p> +Invoked without an argument, <kbd>.ENDNOTE_STRING_UNDERLINE</kbd> +will place a single rule underneath the endnotes-page head. Invoked +with the argument <kbd>DOUBLE</kbd>, +<strong>ENDNOTE_STRING_UNDERLINE</strong> will double-underline +the head. Invoked with any other non-numeric argument, (e.g. +<strong>OFF</strong>, <strong>NO</strong>, <strong>X</strong>, etc.) +the macro disables underlining of the head. +</p> + +<p> +In addition, you can use <strong>ENDNOTE_STRING_UNDERLINE</strong> +to control the weight of the underline rule(s), the gap between the +head and the underline, and, in the case of double-underlines, the +distance between the two rules. +</p> + +<p> +Some examples: + +<pre> + .ENDNOTE_STRING_UNDERLINE 1 + - turn underlining on; set the rule weight to 1 point + + .ENDNOTE_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 + + .ENDNOTE_STRING_UNDERLINE DOUBLE .75 3p + - turn double-underlining on; set the rule weight to 3 points + + .ENDNOTE_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 +</pre> + +Note, from the above, that in all instances, underlining (single or +double) is enabled whenever <strong>ENDNOTE_STRING_UNDERLINE</strong> +is used in this way. +</p> + +<p> +<strong>Mom</strong>'s default is to double-underline the head +with 1/2-point rules placed 2 points apart and 2 points below the +baseline of the head. +</p> + +<!-- -ENDNOTE_STRING_CAPS- --> + +<a name="ENDNOTE_STRING_CAPS"><h5>*<u>Endnotes first page header (title) automatic capitalization</u></h5></a> + +<p> +<nobr>Macro: <strong>ENDNOTE_STRING_CAPS</strong> <kbd>toggle</kbd></nobr> +</p> + +<p> +Invoked by itself, <kbd>.ENDNOTE_STRING_CAPS</kbd> will +automatically capitalize the endnotes-page head. Invoked with any +other argument, the macro disables automatic capitalization of the +head. +</p> + +<p> +If you're generating a table of contents, you may want the +endnotes-pages head string in caps, but the toc entry in caps/lower +case. If the argument to +<a href="#ENDNOTE_STRING">ENDNOTE_STRING</a> +is in caps/lower case and <strong>ENDNOTE_STRING_CAPS</strong> is +on, this is exactly what will happen. +</p> + +<p> +<strong>Mom</strong>'s default is to capitalize the endnotes-pages +head string. +</p> + +<!-- -ENDNOTE_TITLE- --> + +<a name="ENDNOTES_DOC_TITLE"><h4><u>4. Endnote document-identification title</u></h4></a> + +<a name="ENDNOTE_TITLE"><h5>*<u>Endnote document-identification title string</u></h5></a> + +<p> +<nobr>Macro: <strong>ENDNOTE_TITLE</strong> <kbd>"<title to identify a document in endnotes>"</kbd></nobr> +</p> + +<p> +By default, <strong>mom</strong> identifies the document(s) to which +endnotes belong by the document title(s) given to the +<a href="docprocessing.html#TITLE">TITLE</a> +macro. If you'd like her to identify the document(s) another way, +just invoke <kbd>.ENDNOTE_TITLE</kbd> with the identifying title you +want, surrounded by double-quotes. +</p> + +<p> +If you don't want any identifying title, invoke +<kbd>.ENDNOTE_TITLE</kbd> with a blank argument (either two +double-quotes side by side — <kbd>""</kbd> — +or no argument at all). This is particularly useful if you have a +single (i.e. non-collated) document and find having the document's +title included in the endnotes redundant. +</p> + +<!-- -ENDNOTE_TITLE_CONTROL- --> + +<a name="ENDNOTE_TITLE_CONTROL"><h5>*<u>Endnote document-identification title control</u></h5></a> + +<p> +See +<a href="#CONTROL_MACRO_ARGS">Arguments to the control macros</a>. +</p> + +<pre> +.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) +</pre> + +<!-- -ENDNOTE_TITLE_UNDERLINE- --> + +<a name="ENDNOTE_TITLE_UNDERLINE"><h5>*<u>Endnotes-page head (title) underlining</u></h5></a> + +<p> +<nobr>Macro: <strong>ENDNOTE_TITLE_UNDERLINE</strong> <kbd>[DOUBLE] [<underline weight> [<underline gap> [<distance between double rules]]] | <none> | <anything></kbd></nobr> +<br/> + +Alias: <strong>ENDNOTE_TITLE_UNDERSCORE</strong> +<br/> + +<em>*The argument</em> <kbd><underline weight></kbd> <em>must</em> NOT <em>have the</em> <a href="definitions.html#TERMS_UNITOFMEASURE">unit of measure</a>, <kbd>p</kbd>, <em>appended to it</em> +</p> + +<p> +Invoked without an argument, <kbd>.ENDNOTE_TITLE_UNDERLINE</kbd> +will place a single rule underneath the document identification +title. Invoked with the argument <kbd>DOUBLE</kbd>, +<strong>ENDNOTE_TITLE_UNDERLINE</strong> will double-underline +the title. Invoked with any other non-numeric argument, (e.g. +<strong>OFF</strong>, <strong>NO</strong>, <strong>X</strong>, etc.) +the macro disables underlining of the title. +</p> + +<p> +In addition, you can use <strong>ENDNOTE_TITLE_UNDERLINE</strong> +to control the weight of the underline rule(s), the gap between the +title and the underline, and, in the case of double-underlines, the +distance between the two rules. +</p> + +<p> +Some examples: + +<pre> + .ENDNOTE_TITLE_UNDERLINE 1 + - turn underlining on; set the rule weight to 1 point + + .ENDNOTE_TITLE_UNDERLINE 1 3p + - turn underlining on; set the rule weight to 1 point; set + the gap between the title and the underline to 3 points + + .ENDNOTE_TITLE_UNDERLINE DOUBLE .75 3p + - turn double-underlining on; set the rule weight to 3 points + + .ENDNOTE_TITLE_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 title and the upper + underline to 1-1/2 points; set the gap between the upper + and the lower underline to 1-1/2 points +</pre> + +Note, from the above, that in all instances, underlining (single or +double) is enabled whenever <strong>ENDNOTE_TITLE_UNDERSCORE</strong> +is used in this way. +</p> + +<p> +<strong>Mom</strong>'s default is to single-underline the title +with a 1/2-point rule place 2 points below its baseline. +</p> + +<!-- -ENDNOTE_NUMBERING- --> + +<a name="ENDNOTES_NUMBERING"><h4><u>5. Endnotes-pages endnote numbering style</u></h4></a> + +<a name="ENDNOTE_MARKER_STYLE"><h5>*<u>Endnote marker style</u></h5></a> + +<p> +The macro to control how endnotes are referenced is +<strong>ENDNOTE_MARKER_STYLE</strong>. +</p> + +<p> +By default, <strong>mom</strong> places superscript numbers in +<a href="definitions.html#RUNNING">running text</a> +to identify endnotes. However, if you have +<a href="#NUMBER_LINES">line-numbering</a> +turned on, you may instruct <strong>mom</strong> not to put +superscript numbers in the running text, but rather to reference +endnotes by line number. The command to do this is + +<pre> + .ENDNOTE_MARKER_STYLE LINE +</pre> +</p> + +<p> +With <strong>ENDNOTE_MARKER_STYLE LINE</strong>, +<strong>mom</strong> will identify endnotes either by single +line numbers, or line ranges. If what you want is a single line +number, you need only invoke <kbd>.ENDNOTE</kbd>, <em>without +terminating the text line before it with</em> <kbd>\c</kbd>, +at the appropriate place in running text. (Should you wish to +revert to <strong>mom</strong>'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> + +<a name="EN-MARK"></a> + +<p> +If you want a range of line numbers (e.g. [5-11] ), +insert, directly into the first line of the range you want, the +<a href="definitions.html#TERMS_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). +<strong>Mom</strong> is smart enough to figure out that where +<kbd>.ENDNOTE</kbd> is invoked represents the terminating line +number. +</p> + +<a name="ENDNOTE_LINENUMBER_GAP"><h5>*<u>Spacing between line-numbered endnotes and the endnote text</u></h5></a> + +<p> +Given the impossibility of knowing, in advance, the "string length" +of all the line numbers or ranges of line numbers that will be used +in endnotes (the string length of 12 is two; the string length +of 12-15 is 5), <strong>mom</strong> cannot "hang" line numbers +and guarantee that they, and the endnote text, will align in a +visually pleasing manner. Consequently, <strong>mom</strong> sets +the entirety of line-numbered endnotes completely flush left, +<strong>including the line numbers themselves</strong>. 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: + +<pre> + [1-2] Notwithstanding, Frye later asserts that Christianity + is "a ghost with the chains of a foul historical record of + cruelty clanking behind it." +</pre> +</p> + +<p> +You can change the size of the gap with the macro, +<strong>ENDNOTE_LINENUMBER_GAP</strong>, which takes as its single +argument the size of the gap. The argument requires a +<a href="definitions.html#TERMS_UNITOFMEASURE">unit of measure</a>. +So, for example, to change the gap to 2 +<a href="definitions.html#TERMS_PICASPOINTS">picas</a>, +you'd do + +<pre> + .ENDNOTE_LINENUMBER_GAP 2P +</pre> +</p> + +<p> +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#TERMS_EM">ems</a>. +</p> + +<a name="ENDNOTE_LINENUMBER_BRACKETS"><h5>*<u>Brackets around endnotes line-numbers</u></h5></a> + +<p> +By default, <strong>mom</strong> puts endnote line numbers inside +square brackets. The style of the brackets may be changed with the +macro, <strong>ENDNOTE_LINENUMBER_BRACKETS</strong>, 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> + +<a name="ENDNOTE_LINENUMBER_SEPARATOR"><h5>*<u>A separator after endnotes line-numbers instead of brackets</u></h5></a> + +<p> +If you don't want the numbers enclosed in brackets, you may tell +<strong>mom</strong> 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 <strong>ENDNOTE_LINENUMBER_SEPARATOR</strong>, +which takes, as its single argument, the separator you want. +(If the argument contains spaces, don't forget to enclose the +argument in double-quotes.) The separator can be composed of +any valid groff character, or any combination of characters. +For example, to get a colon separator after the line number in +line-numbered endnotes, you'd do + +<pre> + .ENDNOTE_LINENUMBER_SEPARATOR : +</pre> +</p> + +<a name="ENDNOTE_NUMBER_CONTROL"><h5>*<u>Endnote numbering style control</u></h5></a> + +<p> +See +<a href="#CONTROL_MACRO_ARGS">Arguments to the control macros</a>. +</p> + +<p> +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> + +<pre> +.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) +</pre> + +<a name="ENDNOTE_NUMBER_ALIGNMENT"><h5>*<u>Endnote numbering alignment</u></h5></a> + +<p> +By default, <strong>mom</strong> hangs the numbers on endnotes pages, +aligned right to two placeholders, producing this: + +<a name="ENDNOTE_NUMBERING_ALIGNMENT_EXAMPLE"></a> + +<pre> + 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. +</pre> +</p> + +<p> +The macros to alter this behaviour are + +<ul> + <li><a href="#ENDNOTE_NUMBERS_ALIGN_RIGHT"><strong>ENDNOTE_NUMBERS_ALIGN_RIGHT</strong></a></li> + <li><a href="#ENDNOTE_NUMBERS_ALIGN_LEFT"><strong>ENDNOTE_NUMBERS_ALIGN_LEFT</strong></a></li> +</ul> +</p> + +<hr width="33%" align="left"/> + +<!-- -ENDNOTE_NUMBERS_ALIGN_RIGHT- --> + +<a name="ENDNOTE_NUMBERS_ALIGN_RIGHT"></a> + +<p> +<nobr>Macro: <strong>ENDNOTE_NUMBERS_ALIGN_RIGHT</strong> <number of placeholders></nobr> +</p> + +<p> +<strong>ENDNOTE_NUMBERS_ALIGN_RIGHT</strong> 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 + +<pre> + .ENDNOTE_NUMBERS_ALIGN_RIGHT 1 +</pre> + +which would ensure that the endnote numbers hang, but are all flush +with the page's left margin. If, god help you, you have over a hundred +endnotes, you'd want to do + +<pre> + .ENDNOTE_NUMBERS_ALIGN_RIGHT 3 +</pre> + +to ensure that the numbers hang and are properly right-aligned. +</p> + +<hr width="33%" align="left"/> + +<!-- -ENDNOTE_NUMBERS_ALIGN_LEFT- --> + +<a name="ENDNOTE_NUMBERS_ALIGN_LEFT"></a> + +<p> +Macro: <strong>ENDNOTE_NUMBERS_ALIGN_LEFT</strong> +</p> + +<p> +If you don't want the endnote numbers to hang and right-align, +invoke <kbd>.ENDNOTE_NUMBERS_ALIGN_LEFT</kbd>, which doesn't require +any argument. This disables hanging and right-alignment of endnote +numbers, so that the example +<a href="#ENDNOTE_NUMBERING_ALIGNMENT_EXAMPLE">above</a> +comes out like this: + +<pre> + 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. +</pre> +</p> + +<hr/> + +<!-- ==================================================================== --> + +<a name="MARGIN_NOTES_INTRO"><h2><u>Margin notes</u></h2></a> + +<ul> + <li><a href="#MARGIN_NOTES_BEHAVIOUR">Margin notes behaviour</a></li> + <ul> + <li><a href="#MARGIN_NOTES_VERTICAL">Adjusting the vertical position of margin notes</a></li> + </ul> + <li><a href="#MN_INIT">Macro: MN_INIT</a> — initialize margin notes</li> + <li><a href="#MN">Tag: MN</a></li> +</ul> + +<p> +Margin notes are short annotations that appear in either the left +or right margin of a document. Sometimes they comment on the text. +Sometimes they assist in following the "flow" of a +document by summarizing the subject of a portion of text. Sometimes +they're comments to yourself in a draft copy. +</p> + +<p> +The margin notes macros and routines in om.tmac +(<strong>mom</strong>) are "mommified" versions of the +margin notes macros and routines written by Werner Lemberg and +patched by Gaius Mulley. +</p> + +<a name="MARGIN_NOTES_BEHAVIOUR"><h3><u>Margin notes behaviour</u></h3></a> + +<p> +First things first: before you enter your first margin note, you +must "initialize" margin notes with +<a href="#MN_INIT">MN_INIT</a>. +<strong>MN_INIT</strong> sets up the style parameters for margin +notes, including things like +<a href="definitions.html#TERMS_FONT">font</a>, +<a href="definitions.html#TERMS_FAMILY">family</a> +and +<a href="definitions.html#TERMS_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 <strong>MN</strong>, 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#TERMS_RUNNING">running text</a>, +it's impossible for <strong>mom</strong> to guess whether to align +the first lines of margin notes with a document +<a href="definitions.html#TERMS_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, <strong>mom</strong> 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, <strong>mom</strong> tries to place margin +notes at the point where you invoke the tag, +<a href="#MN"><kbd>.MN</kbd></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, <strong>mom</strong> will "shift" the +margin note down on the page, placing it one (margin note) linespace +beneath the previous margin note (plus whatever vertical space +is required to get the first line to line up with a baseline of +running text). A warning will be issued, letting you know this has +happened, and where. +</p> + +<p> +Sometimes, if a margin note has to be shifted down, there simply +isn't enough room to start the margin note on the page on which +<kbd>.MN</kbd> is invoked. In that case, <strong>mom</strong> +ignores the margin note entirely and issues a warning, letting you +know what she's done, and where. +</p> + +<p> +In the event that a margin note, sucessfully begun on a page, runs +past your bottom margin (or the last line before footnotes begin), +the margin note will "flow" onto the next page. If it is +a "left" margin note, it will continue in the left margin. +If it is a "right" margin note, it will continue in the +right margin. +</p> + +<p> +If your document is being set in two columns, <strong>mom</strong> +will sensibly and automatically set all margin notes pertaining +to the left column in the left margin, and all margin notes +pertaining to the right column in the right margin, regardless of +the "direction" argument you give the <strong>MN</strong> +tag. If you try to use <strong>MN</strong> in documents of more +than two columns, <strong>mom</strong> will ignore all margin notes, +and issue warning for each. +</p> + +<a name="MARGIN_NOTES_VERTICAL"><h4><u>Adjusting the vertical position of margin notes</u></h4></a> + +<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 + +<pre> + \!<a href="typesetting.html#ALD">.ALD</a> (to lower the margin note)a + and + \!<a href="typesetting.html#RLD">.RLD</a> (to raise it) +</pre> + +The <kbd>\!</kbd> <em>must</em> precede the macros, or they won't +have any effect. +</p> + +<hr width="66%" align="left"/> + +<!-- -MN_INIT- --> + +<a name="MN_INIT"></a> + +<p> +Macro: <strong>MN_INIT</strong> +<br/> + +<em>Macro arguments:</em> +<br/> + +<kbd><nobr>[ RAGGED | SYMMETRIC ]</nobr> +<br/> + +<nobr>< left-width right-width gutter family+font point-size lead colour hyphenation-flags ></nobr></kbd> +</p> + +<p> +Before you enter your first margin note, you must initialize +all the parameters associated with margin notes with +<strong>MN_INIT</strong>. If you forget to do so, +<strong>mom</strong> will issue a warning and abort. +</p> + +<p> +The argument list is quite long; an explanation of each argument +follows. Any argument whose value you want to be the default must +be entered as <kbd>""</kbd> (i.e. two double-quotes with +no space between them). Defaults for each argument are given in the +explanations below. +</p> + +<h4><kbd>[ 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 +<em>right</em>, and right margin notes will be set flush +<em>left</em>. The effect is something like this: + +<pre> + 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. +</pre> +</p> + +<p> +If the argument is omitted, or given as "", 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><kbd><left-width></kbd></h4> + +<p> +The width of left margin notes. A +<a href="definitions.html#TERMS_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><kbd><right-width></kbd></h4> + +<p> +The width of right margin notes. A +<a href="definitions.html#TERMS_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><kbd><gutter></kbd></h4> + +<p> +The +<a href="definitions.html#TERMS_GUTTER">gutter</a> +between margin notes and +<a href="definitions.html#TERMS_RUNNING">running text</a>. +A +<a href="definitions.html#TERMS_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#TERMS_EM">em</a>. +</p> + +<h4><kbd><font></kbd></h4> + +<p> +The family+font for margin notes. Yes, that's right: the family +PLUS font combo. For example, if you want Times Roman Medium, +the argument must be TR. If you want Palatino Medium Italic, the +argument must be PI. The default is the same family+font combo used +for a document's paragraph text. +</p> + +<h4><kbd><point size></kbd></h4> + +<p> +The point size of type for margin notes. There is no need to append a +<a href="definitions.html#TERMS_UNITOFMEASURE">unit of measure</a> +to the argument; +<a href="definitions.html#TERMS_PICASPOINTS">points</a> +is assumed (although there's nothing preventing you from appending an +alternative unit of measure directly to the argument). The default +is for margin notes to use the same point size of type as is used +in document paragraphs. +</p> + +<h4><kbd><lead></kbd></h4> + +<p> +The +<a href="definitions.html#TERMS_LEADING">leading</a> +of margin notes. <strong>lead</strong> uses +<a href="definitions.html#TERMS_PICASPOINTS">points</a> +as its unit of measure, so don't tack a unit of measure onto the +end of the argument. The default lead is the same leading as +is used for paragraph text (i.e. the document's base leading). +For convenience and clarity, you may, instead, give the word, +<strong>DOC</strong>, to this argument, which indicates that the +leading should be the same as the document's base leading. +</p> + +<h4><kbd><colour></kbd></h4> + +<p> +The colour of margin notes. The colour must be pre-initialized +with +<a href="color.html#NEWCOLOR">NEWCOLOR</a> +or +<a href="color.html#XCOLOR">XCOLOR</a>. +The default is black. +</p> + +<h4><kbd><hyphenation-flags></kbd></h4> + +<p> +A number telling <strong>groff</strong> how you want margin notes +hyphenated. + +<pre> + 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 +</pre> + +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- --> + +<hr width="33%" align="left"/> + +<a name="MN"></a> + +<p> +<nobr>Macro: <strong>MN</strong> <kbd>LEFT | RIGHT</kbd></nobr> +</p> + +<p> +Once you've initialized margin notes with +<a href="#MN_INIT"><kbd>.MN_INIT</kbd></a>, +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 +<strong>QUIT</strong>, <strong>END</strong>, <strong>X</strong>, +etc) exits the current margin note. +</p> + +<hr/> + +<!-- ==================================================================== --> + +<!-- -BLANK_PAGE- --> + +<a name="BLANK_PAGE_TITLE"><h2><u>Inserting a blank page into the document</u></h2></a> + +<a name="BLANK_PAGE"></a> +<p> +<nobr>Macro: <strong>BLANKPAGE</strong> <kbd><# of blank pages to insert> | NULL</kbd></nobr> +</p> + +<p> +This one does exactly what you'd expect — inserts a blank +page into the document. Unless you give the optional argument, +<kbd>NULL</kbd>, <strong>mom</strong> 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's up to you, the user, +to figure out what to do with this feature. However, it's worth +noting that without it, inserting completely blank pages, to use +a vernacular Québécois phrase, "c'est pas évident" +(somewhere between "isn't easy", "isn't obvious" +and "isn't fun"). +</p> + +<p> +The required argument to <strong>BLANK_PAGE</strong> 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 +<strong>mom</strong>: + +<pre> + .BLANKPAGE 1 +</pre> +</p> + +<p> +The optional argument, <kbd>MULL</kbd>, allows you to output the +specified number of pages without <strong>mom</strong> 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> + +<hr/> + +<!-- -FINIS- --> + +<a name="FINIS_INTRO"><h2><u>Document termination string</u></h2></a> + +<ul> + <li><a href="#FINIS">Tag: FINIS</a></li> + <ul> + <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> +</ul> + +<p> +The use of <strong>FINIS</strong> is optional. If you invoke it +(at the end of a document before +<a href="#TOC">TOC</a> +or +<a href="#ENDNOTES">ENDNOTES</a>), +<strong>mom</strong> +deposits the word, END, centred after a blank line, beneath the last +line of the document. END is enclosed between +<a href="definitions.html#TERMS_EM">em-dashes</a>. +</p> + +<p> +<strong>Please note</strong> that in versions of +<strong>mom</strong> prior to 1.1.9, <strong>FINIS</strong> used to +turn off +<a href="definitions.html#TERMS_FOOTER">footers</a> +(if they were on) and page numbering (if page numbers were at the +bottom of the page). Damned if I can recall why I thought anyone +would want this behaviour; it has been removed. +</p> + +<p> +If you're writing in a language other than English, you can +change what <strong>mom</strong> prints for END with +the control macro <strong>FINIS_STRING</strong>. +</p> + +<hr width="66%" align="left"/> + +<a name="FINIS"></a> + +<p> +Macro: <strong>FINIS</strong> +</p> + +<p> +The use of <strong>FINIS</strong> is optional, but if you use +it, it should be the last macro you invoke in a document (before +<a href="#ENDNOTES">ENDNOTES</a> +or +<a href="#TOC">TOC</a>). +See +<a href="#FINIS_INTRO">above</a> +for a description of how <strong>FINIS</strong> behaves. +</p> + +<p> +<strong>NOTE:</strong> If you don't use <strong>FINIS</strong>, +and you don't want +<a href="definitions.html#TERMS_FOOTER">footers</a> +(if they're on) or a page number at the bottom of the last page of +a document, you have to turn them off manually, as the last two +lines of your document file, like this: + +<pre> + .FOOTERS OFF + .PAGINATE OFF +</pre> +</p> + +<!-- -FINIS STRING- --> + +<hr width="33%" align="left"/> + +<a name="FINIS_STRING"><h3><u>Changing the FINIS string</u></h3></a> + +<p> +By default, <strong>FINIS</strong> prints the word, END, between +<a href="definitions.html#TERMS_EM">em-dashes</a>. +If you'd like <strong>mom</strong> to print something else +between the dashes, use the <strong>FINIS_STRING</strong> macro +(anywhere in the document prior to <strong>FINIS</strong>). +</p> + +<p> +For example, if your document's in French, you'd do + +<pre> + .FINIS_STRING "FIN" +</pre> + +Double-quotes must enclose the macro's argument. +</p> + +<p> +<strong>NOTE:</strong> If you pass <strong>FINIS_STRING</strong> +a blank string, i.e. + +<pre> + .FINIS_STRING "" +</pre> + +<strong>mom</strong> will still print the em-dashes if 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 TYPEWRITE</a>, +it's a short, dashed line composed of four hyphens.) +</p> + +<!-- -FINIS STRING CAPS- --> + +<hr width="33%" align="left"/> + +<a name="FINIS_STRING_CAPS"><h3><u>Automatic capitalization of the FINIS string</u></h3></a> + +<p> +By default, <strong>mom</strong> sets the string you pass to +<strong>FINIS</strong> all-caps. If you'd prefer that she not +do so, but rather respect the FINIS string exactly as you enter +it, invoke the macro, <kbd>.FINIS_STRING_CAPS</kbd> with the +<kbd>OFF</kbd> argument, like this: + +<pre> + .FINIS_STRING_CAPS OFF +</pre> + +<kbd>OFF</kbd>, above, could be anything, e.g. <strong>NO</strong> +or <strong>X</strong>. +</p> + +<!-- -FINIS COLOR- --> + +<hr width="33%" align="left"/> + +<a name="FINIS_COLOR"><h3><u>Changing the FINIS colour</u></h3></a> + +<p> +Invoking the control macro, <strong>FINIS_COLOR</strong>, with a +pre-defined (or "initalized") color changes the colour of +both the FINIS string and the em-dashes that surround it. If you +use the +<a href="definitions.html#TERMS_INLINE">inline escape</a>, +<a href="color.html#COLOR_INLINE"><kbd>\*[<colorname>]</kbd></a>, +in the argument passed to <strong>FINIS</strong>, only the text +will be in the new colour; the em-dashes will be in the default +document colour (usually black). +</p> + +<hr/> + +<!-- ==================================================================== --> + +<a name="TOC_INTRO"><h2><u>Tables of contents</u></h2></a> + +<ul> + <li><a href="#TOC_BEHAVIOUR">TOC behaviour</a> + <ul> + <li><a href="#PSSELECT">Using psselect to put the table of contents where you want</a></li> + </ul></li> + <li><a href="#TOC">Macro: TOC</a> — tell <strong>mom</strong> to output a table of contents</li> + <li><a href="#TOC_CONTROL">TOC control macros</a></li> +</ul> + +<p> +Want a table of contents for your document? Easy. Just enter + +<pre> + .TOC +</pre> + +as the very last macro of your document file. <strong>Mom</strong> +will have picked up all document titles (in +<a href="rectoverso.html#COLLATE">collated</a> +documents), all heads, subheads, and paragraph heads, as well as any +endnotes pages that have been output, and assigned them the +appropriate page number (and page numbering style). Talk about a +no-brainer! +</p> + +<p> +That said, tables of contents (tocs) have even more control macros +than endnotes. As always, the reason for so many control macros is +so that if you want to change just about any aspect of the toc's +typographic appearance, you can. <strong>Mom</strong> is all about +simplicity AND flexibility. +</p> + +<a name="TOC_BEHAVIOUR"><h3><u>TOC behaviour</u></h3></a> + +<p> +When you output a toc (with +<a href="#TOC">TOC</a>), +<strong>mom</strong> finishes processing the last page of your document, +then breaks to a new page for printing the toc. +</p> + +<p> +<strong>Mom</strong> follows standard typesetting conventions for +tables of contents. To this end, if +<a href="headfootpage.html#HEADERS">HEADERS</a> +are on for the document, the first page of the toc has no page +header, but does have a first page (roman numeral) number, always +"1", in the bottom margin. If +<a href="headfootpage.html#FOOTERS">FOOTERS</a> +are on for the document, the first page has neither a footer, nor a +page number in the top margin. (If you absolutely must have a page +footer on the first page of the toc, simply invoke +<a href="headfootpage.html#FOOTER_ON_FIRST_PAGE"><kbd>.FOOTER_ON_FIRST_PAGE</kbd></a> +immediately before <strong>TOC</strong>.) Subsequent toc pages have +both page headers or footers and a page number. +</p> + +<p> +Entries in the toc are hierarchically indented, as you would +expect. By default, each type of entry (e.g. a head or a subhead) +is set in a different font as well. If any of heads, subheads or +paragraph heads are numbered in the body of the document, they are +also numbered in the toc. Head numbering in the toc is NOT +concatenated as it is in the body of the document, which would be +visually redundant in a toc. +</p> + +<p> +Tocs are never set in columns, regardless of whether the rest of +the document is. Lastly, if +<a href="rectoverso.html#RECTO_VERSO">recto/verso</a> +printing is enabled, the toc respects it. This sometimes leads to +tocs that begin with the wrong margins, but the margins can be +corrected either by outputting a +<a href="#BLANK_PAGE">BLANKPAGE</a> +or by using the toc control macro +<a href="#TOC_RV_SWITCH">TOC_RV_SWITCH</a>. +</p> + +<p> +The overall toc +<a href="definitions.html#TERMS_FAMILY">family</a>, +<a href="definitions.html#TERMS_PS">point size</a> +and +<a href="definitions.html#TERMS_LEADING">lead</a> +can be altered with the toc +<a href="definitions.html#TERMS_CONTROLMACRO">control macros</a>, +as can the family, +<a href="definitions.html#TERMS_FONT">font</a>, +point size and indent of each type of toc entry (i.e. title, head, +subhead, paragraph head). Furthermore, the page numbering style +can be changed, as can the amount of visual space reserved for toc +entry page numbers. +</p> + +<a name="PSSELECT"><h4><u>Using psselect to put the table of contents where you want</u></h4></a> + +<p> +<strong>Mom</strong> always outputs tables of contents as the last +pages of any document. While this is desirable for some language +conventions — French, for example — it is not desirable +for others. +</p> + +<p> +If you'd like your tables of contents to be placed somewhere else, +you have two options: re-arrange the pages by hand (okay for one or +two hard copies of your document), or use the <strong>psselect</strong> +programme provided by the <strong>psutils</strong> suite of tools +(which you may have to install as a package from your distribution +if it is not already on your system). +</p> + +<p> +The procedure for using <strong>psselect</strong> begins by you +determining how many pages comprise the table of contents. You +can do this by previewing the document with a PostScript viewer, +say, <strong>gv</strong>. Once you know the number of pages in the +table of contents, use <strong>psselect</strong> to re-arrange them +appropriately. +</p> + +<p> +Say, for example, the table of contents runs to just one page. The +command to place the one-page table of contents at the start of the +document is: + +<pre> + psselect -p _1,1-_2 <PostScript file> > <new PostScript file> +</pre> +</p> + +<p> +The <kbd>-p</kbd> option instructs <strong>psselect</strong> that +what follows is a comma-separated list of the order in which +to re-arrange pages. The underscore character means "counting +backwards from the end of the document". Thus, the above says +"put the last page first (i.e. the table of contents), followed by +all pages from the original first page up to the second to last." +<strong>psselect</strong> outputs to stdout, so you have to redirect +the output to a new file. +</p> + +<p> +If your table of contents runs to two pages, the command would look +like this: + +<pre> + psselect -p _1-_2,1-_3 <PostScript file> > <new PostScript file> +</pre> +</p> + +<p> +If your table of contents runs to two pages and you have a cover +page that you would like to appear before the toc, the command would look +like this: + +<pre> + psselect -p 1,_1-_2,2-_3 <PostScript file> > <new PostScript file> +</pre> +</p> + +<!-- -TOC- --> + +<hr width="33%" align="left"/> + +<a name="TOC"></a> + +<p> +<a name="TOC">Macro: <strong>TOC</strong></a> +</p> + +<p> +If you want a toc, just put <strong>TOC</strong> as the last macro +in a document. <strong>Mom</strong> takes care of the rest. +</p> + +<hr width="66%" align="left"/> + +<a name="TOC_CONTROL"><h3><u>TOC control macros</u></h3></a> + +<p> +TOC control macros must be placed prior to invoking +<a href="docprocessing.html#START"><kbd>.START</kbd></a>. +</p> + +<p> +<strong>ERRATUM:</strong> In versions of <strong>mom</strong> prior to +1.3-e_3, the documentation stated that TOC control macros could go +anywhere in a <strong>mom</strong> file prior to invoking +<kbd>.TOC</kbd>. +That convenience has been removed for Very Good Reasons. +</p> + +<ol> + <li><a href="#TOC_GENERAL"><strong>General toc page style control</strong></a></li> + <ul> + <li><a href="#TOC_FAMILY">Base family for toc pages</a></li> + <li><a href="#TOC_PT_SIZE">Base point size for toc pages</a></li> + <li><a href="#TOC_LEAD">Leading of toc pages</a></li> + </ul> + <li><a href="#TOC_PAGENUMBERING"><strong>Toc page numbering</strong></a></li> + <ul> + <li><a href="#PAGINATE_TOC">Turn toc pagination on or off</a></li> + + <li><a href="#TOC_PAGENUM_STYLE">Toc page numbering style</a></li> + </ul> + <li><a href="#TOC_HEADER"><strong>Changing the toc header (title), string and style</strong></a></li> + <ul> + <li><a href="#TOC_HEADER_STRING">Changing the string (title)</a></li> + <li><a href="#TOC_HEADER_STYLE">Changing the string (title) style</a></li> + </ul> + <li><a href="#TOC_STYLE"><strong>Changing the style for toc entries</strong></a></li> + <ul> + <li><a href="#TOC_INDENT">The toc _INDENT control macros</a></li> + <li><a href="#TOC_TITLE">Changing the style for toc title entries</a></li> + <li><a href="#TOC_HEAD">Changing the style for toc head entries</a></li> + <li><a href="#TOC_SUBHEAD">Changing the style for toc subhead entries</a></li> + <li><a href="#TOC_PARAHEAD">Changing the style for toc paragraph head entries</a></li> + <li><a href="#TOC_PN">Changing the style for toc page number listings</a></li> + </ul> + <li><a href="#TOC_ADDITIONAL"><strong>Additional toc control macros</strong></a></li> + <ul> + <li><a href="#TOC_TITLE_ENTRY">Change the wording of a toc title entry</a></li> + <li><a href="#TOC_APPENDS_AUTHOR">Append author(s) to toc title entries</a></li> + <li><a href="#TOC_RV_SWITCH">TOC_RV_SWITCH</a></li> + <li><a href="#TOC_PADDING">TOC_PADDING</a></li> + </ul> +</ol> + +<hr width="66%" align="left"/> + +<a name="TOC_GENERAL"><h4><u>1. General toc page style control</u></h4></a> + +<a name="TOC_FAMILY"><h5>*<u>Toc family</u></h5></a> + +<p> +See +<a href="#CONTROL_MACRO_ARGS">Arguments to the control macros</a>. +</p> + +<p> +Set the family of toc pages with <strong>TOC_FAMILY</strong>, which +establishes the default family for every element of a toc page, +including the toc title ("Contents") and the page number +in the top or bottom margin. The default is the prevailing document +family. +</p> + +<p> +All elements on a toc page also have their own _FAMILY +control macros, which override the default set by +<strong>TOC_FAMILY</strong>. +</p> + +<!-- -TOC_PT_SIZE- --> + +<a name="TOC_PT_SIZE"><h5>*<u>Toc point size</u></h5></a> + +<p> +<nobr>Macro: <strong>TOC_PT_SIZE</strong> <kbd><base type size of the toc></kbd></nobr> +</p> + +<p> +Unlike most other control macros that deal with size of document +elements, <strong>TOC_PT_SIZE</strong> takes as its argument an +absolute value, relative to nothing. Therefore, the argument +represents the size of toc type in +<a href="definitions.html#TERMS_PICASPOINTS">points</a>, +unless you append an alternative +<a href="definitions.html#TERMS_UNITOFMEASURE">unit of measure</a>. +For example, + +<pre> + .TOC_PT_SIZE 12 +</pre> + +sets the base point size of type for the toc to 12 points, whereas + +<pre> + .TOC_PT_SIZE .6i +</pre> + +sets the base point size of type for the toc to 1/6 of an inch. +</p> + +<p> +The type size set with <strong>TOC_PT_SIZE</strong> forms the basis +from which the point size of other toc page elements are calculated. +</p> + +<p> +The default for +<a href="docprocessing.html#PRINTSTYLE">PRINTSTYLE TYPESET</a> +is 12.5 points (the same default size used in the body of the +document). +</p> + +<!-- -TOC_LEAD- --> + +<a name="TOC_LEAD"><h5>*<u>Toc lead</u></h5></a> + +<p> +<nobr>Macro: <strong>TOC_LEAD</strong> <kbd><leading of the toc> [ ADJUST ]</kbd></nobr> +<br/> + +<em>*Does not require a <a href="definitions.html#TERMS_UNITOFMEASURE">unit of measure</a>; points is assumed</em> +</p> + +<p> +Unlike most other control macros that deal with leading of document +elements, <strong>TOC_LEAD</strong> takes as its argument an +absolute value, relative to nothing. Therefore, the argument +represents the +<a href="definitions.html#TERMS_LEADING">leading</a> +of tocs in +<a href="definitions.html#TERMS_PICASPOINTS">points</a> +unless you append an alternative +<a href="definitions.html#TERMS_UNITOFMEASURE">unit of measure</a>. +For example, + +<pre> + .TOC_LEAD 14 +</pre> + +sets the base leading of type on the endnotes page to 14 +points, whereas + +<pre> + .TOC_LEAD .5i +</pre> + +sets the base leading of type on the endnotes page to 1/2 inch. +</p> + +<p> +If you want the leading of toc pages adjusted to fill the +page, pass <strong>TOC_LEAD</strong> 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 TYPESET</a> +is the prevailing document lead (16 by default), adjusted. +</p> + +<p> +<strong>NOTE:</strong> Even if you give <strong>mom</strong> +a <nobr><kbd>.DOC_LEAD_ADJUST OFF</kbd></nobr> command, she +will still, by default, adjust toc leading. You MUST enter +<nobr><kbd>TOC_LEAD <lead></kbd></nobr> with no +<kbd>ADJUST</kbd> argument to disable this default behaviour. +</p> + +<p> +<strong>ADDITIONAL NOTE:</strong> Tocs are always double-spaced in +<a href="docprocessing.html#PRINTSTYLE">PRINTSTYLE TYPEWRITE</a>, +regardless of whether the body of the document is single-spaced. +</p> + +<hr width="66%" align="left"/> + +<a name="TOC_PAGENUMBERING"><h4><u>2. Toc page numbering</u></h4></a> + +<p> +The page numbering of toc pages is controlled by the same macros +that control +<a href="headfootpage.html#PAGINATION">document page numbering</a>, +except +<a href="headfootpage.html#PAGENUM">PAGENUM</a> +(tocs always start on page 1). The defaults are the same as for the +rest of the document. +</p> + +<p> +If you wish to change some aspect of toc pagination, use +the document pagination control macros immediately prior to +<kbd>.TOC</kbd>. +</p> + +<p> +A special macro, +<a href="#TOC_PAGENUM_STYLE">TOC_PAGENUM_STYLE</a> +controls the style of toc pages page numbers. +</p> + +<!-- -PAGINATE_TOC- --> + +<hr width="33%" align="left"/> + +<a name="PAGINATE_TOC"></a> + +<p> +<nobr>Macro: <strong>PAGINATE_TOC</strong> <kbd><toggle></kbd></nobr> +</p> + +<p> +By default, <strong>mom</strong> paginates the toc. If you'd like +her not to, do + +<pre> + .PAGINATE_TOC OFF +</pre> +</p> + +<p> +<strong>NOTE:</strong> Simply invoking +<nobr><kbd>.PAGINATION OFF</kbd></nobr> +or +<nobr><kbd>.PAGINATE OFF</kbd></nobr> +disables toc pagination <em>for the first toc page only.</em> You +MUST use <kbd>.PAGINATE_TOC OFF</kbd> to disable toc pagination, +even if pagination is turned off elsewhere in your document. +</p> + +<!-- -TOC_PAGENUM_STYLE- --> + +<hr width="33%" align="left"/> + +<a name="TOC_PAGENUM_STYLE"></a> + +<p> +<nobr>Macro: <strong>TOC_PAGENUM_STYLE</strong> <kbd><DIGIT | ROMAN | roman | ALPHA | alpha></kbd></nobr> +</p> + +<p> +By default, <strong>mom</strong> uses roman numerals to number toc +pages. Use <strong>TOC_PAGENUM_STYLE</strong> if you'd prefer +something else. For example, to have standard digits instead of +roman numerals, do the following: + +<pre> + .TOC_PAGENUM_STYLE DIGIT +</pre> +</p> + +<hr width="66%" align="left"/> + +<a name="TOC_HEADER"><h4><u>3. Changing the toc header (title) string and style</u></h4></a> + +<p> +The toc header string is the title that appears at to top of the +toc. By default, it's "Contents". If you'd like +something else, say, "Table of Contents", do +</p> + +<p> +<a name="TOC_HEADER_STRING"></a> +<pre> + .TOC_HEADER_STRING "Table of Contents" +</pre> + +<a name="TOC_HEADER_STYLE"></a> +The style of the toc header (title) is managed by the usual control +macros (see +<a href="#CONTROL_MACRO_ARGS">arguments to the control macros</a>). +</p> + +<p> +<pre> + .TOC_HEADER_FAMILY default = prevailing doc family (Times Roman in TYPEWRITE) + .TOC_HEADER_FONT default = bold + .TOC_HEADER_SIZE default = +4 + .TOC_HEADER_QUAD default = left +</pre> + +<hr width="66%" align="left"/> + +<a name="TOC_STYLE"><h4><u>4. Changing the style for toc entries</u></h4></a> +</p> + +<p> +"Toc entries" refers to titles, heads, subheads and +paragraph heads as they appear in the toc. Their style is managed +by the usual +<a href="definitions.html#TERMS_CONTROLMACRO">control macros</a>, +starting with TOC_ +</p> + +<a name="TOC_INDENT"><h5>*<u>The table of contents _INDENT control macros</u></h5></a> + +<p> +The toc control macros that end in _INDENT all take a single +argument that requires a +<a href="definitions.html#TERMS_UNITOFMEASURE">unit of measure</a>. +The argument is the distance to indent the entry, always measured +from the left margin. For example, + +<pre> + .TOC_HEAD_INDENT 2P +</pre> + +indents head entries 2 +<a href="definitions.html#TERMS_PICASPOINTS">picas</a> +from the left margin. +</p> + +<a name="TOC_TITLE"><h5>*<u>Changing the style for toc title entries</u></h5></a> + +<p> +(See +<a href="#CONTROL_MACRO_ARGS">arguments to the control macros</a>). +</p> + +<p> +Toc title entries are the titles of documents that have been +<a href="rectoverso.html#COLLATE">collated</a> +together. +</p> + +<pre> + .TOC_TITLE_FAMILY default = prevailing doc family (Times Roman in TYPEWRITE) + .TOC_TITLE_FONT default = bold italic + .TOC_TITLE_SIZE default = +0 + .TOC_TITLE_INDENT default = 0 for TYPESET and TYPEWRITE +</pre> + +<a name="TOC_HEAD"><h5>*<u>Changing the style for toc head entries</u></h5></a> + +<p> +(See +<a href="#CONTROL_MACRO_ARGS">arguments to the control macros</a>). +</p> + +<p> +Toc head entries are main heads that appear in the body of a +document. +</p> + +<pre> + .TOC_HEAD_FAMILY default = prevailing doc family (Times Roman in TYPEWRITE) + .TOC_HEAD_FONT default = bold + .TOC_HEAD_SIZE default = +.5 + .TOC_HEAD_INDENT default = 18p for TYPESET; 2m for TYPEWRITE +</pre> + +<a name="TOC_SUBHEAD"><h5>*<u>Changing the style for toc subhead entries</u></h5></a> + +<p> +(See +<a href="#CONTROL_MACRO_ARGS">arguments to the control macros</a>). +</p> + +<p> +Toc subhead entries are subheads that appear in the body of a +document. +</p> + +<pre> + .TOC_SUBHEAD_FAMILY default = prevailing doc family (Times Roman in TYPEWRITE) + .TOC_SUBHEAD_FONT default = roman + .TOC_SUBHEAD_SIZE default = +0 + .TOC_SUBHEAD_INDENT default = 30p for TYPESET; 4m for TYPEWRITE +</pre> + +<a name="TOC_PARAHEAD"><h5>*<u>Changing the style for toc paragraph head entries</u></h5></a> + +<p> +(See +<a href="#CONTROL_MACRO_ARGS">arguments to the control macros</a>). +</p> + +<p> +Toc paragraph head entries are paragraph heads that appear in the +body of a document. +</p> + +<pre> + .TOC_PARAHEAD_FAMILY default = prevailing doc family (Times Roman in TYPEWRITE) + .TOC_PARAHEAD_FONT default = italic + .TOC_PARAHEAD_SIZE default = +0 + .TOC_PARAHEAD_INDENT default = 42p for TYPESET; 6m for TYPEWRITE +</pre> + +<a name="TOC_PN"><h5>*<u>Changing the style for toc paragraph page number listings</u></h5></a> + +<p> +(See +<a href="#CONTROL_MACRO_ARGS">arguments to the control macros</a>). +</p> + +<p> +Toc paragraph head entries are paragraph heads that appear in the +body of a document. +</p> + +<pre> + .TOC_PN_FAMILY default = prevailing doc family (Times Roman in TYPEWRITE) + .TOC_PN_FONT default = roman + .TOC_PN_SIZE default = +0 +</pre> + +<hr width="66%" align="left"/> + +<a name="TOC_ADDITIONAL"><h4><u>5. Additional toc macros</u></h4></a> + +<p> +The following macros allow you to switch page margins should +they be incorrect for recto/verso printing, to establish how +many placeholders to leave for page listings, and to have +<strong>mom</strong> append author(s) to toc title entries. +</p> + +<!-- -TOC_RV_SWITCH- --> + +<hr width="33%" align="left"/> + +<a name="TOC_RV_SWITCH"></a> + +<p> +Macro: <strong>TOC_RV_SWITCH</strong> +</p> + +<p> +<strong>TOC_RV_SWITCH</strong> doesn't take an argument. It simply +instructs <strong>mom</strong> to switch the left and right margins +of +<a href="rectoverso.html#RECTO_VERSO">recto/verso</a> +documents should the toc happen to begin on an even page when you +want an odd, or vice versa. +</p> + +<p> +The same result can be accomplished by outputting a +<a href="#BLANK_PAGE">BLANKPAGE</a>. +</p> + +<!-- -TOC_TITLE_ENTRY- --> + +<hr width="33%" align="left"/> + +<a name="TOC_TITLE_ENTRY"></a> + +<p> +<nobr>Macro: <strong>TOC_TITLE_ENTRY</strong> <kbd><"alternate wording for a title entry in the toc"></kbd></nobr> +</p> + +<p> +In +<a href="rectoverso.html#COLLATE">collated</a> +documents, the title of each separate document appears in the table +of contents. It may sometimes happen that you don't want the title +as it appears in the toc to be the same as what appears in +the +<a href="definitions.html#TERMS_DOCHEADER">docheader</a>. +You might, for example, want to shorten it. Or, in the case of +chapters where the docheader contains both a chapter number and a +chapter title, like this + +<pre> + Chapter 6 + Burning Bush — Maybe God Was Right +</pre> + +you might want only the chapter title, not the chapter number, to +show up in the toc. (By default, <strong>TOC</strong> generates +both.) +</p> + +<p> +If you want to change the wording of a title entry in the toc, +simply invoke <kbd>.TOC_TITLE_ENTRY</kbd> with the desired +wording, enclosed in double-quotes. Using the example, above, + +<pre> + .CHAPTER 6 + .CHAPTER_TITLE "Burning Bush — Maybe God Was Right" + .TOC_TITLE_ENTRY "Burning Bush" + .DOCTYPE CHAPTER +</pre> + +would identify chapter 6 in the toc simply as "Burning +Bush". +</p> + +<!-- -TOC_APPENDS_AUTHOR- --> + +<hr width="33%" align="left"/> + +<a name="TOC_APPENDS_AUTHOR"></a> + +<p> +<nobr>Macro: <strong>TOC_APPENDS_AUTHOR</strong> <kbd><none> | <"name(s) of authors"></kbd></nobr> +</p> + +<p> +In certain kinds of collated documents, different authors are +responsible for the articles or stories contained within them. In +such documents, you may wish to have the author or authors +appended to the toc's title entry for each story or article. +</p> + +<p> +If you invoke <kbd>.TOC_APPENDS_AUTHOR</kbd> with no argument, +<strong>mom</strong> appends the first argument you passed to +<a href="docprocessing.html#AUTHOR">AUTHOR</a> +to toc title entries, separated by a front-slash. +</p> + +<p> +If you invoke <kbd>.TOC_APPENDS_AUTHOR</kbd> with an argument +(surrounded by double-quotes), <strong>mom</strong> will append it +to the toc title entries instead. This is useful if you have +multiple authors you wish to identify by last name only. For +example, if three authors — Joe Blough, Jane Doe, and John +Deere — are responsible for a single article + +<pre> + .TOC_APPENDS_AUTHOR "Blough et al." +</pre> + +would be a good way to identify them in the toc. +</p> + +<!-- -TOC_PADDING- --> + +<hr width="33%" align="left"/> + +<a name="TOC_PADDING"></a> + +<p> +<nobr>Macro: <strong>TOC_PADDING</strong> <kbd><number of placeholders to allow for page number listings></kbd></nobr> +</p> + +<p> +By default, <strong>mom</strong> allows room for 3 digits in the +page number listings of tocs. If you'd like some other number of +placeholders, say 2, do + +<pre> + .TOC_PADDING 2 +</pre> +</p> + +<hr/> + +<!-- -PSPIC- --> + +<h2><u>Inserting images into a document — the PSPIC macro</u></h2> + +<a name="PSPIC"></a> + +<p> +<nobr>Macro: <strong>PSPIC</strong> <kbd>[ -L | -R | -I <n> ] <file> [ width [ height ] ]</kbd></nobr> +</p> + +<p> +You can insert images into a document by using the +<strong>PSPIC</strong> macro. <strong>PSPIC</strong> isn't +actually part of <strong>mom</strong>; it comes packaged with +<strong>groff</strong> itself. Use it whenever you want to insert +images into a <strong>mom</strong> document. The image must be +in PostScript format, either straight .ps or .eps (Encapsulated +PostScript). There have been reports of trouble with PostScript +level 2 images, so don't save your images in this format. +</p> + +<p> +<kbd>man groff_tmac</kbd> contains the documentation for +<strong>PSPIC</strong>, but I'll repeat it here with a few +modifications. +</p> + +<p> +---<em>From man groff_tmac</em>--- +<br/><br/> +<strong><kbd><file></kbd></strong> is the name of the file +containing the illustration; width and height give the desired width +and height of the graphic. The width and height arguments may have +<a href="definitions.html#TERMS_UNITOFMEASURE">units of measure</a> +attached; the default unit of measure is +<strong><kbd>i</kbd></strong>. This macro will scale the graphic +uniformly in the x and y directions so that it is no more than +width wide and height high. By default, the graphic will be +horizontally centered. The <strong><kbd>-L</kbd></strong> +and <strong><kbd>-R</kbd></strong> options cause the graphic +to be left-aligned and right-aligned, respectively. The +<strong><kbd>-I</kbd></strong> option causes the graphic to be +indented by <kbd><n></kbd> (default unit of measure is +"m"). +<br/><br/> +------------------------- +</p> + +<p> +Unless you're a PostScript whiz and have futzed around with +bounding boxes and whatnot, it'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#TERMS_RUNNING">running text</a> +will almost certainly disrupt the baseline placement of running +text. In order to get <strong>mom</strong> 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> + +<hr/> + +<p> +<a href="headfootpage.html#TOP">Next</a> +<a href="docprocessing.html#TOP">Prev</a> +<a href="#TOP">Top</a> +<a href="toc.html">Back to Table of Contents</a> +</p> + +</body> +</html> + +<!-- vim: fileencoding=latin1: nomodified: +--> diff --git a/contrib/mom/momdoc/docprocessing.html b/contrib/mom/momdoc/docprocessing.html new file mode 100644 index 00000000..1fb429e6 --- /dev/null +++ b/contrib/mom/momdoc/docprocessing.html @@ -0,0 +1,3365 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!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=iso-8859-1"/> +<title>Mom -- Document Processing, Introduction and Setup</title> +</head> +<body bgcolor="#dfdfdf"> + +<!-- ==================================================================== --> + +<a name="TOP"></a> + +<p> +<a href="typemacdoc.html#TOP">Next</a> +<a href="color.html#TOP">Prev</a> +<a href="toc.html">Back to Table of Contents</a> +</p> + +<a name="DOCPROCESSING"><h1 align="center"><u>Document processing with mom</u></h1></a> + +<p> +<a href="#INTRO_MACROS_DOCPROCESSING">Introduction to document processing</a> +<br/> + +<a href="#DEFAULTS">Some document defaults</a> +<br/> + +<a href="#LEADING_NOTE">***IMPORTANT NOTE on leading/spacing and bottom margins***</a> +<br/> + +<a href="#SHIM">The SHIM macro</a> +</p> + +<h2><u>Table of Contents for document processing</u></h2> + +<ul> + <li><a href="#SETUP"><strong>DOCUMENT SETUP</strong></a> + <br/> + <a href="#DOCPROCESSING_TUT">Tutorial — setting up a mom document</a> + </li> + <ul> + <li><a href="#REFERENCE_MACROS"><strong>The Reference Macros</strong></a></li> + <ul> + <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> + </ul> + <li><a href="#DOCSTYLE_MACROS"><strong>The Docstyle Macros</strong></a></li> + <ul> + <li><a href="#DOCTYPE">DOCTYPE</a></li> + <li><a href="#PRINTSTYLE">PRINTSTYLE</a></li> + <li><a href="#COPYSTYLE">COPYSTYLE</a></li> + </ul> + <li><a href="#START_MACRO"><strong>Initiate document processing</strong></a></li> + <ul> + <li><a href="#START">START</a></li> + </ul> + <li><a href="#STYLE_BEFORE_START"><strong>Changing global typesetting and formatting parameters before START</strong></a></li> + <ul> + <li><a href="#TYPE_BEFORE_START">Using the typesetting macros before START</a></li> + <ul> + <li><a href="docprocessing.html#INCLUDE">Including (sourcing) style sheets and files</a></li> + <li><a href="#COLOR">Initializing colours</a></li> + </ul> + <li><a href="#DOC_LEAD_ADJUST">DOC_LEAD_ADJUST — adjust a document's leading to fill pages</a></li> + <li><a href="#DOCHEADER">Managing the document header</a></li> + <ul> + <li><a href="#DOCHEADER">DOCHEADER — turning docheaders off</a></li> + <li><a href="#DOCHEADER_CONTROL">Docheader control</a></li> + </ul> + </ul> + <li><a href="#COLUMNS_INTRO"><strong>Setting documents in columns</strong></a></li> + <ul> + <li><a href="#COLUMNS">COLUMNS</a></li> + <li><a href="#BREAKING_COLUMNS">Breaking columns manually</a></li> + <ul> + <li><a href="#COL_NEXT">COL_NEXT</a></li> + <li><a href="#COL_BREAK">COL_BREAK</a></li> + </ul> + </ul> + <li><a href="#DOC_PARAM_MACROS"><strong>Changing global style parameters after START</strong></a></li> + <ul> + <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><a href="typemacdoc.html#TYPESETTING"><strong>Using the typesetting macros during document processing</strong></a></li> + <li><a href="docelement.html#DOCELEMENT"><strong>THE DOCUMENT ELEMENT TAGS</strong></a></li> + <ul> + <li><a href="docelement.html#DOCELEMENT_INTRO">Introduction to the document element tags</a></li> + <ul> + <li><a href="docelement.html#DOCELEMENT_CONTROL">Document element (tag) control macros</a></li> + <li><a href="docelement.html#CONTROL_MACRO_ARGS">Arguments to the control macros</a></li> + </ul> + <li><a href="docelement.html#EPIGRAPH_INTRO"><strong>Epigraphs</strong></a></li> + <ul> + <li><a href="docelement.html#EPIGRAPH">EPIGRAPH</a></li> + <li><a href="docelement.html#EPIGRAPH_CONTROL">Epigrah control</a></li> + </ul> + <li><a href="docelement.html#PP_INTRO"><strong>Paragraphs</strong></a></li> + <ul> + <li><a href="docelement.html#PP">PP</a></li> + <li><a href="docelement.html#PP_CONTROL">Paragraph control</a></li> + </ul> + <li><a href="docelement.html#HEAD_INTRO"><strong>Main heads</strong></a></li> + <ul> + <li><a href="docelement.html#HEAD">HEAD</a></li> + <li><a href="docelement.html#HEAD_CONTROL">Head control</a></li> + </ul> + <li><a href="docelement.html#SUBHEAD_INTRO"><strong>Subheads</strong></a></li> + <ul> + <li><a href="docelement.html#SUBHEAD">SUBHEAD</a></li> + <li><a href="docelement.html#SUBHEAD_CONTROL">Subhead control</a></li> + </ul> + <li><a href="docelement.html#PARAHEAD_INTRO"><strong>Paragraph heads</strong></a></li> + <ul> + <li><a href="docelement.html#PARAHEAD">PARAHEAD</a></li> + <li><a href="docelement.html#PARAHEAD_CONTROL">Parahead control</a></li> + </ul> + <li><a href="docelement.html#LINEBREAK_INTRO"><strong>Linebreaks (author linebreaks, also called section breaks)</strong></a></li> + <ul> + <li><a href="docelement.html#LINEBREAK">LINEBREAK</a></li> + <li><a href="docelement.html#LINEBREAK_CONTROL">Linebreak control</a></li> + </ul> + <li><a href="docelement.html#QUOTE_INTRO"><strong>Quotes (line for line poetic quotes or code snippets)</strong></a></li> + <ul> + <li><a href="docelement.html#QUOTE">QUOTE</a></li> + <li><a href="docelement.html#QUOTE_CONTROL">Quote control</a></li> + </ul> + <li><a href="docelement.html#BLOCKQUOTE_INTRO"><strong>Blockquotes (cited material)</strong></a></li> + <ul> + <li><a href="docelement.html#BLOCKQUOTE">BLOCKQUOTE</a></li> + <li><a href="docelement.html#BLOCKQUOTE_CONTROL">Blockquote control</a></li> + </ul> + <li><a href="docelement.html#FOOTNOTE_INTRO"><strong>Footnotes</strong></a></li> + <ul> + <li><a href="docelement.html#FOOTNOTE">FOOTNOTE</a></li> + <li><a href="docelement.html#FOOTNOTE_CONTROL">Footnote control</a></li> + </ul> + <li><a href="docelement.html#ENDNOTE_INTRO"><strong>Endnotes</strong></a></li> + <ul> + <li><a href="docelement.html#ENDNOTE">ENDNOTE</a></li> + <li><a href="docelement.html#ENDNOTE_CONTROL">Endnote control</a></li> + </ul> + <li><a href="docelement.html#FINIS_INTRO"><strong>Document termination string</strong></a></li> + <ul> + <li><a href="docelement.html#FINIS">FINIS</a></li> + <li><a href="docelement.html#FINIS_CONTROL">Finis control</a></li> + </ul> + </ul> + <li><a href="headfootpage.html#HEADFOOTPAGE"><strong>HEADERS and FOOTERS</strong></a></li> + <ul> + <li><a href="headfootpage.html#HEADFOOTPAGE_INTRO">Introduction to headers/footers</a></li> + <li><a href="headfootpage.html#HEADFOOT_MANAGEMENT">Managing headers/footers</a></li> + <ul> + <li><a href="headfootpage.html#HEADERS">HEADERS</a> — on or off</li> + <li><a href="headfootpage.html#FOOTERS">FOOTERS</a> — on or off</li> + <li><a href="headfootpage.html#FOOTER_ON_FIRST_PAGE">FOOTER_ON_FIRST_PAGE</a></li> + </ul> + <li><a href="headfootpage.html#HEADFOOT_CONTROL">Header/footer control</a></li> + <ul> + <li><a href="headfootpage.html#HDRFTR_STRINGS">Header/footer strings</a></li> + <li><a href="headfootpage.html#HDRFTR_STYLE">Header/footer style</a> — global and part-by-part</li> + <li><a href="headfootpage.html#HDRFTR_VERTICAL">Header/footer placement and spacing</a></li> + <li><a href="headfootpage.html#HDRFTR_SEPARATOR">The header/footer separator rule</a></li> + </ul> + </ul> + <li><a href="headfootpage.html#PAGINATION"><strong>PAGINATION</strong></a></li> + <ul> + <li><a href="headfootpage.html#PAGINATE">PAGINATE</a> — on or off</li> + <li><a href="headfootpage.html#PAGENUMBER">PAGENUMBER</a> — user supplied page number</li> + <li><a href="headfootpage.html#PAGENUM_STYLE">PAGENUM_STYLE</a> — digits, roman numerals, etc.</li> + <li><a href="headfootpage.html#DRAFT_WITH_PAGENUMBER">DRAFT_WITH_PAGENUMBER</a> — attach draft/revision information to page numbers</li> + <li><a href="headfootpage.html#PAGINATE_CONTROL">Pagination control</a></li> + </ul> + <li><a href="rectoverso.html#RECTOVERSO"><strong>RECTO_VERSO PRINTING and COLLATING</strong></a></li> + <ul> + <li><a href="rectoverso.html#RECTOVERSO_INTRO">Introduction to recto/verso</a></li> + <ul> + <li><a href="rectoverso.html#RECTO_VERSO">RECTO_VERSO</a></li> + <li><a href="rectoverso.html#SWITCH_HDRFTR">SWITCH_HEADERS</a> (also FOOTERS)</li> + </ul> + <li><a href="rectoverso.html#COLLATE_INTRO">Introduction to collating</a></li> + <ul> + <li><a href="rectoverso.html#COLLATE">COLLATE</a></li> + </ul> + </ul> + <li><a href="cover.html#TOP"><strong>CREATING A COVER PAGE</strong></a></li> + <li><a href="letters.html#LETTERS"><strong>WRITING LETTERS</strong></a></li> + <ul> + <li><a href="letters.html#LETTERS_INTRO">Introduction to writing letters</a></li> + <li><a href="letters.html#TUTORIAL">Tutorial on writing letters</a></li> + <li><a href="letters.html#LETTERS_DEFAULTS">Default style for letters</a></li> + <li><a href="letters.html#LETTERS_MACROS">The letter macros</a></li> + </ul> + </ul> +</ul> + +<hr/> + +<!-- ==================================================================== --> + +<h2><a name="INTRO_MACROS_DOCPROCESSING"><u>Introduction to document processing</u></a></h2> + +<p> +As explained in +<a href="intro.html#INTRO_DOCPROCESSING">Document processing with mom</a>, +document processing 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't forget: if you don't like the +"official" name of a tag — too long, cumbersome +to type in, not "intuitive" enough — you can change it +with the +<a href="goodies.html#ALIAS">ALIAS</a> +macro.) +</p> + +<p> +In addition to the tags themselves, <strong>mom</strong> has an +extensive array of macros that control how they look and behave. +</p> + +<p> +Setting up a <strong>mom</strong> doc is a simple, four-part procedure. +You begin by entering information about the document itself (title, +subtitle, author, etc.). Next, you tell <strong>mom</strong> what +kind of document you'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 +<strong>mom</strong>'s default behaviour as you wish. Lastly, you +invoke the +<a href="#START">START</a> +macro. Voilą! You're ready to write. +</p> + +<!-- ==================================================================== --> + +<hr align="left" width="66%"/> + +<h2><a name="DEFAULTS"><u>Some document defaults</u></a></h2> + +<p> +As is to be expected, <strong>mom</strong> 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. Just in case, here they are. + +<ul> + <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 <nobr>( e.g. -6- )</nobr> + </li> + <li>the first page of a document begins with a + <a href="definitions.html#TERMS_DOCHEADER">document header</a> + </li> + <li>subsequent pages have + <a href="definitions.html#TERMS_HEADER">page headers</a> + with a rule underneath + </li> +</ul> +</p> + +<p> +Another way to check up on document processing defaults is to have +a look at the macro file (om.tmac). Each macro is preceded by a +description that (generally) says what its default is (if it has +one). +</p> + +<!-- ==================================================================== --> + +<hr align="left" width="66%"/> + +<a name="LEADING_NOTE"><h2><u>IMPORTANT NOTE on leading/spacing and bottom margins</u></h2></a> + +<p> +<strong>Mom</strong> takes evenly-aligned bottom margins in +<a href="definitions.html#TERMS_RUNNING">running text</a> +very seriously. Only under a very few (exceptional) circumstances +will she allow a bottom margin to "hang" (i.e. to fall +short). +</p> + +<p> +In order to ensure even bottom margins, <strong>mom</strong> +uses the "base" document +<a href="definitions.html#TERMS_LEADING">leading</a> +in effect <em>at the start of running text on each page</em> (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#TERMS_CONTROLMACRO">control macro</a> +<a href="#DOC_LEAD">DOC_LEAD</a>. +</p> + +<p> +Because <strong>mom</strong> 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'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's a question of adding or subtracting full line spaces between +or within document elements, you can do so by using the "v" +<a href="definitions.html#TERMS_UNITOFMEASURE">unit of measure</a> +with whatever spacing macro you choose — +<a href="typesetting.html#ALD">ALD</a>, +<a href="typesetting.html#RLD">RLD</a>, +<a href="typesetting.html#SPACE">SPACE</a> +— and <strong>mom</strong> won't object. "v" means +"the current leading", so she isn't confused by it. And +since "v" accepts decimal fractions, you can add/subtract +half linespaces and quarter linespaces with "v" as well, +<em>provided you compensate for the fractional linespace somewhere +else on the page</em>. +</p> + +<p> +If all this seems like too much work, <strong>mom</strong> +provides a special macro to get you out of trouble if you've played +around with leading and/or spacing. The macro is called +<strong>SHIM</strong> (like those little pieces of wood carpenters +use to get their work even, level and snug), and it's described +below. +</p> + +<!-- -SHIM- --> + +<hr width="33%" align="left"/> + +<a name="SHIM"></a> + +<p> +<nobr>Macro: <strong>SHIM</strong></nobr> +</p> + +<p> +<strong>SHIM</strong> doesn't take any argument. Use it whenever +you've played around with the +<a href="definitions.html#TERMS_LEADING">leading</a> +or spacing on a page and you +need to get <strong>mom</strong>'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, <strong>PSPIC</strong> (see <kbd>man +groff_tmac</kbd> for usage). +</p> + +<p> +Pictures aren't usually conveniently sized in multiples of document +leading, which means that when you insert the picture, you disrupt +<strong>mom</strong>'s ordered placement of baselines on the page. +This will certainly result in a bottom margin that doesn't match the +bottom margins of your document's other pages. +</p> + +<p> +The solution is to insert <strong>SHIM</strong> after the picture, +like this: + +<pre> + <some lines of text> + .PSPIC <full path to picture> + .SHIM + <more lines of text> +</pre> +</p> + +<p> +<strong>SHIM</strong> instructs <strong>mom</strong> 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#TERMS_OUTPUTLINE">output line</a> +falls where <strong>mom</strong> 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't centre nicely between the lines of text, you can always do + +<pre> + <some lines of text> + .RLD 3p + .PSPIC <full path to picture> + .SHIM + <more lines of text> +</pre> + +to raise the picture slightly +(<strong>R</strong>everse <strong>L</strong>ea<strong>D</strong> +3 points; see +<a href="typesetting.html#RLD">RLD</a>), +and still have <strong>SHIM</strong> ensure that text underneath +falls exactly where it's supposed to. +</p> + +<p> +<strong>NOTE:</strong> For information on disabling the automatic +shimming of quotes and blockquotes during document processing, see +<a href="docelement.html#NO_SHIM">here</a>. +</p> + +<hr/> + +<!-- ==================================================================== --> + +<a name="SETUP"><h2><u>Document setup</u></h2></a> + +<a name="DOCPROCESSING_TUT"><h3><u>Tutorial — setting up a mom document</u></h3></a> + +<p> +There are four "parts" to setting up a +<strong>mom</strong> doc (three, actually, with one optional). +Before we proceed, though, be reassured that something as simple as + +<pre> + .TITLE "By the Shores of Lake Attica" + .AUTHOR "Rosemary Winspeare" + .PRINTSTYLE TYPESET + .START +</pre> + +produces a beautifully typeset 8.5x11 document, with a +<a href="definitions.html#TERMS_DOCHEADER">docheader</a> +at the top of page 1, +<a href="definitions.html#TERMS_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're going to set up a short +story — <em>My Pulitzer Winner</em> by Joe Blow. Thankfully, +we don't have to look at story itself, just the setup. +Joe wants the document + +<ul> + <li>to be draft 7, revision 39;</li> + <li>to use the "default" style of document formatting:</li> + <li>to print as draft-style output (instead of "final" copy output);</li> + <li>to be typeset, in Helvetica, 12 on 14, + <a href="definitions.html#TERMS_RAG">rag-right</a>; + </li> + <li>to have <a href="definitions.html#TERMS_FOOTER">footers</a> + instead of + <a href="definitions.html#TERMS_HEADER">headers</a>; + </li> + <li>to use a single asterisk for + <a href="definitions.html#TERMS_LINEBREAK">author linebreaks</a>. + </li> +</ul> +</p> + +<p> +Joe Blow has no taste in typography. His draft won't look pretty, +but this is, after all, a tutorial; we're after examples, not beauty. +</p> + +<h4><u>Step 1</u></h4> + +<p> +The first step in setting up any document is giving <strong>mom</strong> +some reference information. The reference macros are: + +<ul> + <li>TITLE</li> + <li>DOCTITLE</li> + <li>COVERTITLE</li> + <li>SUBTITLE</li> + <li>AUTHOR</li> + <li>CHAPTER — the chapter number</li> + <li>DRAFT — the draft number</li> + <li>REVISION — the revision number</li> + <li>COPYRIGHT — only used on cover pages</li> + <li>MISC — only used on cover pages</li> + <li>COVER_TITLE — only on cover pages; only if needed</li> + <li>DOC_COVER_TITLE — only on document cover pages; only if needed</li> +</ul> +</p> + +<p> +You can use as many or as few as you wish, although at a minimum, +you'll probably fill in <strong>TITLE</strong> (unless the document's +a letter) and <strong>AUTHOR</strong>. Order doesn't matter. +You can separate the +<a href="definitions.html#TERMS_ARGUMENTS">arguments</a> +from the macros by any number of spaces. The following are +what you'd need to start Joe Blow's story. + +<pre> + .TITLE "My Pulitzer Winner" + .AUTHOR "Joe Blow" + .DRAFT 7 + .REVISION 39 +</pre> +</p> + +<h4><u>Step 2</u></h4> + +<p> +Once you've given <strong>mom</strong> 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? +<strong>Mom</strong> calls the macros that answer these questions +"the docstyle macros." They are: + +<ul> + <li>DOCTYPE — the type of document (default, chapter, user-defined, letter)</li> + <li>PRINTSTYLE — typeset or typewritten</li> + <li>COPYSTYLE — draft or final copy</li> +</ul> +</p> + +<p> +<strong>Mom</strong> has defaults for <strong>DOCTYPE</strong> +and <strong>COPYSTYLE</strong>; if they're what you want, you +don't need to include them here. However, <strong>PRINTSTYLE</strong> +has no default and MUST be present in every formatted document. +If you omit it, <strong>mom</strong> won't process the document AND +she'll complain (both to stderr and as a single printed sheet with +a warning). Moms — they can be so annoying sometimes. <sigh> +</p> + +<p> +Adding to what we already have, the next bit of setup for Joe +Blow's story looks like this: + +<pre> + .TITLE "My Pulitzer Winner" + .AUTHOR "Joe Blow" + .DRAFT 7 + .REVISION 39 + \# + .DOCTYPE DEFAULT \"Superfluous; mom uses DOCTYPE DEFAULT by default + .PRINTSTYLE TYPESET + .COPYSTYLE DRAFT +</pre> +</p> + +<p> +Notice the use of the +<a href="definitions.html#TERMS_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><u>Step 3</u></h4> + +<p> +This step — completely optional — is where you, the user, take +charge. <strong>Mom</strong> has defaults for <em>everything</em>, +but who's ever satisfied with defaults? Use any of the <a +href="typesetting.html#MACROS_TYPESETTING">typesetting macros</a> +here to change <strong>mom</strong>'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 +"style-sheet " section of a document. And please note: +you MUST give <strong>mom</strong> a +<a href="#PRINTSTYLE">PRINTSTYLE</a> +directive <strong>before</strong> making any such changes. +</p> + +<p> +Joe Blow wants his story printed in Helvetica, 12 on 14, rag +right, with +<a href="definitions.html#TERMS_FOOTER">page footers</a> +instead of +<a href="definitions.html#TERMS_HEADER">page headers</a> +and a single asterisk for the +<a href="definitions.html#TERMS_LINEBREAK">linebreak</a> +character. None of these requirements conforms +to <strong>mom</strong>'s defaults for the chosen +<strong>PRINTSTYLE</strong> (TYPESET), so we change them here. +The setup for Joe Blow's story now looks like this: + +<pre> + .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 * +</pre> +</p> + +<h4><u>Step 4</u></h4> + +<p> +The final step in setting up a document is telling +<strong>mom</strong> to start document processing. It's a +no-brainer, just the single macro <strong>START</strong>. Other +than <strong>PRINTSTYLE</strong>, it's the only macro required for +document processing (although I can't guarantee you'll like the +results of using just the two). +</p> + +<p> +Here's the complete setup for <em>My Pulitzer Winner</em>: + +<pre> + .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 +</pre> +</p> + +<p> +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: + +<pre> + .TITLE "My Pulitzer Winner" + .AUTHOR "Joe Blow" + .DRAFT 7 + .REVISION 39 + \# + .PRINTSTYLE TYPEWRITE + .COPYSTYLE DRAFT + \# + .START +</pre> +</p> + +<p> +<kbd>.PRINTSTYLE TYPEWRITE</kbd>, above, means that Joe's work +will come out "typewritten, double-spaced", 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: + +<pre> + .TITLE "My Pulitzer Winner" + .AUTHOR "Joe Blow" + .DRAFT 7 + .REVISION 39 + \# + .PRINTSTYLE TYPESET \"first change + .COPYSTYLE FINAL \"second change + \# + .START +</pre> +</p> + +<p> +In the above, <kbd>.DRAFT 7, .REVISION 39,</kbd> and <kbd>.COPYSTYLE +FINAL</kbd> are actually superfluous. The draft and revision +numbers aren't used when <strong>COPYSTYLE</strong> is +<strong>FINAL</strong>, and <strong>COPYSTYLE FINAL</strong> is +<strong>mom</strong>'s default unless you tell her otherwise. +BUT... to judge from the number of drafts already, J. Blow may very +well decide his "final" version still isn'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'll be ready to +tackle his Pulitzer winner again. +</p> + +<hr/> + +<!-- ======================================================================== --> + +<a name="REFERENCE_MACROS"><h2><u>The Reference Macros</u></h2></a> + +<p> +The reference macros give <strong>mom</strong> the information +she needs to generate +<a href="definitions.html#TERMS_DOCHEADER">docheaders</a>, +<a href="definitions.html#TERMS_HEADER">page headers</a>, +and +<a href="cover.html#COVER_TOP">covers</a>. +They must go at the top of any file that uses <strong>mom</strong>'s +document processing macros. +</p> + +<a name="INDEX_REFERENCE"><h3><u>Reference macros list</u></h3></a> + +<ul> + <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> +</ul> + +<!-- -TITLE- --> + +<hr width="66%" align="left"/> + +<a name="TITLE"></a> + +<p> +<nobr>Macro: <strong>TITLE</strong> <kbd>"<title string>" ["<2nd line>" ["<3rd line>" ... ] ]</kbd></nobr> +<br/> + +<em>*Arguments must be enclosed in double-quotes</em> +</p> + +<p> +The title string can be caps or caps/lower-case; it's up to you. In +<a href="#PRINTSTYLE">PRINTSTYLE TYPESET</a>, +the title will appear in the +<a href="definitions.html#TERMS_DOCHEADER">docheader</a> +exactly as you typed it. However, <strong>mom</strong> converts +the title to all caps in +<a href="definitions.html#TERMS_HEADER">page headers</a> +unless you turn that feature off (see +<a href="headfootpage.html#_CAPS">HEADER_<POSITION>_CAPS</a>). +In +<a href="#PRINTSTYLE">PRINTSTYLE TYPEWRITE</a>, +the title always gets converted to caps. +</p> + +<p> +<strong>TITLE</strong> 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> + +<p> +<strong>NOTE:</strong> If your +<a href="#DOCTYPE">DOCTYPE</a> +is <strong>CHAPTER</strong>, <strong>TITLE</strong> should be the +title of the opus, not "CHAPTER whatever". +</p> + +<!-- -DOCTITLE- --> + +<hr width="33%" align="left"/> + +<a name="DOC_TITLE"></a> + +<p> +<nobr>Macro: <strong>DOCTITLE</strong> <kbd>"<overall document title>" ["<2nd line>" ["<3rd line>" ... ] ]</kbd></nobr> +<br/> + +<em>*Arguments must be enclosed in double-quotes</em> +</p> + +<p> +<strong>NOTE:</strong> This macro should be used only if your +<a href="#DOCTYPE">DOCTYPE</a> +is <strong>DEFAULT</strong> (which is <strong>mom</strong>'s +default). If your <strong>DOCTYPE</strong> is +<strong>CHAPTER</strong>, use +<a href="#TITLE">TITLE</a> +to set the overall document title for cover pages, document cover +pages, and page headers or footers. +</p> + +<p> +When you'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'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 <strong>DOCTITLE</strong>. +</p> + +<p> +<strong>DOCTITLE</strong> tells <strong>mom</strong> 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'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#TERMS_HEADER">page headers</a>, +all in caps unless you turn that feature off (see +<a href="headfootpage.html#_CAPS">HEADER_<POSITION>_CAPS</a>). +In +<a href="#PRINTSTYLE">PRINTSTYLE TYPEWRITE</a>, +the doctitle always gets converted to caps. +</p> + +<p> +<strong>DOCTITLE</strong> 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> + +<p> +<strong>NOTE:</strong> If your +<a href="#DOCTYPE">DOCTYPE</a> +is <strong>CHAPTER</strong>, you don't need +<strong>DOCTITLE</strong>. <strong>TITLE</strong> takes care of +everything. +</p> + +<!-- -SUBTITLE- --> + +<hr width="33%" align="left"/> + +<a name="SUBTITLE"></a> + +<p> +<nobr>Macro: <strong>SUBTITLE</strong> <kbd>[COVER | DOC_COVER] "<subtitle>" ["<2nd line>" ["<3rd line>" ... ] ]</kbd></nobr> +<br/> + +<em>*String arguments must be enclosed in double-quotes</em> +</p> + +<p> +The subtitle string can be caps or caps/lower-case. I recommend +caps/lower case. +</p> + +<p> +<strong>SUBTITLE</strong> 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 <strong>SUBTITLE</strong>, 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 "document +covers" and "covers"). Thus, it is possible to have +differing subtitles appear on the document cover, the cover +("title") page, and in the document header. An extreme +example would be: + +<pre> + .SUBTITLE "The Docheader Subtitle" + .SUBTITLE DOC_COVER "The Document Cover Subtitle" + .SUBTITLE COVER "The Cover Subtitle" +</pre> + +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 ("title") page. +</p> + +<p> +If you don'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 "SUBTITLE" 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- --> + +<hr width="33%" align="left"/> + +<a name="AUTHOR"></a> + +<p> +<nobr>Macro: <strong>AUTHOR</strong> <kbd>[COVER | DOC_COVER] "<author>" [ "<author2>" ["<author3>" ... ] ]</kbd></nobr> +<br/> + +Alias: <strong>EDITOR</strong> +<br/> + +<em>*String arguments must be enclosed in double-quotes</em> +</p> + +<p> +Each author string can hold as many names as you like, e.g. + +<pre> + .AUTHOR "Joe Blow" + or + .AUTHOR "Joe Blow, Jane Doe" "John Hancock" +</pre> +</p> + +<p> +<strong>Mom</strong> prints each string that's enclosed in +double-quotes on a separate line in the +<a href="definitions.html#TERMS_DOCHEADER">docheader</a>, +however only the first string appears in +<a href="definitions.html#TERMS_HEADER">page headers</a>. +If you want <strong>mom</strong> to put something else in the author +part of page headers (say, just the last names of a document'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 <strong>AUTHOR</strong>, 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 "document +covers" and "covers"). Thus, it is possible to have +differing authors on the document cover, the cover +("title") page, in the document first-page header and +subsequent page headers/footers. An example might be: + +<pre> + .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)" +</pre> + +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 ("title") page. +</p> + +<p> +If you don'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 "AUTHOR" 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- --> + +<hr width="33%" align="left"/> + +<a name="CHAPTER"></a> + +<p> +<nobr>Macro: <strong>CHAPTER</strong> <kbd><chapter number></kbd></nobr> +</p> + +<p> +The chapter number can be in any form you like — a digit, a roman +numeral, a word. If you choose +<a href="#DOCTYPE">DOCTYPE CHAPTER</a>, +<strong>mom</strong> prints whatever argument you pass +<strong>CHAPTER</strong> beside the word "Chapter" as a +single line +<a href="definitions.html#TERMS_DOCHEADER">docheader</a>. +She also puts the same thing in the middle of +<a href="definitions.html#TERMS_HEADER">page headers</a>. +</p> + +<p> +Please note that if your argument to <strong>CHAPTER</strong> runs +to more than one word, you must enclose the argument in +double-quotes. +</p> + +<p> +If you're not using <strong>DOCTYPE CHAPTER</strong>, the macro can +be used to identify any document as a chapter <em>for the purpose of +prepending a chapter number to numbered head elements</em>, provided +you pass it a +<a href="definitions.html#TERMS_NUMERICARGUMENT">numeric argument</a>. +See +<a href="docelement.html#PREFIX_CHAPTER_NUMBER">PREFIX_CHAPTER_NUMBER</a>. +</p> + +<!-- -CHAPTER_STRING- --> + +<a name="CHAPTER_STRING"><h4><u>The chapter string</u></h4></a> + +<p> +If you're not writing in English, you can ask <strong>mom</strong> +to use the word for "chapter" in your own language by +telling her what it is with the <strong>CHAPTER_STRING</strong> +macro, like this: + +<pre> + .CHAPTER_STRING "Chapītre" +</pre> +</p> + +<p> +You can also use <strong>CHAPTER_STRING</strong> if you want +"CHAPTER" instead of "Chapter" in the doc-and +page-headers. +</p> + +<!-- -CHAPTER_TITLE- --> + +<hr width="33%" align="left"/> + +<a name="CHAPTER_TITLE"></a> + +<p> +<nobr>Macro: <strong>CHAPTER_TITLE</strong> "<chapter title>" ["<2nd line>" ["<3rd line>" ... ] ]</nobr> +<br/> + +<em>*Arguments must be enclosed in double-quotes</em> +</p> + +<p> +If, either in addition to or instead of "Chapter +<n>" appearing at the top of chapters, you want your +chapter to have a title, use <strong>CHAPTER_TITLE</strong>, with +your title enclosed in double-quotes, like this: + +<pre> + .CHAPTER_TITLE "The DMCA Nazis" +</pre> +</p> + +<p> +<strong>CHAPTER_TITLE</strong> 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've used +<a href="#CHAPTER">CHAPTER</a> +to give the chapter a number, both "Chapter <n>" and +the chapter title will appear at the top of the chapter, like this: + +<pre> + Chapter 1 + The DMCA Nazis +</pre> +</p> + +<p> +In such a case, by default, only the chapter's title will appear in +the +<a href="definitions.html#TERMS_HEADER">page headers</a>, +not "Chapter <n>". +</p> + +<p> +If you omit <strong>CHAPTER</strong> 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. <strong>CHAPTER_TITLE_FAMILY</strong>, +<strong>CHAPTER_TITLE_FONT</strong>, etc. The default family, +font and point size are Times Roman, Bold Italic, 4 points larger +than +<a href="definitions.html#TERMS_RUNNING">running text</a>. +</p> + +<!-- -DRAFT- --> + +<hr width="33%" align="left"/> + +<a name="DRAFT"></a> + +<p> +<nobr>Macro: <strong>DRAFT</strong> <kbd><draft number></kbd></nobr> +</p> + +<p> +<strong>DRAFT</strong> only gets used with +<a href="#COPYSTYLE">COPYSTYLE DRAFT</a>. +If the <strong>COPYSTYLE</strong> is <strong>FINAL</strong> (the +default), <strong>mom</strong> ignores <strong>DRAFT</strong>. +<strong>DRAFT</strong> accepts both alphabetic and numeric +arguments, hence it's possible to do either + +<pre> + .DRAFT 2 + or + .DRAFT Two +</pre> +</p> + +<p> +<strong>Mom</strong> prints the argument to <kbd>.DRAFT</kbd> (i.e. +the draft number) beside the word "Draft" in the middle +part of +<a href="definitions.html#TERMS_HEADER">page headers</a>. +</p> + +<p> +<strong>A small word of caution:</strong> If your argument to +<kbd>.DRAFT</kbd> is more than one word long, you must enclose the +argument in double-quotes. +</p> + +<p> +You may, if you wish, invoke <kbd>.DRAFT</kbd> without an +argument, in which case, no draft number will be printed beside +"Draft" in headers or footers. +</p> + +<!-- -DRAFT_STRING- --> + +<a name="DRAFT_STRING"><h4><u>The draft string</u></h4></a> + +<p> +If you're not writing in English, you can ask <strong>mom</strong> +to use the word for "draft" in your own language by +telling her what it is with the <strong>DRAFT_STRING</strong> macro, +like this: + +<pre> + .DRAFT_STRING "Jet" +</pre> +</p> + +<p> +Equally, <strong>DRAFT_STRING</strong> can be used to roll your own +solution to something other than the word "Draft." For +example, you might want "Trial run alpha-three" to appear +in the headers of a draft version. You'd accomplish this by doing + +<pre> + .DRAFT alpha-three + .DRAFT_STRING "Trial run +</pre> +</p> + +<p> +<kbd>.DRAFT</kbd> without an argument, above, ensures that only the +<strong>DRAFT_STRING</strong> gets printed. +</p> + +<p> +<strong>NOTE:</strong> If you define both a blank <kbd>.DRAFT</kbd> +and a blank <kbd>.DRAFT_STRING</kbd>, <strong>mom</strong> skips the +draft field in headers entirely. If this is what you want, this is +also the only way to do it. Simply omitting a <kbd>.DRAFT</kbd> and +<kbd>.DRAFT_STRING</kbd> will result in <strong>mom</strong> using +her default, which is to print "Draft <number>". +</p> + +<!-- -REVISION- --> + +<hr width="33%" align="left"/> + +<a name="REVISION"></a> + +<p> +<nobr>Macro: <strong>REVISION</strong> <kbd><revision number></kbd></nobr> +</p> + +<p> +<strong>REVISION</strong> only gets used with +<a href="#COPYSTYLE">COPYSTYLE DRAFT</a>. +If the <strong>COPYSTYLE</strong> is <strong>FINAL</strong> +(the default), <strong>mom</strong> ignores the +<strong>REVISION</strong> macro. <strong>REVISION</strong> accepts +both alphabetic and numeric arguments, hence it's possible to do +either + +<pre> + .REVISION 2 + or + .REVISION Two +</pre> +</p> + +<p> +<strong>Mom</strong> prints the revision number beside the shortform +"Rev." in the middle part of +<a href="definitions.html#TERMS_HEADER">page headers</a>. +</p> + +<p> +<strong>A small word of caution:</strong> If your argument to +<kbd>.REVISION</kbd> is more than one word long, you must +enclose the argument in double-quotes. +</p> + +<p> +You may, if you wish, invoke <kbd>.REVISION</kbd> without an +argument, in which case, no revision number will be printed beside +"Rev." in headers or footers. +</p> + +<!-- -REVISION_STRING- --> + +<a name="REVISION_STRING"><h4><u>The revision string</u></h4></a> + +<p> +If you're not writing in English, you can ask <strong>mom</strong> +to use the word for "revision," or a shortform +thereof, in your own language by telling her what it is with the +<strong>REVISION_STRING</strong> macro, like this: + +<pre> + .REVISION_STRING "Rév." +</pre> +</p> + +<p> +Additionally, you may sometimes want to make use of +<strong>mom</strong>'s +<a href="#COPYSTYLE">COPYSTYLE DRAFT</a> +but not actually require any draft information. For example, you +might like <strong>mom</strong> 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: + +<pre> + .DRAFT + .DRAFT_STRING + .REVISION 2 +</pre> +</p> + +<p> +Equally, if you want to roll your own solution to what revision +information appears in headers, you could do something like this: + +<pre> + .DRAFT + .DRAFT_STRING + .REVISION "two-twenty-two" + .REVISION_STRING "Revision" +</pre> +</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- --> + +<hr width="33%" align="left"/> + +<a name="COPYRIGHT"></a> + +<p> +<nobr>Macro: <strong>COPYRIGHT</strong> <kbd>[COVER | DOC_COVER] "<copyright info>"</kbd></nobr> +<br/> + +<em>*Argument must be enclosed in double-quotes</em> +</p> + +<p> +The argument passed to <strong>COPYRIGHT</strong> 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 +<strong>COPYRIGHT</strong>; <strong>mom</strong> puts it in for +you. +</p> + +<p> +If the optional argument, <kbd>COVER</kbd> or <kbd>DOC_COVER</kbd>, +is given to <strong>COPYRIGHT</strong>, 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 "document +covers" and "covers"). Thus, it is possible to have +differing copyright information on the document cover and on the +cover ("title") page. An example might be: + +<pre> + .COPYRIGHT DOC_COVER "2006 John Smith and Jane Doe" + .COPYRIGHT COVER "2002 Joe Blow" +</pre> + +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 +("title") page. +</p> + +<p> +If you don'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 +"COPYRIGHT" 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- --> + +<hr width="33%" align="left"/> + +<a name="MISC"></a> + +<p> +<nobr>Macro: <strong>MISC</strong> <kbd>[COVER | DOC_COVER] "<argument 1>" ["<argument 2>" "<argument 3>" ...]</kbd></nobr> +<br/> + +<em>*String arguments must be enclosed in double-quotes</em> +</p> + +<p> +The argument(s) passed to <strong>MISC</strong> 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>. +<strong>MISC</strong> 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're submitting an essay where the prof has +requested that you include the course number, his name and the +date, you could do + +<pre> + .MISC "Music History 101" "Professor Hasbeen" "Dec. 24, 2006" +</pre> + +and the information would appear on the essay's cover page. +</p> + +<p> +If the optional argument, <kbd>COVER</kbd> or <kbd>DOC_COVER</kbd>, +is given to <strong>MISC</strong>, 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 "document +covers" and "covers"). Thus, it is possible to have +differing miscellaneous information on the document cover and on the +cover ("title") page. An example might be: + +<pre> + .MISC DOC_COVER "Music History 101" "Professor Hasbeen" + .MISC COVER "Spring Term Paper" +</pre> + +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 ("title") page. +</p> + +<p> +If you don'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 "MISC" +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- --> + +<hr width="33%" align="left"/> + +<a name="COVERTITLE"></a> + +<p> +<nobr>Macro: <strong>COVERTITLE</strong> <kbd>"<user defined cover page title>" ["<2nd line>" ["<3rd line>" ... ] ]</kbd></nobr> +<br/> + +<a name="DOC_COVERTITLE"></a> + +<nobr>Macro: <strong>DOC_COVERTITLE</strong> "<user defined document cover page title>" ["<2nd line>" ["<3rd line>" ... ] ]</nobr> +<br/> + +<em>*Arguments must be enclosed in double-quotes</em> +</p> + +<p> +The arguments passed to <strong>COVERTITLE</strong> or +<strong>DOC_COVERTITLE</strong> 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 <strong>COVERTITLE</strong> or +<strong>DOC_COVERTITLE</strong> is when none of the required first +arguments to <strong>COVER</strong> or <strong>DOC_COVER</strong> +fits your needs for the title you want to appear on cover (or doc +cover) pages. +</p> + +<p> +<strong>COVERTITLE</strong> and <strong>DOC_COVERTITLE</strong> +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> + +<hr/> + +<!-- ======================================================================== --> + +<a name="DOCSTYLE_MACROS"><h2><u>The Docstyle Macros</u></h2></a> + +<p> +The docstyle macros tell <strong>mom</strong> what type of +document you're writing, whether you want the output typeset or +"typewritten", and whether you want a draft copy (with +draft and revision information in the headers) or a final copy. +</p> + +<a name="INDEX_DOCSTYLE"><h3><u>Docstyle macros list</u></h3></a> + +<ul> + <li><a href="#DOCTYPE">DOCTYPE</a></li> + <li><a href="#PRINTSTYLE">PRINTSTYLE</a></li> + <ul> + <li><a href="#TYPESET_DEFAULTS">Defaults for PRINTSTYLE TYPESET</a></li> + <li><a href="#TYPEWRITE_DEFAULTS">Defaults for PRINTSTYLE TYPEWRITE</a></li> + <ul> + <li><a href="#TYPEWRITE_CONTROL">TYPEWRITE control macros</a></li> + </ul> + </ul> + <li><a href="#COPYSTYLE">COPYSTYLE</a></li> +</ul> + +<!-- -DOCTYPE- --> + +<hr width="66%" align="left"/> + +<a name="DOCTYPE"></a> + +<p> +<nobr>Macro: <strong>DOCTYPE</strong> <kbd>DEFAULT | CHAPTER | NAMED "<name>" | LETTER</kbd></nobr> +</p> + +<p> +The arguments <kbd>DEFAULT, CHAPTER</kbd> and +<kbd>NAMED</kbd> tell <strong>mom</strong> what to put in the +<a href="definitions.html#TERMS_DOCHEADER">docheader</a> +and +<a href="definitions.html#TERMS_HEADER">page headers</a>. +<kbd>LETTER</kbd> tells her that you want to write a letter. +</p> + +<p> +<strong>Mom</strong>'s default <strong>DOCTYPE</strong> is +<kbd>DEFAULT</kbd>. If that's what you want, you don't +have to give a <strong>DOCTYPE</strong> command. +</p> + +<h4><u>DEFAULT</u></h4> + +<p> +<strong>DEFAULT</strong> prints a +<a href="definitions.html#TERMS_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 <strong>mom</strong> outputs each part of the page header.) +</p> + +<h4><u>CHAPTER</u></h4> + +<p> +<strong>CHAPTER</strong> prints "Chapter <n>" in place of a +<a href="definitions.html#TERMS_DOCHEADER">docheader</a> +<nobr>(<kbd><n></kbd></nobr> is what you gave to the +<a href="#REFERENCE_MACROS">reference macro</a> +<a href="#CHAPTER">CHAPTER</a>). +If you give the chapter a title with +<a href="#CHAPTER_TITLE">CHAPTER TITLE</a>, +<strong>mom</strong> prints "Chapter <n>" 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>, +<strong>mom</strong> prints only the chapter title. <em>(*For +backward compatibility with pre-1.1.5 versions of</em> +<strong>mom</strong><em>, you can also supply a chapter title by +omitting the</em> <strong>CHAPTER</strong> <em>reference macro and +supplying a chapter title with</em> +<a href="#CHAPTER_STRING">CHAPTER_STRING</a>.) +</p> + +<p> +The page headers in <strong>DOCTYPE CHAPTER</strong> contain the author, +the title of the book (which you gave with +<a href="#TITLE">TITLE</a>), +and "Chapter <n>" (or the chapter title). See +<a href="headfootpage.html#HEADER_STYLE">Default Specs for Headers</a> +for <strong>mom</strong>'s default type parameters for each part of +the page header. +</p> + +<h4><u>NAMED</u></h4> + +<p> +<strong>NAMED</strong> takes an additional argument: a name +for this particular kind of document (e.g. outline, synopsis, +abstract, memorandum), enclosed in double-quotes. +<strong>NAMED</strong> is identical to <strong>DEFAULT</strong> +except that <strong>mom</strong> prints the argument to +<strong>NAMED</strong> beneath the +<a href="definitions.html#TERMS_DOCHEADER">docheader</a>, +as well as in page headers. +(See +<a href="headfootpage.html#HEADER_STYLE">Default specs for headers</a> +for how <strong>mom</strong> 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 <strong>DOCTYPE NAMED</strong> +a third (optional) argument: the name of a colour pre-defined (or +"initialized") with +<a href="color.html#NEWCOLOR">NEWCOLOR</a> +or +<a href="color.html#XCOLOR">XCOLOR</a>. +For example, if you have a doctype named "Warning", +and you'd like "Warning" to be in red, assuming you've +pre-defined (or "initialized") the color, red, this is +what the <strong>DOCTYPE</strong> entry would look like: + +<pre> + .DOCTYPE NAME "Warning" red +</pre> +</p> + +<p> +By default, the string passed to <strong>DOCTYPE NAMED</strong> is +underlined in the docheader, and on document-cover pages and cover +("title"") pages. (See the +<a href="cover.html#INTRO">Introduction to covers</a> +for the difference between "doc cover" and "cover" +pages.) +</p> + +<a name="DOCTYPE_UNDERLINE"><h5><u>The DOCTYPE_UNDERLINE macro</u></h5></a> + +<p> +Formerly, this underlining was carved in stone. As of version +1.5 of <strong>mom</strong>, you can now use the macro +<strong>DOCTYPE_UNDERLINE</strong> to set the weight of the +underline and its distance from the doctype-name <em>in the +docheader</em> (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. +<strong>Mom</strong>'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 "gap" is the distance from the +<a href="definitions.html#TERMS_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#TERMS_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. +<strong>Mom</strong>'s default for head underlines 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 head to +the upper edge of the underline. <strong>Mom</strong>'s default +gap for named-doctype underlines 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 that is: + +<pre> + .DOCTYPE_UNDERLINE 2 3p +</pre> + +If you wanted the same thing, but were content with +<strong>mom</strong>'s default gap of 2 points, + +<pre> + .DOCTYPE_UNDERLINE 4 +</pre> + +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><nobr>.DOCTYPE_UNDERLINE +OFF</nobr></kbd> (or <strong>NO</strong>, <strong>X</strong>, etc.) +</p> + +<p> +Please note that if you supply a weight to +<strong>DOCTYPE_UNDERLINE</strong>, 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 head underlining off manually +afterwards. +</p> + +<h4><u>LETTER</u></h4> + +<p> +<strong>LETTER</strong> tells mom you're writing a letter. See +the section +<a href="letters.html#INTRO">Writing Letters</a> +for instructions on using <strong>mom</strong> to format letters. +</p> + +<!-- -PRINTSTYLE- --> + +<hr width="33%" align="left"/> + +<a name="PRINTSTYLE"></a> + +<p> +<nobr>Macro: <strong>PRINTSTYLE</strong> <kbd>TYPESET | TYPEWRITE [ SINGLESPACE ]</kbd></nobr> +<br/> + +<em>*Required for document processing</em> +<br/> + +<em>*Must come before any changes to default document style</em> +</p> + +<p> +<strong>PRINTSTYLE</strong> tells <strong>mom</strong> whether to typeset +a document, or to print it out "typewritten, doubled-spaced". +</p> + +<p> +<strong>THIS MACRO MAY NOT BE OMITTED.</strong> In order for +document processing to take place, <strong>mom</strong> requires +a <strong>PRINTSTYLE</strong>. If you don't give one, +<strong>mom</strong> will warn you on stderr and print a single +page with a nasty message. +</p> + +<p> +Furthermore, <strong>PRINTSTYLE</strong> must come before any +changes to <strong>mom</strong>'s default typestyle parameters. +(This applies primarily to, but is by no means restricted to, +<strong>PRINTSTYLE TYPESET</strong>.) <strong>PRINTSTYLE</strong> +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> + +<p> +<strong>TYPESET</strong>, 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, <strong>PRINTSTYLE TYPESET</strong> must come +before any changes to <strong>mom</strong>'s default typographic +settings. For example, + +<pre> + .PAPER A4 + .LS 14 + .PRINTSTYLE TYPESET +</pre> + +will not changes <strong>mom</strong>'s default paper size to A4, +nor her default document leading 14 points, whereas + +<pre> + .PRINTSTYLE TYPESET + .PAPER A4 + .LS 14 +</pre> + +will. +</p> + +<p> +With <strong>TYPEWRITE</strong>, <strong>mom</strong> 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#TERMS_LEADING">leading</a> +are (mostly) ignored. An important exception is +<a href="headfootpage.html#HDRFTR_GLOBAL_SIZE">HEADER_SIZE</a> +(and, by extension, <strong>FOOTER_SIZE</strong>), which allows +you to reduce the point size of headers/footers should they become +too crowded. Most of <strong>mom</strong>'s inlines affecting the +appearance of type are also ignored (<kbd>\*S</kbd> is an exception; +there may be a few others). +</p> + +<p> +In short, <strong>TYPEWRITE</strong> never produces effects +other than those available on a typewriter. Don't be fooled by +how brainless this sounds; <strong>mom</strong> is remarkably +sophisticated when it comes to conveying the typographic sense of a +document within the confines of <strong>TYPEWRITE</strong>. +</p> + +<p> +The primary uses of <strong>TYPEWRITE</strong> 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's in the submission phase of its life (say, to show fellow +writers for critiquing), simply change <strong>TYPEWRITE</strong> to +<strong>TYPESET</strong> and print out a copy. +</p> + +<p> +If, for some reason, you would prefer the output +of <strong>TYPEWRITE</strong> single-spaced, pass +<strong>PRINTSTYLE TYPEWRITE</strong> the optional argument, +<strong>SINGLESPACE</strong>. +</p> + +<p> +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 <strong>DOC_LEAD</strong> is set +<strong>before</strong> you invoke the <kbd>.START</kbd> +macro. +</p> + +<a name="TYPESET_DEFAULTS"><h3><u>TYPESET defaults</u></h3></a> + +<pre> + 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 +</pre> + +<a name="TYPEWRITE_DEFAULTS"><h3><u>TYPEWRITE defaults</u></h3></a> + +<pre> + 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 +</pre> + +<a name="TYPEWRITE_CONTROL"><h3><u>PRINTSTYLE TYPEWRITE control macros</u></h3></a> + +<p> +In <strong>PRINTSTYLE TYPEWRITE</strong>, <strong>mom</strong>, +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#TERMS_INLINES">inline escape</a> +for pseudo-italics. +</p> + +<p> +If you'd prefer that <strong>mom</strong> were less bloody-minded +about pretending to be a typewriter (i.e. you'd like italics and +pseudo-italics to come out as italics), use the control macros +<kbd>.ITALIC_MEANS_ITALIC</kbd> and <kbd>.SLANT_MEANS_SLANT</kbd>. +Neither requires an argument. +</p> + +<p> +Although it'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> + +<a name="UNDERLINE_QUOTES"></a> + +<p> +Additionally, by default, <strong>mom</strong> underlines +<a href="definitions.html#TERMS_QUOTES">quotes</a> +(but not +<a href="definitions.html#TERMS_BLOCKQUOTES">blockquotes</a>) +in <strong>PRINTSTYLE TYPEWRITE</strong>. +If you don't like this behaviour, turn it off with + +<pre> + .UNDERLINE_QUOTES OFF +</pre> +</p> + +<p> +To turn underlining of quotes back on, use +<strong>UNDERLINE_QUOTES</strong> without an argument. +</p> + +<p> +While most of the +<a href="docelement.html#DOCELEMENT_CONTROL">control macros</a> +have no effect on <strong>PRINTSTYLE TYPEWRITE</strong>, there +is an important exception: +<a href="headfootpage.html#HDRFTR_GLOBAL_SIZE">HEADER_SIZE</a> +(and by extension, <strong>FOOTER_SIZE</strong>). 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 +<a href="#COPYSTYLE">COPYSTYLE</a> +is <strong>DRAFT</strong>). +</p> + +<!-- -COPYSTYLE- --> + +<hr width="33%" align="left"/> + +<a name="COPYSTYLE"></a> + +<p> +<nobr>Macro: <strong>COPYSTYLE</strong> <kbd>DRAFT | FINAL</kbd></nobr> +</p> + +<p> +<strong>Mom</strong>'s default <strong>COPYSTYLE</strong> is +<strong>FINAL</strong>, so you don't have to use this macro unless +you want to. +</p> + +<p> +<strong>COPYSTYLE DRAFT</strong> exhibits the following behaviour: + +<ol> + <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#TERMS_HEADER">page headers</a> + (or footers, depending on which you've selected) along with + any other information that normally appears there. + </li> +</ol> +</p> + +<p> +<strong>IMPORTANT:</strong> 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> + +<p> +<strong>COPYSTYLE FINAL</strong> differs from <strong>DRAFT</strong> in that: + +<ol> + <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> +</p> + +<p> +<a name="COPYSTYLE_NOTE"><strong>NOTE:</strong></a> +The centre part of page headers can get crowded, +especially with +<a href="docprocessing.html#DOCTYPE">DOCTYPE CHAPTER</a> +and +<a href="docprocessing.html#DOCTYPE">DOCTYPE NAMED</a>, +when the <strong>COPYSTYLE</strong> is <strong>DRAFT</strong>. +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 TYPESET</a>, +is to reduce the size of the header'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> + +<hr/> + +<!-- ======================================================================== --> + +<a name="START_MACRO"><h2><u>Initiate document processing</u></h2></a> + +<p> +In order to use <strong>mom</strong>'s document element macros +(tags), you have to tell her you want them. The macro to do this is +<strong>START</strong>. +</p> + +<p> +<strong>START</strong> collects the information you gave +<strong>mom</strong> in the setup section at the top of your file (see +<a href="#DOCPROCESSING_TUT">Tutorial — setting up a mom document</a>), +merges it with her defaults, sets up headers and page numbering, +and prepares <strong>mom</strong> to process your document using +the document element tags. No document processing takes place until +you invoke <kbd>.START</kbd>. +</p> + +<!-- -START- --> + +<hr width="66%" align="left"/> + +<a name="START"></a> + +<p> +<nobr>Macro: <strong>START</strong></nobr> +<br/> + +<em>*Required for document processing.</em> +</p> + +<p> +<strong>START</strong> takes no arguments. It simply instructs +<strong>mom</strong> to begin document processing. If you don't +want document processing (i.e. you only want the +<a href="typesetting.html#MACROS_TYPESETTING">typesetting macros</a>), +don't use <strong>START</strong>. +</p> + +<p> +At a barest minimum before <strong>START</strong>, you must enter a +<a href="#PRINTSTYLE">PRINTSTYLE</a> +command. +</p> + +<hr/> + +<!-- ======================================================================== --> + +<a name="STYLE_BEFORE_START"><h2><u>Changing global typesetting and formatting parameters before START</u></h2></a> + +<p> +In the third (optional) part of setting up a document (see +<a href="#DOCPROCESSING_TUT">Tutorial — setting up a mom document</a>), +you can use the +<a href="typesetting.html">typesetting macros</a> +to change <strong>mom</strong>'s document-wide defaults for margins, +line length, family, base point size, +<a href="definitions.html#TERMS_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#TERMS_DOCHEADER">docheader</a>, +and whether you want you want the document's nominal leading +adjusted to fill pages fully to the bottom margin. +</p> + +<ul> + <li><a href="#TYPE_BEFORE_START">Using the typesetting macros before START</a></li> + <li><a href="#DOC_LEAD_ADJUST">DOC_LEAD_ADJUST</a> + — adjusting linespacing for equal, accurate bottom margins + </li> + <li><a href="#DOCHEADER">DOCHEADER</a> + — turning the docheader off + </li> + <ul> + <li><a href="#DOCHEADER_CONTROL">Docheader control</a></li> + </ul> +</ul> + +<hr width="66%" align="left"/> + +<a name="TYPE_BEFORE_START"><h3><u>Using the typesetting macros before START</u></h3></a> + +<p> +From time to time (or maybe frequently), you'll want the overall +look of a document to differ from <strong>mom</strong>'s defaults. +Perhaps you'd like her to use a different +<a href="definitions.html#TERMS_FAMILY">family</a>, +or a different overall +<a href="definitions.html#TERMS_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) <strong>after</strong> +<a href="#PRINTSTYLE">PRINTSTYLE</a> +and <strong>before</strong> +<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've missed +is "<u>after <strong>PRINTSTYLE</strong></u>". +</p> + +<p> +Changes to any aspect of the default look and/or formatting +of a <strong>mom</strong> document must come after +<strong>PRINTSTYLE</strong>. For example, it might seem natural to +set up page margins at the very top of a document with + +<pre> + .L_MARGIN 1i + .R_MARGIN 1.5i +</pre> +</p> + +<p> +However, when you invoke <kbd>.PRINTSTYLE</kbd>, those margins +will be overridden. The correct place to set margins — and +all other changes to the look of a document — is <strong>after +PRINTSTYLE</strong>. +</p> + +<p> +<strong>NOTE:</strong> Don't use the macros listed in +<a href="#DOC_PARAM_MACROS">Changing document-wide typesetting parameters after START</a> +prior to <strong>START</strong>; they are exclusively for use +afterwards. +</p> + +<p> +When used before <strong>START</strong>, the +<a href="typesetting.html#MACROS_TYPESETTING">typesetting macros</a> +(below) have the following meanings: + +<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 <a href="#DOC_LEAD_ADJUST">DOC_LEAD_ADJUST</a> +***See <a href="#LRC_NOTE">Special note</a> +</pre> +</p> + +<p> +Other macros that deal with type style, or refinements thereof +(<strong>KERN, LIGATURES, HY, WS, SS,</strong> etc.), behave normally. +It is not recommended that you set up tabs or indents prior to +<strong>START</strong>. +</p> + +<p> +If you want to change any of the basic parameters (above) +<em>after</em> <strong>START</strong> and have them affect a +document globally (as if you'd entered them <em>before</em> +<strong>START</strong>), you must use the macros listed in +<a href="#DOC_PARAM_MACROS">Changing document-wide style parameters after START</a>. +</p> + +<a name="LRC_NOTE"><h4><u>Special note on LEFT, RIGHT and CENTER prior to START</u></h4></a> + +<p> +In a word, these three macros have no effect on document processing +when invoked prior to <strong>START</strong>. +</p> + +<p> +All <strong>mom</strong>'s document element tags +(<strong>PP</strong>, <strong>HEAD</strong>, +<strong>BLOCKQUOTE</strong>, <strong>FOOTNOTE</strong>, etc.) +except +<a href="docelement.html#QUOTE">QUOTE</a> +set a +<a href="definitions.html#TERMS_FILLED">fill mode</a> +as soon as they're invoked. If you wish to turn fill mode off for +the duration of any tag (with +<nobr><a href="typesetting.html#LRC">LEFT, RIGHT or CENTER</a>)</nobr> +you must do so immediately after invoking the tag. Furthermore, +the change affects <em>only</em> 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- --> + +<hr align="left" width="66%"/> + +<a name="INCLUDE"><h2><u>Including (sourcing) style sheets and files</u></h2></a> + +<p> +If you routinely make the same changes to <strong>mom</strong>'s +defaults in order to create similar documents in a similar +style — in other words, you need a template— you can create +style-sheet files and include, or "source", them into your +<strong>mom</strong> documents with the macro, +<strong>INCLUDE</strong>. 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'd create a file, let's call +it <kbd>head_template</kbd>, in which you'd place the pertinent +HEAD control macros. + +<pre> + .HEAD_FAMILY H + .HEAD_FONT BI + .HEAD_QUAD L + .HEAD_UNDERLINE OFF +</pre> + +Then, in the preliminary document set-up section of your main file, +you'd include the style sheet, or template, like this: + +<pre> + .TITLE "Sample Document + .AUTHOR "Joe Blow + .PRINTSTYLE TYPESET + \# + .INCLUDE head_template + \# + .START +</pre> + +The blank comment lines <nobr>( <kbd>\#</kbd> )</nobr> aren'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're working, you simply enter the filename after +<kbd>.INCLUDE</kbd>. If the file's in another directory, you must +provide a full path name to it. For example, if you'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: + +<pre> + .TITLE "Sample Document + .AUTHOR "Joe Blow + .PRINTSTYLE TYPESET + \# + .INCLUDE /home/joe/style_sheets/head_template + \# + .START +</pre> +</p> + +<p> +<strong>INCLUDE</strong> 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 +<strong>mom</strong> formatting commands. Neither is +<strong>INCLUDE</strong> restricted to use with +<strong>mom</strong>'s document processing macros. You can use it +in plain typeset documents as well. +</p> + +<p> +<strong>EXPERTS: INCLUDE</strong> is an alias for the groff +request, <kbd>.so</kbd>. Mix 'n' match with impunity. +</p> + +<!-- -COLOUR- --> + +<hr align="left" width="66%"/> + +<a name="COLOR"><h2><u>Initializing colours</u></h2></a> + +<p> +Although it doesn'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 +<a href="#START">START</a>. +</p> + +<p> +The macro, +<a href="color.html#COLOR">COLOR</a>, +and the +<a href="definitions.html#TERMS_INLINES">inline escape</a>, +<a href="color.html#COLOR_INLINE"><kbd>\[<colorname>]</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> + +<p> +<strong>PLEASE NOTE:</strong> If you plan to have <strong>mom</strong> +generate a +<a href="docelement.html#TOC">table of contents</a>, +do NOT embed colour +<a href="definitions.html#TERMS_INLINES">inline escapes</a> +(<a href="color.html#COLOR_INLINE"><kbd>\[<colorname>]</kbd></a>) +in the +<a href="definitions.html#TERMS_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#TERMS_CONTROLMACRO">control macros</a> +<strong>mom</strong> provides to automatically colourize these +elements. +</p> + +<!-- -DOC LEAD ADJUST- --> + +<hr align="left" width="66%"/> + +<a name="DOC_LEAD_ADJUST"><h2><u>Adjust a document's leading to fill pages</u></h2></a> + +<p> +<nobr>Macro: <strong>DOC_LEAD_ADJUST</strong> <kbd>toggle</kbd></nobr> +<br/> + +<em>*Must come after LS or AUTOLEAD and before START</em> +</p> + +<p> +<strong>DOC_LEAD_ADJUST</strong> is a special macro to adjust +document +<a href="definitions.html#TERMS_LEADING">leading</a> +so that bottom margins fall precisely where you expect. +</p> + +<p> +If you invoke <kbd>.DOC_LEAD_ADJUST</kbd>, <strong>mom</strong> +takes the number of lines that fit on the page at your requested +leading, then incrementally adds +<a href="definitions.html#TERMS_UNITS">machine units</a> +to the leading until the maximum number of lines at the new leading +matches the bottom margin. 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's <strong>mom</strong>'s default. +</p> + +<p> +Should you NOT want adjusted document leading, you MUST turn it +off manually, like this: + +<pre> + .DOC_LEAD_ADJUST OFF +</pre> +</p> + +<p> +If you set the document leading prior to <strong>START</strong> +with +<a href="typesetting.html#LEADING">LS</a> +or +<a href="typesetting.html#AUTOLEAD">AUTOLEAD</a>, +<strong>DOC_LEAD_ADJUST OFF</strong> must come afterwards, like +this: + +<pre> + .LS 12 + .DOC_LEAD_ADJUST OFF +</pre> +</p> + +<p> +In this scenario, the maximum number of lines that fit on a page at +a +<a href="definitions.html#TERMS_LEADING">leading</a> +of 12 +<a href="definitions.html#TERMS_PICASPOINTS">points</a> +determine where <strong>mom</strong> ends +a page. The effect will be that last lines usually fall (slightly) +short of the "official" bottom margin. +</p> + +<p> +In +<a href="docprocessing.html#PRINTSTYLE">PRINTSTYLE</a> +<strong>TYPEWRITE</strong>, the leading is always adjusted and +can't be turned off. +</p> + +<p> +<strong>NOTE:</strong> <strong>DOC_LEAD_ADJUST</strong>, 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> +<strong>ADDITIONAL NOTE:</strong> Even if you disable +<strong>DOC_LEAD_ADJUST</strong>, <strong>mom</strong> 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> + +<!-- -DOCHEADER- --> + +<hr align="left" width="66%"/> + +<a name="DOCHEADER"><h2><u>Managing the docheader</u></h2></a> + +<p> +<nobr>Macro: <strong>DOCHEADER</strong> <kbd><toggle> [ distance to advance from top of page ]</kbd></nobr> +<br/> + +<em>*Must come before</em> START; <kbd>distance</kbd> <em>requires a <a href="definitions.html#TERMS_UNITOFMEASURE">unit of measure</a></em> +</p> + +<p> +By default, <strong>mom</strong> prints a +<a href="definitions.html#TERMS_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't want a docheader, +turn it off with + +<pre> + .DOCHEADER OFF +</pre> +</p> + +<p> +<strong>DOCHEADER</strong> is a toggle macro, so the argument doesn't +have to be <strong>OFF</strong>; it can be anything you like. +</p> + +<p> +If you turn the docheader off, <strong>mom</strong>, by default, starts +the running text of your document on the same top +<a href="definitions.html#TERMS_BASELINE">baseline</a> +as all subsequent pages. If you'd like her to start at a different +vertical position, give her the distance you'd like as a second +argument. + +<pre> + .DOCHEADER OFF 1.5i +</pre> +</p> + +<p> +This starts the document 1.5 inches from the top of the page PLUS +whatever spacing adjustment <strong>mom</strong> has to make in +order to ensure that the first baseline of running text falls on a +"valid" 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#TERMS_BASELINE">baseline</a> +of the first line of type. +</p> + +<p> +<strong>TIP:</strong> Since no document processing happens until +you invoke +<a href="#START"><kbd>.START</kbd></a> +— including anything to do with docheaders — you can +typeset your own docheader prior to <strong>START</strong> (if +you don't like the way <strong>mom</strong> does things) and use +<strong>DOCHEADER OFF</strong> with its optional distance argument +to ensure that the body of your document starts where you want. You +can even insert a PostScript file (with <kbd>.PSPIC</kbd>; see the +<strong>groff_tmac</strong> man page for usage). +</p> + +<!-- DOCHEADER CONTROL --> + +<a name="DOCHEADER_CONTROL"><h3><u>How to change the look of docheaders: docheader control macros</u></h3></a> + +<p> +With +<a href="#PRINTSTYLE">PRINTSTYLE TYPEWRITE</a>, +the look of docheaders is carved in stone. +In +<a href="#PRINTSTYLE">PRINTSTYLE TYPESET</a>, +however, you can make a lot of changes. Macros that alter docheaders +MUST come before +<a href="#START">START</a>. +</p> + +<a name="DOCHEADER_DESC"></a> + +<p> +A typeset docheader has the following characteristics. Note that +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; <strong>mom</strong> will +compensate: + +<pre> + 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 +</pre> +</p> + +<p> +If the +<a href="#DOCTYPE">DOCTYPE</a> +is CHAPTER, + +<pre> + Chapter <n> bold, 4 points larger than running text + Chapter Title bold italic, 4 points larger than running text +</pre> +</p> + +<p> +The +<a href="definitions.html#TERMS_FAMILY">family</a> +is the prevailing family of the whole document. +</p> + +<p> +<strong>NOTE:</strong> If your <strong>DOCTYPE</strong> is +<strong>CHAPTER</strong> and you have both "Chapter +<n>" and a "Chapter Title" (as above), +<strong>mom</strong> inserts a small amount of whitespace between +them, equal to one-quarter of the +<a href="definitions.html#TERMS_LEADING">leading</a> +in effect. If this doesn't suit you, you can alter the space +by including the +<a href="definitions.html#TERMS_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: + +<pre> + .CHAPTER_TITLE "\*[DOWN 2p]Why Not Patent Calculus?" + or + .CHAPTER_TITLE "\*[UP 2p]Why Not Patent Calculus?" +</pre> +</p> + +<a name="DOCHEADER_CONTROL_INDEX"><h4><u>The docheader macros to:</u></h4></a> + +<ol> + <li><a href="#CHANGE_START">Change the starting position of the docheader</a></li> + <li><a href="#DOCHEADER_FAMILY">Change the family of the entire docheader</a></li> + <li><a href="#ADJUST_LEADING">Adjust the docheader leading</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 docheader elements</a></li> + <li><a href="#CHANGE_COLOR">Change the colour of the docheader</a></li> + <li><a href="#CHANGE_SIZE">Adjust the size of docheader elements</a></li> + <li><a href="#CHANGE_ATTRIBUTE">Change the attribution string ("by")</a></li> +</ol> + +<a name="CHANGE_START"><h5><u>1. Change the starting position</u></h5></a> + +<p> +By default, a docheader starts on the same +<a href="definitions.html#TERMS_BASELINE">baseline</a> +as +<a href="definitions.html#TERMS_RUNNING">running text</a>. +If you'd like it to start somewhere else, use the macro +<kbd>.DOCHEADER_ADVANCE</kbd> and give it the distance you want +(measured from the top edge of the paper to the first baseline +of the docheader), like this: + +<pre> + .DOCHEADER_ADVANCE 4P +</pre> + +A +<a href="definitions.html#TERMS_UNITOFMEASURE">unit of measure</a> +is required. +</p> + +<p> +<strong>NOTE:</strong> If +<a href="headfootpage.html#HEADERS">HEADERS</a> +are <strong>OFF</strong>, <strong>mom</strong>'s normal top +margin for +<a href="definitions.html#TERMS_RUNNING">running text</a> +(7.5 +<a href="definitions.html#TERMS_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 +<a href="#CHANGE_START">DOCHEADER_ADVANCE</a> +to place them where you want. +</p> + +<a name="DOCHEADER_FAMILY"><h5><u>2. Change the family of the entire docheader</u></h5></a> + +<p> +By default, <strong>mom</strong> sets the docheader in the same +family used for +<a href="definitions.html#TERMS_RUNNING">running text</a>. +If you'd prefer to have your docheaders set in a different family, +invoke <kbd>.DOCHEADER_FAMILY</kbd> with the family you want. +The argument for <strong>DOCHEADER_FAMILY</strong> is the same as +for +<a href="typesetting.html#FAMILY">FAMILY</a>. +</p> + +<p> +For example, <strong>mom</strong>'s default family for running text +is Times Roman. If you'd like to keep that default, but have the +docheaders set entirely in Helvetica, + +<pre> + .DOCHEADER_FAMILY H +</pre> + +is how you'd do it. +</p> + +<p> +Please note that if you use <strong>DOCHEADER_FAMILY</strong>, +you can still alter the family of individual parts of the docheader +with the macros listed +<a href="#CHANGE_FAMILY">here</a>. +</p> + +<a name="ADJUST_LEADING"><h5><u>3. Adjust the leading</u></h5></a> + +<p> +The +<a href="definitions.html#TERMS_LEADING">leading</a> +of docheaders is the same as running text. If you'd like your +docheaders to have a different leading, say, 2 points more than the +lead of running text, use: + +<pre> + .DOCHEADER_LEAD +2 +</pre> +</p> + +<p> +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#TERMS_UNITOFMEASURE">unit of measure</a> +is required; points is assumed. +</p> + +<a name="CHANGE_FAMILY"><h5><u>4. Change the family of docheader elements</u></h5></a> + +<p> +The following macros let you change the +<a href="definitions.html#TERMS_FAMILY">family</a> +of each docheader element separately: + +<ul> + <li><nobr><kbd>.TITLE_FAMILY <family></kbd></nobr></li> + <li><nobr><kbd>.CHAPTER_TITLE_FAMILY <family></kbd></nobr></li> + <li><nobr><kbd>.SUBTITLE_FAMILY <family></kbd></nobr></li> + <li><nobr><kbd>.AUTHOR_FAMILY <family></kbd></nobr></li> + <li><nobr><kbd>.DOCTYPE_FAMILY <family></kbd></nobr> + (if <a href="#DOCTYPE">DOCTYPE</a> is NAMED) + </li> +</ul> +</p> + +<p> +Simply pass the appropriate macro the family you want, just as you +would with +<a href="typesetting.html#FAMILY">FAMILY</a>. +</p> + +<a name="CHANGE_FONT"><h5><u>5. Change the font of docheader elements</u></h5></a> + +<p> +The following macros let you change the +<a href="definitions.html#TERMS_FONT">font</a> +of each docheader element separately: + +<ul> + <li><nobr><kbd>.TITLE_FONT R | B | I | BI</kbd></nobr></li> + <li><nobr><kbd>.CHAPTER_TITLE_FONT R | B | I | BI</kbd></nobr></li> + <li><nobr><kbd>.SUBTITLE_FONT R | B | I | BI</kbd></nobr></li> + <li><nobr><kbd>.AUTHOR_FONT R | B | I | BI</kbd></nobr></li> + <li><nobr><kbd>.DOCTYPE_FONT R | B | I | BI</kbd></nobr> + (if <a href="#DOCTYPE">DOCTYPE</a> is NAMED) + </li> +</ul> +</p> + +<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> + +<a name="CHANGE_COLOR"><h5><u>6. Change the colour of the docheader elements individually</u></h5></a> + +<p> +The following macros let you change the color of each docheader +element separately. You must pre-define (or +"initialize") the color with +<a href="color.html#NEWCOLOR">NEWCOLOR</a> +or +<a href="color.html#XCOLOR">XCOLOR</a>. + +<ul> + <li><nobr><kbd>.TITLE_COLOR <colorname></kbd></nobr></li> + <li><nobr><kbd>.CHAPTER_TITLE_COLOR <colorname></kbd></nobr></li> + <ul> + <li><strong>Note: CHAPTER_TITLE_COLOR</strong> is needed + only if you enter both a <strong>CHAPTER</strong> + reference macro AND a <strong>CHAPTER_TITLE</strong> + macro. Otherwise, the macro, + <strong>TITLE_COLOR</strong> takes care of colorizing + the chapter header. + </li> + </ul> + <li><nobr><kbd>.SUBTITLE_COLOR <colorname></kbd></nobr></li> + <li><nobr><kbd>.ATTRIBUTE_COLOR <colorname></kbd></nobr> + (the "by" string that precedes the author[s] name[s]) + </li> + <li><nobr><kbd>.AUTHOR_COLOR <colorname></kbd></nobr></li> + <li><nobr><kbd>.DOCTYPE_COLOR <colorname></kbd></nobr> + (if <a href="#DOCTYPE">DOCTYPE</a> is NAMED) + </li> +</ul> +</p> + +<p> +It is not recommended that you embed colour (with the +<a href="definitions.html#TERMS_INLINES">inline escape</a>, +<a href="color.html#COLOR_INLINE"><kbd>\*[<colorname>]</kbd></a>) +in the strings passed to +<strong>TITLE</strong>, <strong>CHAPTER_TITLE</strong>, +<strong>SUBTITLE</strong>, <strong>AUTHOR</strong> or the name you +give <strong>DOCTYPE NAMED</strong>. The strings passed to these +macros are used to generate page +<a href="definitions.html#TERMS_HEADER">headers</a> +and +<a href="definitions.html#TERMS_FOOTER">footers</a>. +An embedded colour will cause the string to be colourized any time +it appears in headers or footers. (If you want headers or footers +colourized, or parts thereof, use the header/footer control macros.) +</p> + +<a name="DOCHEADER_COLOR"></a> + +<p> +If you want to colourize the entire docheader, use the macro + +<ul> + <li><nobr><strong>DOCHEADER_COLOR</strong> <kbd><color name></kbd></nobr></li> +</ul> +</p> + +<a name="CHANGE_SIZE"><h5><u>7. Adjust the size of docheader elements</u></h5></a> + +<p> +The following macros let you adjust the point size of each docheader +element separately. +</p> + +<p> +<strong>Mom</strong> 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#TERMS_UNITOFMEASURE">unit of measure</a>, +so there's no need to append a unit to the argument. Fractional point +sizes are allowed. +</p> + +<ul> + <li><nobr><kbd>.TITLE_SIZE <+/-points></kbd></nobr> + <br/> + + default = +3.5 (+4 if docheader title is "Chapter <n>") + </li> + <li><nobr><kbd>.CHAPTER_TITLE_SIZE <+/-points></kbd></nobr> + <br/> + + default = +4 + </li> + <li><nobr><kbd>.SUBTITLE_SIZE <+/-points></kbd></nobr> + <br/> + + default = +0 + </li> + <li><nobr><kbd>.AUTHOR_SIZE <+/-points></kbd></nobr> + <br/> + + default = +0 + </li> + <li><nobr><kbd>.DOCTYPE_SIZE <+/-points></kbd></nobr> + (if <a href="#DOCTYPE">DOCTYPE</a> is NAMED) + <br/> + + default = +3 + </li> +</ul> + +<p> +Simply pass the appropriate macro the size adjustment you want. +</p> + +<a name="CHANGE_ATTRIBUTE"><h5><u>8. Change the attribution string ("by")</u></h5></a> + +<p> +If you're not writing in English, you can change what +<strong>mom</strong> prints where "by" appears in +docheaders. For example, + +<pre> + .ATTRIBUTE_STRING "par" +</pre> + +changes "by" to "par". <strong>ATTRIBUTE_STRING</strong> +can also be used, for example, to make the attribution read +"Edited by". +</p> + +<p> +If you don't want an attribution string at all, simply pass +<strong>ATTRIBUTE_STRING</strong> an empty argument, like this: + +<pre> + .ATTRIBUTE_STRING "" +</pre> +</p> + +<p> +<strong>Mom</strong> 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 <strong>ATTRIBUTE_STRING</strong>, 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 "document +covers" and "covers"). Thus, it is possible to have +different attribution strings on the document cover page, the cover +("title") page, and in the first-page docheader. An +extreme example would be: + +<pre> + .ATTRIBUTE_STRING "" + .ATTRIBUTE_STRING DOC_COVER "Edited by" + .ATTRIBUTE_STRING COVER "by" +</pre> + +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 "Edited by" on the +document cover; the third will print "by" on the cover +("title") page. +</p> + +<p> +If you don'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> + +<p> +<strong>NOTE:</strong> The type specs for the attribution line +in docheaders are the same as for the author line. Although +it's highly unlikely you'll want the attribution line in a +different family, font, or point size, you can do so by using +<a href="definitions.html#TERMS_INLINES">inline escapes</a> +in the argument to <strong>ATTRIBUTE_STRING</strong>. For +example, + +<pre> + .ATTRIBUTE_STRING "\f[HBI]\*[SIZE -2p] by \*[SIZE +2p]\*[PREV]" +</pre> + +would set "by" in Helvetica bold italic, 2 points +smaller than normal. +</p> + +<!-- -COLUMNS- --> + +<hr align="left" width="66%"/> + +<a name="COLUMNS_INTRO"><h2><u>Setting documents in columns</u></h2></a> + +<p> +Setting documents in columns is easy with <strong>mom</strong>. (Of +course she'd say that, but it's true!) 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#TERMS_GUTTER">gutters</a>). +That's it. <strong>Mom</strong> takes care of everything else, from +soup to nuts. +</p> + +<h3><u>Some words of advice</u></h3> + +<p> +If you want your type to achieve a pleasing +<a href="definitions.html#TERMS_JUST">justification</a> +or +<a href="definitions.html#TERMS_RAG">rag</a> +in columns, reduce the point size of type (and probably the +<a href="definitions.html#TERMS_LEADING">leading</a> +as well). <strong>Mom</strong>'s default document point +size is 12.5, which works well across her default 39 +<a href="definitions.html#TERMS_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'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- --> + +<hr width="33%" align="left"/> + +<a name="COLUMNS"></a> + +<p> +<nobr>Macro: <strong>COLUMNS</strong> <kbd><number of columns> <width of gutters></kbd></nobr> +<br/> + +<em>*Should be the last macro before</em> START +<br/> + +<em>The second argument requires a <a href="definitions.html#TERMS_UNITOFMEASURE">unit of measure</a></em> +</p> + +<p> +<strong>COLUMNS</strong> takes two arguments: the number of +columns you want on document pages, and the width of the +<a href="definitions.html#TERMS_GUTTER">gutter</a> +between them. For example, to set up a page with two columns +separated by an 18 point gutter, you'd do + +<pre> + .COLUMNS 2 18p +</pre> +</p> + +<p> +Nothing to it, really. However, as noted above, +<strong>COLUMNS</strong> should always be the last document +setup macro prior to +<a href="#START">START</a>. +</p> + +<p> +<strong>NOTE:</strong> <strong>Mom</strong> ignores columns completely +when the +<a href="#PRINTSTYLE">PRINTSTYLE</a> +is <strong>TYPEWRITE</strong>. The notion of typewriter-style +output in columns is just too ghastly for her to bear. +</p> + +<h4><u>Using tabs when COLUMNS are enabled</u></h4> + +<p> +<strong>Mom</strong>'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'd expect during document processing, even when +<strong>COLUMNS</strong> are enabled. Tab structures set up +during document processing carry over from page to page and column +to column. +</p> + +<!-- -BREAKING COLUMNS- --> + +<a name="BREAKING_COLUMNS"><h4><u>Breaking columns manually</u></h4></a> + +<p> +<strong>Mom</strong> 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: <strong>COL_NEXT</strong> and <strong>COL_BREAK</strong>. +</p> + +<a name="COL_NEXT"></a> + +<p> +<kbd>.COL_NEXT</kbd> breaks the line just before it, +<a href="definitions.html#TERMS_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, <strong>mom</strong> starts a new page +at the "column 1" position. This is the macro to use when +you want to start a new column after the end of a paragraph. +</p> + +<a name="COL_BREAK"></a> + +<p> +<kbd>.COL_BREAK</kbd> is almost the same, except that +instead of breaking and quadding the line preceding it, +she 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> + +<p> +If you need <strong>COL_BREAK</strong> in the middle of a blockquote +or (god help you) an epigraph, you must do the following in order for +<strong>COL_BREAK</strong> to work: + +<pre> + .SPREAD + \!.COL_BREAK +</pre> +</p> + +<hr/> + +<!-- ======================================================================== --> + +<a name="DOC_PARAM_MACROS"><h2><u>Changing global style parameters after START</u></h2></a> + +<p> +In the normal course of things, you change the basic type +parameters of a document <em>before</em> +<a href="#START">START</a>, +using +<a href="typesetting.html#MACROS_TYPESETTING">typesetting macros</a> +(<strong>L_MARGIN, FAMILY, PT_SIZE, LS,</strong> etc). After +<strong>START</strong>, you MUST use the following macros to make +global changes to the basic type parameters of a document. +</p> + +<a name="INDEX_DOC_PARAM"><h3><u>Macro list</u></h3></a> + +<ul> + <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> + +<!-- -DOC_LEFT_MARGIN --> + +<hr width="66%" align="left"/> + +<a name="DOC_LEFT_MARGIN"></a> + +<p> +<nobr>Macro: <strong>DOC_LEFT_MARGIN</strong> <kbd><left margin></kbd></nobr> +<br/> + +<em>*Requires a <a href="definitions.html#TERMS_UNITOFMEASURE">unit of measure</a></em> +</p> + +<ul> + <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 --> + +<hr width="33%" align="left"/> + +<a name="DOC_RIGHT_MARGIN"></a> + +<p> +<nobr>Macro: <strong>DOC_RIGHT_MARGIN</strong> <kbd><right margin></kbd></nobr> +<br/> + +<em>*Requires a <a href="definitions.html#TERMS_UNITOFMEASURE">unit of measure</a></em> +</p> + +<ul> + <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#TERMS_DOCHEADER">docheaders</a>, + headers (or footers) and page numbering to the new value; + for changing the right margin of + <a href="definitions.html#TERMS_RUNNING">running text</a> + only, use + <a href="typesetting.html#R_MARGIN">R_MARGIN</a> + (see + <a href="typemacdoc.html#TOP">Using typesetting macros during + document processing</a>, + entry for <strong>R_MARGIN</strong>) + </li> + <li>all mom commands that include a right indent calculate + the indent from the new value + </li> +</ul> + +<!-- -DOC_RIGHT_MARGIN --> + +<hr width="33%" align="left"/> + +<a name="DOC_LINE_LENGTH"></a> + +<p> +<nobr>Macro: <strong>DOC_LINE_LENGTH</strong> <kbd><length></kbd></nobr> +<br/> + +<em>*Requires a <a href="definitions.html#TERMS_UNITOFMEASURE">unit of measure</a></em> +</p> + +<ul> + <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#TERMS_RUNNING">running text</a> + only, use + <a href="typesetting.html#LINELENGTH">LL</a> + (see + <a href="typemacdoc.html#TOP">Using typesetting macros during + document processing</a>, + entry for <strong>LL</strong>) + </li> +</ul> + +<!-- -DOC_FAMILY- --> + +<hr width="33%" align="left"/> + +<a name="DOC_FAMILY"></a> + +<p> +<nobr>Macro: <strong>DOC_FAMILY</strong> <kbd><family></kbd></nobr> +</p> + +<ul> + <li>the argument is the same as for + <a href="typesetting.html#FAMILY">FAMILY</a> + </li> + <li>globally changes the type family for</li> + <ul> + <li>the <a href="definitions.html#TERMS_DOCHEADER">docheader</a></li> + <li>all <a href="docelement.html#INDEX_DOCELEMENT">document element tags</a>, including footnotes</li> + <li><a href="definitions.html#TERMS_HEADER">headers and/or footers</a></li> + <li><a href="docelement.html#NUMBER_LINES_INTRO">line numbering</a></li> + <li><a href="headfootpage.html#PAGINATION">page numbering</a></li> + </ul> + <li>does <em>not</em> change the family of</li> + <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>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- --> + +<hr width="33%" align="left"/> + +<a name="DOC_PT_SIZE"></a> + +<p> +<nobr>Macro: <strong>DOC_PT_SIZE</strong> <kbd><point size></kbd></nobr> +<br/> + +<em>*Does not require a <a href="definitions.html#TERMS_UNITOFMEASURE">unit of measure</a>; points is assumed</em> +</p> + +<ul> + <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- --> + +<hr width="33%" align="left"/> + +<a name="DOC_LEAD"></a> + +<p> +<nobr>Macro: <strong>DOC_LEAD</strong> <kbd><points></kbd> [ ADJUST ]</nobr> +<br/> + +<em>*Does not require a <a href="definitions.html#TERMS_UNITOFMEASURE">unit of measure</a>; points is assumed</em> +</p> + +<ul> + <li>the argument is the same as for + <a href="typesetting.html#LEADING">LS</a>, + and refers to the + <a href="definitions.html#TERMS_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 <strong>ADJUST</strong> performs + leading adjustment as explained in + <a href="#DOC_LEAD_ADJUST">DOC_LEAD_ADJUST</a> + </li> +</ul> + +<p> +<strong>IMPORTANT:</strong> Do not use <strong>DOC_LEAD</strong> +in the middle of a page! It should always and only be invoked +immediately prior to a new page, like this: + +<pre> + .DOC_LEAD <new value> + .NEWPAGE +</pre> +</p> + +<p> +<strong>NOTE:</strong> Even if you don't pass +<strong>DOC_LEAD</strong> the optional argument +<kbd>ADJUST</kbd>, <strong>mom</strong> 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> + +<!-- -DOC_QUAD- --> + +<hr width="33%" align="left"/> + +<a name="DOC_QUAD"></a> + +<p> +<nobr>Macro: <strong>DOC_QUAD</strong> <kbd>L | R | C | J</kbd></nobr> +</p> + +<ul> + <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> + +<hr/> + +<p> +<a href="typemacdoc.html#TOP">Next</a> +<a href="color.html#TOP">Prev</a> +<a href="#TOP">Top</a> +<a href="toc.html">Back to Table of Contents</a> +</p> + +</body> +</html> + +<!-- vim: fileencoding=latin1: nomodified: +--> diff --git a/contrib/mom/momdoc/goodies.html b/contrib/mom/momdoc/goodies.html new file mode 100644 index 00000000..db30bc33 --- /dev/null +++ b/contrib/mom/momdoc/goodies.html @@ -0,0 +1,1435 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!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=iso-8859-1"/> +<title>Mom -- Goodies</title> +</head> +<body bgcolor="#dfdfdf"> + +<!-- ==================================================================== --> + +<a name="TOP"></a> + +<p> +<a href="inlines.html#TOP">Next</a> +<a href="typesetting.html#TOP">Prev</a> +<a href="toc.html">Back to Table of Contents</a> +</p> + +<a name="GOODIES"><h1 align="center"><u>Goodies</u></h1></a> + +<p> +The macros in this section are a collection of useful (and sometimes +nearly indispensable) routines to simplify typesetting. +</p> + +<a name="INDEX_GOODIES"><h3><u>Goodies list</u></h3></a> + +<ul> + <li><a href="#ALIAS">ALIAS</a> (rename macros)</li> + <li><a href="#SILENT">SILENT</a> ("hide" input lines from output)</li> + <li><a href="#TRAP">TRAP</a> (suspend/re-invoke traps)</li> + <li><a href="#SMARTQUOTES">SMARTQUOTES</a> (convert typewriter doublequotes to proper doublequotes)</li> + <li><a href="#CAPS">CAPS</a> (convert to upper case)</li> + <li><a href="#STRING">STRING</a> (user-definable strings)</li> + <li><a href="#ESC_CHAR">ESC_CHAR</a> (change to escape character to something other than a backslash)</li> + <li><strong>Underscore/underline</strong></li> + <ul> + <li><a href="#UNDERSCORE">UNDERSCORE</a> (single underscore)</li> + <li><a href="#UNDERSCORE2">UNDERSCORE2</a> (double underscore)</li> + <li><a href="#UNDERLINE">UNDERLINE</a> (underline — Courier only!)</li> + <li><a href="#UL">\*[UL]</a> (inline escape to underline — Courier only!)</li> + </ul> + <li><strong>Padding</strong></li> + <ul> + <li><a href="#PAD">PAD</a> (insert equalized space into lines)</li> + <li><a href="#PAD_MARKER">PAD_MARKER</a> (change/set the marker used with <strong>PAD</strong>)</li> + </ul> + <li><strong>Leaders</strong></li> + <ul> + <li><a href="#LEADER">\*[LEADER]</a> (inline escape to add leaders to a line)</li> + <li><a href="#LEADER_CHARACTER">LEADER_CHARACTER</a> (change/set the leader character)</li> + </ul> + <li><strong>Drop caps</strong></li> + <ul> + <li><a href="#DROPCAP">DROPCAP</a> (set a drop cap)</li> + <li><strong>Support macros for DROPCAP</strong></li> + <ul> + <li><a href="#DROPCAP_FAMILY">DROPCAP_FAMILY</a> (change drop cap family)</li> + <li><a href="#DROPCAP_FONT">DROPCAP_FONT</a> (change drop cap font)</li> + <li><a href="#DROPCAP_ADJUST">DROPCAP_ADJUST</a> (alter size of drop cap)</li> + <li><a href="#DROPCAP_COLOR">DROPCAP_COLOR</a> (change colour of drop cap)</li> + <li><a href="#DROPCAP_GUTTER">DROPCAP_GUTTER</a> (change space between drop cap and running text)</li> + </ul> + </ul> + <li><strong>Superscripts</strong></li> + <ul> + <li><a href="#SUP">\*[SUP]</a> (set superscript)</li> + <li><a href="#CONDSUP">\*[CONDSUP]</a> (set condensed superscript)</li> + <li><a href="#EXTSUP">\*[EXTSUP]</a> (set extended superscript)</li> + </ul> + <li><strong>Lists</strong></li> + <ul> + <li><a href="docelement.html#LIST_INTRO">Introduction to lists</a></li> + <li><a href="docelement.html#LIST">LIST</a></li> + <li><a href="docelement.html#ITEM">ITEM</a></li> + <li><a href="docelement.html#SHIFT_LIST">SHIFT_LIST</a></li> + <li><a href="docelement.html#RESET_LIST">RESET_LIST</a></li> + <li><a href="docelement.html#PAD_LIST_DIGITS">PAD_LIST_DIGITS</a></li> + </ul> +</ul> + +<!-- -ALIAS- --> + +<hr width="66%" align="left"/> + +<a name="ALIAS"><h3><u>Rename macros</u></h3></a> + +<p> +<nobr>Macro: <strong>ALIAS</strong> <kbd><new name> <old name></kbd></nobr> +</p> + +<p> +The <strong>ALIAS</strong> 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 +<strong>mom</strong>; 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. +<strong>Mom</strong> doesn't like people to feel intimidated; +she wants them to feel welcome. Consequently, she tries +for easy-to-grasp, self-explanatory macro names. However, +<strong>mom</strong> 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'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't like one of <strong>mom</strong>'s macro names, +say, PAGEWIDTH, change it, like this: + +<pre> + .ALIAS PW PAGEWIDTH + | | + new__| |__official + name name +</pre> +</p> + +<p> +The first argument to <strong>ALIAS</strong> is the new name you +want for a macro. The second is the "official" name by +which the macro is normally invoked. After <strong>ALIAS</strong>, +either can be used. +</p> + +<p> +Note that in <strong>ALIAS</strong>, you do NOT include the period +(dot) that precedes the macro when it's a +<a href="definitions.html#TERMS_CONTROLLINES">control line</a>. +</p> + +<p> +<strong>NOTE:</strong> If you use <strong>ALIAS</strong> a lot, and +always for the same things, consider creating an aliases file of the +form + +<pre> + .ALIAS <new name> <old name> + .ALIAS <new name> <old name> + .ALIAS <new name> <old name> + ...etc +</pre> + +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 <kbd>mom_aliases</kbd> in your home directory under +a directory called <kbd>Mom</kbd>, you'd source it by placing + +<pre> + .INCLUDE /home/<username>/Mom/mom_aliases +</pre> + +at the top of your documents. +</p> + +<p> +If you share documents that make use of an alias file, remember that +other people don't have the file! Paste the whole thing at the top +of your documents, please. +</p> + +<p> +<strong>EXPERTS:</strong> <strong>ALIAS</strong> is an alias +of <kbd>.als</kbd>. You can use either, or mix 'n' match with +impunity. +</p> + +<!-- -SILENT- --> + +<hr width="33%" align="left"/> + +<a name="SILENT"><h3><u>Hide input lines from output</u></h3></a> + +<p> +<nobr>Macro: <strong>SILENT</strong> <kbd>toggle</kbd></nobr> +<br/> + +Alias: <strong>COMMENT</strong> +</p> + +<p> +Sometimes, you want to "hide" +<a href="definitions.html#TERMS_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't want input lines +to appear in the output, use the <strong>SILENT</strong> macro. +</p> + +<p> +<strong>SILENT</strong> is a toggle. Invoking it without an argument +turns it on; any argument turns it off. E.g., + +<pre> + .SILENT + A line of text + .SILENT OFF +</pre> +</p> + +<p> +The line "A line of text" will not appear in the +output copy. +</p> + +<p> +<strong>SILENT</strong> is aliased as <strong>COMMENT</strong>. +If you want to insert non-printing comments into your documents, +you may prefer this. +</p> + +<p> +<strong>NOTE: SILENT</strong> does not automatically break an +<a href="definitions.html#TERMS_INPUTLINE">input line</a> +(see +<a href="typesetting.html#BR">BR</a>) +when you're in one of the +<a href="definitions.html#TERMS_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 <strong>J</strong> or +<strong>QUAD</strong> argument. You must insert <kbd>.BR</kbd> +yourself, or risk a portion of your text disappearing into a black +hole. +</p> + +<!-- -TRAP- --> + +<hr width="33%" align="left"/> + +<a name="TRAP"><h3><u>Suspend/re-invoke traps</u></h3></a> + +<p> +<nobr>Macro: <strong>TRAP</strong> <kbd>toggle</kbd></nobr> +</p> + +<p> +Traps are vertical positions on the output page at which you or +<strong>mom</strong> 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't want them. If this +happens, surround just the offending macros and input lines with + +<pre> + .TRAP OFF + ... + .TRAP +</pre> +</p> + +<p> +<strong>TRAP</strong> is a toggle, therefore any argument +turns it off (i.e. suspends the trap), and no argument turns it +(back) on. +</p> + +<!-- -SMARTQUOTES- --> + +<hr width="33%" align="left"/> + +<a name="SMARTQUOTES"><h3><u>Convert typewriter doublequotes to proper doublequotes</u></h3></a> + +<p> +<nobr>Macro: <strong>SMARTQUOTES</strong> <kbd>[<off>] [ ,, | >> | << ]</kbd></nobr> +<br/> + +or +<br/> + +<nobr>Macro: <strong>SMARTQUOTES</strong> <kbd>DA | DE | ES | FR | IT | NL | NO | PT | SV</kbd></nobr> +</p> + +<p> +If you invoke <strong>SMARTQUOTES</strong> without an argument, +<strong>mom</strong> 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 +doublequotes — 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't want to look like an amateur, do you? +</p> + +<a name="SQ_INTERNATIONAL"><h3><u>Internationalization</u></h3></a> + +<p> +If you invoke <strong>SMARTQUOTES</strong> with one of the +optional arguments (<kbd>,,</kbd> or <kbd>>></kbd> +or <kbd><<</kbd>) you can use <kbd>"</kbd> as +"cheap" open-and close-quotes when inputting text in a +language other than English, and have <strong>mom</strong> convert +them, on output, into the chosen open-and close-quote style. +</p> + +<p> +<kbd>,,</kbd> opens quotes with "lowered doublequotes" and +closes them with "raised doublequotes", as in this ascii +approximation: + +<pre> + ,,Hilfe !`` +</pre> + +<kbd>>></kbd> opens quotes with guillemets pointing to the +right, and closes them with guillemets pointing to the left, as in +this ascii approximation: + +<pre> + >>Zurück !<< +</pre> +</p> + +<p> +<kbd><<</kbd> opens quotes with guillemets pointing to the +left, and closes them with guillemets pointing to the right, as in +this ascii approximation: + +<pre> + <<Mais monsieur! Je ne suis pas ce genre de fille!>> +</pre> +</p> + +<p> +Please note: the above arguments to <strong>SMARTQUOTES</strong> +are literal ASCII characters. <kbd>,,</kbd> is two commas, +<kbd><<</kbd> is two less-than signs and <kbd>>></kbd> +is two greater-than signs. +</p> + +<p> +Alternatively, you can pass <strong>SMARTQUOTES</strong> the +two-letter, ISO 639 abbreviation for the language you're writing in, +and <strong>mom</strong> will output the correct quotes. + +<pre> + .SMARTQUOTES DA = Danish >>text<< + .SMARTQUOTES DE = German ,,text`` + .SMARTQUOTES ES = Spanish ``text““ + .SMARTQUOTES FR = French << text >> + .SMARTQUOTES IT = Italian << text >> + .SMARTQUOTES NL = Dutch ““text““ + .SMARTQUOTES NO = Norwegian <<text>> + .SMARTQUOTES PT = Portuguese <<text>> + .SMARTQUOTES SV = Swedish >>text>> +</pre> +</p> + +<p> +Turn <strong>SMARTQUOTES</strong> off by passing it any argument +<em>not</em> in the argument list (e.g. <strong>OFF</strong>, +<strong>QUIT</strong>, <strong>X</strong>, etc.) +</p> + +<p> +If you're using the +<a href="docprocessing.html#DOCPROCESSING">document processing macros</a> +with +<a href="docprocessing.html#PRINTSTYLE">PRINTSTYLE TYPESET</a>, +<strong>SMARTQUOTES</strong> is on by default (in the Anglo-American +style); with +<a href="docprocessing.html#PRINTSTYLE">PRINTSTYLE TYPEWRITE</a>, +it's off by default (and should probably stay that way). +</p> + +<p> +Finally, if you'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's native +<a href="definitions.html#TERMS_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 <strong>mom</strong>'s +<a href="inlines.html#INLINE_KERNING_MOM">inline kerning escapes</a> +to fine-tune the look of quotes. +</p> + +<p> +<strong>NOTE:</strong> <strong>SMARTQUOTES</strong> does not work on +single quotes, which most people input with the apostrophe (found +at the right-hand end of the "home row" 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, +"backtick" veut dire l'accent grave.) Here's an example +of correct input copy with single quotes: + +<pre> + "But she said, `I don't want to!'" +</pre> +</p> + +<p> +<strong>ADDITIONAL NOTE:</strong> Whether or not you have +<strong>SMARTQUOTES</strong> turned on, get into the habit of +entering the foot-and inch-marks, when you need them, with the +<a href="definitions.html#TERMS_INLINES">inline escapes</a> +<kbd>\*[FOOT]</kbd> and <kbd>\*[INCH]</kbd>, instead of <kbd>'</kbd> +and <kbd>"</kbd>. +</p> + +<!-- -CAPS- --> + +<hr width="33%" align="left"/> + +<a name="CAPS"><h3><u>Convert to upper case</u></h3></a> + +<p> +<nobr>Macro: <strong>CAPS</strong> <kbd>toggle</kbd></nobr> +</p> + +<p> +<strong>CAPS</strong> converts all lower case letters to upper case. +Primarily, it's a support macro used by the +<a href="docprocessing.html#DOCPROCESSING">document processing macros</a>, +but you may find it helpful on occasion. <strong>CAPS</strong> is +a toggle, therefore no argument turns it on, any argument +(<strong>OFF, QUIT, X,</strong> etc.) turns it +off. + +<pre> + .CAPS + All work and no play makes Jack a dull boy. + .CAPS OFF +</pre> + +produces, on output + +<pre> + ALL WORK AND NO PLAY MAKES JACK A DULL BOY. +</pre> +</p> + +<p> +If you wish to capitalise a section of type inlines, use the +<a href="definitions.html#TERMS_INLINES">inline escapes</a>, +<a href="inlines.html#UC_LC"><kbd>\*[UC]...\*[LC]</kbd></a> +like this: + +<pre> + All work \*[UC]and\*[LC] no play makes Jack a dull boy. +</pre> + +The above produces, on output + +<pre> + All work AND no play makes Jack a dull boy. +</pre> +</p> + +<p> +The inline escapes are especially useful for capitalizing +<strong>mom</strong>'s +<a href="headfootpage.html#RESERVED_STRINGS">reserved strings</a> +(document title, author[s], etc) when designing your own +<a href="headfootpage.html#HEADFOOTPAGE_INTRO">HEADERS and FOOTERS</a> +when using the +<a href="docprocessing.html#DOCPROCESSING">document processing macros</a>. +</p> + +<!-- -STRING- --> + +<hr width="33%" align="left"/> + +<a name="STRING"><h3><u>User-defined strings</u></h3></a> + +<p> +<nobr>Macro: <strong>STRING</strong> <kbd><name> <what you want in the string></kbd></nobr> +</p> + +<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're creating a document that repeatedly uses +the phrase "the Montreal/Windsor corridor". Instead of +typing all that out every time, you could define a string, like +this: + +<pre> + .STRING mw the Montreal/Windsor corridor +</pre> +</p> + +<p> +Once a string is defined, you can call it any time with the +<a href="definitions.html#INLINES">inline escape</a> +<kbd>\*[<stringname>]</kbd>. Using the example string above + +<pre> + The schedule for trains along \*[mw]: +</pre> + +produces, on output + +<pre> + The schedule for trains along the Montreal/Windsor corridor: +</pre> +</p> + +<p> +<strong>NOTE:</strong> Be very careful not to put any spaces at the +ends of strings you're defining, unless you want them. Everything +after the name argument you pass to <strong>STRING</strong> goes +into the string, including trailing spaces. +</p> + +<p> +<strong>Experts: STRING</strong> is an alias for <strong>ds</strong>. +You can use either, or mix 'n' match with impunity. +</p> + +<!-- -ESC_CHAR- --> + +<hr width="33%" align="left"/> + +<a name="ESC_CHAR"><h3><u>Change the escape character</u></h3></a> + +<p> +<nobr>Macro: <strong>ESC_CHAR</strong> <kbd><new character> | <anything></kbd></nobr> +</p> + +<p> +<strong>Groff</strong>'s and <strong>mom</strong>'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 +<nobr>(<kbd>\\</kbd>),</nobr> which is convenient if you don'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 <strong>ESC_CHAR</strong> to make the change permanent +(until you decide to restore the escape character to its default, +the backslash). +</p> + +<p> +<strong>ESC_CHAR</strong> with a single character argument +changes the escape character to whatever the argument is. +<strong>ESC_CHAR</strong> with no argument restores the escape +character to the backslash. +</p> + +<p> +<strong>Experts</strong>: <strong>ESC_CHAR</strong> is an alias of +<kbd>.ec</kbd>. Mix 'n' match the two with impunity. +</p> + +<!-- -UNDERSCORE- --> + +<hr width="33%" align="left"/> + +<a name="UNDERSCORE"><h3><u>Single underscore</u></h3></a> + +<p> +<nobr>Macro: <strong>UNDERSCORE</strong> <kbd>[ <distance below baseline> ] "<string>"</kbd></nobr> +<br/> + +<em>*Optional argument requires a <a href="definitions.html#TERMS_UNITOFMEASURE">unit of measure</a></em> +</p> + +<p> +By default, <strong>UNDERSCORE</strong> places an underscore 2 +points beneath the required +<a href="definitions.html#TERMS_STRINGARGUMENT">string argument</a>. +The string must be enclosed in double-quotes, like this: + +<pre> + .UNDERSCORE "Unmonitored monopolies breed high prices and poor products." +</pre> +</p> + +<p> +If you wish to change the distance of the rule from the +baseline, use the optional argument <kbd><distance below +baseline></kbd> (with a unit of measure). + +<pre> + .UNDERSCORE 3p "Unmonitored monopolies breed high prices and poor products." +</pre> +</p> + +<p> +The above places upper edge of the underscore 3 points below the +<a href="definitions.html#TERMS_BASELINE">baseline</a>. +</p> + +<a name="UNDERSCORE_WEIGHT"></a> + +<h4><u>Controlling the weight of underscores</u></h4> + +<p> +(Please note that <strong>UNDERSCORE_WEIGHT</strong> also sets the +weight of +<a href="#UNDERSCORE2">double underscores.</a>) +</p> + +<p> +The weight (thickness) of underscores may be controlled with the +macro, <strong>UNDERSCORE_WEIGHT</strong>. Thus, if you want +underscores with a weight of 1-1/2 points, you'd invoke: + +<pre> + .UNDERSCORE_WEIGHT 1.5 +</pre> + +prior to invoking <kbd>.UNDERSCORE</kbd>. Every subsequent +instance of <kbd>.UNDERSCORE</kbd> will use this weight. +</p> + +<p> +<strong>Mom</strong>'s default underscore weight is 1/2 point. +</p> + +<a name="NOTES_UNDERSCORE"></a> + +<h4><u>NOTES:</u></h4> + +<p> +<strong>UNDERSCORE</strong> does not work across line breaks in +output copy, which is to say that you can't underscore a multi-line +passage simply by putting the text of the whole thing in the string +you pass to <strong>UNDERSCORE</strong>. Each +<a href="definitions.html#TERMS_OUTPUTLINE">output line</a> +or portion of an output line you want underscored must be plugged +separately into <strong>UNDERSCORE</strong>. 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'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're using the document processing macro +<a href="#PRINTSTYLE">PRINTSTYLE TYPEWRITE</a>), +with the +<a href="#UNDERLINE">UNDERLINE</a> +macro. <strong>UNDERLINE</strong> is designed specifically for this +purpose, but works only with the monspaced fonts. +</p> + +<p> +<strong>Mom</strong> doesn't always get the position and length +of the underscore precisely right in +<a href="definitions.html#TERMS_JUST">justified</a> +copy, although she's fine with all the other +<a href="definitions.html#TERMS_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't happen until <em>after</em> the line has been processed +in all other respects — including establishing how long to +make an underscore. A workaround is to prepend the backslash +character <nobr>(<kbd>\</kbd>)</nobr> to each word space in the +string passed to <strong>UNDERSCORE</strong>. The word spacing of +the underscored string <em>may</em> be slightly smaller than the +word space of the remainder of the line, but in many cases, the +difference isn't visually noticeable. +</p> + +<p> +<strong>UNDERSCORE</strong> tends to confuse +<strong>gxditview</strong>, even though the output, when +printed, looks fine. Generally, I recommend using <strong>gv</strong> +to preview files anyway. See the section on +<a href="using.html#USING_PREVIEWING">previewing</a>. +</p> + +<p> +<a name="UNDERSCORE_COLOR"><strong>Colorizing underscored text:</strong></a> +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 + +<pre> + .COLOR red + .UNDERSCORE "text to underscore" + .COLOR black +</pre> + +rather than + +<pre> + .UNDERSCORE "\*[red]text to underscore\*[black]" +</pre> + +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: + +<pre> + .UNDERSCORE "\*[red]text to underscore\*[blue]" + .COLOR black +</pre> +</p> + +<!-- -UNDERSCORE2- --> + +<hr width="33%" align="left"/> + +<a name="UNDERSCORE2"><h3><u>Double underscore</u></h3></a> + +<p> +<nobr>Macro: <strong>UNDERSCORE2</strong> [ <distance below baseline> [ <distance between rules> ] ] "<string>"</nobr> +<br/> + +<em>*Optional arguments require a <a href="definitions.html#TERMS_UNITOFMEASURE">unit of measure</a></em> +</p> + +<p> +By default, <strong>UNDERSCORE2</strong> places a double underscore +2 points beneath the required +<a href="definitions.html#TERMS_STRINGARGUMENT">string argument</a>. +The string must be enclosed in double-quotes, like this: + +<pre> + .UNDERSCORE2 "Unmonitored monopolies breed high prices and poor products." +</pre> +</p> + +<p> +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 baseline, use the optional argument <kbd><distance below +baseline></kbd> (with a unit of measure), e.g., + +<pre> + .UNDERSCORE2 3p "Unmonitored monopolies breed high prices and poor products." +</pre> + +which places the upper edge of the first rule of the double +underscore 3 points below the +<a href="definitions.html#TERMS_BASELINE">baseline</a>. +</p> + +<p> +If you wish to change the distance between the two rules as +well, use the second optional argument <kbd><distance between +rules></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> + +<p> +<strong>NOTE:</strong> the same restrictions and caveats apply +to <strong>UNDERSCORE2</strong> as to +<strong>UNDERSCORE</strong>. See the +<a href="#NOTES_UNDERSCORE">NOTES</a> +for <strong>UNDERSCORE</strong>. +</p> + +<!-- -UNDERLINE- --> + +<hr width="33%" align="left"/> + +<a name="UNDERLINE"><h3><u>Underline text — monospaced fonts only</u></h3></a> + +<p> +<nobr>Macro: <strong>UNDERLINE</strong> <kbd>toggle</kbd></nobr> +</p> + +<p> +If your font is monospaced one, like Courier, or you're using the +document processing macro +<a href="#PRINTSTYLE">PRINTSTYLE TYPEWRITE</a>, +<strong>UNDERLINE</strong> allows you to underline words and +passages that, in typeset copy, would be italicized. You invoke +<kbd>.UNDERLINE</kbd> as you do with all toggle macros — by +itself (i.e. with no argument) to initiate underlining, and with any +argument (<strong>OFF, QUIT, X,</strong> etc) to turn underlining +off. +</p> + +<p> +When on, <strong>UNDERLINE</strong> underlines letters, words +and numbers, but not punctuation or spaces. This makes for more +readable copy than a solid underline. +</p> + +<p> +<strong>NOTE:</strong> Underlining may also be turned on and off +<a href="definitions.html#TERMS_INLINES">inline</a> +with the escapes +<a href="#UL"><kbd>\*[UL]...\*[ULX]</kbd></a>. +</p> + +<!-- -UL- --> + +<hr width="33%" align="left"/> + +<a name="UL"><h3><u>Inline escape for underlining — monospaced fonts only</u></h3></a> + +<p> +Inline: <kbd>\*[UL]...\*[ULX]</kbd> +</p> + +<p> +If your font is a monospaced one, like Courier, or you'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 +<a href="#UNDERLINE">UNDERLINE</a> +and the inline escape <kbd>\*[UL]</kbd> are functionally +identical, hence + +<pre> + .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 +</pre> + +produces the same result as + +<pre> + .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] +</pre> +</p> + +<!-- -PAD- --> + +<hr width="33%" align="left"/> + +<a name="PAD"><h3><u>Insert space into lines</u></h3></a> + +<p> +<nobr>Macro: <strong>PAD</strong> <kbd>"<string with pad markers inserted>" [ NOBREAK ]</kbd></nobr> +</p> + +<p> +With <strong>PAD</strong>, you can insert unspecified amounts of +whitespace into a line. + +<a name="NOBREAK"></a> + +The optional <kbd>NOBREAK</kbd> argument tells <strong>mom</strong> +not to advance on the page after the <strong>PAD</strong> macro has +been invoked. +</p> + +<p> +<strong>PAD</strong> 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: + +<pre> + Date Signature | +</pre> +</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, | 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 # (the pound or number sign on your keyboard) and can +be used multiple times in a line. With that in mind, here's how +you'd input the Date/Signature line (assuming a length of 30 picas): + +<pre> + .LL 30P + .PAD "Date#Signature###" +</pre> +</p> + +<p> +When the line is output, the space remaining on the line, after +"Date" and "Signature" 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> + +<a name="PAD_EXAMPLE"></a> + +<p> +One rarely wants merely to insert space in a line; one usually +wants to fill it with something, hence <strong>PAD</strong> 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 +<strong>mom</strong>'s +<a href="definitions.html#TERMS_INLINES">inline escape</a> +<a href="inlines.html#INLINE_RULE_MOM"><kbd>\*[RULE]</kbd></a>. +(Instead of <kbd>\*[RULE]</kbd>, +groff's line drawing function, +<a href="inlines.html#INLINE_LINEDRAWING_GROFF"><kbd>\l</kbd></a> +could be used.) + +<pre> + .LL 30P + .PAD "Date \*[ST1]#\*[ST1X] Signature \*[ST2]###\*[ST2X]" NOBREAK + .ST 1 J + .ST 2 J + .TAB 1 + \*[RULE] + .TN + \*[RULE] + .TQ +</pre> +</p> + +<p> +If you're not a typesetter, and if you'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: + +<ol> + <li>Pads the Date/Signature line (using the pad marker + <kbd>#</kbd>), encloses the padded space with two string + tabs markers, and outputs the line without advancing on the + page. + </li> + <li>Sets the two string tabs. + </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> + +<p> +Often, when setting up string tabs this way, you don't want the +padded line to print immediately. To accomplish this, use +<a href="#SILENT">SILENT</a>. +See the +<a href="typesetting.html#STRING_TABS_TUT">quickie tutorial on string tabs</a> +for an example. +</p> + +<p> +<strong>NOTE:</strong> Because the pound sign +<nobr>(<kbd>#</kbd>)</nobr> is used as the pad marker, you can'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 +<a href="#PAD_MARKER">PAD_MARKER</a>. +Also, be aware that <kbd>#</kbd> as a pad marker only applies +within the <strong>PAD</strong> macro; at all other times it prints +literally, just as you'd expect. +</p> + +<p> +Another important consideration when using <strong>PAD</strong> is that +because the string must be enclosed in double-quotes, you can't use the +double-quote <nobr>(<kbd>"</kbd>)</nobr> as part of the string. The +way to circumvent this is to use the groff +<a href="definitions.html#TERMS_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 <strong>PAD</strong>. +</p> + +<!-- -PAD_MARKER- --> + +<hr width="33%" align="left"/> + +<a name="PAD_MARKER"><h3><u>Change/set the marker used with PAD</u></h3></a> + +<p> +<nobr>Macro: <strong>PAD_MARKER</strong> <character to use as the pad marker></nobr> +</p> + +<p> +If you need to change <strong>mom</strong>'s default pad marker +<nobr>(<kbd>#</kbd>),</nobr> either because you want a literal # in +the padded line, or simply because you want to use another character +instead, use <strong>PAD_MARKER</strong>, whose argument is the new +pad marker character you want. + +<pre> + .PAD_MARKER @ +</pre> + +changes the pad marker to @. +</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]- --> + +<hr width="33%" align="left"/> + +<a name="LEADER"><h3><u>Inline escape to add leaders to a line</u></h3></a> + +<p> +Inline: <kbd>\*[LEADER]</kbd> +</p> + +<p> +Whenever you want to fill a line or tab with +<a href="definitions.html#TERMS_LEADER">leaders</a>, +use the +<a href="definitions.html#TERMS_INLINES">inline escape</a> +<kbd>\*[LEADER]</kbd>. The remainder of the line or tab will be +filled with the leader character. <strong>Mom</strong>'s default +leader character is a period (dot), but you can change it to any +character you like with +<a href="#LEADER_CHARACTER">LEADER_CHARACTER</a>. +</p> + +<p> +<strong>NOTE:</strong> <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. + +<pre> + .LL 30P + .PAD "Date\*[ST1]#\*[ST1X]Signature\*[ST2]###\*[ST2X]" + .EL + .ST 1 J + .ST 2 J + .TAB 1 + \*[LEADER] + .TN + \*[LEADER] + .TQ +</pre> +</p> + +<p> +The <strong>PAD</strong> line sets the words Date and Signature, +and marks string tabs around the pad space inserted in the line. +The string tabs are then "set", called, and filled +with leaders. The result looks like this: + +<pre> + Date.............Signature..................................... +</pre> +</p> + +<!-- -LEADER_CHARACTER- --> + +<hr width="33%" align="left"/> + +<a name="LEADER_CHARACTER"><h3><u>Change/set the leader character</u></h3></a> + +<p> +<nobr>Macro: <strong>LEADER_CHARACTER</strong> <kbd><character></kbd></nobr> +</p> + +<p> +<strong>LEADER_CHARACTER</strong> takes one argument: a single +character you would like to be used for +<a href="definitions.html#TERMS_LEADER">leaders</a>. +(See +<a href="#LEADER"><kbd>\*[LEADER]</kbd></a> +for an explanation of how to fill lines with leaders.) +</p> + +<p> +For example, to change the leader character from <strong>mom</strong>'s +default (a period) to the underscore character, enter + +<pre> + .LEADER_CHARACTER _ +</pre> +</p> + +<!-- -DROPCAP- --> + +<hr width="33%" align="left"/> +<a name="DROPCAP"><h3><u>Drop caps</u></h3></a> + +<p> +<nobr>Macro: <strong>DROPCAP</strong> <kbd><dropcap letter> <number of lines to drop> [ COND <percentage> | EXT <percentage> ]</kbd></nobr> +</p> + +<p> +The first two arguments to <strong>DROPCAP</strong> are the letter you +want to be the +<a href="definitions.html#TERMS_DROPCAP">drop cap</a> +and the number of lines you want it to drop. By default, +<strong>mom</strong> uses the current family and font for the drop +cap. +</p> + +<p> +The optional argument <nobr>(<kbd>COND</kbd> or +<kbd>EXT</kbd>)</nobr> indicates that you want the drop +cap condensed (narrower) or extended (wider). If you use +<kbd>COND</kbd> or <kbd>EXT</kbd>, you must follow the argument with +the percentage of the letter's normal width you want it condensed or +extended. No percent sign (%) is required. +</p> + +<p> +<strong>Mom</strong> 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 "T" looks +like this: + +<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... +</pre> +</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's text will revert to the left margin. +</p> + +<p> +<strong>NOTE:</strong> When using the +<a href="docprocessing.html#DOCPROCESSING">document processing macro</a> +<a href="docelement.html#PP">PP</a>, +<strong>DROPCAP</strong> only works + +<ul> + <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>and when the + <a href="docprocessing.html#PRINTSTYLE">PRINTSTYLE</a> + is TYPESET.</li> +</ul> + +If these conditions aren't met, <strong>DROPCAP</strong> is silently ignored. +</p> + +<p> +<strong>WARNING:</strong> <strong>DROPCAP</strong> 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 <strong>mom</strong> does her thing. +</p> + +<h4><a name="DROPCAP_SUPPORT"><u>Support macros for DROPCAP</u></a></h4> + +<p> +Drop caps are the bane of most typesetters' existence. It'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'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> +<strong>Mom</strong> 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 +<strong>DROPCAP</strong>, namely +</p> + +<p> +<a href="#DROPCAP_FAMILY">DROPCAP_FAMILY</a> +<br/> + +<a href="#DROPCAP_FONT">DROPCAP_FONT</a> +<br/> + +<a href="#DROPCAP_COLOR">DROPCAP_COLOR</a> +<br/> + +<a href="#DROPCAP_ADJUST">DROPCAP_ADJUST</a> +<br/> + +and +<br/> + +<a href="#DROPCAP_GUTTER">DROPCAP_GUTTER</a>. +</p> + +<p> +These macros must, of course, come before you invoke +<strong>DROPCAP</strong>. +</p> + +<h4><a name="DROPCAP_FAMILY"><u>DROPCAP_FAMILY</u></a></h4> + +<p> +Set the drop cap family by giving +<strong>DROPCAP_FAMILY</strong> the name of the family you want, +e.g. + +<pre> + .DROPCAP_FAMILY H +</pre> + +which will set the family to Helvetica for the drop cap only. +</p> + +<h4><a name="DROPCAP_FONT"><u>DROPCAP_FONT</u></a></h4> + +<p> +Set the drop cap font by giving +<strong>DROPCAP_FONT</strong> the name of the font you want, +e.g. + +<pre> + .DROPCAP_FONT I +</pre> + +which will set the font to italic for the drop cap only. +</p> + +<h4><a name="DROPCAP_ADJUST"><u>DROPCAP_ADJUST</u></a></h4> + +<p> +If the size <strong>mom</strong> calculates for the drop cap +isn't precisely what you want, you can increase or decrease it +with <strong>DROPCAP_ADJUST</strong>, like this: +e.g. + +<pre> + .DROPCAP_ADJUST +1 + or + .DROPCAP_ADJUST -.75 +</pre> +</p> + +<p> +<strong>DROPCAP_ADJUST</strong> only understands +<a href="definitions.html#TERMS_PICASPOINTS">points</a>, +therefore do not append any +<a href="definitions.html#TERMS_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> + +<h4><a name="DROPCAP_COLOR"><u>DROPCAP_COLOR</u></a></h4> + +<p> +If you'd like your drop cap colourized, simply invoke +<strong>DROPCAP_COLOR</strong> with the name of a colour you've already +created ("initialized") 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> + +<h4><a name="DROPCAP_GUTTER"><u>DROPCAP_GUTTER</u></a></h4> + +<p> +By default, <strong>mom</strong> puts three points of space +between the drop cap and the text indented beside it. If you +want another value, use <strong>DROPCAP_GUTTER</strong> (with a +unit of measure), like this: + +<pre> + .DROPCAP_GUTTER 6p +</pre> +</p> + +<!-- -\*[SUP]- --> + +<hr width="33%" align="left"/> + +<a name="SUP"><h3><u>Superscript</u></h3></a> + +<p> +Inlines: <kbd>\*[SUP]...\*[SUPX]</kbd> +</p> + +<p> +Superscripts are accomplished +<a href="definitions.html#TERMS_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> + +<a name="CONDSUP"></a> +<a name="EXTSUP"></a> + +<p> +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> + +<p> +<strong>NOTE:</strong> <strong>Mom</strong> does a pretty fine job of +making superscripts look good in any font and at any size. If you'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's no <strong>mom</strong> equivalent for subscripts. +I'm neither a mathematician nor a chemist, so I don't need them. +Of course, anyone who wishes to contribute a subscript routine to +<strong>mom</strong> will receive eternal blessings not only in this +lifetime, but in all lifetimes to come. +</p> + +<hr/> + +<a href="inlines.html#TOP">Next</a> +<a href="typesetting.html#TOP">Prev</a> +<a href="#TOP">Top</a> +<a href="toc.html">Back to Table of Contents</a> + +</body> +</html> + +<!-- vim: fileencoding=latin1: nomodified: +--> diff --git a/contrib/mom/momdoc/graphical.html b/contrib/mom/momdoc/graphical.html new file mode 100644 index 00000000..3c21a969 --- /dev/null +++ b/contrib/mom/momdoc/graphical.html @@ -0,0 +1,578 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!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=iso-8859-1"/> +<title>Mom -- Graphical Objects</title> +</head> +<body bgcolor="#dfdfdf"> + +<!-- ==================================================================== --> + +<a name="TOP"></a> + +<p> +<a href="docprocessing.html#TOP">Next</a> +<a href="color.html#TOP">Prev</a> +<a href="toc.html">Back to Table of Contents</a> +</p> + +<h1 align="center"><a name="COLOR_INTRO"><u>Graphical objects</u></a></h1> + +<p> +<a href="#INTRO_GRAPHICAL">Introduction to graphical objects</a> + +<ul> + <li><a href="#BEHAVIOUR">Graphical object behaviour</a></li> + <li><a href="#ORDER">Order of arguments</a></li> +</ul> + +<a href="#MACROS_GRAPHICAL">Index of graphical object macros</a> +</p> + +<a name="INTRO_GRAPHICAL"><h2><u>Introduction to graphical objects</u></h2></a> + +<p> +<strong>Groff</strong> has a number of +<a href="definitions.html#TERMS_INLINES">inline escapes</a> +for drawing rules, polygons, ellipses and splines. All begin with +<kbd>\D</kbd> (presumably for "Draw") and are documented +in the <strong>groff</strong> info manual: + +<pre> + info groff => Escape index => \D +</pre> +</p> + +<p> +The escapes allow you to draw just about any simple graphical object +you can think of, but owing to their syntax, they're not always easy +to read, which can make tweaking them difficult. Additionally, +while they perform in a <em>consistent</em> manner, they don't +always perform in an <em>expected</em> 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, <strong>mom</strong> provides macros +to draw these objects in an easy-to-understand way; the results are +predictable, and <strong>mom</strong>'s syntax makes fixes or tweaks +painless. +</p> + +<a name="GRAPHICAL_EXAMPLE"></a> + +<p> +For example, if you want to draw a 2-inch square outline box at the left +margin using <strong>groff</strong>'s <kbd>\D</kbd> escapes, it looks like this: + +<pre> + 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 +</pre> + +Obviously, this isn't very efficient for something as simple as a +box. +</p> + +<p> +Here's the same box, drawn with <strong>mom</strong>'s box drawing +macro, +<a href="#DBX">DBX</a>: + +<pre> +left margin indent-+ +-box width + | | + .DBX .5 0 2i 2i + | | + rule weight--+ +-box depth + (in points) +</pre> +</p> + +<p> +<strong>Mom</strong>'s graphical object macros allow — in fact, +require — giving the rule weight ("thickness") 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 <strong>mom</strong>'a +graphical object macros, which means you must supply the arguments +every time you invoke them. +</p> + +<p> +<strong>NOTE:</strong> As stated above, <strong>mom</strong> only +provides macros for commonly-used graphical objects (rules, boxes, +circles) only. More complex objects (polygons, non-straight lines, +splines) must be drawn using <strong>groff</strong>'s <kbd>\D</kbd> +escapes. +</p> + +<a name="BEHAVIOUR"><h3><u>Graphical object behaviour</u></h3></a> + +<p> +<strong>Mom</strong>'s graphical object macros all behave in the +following, carved-in-stone ways: + +<ol> + <li>Objects are drawn from the + <a href="definitions.html#TERMS_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 <em>inward</em>.</li> + <li>Objects return to their horizontal/vertical point of origin.</li> +</ol> + +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're placed and how much room they occupy. +Furthermore, because all return to their point of origin, you'll +know exactly where you are on the page. +</p> + +<a name="ORDER"><h3><u>Order of arguments</u></h3></a> + +<p> +The order of arguments to the graphical object macros is the same +for every macro: + +<ul> + <li>the <strong>Weight</strong> of the rule</li> + <ul> + <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 <strong>weight</strong> argument if you want the + object filled</li> + </ul> + <li>the <strong>Indent</strong> from the current left margin at + which to begin the object</li> + <li>the <strong>Length</strong> of the object, if applicable</li> + <li>the <strong>Depth</strong> of the object, if applicable</li> + <li>the <strong>Colour</strong> of the object (optional)</li> +</ul> +</p> + +<p> +A simple mnemonic for the order of arguments is "WILD C". +If you fix the mnemonic in your brain and apply a little judicious +reasoning, you'll always remember how to draw graphical objects. +The "judicious reasoning" means that, for example, +horizontal rules don't require a depth and vertical rules don't +require a length. Thus, in the case of drawing a horizontal rule, +you supply the macro, +<a href="#DRH">DRH</a>, +with only the arguments (from the mnemonic) that apply: W-I-L (and +possibly C). +</p> + +<a name="MACROS_GRAPHICAL"><h3><u>Index of graphical object macros</u></h3></a> + +<ul> + <li><a href="#DRH">DRH</a> + — horizontal rule</li> + <li><a href="#DRV">DRV</a> + — vertical rule</li> + <li><a href="#DBX">DBX</a> + — box</li> + <li><a href="#DCL">DCL</a> + — circle or ellipse</li> +</ul> + +<!-- -DRH- --> + +<hr width="66%" align="left"/> + +<a name="DRH"><h3><u>Drawing horizontal rules</u></h3></a> + +<p> +<nobr>Macro: <strong>DRH</strong> <kbd><none> | <rule weight> <indent> <length> [<colour>]</kbd></nobr> +<br/> + +<em>*The argument to</em> <kbd><rule weight></kbd> <em>is +in</em> +<a href="definitions.html#TERMS_PICASPOINTS">points</a>, +<em>but do </em> NOT <em>append the</em> +<a href="definitions.html#TERMS_UNITSOFMEASURE">unit of +measure</a>, <kbd>p</kbd>. +<br/> + +<em>*The arguments,</em> <kbd><indent></kbd> <em>and</em> +<kbd><length></kbd>, <em>require a unit of measure.</em> +</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 "full +measure" rule), you may invoke <kbd>.DRH</kbd> without any +arguments. (Note that <strong>DRH</strong> is the only graphical +object macro that may be invoked without arguments.) The weight of +the rule is determined by the argument you last gave the macro, +<a href="inlines.html#RULE_WEIGHT">RULE_WEIGHT</a>. +<strong>DRH</strong>, used this way, is exactly equivalent to +entering the +<a href="definitions.html#TERMS_INLINES">inline escape</a>, +<a href="inlines.html#INLINE_RULE_MOM"><kbd>\*[RULE]</kbd></a>. +</p> + +<p> +To draw horizontal rules of a specified length, you must, at a +minimum, supply +<strong>DRH</strong> with the arguments +<kbd><nobr>rule weight,</nobr> 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 +<strong>XCOLOR</strong>). +</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: + +<pre> + weight length + | | + .DRH 1.125 2P 3i + | + indent +</pre> + +(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: + +<pre> + .DRH 1.125 2P 3i blue +</pre> +</p> + +<h3><u>How mom handles the positioning of horizontal rules</u></h3> + +<p> +Horizontal rules are drawn from left to right, and from the baseline +down. "From the baseline down" 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, <strong>mom</strong> returns +you to the current left margin, at the same vertical position on +the page as when <strong>DRH</strong> was invoked. In other words, +<strong>DRH</strong> causes no movement on the page, either +horizontal or vertical. +</p> + +<!-- -DRV- --> + +<hr width="33%" align="left"/> + +<a name="DRV"><h3><u>Drawing vertical rules</u></h3></a> + +<p> +<nobr>Macro: <strong>DRV</strong> <kbd><rule weight> <indent> <depth> [<colour>]</kbd></nobr> +<br/> + +<em>*The argument to</em> <kbd><rule weight></kbd> <em>is +in</em> +<a href="definitions.html#TERMS_PICASPOINTS">points</a>, +<em>but do </em> NOT <em>append the</em> +<a href="definitions.html#TERMS_UNITSOFMEASURE">unit of +measure</a>, <kbd>p</kbd>. +<br/> + +<em>*The arguments,</em> <kbd><indent></kbd> <em>and</em> +<kbd><depth></kbd>, <em>require a unit of measure.</em> +</p> + +<p> +To draw vertical rules of a specified length, you must, at a +minimum, supply +<strong>DRV</strong> with the arguments +<kbd><nobr>rule weight,</nobr> 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 +<strong>XCOLOR</strong>). +</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: + +<pre> + weight depth + | | + .DRV .75 19P+6p 6c + | + indent +</pre> + +(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: + +<pre> + .DRV .75 19P+6p 6c red +</pre> +</p> + +<h3><u>How mom handles the positioning of vertical rules</u></h3> + +<p> +Vertical rules are drawn from the baseline down, and from left to +right. "Left to right" 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 <strong>DRV</strong>. +</p> + +<p> +Furthermore, after the rule is drawn, <strong>mom</strong> returns +you to the current left margin, at the same vertical position +on the page as when <strong>DRV</strong> was invoked. In other +words, <strong>DRV</strong> causes no movement on the page, either +horizontal or vertical. +</p> + +<!-- -DBX- --> + +<hr width="33%" align="left"/> + +<a name="DBX"><h3><u>Drawing boxes</u></h3></a> + +<p> +<nobr>Macro: <strong>DBX</strong> <kbd>< <rule weight> | SOLID > <indent> <length> <depth> [<colour>]</kbd></nobr> +<br/> + +<em>*The argument to</em> <kbd><rule weight></kbd> <em>is +in</em> +<a href="definitions.html#TERMS_PICASPOINTS">points</a>, +<em>but do </em> NOT <em>append the</em> +<a href="definitions.html#TERMS_UNITSOFMEASURE">unit of +measure</a>, <kbd>p</kbd>. +<br/> + +<em>*The arguments,</em> <kbd><indent></kbd><em>,</em> +<kbd><length></kbd> <em>and</em> <kbd><depth></kbd> +<em>require a unit of measure.</em> +</p> + +<p> +To draw boxes of specified dimensions, you must, at a minimum, +supply <strong>DBX</strong> with the arguments <kbd><nobr>rule +weight</nobr></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 +<strong>XCOLOR</strong>). +</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: + +<pre> + indent depth + | | + .DBX .5 1i 12P 6P + | | + weight length +</pre> + +(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> + +If you want the same box, but solid ("filled") rather +than drawn as an outline: + +<pre> + .DBX SOLID 1i 12P 6P +</pre> + +<p> +Additionally, if you want the box green: + +<pre> + .DBX .5 1i 12P 6P green + or + .DBX SOLID 1i 12P 6P green +</pre> +</p> + +<h3><u>How mom handles the positioning of boxes</u></h3> + +<p> +Boxes are drawn from the baseline down, from left to right, and +from the perimeter <em>inward</em>. "From the perimeter +inward" 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 +<em>within</em> the dimensions of the box. +</p> + +<p> +Furthermore, after the box is drawn, <strong>mom</strong> returns +you to the current left margin, at the same vertical position +on the page as when <strong>DBX</strong> was invoked. In other +words, <strong>DBX</strong> causes no movement on the page, either +horizontal or vertical. +</p> + +<!-- -DCL- --> + +<hr width="33%" align="left"/> + +<a name="DCL"><h3><u>Drawing circles (ellipses)</u></h3></a> + +<p> +<nobr>Macro: <strong>DCL</strong> <kbd>< <rule weight> | SOLID > <indent> <length> <depth> [<colour>]</kbd></nobr> +<br/> + +<em>*The argument to</em> <kbd><rule weight></kbd> <em>is +in</em> +<a href="definitions.html#TERMS_PICASPOINTS">points</a>, +<em>but do </em> NOT <em>append the</em> +<a href="definitions.html#TERMS_UNITSOFMEASURE">unit of +measure</a>, <kbd>p</kbd>. +<br/> + +<em>*The arguments,</em> <kbd><indent></kbd><em>,</em> +<kbd><length></kbd> <em>and</em> <kbd><depth></kbd> +<em>require a unit of measure.</em> +</p> + +<p> +To draw circles of specified dimensions, you must, at a minimum, +supply <strong>DCL</strong> with the arguments <kbd><nobr>rule +weight</nobr></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 +<strong>XCOLOR</strong>). +</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: + +<pre> + indent depth + | | + .DCL .5 1i 6c 3c + | | + weight ength +</pre> + +(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> + +If you want the same box, but solid ("filled") rather +than drawn as an outline: + +<pre> + .DCL SOLID 1i 6c 3c +</pre> + +<p> +Additionally, if you want the circle yellow: + +<pre> + .DCL .5 1i 6c 3c yellow + or + .DCL SOLID 1i 6c 3c yellow +</pre> +</p> + +<h3><u>How mom handles the positioning of circles (ellipses)</u></h3> + +<p> +Circles (ellipses) are drawn from the baseline down, from left +to right, and from the perimeter <em>inward</em>. "From the +perimeter inward" means that if you request a box weight of six +points, the 6-point rule used to draw the outline of the circle or +ellipse falls entirely <em>within</em> the dimensions of the circle +or ellipse. +</p> + +<p> +Furthermore, after the circle is drawn, <strong>mom</strong> returns +you to the current left margin, at the same vertical position +on the page as when <strong>DCL</strong> was invoked. In other +words, <strong>DCL</strong> causes no movement on the page, either +horizontal or vertical. +</p> + +<hr/> + +<p> +<a href="docprocessing.html#TOP">Next</a> +<a href="color.html#TOP">Prev</a> +<a href="#TOP">Top</a> +<a href="toc.html">Back to Table of Contents</a> +</p> + +</body> +</html> + +<!-- vim: fileencoding=latin1: nomodified: +--> diff --git a/contrib/mom/momdoc/headfootpage.html b/contrib/mom/momdoc/headfootpage.html new file mode 100644 index 00000000..2041a1f7 --- /dev/null +++ b/contrib/mom/momdoc/headfootpage.html @@ -0,0 +1,2229 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!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=iso-8859-1"/> +<title>Mom -- Document processing: headers, footers and pagination</title> +</head> +<body bgcolor="#dfdfdf"> + +<!-- ==================================================================== --> + +<a name="TOP"></a> + +<p> +<a href="rectoverso.html#TOP">Next</a> +<a href="docelement.html#TOP">Prev</a> +<a href="toc.html">Back to Table of Contents</a> +</p> + +<a name="HEADFOOTPAGE"><h1 align="center"><u>Page headers, footers, and pagination</u></h1></a> + +<ul> + <li><a href="#HEADFOOTPAGE_INTRO">Introduction — VERY IMPORTANT; read me!</a></li> + <ul> + <li><a href="#PAGINATION_NOTE">An important note on pagination</a></li> + </ul> + <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> + <li><a href="#HEADFOOT_MANAGEMENT">Managing headers/footers</a> — see also <a href="#HEADFOOT_TOC">Control macros for headers/footers</a></li> + <ul> + <li><a href="#HEADERS">HEADERS</a> — on or off</li> + <li><a href="#FOOTERS">FOOTERS</a> — on or off</li> + <li><a href="#FOOTER_ON_FIRST_PAGE">FOOTER_ON_FIRST_PAGE</a></li> + <li><a href="#USERDEF_HDRFTR">User-defined, single string recto/verso headers/footers</a></li> + <ul> + <li><a href="#USERDEF_HDRFTR_INTRO">Introduction</a></li> + <li><a href="#HDRFTR_RECTOVERSO">HEADER_RECTO, HEADER_VERSO</a></li> + <li><a href="#RESERVED_STRINGS">Using mom's "reserved" strings in header/footer definitions</a> + (title, author, etc.) + </li> + </ul> + <li><a href="#HEADERS_AND_FOOTERS">HEADERS_AND_FOOTERS</a> + — putting both headers and footers on document pages + </li> + </ul> + <a name="HEADFOOT_TOC"></a> + <li><a href="#HEADFOOT_CONTROL">Control macros for headers/footers</a></li> + <ul> + <li><a href="#HDRFTR_STRINGS">Header/footer strings</a></li> + <ul> + <li><a href="#RESERVED_STRINGS">Using mom's "reserved" strings in header/footer definitions</a> + (title, author, etc.) + </li> + </ul> + <li><a href="#HDRFTR_STYLE">Header/footer style</a></li> + <ul> + <li><a href="#HDRFTR_STYLE_GLOBAL">Global style control</a></li> + <li><a href="#HDRFTR_STYLE_PART">Part-by-part style control</a></li> + </ul> + <li><a href="#HDRFTR_VERTICAL">Vertical placement and spacing of headers/footers</a></li> + <ul> + <li><a href="#HDRFTR_MARGIN">HEADER_MARGIN</a></li> + <li><a href="#HDRFTR_GAP">HEADER_GAP</a></li> + </ul> + <li><a href="#HDRFTR_SEPARATOR">The header/footer separator rule</a></li> + <ul> + <li><a href="#HDRFTR_RULE">HEADER_RULE</a> — on or off</li> + <li><a href="#HDRFTR_RULE_WEIGHT">HEADER_RULE_WEIGHT</a> — weight of the rule</li> + <li><a href="#HDRFTR_RULE_GAP">HEADER_RULE_GAP</a> — distance of rule from header/footer</li> + <li><a href="#HDRFTR_RULE_COLOR">HEADER_RULE_COLOR</a> — colour of the header/footer rule</li> + </ul> + </ul> + <li><a href="#PAGINATION">Pagination</a></li> + <ul> + <li><a href="#INDEX_PAGINATION">Pagination control macros</a></li> + </ul> +</ul> + +<a name="HEADFOOTPAGE_INTRO"><h2><u>Introduction</u></h2></a> + +<p> +<a href="definitions.html#TERMS_HEADER">Headers</a> +and +<a href="definitions.html#TERMS_FOOTER">footers</a>, +as defined in the section +<a href="definitions.html#TERMS_MOM">Mom'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#TERMS_RUNNING">running text</a>. +They are, in all respects but two, identical. The differences are: + +<ol> + <li>headers appear in the margin <em>above</em> running text while + footers appear in the margin <em>beneath</em> running text; + </li> + <li>the (optional) rule that separates headers from running + text appears <em>below</em> the header while + the (optional) rule that separates footers from running + text appears <em>above</em> the footer. + </li> +</ol> +</p> + +<a name="HEADERFOOTER"></a> + +<p> +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> +Furthermore, any +<a href="definitions.html#TERMS_CONTROLMACRO">control macro</a> +that begins with <strong>HEADER_</strong> may be used to control +footers, simply by replacing <strong>HEADER_</strong> with +<strong>FOOTER_</strong>. +</p> + +<p> +<strong>Author's note:</strong> Left to their own devices (i.e. if +you're happy with the way <strong>mom</strong> 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> + +<a name="PAGINATION_NOTE"></a> + +<p> +<strong>NOTE:</strong> While the single page number that +<strong>mom</strong> generates in either the top or bottom margin +above or below running text is technically a kind of header/footer, +<strong>mom</strong> and this documentation treat it as a +separate page element. +</p> + +<a name="DESCRIPTION_GENERAL"><h3><u>General description of headers/footers</u></h3></a> + +<p> +Headers comprise three distinct parts: a left part, a centre part, +and a right part. Each part contains text (a "string") +that identifies some aspect of the document as a whole. +</p> + +<p> +The left part ("header left") lines up with the document's +left margin. The centre part ("header centre") is +centred on the document's line length. The right part ("header +right") lines up with the document's right margin. Not all parts +need contain a string, and if you don't want headers at all, you can +turn them off completely. +</p> + +<p> +<strong>A note to groff experts:</strong> Although +<strong>mom</strong>'s headers resemble the three-part titles +generated by <kbd>.tl</kbd>, they're in no way related to +it, nor based upon it. <kbd>.tl</kbd> is not used at all in +<strong>mom</strong>. +</p> + +<p> +Normally, <strong>mom</strong> 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 — including +page numbers — to go in any part of headers. What'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, <strong>mom</strong> prints a horizontal rule beneath +headers to separate them visually from running text. In the case of +footers, the rule is <em>above</em> running text. You can increase +or decrease the space between the header and the rule if you like +(with +<a href="#HDRFTR_RULE_GAP">HEADER_RULE_GAP</a>), +or remove it completely. +</p> + +<a name="HEADER_STYLE"><h3><u>Default specs for headers/footers</u></h3></a> + +<p> +<strong>Mom</strong> 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 +<strong>mom</strong> puts by default in each part are explained in +<a href="docprocessing.html#DOCTYPE">DOCTYPE</a>.) +</p> + +<p> +<strong>NOTE:</strong> Except for capitalization (all caps or +caps/lower-case), these defaults apply only to +<a href="docprocessing.html#PRINTSTYLE">PRINTSTYLE TYPESET</a>. +</p> + +<pre> +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 +</pre> + +<p> +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, <strong>mom</strong> 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> + +<a name="VERTICAL_SPACING"><h3><u>Vertical placement and spacing of headers/footers</u></h3></a> + +<p> +As explained in the section on +<a href="typemacdoc.html">typesetting macros in document processing</a>, +the top and bottom margins of a <strong>mom</strong> document +are the vertical start and end positions of +<a href="definitions.html#TERMS_RUNNING">running text</a>, +not the vertical positions of headers or footers, which, by definition, +appear in the margins <em>above</em> (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 <em>top</em> edge of the page. +The header rule, whose position is relative to the header itself, +is controlled by a separate macro. +<strong>FOOTER_MARGIN</strong> establishes the baseline position of +footers relative to the <em>bottom</em> edge of the page. +</p> + +<p> +<a href="#HDRFTR_GAP">HEADER_GAP</a> +establishes the distance between headers and the <em>start</em> +of running text (effectively making <strong>HEADER_MARGIN + +HEADER_GAP</strong> the top margin of running text unless you give +<strong>mom</strong> a literal top margin (with +<a href="typesetting.html#T_MARGIN">T_MARGIN</a>), +in which case she ignores <strong>HEADER_GAP</strong> and starts +running text at whatever top margin you gave. +<strong>FOOTER_GAP</strong> and +<a href="typesetting.html#B_MARGIN">B_MARGIN</a> +work similarly, except they determine where running text +<em>ends</em> on the page. (See +<a href="#FOOTER_MARGIN">FOOTER MARGIN AND BOTTOM MARGIN — VERY IMPORTANT!</a> +for a warning about possible conflicts between the footer margin and +the bottom margin.) +</p> + +<p> +Confused? <strong>Mom</strong> apologizes. It's really quite +simple. By default, <strong>mom</strong> sets headers 4-1/2 +<a href="definitions.html#TERMS_PICASPOINTS">picas</a> +down from the top of the page and starts running text 3 picas (the +<strong>HEADER_GAP</strong>) beneath that, which means the effective +top margin of running text is 7-1/2 picas (visually approx. 1 inch). +If you give <strong>mom</strong> a literal top margin (with +<a href="typesetting.html#T_MARGIN">T_MARGIN</a>), +she ignores the <strong>HEADER_GAP</strong> and starts running +text at whatever top margin you gave. +</p> + +<p> +Footers are treated the same way, the only difference being the +default distances. <strong>Mom</strong> sets footers 3 picas up from +the bottom of the page, and interrupts the processing of running +text 3 picas (the <strong>FOOTER_GAP</strong>) above that (again, +visually approx. 1 inch). If you give <strong>mom</strong> a +literal bottom margin (with +<a href="typesetting.html#B_MARGIN">B_MARGIN</a>), +she ignores the <strong>FOOTER_GAP</strong> and interrupts the +processing of running text at whatever bottom margin you gave. +</p> + +<p> +If <strong>mom</strong> 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> + +<hr/> + +<!-- ======================================================================== --> + +<a name="HEADFOOT_MANAGEMENT"><h2><u>Managing headers/footers</u></h2></a> + +<h3><u>Macro list</u></h3> + +<ul> + <li><a href="#HEADERS">HEADERS</a> — on or off</li> + <li><a href="#FOOTERS">FOOTERS</a> — on or off</li> + <li><a href="#FOOTER_ON_FIRST_PAGE">FOOTER_ON_FIRST_PAGE</a></li> + <li><a href="#USERDEF_HDRFTR">User-defined, single string recto/verso headers/footers</a></li> + <ul> + <li><a href="#USERDEF_HDRFTR_INTRO">Introduction</a></li> + <li><a href="#HDRFTR_RECTOVERSO">HEADER_RECTO, HEADER_VERSO</a></li> + <li><a href="#RESERVED_STRINGS">Using mom's "reserved" strings in header/footer definitions</a> + (title, author, etc.) + </li> + </ul> + <li><a href="#HEADERS_AND_FOOTERS">HEADERS_AND_FOOTERS</a> + — putting both headers and footers on document pages + </li> + <li><a href="#HEADFOOT_CONTROL">Header and footer control macros</a></li> +</ul> + +<p> +The following are the basic macros for turning +<a href="definitions.html#TERMS_HEADER">headers</a> +or +<a href="definitions.html#TERMS_FOOTER">footers</a> +on or off. They should be invoked prior to +<a href="docprocessing.html#START">START</a>. +</p> + +<p> +By default, <strong>mom</strong> prints page headers. If you turn +them off, she will begin +<a href="definitions.html#TERMS_RUNNING">running text</a> +on each page with a default top margin of 6 +<a href="definitions.html#TERMS_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> + +<p> +Please note that +<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'd prefer footers in a +document, you need only invoke +<a href="#FOOTERS"><kbd>.FOOTERS</kbd></a>; +there's no need to turn headers off first. +</p> + +<p> +If you need both headers and footers, there's a special macro, +<a href="#HEADERS_AND_FOOTERS">HEADERS_AND_FOOTERS</a>, +that allows you to set this up. +</p> + +<!-- -HEADERS- --> + +<hr width="66%" align="left"/> + +<a name="HEADERS"></a> + +<p> +<nobr>Macro: <strong>HEADERS</strong> <kbd>toggle</kbd></nobr> +</p> + +<p> +<a href="definitions.html#TERMS_HEADER">Page headers</a> +are on by default. If you don't want them, turn them off by +invoking <kbd>.HEADERS</kbd> with any argument (<strong>OFF, QUIT, +END, X...</strong>), e.g. + +<pre> + .HEADERS OFF +</pre> +</p> + +<p> +<strong>NOTE:</strong> <strong>HEADERS</strong> automatically +disables +<a href="definitions.html#TERMS_FOOTER">footers</a> +(you can't have both), but not the page numbers that normally +appear at the bottom of the page. +</p> + +<p> +<strong>ADDITIONAL NOTE:</strong> If <strong>HEADERS</strong> +are <strong>OFF</strong>, <strong>mom</strong>'s normal top +margin for +<a href="definitions.html#TERMS_RUNNING">running text</a> +(7.5 +<a href="definitions.html#TERMS_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 +<a href="#FOOTERS">FOOTERS</a>). +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- --> + +<hr width="33%" align="left"/> + +<a name="FOOTERS"></a> + +<p> +<nobr>Macro: <strong>FOOTERS</strong> <kbd>toggle</kbd></nobr> +</p> + +<p> +<a href="definitions.html#TERMS_FOOTER">Page footers</a> +are off by default. If you want them instead of +<a href="definitions.html#TERMS_HEADER">headers</a> +(you can't have both), turn them on by invoking +<kbd>.FOOTERS</kbd> without an argument, e.g. + +<pre> + .FOOTERS +</pre> +</p> + +<p> +<strong>FOOTERS</strong> automatically disables headers, and +<strong>mom</strong> shifts the placement of page numbers from their +normal position at page bottom to the top of the page. +</p> + +<p> +<strong>NOTE:</strong> By default, when footers are on, +<strong>mom</strong> 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't want this behaviour, you can change it with +<a href="#PAGENUM_ON_FIRST_PAGE">PAGENUM_ON_FIRST_PAGE</a>. +</p> + +<!-- -FOOTER_ON_FIRST_PAGE- --> + +<hr width="33%" align="left"/> + +<a name="FOOTER_ON_FIRST_PAGE"></a> + +<p> +<nobr>Macro: <strong>FOOTER_ON_FIRST_PAGE</strong> <kbd>toggle</kbd></nobr> +</p> + +<p> +If you invoke +<a href="#FOOTERS"><kbd>.FOOTERS</kbd></a>, +<strong>mom</strong>, 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> + +<hr/> + +<!-- -USERDEF_HDRFTR- --> + +<a name="USERDEF_HDRFTR"><h2><u>User-defined, single string recto/verso headers/footers</u></h2></a> + +<a name="USERDEF_HDRFTR_INTRO"><h3><u>Introduction</u></h3></a> + +<p> +Sometimes, you'll find you can't get <strong>mom</strong>'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's author, centred, and verso page headers to contain the +document's title, also centred, like this: + +<pre> + +------------------------+ +------------------------+ + | Author | | Title | + | | | | + | | | | + | | | | + | | | | + | | | | + | | | | + | | | | + | | | | + | | | | + | | | | + | | | | + | | | | + | | | | + +------------------------+ +------------------------+ +</pre> +</p> + +<p> +With <strong>mom</strong>'s standard 3-part headers, this isn't +possible, even when +<a href="rectoverso.html#RECTO_VERSO">RECTO_VERSO</a> +is enabled. <strong>RECTO_VERSO</strong> 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, <strong>mom</strong> 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_RECTOVERSO">HEADER_RECTO</a> +and +<a href="#HDRFTR_RECTOVERSO">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#TERMS_STRINGARGUMENT">string argument</a> +with which, by combining text and +<a href="definitions.html#TERMS_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, <strong>mom</strong> provides a special +mechanism whereby it's possible to "pad" the string as +well. +</p> + +<!-- -HDRFTR_RECTOVERSO- --> + +<hr width="66%" align="left"/> + +<a name="HDRFTR_RECTOVERSO"></a> + +<p> +<nobr>Macro: <strong>HEADER_RECTO</strong> <kbd>LEFT | CENTER | RIGHT "<header recto string>"</kbd></nobr> +<br/> + +<nobr>Macro: <strong>HEADER_VERSO</strong> <kbd>LEFT | CENTER | RIGHT "<header verso string>"</kbd></nobr> +<br/> +</p> + +<p> +<strong>HEADER_RECTO</strong> and <strong>HEADER_VERSO</strong> +behave identically, hence all references to +<strong>HEADER_RECTO</strong> in this section also +refer to <strong>HEADER_VERSO</strong>. Furthermore, +<strong>FOOTER_</strong> can be used instead of +<strong>HEADER_</strong> to set up recto/verso footers. +</p> + +<p> +The first argument to <strong>HEADER_RECTO</strong> is the +direction in which you want the header +<a href="definitions.html#TERMS_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>. The second argument is a string, +surrounded by double-quotes, containing what you want in the header. +<strong>HEADER_RECTO</strong> disables <strong>mom</strong>'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#TERMS_INLINES">inline escape</a> +<a href="color.html#COLOR_INLINE"><kbd>\*[<colorname>]</kbd></a>). +</p> + +<p> +By default, <strong>HEADER_RECTO</strong> 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#TERMS_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> inline. +</p> + +<a name="PADDING_HDRFTR"><h4>*<u>Padding the HEADER_RECTO/HEADER_VERSO string</u></h4></a> + +<p> +You can "pad" the header-recto string, a convenience +you'll appreciate in circumstances such as the following. + +<pre> + VERSO RECTO + +------------------------+ +------------------------+ + | Author Page# | | Page# Title | + | | | | + | | | | + | | | | + | | | | + | | | | + | | | | + | | | | + | | | | + | | | | + | | | | + | | | | + | | | | + | | | | + +------------------------+ +------------------------+ +</pre> +</p> + +<p> +To pad the string argument passed to <strong>HEADER_RECTO</strong>, +begin and end the string (inside the double-quotes) with the caret +character (<kbd>^</kbd>). Enter the pound sign (<kbd>#</kbd>) +at any point in the string where you want an equalized amount of +whitespace inserted. (If you're unsure what padding is, see +<a href="goodies.html#PAD">Insert space into lines</a>.) +Note that if you're padding the string, it doesn't matter what quad +direction you give <strong>HEADER_RECTO</strong> since padding, by +its nature, justifies text to the left and right margins. +</p> + +<p> +The situation depicted above is accomplished like this: + +<pre> + .HEADER_RECTO LEFT "^\*[PAGE#]#\E*[$TITLE]^" + .HEADER_VERSO LEFT "^\E*[$AUTHOR]#\*[PAGE#]^" +</pre> +</p> + +<p> +Note that <strong>mom</strong> does not interpret the <kbd>#</kbd> +in <kbd>\*[PAGE#]</kbd> as a padding marker (i.e. as a place to +insert whitespace). +</p> + +<p> +Also, notice that the argument, <kbd>LEFT</kbd>, is used in both +cases. When padding a header, it doesn't matter whether you use +<kbd>LEFT, CENTER</kbd> or <kbd>RIGHT</kbd> as the argument. +</p> + +<p> +Furthermore, should you need a user-defined header of +the sort provided by <strong>HEADER_RECTO</strong> and +<strong>HEADER_VERSO</strong> but aren't actually printing +recto/verso, you can use <strong>HEADER_RECTO</strong> to design the +header that appears at the top of every page. +</p> + +<p> +<strong>IMPORTANT:</strong> 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 +<strong>HEADER_RECTO</strong> string. If you absolutely must +have a literal pound sign in your <strong>HEADER_RECTO</strong> +string, use the escape sequence for the pound sign +<nobr>( <kbd>\[sh]</kbd> )</nobr> where you want the pound sign +to go. +</p> + +<!-- -HDRFTR_RECTOVERSO- --> + +<hr width="33%" align="left"/> + +<a name="HEADERS_AND_FOOTERS"></a> + +<p> +<nobr>Macro: <strong>HEADERS_AND_FOOTERS </strong></nobr> +<br/> + +Invocation: +<pre> + .HEADERS_AND_FOOTERS \ + <L | C | R> "<recto header string>" \ + <L | C | R> "<recto footer string>" \ + <L | C | R> "<verso header string>" \ + <L | C | R> "<verso footer string>" + +or + + .HEADERS_AND_FOOTERS <anything> +</pre> +</p> + +<p> +<strong>HEADERS_AND_FOOTERS</strong> allows you to have both +headers and footers on the same page. +</p> + +<p> +Unlike the macros, +<a href="#HEADERS">HEADERS</a> +and +<a href="#FOOTERS">FOOTERS</a>, +<strong>HEADERS_AND_FOOTERS</strong> requires that you supply +the information you want in the headers and footers yourself. +<strong>Mom</strong> does no automatic generation of things like +the title and the author in headers and footers when you're using +<strong>HEADERS_AND_FOOTERS</strong>. Furthermore, style +changes — family, font, pointsize, colour, capitalization, etc +— are entirely your responsibility and must be made with +<a href="definitions.html#TERMS_INLINES">inline escapes</a> +in the arguments passed to <kbd>"<recto +header string>"</kbd>, <kbd>"<recto +footer string>"</kbd>, etc. By default, +<strong>mom</strong> sets the headers and footers created with +<strong>HEADERS_AND_FOOTERS</strong> in the same family, font, +point size, capitalization style and colour as +<a href="definitions.html#TERMS_RUNNING">running text</a>. +</p> + +<p> +The manner of entering what you want is identical to the way you +input +<a href="#USERDEF_HDRFTR">single string headers and footers</a>. +I suggest reading up on them, as well as looking at the entries, +<a href="#HDRFTR_RECTOVERSO">HEADER_RECTO</a> +and +<a href="#RESERVED_STRINGS">Using mom's "reserved" strings in header/footer definitions</a>. +</p> + +<p> +The same +<a href="#PADDING_HDRFTR">padding mechanism</a> +used in <strong>HEADER_RECTO</strong> and +<strong>HEADER_VERSO</strong> is available in the +<a href="definitions.html#TERMS_STRINGARGUMENT">string arguments</a> +passed to +<strong>HEADERS_AND_FOOTERS</strong>, allowing you to simulate +two- and three-part headers and footers. +</p> + +<p> +<nobr><kbd>L | C | R</kbd></nobr> in the arguments to +<strong>HEADERS_AND_FOOTERS</strong> 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 +<strong>mom</strong>'s +<a href="#RESERVED_STRINGS">"reserved" strings</a>, +and whatever +<a href="definitions.html#TERMS_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 <strong>HEADERS_AND_FOOTERS</strong> +<strong><em>except the last one</em></strong> requires a backslash +after it. The use of backslashes isn'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. <strong>OFF, QUIT, END, +X...</strong>). <strong>Mom</strong> 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 +<strong>HEADERS_AND_FOOTERS</strong> off, just invoke +<a href="#FOOTERS"><kbd>.FOOTERS</kbd></a> +afterwards. +</p> + +<h4><u>Some examples</u></h4> + +<h5><u>Example 1</u></h5> + +<p> +If you want the same header and footer on every page, here's how +you'd do it. + +<pre> + .HEADERS_AND_FOOTERS \ +-----------------------+ + C "\E*[$TITLE]" \ | Title | + L "^\E*[$AUTHOR]#\*[PAGE#]^" | | + | | + | | + | | + | | + | | + | | + | | + | | + | | + | | + | | + | Author Pg. # | + +-----------------------+ +</pre> +</p> + +<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't have to use these special strings. You can type in +anything you like. I've only used them here to show that they're +available. +</p> + +<h5><u>Example 2</u></h5> + +<p> +If you want different headers and footers on recto/verso pages, +here's a recipe: + +<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.# | + +-----------------------+ +------------------------+ +</pre> +</p> + +<hr/> + +<a name="HEADFOOT_CONTROL"><h2><u>Control macros for headers/footers</u></h2></a> + +<p> +Virtually every part of headers (see the paragraph on how +<a href="#HEADERFOOTER">"headers" means "footers"</a> +in the +<a href="#HEADFOOTPAGE_INTRO">introduction to headers/footers</a>) +can be designed to your own specifications. +</p> + +<a name="INDEX_REFERENCE"><h3><u>Header/footer control macros</u></h3></a> + +<ul> + + <a name="STRINGS"></a> + + <li><a href="#HDRFTR_STRINGS"><strong>STRINGS</strong></a></li> + <ul> + <li><a href="#HDRFTR_LEFT">HEADER_LEFT</a></li> + <li><a href="#HDRFTR_CENTER">HEADER_CENTER</a></li> + <ul> + <li><a href="#HDRFTR_CENTER_PAD">HEADER_CENTER_PAD</a> — stick some space left or right of the centre string</li> + </ul> + <li><a href="#HDRFTR_RIGHT">HEADER_RIGHT</a></li> + <li><a href="#RESERVED_STRINGS">Using mom's "reserved" strings in header/footer definitions</a> + (e.g. <kbd>\E*[$TITLE]</kbd> when you want 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> + + <a name="STYLE"></a> + + <li><a href="#HDRFTR_STYLE"><strong>STYLE</strong></a></li> + <ul> + + <a name="GLOBAL"></a> + + <li><a href="#HDRFTR_STYLE_GLOBAL"><strong>Global changes</strong></a></li> + <li><a href="#HDRFTR_GLOBAL_FAMILY">HEADER_FAMILY</a> — family for entire header</li> + <li><a href="#HDRFTR_GLOBAL_SIZE">HEADER_SIZE</a> — size for entire header</li> + <li><a href="#HDRFTR_PLAIN">HEADER_PLAIN</a> — disable default adjustments to header parts</li> + <li><a href="#HDRFTR_COLOR">HEADER_COLOR</a> — colourize the header</li> + </ul> + <ul> + + <a name="PART_BY_PART"></a> + + <li><a href="#HDRFTR_STYLE_PART"><strong>Part-by-part changes</strong></a></li> + <li><a href="#_FAMILY">_FAMILY</a> — left, centre or right family</li> + <li><a href="#_FONT">_FONT</a> — left, centre or right font</li> + <li><a href="#_SIZE">_SIZE</a> — left, centre or right size</li> + <li><a href="#_CAPS">_CAPS</a> — left, centre or right all caps</li> + <li><a href="#_COLOR">_COLOR</a> — left, centre or right colour</li> + </ul> + + <a name="VERTICAL"></a> + + <li><a href="#HDRFTR_VERTICAL"><strong>VERTICAL PLACEMENT AND SPACING</strong></a></li> + <ul> + <li><a href="#HDRFTR_MARGIN">HEADER_MARGIN</a></li> + <li><a href="#HDRFTR_GAP">HEADER_GAP</a></li> + </ul> + + <a name="SEPARATOR_RULE"></a> + + <li><a href="#HDRFTR_SEPARATOR"><strong>SEPARATOR RULE</strong></a></li> + <ul> + <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> +</ul> + +<!-- -HDRFTR_STRINGS- --> + +<hr width="66%" align="left"/> + +<a name="HDRFTR_STRINGS"><h3><u>Header/footer strings</u></h3></a> + +<a name="HDRFTR_LEFT"></a> + +<p> +<nobr>Macro: <strong>HEADER_LEFT</strong> <kbd>"<text of header left>" | #</kbd></nobr> +<br/> + +<a name="HDRFTR_CENTER"></a> + +<nobr>Macro: <strong>HEADER_CENTER</strong> <kbd>"<text of header centre>" | #</kbd></nobr> +<br/> + +<a name="HDRFTR_RIGHT"></a> + +<nobr>Macro: <strong>HEADER_RIGHT</strong> <kbd>"<text of header right>" | #</kbd></nobr> +</p> + +<p> +To change the text (the "string") of the left, centre, or +right part of headers, invoke the appropriate macro above with the +string you want. For example, <strong>mom</strong>, by default, +prints the document'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 <strong>HEADER_LEFT</strong> like this: + +<pre> + .HEADER_LEFT "R. Stallman, E. Raymond" +</pre> +</p> + +<p> +Because the arguments to <strong>HEADER_LEFT, _CENTER,</strong> +and <strong>_RIGHT</strong> are +<a href="definitions.html#TERMS_STRINGARGUMENT">string arguments</a>, +they must be enclosed in double-quotes. +</p> + +<p> +<strong>NOTE:</strong> Replace <strong>HEADER_</strong>, above, +with <strong>FOOTER_</strong> to change the strings in footers. + +<a name="HDRFTR_CENTER_PAD"><h4>*<u>Padding the header/footer centre string</u></h4></a> + +<p> +<nobr>Macro: <strong>HEADER_CENTER_PAD</strong> <kbd>LEFT | RIGHT <amount of space by which to pad centre string left or right></kbd></nobr> +<br/> + +<em>*Requires a <a href="definitions.html#TERMS_UNITOFMEASURE">unit of measure</a></em> +</p> + +<p> +By default, <strong>mom</strong> centres the header centre string +literally on the line length in effect for page headers. In some +cases, notably when the header left or header right strings are +particularly long, the effect isn't pretty. The offendingly long +header left or right crowds, or even overprints, the header centre. +That's where <strong>HEADER_CENTER_PAD</strong> comes in. With a +bit of experimentation (yes, you have to preview the document), you +can use <strong>HEADER_CENTER_PAD</strong> 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 "By +the Shores of Lake Attica." You've told <strong>mom</strong> +you want +<br/><br/> + +<nobr> <a href="docprocessing.html#DOCTYPE">.DOCTYPE</a> <strong>NAMED</strong> "Outline"</nobr> +<br/><br/> + +but when you preview your work, you see that "Outline", in +the centre of the page header, is uncomfortably close to the title, +which is to the right of it. By invoking + +<pre> + .HEADER_CENTER_PAD RIGHT 3P +</pre> +</p> + +you can scoot the word "Outline" over three +<a href="definitions.html#TERMS_PICASPOINTS">picas</a> +to the left (the padding's added to 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 +obviously puts the padding on the left side of the string. +</p> + +<p> +Most reassuring of all is that if you use +<strong>HEADER_CENTER_PAD</strong> conjunction with +<a href="rectoverso.html#RECTO_VERSO">RECTO_VERSO</a>, +<strong>mom</strong> will pad the centre string appropriately left +OR right, depending on which page you're on, without you having to +tell her to do so. +</p> + +<a name="RESERVED_STRINGS"><h4>*<u>Using mom's "reserved" strings in header/footer definitions</u></h4></a> + +<p> +As pointed out in the author's note in the introduction to +headers/footers, headers and footers are something you don't +normally have to worry much about. <strong>Mom</strong> 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. 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, <strong>mom</strong> has a number of +"reserved" strings that you can plug into the +<strong>HEADER_LEFT, _CENTER</strong> and <strong>_RIGHT</strong> +macros. They are: + +<pre> + \E*[$TITLE] — the current argument passed to .TITLE + \E*[$DOCTITLE] — the current argument passed to .DOCTITLE + \E*[$AUTHOR] — the current first argument passed to .AUTHOR + \E*[$AUTHOR_1...9] — the current arguments passed to .AUTHOR + \E*[$AUTHORS] — a comma-separated concatenated string + of all the current arguments passed to .AUTHOR + (i.e. a list of authors) + \E*[$CHAPTER_STRING] — the current argument passed to .CHAPTER_STRING, + if invoked, otherwise, "Chapter" + \E*[$CHAPTER] — the current argument (typically a number) passed + to .CHAPTER + \E*[$CHAPTER_TITLE] — the current argument passed to .CHAPTER_TITLE +</pre> +</p> + +<p> +Returning to the scenario above, first, you'd define a centre +string for the endnotes page: + +<pre> + .HEADER_CENTER "Endnotes" +</pre> + +Then, you'd output the endnotes: + +<pre> + .ENDNOTES +</pre> + +Then, you'd prepare <strong>mom</strong> for the next document: + +<pre> + .COLLATE + .TITLE "New Doc Title" + .AUTHOR "Josephine Blough" +</pre> + +Then, you'd redefine the header centre string using the reserved +string <kbd>\E*[$TITLE]</kbd>, like this: + +<pre> + .HEADER_CENTER "\E*[$TITLE]" +</pre> +</p> + +<p> +And last, you'd do: + +<pre> + .START +</pre> +</p> + +<p> +Voilą! Any argument you pass to <strong>TITLE</strong> from here +on in (say, for subsequent documents) is back in the header centre +position. Here's the whole routine again: + +<pre> + .HEADER_CENTER "Endnotes" + .ENDNOTES + .COLLATE + .TITLE "New Doc Title" + .AUTHOR "Josephine Blough" + .HEADER_CENTER "\E*[$TITLE]" + .START +</pre> +</p> + +<p> +If need be, you can concatenate the strings, as in the following +example. + +<pre> + .HEADER_CENTER "\E*[$CHAPTER_STRING] \E*[$CHAPTER]" +</pre> + +which, assuming a <kbd>.CHAPTER_STRING</kbd> of +<kbd>"Chapter"</kbd> and a <kbd>.CHAPTER</kbd> of +<kbd>"2",</kbd> would put "Chapter 2" in the +header centre position. +</p> + +<a name="PAGE_NUMBER_SYMBOL"><h4>*<u>Replacing header-left, -CENTER or -right with the page number</u></h4></a> + +<p> +If you would like to have the current page number to appear +header-left, -center, or -right <em>instead</em> of a text +string, invoke the appropriate macro, above, with the single +argument <kbd>#</kbd> (the "number" or +"pound" sign). Do <strong>NOT</strong> use +double-quotes. For example, + +<pre> + .HEADER_CENTER # +</pre> + +will print the current page number in the CENTER part of +headers. +</p> + +<a name="PAGE_NUMBER_INCL"><h4>*<u>Including the page number in header-left, -CENTER or -right</u></h4></a> + +<p> +If you would like to <em>include</em> the current page number in +the string you pass to <strong>HEADER_LEFT, _CENTER,</strong> or +<strong>_RIGHT</strong>, use the special +<a href="definitions.html#TERMS_INLINES">inline escape</a> +<kbd>\*[PAGE#]</kbd> in the string argument. +</p> + +<p> +For example, say you have a document that's ten pages long, and +you want header-right to say "page <whichever> of 10", +invoke <kbd>.HEADER_RIGHT</kbd> as follows: + +<pre> + .HEADER_RIGHT "page \*[PAGE#] of 10" +</pre> +</p> + +<p> +Header-right of page two will read "page 2 of 10", +header-right of page three will read "page 3 of 10", +and so on. +</p> + +<!-- -HDRFTR_STYLE- --> + +<hr width="66%" align="left"/> + +<a name="HDRFTR_STYLE"><h3><u>Header/footer style</u></h3></a> + +<a name="HDRFTR_STYLE_GLOBAL"><h4><u>Global changes</u></h4></a> + +<p> +The following macros allow you to make changes that affect all +parts of the header at once. +</p> + +<p> +Please note that <strong>HEADER_FAMILY</strong> and +<strong>HEADER_FONT</strong> have no effect on +<a href="docprocessing.html#PRINTSTYLE">PRINTSTYLE TYPEWRITE</a>. +</p> + +<ul> + <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> + +<hr width="66%" align="left"/> + +<a name="HDRFTR_GLOBAL_FAMILY"></a> + +<p> +<nobr>Macro: <strong>HEADER_FAMILY</strong> <kbd><family></kbd></nobr> +</p> + +<p> +By default, <strong>mom</strong> uses the default document family +for headers. If you would like her to use another +<a href="definitions.html#TERMS_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> +<strong>NOTE:</strong> Replace <strong>HEADER_</strong>, above, +with <strong>FOOTER_</strong> to change the footer family. +</p> + +<hr width="33%" align="left"/> + +<a name="HDRFTR_GLOBAL_SIZE"></a> + +<p> +<nobr>Macro: <strong>HEADER_SIZE</strong> <+|-number of points></nobr> +<br/> + +<em>*Argument is relative to the point size of type in paragraphs</em> +</p> + +<p> +By default, <strong>mom</strong> makes small adjustments to the size +of each part of a header to achieve an aesthetically pleasing result. +If you'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#TERMS_PICASPOINTS">points</a> +(fractions allowed) by which you want her to in/decrease the size +of headers. For example, + +<pre> + .HEADER_SIZE +.75 +</pre> + +increases the size of every part of a header by 3/4 of a point while +respecting <strong>mom</strong>'s own little size changes. +</p> + +<p> +See +<a href="docelement.html#CONTROL_MACRO_ARGS">Arguments to the control macros</a> +for an explanation of how control macros ending in +<strong>_SIZE</strong> work. +</p> + +<a name="FOOTER_GLOBAL_SIZE"></a> + +<p> +<strong>NOTE:</strong> Replace <strong>HEADER_</strong>, above, +with <strong>FOOTER_</strong> to change the footer size. +</p> + +<p> +<strong>ADDITIONAL NOTE:</strong> Normally, macros that control headers have no +effect on +<a href="docprocessing.html#PRINTSTYLE">PRINTSTYLE TYPEWRITE</a>. +<strong>HEADER_SIZE</strong> is an exception. While all parts of a +header in <strong>PRINTSTYLE TYPEWRITE</strong> are always the same +size, you can use <strong>HEADER_SIZE</strong> with <strong>PRINTSTYLE +TYPEWRITE</strong> to reduce the header's overall point size. +You'll most likely require this when the +<a href="docprocessing.html#COPYSTYLE">COPYSTYLE</a> +is <strong>DRAFT</strong>, since portions of the header may overprint +if, say, the title of your document is very long. +</p> + +<hr width="33%" align="left"/> + +<a name="HDRFTR_PLAIN"></a> + +<p> +Macro: <strong>HEADER_PLAIN</strong> +</p> + +<p> +By default, <strong>mom</strong> 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 +<strong>mom</strong>'s defaults, invoke <kbd>.HEADER_PLAIN</kbd> +by itself, with no argument. <strong>Mom</strong> will disable her +default behaviour for headers, and reset all elements of header +style to the same family, font, and point size as she uses in +paragraphs. +</p> + +<p> +<strong>NOTE:</strong> Replace <strong>HEADER_</strong>, above, with +<strong>FOOTER_</strong> to disable <strong>mom</strong>'s default +behaviour for the various elements of footer style. +</p> + +<hr width="33%" align="left"/> + +<a name="HDRFTR_COLOR"></a> + +<p> +<nobr>Macro: <strong>HEADER_COLOR</strong> <kbd><colorname></kbd></nobr> +</p> + +<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 "initialized") with +<a href="color.html#NEWCOLOR">NEWCOLOR</a> +or +<a href="color.html#XCOLOR">XCOLOR</a>. +</p> + +<p> +<strong>HEADER_COLOR</strong> will set all the parts of the header +AND 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_<POSITION>_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> +<strong>NOTE:</strong> Replace <strong>HEADER_</strong>, above, +with <strong>FOOTER_</strong> to colourize footers. +</p> + +<hr width="66%" align="left"/> + +<a name="HDRFTR_STYLE_PART"><h4><u>Part by part changes</u></h4></a> + +<p> +<strong>NOTE:</strong> When using the following control +macros, replace "<POSITION>" by <strong>LEFT, +CENTER,</strong> or <strong>RIGHT</strong> as appropriate. +</p> + +<ul> + <li><a href="#_FAMILY">HEADER_<POSITION>_FAMILY</a></li> + <li><a href="#_FONT">HEADER_<POSITION>_FONT</a></li> + <li><a href="#_SIZE">HEADER_<POSITION>_SIZE</a></li> + <li><a href="#_CAPS">HEADER_<POSITION>_CAPS</a></li> + <li><a href="#_COLOR">HEADER_<POSITION>_COLOR</a></li> +</ul> + +<hr width="66%" align="left"/> + +<a name="_FAMILY"></a> + +<p> +<nobr>Macro: <strong>HEADER_<POSITION>_FAMILY</strong> <kbd><family></kbd></nobr> +</p> + +<p> +Use <strong>HEADER_<POSITION>_FAMILY</strong> to change the +<a href="definitions.html#TERMS_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 +<strong>_FAMILY</strong> work. +</p> + +<p> +<strong>NOTE:</strong> Replace <strong>HEADER_</strong>, above, +with <strong>FOOTER_</strong> to change a footer part's family. +</p> + +<hr width="33%" align="left"/> + +<a name="_FONT"></a> + +<p> +<nobr>Macro: <strong>HEADER_<POSITION>_FONT</strong> <kbd><font></kbd></nobr> +</p> + +<p> +Use <strong>HEADER_<POSITION>_FONT</strong> to change the +<a href="definitions.html#TERMS_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 +<strong>_FONT</strong> work. +</p> + +<p> +<strong>NOTE:</strong> Replace <strong>HEADER_</strong>, above, +with <strong>FOOTER_</strong> to change a footer part's font. +</p> + +<hr width="33%" align="left"/> + +<a name="_SIZE"></a> + +<p> +<nobr>Macro: <strong>HEADER_<POSITION>_SIZE</strong> <kbd><+|-number of points></kbd></nobr> +</p> + +<p> +Use <strong>HEADER_<POSITION>_SIZE</strong> 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 +<strong>_SIZE</strong> work. +</p> + +<p> +<strong>NOTE:</strong> Replace <strong>HEADER_</strong>, above, +with <strong>FOOTER_</strong> to change a footer part's size. +</p> + +<hr width="33%" align="left"/> + +<a name="_CAPS"></a> + +<p> +<nobr>Macro: <strong>HEADER_<POSITION>_CAPS</strong> <kbd>toggle</kbd></nobr> +</p> + +<p> +<strong>HEADER_<POSITION>_CAPS</strong> is a +<a href="definitions.html#TERMS_TOGGLE">toggle macro</a>. +If you want any part of headers to be set in all caps, +regardless of the capitalization of that part'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 <strong>mom</strong> capitalizes by +default), invoke the macro with any argument (e.g. <strong>OFF, +QUIT, END, X...</strong>). +</p> + +<p> +<strong>NOTE:</strong> Replace <strong>HEADER_</strong>, above, +with <strong>FOOTER_</strong> to change a footer part's +capitalization style. +</p> + +<hr width="33%" align="left"/> + +<a name="_COLOR"></a> + +<p> +<nobr>Macro: <strong>HEADER_<POSITION>_COLOR</strong> <kbd><colorname></kbd></nobr> +</p> + +<p> +<strong>HEADER_<POSITION>_COLOR</strong> 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'd get it: + +<pre> + .HEADER_RIGHT_COLOR red +</pre> +</p> + +<p> +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 "initialize") 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">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 <strong>HEADER_RECTO</strong> +or <strong>HEADER_VERSO</strong> with the +<a href="color.html#COLOR_INLINE"><kbd>\*[<colorname>]</kbd></a> +<a href="definitions.html#TERMS_INLINES">inline escape</a>. +</p> + +<p> +<strong>NOTE:</strong> Replace <strong>HEADER_</strong>, above, +with <strong>FOOTER_</strong> to set the colours for the various +elements of footers. +</p> + +<hr/> + +<!-- -HDRFTR_VERTICAL- --> + +<a name="HDRFTR_VERTICAL"><h2><u>Header/footer vertical placement and spacing</u></h2></a> + +<p> +See +<a href="#VERTICAL_SPACING">Vertical placement and spacing of headers/footers</a> +for an explanation of how <strong>mom</strong> deals with +headers, footers, and top/bottom page margins. +</p> + +<!-- -HDRFTR_MARGIN- --> + +<hr width="66%" align="left"/> + +<a name="HDRFTR_MARGIN"></a> + +<p> +<nobr>Macro: <strong>HEADER_MARGIN</strong> <kbd><distance to baseline of header></kbd></nobr> +<br/> + +<em>*Requires a <a href="definitions.html#TERMS_UNITOFMEASURE">unit of measure</a></em> +</p> + +<p> +Use <strong>HEADER_MARGIN</strong> to set the distance from the +top edge of the page to the +<a href="definitions.html#TERMS_BASELINE">baseline</a> +of type in headers. A unit of measure is required, and decimal +fractions are allowed. +</p> + +<p> +<strong>Mom</strong>'s default header margin is 4-1/2 +<a href="definitions.html#TERMS_PICASPOINTS">picas</a>, +but if you want a different margin, say, 1/2-inch, do + +<pre> + .HEADER_MARGIN .5i +</pre> +</p> + +<p> +If your document uses +<a href="definitions.html#TERMS_FOOTER">footers</a>, +replace <strong>HEADER_</strong>, above, with +<strong>FOOTER_</strong>. The argument to +<strong>FOOTER_MARGIN</strong> is the distance from the bottom edge +of the page to the baseline of type in footers. +</p> + +<p> +<strong>Mom</strong>'s default footer margin is 3 +<a href="definitions.html#TERMS_PICASPOINTS">picas</a>. +</p> + +<a name="FOOTER_MARGIN"></a> + +<h4><u>FOOTER MARGIN AND BOTTOM MARGIN — VERY IMPORTANT!</u></h4> + +<p> +<strong>Mom</strong> requires a footer margin for proper operation, +hence she sets one, even if you don't. (As stated above, her default +footer margin is 3-picas). +</p> + +<p> +If you set a bottom margin for your document (with +<a href="typesetting.html#B_MARGIN">B_MARGIN</a>, +prior to +<a href="docprocessing.html#START">START</a>) +and the margin's too close to <strong>mom</strong>'s default +footer margin (or a footer margin you set yourself +with <strong>FOOTER_MARGIN</strong>), <strong>mom</strong> will +not print your footers; additionally, she'll give you a warning +and some advice on standard error. When this happens, you must +reset either <strong>B_MARGIN</strong> or +<strong>FOOTER_MARGIN</strong> so there's an adequate amount of +space for <strong>mom</strong> 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> + +<h5><u>Example 1</u></h5> + +<pre> + <reference macros, etc> + .PAGINATION OFF + .B_MARGIN .25i + .FOOTER_MARGIN O + .START +</pre> + +<h5><u>Example 2</u></h5> + +<pre> + <reference macros, etc> + .HEADERS OFF + .PAGENUM_POS TOP RIGHT + .B_MARGIN .25i + .FOOTER_MARGIN O + .START +</pre> + +<h4><u>A note on header/footer margins and page numbering</u></h4> + +<p> +<strong>Mom</strong> uses <strong>HEADER_MARGIN</strong> and +<strong>FOOTER_MARGIN</strong> to establish the baseline +position of page numbers in addition to the baseline position of +headers and footers. +</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 <strong>FOOTER_MARGIN</strong>. 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 <strong>mom</strong> to put them +there with +<a href="#PAGENUM_POS">PAGENUM_POS</a>, +you'd use <strong>HEADER_MARGIN</strong> to change their +baseline placement. +</p> + +<!-- -HDRFTR_GAP- --> + +<hr width="66%" align="left"/> + +<a name="HDRFTR_GAP"></a> + +<p> +<nobr>Macro: <strong>HEADER_GAP</strong> <kbd><distance from header to start of running text></kbd></nobr> +<br/> + +<em>*Requires a <a href="definitions.html#TERMS_UNITOFMEASURE">unit of measure</a></em> +</p> + +<p> +Use <strong>HEADER_GAP</strong> to set the distance from the +<a href="definitions.html#TERMS_BASELINE">baseline</a> +of type in headers to the start of +<a href="definitions.html#TERMS_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>, +<strong>HEADER_MARGIN + HEADER_GAP</strong> determine the default +vertical starting position of running text on the page UNLESS you +have given <strong>mom</strong> your own top margin (with +<a href="typesetting.html#T_MARGIN">T_MARGIN</a>). If you give +a top margin, <strong>mom</strong> ignores +<strong>HEADER_GAP</strong>; running text starts at your stated top +margin. +</p> + +<p> +<strong>Mom</strong>'s default header gap is 3 +<a href="definitions.html#TERMS_PICASPOINTS">picas</a>, +but if you want a different gap, say, 2 centimetres, do + +<pre> + .HEADER_GAP 2c +</pre> +</p> + +<p> +If your document uses +<a href="definitions.html#TERMS_FOOTER">footers</a>, +replace <strong>HEADER_</strong>, above, with +<strong>FOOTER_</strong>. The argument to +<strong>FOOTER_GAP</strong> 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>, +<strong>FOOTER_MARGIN + FOOTER_GAP</strong> determine the default +vertical end position of running text on the page UNLESS you have +given <strong>mom</strong> a bottom margin (with +<a href="typesetting.html#B_MARGIN">B_MARGIN</a>). If you give +a bottom margin, <strong>mom</strong> ignores +<strong>FOOTER_GAP</strong>; running text ends at your stated bottom +margin. +</p> + +<p> +<strong>Mom</strong>'s default footer gap is 3 +<a href="definitions.html#TERMS_PICASPOINTS">picas</a>. +</p> + +<p> +<strong>NOTE:</strong> <strong>Mom</strong> uses +<strong>HEADER_GAP</strong> and +<strong>FOOTER_GAP</strong> 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 +<strong>FOOTER_GAP</strong>. If page numbers are at the top of the +page, change the gap between the number and the first line of running +text with <strong>HEADER_GAP</strong>. +</p> + +<hr/> + +<!-- -HDRFTR_SEPARATOR- --> + +<a name="HDRFTR_SEPARATOR"><h2><u>Header/footer separator rule</u></h2></a> + +<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#TERMS_HEADER">header</a> +and helps separate it visually from +<a href="definitions.html#TERMS_RUNNING">running text</a>. If +you don'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> + +<ul> + <li><a href="#HDRFTR_RULE">HEADER_RULE</a> — on or off</li> + <li><a href="#HDRFTR_RULE_WEIGHT">HEADER_RULE_WEIGHT</a> — weight of the rule</li> + <li><a href="#HDRFTR_RULE_GAP">HEADER_RULE_GAP</a> — distance of rule from header</li> + <li><a href="#HDRFTR_RULE_COLOR">HEADER_RULE_COLOR</a> — color of rule header</li> +</ul> + +<!-- -HDRFTR_RULE- --> + +<hr width="66%" align="left"/> + +<a name="HDRFTR_RULE"></a> + +<p> +<nobr>Macro: <strong>HEADER_RULE</strong> <kbd>toggle</kbd></nobr> +</p> + +<p> +By default, <strong>mom</strong> prints a header separator rule +underneath headers (or above footers). If you don't want the +rule, turn it off by invoking <kbd>.HEADER_RULE</kbd> with any +argument (<strong>OFF, QUIT, END, X...</strong>), e.g. + +<pre> + .HEADER_RULE OFF +</pre> +</p> + +<p> +To turn the rule (back) on, invoke <kbd>.HEADER_RULE</kbd> +without any argument. +</p> + +<p> +<strong>NOTE:</strong> Replace <strong>HEADER_</strong>, above, +with <strong>FOOTER_</strong> to enable/disable the printing of +the footer separator rule. (Most likely, if you're using +<a href="#FOOTERS">FOOTERS</a>, you'll want it off.) +</p> + +<!-- -HDRFTR_RULE_WEIGHT- --> + +<hr width="33%" align="left"/> + +<a name="HDRFTR_RULE_WEIGHT"></a> + +<p> +<nobr>Macro: <strong>HEADER_RULE_WEIGHT</strong> <kbd><weight in points></kbd></nobr> +<br/> + +<em>*Argument must</em> NOT <em>have a <a href="definitions.html#TERMS_UNITOFMEASURE">unit of measure</a> appended</em> +</p> + +<p> +<strong>HEADER_RULE_WEIGHT</strong> controls the weight +("thickness") 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#TERMS_PICASPOINTS">points</a> +but <em>without</em> the unit of measure, <kbd>p</kbd>, appended. +The argument to <strong>HEADER_RULE_WEIGHT</strong> 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. + +<pre> + .HEADER_RULE_WEIGHT 4 +</pre> + +which sets the separator rule weight to 4 points, is how you'd do +it. +</p> + +<p> +<strong>Mom</strong>'s default header rule weight is 1/2 point. +</p> + +<p> +<strong>NOTE:</strong> Replace <strong>HEADER_</strong>, above, with +<strong>FOOTER_</strong> to set the weight of the footer separator +rule. +</p> + +<!-- -HDRFTR_RULE_GAP- --> + +<hr width="33%" align="left"/> + +<a name="HDRFTR_RULE_GAP"></a> + +<p> +<nobr>Macro: <strong>HEADER_RULE_GAP</strong> <kbd><distance of rule beneath header></kbd></nobr> +<br/> + +<em>*Requires a <a href="definitions.html#TERMS_UNITOFMEASURE">unit of measure</a></em> +</p> + +<p> +<strong>HEADER_RULE_GAP</strong> is the distance from the +<a href="definitions.html#TERMS_BASELINE">baseline</a> +of type in headers to the top edge of the rule underneath. (If +<strong>FOOTER_RULE_GAP</strong>, the gap is the distance from the +top of the highest +<a href="definitions.html#TERMS_ASCENDER">ascender</a> +to the bottom edge of the rule.) A unit of measure is +required, and decimal fractions are allowed. Please note that +<strong>HEADER_RULE_GAP</strong> has no effect on +<a href="#HDRFTR_GAP">HEADER_GAP</a> +(i.e. <strong>HEADER_RULE_GAP</strong> is NOT added to +<strong>HEADER_GAP</strong> when <strong>mom</strong> calculates the +space between headers and the start of +<a href="definitions.html#TERMS_RUNNING">running text</a>). +</p> + +<p> +By default, the header rule gap is 4 +<a href="definitions.html#TERMS_PICASPOINTS">points</a>. +If you'd like to change it to, say, 1/4 +<a href="definitions.html#TERMS_EM">em</a>, do + +<pre> + .HEADER_RULE_GAP .25m +</pre> +</p> + +<p> +<strong>NOTE:</strong> Replace <strong>HEADER_</strong>, above, +with <strong>FOOTER_</strong> if you're using +<a href="definitions.html#TERMS_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#TERMS_ASCENDER">ascender</a> +in the footer. +</p> + +<p> +<strong>ADDITIONAL NOTE:</strong> When using +<a href="#HDRFTR_RECTOVERSO">FOOTER_RECTO</a> +and +<a href="#HDRFTR_RECTOVERSO">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 <strong>mom</strong> may not get the rule gap right. Inline +changes to the size of type in <strong>FOOTER_RECTO</strong> and +<strong>FOOTER_VERSO</strong> should always be negative (smaller) +than the default. +</p> + +<!-- -HDRFTR_RULE_COLOR- --> + +<hr width="33%" align="left"/> + +<a name="HDRFTR_RULE_COLOR"></a> + +<p> +<nobr>Macro: <strong>HEADER_RULE_COLOR</strong> <kbd><colorname></kbd></nobr> +</p> + +<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 "initialized") with +<a href="color.html#NEWCOLOR">NEWCOLOR</a> +or +<a href="color.html#XCOLOR">XCOLOR</a>. +</p> + +<p> +Please note that <strong>HEADER_RULE_COLOR</strong> overrides the +colour set with +<a href="#HDRFTR_COLOR">HDRFTR_COLOR</a>, +so that it's possible to have the heads entirely in, say, blue (set +with <strong>HEADER_COLOR</strong>), and the header rule in, say, +red. +</p> + +<p> +<strong>NOTE:</strong> Replace <strong>HEADER_</strong>, above, +with <strong>FOOTER_</strong> to change the colour of the footer +rule. +</p> + +<hr/> + +<!-- ==================================================================== --> + +<a name="PAGINATION"><h2><u>Pagination</u></h2></a> + +<p> +By default, <strong>mom</strong> paginates documents. Page numbers +appear in the bottom margin of the page, centred between two hyphens. +As with all elements of <strong>mom</strong>'s document processing, +most aspects of pagination style can be altered to suit your taste +with control macros. +</p> + +<a name="INDEX_PAGINATION"><h3><u>Pagination macros list</u></h3></a> + +<ul> + <li><a href="#PAGINATE">PAGINATE</a> — pagination on or off</li> + <li><a href="#PAGENUMBER">PAGENUMBER</a> — user-defined (starting) page number</li> + <li><a href="#PAGENUM_STYLE">PAGENUM_STYLE</a> — digits, roman numerals, etc</li> + <li><a href="#PAGENUM_ON_FIRST_PAGE">PAGENUM_ON_FIRST_PAGE</a> — applies only when footers are enabled</li> + <li><a href="#DRAFT_WITH_PAGENUMBER">DRAFT_WITH_PAGENUMBER</a> — attach draft/revision information to page numbers</li> + <li><a href="#PAGINATE_CONTROL">Control macros</a></li> +</ul> + +<!-- -PAGINATE- --> + +<hr width="66%" align="left"/> + +<a name="PAGINATE"></a> + +<p> +<nobr>Macro: <strong>PAGINATE</strong> <kbd>toggle</kbd></nobr> +<br/> + +Alias: <strong>PAGINATION</strong> +</p> + +<p> +By default, <strong>mom</strong> paginates documents (in the bottom +margin). If you'd prefer she not paginate, turn pagination off +by invoking <kbd>.PAGINATE</kbd> with any argument (<strong>OFF, +NO, QUIT, END, X...</strong>), e.g. + +<pre> + .PAGINATE NO +</pre> +</p> + +<p> +To (re)start pagination, invoke <kbd>.PAGINATE</kbd> without any +argument. +</p> + +<!-- -PAGENUMBER- --> + +<hr width="33%" align="left"/> + +<a name="PAGENUMBER"></a> + +<p> +<nobr>Macro: <strong>PAGENUMBER</strong> <kbd><number></kbd></nobr> +</p> + +<p> +As is to be expected, pagination of documents begins at page 1. If +you'd prefer that <strong>mom</strong> begin with a different number +on the first page of a document, invoke <kbd>.PAGENUMBER</kbd> with +the number you want. +</p> + +<p> +<strong>PAGENUMBER</strong> need not be used only to give +<strong>mom</strong> a "first page" number. It can be used at any +time to tell <strong>mom</strong> what number you want a page to +have. Subsequent page numbers will, of course, be incremented by 1 +from that number. +</p> + +<!-- -PAGENUM_STYLE- --> + +<hr width="33%" align="left"/> + +<a name="PAGENUM_STYLE"></a> + +<p> +<nobr>Macro: <strong>PAGENUM_STYLE</strong> <kbd>DIGIT | ROMAN | roman | ALPHA | alpha</kbd></nobr> +</p> + +<p> +<strong>PAGENUM_STYLE</strong> lets you tell +<strong>mom</strong> what kind of page numbering you want. +</p> + +<pre> + 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...) +</pre> + +<!-- -PAGENUM_ON_FIRST_PAGE- --> + +<hr width="33%" align="left"/> + +<a name="PAGENUM_ON_FIRST_PAGE"></a> + +<p> +<nobr>Macro: <strong>PAGENUM_ON_FIRST_PAGE</strong> <kbd>toggle</kbd></nobr> +</p> + +<p> +This macro applies only if you've enabled +<a href="#FOOTERS">FOOTERS</a>. +If <strong>FOOTERS</strong> are on, <strong>mom</strong> +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'd like the page number to appear on "first" pages +when footers are on, invoke <kbd>.PAGENUM_ON_FIRST_PAGE</kbd> with +no argument. Any other argument turns the feature off (<strong>OFF, +QUIT, END, X...</strong>). +</p> + +<p> +As with most of the +<a href="definitions.html#TERMS_CONTROLMACRO">control macros</a>, +<strong>PAGENUM_ON_FIRST_PAGE</strong> can be invoked at any time, +meaning that if you don't want a page number on the very first +page of a document, but do want one on pages that appear after +<strong>COLLATE</strong>, 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 <strong>COLLATE</strong>. +</p> + +<!-- -DRAFT_WITH_PAGENUMBER- --> + +<hr width="33%" align="left"/> + +<a name="DRAFT_WITH_PAGENUMBER"></a> + +<p> +<nobr>Macro: <strong>DRAFT_WITH_PAGENUMBER</strong></nobr> +</p> + +<p> +Sometimes, in +<a href="docprocessing.html#COPYSTYLE">COPYSTYLE DRAFT</a>, +the CENTER part of page headers gets overcrowded because of +the draft and revision information that go there by default. +<strong>DRAFT_WITH_PAGENUMBER</strong> 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's page numbering, in the form + +<pre> + Draft #, Rev. # / <pagenumber> +</pre> +</p> + +<p> +If you have not supplied <strong>mom</strong> with a draft number +(with +<a href="docprocessing.html#DRAFT">DRAFT</a>) +<strong>DRAFT_WITH_PAGENUMBER</strong> will assume "Draft +1", and will print it before the page number. +</p> + +<p> +See the note in +<a href="docprocessing.html#COPYSTYLE_NOTE">COPYSTYLE DRAFT</a> +for other ways of dealing with crowded page headers when formatting +draft-style copy. +</p> + +<hr width="66%" align="left"/> + +<!-- -PAGINATE_CONTROL- --> + +<a name="PAGINATE_CONTROL"><h3><u>Pagination control macros</u></h3></a> + +<ol> + <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> + +<a name="PAGINATE_GENERAL"><h4><u>1. Page number family/font/size/colour</u></h4></a> + +<p> +See +<a href="docelement.html#CONTROL_MACRO_ARGS">Arguments to the control macros</a>. +</p> + +<pre> +.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 +</pre> + +<a name="PAGENUM_POS"><h4><u>2. Page number position</u></h4></a> + +<p> +<nobr>Macro: <strong>PAGENUM_POS</strong> <kbd>TOP | BOTTOM LEFT | CENTER | RIGHT</kbd></nobr> +</p> + +<p> +Use <strong>PAGENUM_POS</strong> to change the default position of +automatic page numbering. <strong>PAGENUM_POS</strong> requires +<em>two</em> arguments: a vertical position (TOP or BOTTOM) and a +horizontal position (LEFT or CENTER or RIGHT). +</p> + +<p> +For example, if you turn both +<a href="definitions.html#TERMS_HEADER">headers</a> +and +<a href="definitions.html#TERMS_FOOTER">footers</a> +off (with <nobr><kbd>.HEADERS OFF</kbd></nobr> and +<nobr><kbd>.FOOTERS OFF</kbd>)</nobr> and you want +<strong>mom</strong> to number your pages at the top right position, +enter + +<pre> + .PAGENUM_POS TOP RIGHT +</pre> +</p> + +<a name="PAGENUM_HYPHENS"><h4><u>3. Enclose page numbers with hyphens (on or off)</u></h4></a> + +<p> +By default, <strong>mom</strong> encloses page numbers between +hyphens. If you don't want this behaviour, invoke the macro +<strong>PAGENUM_HYPHENS</strong> with any argument (<strong>OFF, +QUIT, END, X...</strong>), like this: + +<pre> + .PAGENUM_HYPHENS OFF +</pre> +</p> + +<p> +If, for some reason, you want to turn page number hyphens back +on, invoke the macro without an argument. +</p> + +<hr/> + +<p> +<a href="rectoverso.html#TOP">Next</a> +<a href="docelement.html#TOP">Prev</a> +<a href="#TOP">Top</a> +<a href="toc.html">Back to Table of Contents</a> +</p> + +</body> +</html> + +<!-- vim: fileencoding=latin1: nomodified: +--> diff --git a/contrib/mom/momdoc/inlines.html b/contrib/mom/momdoc/inlines.html new file mode 100644 index 00000000..64a99f5d --- /dev/null +++ b/contrib/mom/momdoc/inlines.html @@ -0,0 +1,1048 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!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=iso-8859-1"/> +<title>Mom -- Inline escapes</title> +</head> +<body bgcolor="#dfdfdf"> + +<!-- ==================================================================== --> + +<a name="TOP"></a> + +<p> +<a href="color.html#TOP">Next</a> +<a href="goodies.html#TOP">Prev</a> +<a href="toc.html">Back to Table of Contents</a> +</p> + +<a name="INLINE_ESCAPES"><h1 align="center"><u>Inline escapes</u></h1></a> + +<p> +<a href="#INTRO_INLINE_ESCAPES">Introduction to inline escapes</a> +<br/> + +<a href="#INDEX_INLINES">Index of inline escapes</a> +</p> + +<a name="INTRO_INLINE_ESCAPES"><h2><u>Introduction to inline escapes</u></h2></a> + +<p> +Inline escapes, as described in the +<a href="definitions.html#TERMS_INLINES">groff terms</a> +section of this manual, are typesetting commands that appear in text +<a href="definitions.html#TERMS_INPUTLINE">input lines</a>, +as opposed to macros and other +<a href="definitions.html#TERMS_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 — em-dashes, bullets, +<a href="definitions.html#TERMS_FIGURESPACE">figure/digit-width spaces</a>, +and so on. It is beyond the scope of this manual to provide a +complete list of groff'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 <nobr>(<kbd>\</kbd>)</nobr>. +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 <nobr>(<kbd>\\</kbd>)</nobr>. Groff +understands that this means "please print a backslash character." +(You can also use <kbd>\e</kbd> to print 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> +<strong>Mom</strong> 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's personal inlines</a>. +</p> + +<p> +Despite <strong>mom</strong>'s best intentions, there are still +a number of typesetting functions that can only be accomplished +with groff'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> + +<p> +<strong>HELPFUL BIT OF INFORMATION:</strong> Inline escapes can be used +in +<a href="docprocessing.html#DOCPROCESSING">document processing macros</a> +that take +<a href="definitions.html#TERMS_STRINGARGUMENT">string arguments</a>. +</p> + +<a name="INDEX_INLINES"><h3><u>Inlines index</u></h3></a> + +<ul> + <li><a name="INLINES_MOM"><strong>Mom's personal inlines</strong></a></li> + <ul> + <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="#B">Terminate a line without advancing on the page</a></li> + <li><a href="#TB+">Call the next sequential tab without advancing on the page</a></li> + <li><a href="#INLINE_RULE_MOM">Full measure rules</a></li> + </ul> + <li><a name="INLINES_GROFF"><strong>Groff inline escapes</strong></a></li> + <ul> + <li><a href="#INLINE_FONTS_GROFF">Font control</a> <kbd>\f</kbd></li> + <li><a href="#INLINE_HORIZONTAL_GROFF">Inline horizontal motions</a> <kbd>\h</kbd></li> + <li><a href="#INLINE_VERTICAL_GROFF">Inline vertical motions</a> <kbd>\v</kbd></li> + <li><a href="#INLINE_STRINGWIDTH_GROFF">String width function</a> <kbd>\w</kbd></li> + <li><a href="#INLINE_LINEDRAWING_GROFF">Horizontal line drawing function</a> <kbd>\l</kbd></li> + <li><a href="#INLINE_CHARACTERS_GROFF">Special characters</a></li> + </ul> +</ul> + +<hr/> + +<!-- -INLINE_FONTS_MOM- --> + +<h2><u>Mom's personal inlines</u></h2> + +<a name="INLINE_FONTS_MOM"><h3><u>Changing fonts</u></h3></a> + +<p> +<strong>Mom</strong> provides five escapes for changing fonts +inline: + +<pre> + \*[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)* + + *Note: \*[PREV] 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 \*[PREV]\*[PREV], only the first + \*[PREV] is respected; the second one is silently ignored. +</pre> +</p> + +<p> +These escapes are provided for merely for convenience, legibility, +and consistency when typesetting with <strong>mom</strong>. For +more complete and flexible inline font control, please see +<a href="#INLINE_FONTS_GROFF">font control with <kbd>\f</kbd></a>. +</p> + +<p> +<strong>NOTE CONCERNING DOCUMENT PROCESSING:</strong> If you'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> +Additionally, if you're designing your own +<a href="headfootpage.html#HEADFOOTPAGE_INTRO">HEADERS or FOOTERS</a> +and want to use <strong>mom</strong>'s inline escapes +for changing fonts <em>inside</em> 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>. +</p> + +<!-- -INLINE_SIZE_MOM- --> + +<hr width="33%" align="left"/> + +<a name="INLINE_SIZE_MOM"><h3><u>Changing point size</u></h3></a> + +<p> +<strong>Mom</strong> has two inline escapes for changing point +size: + +<pre> + \*[SIZE <size>] +</pre> + +and + +<pre> + \*[S<size>] +</pre> + +where "size" 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 + +<pre> + \*[SIZE 12] +</pre> + +or + +<pre> + \*S[12] +</pre> +</p> + +<p> +The advantage of the first form is that it's easy to remember, and +follows <strong>mom</strong>'s usual inline syntax. The advantage +of the second is that it's more concise. +</p> + +<p> +Notice that in both cases, the new size does not require a +<a href="definitions.html#TERMS_UNITOFMEASURE">unit of measure</a>; +<a href="definitions.html#TERMS_PICASPOINTS">points</a> +is assumed. However, a unit of measure may be appended to the size +if that's what you wish. Fractional sizes are, of course, allowed. +</p> + +<p> +The size given to <kbd>\*[SIZE <size>]</kbd> or +<kbd>\*S[<size>]</kbd> may be expressed in plus or minus +terms, which can be very useful. In the following examples, the +word "mom" will be output 2 points larger than the point +size of the rest of the line. + +<pre> + 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. +</pre> +</p> + +<p> +<strong>NOTE CONCERNING DOCUMENT PROCESSING:</strong> If you'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 <strong>mom</strong>'s inline escape +for changing point size <em>inside</em> 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 inline beginning with <kbd>\*E</kbd> +rather than just <kbd>\*</kbd>. +</p> + +<p> +<strong>ADDITIONAL NOTE:</strong> If you're accustomed to groff'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. +<strong>Mom</strong> doesn't care. +</p> + +<!-- -CAPITALISATION- --> + +<hr width="33%" align="left"/> + +<a name="UC_LC"><h3><u>Capitalise a section of type</u></h3></a> + +<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: + +<pre> + All work \*[UC]and\*[LC] no play makes Jack a dull boy. +</pre> + +The above produces, on output + +<pre> + All work AND no play makes Jack a dull boy. +</pre> +</p> + +<p> +Most of the time, when you need type in all caps (upper case), you +simply enter it that way in your input files. The chief use of +<kbd>\*[UC]...\*[LC]</kbd> is for capitalizing +<strong>mom</strong>'s +<a href="headfootpage.html#RESERVED_STRINGS">reserved strings</a> +when designing your own +<a href="headfootpage.html#HEADFOOTPAGE_INTRO">HEADERS or FOOTERS</a> +during document processing. If you are using +<kbd>\*[UC]...\*[LC]</kbd> for this purpose, you must enter both +inlines beginning with <kbd>\*E</kbd> rather than just <kbd>\*</kbd>. +</p> + +<!-- -INLINE_KERNING_MOM- --> + +<hr width="33%" align="left"/> + +<a name="INLINE_KERNING_MOM"><h3><u>Pairwise kerning</u></h3></a> + +<p> +Pairwise kerning means moving specific letter pairs closer +together or further apart (see +<a href="definitions.html#TERMS_KERN">Typesetting terms, kerning</a> +for more details). +</p> + +<p> +<strong>Mom</strong> permits inline pairwise +kerning through the use of the inline escapes + +<pre> + \*[BU <n>] Closes the space between letters (<strong>B</strong>ack <strong>U</strong>nits). + \*[FU <n>] Opens the space between letters (<strong>F</strong>orward <strong>U</strong>nits). +</pre> + +"<strong><n></strong>" is the number of +<a href="definitions.html#TERMS_KERNUNIT">kern units</a> +by which to close or open the space between letters. +</p> + +<p> +For example, + +<pre> + THE HUMAN COST OF COMMODIF\*[FU 1]YING FRESH W\*[BU 4]A\*[BU 5]TER +</pre> + +moves the letter <strong>Y</strong> in "COMMODIFYING" +1 kern unit away from the letter <strong>F</strong>, and the +letter <strong>A</strong> in "WATER" 4 kern units closer +to the letter <strong>W</strong>. Additionally, the letter +<strong>T</strong> in "WATER" is moved 5 kern units closer to the +letter <strong>A</strong>. +</p> + +<p> +For backward compatibility, the forms + +<pre> + \*[BU1]...\*[BU36] Move backward 1...36 <a href="definitions.html#TERMS_KERNUNIT">kern units</a> + \*[FU1]...\*[FU36] Move forward 1...36 <a href="definitions.html#TERMS_KERNUNIT">kern units</a> +</pre> + +also exist (i.e. with no space before the number of kern units desired, +up to a limit of 36). +</p> + +<p> +<strong>NOTE CONCERNING DOCUMENT PROCESSING:</strong> If you'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 <strong>mom</strong>'s inline escapes +for kerning <em>inside</em> 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 inline beginning with <kbd>\*E</kbd> +rather than just <kbd>\*</kbd>. +</p> + +<p> +<strong>ADDITIONAL NOTE:</strong> Using <strong>BU</strong> or <strong>FU</strong> +between characters pairs that are already automatically kerned +disables the automatic kerning and uses the value you give to +<strong>BU</strong> or <strong>FU</strong> instead. +</p> + +<!-- -INLINE_HORIZONTAL_MOM- --> + +<hr width="33%" align="left"/> + +<a name="INLINE_HORIZONTAL_MOM"><h3><u>Horizontal inline movement</u></h3></a> + +<p> +Sometimes, you may need to insert a specified amount amount of white +space into an +<a href="definitions.html#TERMS_OUTPUTLINE">output line</a>, +or — occasionally — back up to a +previous position on an +<a href="definitions.html#TERMS_INPUTLINE">output</a> +line in order to create special typographic effects. +</p> + +<p> +<strong>Mom</strong>'s inline escapes for these horizontal movements are + +<pre> + <a name="BCK">\*[BCK <n unit>]</a> Move backward inline the specified number of + <a href="definitions.html#TERMS_UNITOFMEASURE">units of measure</a>; decimal fractions are allowed. + + <a name="FWD">\*[FWD <n unit>]</a> Move forward inline the specified number of + <a href="definitions.html#TERMS_UNITOFMEASURE">units of measure</a>; decimal fractions are allowed. +</pre> +</p> + +<p> +For example, + +<pre> + 1.\*[FWD 12p]The Free Trade Play-Offs: WalMart 100, Mexico 0 +</pre> + +puts 12 points of space between <strong>1.</strong> and +<strong>The</strong>. +</p> + +<p> +<strong>NOTE:</strong> For backward compatibility, the forms + +<pre> + \*[BP.25]...\*[BP12.75] Move backward .25...12.75 points + \*[FP.25]...\*[FP12.75] Move forward .25...12.75 points +</pre> + +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's possible to do, for example, +<kbd>\*[FP.5]</kbd> or <kbd>\*[BP1.25]</kbd> up to a limit +of 12.75 points. +</p> + +<p> +<strong>NOTE CONCERNING DOCUMENT PROCESSING:</strong> If you'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 <strong>mom</strong>'s inline escapes for horizontal movements +<em>inside</em> 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 inline beginning with <kbd>\*E</kbd> +rather than just <kbd>\*</kbd>. +</p> + +<!-- -INLINE_VERTICAL_MOM- --> + +<hr width="33%" align="left"/> + +<a name="INLINE_VERTICAL_MOM"><h3><u>Vertical inline movement</u></h3></a> + +<p> +If you need to move portions of type up or down on a line, +<strong>mom</strong> provides the following inline escapes: + +<pre> + <a name="DOWN">\*[DOWN <n unit>]</a> Move down inline the specified number of + <a href="definitions.html#TERMS_UNITOFMEASURE">units of measure</a> + + <a name="UP">\*[UP <n unit>]</a> Move up inline the specified number of + <a href="definitions.html#TERMS_UNITOFMEASURE">units of measure</a> +</pre> +</p> + +<p> +For example, + +<pre> + Tel: 905\*[UP 1p]-\*[DOWN 1p]4072 +</pre> + +moves the hyphen in the telephone number up by 1 point, then +moves back down by the same amount. +</p> + +<p> +<strong>NOTE:</strong> <kbd>\*[UP]</kbd> and <kbd>\*[DOWN]</kbd> do +not work with the inline escape, +<kbd><a href="#INLINE_RULE_MOM">\*[RULE]</a></kbd>. +See +<a href="#RULE_EXCEPTION">here</a> +for details. +</p> + +<p> +<strong>ADDITIONAL NOTE:</strong> For backward compatibility, the +following are also available: + +<pre> + \*[ALD.25]...\*[ALD12.75] Advance lead .25...12.75 points (move downward) + \*[RLD.25]...\*[RLD12.75] Reverse lead .25...12.75 points (move upward) +</pre> +</p> + +<p> +Both <kbd>\*[ALD]</kbd> and <kbd>\*[RLD]</kbd> work in points, hence +you mustn't use a unit of measure. +</p> + +<p> +<strong>NOTE CONCERNING DOCUMENT PROCESSING:</strong> If you'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 <strong>mom</strong>'s inline escapes for vertical movements +<em>inside</em> 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 inline beginning with <kbd>\*E</kbd> +rather than just <kbd>\*</kbd>. +</p> + +<!-- -INLINE_B_MOM- --> + +<hr width="33%" align="left"/> + +<a name="B"><h3><u>Terminate a line without advancing on the page</u></h3></a> + +<p> +Sometimes, you want <strong>mom</strong> 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 <strong>mom</strong> 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 <strong>EL</strong>, you'd use +<kbd>\*[B]</kbd> like this: + +<pre> + .LEFT + .LS 12.5 + A line of text.\*[B] + .ALD 24p + The next line of text. +</pre> + +<kbd>\*[B]</kbd> works reliably regardless of the current +<a href="definitions.html#TERMS_FILLED">fill mode</a>. +</p> + +<!-- -INLINE_TB+_MOM- --> + +<hr width="33%" align="left"/> + +<a name="TB+"><h3><u>Call the next sequential tab without advancing on the page</u></h3></a> + +<p> +Sometimes, you want <strong>mom</strong> to move to the next tab in +sequence (e.g. from TAB 1 to TAB 2, or TAB 8 to TAB 9) without +<strong>mom</strong> advancing on the page. (See the NOTE +<a href="typesetting.html#NOTE_TN">here</a> +if you're not clear how <strong>mom</strong> manages tabs and +linebreaks.) +</p> + +<p> +In versions of <strong>mom</strong> 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: + +<pre> + .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 +</pre> + +<kbd>\*[TB+]</kbd> works reliably regardless of the current +<a href="definitions.html#TERMS_FILLED">fill mode</a>. +</p> + +<!-- -INLINE_RULE_MOM- --> + +<hr width="33%" align="left"/> + +<a name="INLINE_RULE_MOM"><h3><u>Full measure rules</u></h3></a> + +<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't mean a whole heck of a lot if +you'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: + +<pre> + .LL 6P + \*[RULE] +</pre> + +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#TERMS_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>. <strong>Mom</strong>'s +default is 1/2 point. +</p> + +<p> +Please note that <kbd>\*[RULE]</kbd> draws the rule to the full +measure, hence it <em>cannot</em> be used to fill the remainder of a +partial line with a rule in this way: + +<pre> + Signature__________________________________________ +</pre> +</p> + +<p> +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 <strong>PAD</strong>.) +<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>. This +<em>doesn't</em> work: + +<pre> + \*[DOWN 2p]\*[RULE]\*[UP 2p] +</pre> +</p> + +<p> +This does: + +<pre> + .ALD 2p + \*[RULE] + .RLD 2p +</pre> +</p> + +<p> +See groff's +<a href="#INLINE_LINEDRAWING_GROFF">Horizontal line drawing function</a> +for more information on drawing horizontal rules. +</p> + +<!-- -RULE_WEIGHT- --> + +<hr width="33%" align="left"/> + +<a name="RULE_WEIGHT"></a> + +<p> +<nobr>Macro: <strong>RULE_WEIGHT</strong> <kbd><weight in points></kbd></nobr> +<br/> + +<em>*Argument must be greater than 0 and less than 100; decimal +fractions are allowed</em> +<br/> + +<em>*Must </em>not<em> have a <a href="definitions.html#TERMS_UNITOFMEASURE">unit of measure</a> appended</em> +</p> + +<p> +<strong>RULE_WEIGHT</strong> allows you to tell <strong>mom</strong> +how heavy (in other words, how "thick") 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#TERMS_PICASPOINTS">points</a> +<em>but without the</em> +<a href="definitions.html#TERMS_UNITOFMEASURE">unit of measure</a> +<strong><kbd>p</kbd></strong> <em>attached</em>. Thus, to set the weight of rules +drawm with <kbd>\*[RULE]</kbd> to 1-1/4 points, you'd do + +<pre> + .RULE_WEIGHT 1.25 +</pre> +</p> + +<p> +<strong>RULE_WEIGHT</strong> also sets the weight of rules drawn +with +<a href="graphical.html#DRH"><kbd>.DRH</kbd></a> +when <strong>DRH</strong> is not given any arguments. +</p> + +<hr/> + +<!-- -INLINE_FONT_GROFF- --> + +<h2><u>Groff inline escapes</u></h2> + +<a name="INLINE_FONTS_GROFF"><h3><u>Font control</u> (<kbd>\f</kbd>)</h3></a> + +<p> +Groff's basic mechanism for inline font control is the escape +<kbd>\f[<font>]</kbd>. +</p> + +<pre> + \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]) +</pre> + +<p> +<kbd>\f[<font>]</kbd> can be used with any valid +<a href="definitions.html#TERMS_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 +<strong>mom</strong>). +</p> + +<p> +<kbd>\f[<font>]</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: + +<pre> + .FAM T + .FT R + The command \f[CBI]ls -l\f[P] gives a "long" directory listing. +</pre> + +The Unix command <kbd><strong>ls -l</strong></kbd> will appear in +Courier Bold Italic in a line that is otherwise in Times Roman. +</p> + +<!-- -INLINE_HORIZONTAL_GROFF- --> + +<hr width="33%" align="left"/> + +<a name="INLINE_HORIZONTAL_GROFF"><h3><u>Inline horizontal motions</u> (<kbd>\h</kbd>)</h3></a> + +<p> +Whenever you need to move forward or backward on a line, use +the inline + +<pre> + \h'<distance>' +</pre> +</p> + +<p> +In order to avoid unpleasant surprises, always append a +<a href="definitions.html#TERMS_UNITOFMEASURE">unit of measure</a> +to <kbd><distance></kbd>. For example, + +<pre> + \h'1.25i' +</pre> + +moves you 1.25 inches to the right (forward) of the horizontal +position on the current +<a href="definitions.html#TERMS_OUTPUTLINE">output line</a>. +<kbd>\h'<distance>'</kbd> is exactly equivalent to +<a href="#FWD"><kbd>\*[FWD n<unit>]</kbd></a>. +</p> + +<p> +To move backwards by the same amount, do + +<pre> + \h'-1.25i' +</pre> + +<kbd>\h'-<distance>'</kbd> is exactly equivalent to +<a href="#BCK"><kbd>\*[BCK n<unit>]</kbd></a>. +</p> + +<!-- -INLINE_VERTICAL_GROFF- --> + +<hr width="33%" align="left"/> + +<a name="INLINE_VERTICAL_GROFF"><h3><u>Inline vertical motions</u> (<kbd>\v</kbd>)</h3></a> + +<p> +If you need to raise or lower type on a line (say, for sub- or +superscripts, or any other special effect), use + +<pre> + \v'<distance>' +</pre> +</p> + +<p> +In order to avoid unpleasant surprises, always append a +<a href="definitions.html#TERMS_UNITOFMEASURE">unit of measure</a> +to "distance". For example, + +<pre> + \v'.6m' +</pre> + +moves you (approx.) 2/3 of an +<a href="definitions.html#TERMS_EM">em</a> +downward on the current +<a href="definitions.html#TERMS_OUTPUTLINE">output line</a>. +<kbd>\v'<distance>'</kbd> is exactly equivalent to +<a href="#DOWN"><kbd>\*[DOWN n<unit>]</kbd></a>. +</p> + +<p> +To move upward an equivalent amount, do + +<pre> + \v'-.6m' +</pre> +</p> + +<p> +<kbd>\v'<-distance>'</kbd> is exactly equivalent to <a +href="#UP"><kbd>\*[UP n<unit>]</kbd></a>. +</p> + +<p> +<strong>IMPORTANT:</strong> The vertical motion of <kbd>\v</kbd> +affects ONLY type on the current +<a href="definitions.html#TERMS_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't used <kbd>\v</kbd>. +</p> + +<p> +<strong>TIP:</strong> When using <kbd>\v</kbd> for +occasional effects on a line, don'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> + +<!-- -INLINE_STRINGWIDTHL_GROFF- --> + +<hr width="33%" align="left"/> + +<a name="INLINE_STRINGWIDTH_GROFF"><h3><u>String width function</u> (<kbd>\w</kbd>)</h3></a> + + +<p> +In the context of <strong>mom</strong>, the string width inline +<kbd>\w'string'</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 "Examples:" plus a space, you can set it with +the <kbd>\w</kbd> inline escape: + +<pre> + .IL "\w'Examples: '" +</pre> +</p> + +<p> +<strong>NOTE:</strong> Whenever you pass <kbd>\w'string'</kbd> +to a macro that normally requires a +<a href="definitions.html#TERMS_UNITOFMEASURE">unit of measure</a>, +<em>do <strong>NOT</strong> add a unit of measure to the</em> +<kbd>\w'string'</kbd> <em>argument.</em> +</p> + +<p> +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> + +<!-- -INLINE_LINEDRAWING_GROFF- --> + +<hr width="33%" align="left"/> + +<a name="INLINE_LINEDRAWING_GROFF"><h3><u>Horizontal line drawing function</u> (<kbd>\l</kbd>)</h3></a> + +<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#TERMS_UNITOFMEASURE">unit of measure</a>. +Therefore, to set a 3-pica rule into a line of text, you'd do + +<pre> + A line of text with a superfluous \l'3P' 3-pica rule in it. +</pre> +</p> + +<p> +<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'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> + +<p> +<strong>NOTE:</strong> Besides <kbd>\l</kbd>, <strong>groff</strong> +provides a number of more sophisticated "drawing" +escapes. It is well beyond the scope of this documentation +to demonstrate their usage; see +<nobr><kbd>info groff => Escape index => \D</kbd></nobr> +for directions concerning their use. The drawing escapes +can be a bit unwieldy, so <strong>mom</strong> provides +"user-friendly" 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> +Additionally, <strong>groff</strong> comes with two +"preprocessors" that let you create ruled tables and +vector diagrams (line drawings): <strong>tbl</strong> and +<strong>pic</strong>. The documentation +for <strong>tbl</strong> can be downloaded from + +<pre> + <a 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>; +</pre> + +<strong>pic</strong> from + +<pre> + <a href="http://www.kohala.com/start/troff/gpic.raymond.ps">http://www.kohala.com/start/troff/gpic.raymond.ps</a>. +</pre> + +Both are powerful tools, but they can be nasty to learn — +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> + +<!-- -INLINE_CHARACTERS_GROFF- --> + +<hr width="33%" align="left"/> + +<a name="INLINE_CHARACTERS_GROFF"><h3><u>Special characters and symbols</u></h3></a> + +<p> +Here follows a short list of commonly-used special characters available +via inline escapes. If you're not sure of the meaning of some of +these characters, consult the +<a href="definitions.html#TERMS">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>. + +<pre> + CHARACTER ESCAPE SEQUENCE + --------- --------------- + + Comment line \# + Fixed-width space \<space> i.e. backslash followed by a space + Unbreakable space \~ + Digit-width (figure) space \0 + Zero-width character \& + Discretionary hyphen \% + Backslash \\ or \e + Plus/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 +</pre> +</p> + +<hr/> + +<p> +<a href="color.html#TOP">Next</a> +<a href="goodies.html#TOP">Prev</a> +<a href="#TOP">Top</a> +<a href="toc.html">Back to Table of Contents</a> +</p> + +</body> +</html> + +<!-- vim: fileencoding=latin1: nomodified: +--> diff --git a/contrib/mom/momdoc/intro.html b/contrib/mom/momdoc/intro.html new file mode 100644 index 00000000..85ab852f --- /dev/null +++ b/contrib/mom/momdoc/intro.html @@ -0,0 +1,502 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!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=iso-8859-1"/> +<title>What is mom?</title> +</head> +<body bgcolor="#dfdfdf"> + +<!-- ==================================================================== --> + +<a name="TOP"></a> + +<p> +<a href="definitions.html#TOP">Next</a> +<a href="toc.html">Back to Table of Contents</a> +</p> + +<p> +<a name="INTRO"><h1 align="center"><u>What is mom?</u></h1></a> + +<a href="#INTRO_INTRO">Who is mom meant for?</a> +<br/> + +<a href="#INTRO_TYPESETTING">Typesetting with mom</a> +<br/> + +<a href="#INTRO_DOCPROCESSING">Document processing with mom</a> +<br/> + +<a href="#INTRO_PHILOSOPHY">Mom's philosophy</a> +<br/> + +<a href="#INTRO_DOCUMENTATION">A note on mom's documentation</a> +<br/> + +<a href="#CANONICAL">Canonical reference materials</a> +<br/> + +<a href="#MACRO_ARGS">How to read macro arguments</a> +</p> + +<a name="INTRO_INTRO"><h2><u>Who is mom meant for?</u></h2></a> + +<p> +<strong>Mom</strong> ("my own macros", "my other +macros", "maximum overdrive macros"...) is a macro set for +groff, designed to format documents for PostScript output. +She's aimed at three kinds of users: +</p> + +<ol> + <li>typesetters who suspect groff might be "the right + tool for the job" but who are + frustrated/intimidated by groff's terse, geeky, + not-always-typographically-intuitive + <a href="definitions.html#TERMS_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, <strong>mom</strong> 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's content and logical structure without worrying about +typesetting or page layout at all. +</p> + +<p> +Because <strong>mom</strong> provides both typesetting and document +formatting macros, it'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 — change "spiffy" +to "typographically professional"), 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 <strong>mom</strong>'s document element tags, you don't have to +read up on groff +<a href="definitions.html#TERMS_PRIMITIVES">primitives</a> +in order to accomplish what you want; the typesetting macros take +care of that. +</p> + +<a name="INTRO_TYPESETTING"><h2><u>Typesetting with mom</u></h2></a> + +<p> +<strong>Mom</strong>'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's typesetting +primitives in a way that'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 <strong>mom</strong>'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 <strong>mom</strong> that you +want document processing (via the +<a href="docprocessing.html#START">START</a> +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 +"micro typography" 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's worth, a similar problem exists with engraving musical +scores by computer.) +</p> + +<p> +<strong>Mom</strong> 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#TERMS_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 +<strong>mom</strong>'s typesetting macros. +</p> + +<p> +<strong>Author's note:</strong> 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#TERMS_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> + +<a name="INTRO_DOCPROCESSING"><h2><u>Document processing with mom</u></h2></a> + +<p> +<strong>Mom</strong>'s document processing macros let you format +documents without having to worry about the typographic details. +In this respect, <strong>mom</strong> is similar to other groff macro +packages, as well as to html and LaTeX. Where <strong>mom</strong> +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't want your heads underlined, or you want them bigger/smaller, +or you'd prefer them to be in a different font, or you'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> +<strong>Mom</strong> has some nifty features other macro sets +don'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's a +special macro — +<a href="docprocessing.html#PRINTSTYLE">PRINTSTYLE TYPEWRITE</a> +— 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> + +<a name="INTRO_PHILOSOPHY"><h2><u>Mom's philosophy</u></h2></a> + +<p> +Formatting documents should be easy, from soup to nuts. Writers need +to focus on what they'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'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, "easy," +"comprehensible," and "readable" often mean +"you're stuck with what you get." 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#TERMS_PRIMITIVES">primitives</a> +and +<a href="definitions.html#TERMS_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't really like, or are +forced to learn groff from the ground up — a daunting task, to +say the least. +</p> + +<p> +<strong>Mom</strong> 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 word "user interface" in conjunction +with document processing. Since the user formatting takes place +inside a text editor, little thought is given to the look and feel +of the formatting commands. <strong>Mom</strong> attempts to rectify +this by providing users with a consistent, readable "coding" +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's going on in a document, +typographically and structurally, easier to decipher. +</p> + +<p> +<strong>Mom</strong> 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's displayed. +She's designed for printed output, although with +<a href="docprocessing.html#PRINTSTYLE">PRINTSTYLE TYPEWRITE</a> +she produces acceptable terminal copy. She makes no attempt to be +compatible with older versions of troff. +</p> + +<p> +One special feature in <strong>mom</strong>'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, "hang." There are, +of course, situations where whitespace at the bottom of a page may +be desirable (for example, you wouldn'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, <strong>mom</strong> does +avoid them, by clever adjustments to leading ("line spacing") +and the spacing between different elements on the page. +</p> + +<a name="INTRO_DOCUMENTATION"><h2><u>A note on mom's documentation</u></h2></a> + +<p> +Writing documentation is tough, no doubt about it. One is never +quite sure of the user'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 who 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> +<strong>Mom</strong>'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, +<strong>mom</strong> 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't know much about it. Lastly, it assumes that +everyone — groff newbies and experts alike — learns +faster from a few well-placed examples than from manpage-style +reference docs. What <strong>mom</strong>'s documentation doesn't +assume is that you know everything--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't enough, I offer examples. +</p> + +<a name="CANONICAL"><h3><u>Canonical reference materials</u></h3></a> + +<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 <strong>info</strong> pages, available by typing + +<pre> + info groff +</pre> + +at the command line (assuming you have the <strong>TeXinfo +standalone browser</strong> installed on your system, which is +standard for most GNU/Linux distributions). And for +inputting special characters, see <strong>man groff_char.</strong> +</p> + +<p> +I'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'm more interested in getting +<strong>mom</strong> users up and running. <em>Mea culpa.</em> +</p> + +<p> +<strong>Note:</strong> <strong>Mom</strong>'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's contained in this +documentation. +</p> + +<p> +<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 <strong>mom</strong>'s +homepage. +</p> + +<hr/> + +<a name="MACRO_ARGS"><h2><u>How to read macro arguments</u></h2></a> + +<p> +The concise descriptions of macros in this documentation typically +look like this: + +<blockquote> + <nobr>Macro: <strong>NAME</strong> <kbd>arguments</kbd></nobr> +</blockquote> +</p> + +<p> +<kbd>arguments</kbd> lists the macro's arguments using conventions that +should be familiar to anyone who has ever read a manpage. Briefly: + +<ol> + <li>Macro arguments are separated from each other by spaces. + </li> + <li>If an argument is surrounded by chevrons + (<kbd>< ></kbd>), it'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 "or." + </li> + <li>Arguments that are optional are surrounded by square brackets. + </li> + <li><kbd><off></kbd> in an argument list means that any + argument other than those in the argument list turns the + macro off. + </li> +</ol> +</p> + +<a name="TOGGLE_MACRO"><h3><u>Toggle macros</u></h3></a> + +<p> +Some macros don'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's right: ANY argument. This permits +choosing whatever works for you: OFF, END, QUIT, DONE, Q, X... Hell, +it could even be I_LOVE_MOM. +</p> + +<p> +Since these macros toggle things on and off, the argument list +simply reads + +<blockquote> + <kbd>toggle</kbd> +</blockquote> +</p> + +<h4><u>Example 1: An argument requiring double-quotes</u></h4> + +<blockquote> + <nobr>Macro: <strong>TITLE</strong> <kbd>"<title of document>"</kbd></nobr> +</blockquote> + +<p> +The required argument to <strong>TITLE</strong> is the title of your +document. Since it's surrounded by double-quotes, you must +include them in the argument, like this: + +<pre> + .TITLE "My Pulitzer Novel" +</pre> +</p> + +<h4><u>Example 2: A macro with required and optional arguments</u></h4> + +<blockquote> + <nobr>Macro: <strong>TAB_SET</strong> <kbd><tab #> <indent> <length> [ L | R | C | J [ QUAD ] ]</kbd></nobr> +</blockquote> + +<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: + +<pre> + .TAB_SET 3 6P 3P +</pre> +</p> + +<p> +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: + +<pre> + .TAB_SET 3 6P 3P L + or + .TAB_SET 3 6P 3P L QUAD +</pre> +</p> + +<a name="TOGGLE_EXAMPLE"><h4><u>Example 3: A sample toggle macro:</u></h4></a> + +<blockquote> + <nobr>Macro: <strong>QUOTE</strong> <kbd>toggle</kbd></nobr> +</blockquote> + +<p> +<strong>QUOTE</strong> begins a section of quoted text in a document +and doesn't require an argument. When the quote's finished, +you have to tell <strong>mom</strong> it's done. + +<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 +</pre> +</p> + +<p> +Alternatively, you could have turned the quote off with +<kbd>END</kbd>, or <kbd>X</kbd>, or something else. +</p> + +<hr/> + +<p> +<a href="definitions.html#TOP">Next</a> +<a href="#TOP">Top</a> +<a href="toc.html">Table of Contents</a> +</p> + +</body> +</html> +<!-- vim: fileencoding=latin1: nomodified: +--> diff --git a/contrib/mom/momdoc/letters.html b/contrib/mom/momdoc/letters.html new file mode 100644 index 00000000..6c3137be --- /dev/null +++ b/contrib/mom/momdoc/letters.html @@ -0,0 +1,547 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!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=iso-8859-1"/> +<title>Mom -- Document Processing, Writing Letters</title> +</head> +<body bgcolor="#dfdfdf"> + +<!-- ==================================================================== --> + +<a name="TOP"></a> + +<p> +<a href="macrolist.html#TOP">Next</a> +<a href="refer.html#TOP">Prev</a> +<a href="toc.html">Back to Table of Contents</a> +</p> + +<a name="LETTERS"><h1 align="center"><u>Writing letters with mom</u></h1></a> + +<a name="LETTERS_INTRO"><h2><u>Introduction</u></h2></a> + +<p> +<strong>Mom</strong>'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#TERMS_CONTROLMACRO">control macros</a> +to design correspondence to your own specifications. However, +<strong>mom</strong> 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> + +<hr width="66%" align="left"/> + +<p> +<a name="TUTORIAL"><h2><u>Tutorial on writing letters</u></h2></a> +</p> + +<p> +<strong>Mom</strong> letters begin, like all +<strong>mom</strong>-processed documents, with a +<a href="docprocessing.html#REFERENCE_MACROS">reference macro</a> +(in this case, +<a href="docprocessing.html#AUTHOR">AUTHOR</a>), +a +<a href="docprocessing.html#DOCTYPE">DOCTYPE</a> +(<strong>LETTER</strong>, obviously), the essential +<a href="docprocessing.html#PRINTSTYLE">PRINTSTYLE</a> +macro, and +<a href="docprocessing.html#START">START</a>, +like this: + +<pre> + .AUTHOR "Yannick P. Guique" + .DOCTYPE LETTER + .PRINTSTYLE TYPESET + .START +</pre> +</p> + +<p> +<strong>PRINTSTYLE</strong>, above, could also be +<strong>TYPEWRITE</strong>. <strong>Mom</strong> 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 <strong>START</strong> macro, you enter headers pertinent +to your letter: the date, the addressee (in business correspondence, +typically both name and address), the addresser (that's you; in +business correspondence, typically both name and address), and a +greeting (in full, e.g. "Dear Mr. Smith," or "Dear +Mr. Smith:"). +</p> + +<p> +The macros for entering the headers are simple (they're not even +<a href="definitions.html#TERMS_TOGGLE">toggles</a>): + +<pre> + .DATE + .TO + .FROM + .GREETING +</pre> +</p> + +<p> +You may enter them in any order you like, except for +<strong>GREETING</strong>, which must come last. +<strong>Mom</strong> ignores any headers you omit and spaces the +letter's opening according to what you do include. See +<a href="#LETTERS_DEFAULTS">Default for letters</a> +to find out how <strong>mom</strong> formats the headers. +</p> + +<p> +(In pre 1.1.7-a releases of <strong>mom</strong>, the order +of entry was fixed at the above. This has been changed, although +if you do follow the above order, <strong>mom</strong> will +continue to behave exactly as she did in pre 1.1.7-a.) +</p> + +<p> +Once you'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 an indented closing +("Yours truly," "Sincerely," "Hugs and +kisses"), invoke the macro, <kbd>.CLOSING</kbd>, on a +line by itself and follow it with the text of the closing. +<strong>N.B.</strong> Don't put your name here; <strong>mom</strong> +supplies it automatically from <strong>AUTHOR</strong> with +enough space to leave room for your signature. +</p> + +<p> +Assuming our tutorial letter is for business correspondence, +here's what the complete letter looks like. +</p> + +<pre> + .AUTHOR "Yannick P. Guique" + .DOCTYPE LETTER + .PRINTSTYLE TYPESET + .START + .DATE + August 25, 2004 + .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 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 with its embedded web browser relies heavily + on open source programs and protocols, most notably TCP/IP. + .PP + Therefore, in the interests of your corporation'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, +</pre> + +<p> +This produces a letter with headers that follow the North American +standard for business correspondence. If you'd prefer another style +of correspondence, for example, British, you'd set up the same +letter like this: + +<pre> + .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, +</pre> +</p> + +<p> +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> + +<hr width="66%" align="left"/> + +<a name="LETTERS_DEFAULTS"><h2><u>Defaults for letters</u></h2></a> + +<p> +In letters, if the order of header macros is + +<pre> + .DATE + .TO + .FROM + .GREETING +</pre> + +<strong>mom</strong> sets + +<ol> + <li>the date flush right, page right, at the top of page one, + with a gap of two linespaces underneath + </li> + <li>the addressee in a block flush left, page left, with a gap of + one linespace underneath + </li> + <li>the addresser 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> +</ol> +</p> + +<p> +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>, <strong>mom</strong> 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, <strong>mom</strong> sets + +<ul> + <li>the body of the letter justified</li> + <li>in multi-page letters:</li> + <ul> + <li>a footer indicating there's a next page (of the form <nobr><kbd>.../#</kbd>)</nobr></li> + <li>the page number at the top of every page after page one</li> + </ul> + <li>the closing/signature line flush left, indented halfway across the page</li> +</ul> +</p> + +<p> +Other important style defaults are listed below, and may be changed +via the +<a href="typesetting.html#MACROS_TYPESETTING">typesetting macros</a> +or the document processing +<a href="definitions.html#TERMS_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 +<a href="docprocessing.html#TYPESET_DEFAULTS">PRINTSTYLE TYPESET</a> +or +<a href="docprocessing.html#TYPEWRITE_DEFAULTS">PRINTSTYLE TYPEWRITE</a>. +</p> + +<pre> +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 "next page" number of the form .../# +</pre> + +<hr/> + +<a name="LETTERS_MACROS"><h2><u>The letter macros</u></h2></a> + +<p> +All letter macros must come after +<a href="docprocessing.html#START">START</a>, +except <strong>NO_SUITE</strong>. +</p> + +<ul> + <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></li> + <li><a href="#NO_SUITE">NO_SUITE</a> — "next page" number off</li> +</ul> + +<!-- -DATE- --> + +<hr width="66%" align="left"/> + +<a name="DATE"></a> + +<p> +Macro: <strong>DATE</strong> +</p> + +<p> +Invoke <kbd>.DATE</kbd> on a line by itself, with the date +underneath, like this: + +<pre> + .DATE + October 31, 2002 +</pre> +</p> + +<p> +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: + +<pre> + .DATE + October 31, 2002 + .SPACE \"Or, more simply, .SP +</pre> +</p> + +<p> +If you wish to remove the default space, + +<pre> + .SPACE -1v \"Or, more simply, .SP -1v +</pre> + +will do the trick. +</p> + +<!-- -TO- --> + +<hr width="33%" align="left"/> + +<a name="TO"></a> + +<p> +Macro: <strong>TO</strong> +</p> + +<p> +Invoke <kbd>.TO</kbd> on a line by itself, with the name +and address of the addressee underneath, like this: + +<pre> + .TO + JOHN SMITH + 10 Roberts Crescent + Bramladesh, Ont. +</pre> +</p> + +<p> +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: + +<pre> + .TO + JOHN SMITH + 10 Roberts Crescent + Bramladesh, Ont. + .SPACE \"Or, more simply, .SP +</pre> +</p> + +<p> +If you wish to remove the default space, + +<pre> + .SPACE -1v \"Or, more simply, .SP -1v +</pre> + +will do the trick. +</p> + +<!-- -FROM- --> + +<hr width="33%" align="left"/> + +<a name="FROM"></a> + +<p> +Macro: <strong>FROM</strong> +</p> + +<p> +Invoke <kbd>.FROM</kbd> on a line by itself, with the name +and address of the addresser underneath, like this: + +<pre> + .FROM + JOE BLOW + 15 Brunette Road + Ste-Vieille-Andouille, Québec +</pre> +</p> + +<p> +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: + +<pre> + .FROM + JOE BLOW + 15 Brunette Road + Ste-Vieille-Andouille, Québec + .SPACE \"Or, more simply, .SP +</pre> +</p> + +<p> +If you wish to remove the default space, + +<pre> + .SPACE -1v \"Or, more simply, .SP -1v +</pre> + +will do the trick. +</p> + +<!-- -GREETING- --> + +<hr width="33%" align="left"/> + +<a name="GREETING"></a> + +<p> +Macro: <strong>GREETING</strong> +</p> + +<p> +Invoke <kbd>.GREETING</kbd> on a line by itself, with the +full salutation you want for the letter, like this: + +<pre> + .GREETING + Dear Mr. Smith, +</pre> +</p> + +<!-- -CLOSING- --> + +<hr width="33%" align="left"/> + +<a name="CLOSING"></a> + +<p> +Macro: <strong>CLOSING</strong> +</p> + +<p> +Invoke <kbd>.CLOSING</kbd> on a line by itself after the body of the +letter, with the closing you'd like (e.g. "Yours truly,"), +like this: + +<pre> + .CLOSING + Yours truly, +</pre> +</p> + +<!-- -NO_SUITE- --> + +<hr width="33%" align="left"/> + +<a name="NO_SUITE"></a> + +<p> +Macro: <strong>NO_SUITE</strong> +</p> + +<p> +If you don't want <strong>mom</strong> to print a "next +page" 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> + +<hr/> + +<p> +<a href="macrolist.html#TOP">Next</a> +<a href="refer.html#TOP">Prev</a> +<a href="#TOP">Top</a> +<a href="toc.html">Back to Table of Contents</a> +</p> + +</body> +</html> + +<!-- vim: fileencoding=latin1: nomodified: +--> diff --git a/contrib/mom/momdoc/macrolist.html b/contrib/mom/momdoc/macrolist.html new file mode 100644 index 00000000..030c9778 --- /dev/null +++ b/contrib/mom/momdoc/macrolist.html @@ -0,0 +1,458 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!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=iso-8859-1"/> +<title>Mom -- Quick reference guide</title> +</head> +<body bgcolor="#dfdfdf"> + +<!-- ==================================================================== --> + +<a name="TOP"></a> + +<p> +<a href="appendices.html#TOP">Next</a> +<a href="typemacdoc.html#TOP">Prev</a> +<a href="toc.html">Back to Table of Contents</a> +</p> + +<h1 align="center"><a name="QUICK"><u>Quick reference guide to mom</u></a></h1> + +<p> +Once you know your way around <strong>mom</strong>, you may find +this guide preferable to using the Table of Contents. It lists +<strong>mom</strong>'s major user-space macros. The links point to +references found elsewhere in the documentation. +</p> + +<h2 align="center"><u>Index to the quick reference guide</u></h2> + +<pre> +TYPESETTING MACROS DOCUMENT PROCESSING MACROS +================== ========================== +<a href="#1">Paper size, margins, line length</a> <a href="#18">Reference macros</a> +<a href="#2">Family, font, point size</a> <a href="#19">General document formatting directives</a> +<a href="#3">Font modifications</a> <a href="#20">Line numbering</a> +<a href="#4">Linespacing (leading)</a> <a href="#21">Set documents in columns</a> +<a href="#5">Justification, quad, breaking lines</a> <a href="#22">TYPEWRITE control macros</a> +<a href="#6">Hyphenation</a> <a href="#23">Initiate document processing</a> +<a href="#7">Word and sentence spacing</a> <a href="#24">Epigraphs</a> +<a href="#8">Kerning, ligatures, smartquotes</a> <a href="#25">Main heads</a> +<a href="#9">Horizontal/vertical motions, columns</a> <a href="#26">Subheads</a> +<a href="#10">Indents</a> <a href="#27">Paragraph heads</a> +<a href="#11">Tabs</a> <a href="#28">Paragraphs</a> +<a href="#12">Underscoring, underlining</a> <a href="#29">Quotes (line by line verbatim quotes)</a> +<a href="#13">Superscipts</a> <a href="#30">Blockquotes (cited passages of text)</a> +<a href="#14">Nested lists</a> <a href="#32">Author linebreaks (section breaks)</a> +<a href="#15">Colour</a> <a href="#33">Document termination string</a> +<a href="#16">Dropcaps</a> <a href="#34">Footnotes</a> +<a href="#17">Utilities</a> <a href="#35">Endnotes</a> + <a href="#36">Margin notes</a> + <a href="#37">Bibliographic references</a> + <a href="# 38">Tables of contents</a> + <a href="#39">Letter (correspondence) macros</a> + <a href="#40">Changing global print style parameters after START</a> + <a href="#41">Managing a document's first-page header</a> + <a href="#42">Managing page headers and footers</a> + <a href="#43">Recto/verso page headers and footers</a> + <a href="#44">Pagination</a> + <a href="#45">Document and section cover (title) pages</a> + <a href="#46">Utilities</a> +</pre> + +<hr/> + +<h2 align="center"><u>The Quick Reference Guide</u></h2> + +<pre> +TYPESETTING MACROS +================== + +<a name="1">+++ Paper size, margins, line length</a> + <a href="typesetting.htmlPAPER">PAPER</a> -- set common paper sizes (letter, A4, etc) + <a href="typesetting.htmlPAGEWIDTH">PAGEWIDTH</a> -- set a custom page width + <a href="typesetting.htmlPAGELENGTH">PAGELENGTH</a> -- set a custom page length + <a href="typesetting.htmlPAGE">PAGE</a> -- set explicit page dimensions and margins + <a href="typesetting.htmlT_MARGIN">T_MARGIN</a> -- set a top margin + <a href="typesetting.htmlB_MARGIN">B_MARGIN</a> -- set a bottom margin + <a href="typesetting.htmlL_MARGIN">L_MARGIN</a> -- set a left margin (page offset) + <a href="typesetting.htmlR_MARGIN">R_MARGIN</a> -- set a right margin + <a href="typesetting.htmlLINELENGTH">LL</a> -- set a line length + +<a name="2">+++ Family, font, point size</a> + <a href="typesetting.htmlFAMILY">FAMILY</a> -- set the family of type + <a href="typesetting.htmlFONT">FT</a> -- set the font style (roman, italic, etc) + <a href="typesetting.htmlFALLBACK_FONT">FALLBACK_FONT</a> -- establish a fallback font (for missing fonts) + <a href="typesetting.htmlPS">PT_SIZE</a> -- set the point size + <a href="inlines.htmlINLINE_SIZE_MOM">\*[SIZE n]</a> -- change the point size inline + +<a name="3">+++ Font modifications</a> + * Pseudo italic + <a href="typesetting.htmlSETSLANT">SETSLANT</a> -- set the degree of slant + <a href="typesetting.htmlSLANT_INLINE">\*[SLANT]</a> -- invoke pseudo italic inline + <a href="typesetting.htmlSLANT_INLINE">\*[SLANTX]</a> -- turn off pseudo italic inline + + * Pseudo bold + <a href="typesetting.htmlSETBOLDER">SETBOLDER</a> -- set the amount of emboldening + <a href="typesetting.htmlBOLDER_INLINE">\*[BOLDER]</a> -- invoke pseudo bold inline + <a href="typesetting.htmlBOLDER_INLINE">\*[BOLDERX]</a> -- turn off pseudo bold inline + + * Pseudo condensed + <a href="typesetting.htmlCONDENSE">CONDENSE</a> -- set the amount to pseudo condense + <a href="typesetting.htmlCOND_INLINE">\*[COND]</a> -- invoke pseudo condensing inline + <a href="typesetting.htmlCOND_INLINE">\*[CONDX]</a> -- turn off pseudo condensing inlines + + * Pseudo extended + <a href="typesetting.htmlEXTEND">EXTEND</a> -- set the amount to pseudo extend + <a href="typesetting.htmlEXT_INLINE">\*[EXT]</a> -- invoke pseudo extending inline + <a href="typesetting.htmlEXT_INLINE">\*[EXTX]</a> -- turn off pseudo condensing inlinee + +<a name="4">+++ Linespacing (leading)</a> + <a href="typesetting.htmlLEADING">LS</a> -- set the linespacing (leading) + <a href="typesetting.htmlAUTOLEAD">AUTOLEAD</a> -- set the linespacing relative to the point size + +<a name="5">+++ Justification, quad direction, line-by-line setting, breaking lines</a> + <a href="typesetting.htmlJUSTIFY">JUSTIFY</a> -- justify text to both margins + <a href="typesetting.htmlQUAD">QUAD</a> -- "justify" text left, centre, or right + <a href="typesetting.htmlLRC">LEFT</a> -- set line-by-line quad left + <a href="typesetting.htmlLRC">CENTER</a> -- set line-by-line quad centre + <a href="typesetting.htmlLRC">RIGHT</a> -- set line-by-line quad right + <a href="typesetting.htmlBR">BR</a> -- break a justified line + <a href="typesetting.htmlSPREAD">SPREAD</a> -- force justify a line + <a href="typesetting.htmlEL">EL</a> -- break a line without advancing on the page + +<a name="6">+++ Hyphenation</a> + <a href="typesetting.htmlHY">HY</a> -- turn automatic hyphenation on or off + <a href="typesetting.htmlHY_SET">HY_SET</a> -- set automatic hyphenation parameters + +<a name="7">+++ Word and sentence spacing</a> + <a href="typesetting.htmlWS">WS</a> -- set the minimum word space size + <a href="typesetting.htmlSS">SS</a> -- set the sentence space size + +<a name="8">+++ Kerning, ligatures, smartquotes</a> + <a href="typesetting.htmlKERN">KERN</a> -- turn automatic character pair kerning on or off + <a href="inlines.htmlINLINE_KERNING_MOM">\*[BU n]</a> -- move characters pairs closer together inline + <a href="inlines.htmlINLINE_KERNING_MOM">\*[FU n]</a> -- move character pairs further apart inline + <a href="typesetting.htmlRW">RW</a> -- uniformly reduce space between characters (tighten) + <a href="typesetting.htmlEW">EW</a> -- uniformly increase space between characters (loosen) + <a href="typesetting.htmlBR_AT_LINE_KERN">BR_AT_LINE_KERN</a> -- break previous line every time RW or EW is invoked + <a href="typesetting.htmlLIGATURES">LIGATURES</a> -- turn automatic generation of ligatures on or off + <a href="goodies.htmlSMARTQUOTES">SMARTQUOTES</a> -- turn smartquoting on or off + +<a name="9">+++ Horizontal and vertical movements, columnar setting</a> + <a href="typesetting.htmlALD">ALD</a> -- move downards on the page + <a href="typesetting.htmlRLD">RLD</a> -- move upwards on the page + <a href="typesetting.htmlSPACE">SPACE</a> -- insert space between lines on a page + <a href="inlines.htmlDOWN">\*[DOWN n]</a> -- temporarily move downwards in a line + <a href="inlines.htmlUP">\*[UP n]</a> -- temporarily move upwards in a line + <a href="inlines.htmlFWD">\*[FWD n]</a> -- move forward in a line + <a href="inlines.htmlBCK">\*[BCK n]</a> -- move backwards in a line + <a href="typesetting.htmlMCO">MCO</a> -- turn multiple columns on + <a href="typesetting.htmlMCR">MCR</a> -- return to vertical position of column start + <a href="typesetting.htmlMCX">MCX</a> -- turn multiple columns off, advance past longest column + +<a name="10">+++ Indents</a> + <a href="typesetting.htmlIL">IL</a> -- set and turn on a left indent + <a href="typesetting.htmlIR">IR</a> -- set and turn on a right indent + <a href="typesetting.htmlIB">IB</a> -- set and turn on indents both left and right + <a href="typesetting.htmlIQ">IQ</a> -- quit (exit) all indents + <a href="typesetting.htmlTI">TI</a> -- set and turn on a temporary (one line) indent + <a href="typesetting.htmlHI">HI</a> -- set and turn on a hanging indent + <a href="typesetting.htmlIQ">ILX</a> -- turn left indents off + <a href="typesetting.htmlIQ">IRX</a> -- turn right indents off + <a href="typesetting.htmlIQ">IBX</a> -- turn both left and right indents off + +<a name="11">+++ Tabs</a> + <a href="typesetting.htmlTAB_SET">TAB_SET</a> -- set up a typesetting tab + <a href="typesetting.htmlTAB">TAB <n></a> -- call tab <n> + <a href="typesetting.htmlTQ">TQ</a> -- quit (exit) tabs + <a href="typesetting.htmlINLINE_ST">\*[STn]...\*[STnX]</a> -- mark off tab positions inline + <a href="typesetting.htmlTN">TN</a> -- move to tab <n+1> without advancing on the page + <a href="typesetting.htmlST">ST</a> -- set up tabs whose positions were marked inline + +<a name="12">+++ Underscoring, underlining</a> + <a href="goodies.htmlUNDERSCORE">UNDERSCORE</a> -- underscore type + <a href="goodies.htmlUNDERSCORE2">UNDERSCORE2</a> -- double underscore type + <a href="goodies.htmlUNDERLINE">UNDERLINE</a> -- underline type (fixed width fonts only) + <a href="goodies.htmlUL">\*[UL]...\*[ULX]</a> -- invoke underling inline (fixed width fonts only) + +<a name="13">+++ Superscipts</a> + <a href="goodies.htmlSUP">\*[SUP]...\*[SUPX]</a> -- set characters superscript (inline) + <a href="goodies.htmlSUP">\*[CONDSUP]...\*[CONDSUPX]</a> -- set pseudo condensed characters superscript (inline) + <a href="goodies.htmlSUP">\*[EXTSUP]...\*[EXTSUPX]</a> -- set pseudo extended characters superscript (inline) + +<a name="14">+++ Nested lists</a> + <a href="docelement.htmlLIST">LIST</a> -- initiate a nested list + <a href="docelement.htmlITEM">ITEM</a> -- begin an item in a list + <a href="docelement.htmlSHIFT_LIST">SHIFT_LIST</a> -- change the indent of a list + <a href="docelement.html#RESET_LIST">RESET_LIST</a> -- clear and reset a list's enumerator + <a href="docelement.htmlPAD_LIST_DIGITS">PAD_LIST_DIGITS</a> -- space to leave for digits in a digit-enumerated list + +<a name="15">+++ Colour</a> + <a href="color.htmlNEWCOLOR">NEWCOLOR</a> -- initialize (define) a colour + <a href="color.htmlCOLOR">COLOR</a> -- begin using an initialized colour + <a href="color.htmlXCOLOR">XCOLOR</a> -- initialize a "named" X colour + <a href="color.htmlCOLOR_INLINE">\*[<colorname>]</a> -- being using an initialized colour inline + +<a name="16">+++ Dropcaps</a> + <a href="goodies.htmlDROPCAP">DROPCAP</a> -- set a dropcap + <a href="goodies.htmlDROPCAP_FAMILY">DROPCAP_FAMILY</a> -- set a dropcap's family + <a href="goodies.htmlDROPCAP_FONT">DROPCAP_FONT</a> -- set a dropcap's font style + <a href="goodies.htmlDROPCAP_COLOR">DROPCAP_COLOR</a> -- set a dropcap's colour + <a href="goodies.htmlDROPCAP_ADJUST">DROPCAP_ADJUST</a> -- adjust size of a dropcap + <a href="goodies.htmlDROPCAP_GUTTER">DROPCAP_GUTTER</a> -- adjust space between a dropcap and regular text + +<a name="17">+++ Utilities</a> + <a href="goodies.htmlCAPS">CAPS</a> -- set type all caps + <a href="goodies.htmlSILENT">COMMENT</a> -- silently embed comments in a document + <a href="goodies.htmlESC_CHAR">ESC_CHAR</a> -- change the default escape character + <a href="goodies.htmlLEADER">\*[LEADER]</a> -- insert leaders at the end of a line + <a href="goodies.htmlLEADER_CHARACTER">LEADER_CHARACTER</a> -- change the character used for leaders + <a href="typesetting.htmlNEWPAGE">NEWPAGE</a> -- break to a new page + <a href="goodies.htmlPAD">PAD</a> -- insert equalized regions of whitespace into a line + <a href="goodies.htmlPAD_MARKER">PAD_MARKER</a> -- change the character that identifes padding locations + <a href="inlines.htmlINLINE_RULE_MOM">\*[RULE]</a> -- draw a full measure rule + <a href="goodies.htmlSILENT">SILENT</a> -- turn output processing off or on + <a href="goodies.html#TRAP">TRAP</a> -- enable or disable page position traps +</pre> + +<hr width="66%" align="left"/> + +<pre> +DOCUMENT PROCESSING MACROS +========================== + +<a name="18">+++ Reference macros</a> + <a href="docprocessing.html#TITLE">TITLE</a> -- document title + <a href="docprocessing.html#DOCTITLE">DOCTITLE</a> -- overall document title (if different from TITLE) + <a href="docelement.html#ENDNOTE_TITLE">ENDNOTE_TITLE</a> -- document/chapter identification string for endnotes + <a href="docprocessing.html#CHAPTER">CHAPTER</a> -- chapter number + <a href="docprocessing.html#CHAPTER">CHAPTER_TITLE</a> -- chapter title + <a href="docprocessing.html#DRAFT_STRING">CHAPTER_STRING</a> -- what to use in place of "Chapter" + <a href="docprocessing.html#SUBTITLE">SUBTITLE</a> -- document subtitle + <a href="docprocessing.html#AUTHOR">AUTHOR</a> -- document author(s) + <a href="docprocessing.html#COVERTITLE">DOC_COVERTITLE</a> -- document title cover + <a href="docprocessing.html#COVERTITLE">COVERTITLE</a> -- section cover title + <a href="docprocessing.html#COVERTITLE">COPYRIGHT</a> -- copyright + <a href="docprocessing.html#COVERTITLE">MISC</a> -- miscellaneous cover information + <a href="docprocessing.html#DRAFT">DRAFT</a> -- document's draft number + <a href="docprocessing.html#DRAFT_STRING">DRAFT_STRING</a> -- what to use in place of "Draft" + <a href="docprocessing.html#REVISION">REVISION</a> -- document's revision number + <a href="docprocessing.html#REVISION_STRING">REVISION_STRING</a> -- what to use in place of "Revision" + +<a name="19">+++ General document formatting directives</a> + <a href="docprocessing.html#DOCTYPE">DOCTYPE</a> -- general document type + <a href="docprocessing.html#COPYSTYLE">COPYSTYLE</a> -- draft or final copy + <a href="docprocessing.html#PRINTSTYLE">PRINTSTYLE</a> -- typeset or "typewritten" + +<a name="20">+++ Line numbering</a> + <a href="docelement.html#NUMBER_LINES">NUMBER_LINES</a> -- turn automatic line numbering on or off + <a href="docelement.html#NUMBER_LINES_CONTROL">Control macros</a> + <a href="docelement.html#NUMBER_QUOTE_LINES">NUMBER_QUOTE_LINES</a> -- turn numbering of lines inside QUOTE on or off + <a href="docelement.html#NUMBER_BLOCKQUOTE_LINES">NUMBER_BLOCKQUOTE_LINES</a> -- turn numbering of lines inside BLOCKQUOTE on or off + +<a name="21">+++ Set documents in columns</a> + <a href="docprocessing.html#COLUMNS">COLUMNS</a> + <a href="docprocessing.html#COL_NEXT">COL_NEXT</a> + <a href="docprocessing.html#COL_BREAK">COL_BREAK</a> + +<a name="22">+++ TYPEWRITE control macros</a> + <a href="docprocessing.html#TYPEWRITE_CONTROL">UNDERLINE_ITALIC</a> -- turn underlining of italics on + <a href="docprocessing.html#UNDERLINE_QUOTES">UNDERLINE_QUOTES</a> -- turn underlining of line for line quotes on or off + <a href="docprocessing.html#TYPEWRITE_CONTROL">ITALIC_MEANS_ITALIC</a> -- turn underlining of italics off (use italics) + <a href="docprocessing.html#TYPEWRITE_CONTROL">UNDERLINE_SLANT</a> -- turn underlining of pseudo italics on + <a href="docprocessing.html#TYPEWRITE_CONTROL">SLANT_MEANS_SLANT</a> -- turn underlining of pseudo italics off (use pseudo italics) + +<a name="23">+++ Initiate document processing</a> + <a href="docprocessing.html#START">START</a> -- begin document processing + +<a name="24">+++ Epigraphs</a> + <a href="docelement.html#EPIGRAPH">EPIGRAPH</a> -- set an epigraph underneath the docheader + <a href="docelement.html#EPIGRAPH_CONTROL">Control macros</a> -- change default style of epigraphs + +<a name="25">+++ Main heads</a> + <a href="docelement.html#HEAD">HEAD</a> -- set a main head + <a href="docelement.html#HEAD_GENERAL">Control macros</a> -- change default style of heads + <a href="docelement.html#HEAD_SPACE">HEAD_SPACE</a> -- control spacing around heads + <a href="docelement.html#NUMBER_HEADS">NUMBER_HEADS</a> -- number heads + <a href="docelement.html#PREFIX_CHAPTER_NUMBER">PREFIX_CHAPTER_NUMBER</a> -- prefix chapter number to head numbering scheme + <a href="docelement.html#RESET_HEAD_NUMBER">RESET_HEAD_NUMBER</a> -- reset head number to "1" + +<a name="26">+++ Subheads</a> + <a href="docelement.html#SUBHEAD">SUBHEAD</a> -- set a subhead + <a href="docelement.html#SUBHEAD_GENERAL">Control macros</a> -- change default style of subheads + <a href="docelement.html#NUMBER_SUBHEADS">NUMBER_SUBHEADS</a> -- number subheads + <a href="docelement.html#PREFIX_CHAPTER_NUMBER">PREFIX_CHAPTER_NUMBER</a> -- prefix chapter number to subhead numbering scheme + <a href="docelement.html#RESET_SUBHEAD_NUMBER">RESET_SUBHEAD_NUMBER</a> -- reset subhead number to "1" + +<a name="27">+++ Paragraph heads</a> + <a href="docelement.html#PARAHEAD">PARAHEAD</a> -- set a paragraph head (joined to body of paragraph) + <a href="docelement.html#PARAHEAD_GENERAL">Control macros</a> -- change default style of paraheads + <a href="docelement.html#NUMBER_PARAHEADS">NUMBER_PARAHEADS</a> -- number paraheads + <a href="docelement.html#PREFIX_CHAPTER_NUMBER">PREFIX_CHAPTER_NUMBER</a> -- prefix chapter number to parahead numbering scheme + <a href="docelement.html#RESET_PARAHEAD_NUMBER">RESET_PARAHEAD_NUMBER</a> -- reset parahead number to "1" + +<a name="28">+++ Paragraphs</a> + <a href="docelement.html#PP">PP</a> -- set a paragraph + <a href="docelement.html#PP_CONTROL">Paragraph style</a> -- managing paragraph style concerns + <a href="docelement.html#PP_FONT">PP_FONT</a> -- globally change the font used in regular paragraphs + <a href="docelement.html#PARA_INDENT">PARA_INDENT</a> -- set the paragraph first-line indent + <a href="docelement.html#INDENT_FIRST_PARAS">INDENT_FIRST_PARAS</a> -- indenting of paragraph first-lines on or off + <a href="docelement.html#PP_SPACE">PARA_SPACE</a> -- spacing of paragraphs (single blank line) on or off + +<a name="29">+++ Quotes (line by line verbatim quotes)</a> + <a href="docelement.html#QUOTE">QUOTE</a> -- set cited text line by line + <a href="docelement.html#QUOTE_GENERAL">Control macros</a> -- change default style of quotes + <a href="docelement.html#ALWAYS_FULLSPACE_QUOTES">ALWAYS_FULLSPACE_QUOTES</a> -- control spacing around quotes + <a href="docelement.html#BREAK_QUOTE">BREAK_QUOTE</a> -- deprecated + +<a name="30">+++ Blockquotes (cited passages of text)</a> + <a href="docelement.html#BLOCKQUOTE">BLOCKQUOTE</a> -- set longer passages of cited text + <a href="docelement.html#BLOCKQUOTE_GENERAL">Control macros</a> -- change default style of blockquotes + <a href="docelement.html#ALWAYS_FULLSPACE_QUOTES">ALWAYS_FULLSPACE_QUOTES</a> -- control spacing around quotes + <a href="docelement.html#BREAK_QUOTE">BREAK_BLOCKQUOTE</a> -- deprecated + +<a name="31">+++ Code snippets</a> + <a href="docelement.html#CODE">CODE</a> -- set a code snippet + +<a name="32">+++ Author linebreaks (section breaks)</a> + <a href="docelement.html#LINEBREAK">LINEBREAK</a> -- insert an author linebreak (section break) + <a href="docelement.html#LINEBREAK_CHAR">LINEBREAK_CHAR</a> -- character to use for author linebreaks + <a href="docelement.html#LINEBREAK_COLOR">LINEBREAK_COLOR</a> -- colour of author linebreak character + +<a name="33">+++ Document termination string</a> + <a href="docelement.html#FINIS">FINIS</a> -- insert a document termination string (e.g. --END--) + <a href="docelement.html#FINIS_STRING">FINIS_STRING</a> -- set the document termination string + <a href="docelement.html#FINIS_COLOR">FINIS_COLOR</a> -- set the document termination string colour + +<a name="34">+++ Footnotes</a> + <a href="docelement.html#FOOTNOTE">FOOTNOTE</a> -- set a footnote + <a href="docelement.html#FOOTNOTE_GENERAL">Control macros</a> -- change default style of footnotes + <a href="docelement.html#FOOTNOTE_MARKERS">FOOTNOTE_MARKERS</a> -- turn footnote markers on or off + <a href="docelement.html#FOOTNOTE_MARKER_STYLE">FOOTNOTE_MARKER_STYLE</a> -- type of footnote marker to use + <a href="docelement.html#RESET_FOOTNOTE_NUMBER">RESET_FOOTNOTE_NUMBER</a> -- reset footnote numbering + <a href="docelement.html#FOOTNOTE_RULE">FOOTNOTE_RULE</a> -- turn footnote separator rule on or off + <a href="docelement.html#FOOTNOTE_RULE_ADJ">FOOTNOTE_RULE_ADJ</a> -- adjust vertical position of footnote rule + <a href="docelement.html#FOOTNOTE_RULE_LENGTH">FOOTNOTE_RULE_LENGTH</a> -- adjust length of footnote rule + <a href="docelement.html#FOOTNOTES_RUN_ON">FOOTNOTES_RUN_ON</a> -- instruct footnotes to be continuous (i.e. not to + begin on a new line; only for use with footnotes + identified by document line number) + +<a name="35">+++ Endnotes</a> + <a href="docelement.html#ENDNOTE">ENDNOTE</a> -- set an endnote + <a href="docelement.html#EN-MARK">\*[EN-MARK]</a> -- mark initial line of a range of line numbers + (for use with line numbered endnotes) + <a href="docelement.html#ENDNOTES">ENDNOTES</a> -- output endnotes pages + <a href="docelement.html#ENDNOTE_CONTROL">Control macros</a> -- change just about anything to do with endnotes + <a href="docelement.html#ENDNOTES_GENERAL">Endnotes pages general style control</a> + <a href="docelement.html#ENDNOTES_HEADER_CONTROL">Endotes pages header/footer control</a> + <a href="docelement.html#ENDNOTES_MAIN_TITLE">Endnotes pages main title control</a> + <a href="docelement.html#ENDNOTES_MAIN_TITLE">Endnotes pages document/section identification control</a> + <a href="docelement.html#ENDNOTES_NUMBERING">Endnote identification style</a> + +<a name="36">+++ Margin notes</a> + <a href="docelement.html#MN_INIT">MN_INIT</a> -- initialize margin notes + <a href="docelement.html#MN">MN</a> -- set a margin note + +<a name="37">+++ Bibliographic references</a> + <a href="refer.html#REF">REF</a> -- begin a bibliographic reference + <a href="refer.html#FOOTNOTE_REFS">FOOTNOTE_REFS</a> -- place bibliographic references in footnotes + <a href="refer.html#ENDNOTE_REFS">ENDNOTE_REFS</a> -- place bibliographic references in endnotes + <a href="refer.html#BRACKET_REFS">REF( / REF)</a> -- put parentheses around embedded bibliographic references + <a href="refer.html#BRACKET_REFS">REF[ / REF]</a> -- put square brackets around embedded bibliographic references + <a href="refer.html#BRACKET_REFS">REF{ / REF}</a> -- put curly braces around mbedded bibliographic references + <a href="refer.html#BIBLIOGRAPHY">BIBLIOGRAPHY</a> -- output a bibliography + <a href="refer.html#BIBLIO_CONTROL">Control macros</a> -- change just about anything to do with bibliography pages + <a href="refer.html#BIBLIOGRAPHY_TYPE">BIBLIOGRAPHY_TYPE</a> -- "plain" or enumerated list bibliography + <a href="refer.html#BIBLIO_GENERAL">Bibliography pages general style control</a> + <a href="refer.html#BIBLIO_HEADER_CONTROL">Bibliography pages header/footer control</a> + <a href="refer.html#BIBLIO_MAIN_TITLE">Bibliography pages main head control</a> + +<a name="38">+++ Tables of contents</a> + <a href="docelement.html#TOC">TOC</a> + <a href="docelement.html#TOC_CONTROL">Control macros</a> -- change just about anything to do with table of contents pages + <a href="docelement.html#TOC_GENERAL">Table of contents general style control</a> + <a href="docelement.html#TOC_PAGENUMBERING">Table of contents page numbering</a> + <a href="docelement.html#TOC_HEADER">Table of contents main title control</a> + <a href="docelement.html#TOC_STYLE">Changing the style of the different table of contents entry types</a> + <a href="docelement.html#TOC_ADDITIONAL">Additional table of contents control macros</a> + +<a name="39">+++ Letter (correspondence) macros</a> + <a href="letters.html#DATE">DATE</a> -- letter's date + <a href="letters.html#FROM">FROM</a> -- letter's addresser + <a href="letters.html#TO">TO</a> -- letter's addressee + <a href="letters.html#GREETING">GREETING</a> -- letter's salutation + <a href="letters.html#CLOSING">CLOSING</a> -- letter's closing salutation + <a href="letters.html#NO_SUITE">NO_SUITE</a> -- turn printing of "next page number" off or on + +<a name="40">+++ Changing global print style parameters after START</a> + <a href="docprocessing.html#DOC_LEFT_MARGIN">DOC_LEFT_MARGIN</a> -- left margin of everything on the page + <a href="docprocessing.html#DOC_RIGHT_MARGIN">DOC_RIGHT_MARGIN</a> -- right margin of everything on the page + <a href="docprocessing.html#DOC_LINE_LENGTH">DOC_LINE_LENGTH</a> -- document's base line length + <a href="docprocessing.html#DOC_FAMILY">DOC_FAMILY</a> -- document's base family + <a href="docprocessing.html#DOC_PT_SIZE">DOC_PT_SIZE</a> -- document's base point size + <a href="docprocessing.html#DOC_LEAD">DOC_LEAD</a> -- document's base lead + <a href="docprocessing.html#DOC_QUAD">DOC_QUAD</a> -- document's base quad directions + +<a name="41">+++ Managing a document's first-page header</a> + <a href="docprocessing.html#DOCHEADER">DOCHEADER</a> -- document first-page header on or off + <a href="docprocessing.html#DOCHEADER_CONTROL_INDEX">Control macros</a> -- change default style of docheader elements + +<a name="42">+++ Managing page headers and footers</a> + <a href="headfootpage.html#HEADERS">HEADERS</a> -- turn page headers on or off + <a href="headfootpage.html#FOOTERS">FOOTERS</a> -- turn page footers on or off + <a href="headfootpage.html#HEADERS_AND_FOOTERS">HEADERS_AND_FOOTERS</a> -- enable or disable generation of both headers and footers + <a href="headfootpage.html#INDEX_REFERENCE">Header/footer control macros</a> + <a href="STRINGS">Strings</a> -- left-right-center strings + <a href="STYLE">Style</a> -- change style defaults for headers and/or footers + <a href="GLOBAL">Global</a> -- global style changes + <a href="PART_BY_PART">Part-by-part</a> -- part-by-part style changes + <a href="VERTICAL">Vertical placement</a> -- vertical location of headers and/or footers + <a href="SEPARATOR_RULE">Separator rule</a> -- manage the header/footer separator rule + +<a name="43">+++ Recto/verso page headers and footers</a> + <a href="rectoverso.html#RECTO_VERSO">RECTO_VERSO</a> -- turn recto/verso headers and/or footers on or off + <a href="rectoverso.html#SWITCH_HDRFTR">SWITCH_HEADERS</a> -- switch recto or verso header + <a href="rectoverso.html#SWITCH_HDRFTR">SWITCH_FOOTERS</a> -- switch recto or verso footer + <a href="headfootpage.html#HDRFTR_RECTOVERSO">HEADER_RECTO</a> -- string that constitutes a recto header + <a href="headfootpage.html#HDRFTR_RECTOVERSO">HEADER_VERSO</a> -- string that constitutes a verso header + <a href="headfootpage.html#HDRFTR_RECTOVERSO">FOOTER_RECTO</a> -- string that constitutes a recto footer + <a href="headfootpage.html#HDRFTR_RECTOVERSO">FOOTER_VERSO</a> -- string that constitutes a recto footer + +<a name="44">+++ Pagination</a> + <a href="headfootpage.html#PAGINATE">PAGINATE</a> -- pagination on or off + <a href="headfootpage.html#PAGINATE_CONTROL">Control macros</a> -- change default style for pagination + <a href="headfootpage.html#PAGENUMBER">PAGENUMBER</a> -- user-defined (starting) page number + <a href="headfootpage.html#PAGENUM_STYLE">PAGENUM_STYLE</a> -- digits, roman numerals, etc + <a href="headfootpage.html#PAGENUM_ON_FIRST_PAGE">PAGENUM_ON_FIRST_PAGE</a> -- when footers are enabled + <a href="headfootpage.html#DRAFT_WITH_PAGENUMBER">DRAFT_WITH_PAGENUMBER</a> -- attach draft/revision information to page numbers + +<a name="45">+++ Document and section cover (title) pages</a> + <a href="cover.html#COVER">COVER</a> -- information to include in a section cover + <a href="cover.html#COVER">DOC_COVER</a> -- information to include in a document cover + <a href="cover.html#ON_OFF">COVERS</a> -- turn printing of section covers on or off + <a href="cover.html#ON_OFF">DOC_COVERS</a> -- turn printing of document covers on or off + <a href="cover.html#COVER_CONTROL_INDEX">Control macros</a> -- change style defaults for covers + +<a name="46">+++ Utilities</a> + <a href="docelement.html#BLANK_PAGE">BLANKPAGE</a> -- output one or more blank pages + <a href="docprocessing.html#DOC_LEAD_ADJUST">DOC_LEAD_ADJUST</a> -- adjust document linespacing (lead) to fill pages + <a href="rectoverso.html#COLLATE">COLLATE</a> -- join documents or chapters of a document together + <a href="docprocessing.html#SHIM">SHIM</a> -- move vertical position to nearest next valid baseline +</pre> + +<hr/> + +<p> +<a href="appendices.html#TOP">Next</a> +<a href="typemacdoc.html#TOP">Prev</a> +<a href="#TOP">Top</a> +<a href="toc.html">Back to Table of Contents</a> +</p> + +</body> +</html> + +<!-- vim: fileencoding=latin1: nomodified: +--> diff --git a/contrib/mom/momdoc/rectoverso.html b/contrib/mom/momdoc/rectoverso.html new file mode 100644 index 00000000..028804f9 --- /dev/null +++ b/contrib/mom/momdoc/rectoverso.html @@ -0,0 +1,289 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!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=iso-8859-1"/> +<title>Mom -- Document Processing, Recto/verso printing</title> +</head> +<body bgcolor="#dfdfdf"> + +<!-- ==================================================================== --> + +<a name="TOP"></a> + +<p> +<a href="cover.html#TOP">Next</a> +<a href="headfootpage.html#TOP">Prev</a> +<a href="toc.html">Back to Table of Contents</a> +</p> + +<a name="RECTOVERSO"><h1 align="center"><u>Recto/verso printing, collating</u></h1></a> + +<a name="INDEX_RECTOVERSO"></a> + +<ul> + <li><a href="#RECTOVERSO_INTRO">Introduction to recto/verso</a></li> + <ul> + <li><a href="#RECTOVERSO_LIST">Macro list</a></li> + </ul> + <li><a href="#COLLATE_INTRO">Introduction to collating</a></li> + <ul> + <li><a href="#COLLATE">The COLLATE macro</a></li> + </ul> +</ul> + +<a name="RECTOVERSO_INTRO"><h2><u>Introduction to recto/verso</u></h2></a> + +<p> +Recto/verso printing allows you to set up a <strong>mom</strong> +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, <strong>mom</strong> automatically takes control +of the following aspects of alternating page layout: +</p> + +<ul> + <li>switching left and right margins (if they're not equal)</li> + <li>switching the left and right parts of the default 3-part + <a href="definitions.html#TERMS_HEADER">headers</a> + or + <a href="definitions.html#TERMS_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 "dumb" +printers is to open the document (after it's been processed into +PostScript by groff — see +<a href="using.html#USING_INVOKING">How to invoke groff with mom</a>) +in <strong>gv</strong> (ghostview), click the "odd pages" +icon, then click "Print Marked". After printing +is complete, rearrange the sheets appropriately, put them +back in your printer, and have <strong>gv</strong> print the +"even pages". If you prefer to work from the command +line, check out the man pages for <strong>pstops</strong> and +<strong>psbook</strong>. There are other programs out there as well +to help with two-sided printing. +</p> + +<a name="RECTOVERSO_LIST"><h3><u>Recto/verso macros list</u></h3></a> + +<ul> + <li><a href="#RECTO_VERSO">RECTO_VERSO</a></li> + <li><a href="#SWITCH_HDRFTR">SWITCH_HEADERS (also FOOTERS)</a> + — switch position of the header parts (left and right) + </li> +</ul> + +<!-- -RECTO_VERSO- --> + +<hr align="left" width="66%"/> + +<a name="RECTO_VERSO"></a> + +<p> +Macro: <strong>RECTO_VERSO</strong> +</p> + +<p> +If you want <strong>mom</strong> to set up alternating pages for +recto/verso printing, simply invoke <strong>RECTO_VERSO</strong> +with no argument. +</p> + +<p> +<strong>NOTE:</strong> Recto/verso always switches the left and +right parts of +<a href="definitions.html#TERMS_HEADER">headers</a> +or +<a href="definitions.html#TERMS_FOOTER">footers</a> +on odd/even pages. However, it only switches the left and right +margins if the margins aren'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 <strong>START</strong>). +</p> + +<p> +Equally, recto/verso only switches the page number position if page +numbers aren'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 <strong>START</strong>). +</p> + +<!-- -SWITCH_HDRFTR- --> + +<hr width="33%" align="left"/> + +<a name="SWITCH_HDRFTR"></a> + +<p> +Macro: <strong>SWITCH_HEADERS</strong> +</p> + +<p> +<strong>SWITCH_HEADERS</strong> 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't like +<strong>mom</strong>'s default placement of author and title, use +<strong>SWITCH_HEADERS</strong> to reverse it. +</p> + +<p> +<strong>SWITCH_HEADERS</strong> can also be useful in conjunction +with +<a href="#RECTO_VERSO">RECTO_VERSO</a>. +The assumption of <strong>RECTO_VERSO</strong> is that the first +page of a document (recto/odd) represents the norm for header-left +and header-right, meaning that the second (and all subsequent even) +page(s) of the document exchange header-left and header-right. +</p> + +<p> +If <strong>mom</strong>'s behaviour in this matter is not what you +want, simply invoke <strong>SWITCH_HEADERS</strong> 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> + +<hr/> + +<!-- ===================================================================== --> + +<a name="COLLATE_INTRO"><h2><u>Introduction to collating</u></h2></a> + +<p> +The macro <strong>COLLATE</strong> lets you join documents together. +Primarily, it's a convenience for printing long documents that +comprise several chapters, although it could be used for any +document type (except <strong>LETTER</strong>). +</p> + +<p> +Personally, I prefer to keep chapters in separate files and print +them out as needed. However, that means keeping track of the correct +starting page number for each chapter, a problem circumvented by the +use of <strong>COLLATE</strong>. +</p> + +<p> +When collating chapters, you need only put <kbd>.COLLATE</kbd> at +the end of a chapter, follow it with any +<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 document (unlikely, but +possible), and re-invoke the +<a href="docprocessing.html#START">START</a> +macro. Your new chapter will begin on a fresh page and behave +as expected. +</p> + +<p> +<strong>COLLATE</strong> assumes you are collating documents/files +with similar type-style parameters hence there's no need for +<strong>PRINTSTYLE</strong> to appear after <strong>COLLATE</strong>, +although if you're collating documents that were created as separate +files, chances are the <strong>PRINTSTYLE</strong>'s already there. +</p> + +<a name="CAUTION"></a> + +<p> +<strong><u>Two words of caution:</u></strong> + +<ol> + <li>Do not collate documents of differing + <strong>PRINTSTYLES</strong> (i.e. don't try to + collate a TYPESET document and TYPEWRITE 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> +</p> + +<!-- -COLLATE- --> + +<hr width="66%" align="left"/> + +<a name="COLLATE"></a> + +<p> +Macro: <strong>COLLATE</strong> +</p> + +<p> +The most basic (and most likely) collating situation looks like +this: + +<pre> + .COLLATE + .CHAPTER 17 + .START +</pre> +</p> + +<p> +A slightly more complex version of the same thing, for chapters +that require their own titles, looks like this: + +<pre> + .COLLATE + .CHAPTER_TITLE "Geek Fatigue: Symptoms and Causes" + .START +</pre> +</p> + +<p> +<strong>NOTE:</strong> See the +<a href="#CAUTION">two words of caution</a>, +above. +</p> + +<hr/> + +<p> +<a href="cover.html#TOP">Next</a> +<a href="headfootpage.html#TOP">Prev</a> +<a href="#TOP">Top</a> +<a href="toc.html">Back to Table of Contents</a> +</p> + +</body> +</html> + +<!-- vim: fileencoding=latin1: nomodified: +--> diff --git a/contrib/mom/momdoc/refer.html b/contrib/mom/momdoc/refer.html new file mode 100644 index 00000000..c7718a83 --- /dev/null +++ b/contrib/mom/momdoc/refer.html @@ -0,0 +1,1801 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!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=iso-8859-1"/> +<title>Mom -- Bibliographies and References</title> +</head> +<body bgcolor="#dfdfdf"> + +<!-- ==================================================================== --> + +<a name="TOP"></a> + +<a href="letters.html#TOP">Next</a> +<a href="cover.html#TOP">Prev</a> +<a href="toc.html">Back to Table of Contents</a> + +<h1 align="center"><a name="REF_INTRO"><u>Bibliographies and references</u></a></h1> + +<a href="#INTRO_REF">Introduction to bibliographies and references</a> +<br/> + +<a href="#TUTORIAL_REF">Tutorial</a> + +<ul> + <li><a href="#DB_REF">Creating a <strong>refer</strong> database</a></li> + <li><a href="#RCOMMANDS_REF">Required <strong>refer</strong> commands</a></li> + <li><a href="#ACCESSING_REF">Accessing references</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 <strong>groff</strong> with <strong>mom</strong> and <strong>refer</strong></a></li> +</ul> + +<a href="#MACROS_REF">Index of bibliography and reference macros</a> +<ul> + <li><a href="#BIBLIO_CONTROL">Bibliography page style control macros</a></li> +</ul> + +<a name="INTRO_REF"><h2><u>Introduction to bibliographies and references</u></h2></a> + +<p> +<strong>Mom</strong> provides the ability to automatically format +and generate bibliography pages, as well as footnote or endnote +bibliographic references, or references embedded in text. She +accomplishes this by working in conjunction with a special +<strong>groff</strong> program called "refer". +</p> + +<p> +<strong>refer</strong> is a <strong>groff</strong> +"pre-processor", which is to say that it scans your files +looking for very specific commands (i.e. lines that begin with a +period [dot], just like macros and document element tags). If +the commands aren't there, <strong>refer</strong> can't do it's +job, and neither can <strong>mom</strong>. The scanning is done +<strong>before</strong> any actual <strong>mom</strong> processing +occurs. +</p> + +<p> +<strong>refer</strong> is a program that's been around for +a long time. It's powerful and has many, many features. +Unfortunately, the manpage <nobr>(<kbd>man refer</kbd>),</nobr> +while complete and accurate, is dense and not a good introduction +to <strong>refer</strong>. (It's a classic manpage Catch-22: the +documentation is useful only after you already understand it.) +</p> + +<p> +In order to get <strong>mom</strong> users up and running with +<strong>refer</strong>, this section of <strong>mom</strong>'s +documentation focuses exclusively, in a recipe-like manner, on +what you need to know to use <strong>refer</strong> satisfactorily +in conjunction with <strong>mom</strong>. The information and +instructions are <strong><em><u>not</u></em></strong> to be taken as +a manual or tutorial on full <strong>refer</strong> usage. Much has +been left out, on purpose. +</p> + +<p> +It is tempting to provide two levels of documentation, one for +users familiar with <strong>refer</strong> and one for newcomers +to <strong>groff</strong> and <strong>mom</strong>, but such an +approach may muddy the waters for newcomers. <strong>Mom</strong>'s +allegiance, first and foremost, is to newcomers. If you're already +a <strong>refer</strong> user, the information herein will be useful +for adapting your current <strong>refer</strong> usage to +<strong>mom</strong>'s way of doing things. If you've never used +<strong>refer</strong>, the information is essential, and, in many +cases, may be all you need. +</p> + +<p> +(For the benefit of old groff-hands: <strong>refer</strong> +support in <strong>mom</strong> is heavily based on the +<strong>refer</strong> module of the "ms" macros. The +choice was deliberate so that those wishing to play around with +<strong>mom</strong>'s bibliography formatting style would be +tinkering with the familiar.) +</p> + +<p> +<strong>refer</strong> requires first that you create a +bibliographic database. From the information contained in the +database, <strong>mom</strong> 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 +<strong>refer</strong> (and <strong>mom</strong>) to access entries +in it by supplying keywords from the entries. Depending on what +you've instructed <strong>mom</strong> to do, she will put the +entries — fully and properly formatted with respect to order, +punctuation and italicization — in footnotes, endnotes, or a +full bibliography. +</p> + +<p> +I encourage anyone interested in what MLA style looks like — +and, by extension, how your bibliographies and references will look +after <strong>mom</strong> formats them — to check out + +<pre> + http://www.aresearchguide.com/12biblio.html +</pre> + +or any other website or reference book on MLA style. +</p> + +<p> +<strong>NOTE:</strong> MLA style requires that second and subsequent +lines of individual references be indented. <strong>Mom</strong> +takes care of this for you with a default indent, which can be +changed with the macro +<a href="#INDENT_REFS">INDENT_REFS</a>. +</p> + +<hr align="left" width="66%"/> + +<a name="TUTORIAL_REF"><h2><u>Tutorial</u></h2></a> + +<ol> + <li><a href="#DB_REF">Creating a refer database</a></li> + <li><a href="#RCOMMANDS_REF">Required "refer" commands</a></li> + <li><a href="#ACCESSING_REF">Accessing references</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 refer</a></li> +</ol> + +<a name="DB_REF"><h3><u>1. Creating a refer database</u></h3></a> + +<p> +The first step in using <strong>refer</strong> with +<strong>mom</strong> is setting up your bibliographic database. The +database is a file containing separate entries for each reference +you want to access from your <strong>mom</strong> files. The file +is <em>not</em> a " file"; it is a separate database. You +may set up individual databases for individual documents, or create +a large database that contains all the references you'll ever need. +</p> + +<p> +Entries ("records") in the database file are separated +from each other by a single, blank line. The records themselves +are composed of single lines ("fields") with no blank +lines between them. Each field begins with a percent sign +and a single letter (the "field identifier") 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; <strong>mom</strong> +adds what's correct automatically. Do note, however, that author(s) +<nobr>(<kbd>%A</kbd>)</nobr> 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's last name. +</p> + +<p> +Here's a sample database containing two records so you can +visualize what the above paragraph says: + +<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 +</pre> +</p> + +<p> +The order in which you enter fields doesn't matter. +<strong>mom</strong> and <strong>refer</strong> will re-arrange them +in the correct order for you. +</p> + +<p> +The meaning of the letters follows. There are, with +<strong>refer</strong>, quite a few — all uppercase +— which have, over time, come to be "standard". +<strong>Mom</strong> respects these. However, she adds to the list +(mostly the lowercase letters). +</p> + +<pre> + %A Author — additional authors may be entered on separate %A + lines as in first entry of the sample, above; mom + and refer will figure out what to do with multiple + authors according to MLA rules + %T Title — 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 — the title of a book when %T contains the title + of an article; otherwise, use %T for book + titles + %R Report number — for technical reports + %J Journal name — the name of a journal or magazine when %T + contains the title of an article + %E Editor — 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 — the number of name of a specific edition + (e.g. Second, 2nd, Collector's, etc.) + %V Volume — volume number of a journal or series of books + %N Journal number — journal or magazine number + %S Series — series name for books or journals that are part of + a series + %C City — the city of publication + %I Publisher — the publisher; %I stands for "Issuer" + %D Publication date + %P Page number(s) — enter page ranges as, e.g., 22-25 + %G Gov't. + ordering number — for government publications + %O Other — additional information or comments you want + to appear at the end of the reference + %K Keywords — 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 — if different from the date + of publication + %a additions — for books, any additions to the original work, + such as the preface to a new edition or a new + introduction + %t reprint title — if different from a work's original title + %l translator — 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 — if tr. and ed. are one in the same; + %s site name — for web sites, the site name + %c content + of site — for web sites, the content, if unclear + (i.e. advertisement, cartoon, blog) + %o organization — for web sites, the organization, group or + sponsor of the site + %a access date — for a website, the date you accessed it + %u URL — for websites, the full URL of the site +</pre> + +<a name="REF_DISC_HY"></a> + +<p> +<strong>Tip:</strong> If you have hyphenation turned on in your +document (you probably do), <strong>mom</strong> will hyphenate +your references. This can be a problem because references +typically contain several proper names. Proper names shouldn't be +hyphenated. The solution is to prepend to any proper name in the +database the <strong>groff</strong> +<a href="definitions.html#TERMS_DISCRETIONARYHYPHEN">discretionary hyphen</a> +character, <kbd>\%</kbd>, like this: + +<pre> + %A Hill, \%Reginald +</pre> +</p> + +<p> +Alternatively, you can turn hyphenation off entirely in +references with the macro, +<a href="#HYPHENATE_REFS">HYPHENATE_REFS</a> <kbd>OFF</kbd>. +</p> + +<a name="RCOMMANDS_REF"><h3><u>2. Required "refer" commands</u></h3></a> + +<p> +Having set up your database, you now need to put some +<strong>refer</strong>-specific commands at the top of your +<strong>mom</strong> file. You cannot skip this step, nor can you +"source" these commands with the <strong>groff</strong> +<a href="definitions.html#TERMS_PRIMITIVES">primitive</a>, +<kbd>.so</kbd> or the <strong>mom</strong> macro, +<a href="docprocessing.html#INCLUDE">INCLUDE</a>. +They <strong><em>must</em></strong> appear, exactly as shown, in +every file requiring bibliographic references. +</p> + +<p> +<strong>refer</strong> commands are introduced with 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, <em><u>with +no initial period (dot)</u></em>. +</p> + +<p> +Here's an example: + +<pre> + .R1 + no-label-in-text + no-label-in-reference + .R2 +</pre> +</p> + +<p> +There are an awful lot of <strong>refer</strong> commands. We will +focus only on those required to get <strong>mom</strong> cooperating +with <strong>refer</strong>. If you're interested, study the +<strong>refer</strong> manpage to discover what other commands are +available and how to manipulate them. +</p> + +<p> +At a minimum, all <strong>mom</strong> files accessing +a bibliographic database must contain the following +<strong>refer</strong> commands, exactly as shown: + +<a name="REFER_BLOCK1"></a> + +<pre> +.R1 +no-label-in-text +no-label-in-reference +join-authors ", and " ", " ", and " +database <full path to the database> +.R2 +</pre> +</p> + +<p> +The first two commands tell <strong>refer</strong> to let +<strong>mom</strong> 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 <strong>mom</strong> 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. "...full path to the +database" means the full path <em>including</em> the database +filename, e.g. <nobr><kbd>/home/user/refer/my_database.</kbd></nobr> +</p> + +<p> If you're already a <strong>refer</strong> user, feel free to +enter whatever <strong>refer</strong> commands are necessary to +access the database(s) you want. +</p> + +<p> +With the above <strong>refer</strong> block, you can embed +references directly into the text of your document, or have them +output as footnotes or endnotes. If you want to "collect" +references for later output on a bibliography page, the block must +read: + +<pre> +.R1 +no-label-in-text +no-label-in-reference +join-authors ", and " ", " ", and " +database <full path to the database> +sort +accumulate +.R2 +</pre> +</p> + +<a name="ACCESSING_REF"><h3><u>3. Accessing references</u></h3></a> + +<p> +References are accessed by putting keywords, all on one line, +between the <strong>refer</strong> commands <kbd>.[</kbd> and +<kbd>.]</kbd>. Both of these commands must appear on separate +</p> + +<pre> + .[ + keyword(s) + .] +</pre> +lines, by themselves, like this: + +<p> +Keywords are any word, or set of words, that identify a database +record (i.e. a reference) unambiguously. (<strong>refer</strong> +doesn'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 "Bradbury". If your database contains several +books by Bradbury, say, <em>Fahrenheit 451</em> and <em>The Martian +Chronicles</em>, you could reference them with the keywords, "451" +and "Martian". If, in addition to the two books by Bradbury, you +also had one whose title was <em>The Martian Mission</em>, suitable +keywords to reference <em>The Martian Chronicles</em> might be: + +<pre> + .[ or .[ or .[ + Bradbury Martian Bradbury Chronicles Martian Chronicles + .] .] .] +</pre> +</p> + +<p> +The database field identifier, <kbd>%K</kbd>, lets you create +special keywords for references. This can be very handy if you need +both a "short" and a "long" reference to the +same work. The short reference might be used in footnotes; the long +one in a bibliography. Consider the following: + +<pre> + %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 +</pre> +</p> + +<p> +To access the shorter reference, you'd do + +<pre> + .[ + Nor short + .] +</pre> +</p> + +<p> +To access the longer one, you'd do + +<pre> + .[ + Norris + .] +</pre> +</p> + +<a name="WHERE_REF"><h3><u>4. Telling mom where to put references</u></h3></a> + +<p> +<strong>Mom</strong> provides several mechanisms for outputting +references where you want. +</p> + +<h4><u>Embedding references in the document body</u></h4> + +<p> +References may be embedded in the document body, surrounded by +parentheses, square brackets, or braces. Use whichever you prefer, +following the recipes below. + +<pre> + Parentheses Square brackets Braces + ----------- --------------- ------ + + .REF( .REF[ .REF{ + .[ .[ .[ + keyword(s) keyword(s) keyword(s) + .] .] .] + .REF) .REF] .REF} +</pre> +</p> + +<h4><u>Footnote or endnote references</u></h4> + +<p> +Most times, you'll probably want references in either footnotes or +endnotes. <strong>Mom</strong> provides a simple mechanism whereby +you can choose which, or even switch back and forth. The primary +tag is +<a href="#REF">REF</a>, which is used like this: + +<pre> + .REF + .[ + keyword(s) + .] + .REF +</pre> +</p> + +<p> +<strong>REF</strong> collects references and outputs them +where you say with the macros, +<a href="#FOOTNOTE_REFS">FOOTNOTE_REFS</a> +or +<a href="#ENDNOTE_REFS">ENDNOTE_REFS</a>. +Neither <strong>FOOTNOTE_REFS</strong> nor +<strong>ENDNOTE_REFS</strong> requires an argument. All they do is +tell <strong>REF</strong>, whenever it's invoked, where to put the +references. +</p> + +<p> +A recipe for footnote references looks like this: +<pre> + .FOOTNOTE_REFS + .REF + .[ + keyword(s) + .] + .REF +</pre> +</p> + +<p> +When <strong>FOOTNOTE_REFS</strong> are enabled, +<strong>REF</strong> behaves identically to +<a href="docelement.html#FOOTNOTE">FOOTNOTE</a>, +so please read the +<a href="docelement.html#FOOTNOTE_NOTE">HYPER IMPORTANT NOTE</a> +found in the document entry for <strong>FOOTNOTE</strong>. +</p> + +<p> +The reference between the first and second <strong>REF</strong> +will be treated as a footnote, as will all subsequent +<strong>REF</strong> pairs unless you invoke the macro, +<kbd>.ENDNOTE_REFS</kbd>. +</p> + +<p> +A recipe for endnote references looks like this: + +<pre> + .ENDNOTE_REFS + .REF + .[ + keyword(s) + .] + .REF +</pre> +</p> + +<p> +The reference between the first and second <strong>REF</strong> +will be treated as an endnote, as will all subsequent +<strong>REF</strong> pairs unless you invoke the macro, +<kbd>.FOOTNOTE_REFS</kbd>. +</p> + +<p> +When <strong>ENDNOTE_REFS</strong> are enabled, <strong>REF</strong> +behaves identically to +<a href="docelement.html#FOOTNOTE">ENDNOTE</a>, +so please read the +<a href="docelement.html#ENDNOTE_NOTE">HYPER IMPORTANT NOTE</a> +found in the document entry for <strong>ENDNOTE</strong>. +</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 "short" +references in footnotes, and complete references in endnotes. +</p> + +<a name="COLLECTED_REF"><h4><u>Collected references</u></h4></a> + +<p> +Sometimes, you may want to put references in input text near +sections of text to which they pertain, but not actually want +them output until later (typically, on a bibliography page). +<strong>REF</strong> is used for this, too, but you have to make +sure your <strong>refer</strong> commands block is set up properly. +The recipe for this is: + +<a name="REFER_BLOCK2"></a> + +<pre> +.R1 +no-label-in-text +no-label-in-reference +join-authors ", and " ", " ", and " +database <full path to the database> +sort +accumulate +.R2 +</pre> +</p> + +<p> +After this set up, and provided you don't issue a +<kbd>.FOOTNOTE_REFS</kbd> or <kbd>.ENDNOTE_REFS</kbd> command, all +reference between <strong>REF</strong> pairs will be collected for +later output. +</p> + +<p> +As a precaution, <strong>mom</strong> will issue a message +the first time you call <kbd>.REF</kbd> if neither +<strong>FOOTNOTE_REFS</strong> nor <strong>ENDNOTE_REFS</strong> +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> + +<p> +<strong>LIMITATION:</strong> You cannot combine +"collected" references (plain <strong>REF</strong>) +with <strong>REF</strong>s that are instructed to go into +footnotes (with <strong>FOOTNOTE_REFS</strong>) or endnotes (with +<strong>ENDNOTE_REFS</strong>). This is a limitation imposed by +<strong>refer</strong>, not <strong>mom</strong>. +</p> + +<a name="BIBLIO_REF"><h3><u>5. Creating bibliography pages</u></h3></a> + +<p> +Bibliography pages are separate pages, like endnotes, on which +complete bibliographies are output. And, like endnotes pages, just +about every element on them can be designed to your specifications +with control macros. (See +<a href="#BIBLIO_CONTROL_MACROS">Control macros for bibliographies</a>.) +A bibliography page that uses <strong>mom</strong>'s defaults +begins with the macro, +<a href="#BIBLIOGRAPHY">BIBLIOGRAPHY</a>, +like this: + +<pre> + .BIBLIOGRAPHY +</pre> +</p> + +<p> +Following <strong>BIBLIOGRAPHY</strong>, you have three choices of +how to proceed. +</p> + +<p> +If you have elected to have references collected from within the +body of a document (see above, +<a href="#COLLECTED_REF">Collected references</a>, +for instructions), which assumes you have a <strong>refer</strong> +command block like the one +<a href="#REFER_BLOCK2">here</a> +at the top of your document, you need only do + +<pre> + .BIBLIOGRAPHY + .[ + $LIST$ + .] +</pre> +</p> + +<p> +If you want to create the bibliography by hand (which may be the +case if you've used footnote and/or endnote references throughout +your document), follow this recipe, which assumes you already have a +<strong>refer</strong> block like the one +<a href="#REFER_BLOCK1">here</a> +at the top of your document: + +<pre> + .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$ + .] +</pre> +</p> + +<p> +Your final choice is to output your whole database. Again, +assuming you have a <strong>refer</strong> block like the one +<a href="#REFER_BLOCK1">here</a> +at the top of your file, you need only do: + +<pre> + .BIBLIOGRAPHY + .R1 + bibliography <full path to database> + .R2 +</pre> +</p> + +<p> +If you haven't put a <strong>refer</strong> block in +your file already, you can put the whole thing after +<strong>BIBLIOGRAPHY</strong>, like this: + +<pre> + .BIBLIOGRAPHY + .R1 + no-label-in-text -+ + no-label-in-reference | These are actually optional + database <full path to the database> -+ + join-authors ", and " ", " ", and " + bibliography <full path to database> + .R2 +</pre> +</p> + +<p> +Whichever option you choose, <strong>mom</strong> will output a full +bibliography page, complete with a title ("BIBLIOGRAPHY" +by default, but that can be changed). +</p> + +<a name="INVOKING_REF"><h3><u>6. Invoking groff with mom and refer</u></h3></a> + +<p> +So, now you've got a document, formatted properly to use references +processed with <strong>refer</strong>, what do you do to output the +document? +</p> + +<p> +It's simple. Instead of invoking <strong>groff</strong> 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: + +<pre> + groff -R -mom filename +</pre> +</p> + +<hr align="left" width="66%"/> + +<a name="MACROS_REF"><h3><u>Index of bibliography and reference macros</u></h3></a> + +<ul> + <li><a href="#REF">Tag: REF</a> — collected, footnote or endnote references tag</li> + <li><a href="#FOOTNOTE_REFS">FOOTNOTE_REFS</a> — REFs go to footnotes</li> + <li><a href="#ENDNOTE_REFS">ENDNOTE_REFS</a> — REFs go to endnotes</li> + <li><a href="#BRACKET_REFS">REF(</a> — references embedded in text between parentheses</li> + <li><a href="#BRACKET_REFS">REF[</a> — references embedded in text between square brackets</li> + <li><a href="#BRACKET_REFS">REF{</a> — references embedded in text between braces</li> + <li><a href="#INDENT_REFS">INDENT_REFS</a> — manage the 2nd line indent of references</li> + <li><a href="#HYPHENATE_REFS">HYPHENATE_REFS</a> — en/disable hyphenation of references</li> + <li><a href="#BIBLIOGRAPHY">BIBLIOGRAPHY</a> — begin a bibliography page</li> + <li><a href="#BIBLIOGRAPHY_TYPE">BIBLIOGRAPHY_TYPE</a> — plain, or numbered list bibliography</li> + <li><a href="#BIBLIO_CONTROL">Bibliography page style control macros</a></li> +</ul> + +<!-- -REF- --> + +<hr width="33%" align="left"/> + +<a name="REF"><h4><u>Marking off references for footnotes, endnotes, or collection</u></h4></a> + +<p> +Tag: <strong>REF</strong> +</p> + +<p> +The macro, <strong>REF</strong>, tells <strong>mom</strong> +that what follows is <strong>refer</strong>-specific, a +keyword-identified reference from a <strong>refer</strong> database. +Depending on whether you've issued a +<a href="#FOOTNOTE_REFS">FOOTNOTE_REFS</a> +or +<a href="#ENDNOTE_REFS">ENDNOTE_REFS</a> +instruction, <strong>REF</strong> also tells <strong>mom</strong> +where to place the reference. If <strong>FOOTNOTE_REFS</strong>, +the reference will be formatted and placed in a footnote. If +<strong>ENDNOTE_REFS</strong>, 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 on a +<a href="#BIBLIOGRAPHY">bibliography page</a>. +</p> + +<p> +Before you use <strong>REF</strong>, you must create a +<strong>refer</strong> block containing <strong>refer</strong> +commands (see +<a href="#RCOMMANDS_REF">Required refer commands</a> +in the tutorial, above). +</p> + +<p> +<strong>REF</strong> usage always looks like this: + +<pre> + .REF + .[ + keyword(s) + .] + .REF +</pre> +</p> + +<p> +Notice that <strong>REF</strong> "brackets" the +<strong>refer</strong> call, and never takes an argument. +</p> + +<p> +What <strong>REF</strong> really is is a convenience. One could, +for example, put a reference in a footnote by doing + +<pre> + .FOOTNOTE + .[ + keyword(s) + .] + .FOOTNOTE OFF +</pre> +</p> + +<p> +However, if you have a lot of references going into footnotes (or +endnotes), it's much shorter to type <kbd>.REF/.REF</kbd> than +<kbd>.FOOTNOTE/.FOOTNOTE OFF</kbd>. It also helps you distinguish +— visually, in your input file — between footnotes (or +endnotes) which are references, and footnotes (or endnotes) which +are explanatory, or expand on the text. +</p> + +<p> +<strong>Additional arguments:</strong> If you're using +<strong>REF</strong> to put references in footnotes and your +footnotes need to be indented, you may (indeed, should) pass +<strong>REF</strong> the same arguments used to indent footnotes. +See +<a href="docelement.html#FOOTNOTE">FOOTNOTE</a>. +</p> + +<p> +<strong>Note:</strong> When <strong>REF</strong> is used with +<a href="#FOOTNOTE_REFS">FOOTNOTE_REFS</a>, +it behaves identically to +<a href="docelement.html#FOOTNOTE">FOOTNOTE</a>, +so please read the +<a href="docelement.html#FOOTNOTE_NOTE">HYPER IMPORTANT NOTE</a> +found in the document entry for <strong>FOOTNOTE</strong>. +</p> + +<p> +When <strong>REF</strong> is used with +<a href="#ENDNOTE_REFS">ENDNOTE_REFS</a>, +it behaves identically to +<a href="docelement.html#FOOTNOTE">ENDNOTE</a>, +so please read the +<a href="docelement.html#ENDNOTE_NOTE">HYPER IMPORTANT NOTE</a> +found in the document entry for <strong>ENDNOTE</strong>. +</p> + +<!-- -FOOTNOTE_REFS- --> + +<hr width="33%" align="left"/> + +<a name="FOOTNOTE_REFS"><h4><u>Instruct REF to put references in footnotes</u></h4></a> + +<p> +Macro: <strong>FOOTNOTE_REFS</strong> +</p> + +<p> +<strong>FOOTNOTE_REFS</strong> is an instruction to +<a href="#REF">REF</a>, +saying, "put all subsequent references bracketed by the +<strong>REF</strong> macro into footnotes." You invoke it by +itself, with no argument. +</p> + +<p> +When <strong>FOOTNOTE_REFS</strong> 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 <strong>FOOTNOTE_REFS</strong> 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 <strong>FOOTNOTE_REFS</strong>. +</p> + +<!-- -ENDNOTE_REFS- --> + +<hr width="33%" align="left"/> + +<a name="ENDNOTE_REFS"><h4><u>Instruct REF to put references in endnotes</u></h4></a> + +<p> +Macro: <strong>ENDNOTE_REFS</strong> +</p> + +<p> +<strong>ENDNOTE_REFS</strong> is an instruction to +<a href="#REF">REF</a>, +saying, "add all subsequent references bracketed by the +<strong>REF</strong> macro to endnotes." You invoke it by +itself, with no argument. +</p> + +<p> +When <strong>ENDNOTE_REFS</strong> is in effect, +<strong>mom</strong> 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 <strong>ENDNOTE_REFS</strong> and +<a href="#FOOTNOTE_REFS">FOOTNOTE_REFS</a> +at any time. +</p> + +<!-- -BRACKET_REFS- --> + +<hr width="33%" align="left"/> + +<a name="BRACKET_REFS"><h4><u>References embedded in text</u></h4></a> + +<p> +Macro pair: <strong>REF(</strong> ... <strong>REF)</strong> +<br/> + +Macro pair: <strong>REF[</strong> ... <strong>REF]</strong> +<br/> + +Macro pair: <strong>REF{</strong> ... <strong>REF}</strong> +</p> + +<p> +You may sometimes want to embed references directly into the body +of your documents, typically, but not always, inside parentheses. +<strong>Mom</strong> makes this possible through the use of the +<strong>REF<bracket type></strong> macros. +</p> + +<p> +All three macro pairs, above, are invoked the same way, namely +by introducing the reference with the first ("open") +macro of the <strong>REF<bracket type></strong> +pair, and terminating it with the second ("close") +<strong>REF<bracket type></strong> of the pair. For +example + +<pre> + .REF( + .[ + keyword(s) + .] + .REF) +</pre> + +will embed a reference in the body of your document, surrounded by +parentheses. <strong>.REF[</strong> ... <strong>.REF]</strong> will +surround the reference with square brackets. +<strong>.REF{</strong> ... <strong>.REF}</strong> will surround it with +curly braces. +</p> + +<!-- -INDENT_REFS- --> + +<hr width="33%" align="left"/> + +<a name="INDENT_REFS"><h4><u>Manage the second-line indent of references</u></h4></a> + +<p> +<nobr>Macro: <strong>INDENT_REFS</strong> <kbd>FOOTNOTE | ENDNOTE | BIBLIO <indent> </kbd></nobr> +<br/> + +<em>*<indent> requires a <a href="definitions.html#TERMS_UNITOFMEASURE">unit of measure</a></em> +</p> + +<p> +Proper MLA-style references should have their second, and subsequent +lines, if any, indented. Since <strong>mom</strong> 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#TERMS_EM">ems</a> +for +<a href="docprocessing.html#PRINTSTYLE">PRINSTYLE</a> +<strong>TYPESET</strong> +and 2 ems for +<a href="docprocessing.html#PRINTSTYLE">PRINSTYLE</a> +<strong>TYPEWRITE</strong>. +</p> + +<p> +If you'd like to change the indent for footnotes, endnotes or +bibliographies, just invoke <kbd>.INDENT_REFS</kbd> with a +first argument telling <strong>mom</strong> for which you want the +indent changed, and a second argument saying what you'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#TERMS_PICAS_POINTS">picas</a>, + +<pre> + .INDENT_REFS BIBLIO 3P +</pre> + +is how you'd set it up. +</p> + +<p> +<strong>Tip:</strong> if you are identifying endnotes by line +number +<nobr>(<a href="docelement.html#ENDNOTE_MARKER_STYLE">ENDNOTE_MARKER_STYLE</a> <kbd>LINE</kbd>)</nobr> +and you have instructed <strong>mom</strong> to put references +bracketed by +<a href="#REF">REF</a> +into endnotes (with +<a href="#ENDNOTE_REFS">ENDNOTE_REFS</a>), +you will probably want to adjust the second-line indent for +references in endnotes, owing to the way <strong>mom</strong> +formats line-numbered endnotes. Study the output of such +documents to see whether an indent adjustment is required. +</p> + +<!-- -HYPHENATE_REFS- --> + +<hr width="33%" align="left"/> + +<a name="HYPHENATE_REFS"><h4><u>Enable/disable hyphenation of references</u></h4></a> + +<p> +<nobr>Macro: <strong>HYPHENATE_REFS</strong> <kbd><toggle></kbd></nobr> +</p> + +<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, <strong>mom</strong> will +hyphenate references bracketed by the +<a href="#REF">REF</a> +macro. Since references typically contain quite a lot of proper +names, which shouldn't be hyphenated, you may want to disable +hyphenation for references. +</p> + +<p> +<strong>HYPHENATE_REFS</strong> is a toggle macro; +invoking it by itself will turn automatic hyphenation of +<strong>REF</strong>-bracketed references on (the default). +Invoking it with any other argument (<strong>OFF</strong>, +<strong>NO</strong>, <strong>X</strong>, etc.) will disable +automatic hyphenation for references bracketed by +<strong>REF</strong>. +</p> + +<p> +An alternative to turning reference hyphenation off is to prepend +to selected proper names in your <strong>refer</strong> database +the <strong>groff</strong> +<a href="definitions.html#TERMS_DISCRETIONARYHYPHEN">discretionary hyphen</a> +character, <kbd>\%</kbd>. (See +<a href="#REF_DISC_HY">here</a> +in the tutorial for an example.) +</p> + +<p> +<strong>Note:</strong> references embedded in the body of a document +with +<a href="#BRACKET_REFS">REF</a><strong><bracket type></strong> +are considered part of +<a href="definitions.html#TERMS_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: + +<pre> + .HY OFF + .REF( + .[ + keyword(s) + .] + .REF) + .HY +</pre> +</p> + +<p> +Alternatively, sprinkle your database fields liberally with +<kbd>\%</kbd>. +</p> + +<!-- -BIBLIOGRAPHY- --> + +<hr width="33%" align="left"/> + +<a name="BIBLIOGRAPHY"><h4><u>Begin a bibliography page</u></h4></a> + +<p> +Macro: <strong>BIBLIOGRAPHY</strong> +</p> + +<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. <strong>BIBLIOGRAPHY</strong> breaks to a new page, prints the +title (BIBLIOGRAPHY by default, but that can be changed), and awaits +<strong>refer</strong> 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 page style control macros</a> +for macros to tweak, design and control the appearance of +bibliography pages. +</p> + +<!-- -BIBLIOGRAPHY_TYPE- --> + +<hr width="33%" align="left"/> + +<a name="BIBLIOGRAPHY_TYPE"><h4><u>Plain, or numbered list bibliography</u></h4></a> + +<p> +<nobr>Macro: <strong>BIBLIOGRAPHY_TYPE</strong> <kbd>PLAIN | LIST [ <list separator> ] [ <list prefix> ]</kbd></nobr> +</p> + +<p> +<strong>Mom</strong> offers two styles of bibliography output: +plain, or numbered list style. With <kbd>PLAIN</kbd>, bibliography +entries are output with no enumerators. With <kbd>LIST</kbd>, each +entry is numbered. +</p> + +<p> +Entering <kbd>.BIBLIOGRPHY_TYPE PLAIN</kbd> gives you a plain +bibliography. +</p> + +<p> +Entering <kbd>.BIBLIOGRAPHY_TYPE LIST</kbd> gives +you an enumerated bibliography. The two optional +arguments, <kbd><list separator></kbd> and +<kbd><list prefix></kbd> have the same meaning as the +equivalent arguments to +<a href="docelement.html#LIST">LIST</a> +(i.e. <kbd><separator></kbd> and <kbd><prefix></kbd>). +</p> + +<p> +You may enter <kbd>.BIBLIOGRAPHY_TYPE</kbd> either before or +after <kbd>.BIBLIOGRAPHY</kbd>. It must, however, always come +before the <strong>refer</strong> 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> +<strong>Mom</strong>'s default <strong>BIBLIOGRAPHY_TYPE</strong> +is <strong>LIST</strong>, with a period (dot) as the separator, and +no prefix. +</p> + +<!-- -BIBLIO_CONTROL- --> + +<hr width="66%" align="left"/> + +<a name="BIBLIO_CONTROL"><h3><u>Bibliography pages style control</u></h3></a> + +<p> +<strong>Mom</strong> 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> + <li><a href="#BIBLIO_GENERAL"><strong>General bibliography pages style control</strong></a></li> + <ul> + <li><a href="#BIBLIO_STYLE">Base family/font/quad for bibliographies</a></li> + <li><a href="#BIBLIO_PT_SIZE">Base point size for bibliographies</a></li> + <li><a href="#BIBLIO_LEAD">Leading of bibliographies</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> + <li>Pagination of bibliographies:</li> + <ul> + <li><a href="#BIBLIO_PAGENUM_STYLE">Bibliography pages page numbering style</a></li> + <li><a href="#BIBLIO_FIRST_PAGENUMBER">Setting the first page number of bibliography pages</a></li> + <li><a href="#BIBLIO_NO_FIRST_PAGENUM">Omitting a page number on the first page of bibliographies</a></li> + </ul> + <li><a href="#SUSPEND_PAGINATION">Suspending pagination of bibliographies</a></li> + </ul> + <li><a href="#BIBLIO_HEADER_CONTROL"><strong>Bibliography pages header/footer control</strong></a></li> + <ul> + <li><a href="#BIBLIO_MODIFY_HDRFTR">Modifying what goes in the bibliography pages header/footer</a></li> + <li><a href="#BIBLIO_HDRFTR_CENTER">Enabling a header/footer centre when doctype is CHAPTER</a></li> + <li><a href="#BIBLIO_ALLOWS_HEADERS">Allow headers on bibliography pages</a></li> + </ul> + <li><a href="#BIBLIO_MAIN_TITLE"><strong>Bibliography page head (i.e. the title at the top) control</strong></a></li> + <ul> + <li><a href="#BIBLIO_STRING">Creating/modifying the bibliography page head</a></li> + <li><a href="#BIBLIO_STRING_CONTROL">Bibliography page head control</a></li> + <li><a href="#BIBLIO_STRING_UNDERLINE">Bibliography page head underlining</a></li> + <li><a href="#BIBLIO_STRING_CAPS">Bibliography page head capitalization</a></li> + </ul> +</ol> + +<hr align="left" width="66%"/> + +<a name="BIBLIO_GENERAL"><h4><u>1. General bibliography page style control</u></h4></a> + +<a name="BIBLIO_STYLE"><h5>*<u>Bibliography family/font/quad</u></h5></a> + +<p> +See +<a href="#CONTROL_MACRO_ARGS">Arguments to the control macros</a>. +</p> + +<pre> +.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 or J +</pre> + +<!-- -BIBLIO_PT_SIZE- --> + +<a name="BIBLIO_PT_SIZE"><h5>*<u>Bibliography point size</u></h5></a> + +<p> +<nobr>Macro: <strong>BIBLIOGRAPHY_PT_SIZE</strong> <kbd><base type size of bibliography></kbd></nobr> +</p> + +<p> +Unlike most other control macros that deal with size of document +elements, <strong>BIBLIOGRAPHY_PT_SIZE</strong> takes as its +argument an absolute value, relative to nothing. Therefore, the +argument represents the size of bibliography type in +<a href="definitions.html#TERMS_PICASPOINTS">points</a>, +unless you append an alternative +<a href="definitions.html#TERMS_UNITOFMEASURE">unit of measure</a>. +For example, + +<pre> + .BIBLIOGRAPHY_PT_SIZE 12 +</pre> + +sets the base point size of type on the bibliography page to 12 +points, whereas + +<pre> + .BIBLIOGRAPHY_PT_SIZE .6i +</pre> + +sets the base point size of type on the bibliography page to 1/6 of an +inch. +</p> + +<p> +The type size set with <strong>BIBLIOGRAPHY_PT_SIZE</strong> 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 TYPESET</a> +is 12.5 points (the same default size used in the body of the document). +</p> + +<!-- -BIBLIO_LEAD- --> + +<a name="BIBLIO_LEAD"><h5>*<u>Bibliography lead</u></h5></a> + +<p> +<nobr>Macro: <strong>BIBLIOGRAPHY_LEAD</strong> <kbd><base leading of bibliographies> [ ADJUST ]</kbd></nobr> +<br/> + +<em>*Does not require a <a href="definitions.html#TERMS_UNITOFMEASURE">unit of measure</a>; points is assumed</em> +</p> + +<p> +Unlike most other control macros that deal with leading of document +elements, <strong>BIBLIOGRAPHY_LEAD</strong> takes as its argument +an absolute value, relative to nothing. Therefore, the argument +represents the +<a href="definitions.html#TERMS_LEADING">leading</a> +of endnotes in +<a href="definitions.html#TERMS_PICASPOINTS">points</a> +unless you append an alternative +<a href="definitions.html#TERMS_UNITOFMEASURE">unit of measure</a>. +For example, + +<pre> + .BIBLIOGRAPHY_LEAD 14 +</pre> + +sets the base leading of type on the bibliography page to 14 +points, whereas +</p> + +<p> +<pre> + .BIBLIOGRAPHY_LEAD .5i +</pre> + +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 <strong>BIBLIOGRAPHY_LEAD</strong> 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 TYPESET</a> +is 14 points, adjusted. +</p> + +<p> +<strong>NOTE:</strong> Even if you give <strong>mom</strong> +a <nobr><kbd>.DOC_LEAD_ADJUST OFF</kbd></nobr> command, she +will still, by default, adjust bibliography leading. You MUST enter +<nobr><kbd>BIBLIOGRAPHY_LEAD <lead></kbd></nobr> with no +<kbd>ADJUST</kbd> argument to disable this default behaviour. +</p> + +<!-- -SINGLESPACE_BIBLIO- --> + +<a name="SINGLESPACE_BIBLIO"><h5>*<u>Singlespace bibliographies (TYPEWRITE only)</u></h5></a> + +<p> +<nobr>Macro: <strong>SINGLESPACE_BIBLIOGRAPHY</strong> <kbd><toggle></kbd></nobr> +</p> + +<p> +If your +<a href="docprocessing.html#PRINTSTYLE">PRINTSTYLE</a> +is <strong>TYPEWRITE</strong> and you use TYPEWRITE'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'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_SPACING- --> + +<a name="BIBLIO_SPACING"><h5>*<u>Adjusting the space between bibliography entries</u></h5></a> + +<p> +<nobr>Macro: <strong>BIBLIOGRAPHY_SPACING</strong> <kbd><amount of space> </kbd></nobr> +<br/> + +<em>*Requires a <a href="definitions.html#TERMS_UNITOFMEASURE">unit of measure</a></em> +</p> + +<p> +By default, <strong>mom</strong> inserts 1 linespaces between +bibliography entries on bibliography pages. If you'd prefer she +add a different amount of space, instruct her to do so with the +macro, <strong>BIBLIOGRAPHY_SPACING</strong>. Say, for example, +you'd prefer only 1/2 linespace. That would be done with + +<pre> + .BIBLIOGRAPHY_SPACING .5v +</pre> +</p> + +<p> +As with endnotes pages, owing to the space inserted between +bibliography entries, bibliography pages may have hanging +bottom margins. Unlike endnotes pages, <strong>mom</strong> +is sad to report that there's nothing you can do about +this, except a) pray things work out, or b) set your +<strong>BIBLIOGRAPHY_SPACING</strong> to zero. +</p> + +<!-- -BIBLIO_NO_COLUMNS- --> + +<a name="BIBLIO_NO_COLUMNS"><h5>*<u>Turning off column mode during bibliography output</u></h5></a> + +<p> +<nobr>Macro: <strong>BIBLIOGRAPHY_NO_COLUMNS</strong> <kbd><toggle></kbd></nobr> +</p> + +<p> +By default, if your document is +<a href="docprocessing.html#COLUMNS">set in columns</a>, +<strong>mom</strong> sets the bibliographies in columns, +too. However, if your document is set in columns and +you'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 +<strong>BIBLIOGRAPHY_NO_COLUMNS</strong> turned on. +</p> + +<!-- -BIBLIO_PAGENUM_STYLE- --> + +<a name="BIBLIO_PAGENUM_STYLE"><h5>*<u>Bibliography-page page numbering style</u></h5></a> + +<p> +<nobr>Macro: <strong>BIBLIOGRAPHY_PAGENUM_STYLE</strong> <kbd>DIGIT | ROMAN | roman | ALPHA | alpha</kbd></nobr> +</p> + +<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 + +<pre> + .BIBLIOGRAPHY_PAGENUM_STYLE alpha +</pre> +</p> + +<!-- -BIBLIO_FIRST_PAGENUMBER- --> + +<a name="BIBLIO_FIRST_PAGENUMBER"><h5>*<u>Setting the first page number of bibliography pages</u></h5></a> + +<p> +<nobr>Macro: <strong>BIBILOGRAPHY_FIRST_PAGENUMBER</strong> <kbd><page # that appears on page 1 of bibliographies></kbd></nobr> +</p> + +<p> +Use this macro with caution. If all bibliographies 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, <strong>BIBLIOGRAPHY_FIRST_PAGENUMBER</strong> tells +<strong>mom</strong> what page number to put on the first page of +the bibliography. +</p> + +<p> +If you set <strong>BIBLIOGRAPHY_FIRST_PAGENUMBER</strong> in collated +documents where the bibliographies are output after each separate doc, +you have to reset every separate document'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- --> + +<a name="BIBLIO_NO_FIRST_PAGENUM"><h5>*<u>Omitting a page number on the first page of bibliographies</u></h5></a> + +<p> +<nobr>Macro: <strong>BIBLIOGRAPHY_NO_FIRST_PAGENUM</strong> <kbd><toggle></kbd></nobr> +</p> + +<p> +This macro is for use only if +<a href="headfootpage.html#FOOTERS">FOOTERS</a> +are on. It tells +<a href="#BIBLIOGRAPHY">BIBLIOGRAPHY</a> +not to print a page number on the first bibliography page. +<strong>Mom</strong>'s default is to print the page number. +</p> + +<!-- -SUSPEND_PAGINATION- --> + +<a name="SUSPEND_PAGINATION"><h5>*<u>Suspending pagination of bibliography pages</u></h5></a> + +<p> +Macro: <strong>SUSPEND_PAGINATION</strong> +<br/> + +Macro: <strong>RESTORE_PAGINATION</strong> +</p> + +<p> +<strong>SUSPEND_PAGINATION</strong> doesn't take an argument. +Invoked immediately prior to +<a href="#BIBLIOGRAPHY">BIBLIOGRAPHY</a>, +it turns off pagination for the duration of the bibliography. +<strong>Mom</strong> 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've finished with your bibliography. +</p> + +<a name="BIBLIO_HEADER_CONTROL"><h4><u>2. Bibliography page header/footer control</u></h4></a> + +<a name="BIBLIO_MODIFY_HDRFTR"></a> + +<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 CHAPTER</a>, +<strong>mom</strong> prints the same header or footer used throughout +the document on bibliography pages. Chapters get treated differently +in that, by default, <strong>mom</strong> 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 +<em>not</em> want <strong>mom</strong> to remove the centre string from +the bibliography pages headers/footers, invoke +<a href="#BIBLIOGRAPHY_HDRFTR_CENTER"><kbd>.BIBLIOGRAPHY_HEADER_CENTER</kbd></a> +with no argument. +</p> + +<p> +An important change you may want to make is to put the word +"Bibliography" in the header/footer centre position. +To do so, do + +<pre> + .HEADER_CENTER "Bibliography" + or + .FOOTER_CENTER "Bibliography" +</pre> + +prior to invoking <kbd>.BIBLIOGRAPHY</kbd>. If your +<a href="docprocessing.html#DOCTYPE">DOCTYPE</a> +is <kbd>CHAPTER</kbd>, you must also invoke +<a href="#BIBLIOGRAPHY_HDRFTR_CENTER"><kbd>.BIBLIOGRAPHY_HEADER_CENTER</kbd></a> +for the <strong>HEADER_CENTER</strong> to appear. +</p> + +<a name="BIBLIO_HDRFTR_CENTER"><h5>*<u>Bibliography page header/footer centre string</u></h5></a> + +<p> +<nobr>Macro: <strong>BIBLIOGRAPHY_HEADER_CENTER</strong> <kbd>toggle</kbd></nobr> +</p> + +<p> +If your +<a href="docprocessing.html#DOCTYPE">DOCTYPE</a> +is <kbd>CHAPTER</kbd> and you want <strong>mom</strong> 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. +<strong>Mom</strong>'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 (<strong>OFF, QUIT, Q, X</strong>...). +</p> + +<a name="BIBLIO_ALLOWS_HEADERS"><h5>*<u>Allow headers on bibliography pages</u></h5></a> + +<p> +<nobr>Macro: <strong>BIBLIOGRAPHY_ALLOWS_HEADERS</strong> <kbd><none> | ALL</kbd></nobr> +</p> + +<p> +By default, if <strong>HEADERS</strong> are on, <strong>mom</strong> +prints page headers on all bibliography pages except the first. If you +don't want her to print headers on bibliography pages, do + +<pre> + .BIBLIOGRAPHY_ALLOWS_HEADERS OFF +</pre> +</p> + +<p> +If you want headers on every page <em>including the first</em>, do + +<pre> + .BIBLIOGRAPHY_ALLOWS_HEADERS ALL +</pre> +</p> + +<p> +<strong>NOTE:</strong> If <strong>FOOTERS</strong> are on, +<strong>mom</strong> prints footers on every bibliography page. This is +a style convention. In <strong>mom</strong>, there is no such beast +as <strong>BIBLIOGRAPHY_ALLOWS_FOOTERS OFF</strong>. +</p> + +<a name="BIBLIO_MAIN_TITLE"><h4><u>3. Bibliography page first page head (title) control</u></h4></a> + +<!-- -BIBLIO_STRING- --> + +<a name="BIBLIO_STRING"><h5>*<u>Bibliography pages first page head (title) string</u></h5></a> + +<p> +<nobr>Macro: <strong>BIBLIOGRAPHY_STRING</strong> <kbd>"<head to print at the top of bibliography pages>"</kbd></nobr> +</p> + +<p> +By default, <strong>mom</strong> prints the word +"BIBLIOGRAPHY" as a head 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 bibliography +page head you want, surrounded by double-quotes. If you don't +want a head at the top of the first bibliography page, invoke +<kbd>.BIBLIOGRAPHY_STRING</kbd> with a blank argument (either two +double-quotes side by side — <kbd>""</kbd> — +or no argument at all). +</p> + +<!-- -BIBLIO_STRING_CONTROL- --> + +<a name="BIBLIO_STRING_CONTROL"><h5>*<u>Bibliography page first page head (title) control</u></h5></a> + +<p> +See +<a href="#CONTROL_MACRO_ARGS">Arguments to the control macros</a>. +</p> + +<pre> +.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) +</pre> + +<!-- -BIBLIO_STRING_UNDERLINE- --> + +<a name="BIBLIO_STRING_UNDERLINE"><h5>*<u>Bibliography-page head (title) underlining</u></h5></a> + +<p> +<nobr>Macro: <strong>BIBLIOGRAPHY_STRING_UNDERLINE</strong> <kbd>[DOUBLE] [<underline weight> [<underline gap> [<distance between double rules]]] | <none> | <anything></kbd></nobr> +<br/> + +Alias: <strong>BIBLIOGRAPHY_STRING_UNDERSCORE</strong> +<br/> + +<em>*The argument</em> <kbd><underline weight></kbd> <em>must</em> NOT <em>have the</em> <a href="definitions.html#TERMS_UNITOFMEASURE">unit of measure</a>, <kbd>p</kbd>, <em>appended to it</em> +</p> + +<p> +Invoked without an argument, <kbd>.BIBLIOGRAPHY_STRING_UNDERLINE</kbd> +will place a single rule underneath the bibliography-page head. Invoked +with the argument <kbd>DOUBLE</kbd>, +<strong>BIBLIOGRAPHY_STRING_UNDERLINE</strong> will double-underline +the head. Invoked with any other non-numeric argument, (e.g. +<strong>OFF</strong>, <strong>NO</strong>, <strong>X</strong>, etc.) +the macro disables underlining of the head. +</p> + +<p> +In addition, you can use <strong>BIBLIOGRAPHY_STRING_UNDERLINE</strong> +to control the weight of the underline rule(s), the gap between the +head and the underline, and, in the case of double-underlines, the +distance between the two rules. +</p> + +<p> +Some examples: + +<pre> + .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 points + + .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 +</pre> + +Note, from the above, that in all instances, underlining (single or +double) is enabled whenever <strong>BIBLIOGRAPHY_STRING_UNDERLINE</strong> +is used in this way. +</p> + +<p> +<strong>Mom</strong>'s default is to double-underline the head +with 1/2-point rules placed 2 points apart and 2 points below the +baseline of the head. +</p> + +<!-- -BIBLIO_STRING_CAPS- --> + +<a name="BIBLIO_STRING_CAPS"><h5>*<u>Bibliography-page head (title) automatic capitalization</u></h5></a> + +<p> +<nobr>Macro: <strong>BIBLIOGRAPHY_STRING_CAPS</strong> <kbd>toggle</kbd></nobr> +</p> + +<p> +Invoked by itself, <kbd>.BIBLIOGRAPHY_STRING_CAPS</kbd> will +automatically capitalize the bibliography page head. Invoked with +any other argument, the macro disables automatic capitalization of +the head. +</p> + +<p> +If you're generating a table of contents, you may want the +bibliography page head string in caps, but the toc entry in caps/lower +case. If the argument to +<a href="#BIBLIOGRAPHY_STRING">BIBLIOGRAPHY_STRING</a> +is in caps/lower case and <strong>BIBLIOGRAPHY_STRING_CAPS</strong> is +on, this is exactly what will happen. +</p> + +<p> +<strong>Mom</strong>'s default is to capitalize the bibliography-page +head string. +</p> + +<hr/> + +<p> +<a href="letters.html#TOP">Next</a> +<a href="cover.html#TOP">Prev</a> +<a href="#TOP">Top</a> +<a href="toc.html">Back to Table of Contents</a> +</p> + +</body> +</html> + +<!-- vim: fileencoding=latin1: nomodified: +--> diff --git a/contrib/mom/momdoc/reserved.html b/contrib/mom/momdoc/reserved.html new file mode 100644 index 00000000..05929511 --- /dev/null +++ b/contrib/mom/momdoc/reserved.html @@ -0,0 +1,2664 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!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=iso-8859-1"/> +<title>Mom -- List of reserved words</title> +</head> +<body bgcolor="#dfdfdf"> + +<!--====================================================================--> + +<a name="TOP"></a> + +<p> +<a href="appendices.html#TOP">Prev</a> <a href="toc.html">Back to Table of Contents</a> +</p> + +<a name="RESERVED"><h1 align="center"><u>LIST OF RESERVED WORDS</u></h1></a> + +<p> +The following is a list of "reserved" words used by +<strong>mom</strong>. 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, DON'T USE IT. +Choose something else instead. +</p> + +<p> +Anyone interested in playing around inside <strong>mom</strong>'s macro +file (om.tmac) will find this list useful as well since it lists all +(I hope) the macros, strings, diversions and number registers +<strong>mom</strong> uses, along with brief descriptions of their +functions. +</p> + +<pre> +TYPESETTING +=========== + ++++MACROS+++ + +Page layout +----------- +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 + +Page control +------------ +DO_B_MARGIN Margin at bottom of page; trap-invoked +DO_T_MARGIN Margin at top of page; trap-invoked + +Style +----- +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 + +Autolead +-------- +AUTOLEAD Always lead n points more than .PT_SIZE + +Flush +----- +JUSTIFY Justified text +QUAD Filled text, left, right, or centre + +Quad +---- +CENTER Non-filled text, centre +LEFT Non-filled text, left +RIGHT Non-filled text, right + +Hyphenation +----------- +HY Turn hyphenation on/off, or set LINES, MARGIN, SPACE +HY_SET Set LINES, MARGIN, SPACE in a single command + +Advanced style +-------------- +KERN Turn automatic kerning on or off +LIGATURES Turn ligatures on or off +SS Sentence space control +WS Word space control + +Line breaks +----------- +BR Alias of br +EL Breaks line but doesn't advance +SPACE Alias of sp +SPREAD Alias of brp + +Ald/rld +------- +ALD Advance lead +RLD Reverse lead + +Indents +------- +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 + +Tabs +---- +ST String tab +TAB_SET Tab Set +TN Tab Next +TQ Tab Quit + +MCO Turn on multi-column mode +MCR Return to top of column +MCX Turn off multi-column mode + +Underscore +---------- +UNDERSCORE Underscores words or phrases +UNDERSCORE2 Double underscores words or phrases + +Underline +--------- +UNDERLINE Underlines whole passages (Courier only) + +Smart Quotes +------------ +SMARTQUOTES Turns smart quotes on or off + +Graphical objects +----------------- +RULE_WEIGHT Weight of rules drawn with \*[RULE] +DBX Draw box +DCL Draw circle (ellipse) +DRH Draw horizontal rule +DRV Draw vertical rule + +Misc + Support +-------------- +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 +TRAP Turn traps off or on + ++++DIVERSIONS+++ + +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 Diverts $PAD_STRING for processing +TYPESIZE Diverts SIZESPECS routine so it doesn't print + ++++NUMBER REGISTERS+++ + +#ABORT_FT_ERRORS Abort on FT errors? (boolean) +#ALD ALD value +#ARGS_TO_LIST Tells LIST whether LIST was invoked with a valid + arg; controls LIST OFF processing +#ARGS_TO_SQ Tells SMARTQUOTES whether it was invoked with a + valid arg; controls SMARTQUOTES OFF + processing +#AUTOLEAD_FACTOR Using FACTOR arg to AUTOLEAD? (boolean) +#AUTO_LEAD Using autolead? (boolean) +#AUTOLEAD_VALUE Auto leading value +#BL_INDENT Value of left indent when IB +#B_MARGIN Bottom margin +#B_MARGIN_SET Has a bottom margin been set with B_MARGIN? (boolean) +#BOLDER_UNITS Number of units to embolden type +#BR_AT_LINE_KERN Break when EW/RW are invoked? (boolean) +#BR_INDENT Value of right indent when IB +#BX_SOLID Draw box filled? (boolean) +c column mark +#CAPS_ON Is CAPS enabled? (boolean) +#CL_SOLID Draw cirlce filled? (boolean) +#CODE_FAM Use different family from Courier for CODE? (boolean) +#CONDENSE Are we in pseudo-condense mode? (boolean) +#CONDENSE_WAS_ON For restoring \*[COND] in DROPCAP +#COND_WIDTH Width of pseudo-condensed type + (pointsize x $COND_PERCENT) +#CURRENT_HY \\n[.hy] when ref*normal-print called +#CURRENT_L_LENGTH Current line length at first invocation of LIST; + like #ORIG_L_LENGTH +#CURRENT_TAB Current tab number +#DC_COLOR Colorize dropcap? (boolean) +#DC_GUT Width of dropcap gutter +#DC_HEIGHT Dropcap height +#DC_LINES Number of lines for dropcap +#DEGREES # of degrees slant for pseudo-italic +#ENUMERATOR<n> Number register enumerator for depth <n> in lists +#EXT_WIDTH Width of pseudo-extended type + (pointsize x $EXT_PERCENT) +#EXTEND Are we in pseudo-extend mode? (boolean) +#EXTEND_WAS_ON For restoring \*[EXT] in DROPCAP +#FILL_MODE Which fill mode are we in? (\n(.j) +#FILLED Are we in a fill mode? (boolean) +#H_INDENT Value of left indent when IH +#HL_INDENT<n> Hanging indent for LIST depth <n> +#HL_INDENT Value of the hang when IH +#HY_SET Did we manually set hyphenation parameters? + (boolean) +#HYPHEN_ADJ Amount by which to raise hyphens surrounding page numbers +#HYPHENATE Hyphenation on? (boolean) +#IN_TAB Are we in a tab? (boolean) + Set in macro TAB; used in ST to determine + whether to add #ST_OFFSET to #ST<n>_OFFSET +#INDENT_ACTIVE Indicates whether an indent is active (boolean) +#INDENT_BOTH_ACTIVE Toggle +#INDENT_LEFT_ACTIVE Toggle +#INDENT_RIGHT_ACTIVE Toggle +#INDENT_STYLE_BOTH Indicates IB when #INDENT_ACTIVE=1 (boolean) +#INDENT_STYLE_HANG Indicates IH when #INDENT_ACTIVE=1 (boolean) +#INDENT_STYLE_LEFT Indicates IL when #INDENT_ACTIVE=1 (boolean) +#INDENT_STYLE_RIGHT Indicates IR when #INDENT_ACTIVE=1 (boolean) +#INDENT_STYLE_TEMP Indicates IT when #INDENT_ACTIVE=1 (boolean) +#IGNORE_COLUMNS Don't set document in columns (boolean) +#IN_DIVER Are we in a diversion? (boolean) +#IX_WARN Toggles to 1 the first time IX is user-invoked +#JUSTIFY In EW/RW, when BR_AT_LINE_KERN, whether to + break or break-spread preceding line (boolean) +#KERN Kern on? (boolean) +#KERN_UNIT Size of kern units (1/36 of current point size) +#KERN_WAS_ON Indicates kerning was on; used in list ITEMs (boolean) +#LAST_TAB Last tab number set in multi-columns +#LAST_FN_COUNT_FOR_COLS #FN_COUNT_FOR_COLS at top of HEADER +#LEAD Leading (alias) +#LIGATURES Ligatures on? (boolean) +#LIST_INDENT<n> Left indent of list <n> +#L_INDENT Value of left indent +#L_LENGTH Line length +#L_MARGIN Page offset if set with LMARGIN; + if .po used, \n(.o returns page offset +#LOOP In EPIGRAPH, #LOOP=1 if a while loop executes; otherwise 0. + Elsewhere, an arbitrary incrementing register used to + read in strings +#MCX_ALD Amount to advance past end of longest column +#NEWPAGE Was NEWPAGE just invoked? (boolean) +#NEXT_DEPTH_BACK Next list level back in lists +#NEXT_TAB Current tab number + 1 (used in TN) +#NEXT_TAB Next tab in an n+1 sequence +#NOFILL Are we in a nofill mode? (boolean) +#NOFILL_MODE Nofill mode +#OLD_LEAD Lead in effect prior to changing it with .vs + in .LS +#OPEN_CLOSE Manipulates character " to print `` or '' +#ORIGINAL_L_LENGTH Used in LIST for IB processing; holds \n(.l +p Output line horiz position at end of + $PAD_STRING +#PAD_COUNT Number of times # was included in arg to PAD +#PAD_LIST_DIGITS Pad list digits to the left? (boolean) +#PAD_SPACE Size of padding space +#PAGE_LENGTH Page length (alias) +#PAGE_WIDTH Page width +#PP_ACTIVE Are we in the context of a para? (boolean) +#PRINT_FOOTER_ON_PAGE_1 (boolean) +#PSEUDO_FILL Signals that LEFT, RIGHT or CENTER is + in effect (booleand off, i.e. to 0, when + QUAD <arg> or JUSTIFY is called) +#PT_SIZE Point size (fractional) in units (alias) +#PT_SIZE_SET Was point size set with PT_SIZE? (boolean) +#Q_AT_TOP Does a quote start at the top of a new page? + (boolean) +#QUAD In autoquad mode? (boolean) +#QUIT Tells LIST whether to exit lists completely + (boolean) +#REMOVE Used in LIST OFF cleanup +#RESTORE_LEAD Lead value in effect prior to AUTOLEAD +#RESTORE_LINE_LENGTH Restores actual line length in RULE +#RESTORE_LN_NUMBER Start linenumbering again with stored + #NEXT_LN? (boolean) +#RESTORE_PT_SIZE Stores current point size (in units) prior + to underscore +#R_INDENT Value of right indent +#R_MARGIN Right margin +#RESTORE_PREV_INDENT Tells LIST OFF what kind of indent was active + prior to first invocation of LIST +#RESTORE_SQ Instructs SMARTQUOTES to restore smartquotes if + SMARTQUOTES invoked without an arg +#RLD RLD value +#RULE_WEIGHT Weight given to RULE_WEIGHT +#RULE_WEIGHT_ADJ RULE_WEIGHT/2 +#SHIFT_LIST<n> Value to add to #LIST_INDENT<n> for shifted lists +#SILENT Is silent on? (boolean) +#SIZE_FOR_PAD Used to ensure that the size in effect prior + to PAD is restored at the start of every + iteration of $PAD_STRING +#SLANT_ON Is SLANT on? (boolean) +#SPACE_TO_END Whitespace at end of string passed to PAD +#SQ_WAS_ON Instructs CODE OFF to restore smartquotes if they + were on prior to CODE +#ST<n>_LENGTH Length of ST<n>; calculated during ST <n> +#ST<n>_MARK Page offset of autotab <n> at ST<n>X +#ST_NUM Incrementing counter for autotab identification +#ST<n>_OFFSET Offset (from current tab) to add to #ST<n>_OFFSET + when calculating string indents set from within + tabs +#ST<n>_OFFSET Indent of autotab <n> (page offset) +#STORED_L_INDENT Current left indent at first invocation of LIST +#STORED_R_INDENT Current right indent at first invocation of LIST +#STORED_BL_INDENT Current "both, left" indent at first invocation + of LIST +#STORED_BR_INDENT Current "both, right" indent at first invocation + of LIST +#STORED_HL_INDENT Current hanging indent at first invocation + of LIST +#STORED_T_INDENT Current temporary indent at first invocation + of LIST +#STR_LENGTH Holds string length derived from .length request +#T_INDENT Value of temporary indent +#T_MARGIN Top margin +#TAB_ACTIVE Are we in a tab? (boolean) +#TAB_NUMBER Tab number given to TAB_SET +#TAB_LENGTH Tab length given to TAB_SET +#TAB_OFFSET Tab indent given to TAB_SET +#TEXT_WIDTH Width of string to underscore +#TN Was TN (or \*[T+] called? (boolean) +#TOP Set to 1 in T_MARGIN, DO_T_MARGIN and ALD; tells + the first LS or AUTOLEAD on a page to maintain + the baseline position prior to the LS call +#TOP_BASELINE_ADJ Amount by which to adjust the baseline position + of the first line on the page if an LS or AUTOLEAD + request differs from the lead current at the end of + the previous page +#TOTAL_LISTS Total number of lists in a nest +#UNDERSCORE_WEIGHT Weight of underscores +#UNDERSCORE_WEIGHT_ADJ UNDERSCORE_WEIGHT/2 +#USER_SET_L_LENGTH Did user invoke LL? (boolean) +#USER_SET_TITLE_ITEM Did user invoke TOC_TITLE_ENTRY? +#WEIGHT Weight given to #RULE_WEIGHT +#WEIGHT_ADJ RULE_WEIGHT/2 +u Horiz position of start of underscore + ++++STRINGS+++ + +$ARG String holding substrings derived from .substring request +$COND_PERCENT Percentage by which to pseudo-condense type +$COLOR_SCHEME Color scheme used in NEWCOLOR +$<colorname>_FILL XCOLOR "alias" with _FILL attached; used to determine if + the alias exists when the alias is passed to DBX SOLID + or DCL SOLID +$CURRENT_QUAD Restores current quad value in RULE +$CURRENT_TAB Current tab number +$DC_ADJUST +|- # of points to subtract from dropcap +$DC_FAM Drop cap family +$DC_FT Drop cap font +$DROPCAP The dropcap letter +$ENUMERATOR<n> String enumerator for depth <n> in lists +$ENUMERATOR_TYPE<n> Type of enumerator used in LIST<n> +$EXT_PERCENT Percentage by which to pseudo-extend type +$FAMILY Family +$FAMILY_FOR_PAD Used to ensure that the family in effect prior + to PAD is restored at the start of every + iteration of $PAD_STRING +$FONT Font +$FONT_FOR_PAD Used to ensure that the font in effect prior + to PAD is restored at the start of every + iteration of $PAD_STRING +$PAD_MARKER Character to mark off padding in PAD +$PAD_STRING Arg passed to PAD +$PRE_CODE_FAM Family in effect prior to CODE being invoked +$PRE_CODE_FT Font in effect prior to CODE being invoked +$PREFIX<n> Prefix for enumerator of LIST<n> +$QUAD_VALUE Quad value (left, right, centre, justify) +$QUOTE0 Open quotation marks +$QUOTE1 Close quotation marks +$RESTORE_COND Restores the pseudo-condense value in effect + prior to DROPCAP +$RESTORE_EXT Restores the pseudo-extend value in effect + prior to DROPCAP +$RESTORE_FAM Used to restore the family in effect + prior to DROPCAP +$RESTORE_FT Used to restore the font/fontstyle in effect + prior to DROPCAP +$RESTORE_PT_SIZE Used to restore the point size of normal + running text after a dropcap +$RESTORE_QUAD_VALUE Quad value for use in restoring L, R, C, J + (after tabs) +$RESTORE_SQ The smartquoting string last passed to SMARTQUOTES +$RULE_GAP Distance between underscore rules +$SAVED_STYLE Current style, if there is one (used in FAMILY) +$SAVED_UNDERSCORE_GAP Temporarily holds string in $UNDERSCORE_GAP +$SEPARATOR<n> Separator for depth <n> in lists +$SS_VAR Holds + or - sentence space value +$ST<n>_FILL Always QUAD if QUAD passed to ST <n> +ST\n[#LOOP] Used to initialize string tab markers (1-19) +ST\n[#LOOP]X Used to initialize string tab markers (1-19) +$ST<n>_QUAD_DIR Quad direction supplied to ST for <n> +$TAB_NUMBER Argument passed to TAB macro to call TAB# macro + created in TAB_SET +$UNDERSCORE_GAP Distance between text and underscore rule +$WS_CONSTANT 12; used to hold groff default wordspace +$WS Holds WS value; concatenation of WS_CONSTANT and + WS_VAR +$WS_VAR + or - value to add to $WS_CONSTANT +BLACK Pre-defined black color +black Pre-defined black color +WHITE Pre-defined white color +white Pre-defined white color + ++++ALIASES+++ + +ALIAS als +ALIASN aln +BR br +CENTRE CENTER +COLOUR COLOR +COMMENT SILENT +CONDENSE CONDENSE_OR_EXTEND +EXTEND CONDENSE_OR_EXTEND +FAM FAMILY +FT FONT +HYPHENATE HY +HYPHENATION HY +INCLUDE so +LIG LIGATURES +LL LINE_LENGTH +MAC de +NEW_PAGE bp +NEWCOLOUR NEWCOLOR +NEWPAGE NEW_PAGE +PAGELENGTH PAGE_LENGTH +PAGE_LENGTH pl +PAGEWIDTH PAGE_WIDTH +SPREAD brp +SP sp +STRING ds +TABSET TAB_SET +TB TAB +TI IT +UNDERSCORE_2 UNDERSCORE2 +XCOLOUR XCOLOR + ++++ALIASES FOR NUMBER REGISTERS+++ + +#DIVER_DEPTH dn -- diversion depth +#DIVER_WIDTH dl -- diversion width +#INDENT .i -- value of current indent +#LEAD .v -- line space (.vs, not .ls) +#L_LENGTH .l -- line length +#NUM_ARGS .$ -- number of arguments passed to a macro +#PAGE_LENGTH .p -- page length +#PT_SIZE .ps -- current point size (fractional) in units +#TRAP_DISTANCE .t -- distance to next trap + ++++INLINE ESCAPES+++ + +ALD<n> Move down inline by <n> (between .25 and 12.75) +B Inline equivalent to .EL +BCK Inline backward horizontal movement +BD Bold font +BDI Bold italic font +BLACK Color +black color +BOLDER Pseudo-bold on +BOLDERX Pseudo-bold off +BP Back points (horizontal movement) +BP<n> Back points by <n> (between .25 and 12.75) +BU Back units (inline pairwise kerning) +BU<n> Back units by <n> (between 1 and 36) +COND Pseudo-condense type +COND_FOR_SUP Pseudo-condense string for use with superscripts + (called with CONDSUP) +COND_FOR_SUP Pseudo-extend string for use with superscripts (called + with EXTSUP) +CONDSUP Pseudo-condensed superscript (using value set with + CONDENSE) +CONDSUPX Pseudo-condensed superscript off +CONDX Pseudo-condense off +DOWN Inline downward vertical movement +EN-MARK Inline escape to indicate the beginning of a + range of lines used to identify an endnote +EXT Pseudo-extend type +EXTX Pseudo-extend off +EXTSUP Pseudo-extended superscript +EXTSUPX Pseudo-extended superscript off +FN-MARK Inline escape to indicate the beginning of a + range of lines used to identify a footnote +FP<n> Forward points by <n> (between .25 and 12.75) +FP Forward points (horizontal movement) +FU Forward units (inline pairwise kerning) +FU<n> Forward units by <n> (between 1 and 36) +FWD Inline forward horizontal movement +PREV Return to previous font in effect +RLD<n> Move up, inline, by <n> (between .25 and 12.75) +ROM Roman (medium) font +S Same \s +SLANT Slant (pseudo-italic on +SLANTX Slant off +ST<n> String tab end marker +ST<n> String tab start marker +SUP Superscript +SUPX Superscript off +TB+ Move to next tab number (n+1) without advancing on the page +UP Inline upward vertical movement +WHITE Color +white Color + ++++SPECIAL CHARACTERS+++ + +FOOT The foot character \(fm +INCH The inch character \(fm\(fm +LEADER Deposit leader to end of current LL or TAB +RULE Draw a rule to the full measure of the current line or + tab length + +------------------------------------------------------------------------ + +DOCUMENT PROCESSING +=================== + ++++MACROS+++ + +Document info +------------- +AUTHOR Author +CHAPTER Chapter number +CHAPTER_TITLE Chapter title +COPYRIGHT Copyright info (covers only) +DOCTITLE Overall doc title (for collated docs) +DRAFT Draft number +MISC Misc info (covers only) +REVISION Revision number +SUBTITLE Doc subtitle +TITLE Doc title + +Covers +------ +COVER What goes on cover +COVERS Whether covers get printed (boolean) +COVER_ADVANCE Set vertical start position of cover material +COVER_LEAD Overall leading of covers +COVERTITLE User-defined cover title string +DOC_COVER What goes on doc cover +DOC_COVERS Whether doc covers get printed +DOC_COVER_ADVANCE Set vertical start position of doc cover material +DOC_COVER_LEAD Overall leading of doc covers +DOC_COVERTITLE User-defined doc cover title string + +Document style +-------------- +COPYSTYLE Output style (DRAFT or FINAL) +DEFAULTS In START, sets defaults +DOCTYPE Kind of doc (DEFAULT, CHAPTER, NAMED, LETTER) +PAGENUMBER Page number that appears on 1st page of doc +PAPER Paper size (LETTER, LEGAL, A4) +PRINTSTYLE Print style (TYPEWRITE or TYPESET) +NUMBER_LINES Number output lines in the left margin + +Document tags and macros +------------------------ +ADD_SPACE Special macro to add space to the top of a pages after + page 1; must be preceded by NEWPAGE +BIBLIOGRAPHY Begin a bibliography page +BIBLIOGRAPHY_TYPE LIST or PLAIN +BLOCKQUOTE Block-indented, quoted text +COL_BREAK Breaks and spreads line before invocation; moves to + next column on page or 1st col of next page. An alias + of COL_NEXT. +COL_NEXT Moves to next column on page or 1st col of next page +ENDNOTE Endnote +ENDNOTE_REFS Send REFs to endnotes +ENDNOTES Output endnotes +EPIGRAPH Epigraph before 1st para +FINIS Prints --END-- +FOOTNOTE Collects footnotes in text for printing at bottom of page +FOOTNOTE_REFS Send REFs to footnotes +HEAD Section title (main heads) +HYPHENATE_REFS Turn on/off hyphenation of REF references +ITEM Begin a list item +LINEBREAK Break between narrative sections +LIST Initialize a list +MN Margin note +MN_INIT Initialize parameters for margin notes +NUMBER_LINES Number text lines +NUMBER_BLOCKQUOTE_LINES Number blockquote lines +NUMBER_QUOTE_LINES Number quote lines +PAD_LIST_DIGITS Leave space for two-numeral digit enumerators + in a list +PARAHEAD Paragraph head +PP Paragraph +QUOTE Poetic or line for line quotes +REF Wrapper around FOOTNOTE or ENDNOTE, depending + on FOOTNOTE_REFS or ENDNOTE_REFS +REF( Begin embedded reference, parens +REF) End embedded reference, parens +REF[ Begin embedded reference, square brackets +REF] End embedded reference, square brackets +REF{ Begin embedded reference, braces +REF} End embedded reference, braces +REF_INDENT Amount of 2nd line indent of references for + footnote, endnote or bibliography refs +RESET_LIST Reset digit or alpha list enumerator +SHIFT_LIST Move a list over to the right +START Sets doc defaults and prints info collected + with doc info macros +SUBHEAD Subheads + +Headers/footers +--------------- +BREAK_QUOTE Manually break a footnoted quote that crosses + a page/column +DO_FOOTER Prints footer (after footnote processing, if any) +FOOTER_ON_FIRST_PAGE Print footer on first page? (boolean) +FOOTER Trap-invoked footer macro +HEADER Trap-invoked header macro +PAGINATE Turns page numbering on or off (doc default=on) +PAGINATE_TOC Turns pagination of toc on or off (default=on) +RECTO_VERSO Enables switch HEADER_LEFT and HEADER_RIGHT on + alternate pages + +Alter doc "look" and/or change defaults +--------------------------------------- +***General*** + +ALWAYS_FULLSPACE_QUOTES Fullspace quotes instead of default + 1/2 spacing them. +ATTRIBUTE_STRING What to print before author (default is "by") +CHAPTER_STRING What to print whenever the word "chapter" + is required +COLUMNS Print in columns +DOC_FAMILY Overall doc family +DOCHEADER Print doc header? +DOCHEADER_ADVANCE Start position of docheader (relative to top + of page) +DOCHEADER_LEAD +|- value applied to #DOC_LEAD to in/decrease + leading of doc header +DOC_LEAD_ADJUST Adjust #DOC_LEAD to fill page to #B_MARGIN +DOC_LEAD Overall doc leading +DOC_LEFT_MARGIN Doc left margin +DOC_LINE_LENGTH Doc line length +DOC_PT_SIZE Overall doc point size +DOC_RIGHT_MARGIN Doc right margin +DOC_TITLE Overall doc title that gets printed in + headers/footers (mostly for use with collated + docs where each doc is an article with a + different title +DRAFT_STRING What to print whenever the word "draft" is + required +DRAFT_WITH_PAGENUMBER Attach draft/revision info to page number + (instead of putting it HEADER centre) +REVISION_STRING What to print whenever the word "revision" + is required + +***Covers*** + +COVER_ADVANCE Vertical place on page to start outputting + cover material +COVER_LEAD Lead in/decrease for cover pages +COVERS_COUNT_PAGES Whether to include cover pages in pagination scheme +DOC_COVER_ADVANCE Vertical place on page to start outputting + doc cover material +DOC_COVER_LEAD Lead in/decrease for doc cover pages +DOC_COVERS_COUNT_PAGES Whether to include doc cover pages in pagination scheme + +***Epigraphs and finis*** + +EPIGRAPH_AUTOLEAD Autolead value for epigraphs +EPIGRAPH_INDENT Value by which to multiply PP_INDENT for + block epigraphs +FINIS_STRING What to print when FINIS is invoked +FINIS_STRING_CAPS Whether to capitalize the finis string + +***Footnotes*** + +FOOTNOTE_AUTOLEAD Autolead to use in footnotes +FOOTNOTE_LINENUMBER_BRACKETS Brackets for footnote linenumbers +FOOTNOTE_LINENUMBER_SEPARATOR Separator for footnote linenumbers +FOOTNOTE_MARKERS Turns footnote markers on or off +FOOTNOTE_MARKER_STYLE STAR or NUMBER; default=STAR +FOOTNOTE_RULE_ADJ # of points to raise footnote rule from its + baseline +FOOTNOTE_RULE_LENGTH Length of footnote separator rule +FOOTNOTE_RULE Turns printing of fn separator rule on or off; + default is on +FOOTNOTE_SPACING Post footnote item spacing +FOOTNOTES_RUN_ON Run footnotes on (line numbering mode only) +RESET_FOOTNOTE_NUMBER Reset fn# to 1, or, if arg PAGE, reset + automatically to 1 on every page +RUNON_WARNING Utility macro; warns if FOOTNOTES_RUN_ON + was called when fn marker style is STAR or NUMBER + +***Endnotes*** + +ENDNOTE_LEAD Leading for endnotes page +ENDNOTE_LINENUMBER_BRACKETS Brackets around line numbers identifying + endnotes and text +ENDNOTE_LINENUMBER_GAP Amount of space to leave between line +ENDNOTE_LINENUMBER_SEPARATOR Separator between line numbers identifying + endnotes and the endnote item text + endnotes and text +ENDNOTE_MARKER_STYLE NUMBER or LINE +ENDNOTE_NUMBERS_ALIGN_RIGHT Hang endnote numbers and align right +ENDNOTE_NUMBERS_ALIGN_LEFT Don't hang endnote numbers and align left +ENDNOTE_PARA_INDENT First line indent of paras in multi-para + endnotes +ENDNOTE_PARA_SPACE Whether to space paras in multi-para endnotes +ENDNOTE_PT_SIZE Base point size for endnotes page +ENDNOTE_STRING Endnotes page head +ENDNOTE_STRING_CAPS Capitalize the endnotes string +ENDNOTE_STRING_UNDERLINE Underscoring of endnotes page head +ENDNOTE_TITLE Endnotes identifying title +ENDNOTE_TITLE_SPACE Distance from top of page to endnotest title +ENDNOTE_TITLE_UNDERLINE Underscoring of endnotes identifying title +ENDNOTES_ALLOWS_HEADERS Page headers on endnotes pages? (boolean) +ENDNOTES_FIRST_PAGENUMBER Page number to appear on page 1 of endnotes + pages +ENDNOTES_HDRFTR_CENTER Print header/footer centre string on endnotes + pages? +ENDNOTES_HEADER_CENTER Print header centre string on endnotes pages? +ENDNOTES_FOOTER_CENTER Print footer centre string on endnotes pages? +ENDNOTES_NO_COLUMNS Turn columnar mode off for endnotes pages +ENDNOTES_NO_FIRST_PAGENUM Don't print a pagenumber on page 1 of + endnotes. +ENDNOTES_PAGENUM_STYLE Set numbering style for endnotes pages page + numbers +SINGLESPACE_ENDNOTES Single space TYPEWRITE endnotes + +***Bibliographies*** + +BIBLIOGRAPHY_ALLOWS_HEADERS Allow headers on bib pages +BIBLIOGRAPHY_FIRST_PAGENUMBER Starting page number for bibliographies +BIBLIOGRAPHY_HDRFTR_CENTER Header/footer center string for bib pages +BIBLIOGRAPHY_LEAD Base lead of bib pages +BIBLIOGRAPHY_NO_COLUMNS De-columnize bibliographies +BIBLIOGRAPHY_NO_FIRST_PAGENUM Don't print a page number on the first + page of bibliographies +BIBLIOGRAPHY_PAGENUM_STYLE Format for bib pages page numbering +BIBLIOGRAPHY_PT_SIZE Base point size for bib pages +BIBLIOGRAPHY_SPACING Post bib entry space +BIBLIOGRAPHY_STRING String for bib title +BIBLIOGRAPHY_STRING_CAPS Capitalize bib title string +BIBLIOGRAPHY_STRING_UNDERLINE Underscore bib title string +SINGLESPACE_BIBLIOGRAPHY Singlespace bibs if PRINTSTYLE TYPEWRITE + +***Headers and footers*** + +FOOTER_COLOR Footer color +FOOTER_GAP Distance between running text and footer +FOOTER_MARGIN Distance from footer to bottom of page +FOOTERS Turns footers on or off +HDRFTR_CENTER String to go in centre part of header/footer; + default doctype +HDRFTR_CENTER_CAPS Centre part of header/footer in caps? (boolean) +HDRFTR_CENTER_PAD Pad hdrftr CENTER left or right by specified + amount +HDRFTR_GAP Distance from header/footer to running text +HDRFTR_LEFT_CAPS Left part of header/footer in caps? (boolean) +HDRFTR_LEFT String to go in left part of header/footer; + default is AUTHOR_1 +HDRFTR_LEFT The header/footer left string +HDRFTR_MARGIN Distance from top of page to header +HDRFTR_PLAIN Header/footer fam/ft/ps all same as running + text +HDRFTR_RECTO User-defined, single string recto + header/footer +HDRFTR_RIGHT_CAPS Right part of header/footer in caps? (boolean) +HDRFTR_RIGHT The header/footer right string +HDRFTR_RULE_GAP Space between header/footer and header/footer + rule +HDRFTR_RULE_INTERNAL Prints the header/footer rule +HDRFTR_RULE Turns header/footer rule on or off + When invoked internally, prints the rule. +HDRFTR_VERSO User-defined, single string verso + header/footer +HEADERS Turns headers on or off +HEADERS_AND_FOOTERS Enables and permits the creation of + headers and footers that appear on the + same page +SWITCH_HDRFTR Switch HDRFTR_LEFT and HDRFTR_RIGHT + +***Page numbering*** + +PAGENUM_HYPHENS Turns on/off hyphens surrounding page numbers +PAGENUM_ON_FIRST_PAGE Print page number on first page when footers + are on (boolean) +PAGENUM_POS Controls placement of page numbers; + default=bottom/centred +PAGENUM_SIZE How much to in/decrease point size of page + numbers* +PAGENUM_STYLE Page # in roman, Arabic, or alphabetic +RESTORE_PAGINATION Restore pagination after outputting non- + paginated endnotes. +SUSPEND_PAGINATION Suspend pagination prior to outputting + endnotes + +***Heads*** + +HEADER_GAP Space between header and running text +HEADER_MARGIN Space from top of page to header +HEAD_CAPS Print section titles in caps? (boolean) +HEAD_SPACE Give HEADs 2 line-spaces before. If OFF, + only 1. Default is on. +HEAD_UNDERLINE Underline section titles? (boolean) +NUMBER_HEADS Print head numbers +RESET_HEAD_NUMBER Reset head number + +***Subheads*** + +NUMBER_SUBHEADS Print subhead numbers +RESET_SUBHEAD_NUMBER Reset subhead number + +***Para heads*** + +NUMBER_PARAHEADS Print parahead numbers +PARAHEAD_INDENT How much to indent paraheads +RESET_PARAHEAD_NUMBER Reset parahead number + +PREFIX_CH_NUM_WARNING Macro to abort PREFIX_CHAPTER_NUMBER + with a warning if the arg to CHAPTER isn't + a digit, and user hasn't supplied a digit + to PREFIX_CHAPTER_NUMBER +PREFIX_CHAPTER_NUMBER Prefix the chapter number to numbered + heads, subheads and paraheads +***Paragraphs*** + +INDENT_FIRST_PARAS Indent 1st paras? (doc default=not indented) +PARA_INDENT Size of para indent +PARA_SPACE Put a line space before paras +PP_FONT Overall doc font + +***Quotes*** + +Q_FITS Utility macro for DO_QUOTE +Q_NOFIT Utility macro for DO_QUOTE +QUOTE_AUTOLEAD Leading of (block)quotes + +***Line/section breaks*** + +LINEBREAK_CHAR Linebreak character, iterations and positioning + +***Printstyle TYPEWRITE*** + +ITALIC_MEANS_ITALIC For TYPEWRITE; render .FT I in italic. +SLANT_MEANS_SLANT In TYPEWRITE, render \*[SLANT] as slant +UNDERLINE_ITALIC In TYPEWRITE, render .FT I as underlined +UNDERLINE_QUOTES In TYPEWRITE, underline quotes? (boolean) +UNDERLINE_SLANT In TYPEWRITE, render \*[SLANT] as underlined + +***Table of contents*** + +TOC_APPENDS_AUTHORS Appends author(s) to toc doc title entries +TOC_LEAD Leading of toc pages +TOC_PADDING Number of placeholders for toc entries page + numbers +TOC_HEAD_INDENT Indent of toc head entries +TOC_HEADER_STRING TOC header string (default=Contents) +TOC_PAGENUM_STYLE Page numbering style (hdrftr nums) of + toc pages +TOC_RV_SWITCH Switch L/R margins of toc pages +TOC_PARAHEAD_INDENT Indent of toc parahead entries +TOC_SUBHEAD_INDENT Indent of toc subhead entries +TOC_TITLE_ENTRY User supplied toc doc title entry +TOC_TITLE_INDENT Indent of toc doc title entries + +***Aliases for headers and footers*** +HEADER_SIZE HDRFTR_SIZE +HEADER_RIGHT_PS HDRFTR_RIGHT_SIZE +HEADER_RIGHT_SIZE HDRFTR_RIGHT_SIZE +HEADER_RIGHT_FAM HDRFTR_RIGHT_FAMILY +HEADER_RIGHT_FAMILY HDRFTR_RIGHT_FAMILY +HEADER_RIGHT_FONT HDRFTR_RIGHT_FONT +HEADER_RIGHT_FT HDRFTR_RIGHT_FONT +HEADER_LEFT_PS HDRFTR_LEFT_SIZE +HEADER_LEFT_SIZE HDRFTR_LEFT_SIZE +HEADER_LEFT_FAM HDRFTR_LEFT_FAMILY +HEADER_LEFT_FAMILY HDRFTR_LEFT_FAMILY +HEADER_LEFT_FONT HDRFTR_LEFT_FONT +HEADER_LEFT_FT HDRFTR_LEFT_FONT +HEADER_CENTRE_PS HDRFTR_CENTER_SIZE +HEADER_CENTRE_SIZE HDRFTR_CENTER_SIZE +HEADER_FAM HDRFTR_FAMILY +HEADER_FAMILY HDRFTR_FAMILY +HEADER_CENTRE_FAM HDRFTR_CENTER_FAMILY +HEADER_CENTRE_FAMILY HDRFTR_CENTER_FAMILY +HEADER_CENTRE_FONT HDRFTR_CENTER_FONT +HEADER_CENTRE_FT HDRFTR_CENTER_FONT +HEADER_CENTER_PS HDRFTR_CENTER_SIZE +HEADER_CENTER_SIZE HDRFTR_CENTER_SIZE +HEADER_CENTER_FAM HDRFTR_CENTER_FAMILY +HEADER_CENTER_FAMILY HDRFTR_CENTER_FAMILY +HEADER_CENTER_FONT HDRFTR_CENTER_FONT +HEADER_CENTER_FT HDRFTR_CENTER_FONT +FOOTER_SIZE HDRFTR_SIZE +FOOTER_RIGHT_PS HDRFTR_RIGHT_SIZE +FOOTER_RIGHT_SIZE HDRFTR_RIGHT_SIZE +FOOTER_RIGHT_FAM HDRFTR_RIGHT_FAMILY +FOOTER_RIGHT_FAMILY HDRFTR_RIGHT_FAMILY +FOOTER_RIGHT_FONT HDRFTR_RIGHT_FONT +FOOTER_RIGHT_FT HDRFTR_RIGHT_FONT +FOOTER_LEFT_PS HDRFTR_LEFT_SIZE +FOOTER_LEFT_SIZE HDRFTR_LEFT_SIZE +FOOTER_LEFT_FAM HDRFTR_LEFT_FAMILY +FOOTER_LEFT_FAMILY HDRFTR_LEFT_FAMILY +FOOTER_LEFT_FONT HDRFTR_LEFT_FONT +FOOTER_LEFT_FT HDRFTR_LEFT_FONT +FOOTER_CENTRE_PS HDRFTR_CENTER_SIZE +FOOTER_CENTRE_SIZE HDRFTR_CENTER_SIZE +FOOTER_FAM HDRFTR_FAMILY +FOOTER_FAMILY HDRFTR_FAMILY +FOOTER_CENTRE_FAM HDRFTR_CENTER_FAMILY +FOOTER_CENTRE_FAMILY HDRFTR_CENTER_FAMILY +FOOTER_CENTRE_FT HDRFTR_CENTER_FONT +FOOTER_CENTER_PS HDRFTR_CENTER_SIZE +FOOTER_CENTER_SIZE HDRFTR_CENTER_SIZE +FOOTER_CENTER_FAM HDRFTR_CENTER_FAMILY +FOOTER_CENTER_FAMILY HDRFTR_CENTER_FAMILY +FOOTER_CENTER_FONT HDRFTR_CENTER_FONT +FOOTER_CENTER_FT HDRFTR_CENTER_FONT + + *relative to #DOC_PT_SIZE + **relative to overall ps of headers as set by HEADER_SIZE + ***relative to overall ps of endnotes pages +****relative to overall ps of toc pages + ++++LETTER MACROS+++ + +CLOSING Closing (i.e. Yours truly,) +DATE Date for letters +FROM Addresser's name and address +GREETING Full salutation (e.g. Dear John Smith,) +NO_SUITE Remove suite page numbers from bottom of letter pages +TO Addressee's name and address +ALL_DONE .em (the "end macro") for letters + ++++SUPPORT+++ + +CHECK_INDENT Applies indents to doc elements inside ev's + (head, subhead, etc) +CLEANUP_DEFAULTS Removes selected rregisters and strings + from DEFAULTS after START +DO_COVER Formats and outputs covers +DO_DOC_COVER Formats and outputs doc covers +D0_QUOTE Outputs quotes with space adjustments before + and after +DIVER_FN_1_PRE -+ +DIVER_FN_2_PRE | Manage footnotes called inside diversions + | QUOTE, BLOCKQUOTE and EPIGRAPH +DIVER_FN_2_POST -+ +DIVERT_FN_LEFTOVER Diverts excess fn stored in FN_OVERFLOW into + FOOTNOTE +DIVERT_FN_OVERFLOW Diverts excess fn stored in FN_OVERFLOW when + FN_DEFER into FOOTNOTE +DO_EPIGRAPH Outputs epigraphs with space adjustments before + and after +FN_OVERFLOW_TRAP Fixed at B_MARGIN; if footnotes run longer than + B_MARGIN, diverts excess into FN_OVERFLOW +GET_ROMAN_INDENT Figures out amount of space to reserve + for roman numerals in lists +HDRFTR_RULE Prints rule under header or over footer +MN_OVERFLOW_TRAP Trap-invoked macro to collect margin note + overflows +NO_SHIM Disable SHIM +PRINT_FOOTNOTE_RULE An alias of PRINT_FOOTNOTE; prints footnote + separator rule +PRINT_HDRFTR Prints header/footer (trap invoked) +PRINT_PAGE_NUMBER Invoked in HEADER or FOOTER +PRINT_USERDEF_HDRFTR Prints user defined, single string recto/verso + header/footer +PROCESS_SHIM Calculates #SHIM when \n(.d is lower on the + page than #T_MARGIN +PROCESS_FN_IN_DIVER Processes footnotes gathered in a diversion (called + at page/column breaks) +REMOVE_INDENT Removes indents set with CHECK_INDENT +Q_FITS Handles spacing of quotes when quote fits on the page +Q_NOFIT Handles spacing of quotes when quote does not fit on + the page +QUIT_LISTS Exit lists cleanly and completely +SET_LIST_INDENT Restore indent of a prev. level of list +SHIM Advance to next "valid" baseline +TERMINATE .em that ensures deferred footnotes get output + on final pages +TRAPS Sets hdrftr traps; optionally adjusts #DOC_LEAD + to fill page to #B_MARGIN +TYPEWRITER Sets family (C), font (R) and point size (12) + for PRINTSTYLE TYPEWRITE +VFP_CHECK Trap-sprung macro 1 valid baseline higher than + where FOOTER will be sprung; checks whether + there is, in fact, just enough room for + another line of running text to be added to + the page without jamming footnotes too close + to running text. + ++++DIVERSIONS+++ + +B_QUOTE Block (indented) quote text +CLOSING Closing (i.e. Yours truly,) +EPI_TEXT Epigraph text +END_NOTES Endnotes text +FN_IN_DIVER Footnotes gathered from inside a diversion +FN_OVERFLOW Excess footnotes when B_MARGIN is reached +FOOTNOTES Text of footnotes +GREETING Full salutation (e.g. Dear John Smith,) +LETTERHEAD<n> Date, addresser, addressee or greeting; + <n> is from 1 to 4, supplied by #FIELD +P_QUOTE Line for line (poetic) quote text +RUNON_FOOTNOTES Special diversion for run-on footnotes +RUNON_FN_IN_DIVER Special diversion for run-on footnotes inside + (block)quotes +TOC_ENTRIES TOC entries + ++++NUMBER REGISTERS+++ + +#ADJ_BIB_LEAD Adjust BIB_LEAD? (boolean) +#ADJ_DOC_LEAD Adjust DOC_LEAD? (boolean) +#ADJ_EN_LEAD Adjust EN_LEAD? (boolean) +#ADJ_TOC_LEAD Adjust TOC_LEAD? (boolean) +#ADVANCE_FROM_TOP Distance from page top to start of + running text if no docheader +#ARG_NUM Keeps track of number of args passed to a + macro +#ARGS_TO_LIST Was LIST passed some args? (boolean) +#ATTRIBUTE_COLOR Colorize attribute string? (boolean) +#AUTHOR_<n> Strings passed to AUTHOR +#AUTHOR_COLOR Colorize author(s)? (boolean) +#AUTHOR_COVER_NUM Incrementing register used in definining + $AUTHOR_COVER_<n> strings +#AUTHOR_DOCCOVER_NUM Incrementing register used in definining + $AUTHOR_COVER_<n> strings +#AUTHOR_NUM Keeps track of user-defined string + AUTHOR_<n> in AUTHOR +#AUTHORS Equals final value of AUTHOR_NUM; + used for authors in doc header +#BASELINE_MARK In PP, the vertical position on the page + (when paragraph spacing is on) after a + quote or blockquote has been output and + the post-quote space has been added. +#BMARG Position of unvarying bottom margin + during doc processing; required for + collecting footnotes inside diversions +#BIB_ALLOWS_HEADERS Put headers on bib pages? (boolean) +#BIB_ALLOWS_HEADERS_ALL Put headers on all bib pages? (boolean) +#BIB_FIRST_PAGE Tells PRINT_PAGE_NUMBER about bibliography + first page number +#BIB_FIRST_PN Starting pagenumber for bibliographies +#BIB_HDRFTR_CENTER Put a center string in bib page headers? + (boolean) +#BIB_LEAD Bibliography lead, expressed in points +#BIB_LIST Output bibs in list style? (boolean) +#BIB_NO_COLS De-columnize bibliographies? (boolean) +#BIB_NO_FIRST_PN Put a page number on the first page of + bibliographies? (boolean) +#BIB_SINGLESPACE Single-space TYPEWRITE bibliographies? (boolean) +#BIB_SPACE Post item space for bibliography pages +#BIB_STRING_CAPS Capitalize bib title? (boolean) +#BIB_STRING_UNDERLINE Underscore bib title? 0=no; 1=yes; 2=double +#BIB_STRING_UNDERLINE_WEIGHT Underline weight in units +#BIB_STRING_UNDERLINE_WEIGHT_ADJ Underline weight/2 +#BIB_PS Base point size for bibliography pages expressed + in points +#BIBLIOGRAPHY Are we doing a bib page? (boolean) +#BQ_AUTOLEAD Register created by BLOCKQUOTE_AUTOLEAD +#BQ_LEAD Leading of blockquotes +#BQUOTE_COLOR Colorize blockquotes? (boolean) +#BQUOTE_LN Number blockquotes? (boolean) +#BROKEN_QUOTE Did we invoke BREAK_QUOTE? (boolean) +#CAP_HEIGHT_ADJUST Tallest cap height of strings LEFT, CENTER, + and RIGHT in footers; used to place rule + over footer +#CAPS_WAS_ON In HDRFTR, to re-enable running text CAPS + (boolean) +#CENTER_CAP_HEIGHT Cap height of CENTER string in + headers/footers +#CH_NUM The chapter number obtained by PREFIX_CHAPTER_NUMBER +#CHAPTER_CALLED Has CHAPTER been invoked? (boolean); used + by PREFIX_CHAPTER_NUMBER to see whether + to try to get the chapter number from + the arg passed to CHAPTER +#CHAPTER_TITLE_NUM Incrementing register used to define strings + $CHAPTER_TITLE_<n> +#CHAPTER_TITLE_COLOR Colorize chapter title? (boolean) +#CLOSING Is there a closing (for letters)? (boolean) +#COL_L_LENGTH Line length of columns +#COL_<n>_L_MARGIN Left margin of column <n> +#COL_NEXT Was COL_NEXT invoked? (boolean; used in + FOOTER) +#COL_NUM Incrementing counter of num of columns; + for use with #COL_<n>_L_MARGIN +#COL_TOTAL #COL_L_LENGTH + #GUTTER; used to calculate + #COL_<n>_L_MARGIN +#COLLATE Are we performing a COLLATE? (boolean) +#COLLATED_DOC If 1, instructs TOC that this is a collated + doc +#COLUMNS Are columns turned on? (boolean) +#COLUMNS_WERE_ON Stores columnar state prior to outputting + endnotes in no-columns mode +#COPY_STYLE 1=draft, 2=final +#COUNTERS_RESET Tells FOOTNOTE if fn counters have + been reset because of footnotes gathered + inside a diversion +#COVER Print a COVER? (boolean) +#COVER_ATTRIBUTE_COLOR Colorize cover attribution string? (boolean) +#COVER_AUTHOR Put AUTHOR(s) on COVER? (boolean) +#COVER_AUTHOR_COLOR Colorize cover author(s)? (boolean) +#COVER_BLANKPAGE Output blankpage after COVER? (boolean) +#COVER_COLOR Colorize COVER? (boolean) +#COVER_COPYRIGHT Put copyright on COVER? (boolean) +#COVER_COPYRIGHT_COLOR Colorize cover copyright line? (boolean) +#COVER_DOCTYPE Put doctype on COVER? (boolean) +#COVER_DOCTYPE_COLOR Colorize cover doctype? (boolean) +#COVER_END Are we ending a COVER? (boolean) +#COVER_LEAD Cover leading +#COVER_MISC Put misc on COVER? (boolean) +#COVER_MISC_COLOR Colorize cover misc line? (boolean) +#COVER_RULE_WEIGHT Doctype underline weight on COVER +#COVER_RULE_WEIGHT_ADJ COVER_RULE_WEIGHT/2 +#COVER_START_POS Vertical starting pos of cover material +#COVER_SUBTITLE Put subtitle on COVER? (boolean) +#COVER_TITLE Put title on COVER? (boolean) +#COVER_TITLE_NUM Number of cover title items +#COVER_TITLE_COLOR Colorize cover title? (boolean) +#COVER_SUBTITLE_COLOR Colorize cover subtitle? (boolean) +#COVER_UNDERLINE Underline doctype on COVER? (boolean) +#COVER_UNDERLINE_WEIGHT Doctype underline weight on COVER +#COVER_UNDERLINE_WEIGHT_ADJ COVER_UNDERLINE_WEIGHT/2 +#CURRENT_V_POS \n(.d ; used in SHIM +#COVERS Print covers? (boolean) +#COVERS_COUNT Include COVER in pagination scheme? (boolean) +#COVERS_OFF Don't print COVERs (boolean) +#DATE_FIRST Was .DATE invoked as first letter + header after .START? (boolean) +dc "mark" register for document columns +#DIVER_FN Register that tells FOOTNOTE whether to + "move" or "defer" a footnote collected + inside a diversion +#DEFER_BIB_SPACING Tells DEFAULTS to do BIBLIOGRAPHY_SPACING + if it was called before START +#DEFER_PAGINATION Tells COLLATE to restore pagination (from + RESTORE_PAGINATION +#DEFER_SPACE_ADDED Was space added between two "first" footnotes that + appear on the same page? (boolean) +#DELAY_SHIM Instructs DO_QUOTE to delay SHIM when quote + falls at the top of a page +#DEPTH LIST depth +#DEPTH_1 Doc header depth with lead adjustment + (#DOCHEADER_LINES * #DOCHEADER_LEAD) +#DEPTH_2 Doc header depth without lead adjustment + (#DOCHEADER_LINES * #DOC_LEAD) +#DEPTH_TO_B_MARGIN Page length minus #B_MARGIN +#DIVERSIONS_HY_MARGIN A reasonable value for .hym applied to + QUOTE, BLOCKQUOTE and EPIGRAPH to + avoid excessive hyphenation if these are + set quad left +#DIVERTED Set to 1 in DIVERT_FN_OVERFLOW; reset + subsequently in FOOTNOTES when called by + PROCESS_FN_LEFTOVER to 2 or 3 for use by + FOOTER to decide whether to in/decrease + #FN_DEPTH when outputting footnotes +#DOC_COVER Are we doing a DOC_COVER? (boolean) +#DOC_COVER_AUTHOR Put AUTHOR(s) on DOC_COVER? (boolean) +#DOCCOVER_BLANKPAGE Output blank page after DOC_COVER? (boolean) +#DOC_COVER_CHAPTER_TITLE_COLOR Colorize CHAPTER_TITLE on DOC_COVER? (boolean) +#DOC_COVER_COPYRIGHT Put copyright on DOC_COVER? (boolean) +#DOC_COVER_DOCTYPE Put doctype on DOC_COVER? (boolean) +#DOCCOVER_END Are we finishing a DOC_COVER? (boolean) +#DOC_COVER_LEAD Doc cover leading +#DOC_COVER_MISC Put misc on DOC_COVER? (boolean) +#DOC_COVER_START_POS Vertical starting pos of doc cover material +#DOC_COVER_COLOR Colorize cover? (boolean) +#DOC_COVER_START_POS Vertical starting pos of cover material +#DOC_COVER_TITLE_COLOR Colorize doc cover title? (boolean) +#DOC_COVER_SUBTITLE_COLOR Colorize doc cover subtitle? (boolean) +#DOC_COVER_ATTRIBUTE_COLOR Colorize doc cover attribution string? (boolean) +#DOC_COVER_AUTHOR_COLOR Colorize doc cover author(s)? (boolean) +#DOC_COVER_DOCTYPE_COLOR Colorize doc cover doctype? (boolean) +#DOC_COVER_COPYRIGHT_COLOR Colorize doc cover copyright line? (boolean) +#DOC_COVER_MISC_COLOR Colorize doc cover misc line? (boolean) +#DOC_COVER_SUBTITLE Put subtitle on DOC_COVER? (boolean) +#DOC_COVER_TITLE Put title on DOC_COVER? (boolean) +#DOC_COVER_TITLE_NUM Number of doc cover title items +#DOC_COVERS Print doc covers? (boolean) +#DOC_COVERS_OFF Don't print DOC_COVERs (boolean) +#DOCCOVER_RULE_WEIGHT Doctype underline weight on DOC_COVER +#DOCCOVER_RULE_WEIGHT_ADJ DOCCOVER_RULE_WEIGHT/2 +#DOCCOVER_UNDERLINE Underline doctype on DOC_COVER? (boolean) +#DOCCOVER_UNDERLINE_WEIGHT Doctype underline weight on DOC_COVER +#DOCCOVER_UNDERLINE_WEIGHT_ADJ DOCCOVER_UNDERLINE_WEIGHT/2 +#DOCCOVERS_COUNT Include DOC_COVER in pagination scheme? (boolean) +#DOC_HEADER Whether to print a doc header (boolean) +#DOC_LEAD_ADJ Incrementing value (in units) added to + #DOC_LEAD to fill page to #B_MARGIN +#DOC_LEAD Leading used in body +#DOC_L_LENGTH Global L_LENGTH +#DOC_L_MARGIN Global L_MARGIN +#DOC_LR_MARGIN_TMP In HEADER, if RECTO_VERSO=1, temporarily + holds DOC_L_MARGIN during page margin switch +#DOC_PT_SIZE Point size used for body text +#DOC_R_MARGIN Global R_MARGIN +#DOC_TYPE 1=default, 2=chapter, 3=named, 4=letter +#DOCHEADER_ADVANCE Distance from top-of-page to baseline of + docheader +#DOCHEADER_COLOR Colorize docheader? (boolean) +#DOCHEADER_DEPTH Depth of docheader +#DOCHEADER_LEAD Lead of doc header + (#DOC_LEAD + #DOCHEADER_LEAD_ADJ) +#DOC_LEAD_ADJUST_OFF Don't adjust DOC_LEAD (boolean) +#DOCS Always 1 after START +#DOCTITLE_NUM Number of doctitle items +#DOCTYPE_COLOR Colorize doctype? (boolean) +#DOCTYPE_RULE_WEIGHT Doctype underline weight +#DOCTYPE_RULE_WEIGHT_ADJ DOCTYPE_RULE_WEIGHT/2 +#DOCTYPE_UNDERLINE Underline doctype? (boolean) +#DOCTYPE_UNDERLINE_WEIGHT Weight of doctype underline +#DOCTYPE_UNDERLINE_WEIGHT_ADJ DOCTYPE_UNDERLINE_WEIGHT/2 +#DOING_COVER Tells PRINT_AUTHORS that it's printing + the authors for a cover or doc cover +#DONE_ONCE Keeps track of how many times footnotes + have been collected inside the same diversion +#DONT_RULE_ME Rule this (apparent) first footnote? (boolean) +#DIVER_LN_OFF Turn linenumbering off in (block)quotes? + (boolean) +#DRAFT_WITH_PAGENUM Are we attaching draft/revision info to page + number? (boolean) +#EM_ADJUST Amount to raise \(em at END +#EN_ALLOWS_HEADERS Put page headers on endnotes pages? (boolean) +#EN_ALLOWS_HEADERS_ALL Put page headers on all endnotes pages? + (boolean) +#EN_BQ_AUTOLEAD Register created by EN_BLOCKQUOTE_AUTOLEAD +#EN_BQ_LEAD Leading of blockquotes on endnotes pages +#EN_FIGURE_SPACE Width of \0, for use with formatting endnotes +#EN_FIRST_PAGE Tells PRINT_PAGE_NUMBER about endnotes + first page number +#EN_FIRST_PN Page number that appears on page 1 of + endnotes pages. +#EN_HDRFTR_CENTER Should we print centre string of + headers/footers on endnotes pages? (boolean) +#EN_LEAD Lead of endnotes +#EN_LN_BRACKETS Are we using brackets for line-numbered + endnotes (boolean) +#EN_LN_SEP Are we using a separator for line-numbered + endnotes (boolean) +#EN_MARK \n(ln when \*[EN-MARK] is called +#EN_MARK_2 \n(ln when ENDNOTE is called +#EN_MARKER_STYLE 1=NUMBER; 2=LINE +#EN_NO_COLS Do not set endnotes in columns? (boolean) +#EN_NO_FIRST_PN Put pagenumber on 1st page of endnotes? + (boolean) +#EN_NUMBER Number of current endnote +#EN_NUMBER_PLACEHOLDERS Number of placeholders to reserver for endnotes numbers +#EN_NUMBERS_ALIGN_RIGHT Hang and align endnote numbers right? + (boolean) +#EN_NUMBERS_ALIGN_LEFT Align endnote numbers with left margin? + (boolean) +#EN_NUMBERS_PLACEHOLDERS Number of placeholders when endnote numbers + hang and align right +#EN_NUMBER_L_LENGTH Line length for endnote numbers when they're + right aligned +#EN_PP_INDENT First line indent of paras in multi-para + endnotes +#EN_PP_SPACE Space multi-paras in endnotes? (boolean) +#EN_PS ps of endnotes +#EN_Q_AUTOLEAD Register created by EN_QUOTE_AUTOLEAD +#EN_Q_LEAD Leading of quotes on endnotes pages +#EN_REF Put REFs in endnotes? (boolean) +#EN_SINGLESPACE Single space endnotes pages? (boolean) +#EN_STRING_ADVANCE Vertical position of "ENDNOTES" string (relative to + the top edge of the page) +#EN_STRING_CAPS Should ENDNOTES capitalize the endnotes + string? (boolean) +#EN_STRING_UNDERLINE Underscore endnotes page head? (boolean) +#EN_STRING_UNDERLINE_WEIGHT Weight of endnotes page title underscore +#EN_STRING_UNDERLINE_WEIGHT_ADJ EN_STRING_UNDERLINE_WEIGHT_ADJ/2 +#EN_TEXT_INDENT Page offset for text of endnotes when + numbers right align +#EN_TITLE_UNDERLINE Underscore endnotes document identifier? + (boolean) +#EN_TITLE_UNDERLINE_WEIGHT Weight of endnotes document identification underscore +#EN_TITLE_UNDERLINE_WEIGHT_ADJ EN_STRING_UNDERLINE_WEIGHT_ADJ/2 +#END_QUOTE For PP=0 indenting; did we just end a quote? + (boolean) +#ENDNOTE Are we in an endnote? (boolean) +#ENDNOTE_REFS Are REFs going to endnotes? (boolean) +#ENDNOTES Are we in an endnote (for FOOTERs; boolean) +#EPI_ACTIVE Are we in an epigraph? (boolean) +#EPI_AUTOLEAD Autolead value for epigraphs +#EPI_COLOR Colorize epigraphs? (boolean) +#EPI_DEPTH Depth of epigraph from first baseline to + last +#EPI_FITS Does epigraph fit on page/column? (boolean) +#EPIGRAPH Did we have an epigraph? (boolean) +#EPI_LEAD_DIFF Difference between #DOC_LEAD and #EPI_LEAD +#EPI_LEAD Leading of epigraph; set by AUTOLEAD +#EPI_LINES_EVEN Even # of lines at end of epi crossing page in + TYPEWRITE (d-spaced)? +#EPI_LINES Number of lines in the epigraph +#EPI_LINES_TO_END Number of epigraph lines remaining after + footer trap is sprung +#EPI_LINES_TO_TRAP Number of epigraph lines till footer trap is + sprung +#EPI_L_LENGTH Epigraph line length +#EPI_OFFSET Left margin of epigraphs +#EPI_OFFSET_VALUE Epigraph indent as a function of page offset +#EPI_ON Are we in an epigraph? (boolean) +#EPI_WHITESPACE Space after epigraph to compensate for + epigraph leading +#FIELD Incrementing register tacked onto LETTERHEAD +#FINIS Was FINIS invoked? (boolean) +#FINIS_STRING_CAPS Capitalize finis string? (boolean) +#FINIS_COLOR Colorize FINIS? (boolean) +#FIRST_DOC_TITLE_PN Page number of 1st (collated) doc (for TOC) +#FIRST_DOC_TOC_PN_PADDING Padding for 1st page number of 1st (collated) doc (for TOC) +#FN_AUTOLEAD Autolead value of footnotes +#FN_BL_INDENT Left indent of INDENT BOTH in footnotes +#FN_BR_INDENT Right indent of INDENT BOTH in footnotes +#FN_COUNT Which fn marker to print; also to + tell mom to reserve space for and print + the rule above footnotes +#FN_COUNT_AT_FOOTER The FN_COUNT after FOOTNOTES has been + output in FOOTER +#FN_COUNT_FOR_COLS Holds a separate footnote count for columns + (so they don't reset to 0 1 until page break) +#FN_DEFER Defer footnote to next page/column? (boolean) + If 0, don't defer. +#FN_DEFER_SPACE Whether to deposit space before + footnote 1 because there's a deferred + footnote on the page +#FN_DEPTH Depth of footnote diversion(s) +#FN_FOR_EPI Signals to epigraph that a footnote is being + processed +#FN_GAP When there are footnotes on a page, the + difference between where FOOTER will be + sprung and the next valid baseline. + Used in VFP_CHECK. +#FN_LEAD Lead in footnotes after FN_AUTOLEAD is + applied +#FN_L_INDENT Left indent of INDENT LEFT in footnotes +#FN_LINES Number of lines in fn; used to calculate + fn depth +#FN_LN_BRACKETS Are footnote linenumber brackets being used? + (boolean) +#FN_LN_SEP Is a footnote linenumber separator being used? + (boolean) +#FN_MARK \n(ln when \*[FN-MARK] is called +#FN_MARK_2 \n(nl when FOOTNOTE is called +#FN_MARKER_STYLE 1=STAR; 2=NUMBER +#FN_MARKERS Print footnote markers? (boolean) +#FN_NUMBER The footnote number attached to running text + (and fns) when numbers instead of + star/dagger is being used for footnootes + numbers +#FN_OVERFLOW_DEPTH Depth of leftover from footnote processing +#FN_OVERFLOW_TRAP_POS The register that sets the position of + trap FN_OVERFLOW_TRAP. +#FN_R_INDENT Right indent of INDENT RIGHT in footnotes +#FN_REF Put REFs in footnotes? (boolean) +#FN_RULE Print fn rule? (boolean) +#FN_RULE_ADJ # of points to raise footnote separator from + its baseline +#FN_RULE_LENGTH Length of footnote separator rule +#FN_RULE_WEIGHT Weight of the footnote separator rule +#FN_RULE_WEIGHT_ADJ FN_RULE_WEIGHT/2 +#FN_SPACE Post footnote space +#FN_WAS_DEFERED Tells HEADER about a deferred footnote +#FOOTER_DIFF In TRAPS, the difference between the + original #B_MARGIN and #VISUAL_B_MARGIN +#FOOTER_GAP Amount of space between end of text and + page # +#FOOTER_MARGIN Amount of space between page # and bottom + of page +#FOOTER_POS Position of footer trap (required for + collecting footnotes inside a diversion) +#FOOTER_RULE Print footer rule? (boolean) +#FOOTER_RULE_GAP Gap between footer and separator rule above +#FOOTER_RULE_WEIGHT Weight of footer rule +#FOOTER_RULE_WEIGHT_ADJ #FOOTER_RULE_WEIGHT/2 +#FOOTERS_ON Are we using footers? (boolean) +#FOOTERS_WERE_ON Were footers on? - used in FINIS and BLANKPAGE + (boolean) +#FOOTNOTE_COLOR Colorize footnotes? (boolean) +#FROM_BIB_STRING Tells UNDERSCORE it's underscoring $BIB_STRING +#FROM_COVER Tells UNDERSCORE it's underscoring on a cover +#FROM_DOC_COVER Tells UNDERSCORE it's underscoring on a doccover +#FROM_DOCTYPE Tells UNDERSCORE it's underscoring the doctype +#FROM_EN_STRING Tells UNDERSCORE it's underscoring $EN_STRING +#FROM_EN_TITLE Tells UNDERSCORE it's underscoring $EN_TITLE +#FROM_HEAD Tells UNDERSCORE it's underscoring a head +#FROM_DIVERT_FN Signals to FOOTNOTE, when run from + within DIVERT_FN_LEFTOVER, to set #SPACE_REMAINING + to the total area allowable for running text +#FROM_FOOTER In col to col footnote processing, tells + FOOTNOTE that FOOTNOTES was output from + FOOTER. +#FROM_HEADER In col to col footnote processing, tells + FOOTNOTE that FOOTNOTES was output from + HEADER. +#FULLSPACE_QUOTES Should we fullspace quotes? (boolean) +#GET_DC_HEIGHT Used in routine to get the correct point size for dropcaps +#GET_DEPTH Signals to FOOTNOTE that it should + measure the depth of current footnotes + plus the most recently added one, except + where the footnote is to be deferred to + the next page or column +#GUTTER Width of gutter between columns +#HDRFTR_BOTH Are we setting both headers and footers? (boolean) +#HDRFTR_CENTER_CAPS CENTER part of header/footer in caps? + (boolean; default=off) +#HDRFTR_CENTER_COLOR Colorize header/footer center? (boolean) +#HDRFTR_COLOR Colorize headers/footers? (boolean) +#HDRFTR_CTR_PAD_LEFT Amount of hdrftr CENTER padding on the left +#HDRFTR_CTR_PAD_RIGHT Amount of hdrftr CENTER padding on the right +#HDRFTR_CTR_PAD_TMP Temp storage of left hdrftr CENTER padding + (for recto/verso switch) +#HDRFTR_HEIGHT Cap height of $HDRFTR_RECTO/$HDRFTR_VERSO + strings +#HDRFTR_LEFT_CAPS Left part of header/footer in caps? + (boolean; default=off) +#HDRFTR_LEFT_COLOR Colorize header/footer left? (boolean) +#HDRFTR_PT_SIZE Initial point size of headers/footers +#HDRFTR_RIGHT_CAPS Right part of header/footer in caps? + (boolean; default=on) +#HDRFTR_RIGHT_COLOR Colorize header/footer right? (boolean) +#HDRFTR_RULE Print head/footer rule? (boolean) +#HDRFTR_RULE_COLOR Colorize header/footer rule? (boolean) +#HDRFTR_RULE_GAP Space between header/footer and + header/footer rule +#HDRFTR_RULE_WEIGHT Weight of header/footer rule +#HDRFTR_RULE_WEIGHT_ADJ HDRFTR_RULE_WEIGHT/2 +#HDRFTR_TMP_CAPS_SWITCH Temporarily holds HDRFTR_LEFT_CAPS value if + #SWITCH_HDRFTR=1 +#HEAD 1=main/section head 2=subhead +#HEAD_CAPS Print section titles in caps? (boolean) +#HEAD_COLOR Colorize heads? (boolean) +#HEADER_GAP Distance from header to running text +#HEAD_NUM Head number +#HEAD_SPACE 2 line spaces before heads? (boolean) +#HEAD_UNDERLINE Underline heads? (boolean) +#HEAD_UNDERLINE_WEIGHT Head underline weight +#HEAD_UNDERLINE_WEIGHT_ADJ HEAD_UNDERLINE_WEIGHT/2 +#HEADER_MARGIN Distance from top of page to header +#HEADER_RULE Print header rule? (boolean) +#HEADER_RULE_GAP Gap between header and header rule +#HEADER_RULE_WEIGHT Header rule weight +#HEADER_RULE_WEIGHT_ADJ HEADER_RULE_WEIGHT/2 +#HEADERS_ON Headers on? (boolean) +#HEADER_STATE Saves header state in COLLATE for use in + START after COLLATE +#HEADERS_WERE_ON Were headers on? - used in BLANKPAGE (boolean) +#HF_OFF Has HEADERS_AND_FOOTERS been turned off? (boolean) +#HORIZ_MARK Horizontal +#HOW_MANY Number of blank pages to output +#IGNORE Should we ignore this macro? Set to 1 in + TYPEWRITE. +#IN_BIB_LIST Tells ITEM we're doing a bibliography in + list style +#INDENT_FIRST_PARAS Indent first paras? (boolean) +#INDENT_FIRSTS Tells footnotes to leave INDENT_FIRST_PARAS + alone if it's on for running text. +#ITALIC_MEANS_ITALIC For TYPEWRITE. (boolean) +#ITEM Counter for removing _1, _2, _3... strings + in TITLE, CHAPTER_TITLE, etc. +#L_LENGTH_FOR_EPI Stores line length at top of doc for use + with EPIGRAPH when columns are on +#L_MARGIN_DIFF Difference between DOC_L_MARGIN and + L_MARGIN +#LEFT_CAP_HEIGHT Cap height of left string in headers/footers +#VALID_BASELINE Calculates vert. position of next valid + baseline in SHIM +#LETTER_STYLE 1=BUSINESS 2=PERSONAL +#LINEBREAK Did we have a linebreak? (boolean) +#LINEBREAK_COLOR Colorize linebreak? (boolean) +#LINENUMBER_COLOR Colorize linenumbers? (boolean) +#LINENUMBERS Holds various states of line-numbering when + line numbering is enabled +#LINES_PER_PAGE # of lines (at DOC_LEAD) that fit on + page after #B_MARGIN is set +#LN Are line numbers on? (boolean) +MN-active Are we doing a margin note? (boolean) +MN-curr Current margin note +MN-div-<n>-depth Depth of margin note <n> +MN-hy Hyphenation flag of margin notes +#MNinit Have margin notes been initialized? (boolean) +#MNinit_DEFERRED Did we have to defer a margin note? (boolean) +MN-last-pos Baseline of previous margin note +MN-lead-adj Difference between the current DOC_LEAD and the + leading used in margin notes +MN-left Number of current left margin note +MN-left-start Horizontal start position of left margin note +MN-left-width Width of left margin note +MN-right Number of current right margin note +MN-right-start Horizontal start position of right margin note +MN-right-width Width of right margin note +MN-sep Gutter between margin notes and running text +MN-shifted Did we have to shift a margin note down? (boolean) +MN-size Point size of margin notes +MN-spacing Leading of margin notes +#MISC_<n> Used to print "next" misc lines in DO_COVER +#MISC_COVER_NUM Number of cover misc items +#MISC_DOCCOVER_NUM Number od doc cover misc items +#MISC_NUM Number of MISC items +#MISCS =#MISC_NUM in DO_COVER +#MN_OVERFLOW_LEFT If 1, left margin note text overflows +#MN_OVERFLOW_RIGHT If 1, right margin note text overflows +#n%_AT_PAGENUM_SET Page # from n% when PAGENUMBER invoked +#NEEDS_SPACE Instruct FOOTNOTE, when called by + PROCESS_FN_IN_DIVER, that if the footnote + had to be deferred, the VFP must be + raised by 1v (set in DIVER_FN_2_PRE) +#NEITHER Should we print no covers? (boolean) +#NEXT_AUTHOR Supplies correct digit to AUTHOR_<n> + when printing authors in doc header +#NEXT_LN Next linenumber when \n(ln has to be stored + because linenumbering suspended +#NEXT_MISC Incrementing counter for misc lines in + DO_COVER +#NEXT_SUBTITLE Incrementing register used to print subtitles +#no-repeat-MN-left Don't repeat left margin note (boolean) +#no-repeat-MN-right Don't repeat right margin note (boolean) +#NO_BACK_UP Instructs FN_OVERFLOW_TRAP not to + subtract 1 line of footnote lead from + FN_OVERFLOW in a PREV_FN_DEFERRED + situation. +#NO_BREAK Set to 1 in COLLATE if last line of + text before COLLATE falls at the bottom + of the page; instructs NEWPAGE to use + 'br instead of .br +#NO_COLUMNS Don't print document in columns (boolean) +#NO_FN_MARKER Don't print footnote markers (boolean) +#NO_SHIM Should SHIM shim? (boolean) +#NO_SPACE When para spacing is active, instructs + PP not to add space after a quote or blockquote. +#NO_TRAP_RESET Should we reset page traps? (boolean) +#NOT_YET_ADJUSTED Line on which a footnote was called has not yet + been adjusted by groff (boolean) +#NUM_AUTHORS # of authors mod 2 to test if odd or even + # of authors +#NUM_MISCS Number of args passed to MISC +#NUM_MISCS_COVER Number of args passed to MISC COVER +#NUM_MISCS_DOCCOVER Number of args passed to MISC DOC_COVER +#NUMBER_HEAD Are heads numbered? (boolean) +#NUMBER_PH Are paraheads numbered? (boolean) +#NUMBER_SH Are subheads numbered? (boolean) +#NUM_COLS Number of columns per page +#NUMBERED If set to 1, lets PARAHEAD know that + main- and subhead numbers have already been prefixed + to the parahead string +#NUM_FIELDS Incrementing register used to match + #TOTAL_FIELDS +#OK_PROCESS_LEAD Initial processing of TOC and endnote + leading is deferred until OK_PROCESS_LEAD=1 +#ORIGINAL_B_MARGIN The value for #B_MARGIN as set by the + macro B_MARGIN +#ORIG_DOC_LEAD DOC_LEAD before endnotes, bibliographies, tocs +#ORIG_L_LENGTH \\n(.l before starting LISTs +#ORIGINAL_DOC_LEAD The lead for PRINT_STYLE 1 as set in + PRINTSTYLE; required so that PRINT_STYLE 1 + footnotes have an unadjusted lead of + 12 points +#OVERFLOW Signals to FOOTNOTE that some of the + footnote text won't fit on the page +#OVERFLOW_LEFT Does left margin note overflow? (boolean) +#OVERFLOW_RIGHT Does right margin note overflow? (boolean) +#P Page number for margin notes +#PAD_LIST_DIGITS<n> Pad LIST digits for LIST <n>? (boolean) +#PAGE_NUM_ADJ What to add to n% to get #PAGENUMBER +#PAGE_NUM_H_POS 1=left 2=CENTER 3=right; default=2 +#PAGE_NUM_COLOR Colorize pagenumbers? (boolean) +#PAGE_NUM_HYPHENS Print hyphens surrounding page numbers? + (boolean) +#PAGE_NUM_HYPHENS_SET Did user set (or unset) hyphens around page + numbers? (boolean) +#PAGE_NUM_POS_SET Did user set page number position? (boolean) +#PAGE_NUM_SET Test if PAGE_1_NUM was used to set 1st page + number +#PAGE_NUM_V_POS 1=top 2=bottom; default=2 +#PAGE_NUMS Print page numbers? (boolean) +#PAGE_POS Exact position on page during a diversion + (required for collecting footnotes inside + a diversion) +#PAGE_TOP \n(nl after HEADER completes itself +#PAGENUM_STYLE_SET Did we set pagenumber style? (boolean) +#PAGENUMBER The page number +#PAGES Number of blank pages to output +#PAGINATE Are we paginating? (boolean) +#PAGINATE_TOC Is toc pagination on? (boolean) +#PAGINATE_WAS_ON Keeps track of pagination state while + outputting blank pages +#PAGINATION_STATE Saves pagination state in COLLATE for use in + START after a COLLATE +#PAGINATION_WAS_ON Was pagination on? - used in FINIS (boolean) +#PH_COLOR Colorize paraheads? (boolean) +#PH_INDENT Size of parahead indent +#PH_NUM Parahead number +#PP 0 at first para; auto-increments +#PP_AT_PAGE_BREAK # of last (incl. partial) para on page +#PP_INDENT How much to indent paras +#PP_SPACE Put space before paras? (boolean) +#PP_SPACE_SUSPEND Suspend para spacing for blockquotes and + epigraphs +#PP_STYLE_PREV In footnotes, stores PP style in effect + prior to invoking FOOTNOTE +#PP_STYLE Regular para=1; quote or epi para=2 +#PRE_COLLATE Set to 1 in COLLATE; prevents FAMILY + from clobbering a user-set DOC_FAMILY +#PREFIX_CH_NUM Prefix the chapter number to numbered + heads, subheads and/or paraheads? (boolean) +#PREV_FN_DEFERRED Was previous footnote deferred? (boolean) +#PRINT_PAGENUM_ON_PAGE_1 Should we print the page number on first + page of doc when footers are on? (boolean) +#PRINT_STYLE Typewrite=1, typeset=2 +#PT_SIZE_IN_UNITS Stored value of \n[.ps] from last time + PT_SIZE was called +#Q_AUTOLEAD Register created by QUOTE_AUTOLEAD +#Q_DEPTH Depth of quote +#Q_FITS Does this quote fit on one page/column? + (boolean) +#Q_LEAD Leading of quotes +#Q_LEAD_DIFF Difference between leading of running text + and the leading used in quotes/blockquotes +#Q_LEAD_REAL Leading of quotes and blockquotes saved at the + ends of their respective diversions +#Q_L_LENGTH Line length of quotes +#Q_OFFSET Page offset for quotes +#Q_OFFSET_VALUE Factor by which to multiply PP_INDENT to + offset quotes +#Q_PARTIAL_DEPTH The amount of a quote/blockquote that fits at + the bottom of a page when a quote/blockquote + spans pages +#Q_PP In PP, stores para # in QUOTE. Removed in + ENDQUOTE. +#Q_SPACE_ADJ The flexible amount of whitespace to add before + and after a quote/blockquote +#Q_TOP Vertical place on page that a quote starts +#QUOTE 1=PQUOTE, 2=BQUOTE +#QUOTE_COLOR Colorize quotes (poetic)? (boolean) +#QUOTE_LN Linenumber quotes? (boolean) +#RECTO_VERSO Switch HEADER_LEFT and HEADER_RIGHT on + alternate pages? (boolean) +ref*suppress-period Suppress period at end of ref field? (boolean) +ref*type Kind of reference we're building +#REF Was REF called? (boolean) +#REF_HY Hyphenate REFs? (boolean) +#REF_WARNING Have we issued a ref warning? (boolean) +#REPEAT Number of times to repeat linebreak + character +#RERUN_TRAPS Should we invoke TRAPS? (boolean) +#RESERVED_SPACE Just enough room to put 1 more line of + footnotes on the page +#RESET_EN_PP Holds value of register #EN_PP_INDENT +#RESET_EN_PP_INDENT Holds value of register #EN_PP_INDENT +#RESET_FN_COUNTERS 1 = "moved" footnote collected in a diversion + 2 = "deferred" fn collected in a diversion +#RESET_FN_NUMBER Should fn# start at 1 on every page? + (boolean) +#RESET_L_LENGTH Stores current line length when necessary +#RESET_PARA_SPACE Holds current value of boolean register + #PP_SPACE +#RESET_PP_INDENT Stores value of PP_INDENT when needed +#RESET_QUOTE_SPACING Stores value of boolean register + #FULLSPACE_QUOTES (used in endnotes) +#RESTORE_ADJ_DOC_LEAD Stores value of #ADJ_DOC_LEAD whenever needed +#RESTORE_B_MARGIN Stores #B_MARGIN whenever needed +#RESTORE_DOC_LEAD Stores value of current doc lead (used in + endnotes) +#RESTORE_HY Restore hyphenation after .][? (boolean) +#RESTORE_INDENT Store \n(.i whenever needed +#RESTORE_L_LENGTH Stores \n(.l whenever needed +#RESTORE_LN_NUM Should we restore line numbering? (boolean) +#RESTORE_OFFSET Page offset at moment footer trap is sprung; + not currently used +#RESTORE_TOC_PN_PADDING Saves #TOC_PN_PADDING in TOC prior to + processing $FIRST_DOC_TITLE +#RESTORE_UNDERLINE Instructs CODE OFF to restore underlining of italics + (TYPEWRITE) if underlining was formerly on +#RIGHT_CAP_HEIGHT Cap height of right string in + headers/footers +#RULED Tells FOOTNOTE if a rule (or space has been + put above the first footnote on the page +#RUNON_FN_IN_DIVER If #LN=1, if we're in a (block)quote, instructs + FOOTNOTE to unformat diversion RUNON_FN_IN_DIVER +#RUNON_FOOTNOTES If #LN=1, instructs FOOTNOTE to unformat + diversion RUNON_FOOTNOTES +#RUN_ON Are we using run-on footnotes? (boolean) +#SAVED_DIVER_FN_COUNT In the case of a footnote inside a + diversion that should be treated as a + "normal" footnote, FOOTNOTE needs to + distinguish between a "normal" deferred + footnote (always the 1st footnote on the + page) and one that only looks as if + it should be deferred, when, in fact, + it's an overflow; this register lets + FOOTNOTE know whether the diversion + footnote is, in fact, the first on the + page. +#SAVED_DOC_LEAD Stored value of #DOC_LEAD (used in DEFAULTS after a COLLATE) +#SAVED_FN_COUNT #FN_COUNT+1 prior to +#FN_COUNT; used + in FOOTNOTES while gathering fns inside + diversions +#SAVED_FN_COUNT_FOR_COLS #FN_COUNT_FOR_COLS+1 prior to + +#FN_COUNT_FOR_COLS; used in FOOTNOTES + while gathering fns inside diversions +#SAVED_FN_DEPTH_1 Footnote depth prior to adding footnote + diversion depth to FN_DEPTH; used when + footnote text will overflow +#SAVED_FN_DEPTH_2 Footnote depth after to adding footnote + diversion depth to FN_DEPTH; used when + footnote text will overflow +#SAVED_FN_NUMBER Stores current FN_NUMBER whenever needed +#SAVED_FOOTER_POS Position of FOOTER in DO_QUOTE (hack) +#SAVED_LEAD In FOOTER and DO_FOOTER, stores the + lead in effect prior to outputting + FOOTNOTES or performing either + PROCESS_FN_LEFTOVER or + PROCESS_FN_IN_DIVERSION; both the + diversion FOOTNOTES and the two macros + have, for PRINT_STYLE 2, an AUTOLEAD + call, which requires that an LS be + performed with the #SAVED_LEAD in + order to remove register #AUTO_LEAD or + #AUTO_LEAD_FACTOR. +#SAVED_UNDERSCORE_WEIGHT Stores underscore weight whenever needed +#SAVED_UNDERSCORE_WEIGHT_ADJ SAVED_UNDERSCORE_WEIGHT/2 +#SAVED_VFP Store variable footer position whenever needed +#SAVED_WEIGHT Stores weight given to RULE_WEIGHT whenever needed +#SAVED_WEIGHT_ADJ SAVED_UNDERSCORE_WEIGHT/2 +#SEP_TYPE Set to 1 if LIST separator is ( or [ or { +#SH_COLOR Colorize subheads? (boolean) +#SH_LEAD_ADJUST #DOC_LEAD/8 (TYPESET) or /2 (TYPEWRITE) + (used for subhead spacing) +#SH_NUM Subhead number +#SHIM Amount of lead required to advance to + next valid baseline +#SILENT_BQUOTE_LN "Silently" linenumber blockquotes? (boolean) +#SILENT_QUOTE_LN "Silently" linenumber quotes? (boolean) +#SINGLE_SPACE Is TYPEWRITE in single space mode? (boolean) +#SKIP_FOOTER If 1, instructs DO_FOOTER to do nothing + if B_MARGIN falls below FOOTER_MARGIN +#SLANT_MEANS_SLANT For TYPEWRITE. (boolean) +#SLANT_WAS_ON Keeps track of SLANT when it needs to go off + for a while +#SPACE_REMAINING Space remaining to footer trap; used to + decide whether or not to defer a footnote +#SPACE_TO_FOOTER Distance to FOOTER trap; used to calculate + available space when FOOTNOTE is called inside + a diversion +#SR_ADJ_FACTOR An adjustment factor that compensates + for the fact that #SPACE_REMAINING + sometimes reports a fractionally larger + space than is actually available for + footnote text. +#START If 1, signals completion of START +#START_FOR_FOOTERS Toggle set in START; signals to + PRINT_HDRFTR that START has been invoked, + allowing PRINT_HDRFTR to decide whether or + not to print a footer on page 1 +#START_FOR_MNinit If 1, defer processing MN_INIT until #START +#STORED_PP_INDENT Temporarily holds value of #PP_INDENT +#SUBTITLE_COLOR Colorize subtitle? (boolean) +#SUBTITLE_COVER_NUM Incrementing register used to define strings + $SUBTITLE_COVER_<n> +#SUBTITLE_DOCCOVER_NUM Incrementing register used to define strings + $SUBTITLE_DOCCOVER_<n> +#SUBTITLE_NUM Incrementing register used to define strings + $SUBTITLE_<n> +#SUBTITLES Holds number of subtitle items +#SUITE Current page number (for letters) +#SUP_PT_SIZE Point size of superscript +#SUSPEND_PAGINATION Suspend pagination prior to endnotes? +#SWITCH_HDRFTR Switch HDRFTR_LEFT and HDRFTR_RIGHT? + (boolean) +#T_MARGIN_LEAD_ADJ \n(.v-12000; ensures critically accurate + placement of first lines on pages when + doc processing is not being used and + a T_MARGIN has been set +#TAB_OFFSET# "#" at the end is from $CURRENT_TAB +#TERMINATE Has TERMINATE been called? (boolean) +#TITLE_COLOR Colorize title? (boolean) +#TITLE_NUM Number of title items +#TOC_AUTHORS Whether to append author(s) to toc doc + title entries (boolean) +#TOC_ENTRY_PN Current page number when a toc entry is + collected +#TOC_FIRST_PAGE If 1, tells PRINT_PAGE_NUMBER that this + is the first page of the toc +#TOC_LEAD Leading of toc pages +#TOC_PN_PADDING Max. # of placeholders for toc entries + page numbers +#TOC_PS Point size of toc pages +#TOC_RV_SWITCH Switch L/R margins of toc pages +#TOC_HEAD_INDENT Indent of toc head entries +#TOC_HEAD_SIZE_CHANGE ps in/decrease of toc head entries**** +#TOC_PH_INDENT Indent of toc parahead entries +#TOC_PH_SIZE_CHANGE ps in/decrease of toc parahead entries**** +#TOC_SH_INDENT Indent of toc subhead entries +#TOC_SH_SIZE_CHANGE ps in/decrease of toc subhead entries**** +#TOC_TITLE_INDENT Indent of toc doc title entries +#TOC_TITLE_SIZE_CHANGE ps in/decrease of toc doc title entries**** +#TOTAL_FIELDS Total number of letter header fields +#TRAP \n(.t-1 (used in DO_QUOTE) +#UNDERLINE_ITALIC For TYPEWRITE. (boolean) +#UNDERLINE_ON Was UNDERLINE called? (boolean) +#UNDERLINE_QUOTES Was UNDERLINE_QUOTES called? (boolean) +#UNDERLINE_QUOTE Underline pquotes? (boolean) +#UNDERLINE_SLANT For TYPEWRITE. (boolean) +#UNDERLINE_WAS_ON In HEADER to re-enable running text + UNDERLINE (boolean) +#USER_DEF_HDRFTR_CENTER Has user defined hdrftr center? (boolean) +#USER_DEF_HDRFTR_LEFT Has user defined hdrftr left? (boolean) +#USER_DEF_HDRFTR_RIGHT Has user defined hdrftr right? (boolean) +#USER_DEF_HEADER_CENTER User defined CENTER title? (boolean); + used in COPYSTYLE +#USER_DEF_HEADER_LEFT User defined CENTER title? (boolean); + used in COPYSTYLE +#USER_DEF_HEADER_RIGHT User defined CENTER title? (boolean) + used in COPYSTYLE +#USERDEF_HDRFTR User defined single string recto/verso + header/footer? (boolean) +#USERDEF_HDRFTR_RECTO_QUAD 1=left, 2=CENTER, 3=right +#USERDEF_HDRFTR_VERSO_QUAD 1=left, 2=CENTER, 3=right +#VARIABLE_FOOTER_POS Wandering trap position for processing + footnotes and footers; pos depends on number of + footnotes +#VISUAL_B_MARGIN Set in TRAPS, what \n(nl would report + on the last line of running text before + FOOTER is sprung. +#VFP_DIFF #FN_DEPTH minus #SAVED_FN_DEPTH; the + number of footnote lines that will fit + on the page when there will be over, and + therefore the amount by which to raise + the VFP for footnotes with overflow after + the 1st footnote. +y Vertical position stored with mk in hdrftrs. + ++++STRINGS+++ + +$1ST_LETTER First letter of first arg to LIST +$ADJUST_BIB_LEAD 2nd arg to BIBLIOGRAPHY_LEAD; if not blank + adjust bib leading +$ADJUST_EN_LEAD 2nd arg to ENDNOTE_LEAD; if not blank adjust + endnote leading +$ADJUST_TOC_LEAD 2nd arg to TOC_LEAD; if not blank adjust + toc leading +$ATTRIBUTE_COLOR Attribution string color +$ATTRIBUTE_STRING Attribution string in doc header +$ATTRIBUTE_STRING_COVER Attribution string on cover +$ATTRIBUTE_STRING_DOCCOVER Attribution string on doc cover +$AUTHOR_<n> Document author(s) +$AUTHOR The author, or the first argument + passed to .AUTHOR ($AUTHOR_1) +$AUTHOR_COLOR Author color +$AUTHOR_COVER_<n> Author(s) on cover +$AUTHOR_DOCCOVER_<n> Author(s) on doc cover +$AUTHOR_FAM Family to use for author in doc header +$AUTHOR_FT Font to use for author in doc header +$AUTHOR_SIZE_CHANGE ps in/decrease of author in doc header* +$AUTHOR_PT_SIZE Absolute ps of authors +$AUTHORS Comma-separated concatenated + string of all args passed to .AUTHOR +$BIB_FAM Bibliography page family +$BIB_FT Bibliography page font +$BIB_LEAD Base leading for bibliographies +$BIB_LIST_SEPARATOR Separator between enumerator and text + when outputting bibliographies in LIST style +$BIB_LIST_PREFIX Prefix before enumerator when outputting + bibliographies in LIST style +$BIB_PN_STYLE Format of bibliography page numbers +$BIB_QUAD +$BIB_SPACE Post entry space for bibliographies +$BIB_STRING Bibliography title string +$BIB_STRING_FAM Bib title family +$BIB_STRING_FT Bib title font +$BIB_STRING_QUAD Bib title quad +$BIB_STRING_RULE_GAP Distance between the underscores when BIB_STRING + (bib first-page header) is double-underlined +$BIB_STRING_SIZE_CHANGE Bib title size (+ or -) +$BIB_STRING_UNDERLINE_GAP Distance between BIB_STRING text and (first) + underline rule +$BQ_LN_GUTTER Gutter between line numbers and bquotes in + bquotes +$BQUOTE_COLOR Blockquote color +$BQUOTE_FAM Family to use for blockquotes +$BQUOTE_FT Font to use for blockquotes +$BQUOTE_QUAD Quad value for blockquotes +$BQUOTE_SIZE_CHANGE ps in/decrease of blockquotes* +$BX_COLOR Box color +$BX_DEPTH Box depth +$BX_INDENT Box left margin starting position +$BX_WEIGHT Box rule weight +$BX_WIDTH Box width +$CENTER_TITLE What to put in the middle of header + title +$CH_NUM Chapter number (as a string) +$CHAPTER The chapter number +$CHAPTER_STRING What to print whenever the word + "chapter" is required +$CHAPTER_TITLE Concatenated args passed to CHAPTER_TITLE +$CHAPTER_TITLE_<n> Chapter title items +$CHAPTER_TITLE_FAM Family of chapter title +$CHAPTER_TITLE_FT Font of chapter title +$CHAPTER_TITLE_SIZE_CHANGE ps in/decrease of chapter title* +$CHAPTER_TITLE_PT_SIZE Absolute ps of chapter title +$CHAPTER_TITLE_COLOR Color of chapter title +$CL_COLOR Circle (ellipse) color +$CL_DEPTH Circle (ellipse) depth +$CL_INDENT Circle (ellipse) left margin starting position +$CL_WEIGHT Circle (ellipse) rule weight +$CL_WIDTH Circle (ellipse) width +$CODE_FAM Family to use with CODE +$COLOR_SCHEME Color scheme arg passed to NEWCOLOR +$COPY_STYLE DRAFT or FINAL +$COPYRIGHT Copyright info +$COPYRIGHT_COVER Copyright info for cover +$COPYRIGHT_DOCCOVER Copyright info for doc cover +$COPYRIGHT_FAM Copyright line family +$COPYRIGHT_FT Copyright line font +$COPYRIGHT_PT_SIZE Base string to which $COPYRIGHT_SIZE_CHANGE + is appended +$COPYRIGHT_SIZE_CHANGE Copyright line size* +$COPYRIGHT_COLOR Copyright line color +$COPYRIGHT_QUAD Copyright line quad direction +$COVER_ATTRIBUTE_COLOR Cover attribution string color +$COVER_AUTHOR_COLOR Cover author(s) color +$COVER_AUTHOR_FAM Cover author(s) family +$COVER_AUTHOR_FT Cover author(s) font +$COVER_AUTHOR_PT_SIZE Author point size on cover +$COVER_AUTHOR_SIZE_CHANGE Cover author(s) size* +$COVER_CHAPTER_TITLE_COLOR Color of chapter title on cover +$COVER_CHAPTER_TITLE_PT_SIZE Size of chapter title on cover +$COVER_COLOR Overall cover color +$COVER_COPYRIGHT_PT_SIZE Size of copyright info on cover +$COVER_DOCTYPE_PT_SIZE Size of doctype on cover +$COVER_FAM Overall cover family +$COVER_LEAD_ADJ String appended to DOC_LEAD to arrive at + base leading of covers +$COVER_SUBTITLE_PT_SIZE Size of subtitle on cover +$COVER_TITLE_PT_SIZE Size of title on cover +$COVER_TITLE User-defined cover title string +$COVER_TITLE_<n> Cover title items +$COVER_TITLE_FAM Cover title family +$COVER_TITLE_FT Cover title font +$COVER_TITLE_SIZE_CHANGE Cover title size* +$COVER_TITLE_COLOR Cover title color +$COVER_UNDERLINE_GAP Distance between baseline of the doctype on covers + and the underline +$COVER_SUBTITLE_FAM Cover subtitle family +$COVER_SUBTITLE_FT Cover subtitle font +$COVER_SUBTITLE_SIZE_CHANGE Cover subtitle size* +$COVER_SUBTITLE_COLOR Cover subtitle color +$COVER_DOCTYPE_FAM Cover doctype family +$COVER_DOCTYPE_FT Cover doctype font +$COVER_DOCTYPE_SIZE_CHANGE Cover doctype size* +$COVER_DOCTYPE_COLOR Cover doctype color +$COVER_COPYRIGHT_FAM Cover copyright family +$COVER_COPYRIGHT_FT Cover copyright font +$COVER_COPYRIGHT_SIZE_CHANGE Cover copyright size* +$COVER_COPYRIGHT_COLOR Cover copyright color +$COVER_MISC_FAM Cover misc family +$COVER_MISC_FT Cover misc font +$COVER_MISC_SIZE_CHANGE Cover misc size* +$COVER_MISC_COLOR Cover misc color +$CURRENT_EV \n[.ev] at REF_BRACKETS_START +$DC_COLOR Dropcap color +$DOC_COVER_ATTRIBUTE_COLOR Doc cover attribution string color +$DOC_COVER_AUTHOR_COLOR Doc cover author(s) color +$DOC_COVER_AUTHOR_FAM Doc cover author(s) family +$DOC_COVER_AUTHOR_FT Doc cover author(s) font +$DOC_COVER_AUTHOR_PT_SIZE Size of author on doc cover +$DOC_COVER_AUTHOR_SIZE_CHANGE Doc cover author(s) size* +$DOC_COVER_CHAPTER_TITLE_COLOR Color of chapter title on doc cover +$DOC_COVER_CHAPTER_TITLE_PT_SIZE Size of chapter title on doc cover +$DOC_COVER_COLOR Overall doc cover color +$DOC_COVER_COPYRIGHT_COLOR Doc cover copyright color +$DOC_COVER_COPYRIGHT_FAM Doc cover copyright family +$DOC_COVER_COPYRIGHT_FT Doc cover copyright font +$DOC_COVER_COPYRIGHT_PT_SIZE Size of copyright info on doc cover +$DOC_COVER_COPYRIGHT_SIZE_CHANGE Doc cover copyright size* +$DOC_COVER_DOCTYPE_COLOR Doc cover doctype color +$DOC_COVER_DOCTYPE_FAM Doc cover doctype family +$DOC_COVER_DOCTYPE_FT Doc cover doctype font +$DOC_COVER_DOCTYPE_PT_SIZE Size of doctype on doc cover +$DOC_COVER_DOCTYPE_SIZE_CHANGE Doc cover doctype size* +$DOC_COVER_MISC_COLOR Doc cover misc color +$DOC_COVER_MISC_FAM Doc cover misc family +$DOC_COVER_MISC_FT Doc cover misc font +$DOC_COVER_MISC_SIZE_CHANGE Doc cover misc size* +$DOC_COVER_FAM Overall doc cover family +$DOC_COVER_LEAD_ADJ String appended to DOC_LEAD to arrive at base + leading of doc covers +$DOC_COVER_SUBTITLE_FAM Doc cover subtitle family +$DOC_COVER_SUBTITLE_FT Doc cover subtitle font +$DOC_COVER_SUBTITLE_PT_SIZE Size of subtitle on doc cover +$DOC_COVER_SUBTITLE_SIZE_CHANGE Doc cover subtitle size* +$DOC_COVER_SUBTITLE_COLOR Doc cover subtitle color +$DOC_COVER_TITLE User-defined doc cover title string +$DOC_COVER_TITLE_<n> Doc cover title items +$DOC_COVER_TITLE_COLOR Doc cover title color +$DOC_COVER_TITLE_FAM Doc cover title family +$DOC_COVER_TITLE_FT Doc cover title font +$DOC_COVER_TITLE_PT_SIZE Size of title on doc cover +$DOC_COVER_TITLE_SIZE_CHANGE Doc cover title size* +$DOC_FAM Predominant font family used in the + document +$DOC_QUAD Quad used for body text (justified or + left) +$DOC_TITLE Concatenated args passed to DOCTITLE +$DOC_TITLE_<n> DOCTITLE items +$DOC_TYPE Document type (default, chapter, named, + letter) +$DOCCOVER_UNDERLINE_GAP Distance between baseline of doctype and the + underline on covers +$DOCHEADER_COLOR Color of docheader +$DOCHEADER_FAM Family used for all parts of the docheader +$DOCHEADER_LEAD_ADJ +|- value applied to #DOC_LEAD to + in/decrease leading of doc header +$DOCTYPE_COLOR Color of DOCTYPE string in doc header +$DOCTYPE_FAM Family to use for DOCTYPE string in + doc header +$DOCTYPE_FT Font to use for DOCTYPE string in + doc header +$DOCTYPE_SIZE_CHANGE ps in/decrease of DOCTYPE string in + doc header* +$DOCTYPE_PT_SIZE Absolute ps of DOCTYPE +$DOCTYPE_UNDERLINE_GAP Distance between baseline of DOCTYPE and the + underline in doc header +$DRAFT The draft number (string valued) +$DRAFT_STRING What to print whenever the word "draft" + is required +EN_MARK Inline, gets #EN_MARK (\(ln) +$EN_CLOSE_BRACKET Close bracket for line-number enumerated + endnotes +$EN_FAMILY Family for endnotes +$EN_FT Font for endnotes +$EN_LEAD Leading of endnotes pages +$EN_LINENUMBER String to print for line-number enumerators + in line-numbered endnotes +$EN_LN_FAM Family for line-numbers in line-number + identified endnotes +$EN_LN_FT Font for line-numbers in line-number + identified endnotes +$EN_LN_GAP Gap to leave in initial endnote lines + between line-number identifies and text +$EN_LN_SEP User-defined separator to use between line number(s) + and endnotes when endnotes are identified by line + number +$EN_OPEN_BRACKET Open bracket for line-number enumerated + endnotes +$EN_LN_SIZE_CHANGE Size change (+ or -) for line-numbers in + line-number identified endnotes +$EN_PN_STYLE Pagenumbering style for endnotes pages +$EN_QUAD Quad for endnotes +$EN_STRING Endnotes page head +$EN_STRING_FAM Endnotes page head family +$EN_STRING_FT Endnotes page head font +$EN_STRING_QUAD Endnotes page head quad direction +$EN_STRING_RULE_GAP Distance between rules when EN_STRING is + double-underlined +$EN_STRING_UNDERLINE_GAP Distance between baseline of EN_STRING and + underline rule +$EN_STRING_SIZE_CHANGE Endnotes page head size*** +$EN_TITLE Endnote document identifier +$EN_TITLE_FAM Endnote document identifier family +$EN_TITLE_FT Endnote document identifier font +$EN_TITLE_QUAD Endnote document identifier quad + direction +$EN_TITLE_SIZE_CHANGE Endnote document identifier size*** +$EN_TITLE_UNDERLINE_GAP Distance between baseline of EN_TITLE and underline + rule +$EN_NUMBER_FAM Endnote numbering family +$EN_NUMBER_FT Endnote numbering font +$EN_NUMBER_SIZE_CHANGE Endnote numbering size*** +$EPI_AUTOLEAD Autolead value (decimals ok) of + epigraphs +$EPI_COLOR Color of epigraphs +$EPI_FAM Family to use in epigraphs +$EPI_FT Font to use in epigraphs +$EPI_OFFSET_VALUE Arg passed to EPIGRAPH_INDENT if the + arg has a unit of measure appended to it +$EPI_QUAD Quad in block-style epigraphs + (justified or left) +$EPI_SIZE_CHANGE ps in/decrease of epigraphs* +$EVAL_BIB_SPACE Temporary string to find out if the + arg to BIBLIOGRAPHY_SPACING ended in "v" +$EVAL_EI_ARG Temporary string to find out whether + the arg to EPIGRAPH_INDENT ended with + a unit of measure +$EVAL_QI_ARG Temporary string to find out whether + the arg to QUOTE_INDENT ended with + a unit of measure +eval*[B Used to get substring of \*([B +eval*[S Used to get substring of \*([S +eval*[s Used to get substring of \*([s +$FINIS_COLOR Color of FINIS string +$FINIS_STRING What to print when FINIS macro is + invoked +$FIRST_DOC_TITLE 1st doc's title captured in COLLATE +FN_MARK Inline, gets #FN_MARK (\n(ln) +$FN_CLOSE_BRACKET Close bracket for line-number identified + footnotes +$FN_FAM Family used in footnotes +$FN_FT Font used in footnotes +$FN_LINENUMBER String to print before footnotes when + line-numbering enabled for footnotes +$FN_LN_SEP Separator after line-number identified + footnotes +$FN_OPEN_BRACKET Open bracket for line-number identified + footnotes +$FN_QUAD Quad used in footnotes +$FN_SIZE_CHANGE ps in/decrease of footnotes* +$FOOTNOTE_COLOR Footnote color +$FTR_RECTO_QUAD Quad direction of footer recto +$FTR_RECTO_STRING String for footer recto +$FTR_VERSO_QUAD Quad direction of footer verso +$FTR_VERSO_STRING String for footer verso +$HDR_RECTO_QUAD Quad of header recto +$HDR_RECTO_STRING String for header recto +$HDR_VERSO_QUAD Quad of header verso +$HDR_VERSO_STRING String for header verso +**Note: "header", in the descriptions below, means either headers or footers** + +$HDRFTR_CENTER What to put in CENTER part of headers; + default doctype +$HDRFTR_CENTER_COLOR Color of CENTER part of headers +$HDRFTR_CENTER_FAM Family of CENTER part of headers +$HDRFTR_CENTER_FT Font of centre part of headers +$HDRFTR_CENTER_NEW HDRFTR_CENTER after the start of TOC; + defined in HDRFTR_CENTER if + HDRFTR_CENTER is called as + FOOTER_CENTER +$HDRFTR_CENTER_OLD HDRFTR_CENTER just prior to start of + TOC; defined in HDRFTR_CENTER if + HDRFTR_CENTER is called as + FOOTER_CENTER +$HDRFTR_CENTER_SIZE_CHANGE ps in/decrease of centre title in + headers** +$HDRFTR_COLOR Color of headers/footers +$HDRFTR_FAM Family to use in headers +$HDRFTR_LEFT_COLOR Color of LEFT part of headers +$HDRFTR_LEFT_FAM Family of left part of headers +$HDRFTR_LEFT_FT Font of left part of headers +$HDRFTR_LEFT_SIZE_CHANGE ps in/decrease of author in headers** +$HDRFTR_LEFT What to put in left part of headers; + default author +$HDRFTR_RIGHT_COLOR Color of RIGHT part of headers +$HDRFTR_RIGHT_FAM Family of right part of headers +$HDRFTR_RIGHT_FT Font of right part of headers +$HDRFTR_RIGHT_SIZE_CHANGE ps in/decrease of right part of + headers** +$HDRFTR_RIGHT What to put in right part of headers; + default title +$HDRFTR_RULE_COLOR Color of header rule +$HDRFTR_SIZE_CHANGE ps in/decrease of headers* +$HDRFTR_TMP_SIZE_CHANGE_SWITCH Temporarily holds + HDRFTR_LEFT_SIZE_CHANGE if + #SWITCH_HDRFTRS=1 +$HDRFTR_TMP_SWITCH Temporarily holds HDRFTR_LEFT if + #SWITCH_HDRFTRS=1 +$HDRFTR_TMP_COLOR_SWITCH Temporarily holds HDRFTR_LEFT_COLOR if + #SWITCH_HDRFTRS=1 +$HEAD_COLOR Head color +$HEAD_FAM Family to use for section titles +$HEAD_FT Font to use for section titles +$HEAD_QUAD Quad value of section titles +$HEAD_SIZE_CHANGE ps in/decrease of section titles* +$HEAD_UNDERLINE_GAP Distance between a head and the underline +$HYPHEN Vertically adjusted hyphen used around page numbers +$LHS Holds digits on the left side of the decimal in + weight arg passed to RULE_WEIGHT +$LINEBREAK_CHAR Character that marks line breaks +$LINEBREAK_CHAR_V_ADJ +|- amount by which to raise/lower + linebreak character +$LAST_CHAR Temporary string used to discover whether + user has remembered to put a digit after + ROMAN or roman in arg to LIST +$LINEBREAK_COLOR Linebreak color +$LIST_ARG_1 The first arg to LIST (minus digits if + ROMAN or roman +$LN_COLOR Linenumber color +$LN_FAMILY Linenumber family +$LN_FONT Linenumber font +$LN_GUTTER Gutter to leave between line numbers + and text +$LN_INC 2nd arg to NUMBER_LINES as a string +$LN_NUM 1st arg to NUMBER_LINES as a string +$LN_SIZE_CHANGE ps in/decrease of linenumbers +$MISC_<n> +$MISC_COLOR Misc olor +$MISC_COVER_<n> Misc items for cover +$MISC_DOCCOVER_<n> Misc items for doc cover +$MISC_QUAD Misc quad direction +$MN-arg<n> Sequentially numbered args passed to MNinit +MN-color Color of margin note +MN-curr Number of current margin note +MN-dir Left or right margin note +MN-font Font of margin note +MN-left-ad Fill mode of margin note +PAGE# For use in hdrftr strings where page # + is needed; \*[PAGE] +$PAGENUM_COLOR Page number color +$PAGENUM_STYLE String passed to PAGENUM_STYLE +$PAGE_NUM_FAM Family of page numbers +$PAGE_NUM_FT Font of page numbers +$PAGE_NUM_SIZE_CHANGE ps in/decrease of page numbers +$PAPER Paper size (LETTER, A4, LEGAL); + default=LETTER +$PH_COLOR Parahead color +$PP_FT Font used in paragraphs +$RESTORE_PAGENUM_STYLE Hold previous page numbering style +$ROMAN_WIDTH<n> The digit(s) appended by user to ROMAN or + roman when LIST is invoked +$Q_LN_GUTTER Gutter between linenumbers and quotes + in quotes +$Q_OFFSET_VALUE Arg passed to QUOTE_INDENT if the + arg has a unit of measure appended to it +$QUOTE_COLOR Quote (poetic) color +$QUOTE_FAM Family to use for pquotes +$QUOTE_FT Font to use for pquotes +$QUOTE_SIZE_CHANGE ps in/decrease of pquotes* +ref*post-punct Final punctuation mark of references +ref*spec!<n> Holds fields required by differing reference types +ref*string The data passed to a reference +$REF_BIB_INDENT 2nd line indent value for references in + bibliographies +$REF_EN_INDENT 2nd line indent value for references in + endnotes +$REF_FN_INDENT 2nd line indent value for references in + footnotes +$RESTORE_SS_VAR Saves \*[$SS_VAR] for use with ref*build +#REVISION The revision number (string valued) +$REVISION_STRING What to print whenever the word + "revision" is required +$RHS Holds digits on the right side of the decimal in + weight arg passed to RULE_WEIGHT +$RL_COLOR Rule color (DRH/DRV) +$RL_DEPTH Rule depth (DRH/DRV) +$RL_INDENT Left start position of rule (DRH/DRV) +$RL_LENGTH Rule length (DRH/DRV) +$RL_WEIGHT Rule weight (DRH/DRV) +$SAVED_COPYRIGHT Temporarily holds string in $COPYRIGHT +$SAVED_RULE_GAP Temporarily holds string in $RULE_GAP +$SAVED_PP_FT $PP_FT in effect at start of + .COLLATE; tested for and removed + in .PP +$SH_FAM Family to use in subheads +$SH_FT Font to use in subheads +$SH_SIZE_CHANGE ps in/decrease of subheads* +$SH_COLOR Subhead color +$SUBTITLE Concatenated args passed to SUBTITLE +$SUBTITLE_<n> Subtitle items for doc header +$SUBTITLE_COLOR Color of subtitle +$SUBTITLE_COVER_<n> Subtitle items for cover +$SUBTITLE_DOCCOVER_<n> Subtitle items for doc cover +$SUBTITLE_FAM Family to use for subtitle in doc + header +$SUBTITLE_FT Font to use for subtitle in doc header +$SUBTITLE_SIZE_CHANGE ps in/decrease of subtitle* +$SUBTITLE_PT_SIZE Absolute ps of subtitle +$SUITE The #SUITE number register +$TITLE Concatenated args pass to TITLE +$TITLE_<n> Title items +$TITLE_COLOR Color of title +$TITLE_FAM Family to use for title in doc header +$TITLE_FT Font to use for title in doc header +$TITLE_PT_SIZE Absolute point size of title in docheader +$TITLE_SIZE_CHANGE ps in/decrease of title in doc header* +$TOC_AUTHORS What to print after toc doc title entry + if #TOC_AUTHORS=1 +$TOC_FAM Family to use on toc pages +$TOC_HEAD_FAM Family of toc head entries +$TOC_HEAD_FT Font of toc head entries +$TOC_HEAD_ITEM A head as collected for TOC_ENTRIES +$TOC_HEADER_FAM Family to use for "Contents" +$TOC_HEADER_FT Font to use for "Contents" +$TOC_HEADER_QUAD Quad direction of "Contents" +$TOC_HEADER_SIZE ps in/decrease of "Contents"**** +$TOC_HEADER_STRING Header string of first toc page +$TOC_LEAD Leading of toc pages +$TOC_PH_ITEM Toc parahead entry +$TOC_PN Sets up toc leaders + entry pn + (typeset) +$TOC_PN_FAM Family for toc entries page numbers +$TOC_PN_FT Font for toc entries page numbers +$TOC_PN_SIZE_CHANGE ps in/decrease of toc entries page + numbers +$TOC_PN_STYLE Page-numbering style of toc pages +$TOC_PN_TYPEWRITE Sets up toc leaders + entry pn + (typewrite) +$TOC_PH_FAM Family of toc parahead entries +$TOC_PH_FT Font of toc parahead entries +$TOC_PARAHEAD_ITEM A parahead collected for TOC_ENTRIES +$TOC_SH_FAM Family of toc subhead entries +$TOC_SH_FT Font of toc subhead entries +$TOC_SH_ITEM A subhead collected for TOC_ENTRIES +$TOC_TITLE_FAM Family of toc doc title entries +$TOC_TITLE_FT Font of toc doc title entries +$TOC_TITLE_ITEM Toc document title item +$USER_SET_TITLE_ITEM User defined toc doc title entry as + set by TOC_TITLE_ENTRY +$UR_PAGINATION_STYLE Pagination style prior to endnotes +$USERDEF_HDRFTR_RECTO User defined header/footer recto string +$USERDEF_HDRFTR_VERSO User defined header/footer verso string + + *relative to #DOC_PT_SIZE + **relative to overall ps of headers as set by HEADER_SIZE + ***relative to overall ps of endnotes +****relative to overall ps of toc pages + ++++PREPROCESSOR KEYWORDS+++ + +(eqn) +EQ +EN + +(grn) +GS +GE +GF + +(pic) +PS +PE + +(refer) +R1 +R2 +[ +] + +(tbl) +TS +TE +TH + +(grap) +G1 +G2 + +(ideal) +IS +IE + +(chem) +cstart +cend + ++++ALIASES+++ + +Please note: + +Prior to version 1.1.9, all macros that included the word COLOR had +aliases that used COLOUR instead. This convenience has now been +removed, in an effort to reduce the size of the om.tmac file. + +Furthermore, if you want the convenience, you'll have to edit the +om.tmac file. Simply aliasing, say, HEAD_COLOR as HEAD_COLOUR will +not work, owing to significant changes in the handling of +docelement control macros that end in _COLOR. + ++++The following are for convenience, and header/footer management+++ + +BIBLIOGRAPHY_STRING_UNDERSCORE BIBLIOGRAPHY_STRING_UNDERLINE +BREAK_BLOCKQUOTE BREAK_QUOTE +BREAK_CITATION BREAK_QUOTE +BREAK_CITE BREAK_QUOTE +CITATION BLOCKQUOTE +CITE BLOCKQUOTE +COL_BREAK COL_NEXT +DOC_FAM DOC_FAMILY +DOC_LLENGTH DOC_LINE_LENGTH +DOC_L_LENGTH DOC_LINE_LENGTH +DOC_L_MARGIN DOC_LEFT_MARGIN +DOC_LMARGIN DOC_LEFT_MARGIN +DOC_LS DOC_LEAD +DOC_PS DOC_PT_SIZE +DOC_R_MARGIN DOC_RIGHT_MARGIN +DOC_RMARGIN DOC_RIGHT_MARGIN +ENDNOTE_STRING_UNDERSCORE ENDNOTE_STRING_UNDERLINE +ENDNOTE_TITLE_UNDERSCORE ENDNOTE_TITLE_UNDERLINE +FOOTER_CENTER_CAPS HDRFTR_CENTER_CAPS +FOOTER_CENTER HDRFTR_CENTER +FOOTER_CENTRE_CAPS HDRFTR_CENTER_CAPS +FOOTER_CENTRE HDRFTR_CENTER +FOOTER_LEFT_CAPS HDRFTR_LEFT_CAPS +FOOTER_LEFT HDRFTR_LEFT +FOOTER_PLAIN HDRFTR_PLAIN +FOOTER_RECTO HDRFTR_RECTO +FOOTER_RIGHT_CAPS HDRFTR_RIGHT_CAPS +FOOTER_RIGHT HDRFTR_RIGHT +FOOTER_RULE_GAP HDRFTR_RULE_GAP +FOOTER_RULE HDRFTR_RULE +FOOTER_VERSO HDRFTR_VERSO +HDRFTR_RULE_INTERNAL HDRFTR_RULE +HEADER_CENTER_CAPS HDRFTR_CENTER_CAPS +HEADER_CENTER HDRFTR_CENTER +HEADER_CENTRE_CAPS HDRFTR_CENTER_CAPS +HEADER_CENTRE HDRFTR_CENTER +HEADER_LEFT_CAPS HDRFTR_LEFT_CAPS +HEADER_LEFT HDRFTR_LEFT +HEADER_PLAIN HDRFTR_PLAIN +HEADER_RECTO HDRFTR_RECTO +HEADER_RIGHT_CAPS HDRFTR_RIGHT_CAPS +HEADER_RIGHT HDRFTR_RIGHT +HEADER_RULE_GAP HDRFTR_RULE_GAP +HEADER_RULE HDRFTR_RULE +HEADER_VERSO HDRFTR_VERSO +PAGENUM PAGENUMBER +PAGINATION PAGINATE +PP_FT PP_FONT +PRINT_FOOTNOTE_RULE FOOTNOTE_RULE +SWITCH_FOOTERS SWITCH_HDRFTR +SWITCH_HEADERS SWITCH_HDRFTR +TOC_LS TOC_LEAD +TOC_PS TOC_PT_SIZE + ++++The following are used for docelement type-style control+++ + +AUTHOR_FAMILY _FAMILY +AUTHOR_FONT _FONT +AUTHOR_SIZE _SIZE +BIBLIOGRAPHY_FAMILY _FAMILY +BIBLIOGRAPHY_FONT _FONT +BIBLIOGRAPHY_FOOTER_CENTER BIBLIOGRAPHY_HDRFTR_CENTER +BIBLIOGRAPHY_FOOTER_CENTRE BIBLIOGRAPHY_HDRFTR_CENTRE +BIBLIOGRAPHY_HEADER_CENTER BIBLIOGRAPHY_HDRFTR_CENTER +BIBLIOGRAPHY_HEADER_CENTRE BIBLIOGRAPHY_HDRFTR_CENTRE +BIBLIOGRAPHY_QUAD _QUAD +BIBLIOGRAPHY_STRING_FAMILY _FAMILY +BIBLIOGRAPHY_STRING_FONT _FONT +BIBLIOGRAPHY_STRING_QUAD _QUAD +BIBLIOGRAPHY_STRING_SIZE _SIZE +BLOCKQUOTE_AUTOLEAD Q_AUTOLEAD +BLOCKQUOTE_AUTOLEAD QUOTE_AUTOLEAD +BLOCKQUOTE_COLOR _COLOR +BLOCKQUOTE_FAMILY _FAMILY +BLOCKQUOTE_FONT _FONT +BLOCKQUOTE_QUAD _QUAD +BLOCKQUOTE_SIZE _SIZE +CHAPTER_TITLE_COLOR _COLOR +CHAPTER_TITLE_FAMILY _FAMILY +CHAPTER_TITLE_FONT _FONT +CHAPTER_TITLE_SIZE _SIZE +COVER_ATTRIBUTE_COLOR _COLOR +COVER_AUTHOR_COLOR _COLOR +COVER_AUTHOR_FAMILY _FAMILY +COVER_AUTHOR_FONT _FONT +COVER_AUTHOR_SIZE _SIZE +COVER_COLOR _COLOR +COVER_COPYRIGHT_COLOR _COLOR +COVER_COPYRIGHT_FAMILY _FAMILY +COVER_COPYRIGHT_FONT _FONT +COVER_COPYRIGHT_QUAD _QUAD +COVER_COPYRIGHT_SIZE _SIZE +COVER_DOCTYPE_COLOR _COLOR +COVER_DOCTYPE_FAMILY _FAMILY +COVER_DOCTYPE_FONT _FONT +COVER_DOCTYPE_SIZE _SIZE +COVER_FAMILY _FAMILY +COVER_MISC_COLOR _COLOR +COVER_MISC_QUAD _QUAD +COVER_SUBTITLE_COLOR _COLOR +COVER_SUBTITLE_FAMILY _FAMILY +COVER_SUBTITLE_FONT _FONT +COVER_SUBTITLE_SIZE _SIZE +COVER_TITLE_COLOR _COLOR +COVER_TITLE_FAMILY _FAMILY +COVER_TITLE_FONT _FONT +COVER_TITLE_SIZE _SIZE +DOC_COVER_ATTRIBUTE_COLOR _COLOR +DOC_COVER_AUTHOR_COLOR _COLOR +DOC_COVER_AUTHOR_FAMILY _FAMILY +DOC_COVER_AUTHOR_FONT _FONT +DOC_COVER_AUTHOR_SIZE _SIZE +DOC_COVER_COLOR _COLOR +DOC_COVER_COPYRIGHT_COLOR _COLOR +DOC_COVER_COPYRIGHT_FAMILY _FAMILY +DOC_COVER_COPYRIGHT_FONT _FONT +DOC_COVER_COPYRIGHT_QUAD _QUAD +DOC_COVER_COPYRIGHT_SIZE _SIZE +DOC_COVER_DOCTYPE_COLOR _COLOR +DOC_COVER_DOCTYPE_FAMILY _FAMILY +DOC_COVER_DOCTYPE_FONT _FONT +DOC_COVER_DOCTYPE_SIZE _SIZE +DOC_COVER_FAMILY _FAMILY +DOC_COVER_MISC_COLOR _COLOR +DOC_COVER_MISC_QUAD _QUAD +DOC_COVER_SUBTITLE_COLOR _COLOR +DOC_COVER_SUBTITLE_FAMILY _FAMILY +DOC_COVER_SUBTITLE_FONT _FONT +DOC_COVER_SUBTITLE_SIZE _SIZE +DOC_COVER_TITLE_COLOR _COLOR +DOC_COVER_TITLE_FAMILY _FAMILY +DOC_COVER_TITLE_FONT _FONT +DOC_COVER_TITLE_SIZE _SIZE +DOCHEADER_COLOR _COLOR +DOCHEADER_FAMILY _FAMILY +DOC_QUAD _QUAD +DOCTYPE_FAMILY _FAMILY +DOCTYPE_FONT _FONT +DOCTYPE_SIZE _SIZE +ENDNOTE_BLOCKQUOTE_AUTOLEAD Q_AUTOLEAD +ENDNOTE_BLOCKQUOTE_AUTOLEAD QUOTE_AUTOLEAD +ENDNOTE_FAMILY _FAMILY +ENDNOTE_FONT _FONT +ENDNOTE_LINENUMBER_FAMILY _FAMILY +ENDNOTE_LINENUMBER_FONT _FONT +ENDNOTE_LINENUMBER_SIZE _SIZE +ENDNOTE_NUMBER_FAMILY _FAMILY +ENDNOTE_NUMBER_FONT _FONT +ENDNOTE_NUMBER_SIZE _SIZE +ENDNOTE_QUAD _QUAD +ENDNOTE_QUOTE_AUTLOEAD Q_AUTOLEAD +ENDNOTE_QUOTE_AUTOLEAD QUOTE_AUTOLEAD +ENDNOTE_STRING_FAMILY _FAMILY +ENDNOTE_STRING_FONT _FONT +ENDNOTE_STRING_QUAD _QUAD +ENDNOTE_STRING_SIZE _SIZE +ENDNOTE_TITLE_FAMILY _FAMILY +ENDNOTE_TITLE_FONT _FONT +ENDNOTE_TITLE_QUAD _QUAD +ENDNOTE_TITLE_SIZE _SIZE +EPIGRAPH_COLOR _COLOR +EPIGRAPH_FAMILY _FAMILY +EPIGRAPH_FONT _FONT +EPIGRAPH_QUAD _QUAD +EPIGRAPH_SIZE _SIZE +FINIS_COLOR _COLOR +FOOTNOTE_COLOR _COLOR +FOOTNOTE_FAMILY _FAMILY +FOOTNOTE_FONT _FONT +FOOTNOTE_QUAD _QUAD +FOOTNOTE_SIZE _SIZE +HDRFTR_CENTER_FAMILY _FAMILY +HDRFTR_CENTER_FONT _FONT +HDRFTR_CENTER_SIZE _SIZE +HDRFTR_COLOR _COLOR +HDRFTR_FAMILY _FAMILY +HDRFTR_LEFT_FAMILY _FAMILY +HDRFTR_LEFT_FONT _FONT +HDRFTR_LEFT_SIZE _SIZE +HDRFTR_RIGHT_FAMILY _FAMILY +HDRFTR_RIGHT_FONT _FONT +HDRFTR_RIGHT_SIZE _SIZE +HDRFTR_RULE_COLOR _COLOR +HDRFTR_SIZE _SIZE +HEAD_COLOR _COLOR +HEAD_FAMILY _FAMILY +HEAD_FONT _FONT +HEAD_QUAD _QUAD +HEAD_SIZE _SIZE +LINEBREAK_COLOR _COLOR +LINENUMBER_FAMILY _COLOR +LINENUMBER_FONT _COLOR +LINENUMBER_SIZE _COLOR +LINENUMBER_COLOR _COLOR +MISC_COLOR _COLOR +MISC_QUAD _QUAD +PAGENUM_COLOR _COLOR +PAGENUM_FAMILY _FAMILY +PAGENUM_FONT _FONT +PARAHEAD_COLOR _COLOR +PARAHEAD_FAMILY _FAMILY +PARAHEAD_FONT _FONT +PARAHEAD_SIZE _SIZE +QUOTE_COLOR _COLOR +QUOTE_FAMILY _FAMILY +QUOTE_FONT _FONT +QUOTE_INDENT _INDENT +QUOTE_SIZE _SIZE +REF_INDENT INDENT_REFS +REF) REF_BRACKETS_END +REF] REF_BRACKETS_END +REF} REF_BRACKETS_END +REF( REF_BRACKETS_START +REF[ REF_BRACKETS_START +REF{ REF_BRACKETS_START +SUBHEAD_COLOR _COLOR +SUBHEAD_FAMILY _FAMILY +SUBHEAD_FONT _FONT +SUBHEAD_SIZE _SIZE +SUBTITLE_COLOR _COLOR +SUBTITLE_FAMILY _FAMILY +SUBTITLE_FONT _FONT +SUBTITLE_SIZE _SIZE +TITLE_COLOR _COLOR +TITLE_FAMILY _FAMILY +TITLE_FONT _FONT +TITLE_SIZE _SIZE +TOC_FAM _FAMILY +TOC_FAMILY _FAMILY +TOC_HEADER_FAMILY _FAMILY +TOC_HEADER_FONT _FONT +TOC_HEADER_QUAD _QUAD +TOC_HEADER_SIZE _SIZE +TOC_HEAD_FAMILY _FAMILY +TOC_HEAD_FONT _FONT +TOC_HEAD_SIZE _SIZE +TOC_PARAHEAD_FAMILY _FAMILY +TOC_PARAHEAD_FONT _FONT +TOC_PARAHEAD_SIZE _SIZE +TOC_PN_FAMILY _FAMILY +TOC_PN_FONT _FONT +TOC_PN_SIZE _SIZE +TOC_PT_SIZE _SIZE +TOC_SUBHEAD_FAMILY _FAMILY +TOC_SUBHEAD_FONT _FONT +TOC_SUBHEAD_SIZE _SIZE +TOC_TITLE_FAMILY _FAMILY +TOC_TITLE_FONT _FONT +TOC_TITLE_SIZE _SIZE + ++++The following are used to control underlining/underscoring weights+++ + +UNDERSCORE_WEIGHT RULE_WEIGHT +HEAD_UNDERLINE_WEIGHT RULE_WEIGHT +HEADER_RULE_WEIGHT RULE_WEIGHT +FOOTER_RULE_WEIGHT RULE_WEIGHT +FOOTNOTE_RULE_WEIGHT RULE_WEIGHT +COVER_UNDERLINE_WEIGHT RULE_WEIGHT +DOC_COVER_UNDERLINE_WEIGHT RULE_WEIGHT +ENDNOTE_STRING UNDERLINE_WEIGHT RULE_WEIGHT +ENDNOTE_TITLE UNDERLINE_WEIGHT RULE_WEIGHT +BIBLIOGRAPHY_STRING UNDERLINE_WEIGHT RULE_WEIGHT +</pre> + +<hr/> +<a href="appendices.html#TOP">Prev</a> +<a href="#TOP">Top</a> +<a href="toc.html">Back to Table of Contents</a> +</body> +</html> +<!-- vim: fileencoding=latin1: nomodified: +--> diff --git a/contrib/mom/momdoc/toc.html b/contrib/mom/momdoc/toc.html new file mode 100644 index 00000000..ab176fca --- /dev/null +++ b/contrib/mom/momdoc/toc.html @@ -0,0 +1,447 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!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=iso-8859-1"/> +<title>Mom, version 1.5 -- Table of Contents</title> +</head> +<body bgcolor="#dfdfdf"> + +<!-- ==================================================================== --> + +<h1 align="center"><u>Table of Contents for mom, version 1.5</u></h1> + +<p> +The table of contents has grown quite large. If you've been using +<strong>mom</strong> for a while, you might prefer the +<a href="macrolist.html#TOP"><strong>Quick Reference Guide</strong></a>. +</p> + +<p> +If you're new to <strong>mom</strong>, click on any link in the +<a href="#QUICK_TOC"><strong>Quick Table of Contents</strong></a> +to go to the +appropriate section of the <strong>Full Table of Contents</strong>. +</p> + +<p> +Alternatively, go directly to the +<a href="#TOC_PROP"><strong>Full Table of Contents</strong></a>. +</p> + +<hr/> + +<!-- -QUICK TABLE OF CONTENTS- --> + +<a name="QUICK_TOC"><h2><u>Quick Table of Contents</u></h2></a> + +<a href="#WHAT"><strong>INTRODUCTORY STUFF</strong></a> + +<ul> + <li><a href="#WHAT">What is mom?</a></li> + <li><a href="#DEFS">Definitions of terms used in this manual</a></li> + <li><a href="#USING">Using mom</a></li> +</ul> + +<a href="#TYPESET"><strong>TYPESETTING WITH MOM</strong></a> + +<ul> + <li><a href="#TYPE_INTRO">Intro to typesetting macros</a></li> + <li><a href="#PAGE">Page setup</a></li> + <li><a href="#PARAM">Basic typesetting parameters</a></li> + <li><a href="#JUST">Justifying, quadding, etc.</a></li> + <li><a href="#REFINE">Refinements</a></li> + <li><a href="#MOD">Modifying type</a></li> + <li><a href="#VERT">Vertical movements</a></li> + <li><a href="#TAB">Tabs</a></li> + <li><a href="#COL">Multiple columns</a></li> + <li><a href="#IND">Indents</a></li> + <li><a href="#GOODIES">Goodies</a></li> + <li><a href="#ESCAPES">Inline escapes</a></li> + <li><a href="#COLOR">Coloured text</a></li> + <li><a href="#GRAPHICAL">Graphical objects</a></li> +</ul> + +<a href="#DOCPROC"><strong>DOCUMENT PROCESSING WITH MOM</strong></a> + +<ul> + <li><a href="#DOCPROC">Introduction to document processing</a></li> + <li><a href="#PRELIM">Preliminary document setup</a></li> + <li><a href="#TAGS">The document element tags</a> — heads, subheads, footnotes, etc.</li> + <li><a href="#IMAGES">Inserting images into a document</a></li> + <li><a href="#HDRFTR">Page headers and footers</a></li> + <li><a href="#PAGINATE">Pagination</a></li> + <li><a href="#RV">Recto/verso printing and collating</a></li> + <li><a href="#COVER">Cover pages</a></li> + <li><a href="#REF">Bibliographies and references</a></li> + <li><a href="#LETTER">Writing letters</a></li> + <li><a href="#TYPEMACDOC">Using typesetting macros during document processing</a></li> + <li><a href="#QUICK">Quick reference guide to mom</a></li> + <li><a href="#APP">Appendices</a></li> +</ul> + +<hr/> + +<!-- -FULL TABLE OF CONTENTS- --> + +<a name="TOC_PROP"><h2><u>Full Table of Contents</u></h2></a> + +<a name="WHAT"></a> +<a href="intro.html#INTRO"><strong>1. WHAT IS MOM?</strong></a> + +<ul> + <li><a href="intro.html#INTRO_INTRO">1.1 Who is mom meant for?</a></li> + <li><a href="intro.html#INTRO_TYPESETTING">1.2 Typesetting with mom</a></li> + <li><a href="intro.html#INTRO_DOCPROCESSING">1.3 Document processing with mom</a></li> + <li><a href="intro.html#INTRO_PHILOSOPHY">1.4 Mom's philosophy</a></li> + <li><a href="intro.html#INTRO_DOCUMENTATION">1.5 A note on mom's documentation</a></li> + + <ul> + <li><a href="intro.html#MACRO_ARGS">1.5.1 How to read macro arguments</a></li> + <li><a href="intro.html#TOGGLE_MACRO">1.5.2 "Toggle" macros</a></li> + </ul> + +</ul> + +<a name="DEFS"></a> +<a href="definitions.html#TERMS"><strong>2. DEFINITIONS OF TERMS USED IN THIS MANUAL</strong></a> + +<ul> + <li><a href="definitions.html#TERMS_TYPESETTING">2.1 Typesetting terms</a></li> + <li><a href="definitions.html#TERMS_GROFF">2.2 Groff terms</a></li> + <li><a href="definitions.html#TERMS_MOM">2.3 Mom's document processing terms</a></li> +</ul> + +<a name="USING"></a> +<a href="using.html#USING"><strong>3. USING MOM</strong></a> + +<ul> + <li><a href="using.html#USING_INTRO">3.1 Introduction</a></li> + <li><a href="using.html#USING_MACROS">3.2 How to input mom's macros</a></li> + <li><a href="using.html#USING_INVOKING">3.3 Printing — invoking groff with mom</a></li> + <li><a href="using.html#USING_PREVIEWING">3.4 How to preview documents</a></li> +</ul> + +<!-- -TYPESETTING MACROS- --> + +<a name="TYPESET"></a> +<a href="typesetting.html#MACROS_TYPESETTING"><strong>4. THE TYPESETTING MACROS</strong></a> + +<ul> + <a name="TYPE_INTRO"></a> + <li><a href="typesetting.html#INTRO_MACROS_TYPESETTING"><strong>4.1 Introduction to the typesetting macros</strong></a></li> + + <a name="PAGE"></a> + <li><a href="typesetting.html#PAGE_MARGINS"><strong>4.2 Page Setup</strong></a> — paper size and page margins</li> + + <ul> + <li><a href="typesetting.html#INDEX_SETUP">4.2.1 Macro list</a></li> + </ul> + + <a name="PARAM"></a> + <li><a href="typesetting.html#BASIC_PARAMS"><strong>4.3 Basic Parameters</strong></a> — family, font, fallback font, point size, line space, line length, autolead</li> + + <ul> + <li><a href="typesetting.html#INDEX_BASIC">4.3.1 Macro list</a></li> + </ul> + + <a name="JUST"></a> + <li><a href="typesetting.html#JUST_QUAD_FILL"><strong>4.4 Justifying, Quadding, Filling and Breaking Lines</strong></a></li> + + <ul> + <li><a href="typesetting.html#INDEX_JUST">4.4.1 Macro list</a></li> + </ul> + + <a name="REFINE"></a> + <li><a href="typesetting.html#REFINEMENTS"><strong>4.5 Refinements</strong></a> — word space, sentence space, letter spacing (track kerning), hyphenation, kerning, ligatures</li> + + <ul> + <li><a href="typesetting.html#INDEX_REFINEMENTS">4.5.1 Macro list</a></li> + </ul> + + <a name="MOD"></a> + <li><a href="typesetting.html#MODIFICATIONS"><strong>4.6 Modifying Type</strong></a> — pseudo-italic, -bold, -condensed, and -extended</li> + + <ul> + <li><a href="typesetting.html#INDEX_MODIFICATIONS">4.6.1 Macro list</a></li> + </ul> + + <a name="VERT"></a> + <li><a href="typesetting.html#ALDRLD"><strong>4.7 Vertical Movements</strong></a> — moving up and down on the page</li> + + <ul> + <li><a href="typesetting.html#INDEX_ALDRLD">4.7.1 Macro list</a></li> + </ul> + + <a name="TAB"></a> + <li><a href="typesetting.html#TABS"><strong>4.8 Tabs</strong></a></li> + + <ul> + <li><a href="typesetting.html#TYPESETTING_TABS">4.8.1 Typesetting tabs</a></li> + + <ul> + <li><a href="typesetting.html#TYPESETTING_TABS_TUT">4.8.1.1 Quickie tutorial</a></li> + </ul> + + <li><a href="typesetting.html#STRING_TABS">4.8.2 String tabs (autotabs)</a></li> + + <ul> + <li><a href="typesetting.html#STRING_TABS_TUT">4.8.2.1 Quickie tutorial</a></li> + </ul> + + <li><a href="typesetting.html#INDEX_TABS">4.8.3 Macro list</a></li> + </ul> + + <a name="COL"></a> + <li><a href="typesetting.html#MULTI_COLUMNS"><strong>4.9 Multi-columns</strong></a></li> + + <ul> + <li><a href="typesetting.html#INDEX_MULTI_COLUMNS">4.9.1 Macro list</a></li> + </ul> + + <a name="IND"></a> + <li><a href="typesetting.html#INDENTS"><strong>4.10 Indents</strong></a></li> + + <ul> + <li><a href="typesetting.html#INDENTS_TUT">4.10.1 A brief explanation of how mom handles indents</a></li> + <li><a href="typesetting.html#INDEX_INDENTS">4.10.2 Macro list</a></li> + </ul> + + <a name="GOODIES"></a> + <li><a href="goodies.html#GOODIES"><strong>4.11 Goodies</strong></a> + — aliases, transparent lines, smartquotes, caps, + underscoring/underlining, padding lines, leaders, drop + caps, superscripts, (nested) lists, user-definable strings, + changing the escape character</li> + + <ul> + <li><a href="goodies.html#INDEX_GOODIES">4.11.1 Macro list</a></li> + </ul> + + <a name="ESCAPES"></a> + <li><a href="inlines.html#INLINE_ESCAPES"><strong>4.12 Inline Escapes</strong></a></li> + + <ul> + <li><a href="inlines.html#INTRO_INLINE_ESCAPES">4.12.1 Introduction to inline escapes</a></li> + <li><a href="inlines.html#INLINES_MOM">4.12.2 Mom's personal inlines</a></li> + <li><a href="inlines.html#INLINES_GROFF">4.12.3 Groff inlines</a></li> + <li><a href="inlines.html#INLINE_CHARACTERS_GROFF">4.12.3.1 Inlines for special characters and symbols</a></li> + </ul> + + <a name="COLOR"></a> + <li><a href="color.html#TOP"><strong>4.13 Coloured text</strong></a></li> + + <ul> + <li><a href="color.html#INTRO_COLOR">4.13.1 Introduction to coloured text</a></li> + <li><a href="color.html#MACROS_COLOR">4.13.2 Macro list</a></li> + </ul> + + <a name="GRAPHICAL"></a> + <li><a href="graphical.html#TOP"><strong>4.14 Graphical objects</strong></a> + — horizontal and vertical rules, boxes, ellipses (circles)</li> + + <ul> + <li><a href="graphical.html#INTRO_GRAPHICAL">4.14.1 Introduction to graphical objects</a></li> + <li><a href="graphical.html#MACROS_GRAPHICAL">4.13.2 Macro list</a></li> + </ul> + +</ul> + +<!-- -DOCUMENT PROCESSING MACORS- --> + +<a name="DOCPROC"></a> +<a href="docprocessing.html#DOCPROCESSING"><strong>5. DOCUMENT PROCESSING WITH MOM</strong></a> + +<ul> + <li><a href="docprocessing.html#INTRO_MACROS_DOCPROCESSING"><strong>5.1 Introduction to document processing</strong></a></li> + <li><a href="docprocessing.html#DEFAULTS"><strong>5.2 Some document defaults</strong></a></li> + + <ul> + <li><a href="docprocessing.html#LEADING_NOTE">IMPORTANT NOTE on leading/spacing and bottom margins</a></li> + <li><a href="docprocessing.html#SHIM">The SHIM macro</a> — to get document leading back on track</li> + </ul> + + <a name="PRELIM"></a> + <li><a href="docprocessing.html#SETUP"><strong>5.3 PRELIMINARY DOCUMENT SETUP</strong></a></li> + + <ul> + <li><a href="docprocessing.html#DOCPROCESSING_TUT">5.3.1 Tutorial</a> — setting up a mom document</li> + <li><a href="docprocessing.html#REFERENCE_MACROS"><strong>5.3.2 The Reference Macros</strong></a> — giving <strong>mom</strong> the information she needs to do her job</li> + + <ul> + <li><a href="docprocessing.html#TITLE">5.3.2.1 TITLE</a></li> + <li><a href="docprocessing.html#DOC_TITLE">5.3.2.2 DOCTITLE</a></li> + <li><a href="docprocessing.html#SUBTITLE">5.3.2.3 SUBTITLE</a></li> + <li><a href="docprocessing.html#AUTHOR">5.3.2.4 AUTHOR</a></li> + <li><a href="docprocessing.html#CHAPTER">5.3.2.5 CHAPTER</a></li> + <li><a href="docprocessing.html#CHAPTER_TITLE">5.3.2.6 CHAPTER_TITLE</a></li> + <li><a href="docprocessing.html#DRAFT">5.3.2.7 DRAFT</a></li> + <li><a href="docprocessing.html#REVISION">5.3.2.8 REVISION</a></li> + <li><a href="docprocessing.html#COPYRIGHT">5.3.2.9 COPYRIGHT</a></li> + <li><a href="docprocessing.html#MISC">5.3.2.10 MISC</a></li> + <li><a href="docprocessing.html#COVERTITLE">5.3.2.11 COVER_TITLE</a></li> + <li><a href="docprocessing.html#COVERTITLE">5.3.2.12 DOC_COVER_TITLE</a></li> + </ul> + + <li><a href="docprocessing.html#DOCSTYLE_MACROS"><strong>5.3.3 The Docstyle Macros</strong></a> — telling <strong>mom</strong> what kind of document you're creating and how you want it to look overall</li> + + <ul> + <li><a href="docprocessing.html#DOCTYPE">5.3.3.1 DOCTYPE</a> — kind of document</li> + <li><a href="docprocessing.html#PRINTSTYLE">5.3.3.2 PRINTSTYLE</a> — typeset or typewrite</li> + <li><a href="docprocessing.html#COPYSTYLE">5.3.3.3 COPYSTYLE</a> — draft or final</li> + </ul> + + <li><a href="docprocessing.html#START_MACRO"><strong>5.3.4 Initiate document processing</strong></a></li> + + <ul> + <li><a href="docprocessing.html#START">5.3.4.1 START</a> — the required macro to initiate document processing</li> + </ul> + + <li><a href="docprocessing.html#STYLE_BEFORE_START"><strong>5.3.5 Changing global typesetting and formatting parameters <em>before</em> START</strong></a></li> + + <ul> + <li><a href="docprocessing.html#TYPE_BEFORE_START">5.3.5.1 Using the typesetting macros before START</a></li> + + <ul> + <li><a href="docprocessing.html#INCLUDE">Including (sourcing) style sheets and files</a></li> + <li><a href="docprocessing.html#COLOR">Initializing colours</a></li> + </ul> + + <li><a href="docprocessing.html#DOC_LEAD_ADJUST">5.3.5.2 DOC_LEAD_ADJUST</a> — adjust a document's + <a href="definitions.html#TERMS_LEADING">leading</a> + (line spacing) to fill pages</li> + <li><a href="docprocessing.html#DOCHEADER">5.3.5.3 DOCHEADER</a> — managing the + <a href="definitions.html#TERMS_DOCHEADER">document header</a></li> + <li><a href="docprocessing.html#COLUMNS_INTRO">5.3.5.4 COLUMNS</a> — setting documents in columns</li> + </ul> + + <li><a href="docprocessing.html#DOC_PARAM_MACROS"><strong>5.3.6 Changing global style parameters <em>after</em> START</strong></a></li> + + <ul> + <li><a href="docprocessing.html#INDEX_DOC_PARAM">5.3.6.1 Macro list</a></li> + </ul> + + <a name="TYPEMACDOC"></a> + <li><a href="typemacdoc.html#TYPESETTING"><strong>5.3.7 Using the typesetting macros during document processing</strong></a></li> + </ul> + + <a name="TAGS"></a> + <li><a href="docelement.html#DOCELEMENT"><strong>5.4 THE DOCUMENT ELEMENT TAGS</strong></a></li> + + <ul> + <li><a href="docelement.html#DOCELEMENT_INTRO">5.4.1 Introduction to the document element tags</a></li> + + <ul> + <li><a href="docelement.html#DOCELEMENT_CONTROL">Control macros</a> — changing style defaults for document element tags</li> + <li><a href="docelement.html#CONTROL_MACRO_ARGS">Arguments to the control macros</a></li> + </ul> + + <li><a href="docelement.html#EPIGRAPH_INTRO">5.4.2 Epigraphs</a></li> + <li><a href="docelement.html#PP_INTRO">5.4.3 Paragraphs</a></li> + <li><a href="docelement.html#HEAD_INTRO">5.4.4 Main heads</a></li> + <li><a href="docelement.html#SUBHEAD_INTRO">5.4.5 Subheads</a></li> + <li><a href="docelement.html#PARAHEAD_INTRO">5.4.6 Paragraph heads</a></li> + <li><a href="docelement.html#LINEBREAK_INTRO">5.4.7 Linebreaks</a> — author linebreaks (section breaks)</li> + <li><a href="docelement.html#QUOTE_INTRO">5.4.8 Quotes</a> — line for line poetic quotes or unformatted, verbatim text (e.g. code snippets)</li> + <li><a href="docelement.html#BLOCKQUOTE_INTRO">5.4.9 Blockquotes</a> — cited material</li> + <li><a href="docelement.html#CODE">5.4.10 Code</a> — inserting code snippets into documents</li> + <li><a href="docelement.html#LIST_INTRO">5.4.11 Lists</a> — (nested) lists</li> + <li><a href="docelement.html#NUMBER_LINES_INTRO">5.4.12 Line numbering</a></li> + <li><a href="docelement.html#FOOTNOTE_INTRO">5.4.13 Footnotes</a></li> + <li><a href="docelement.html#ENDNOTE_INTRO">5.4.14 Endnotes</a></li> + <li><a href="docelement.html#MARGIN_NOTES_INTRO">5.4.15 Margin notes</a></li> + <li><a href="docelement.html#BLANK_PAGE_TITLE">5.4.16 Blank pages</a></li> + <li><a href="docelement.html#FINIS_INTRO">5.4.17 Document termination string</a> — FINIS</li> + <li><a href="docelement.html#TOC_INTRO">5.4.18 Tables of contents</a></li> + </ul> + + <a name="IMAGES"></a> + <li><a href="docelement.html#PSPIC"><strong>5.5 INSERTING IMAGES INTO A DOCUMENT</strong></a></li> + + <a name="HDRFTR"></a> + <li><a href="headfootpage.html#HEADFOOTPAGE"><strong>5.6 PAGE HEADERS AND FOOTERS</strong></a></li> + + <ul> + <li><a href="headfootpage.html#HEADFOOTPAGE_INTRO">5.6.1 Introduction</a></li> + <li><a href="headfootpage.html#DESCRIPTION_GENERAL">5.6.2 General description of headers/footers</a></li> + <li><a href="headfootpage.html#HEADER_STYLE">5.6.3 Default specs for headers/footers</a></li> + <li><a href="headfootpage.html#VERTICAL_SPACING">5.6.4 Vertical placement and spacing of headers/footers</a></li> + <li><a href="headfootpage.html#HEADFOOT_MANAGEMENT">5.6.5 Managing headers/footers</a></li> + + <ul> + <li><a href="headfootpage.html#USERDEF_HDRFTR">5.6.5.1 User-defined, single string recto/verso headers/footers</a></li> + </ul> + + <li><a href="headfootpage.html#HEADFOOT_CONTROL">5.6.6 Control macros for headers/footers</a></li> + </ul> + + <a name="PAGINATE"></a> + <li><a href="headfootpage.html#PAGINATION"><strong>5.7 PAGINATION</strong></a></li> + + <ul> + <li><a href="headfootpage.html#PAGINATION">Introduction</a></li> + <li><a href="headfootpage.html#INDEX_PAGINATION">Pagination macros list</a></li> + </ul> + + <a name="RV"></a> + <li><a href="rectoverso.html#RECTOVERSO"><strong>5.8 RECTO/VERSO PRINTING, COLLATING</strong></a></li> + + <ul> + <li><a href="rectoverso.html#RECTOVERSO_INTRO">5.8.1 Introduction to recto/verso</a></li> + + <ul> + <li><a href="rectoverso.html#RECTOVERSO_LIST">5.8.1.1 Macro list</a></li> + </ul> + + <li><a href="rectoverso.html#COLLATE_INTRO">5.8.2 Introduction to collating</a></li> + + <ul> + <li><a href="rectoverso.html#COLLATE">5.8.2.1 The COLLATE macro</a></li> + </ul> + + </ul> + + <a name="COVER"></a> + <li><a href="cover.html#COVER_TOP"><strong>5.9 CREATING COVER PAGES</strong></a></li> + + <a name="REF"></a> + <li><a href="refer.html#REF_INTRO"><strong>5.10 BIBLIOGRAPHIES AND REFERENCES</strong></a></li> + + <a name="LETTER"></a> + <li><a href="letters.html#LETTERS"><strong>5.11 WRITING LETTERS</strong></a></li> + + <ul> + <li><a href="letters.html#LETTERS_INTRO">5.11.1 Introduction to writing letters</a></li> + <li><a href="letters.html#TUTORIAL">5.11.2 Tutorial on writing letters</a></li> + <li><a href="letters.html#LETTERS_DEFAULTS">5.11.3 Default style for letters</a></li> + <li><a href="letters.html#LETTERS_MACROS">5.11.4 The letter macros</a></li> + </ul> + +</ul> + +<a name="QUICK"></a> +<a href="macrolist.html#QUICK"><strong>6. QUICK REFERENCE GUIDE TO MOM</strong></a> +<br/> + +<a name="APP"></a> +<a href="appendices.html#APPENDICES"><strong>7. APPENDICES</strong></a> + +<ul> + <li><a href="appendices.html#MOREDOC">7.1 Further notes on this documentation</a></li> + <li><a href="appendices.html#FONTS">7.2 Adding PostScript fonts to groff</a></li> + + <ul> + <li><a href="appendices.html#HOWTO">7.2.1 How to create a PostScript font for use with groff</a></li> + </ul> + + <li><a href="appendices.html#CODENOTES">7.3 Some reflections on mom</a></li> + <li><a href="reserved.html#RESERVED">7.5 List of reserved words</a> + — complete list of macros, registers, strings, aliases and diversions</li> + <li><a href="appendices.html#CONTACT">7.5 Contact the author</a></li> +</ul> + +</body> +</html> + +<!-- vim: fileencoding=latin1: nomodified: +--> diff --git a/contrib/mom/momdoc/typemacdoc.html b/contrib/mom/momdoc/typemacdoc.html new file mode 100644 index 00000000..52975b94 --- /dev/null +++ b/contrib/mom/momdoc/typemacdoc.html @@ -0,0 +1,299 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!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=iso-8859-1"/> +<title>Mom -- Typesetting macros in document processing</title> +</head> +<body bgcolor="#dfdfdf"> + +<!-- ==================================================================== --> + +<a name="TOP"></a> + +<p> +<a href="docelement.html#TOP">Next</a> +<a href="docprocessing.html#TOP">Prev</a> +<a href="toc.html">Back to Table of Contents</a> +</p> + +<a name="TYPESETTING"><h1 align="center"><u>Using the typesetting macros during document processing</u></h1></a> + +<p> +<a href="#BEHAVIOUR">Typesetting macro behaviour</a> +<br/> + +<a href="#TB_MARGINS">Top and bottom margins in document processing</a> +<br/> + +<a href="#SPACE">Inserting space at the top of a page</a> +<br/> + + * <a href="#ADD_SPACE">ADD_SPACE</a> +</p> + +<a name="BEHAVIOUR"><h2><u>Typesetting macro behaviour</u></h2></a> + +<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#TERMS_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> +<strong>Mom</strong>'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#TERMS_FAMILY">family</a>, +<a href="definitions.html#TERMS_FONT">font</a>, +<a href="definitions.html#TERMS_PS">point size</a>, +<a href="definitions.html#TERMS_LEADING">leading</a>, +and +<a href="definitions.html#TERMS_QUAD">quad</a>. +</p> + +<p> +<strong>Mom</strong> assumes that any changes to these parameters +stem from a temporary need to set type in a style different from +that provided by <strong>mom</strong>'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 <strong>mom</strong> 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 <strong>mom</strong> +to put space at the tops of pages after the first.) +</p> + +<pre> +MACRO EFFECT DURING DOCUMENT PROCESSING +----- --------------------------------- + +L_MARGIN *The left margin of all running text + assumes the new value. + + *The line length remains unaltered. + + *The header and footer left margin + remain at the current document default. + + (You won't use this often by itself. Most + likely, you'll use it in combination with + R_MARGIN or LL.) + +R_MARGIN *The right margin of all running text + assumes the new value. In other words, + the line length is altered. + + *The header and footer right margin + remain at the current document default. + +LL *The line length of all running text + is set to the new value. + + *The header and footer line length remain + at the current document default. + +FAMILY *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 *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. — \*[SLANT] and \*[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. + \*[COND] and \*[EXT] behave similarly. + +PT_SIZE *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 *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't align with the bottom margin + of subsequent pages. You'll need to use the SHIM + macro to get mom back on track when you're ready + to return to the document's default leading. + +QUAD *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. — Line-for-line quadding macros + (LEFT, CENTER, RIGHT) are also temporary, + overridden by the QUAD value of any subsequent + document element tag. +</pre> + +<hr/> + +<!-- ===================================================================== --> + +<a name="TB_MARGINS"><h2><u>Top and bottom margins in document processing</u></h2></a> + +<p> +Normally, <strong>mom</strong> establishes the top and bottom +margins of +<a href="definitions.html#TERMS_RUNNING">running text</a> +in documents from the values of <strong>HEADER_MARGIN + +HEADER_GAP</strong> and <strong>FOOTER_MARGIN + FOOTER_GAP</strong> +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 +<strong>HEADER_GAP</strong> and <strong>FOOTER_GAP</strong>. +</p> + +<p> +Put another way, in document processing, <strong>T_MARGIN</strong> +and <strong>B_MARGIN</strong> set the top and bottom margins of +running text, but have no effect on the placement of +<a href="definitions.html#TERMS_HEADER">headers</a>, +<a href="definitions.html#TERMS_FOOTER">footers</a>, +or page numbers. +</p> + +<hr/> + +<!-- ==================================================================== --> + +<a name="SPACE"><h2><u>Inserting space at the top of a page</u></h2></a> + +<p> +Occasionally, you may want to insert space before the start of +<a href="definitions.html#TERMS_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 <strong>mom</strong> +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, +<strong>ADD_SPACE</strong>, in conjuction with +<a href="typesetting.html#NEWPAGE">NEWPAGE</a>. +</p> + +<!-- -ADD_SPACE- --> + +<hr width="66%" align="left"/> + +<a name="ADD_SPACE"></a> + +<p> +<nobr>Macro: <strong>ADD_SPACE</strong> <kbd><amount of space></kbd></nobr> +<br/> + +<em>*Requires a <a href="definitions.html#TERMS_UNITOFMEASURE">unit of measure</a></em> +</p> + +<p> +<strong>ADD_SPACE</strong> takes as its single argument the distance +you want <strong>mom</strong> to advance from the normal baseline +position at the top of the page. A +<a href="definitions.html#TERMS_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#TERMS_RUNNING">running text</a> +on a page other than the first. You'd accomplish it with + +<pre> + .NEWPAGE + .ADD_SPACE 2i +</pre> + +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 +<strong>mom</strong>'s ability to guarantee perfectly flush bottom +margins, I highly recommend using the +<a href="docprocessing.html#SHIM">SHIM</a> +macro immediately after <strong>ADD_SPACE</strong>. +</p> + +<hr/> + +<p> +<a href="docelement.html#TOP">Next</a> +<a href="docprocessing.html#TOP">Prev</a> +<a href="#TOP">Top</a> +<a href="toc.html">Back to Table of Contents</a> +</p> + +</body> +</html> + +<!-- vim: fileencoding=latin1: nomodified: +--> diff --git a/contrib/mom/momdoc/typesetting.html b/contrib/mom/momdoc/typesetting.html new file mode 100644 index 00000000..fb616fc2 --- /dev/null +++ b/contrib/mom/momdoc/typesetting.html @@ -0,0 +1,5084 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!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=iso-8859-1"/> +<title>Mom -- Typesetting Macros</title> +</head> +<body bgcolor="#dfdfdf"> + +<!-- ==================================================================== --> + +<a name="TOP"></a> + +<p> +<a href="goodies.html#TOP">Next</a> +<a href="definitions.html#TOP">Prev</a> +<a href="toc.html">Back to Table of Contents</a> +</p> + +<a name="MACROS_TYPESETTING"><h1 align="center"><u>The typesetting macros</u></h1></a> + +<ul> + <li><a href="#INTRO_MACROS_TYPESETTING"><strong>Introduction to the typesetting macros</strong></a></li> + <br/> + + <li><strong>PAGE SETUP</strong></li> + <ul> + <li><a href="#INTRO_SETUP">Introduction to Page Setup</a></li> + <li><a href="#INDEX_SETUP">List of macros</a></li> + </ul> + <li><strong>BASIC TYPESETTING PARAMETERS</strong></li> + <ul> + <li><a href="#INTRO_BASIC_PARAMS">Introduction to Basic Parameters</a></li> + <li><a href="#INDEX_BASIC">List of macros</a></li> + </ul> + <li><strong>JUSTIFYING, QUADDING, FILLING, BREAKING and JOINING LINES</strong></li> + <ul> + <li><a href="#JUST_QUAD_FILL">Introduction to justify, quad, fill, break</a></li> + <li><a href="#INDEX_JUST">List of macros</a></li> + </ul> + <li><strong>TYPOGRAPHIC REFINEMENTS</strong></li> + <ul> + <li><a href="#INTRO_REFINEMENTS">Introduction to typographic refinements</a></li> + <li><a href="#INDEX_REFINEMENTS">List of macros</a></li> + </ul> + <li><strong>TYPE MODIFICATIONS — pseudo italic, bold, condense, extend</strong></li> + <ul> + <li><a href="#MODIFICATIONS">Introduction to type modifications</a></li> + <li><a href="#INDEX_MODIFICATIONS">List of macros</a></li> + </ul> + <li><strong>VERTICAL MOVEMENTS</strong></li> + <ul> + <li><a href="#ALDRLD">Introduction to vertical movements</a></li> + <li><a href="#INDEX_ALDRLD">List of macros</a></li> + </ul> + <li><strong>TABS</strong></li> + <ul> + <li><a href="#TABS">Introduction to tabs</a></li> + <li><a href="#TYPESETTING_TABS">Typesetting tabs</a></li> + <ul> + <li><a href="#TYPESETTING_TABS_TUT">Quickie tutorial</a></li> + </ul> + <li><a href="#STRING_TABS">String tabs</a></li> + <ul> + <li><a href="#STRING_TABS_TUT">Quickie tutorial</a></li> + </ul> + <li><a href="#INDEX_TABS">List of macros</a></li> + </ul> + <li><strong>MULTI-COLUMNS</strong></li> + <ul> + <li><a href="#MULTI_COLUMNS">Introduction to multi-columns</a></li> + <li><a href="#INDEX_MULTI_COLUMNS">List of macros</a></li> + </ul> + <li><strong>INDENTS</strong></li> + <ul> + <li><a href="#INDENTS">Introduction to indents</a></li> + <li><a href="#INDEX_INDENTS">List of macros</a></li> + </ul> + <li><strong>GOODIES</strong></li> + <ul> + <li><a href="goodies.html#GOODIES">Introduction to goodies</a></li> + <li><a href="goodies.html#INDEX_GOODIES">List of macros</a></li> + </ul> + <li><strong>INLINE ESCAPES</strong></li> + <ul> + <li><a href="inlines.html#INTRO_INLINE_ESCAPES">Introduction to inline escapes</a></li> + <li><a href="inlines.html#INDEX_INLINES">List of inline escapes</a></li> + </ul> + <li><strong>COLOURED TEXT</strong></li> + <ul> + <li><a href="color.html#INTRO_COLOR">Introduction to coloured text</a></li> + <li><a href="color.html#MACROS_COLOR">Macro list</a></li> + </ul> +</ul> + +<hr/> + +<h2><a name="INTRO_MACROS_TYPESETTING"><u>Introduction to the typesetting macros</u></a></h2> + +<p> +<strong>Mom</strong>'s typesetting macros provide access to groff's +typesetting capabilities. Aside from controlling basic type +parameters (family, font, line length, point size, leading), +<strong>mom</strong>'s macros fine-tune wordspacing, letterspacing, +kerning, hyphenation, and so on. In addition, <strong>mom</strong> +has true typesetting tabs, string tabs, multiple indent styles, line +padding, and a batch of other goodies. +</p> + +<p> +In some cases, <strong>mom</strong>'s typesetting macros merely +imitate groff primitives. In others, they approach typesetting +concerns in conceptually new ways (for groff, at least). This +should present no problem for newcomers to groff who are learning +<strong>mom</strong>. Old groff hands should be careful. Just +because it looks like a duck and walks like a duck does not, in this +instance, mean that it is a duck. When using <strong>mom</strong>, +stay away from groff primitives if <strong>mom</strong> provides a +macro that accomplishes the same thing. +</p> + +<p> +<strong>Mom</strong>'s typesetting macros can be used as a +standalone package, independent of the +<a href="docprocessing.html#DOCPROCESSING">document processing macros</a>. +With them, you can typeset on-the-fly. Book covers, your best +friend's résumé, a poster for a lost dog — none of these requires +structured document processing (page headers, paragraphs, heads, +footnotes, etc). What they do demand is precise control over every +element on the page. The typesetting macros give you that control. +</p> + +<hr/> + +<!-- ==================================================================== --> + +<a name="INTRO_SETUP"></a> + +<a name="PAGE_MARGINS"><h2><u>Page setup: paper size and page margins</u></h2></a> + +<p> +The page setup macros establish the physical dimensions of your page +and the margins you want it to have. <strong>Groff</strong> has +defaults for these, but I recommend setting them at the top of your +files anyway unless you're using <strong>mom</strong>'s +<a href="docprocessing.html#DOCPROCESSING">document processing macros</a> +and are content with her defaults. +</p> + +<p> +The +<a href="#PAPER">PAPER</a> +macro provides a shortcut for setting the page to the correct +dimensions for a number of well-known, established paper sizes. The +<a href="#PAGE">PAGE</a> +macro provides a convenient way of setting the page dimensions and +some or all of the page margins with a single macro. +</p> + +<a name="DIMENSIONS_NOTE"><h3><u>Important note on page dimensions and papersize</u></h3></a> + +<p> +<strong>Mom</strong>'s macros for setting up the desired size of +printer sheets (the "papersize") tell <strong>mom</strong> +and <strong>groff</strong> about the page dimensions, but not the +driver responsible for generating the final PostScript file. You +<em><strong>must</strong></em> take care of this yourself. +</p> + +<p> +If you routinely print documents on the same size paper (you +probably do), the easiest way to make sure the PostScript driver +knows about your papersize is to edit the file + +<pre> + <path to groff>/font/devps/DESC +</pre> + +In it, you will see a line that reads + +<pre> + papersize <papersize> +</pre> + +Change <kbd><papersize></kbd> to either the name of your +papersize (e.g. a4, letter, legal, etc.; a full list of valid named +papersizes that can be used in DESC is found in +<nobr><kbd>man papersize</kbd></nobr>. If your routine papersize is +non-standard (i.e. doesn't have a "name") you can give +the dimensions for your papersize, separated by a comma. The +dimensions <em><strong>must</strong></em> have a +<a href="definitions.html#TERMS_UNITOFMEASURE">unit of measure</a> +appended. Valid units of measure for papersize are +inches <nobr>(<kbd>i</kbd>),</nobr> +centimeters <nobr>(<kbd>c</kbd>),</nobr> +picas <nobr>(<kbd>P</kbd>)</nobr> and +points <nobr>(<kbd>p</kbd>).</nobr> +</p> + +<p> +For example, to set up a routine papersize of 8 inches by 10 inches, +the line would look like this: + +<pre> + papersize 8i,10i +</pre> +</p> + +<p> +Having set up your routine papersize, if you occasionally need +to print on sheets that do not conform to its dimensions, +you <em><strong>must</strong></em>, in addition to setting +the page dimensions in your <strong>mom</strong> file, +invoke <strong>groff</strong> on the command line with the +<kbd>-P-p<papersize></kbd> option. +</p> + +<p> +For example, suppose your routine papersize is "letter", +and you need to print something on a "legal"-sized sheet. +After telling <strong>mom</strong> about the legal-size sheet (with +either +<a href="#PAGELENGTH">PAGELENGTH</a> +and +<a href="#PAGEWIDTH">PAGEWIDTH</a>, +or +<a href="#PAPER">PAPER</a>, +or +<a href="#PAGE">PAGE</a>, +in your <strong>mom</strong> file, when you invoke +<strong>groff</strong> to process the file, the command would look +like this: + +<pre> + groff -mom -P-plegal +</pre> +</p> + +<p> +Consult <nobr><kbd>man groff</kbd></nobr>, +<nobr><kbd>man grops</kbd></nobr> and +<nobr><kbd>man groff_font</kbd></nobr> for additional information +concerning papersizes, as well as information on printing in +"landscape" orientation. +</p> + +<a name="INDEX_SETUP"><h3><u>Page setup macros list</u></h3></a> + +<ul> + <li><a href="#PAGEWIDTH">PAGEWIDTH</a> (page width)</li> + <li><a href="#PAGELENGTH">PAGELENGTH</a> (page length)</li> + <li><a href="#PAPER">PAPER</a> (common paper sizes)</li> + <li><a href="#L_MARGIN">L_MARGIN</a> (left margin)</li> + <li><a href="#R_MARGIN">R_MARGIN</a> (right margin)</li> + <li><a href="#T_MARGIN">T_MARGIN</a> (top margin)</li> + <li><a href="#B_MARGIN">B_MARGIN</a> (bottom margin)</li> + <li><a href="#PAGE">PAGE</a> (page dimensions and margins all in one fell swoop)</li> + <li><a href="#NEWPAGE">NEWPAGE</a> (start a new page)</li> +</ul> + +<!-- -PAGEWIDTH- --> + +<hr width="66%" align="left"/> + +<a name="PAGEWIDTH"><h3><u>Page width</u></h3></a> + +<p> +<nobr>Macro: <strong>PAGEWIDTH</strong> <kbd><width of printer sheet></kbd></nobr> +<br/> + +<em>*Requires a <a href="definitions.html#TERMS_UNITOFMEASURE">unit of measure</a></em> +</p> + +<p> +The argument to <strong>PAGEWIDTH</strong> is the width of your +printer sheet. <strong>PAGEWIDTH</strong> requires a unit of measure. +Decimal fractions are allowed. Hence, to tell <strong>mom</strong> +the width of your printer sheet is 8-1/2 inches, you enter + +<pre> + .PAGEWIDTH 8.5i +</pre> +</p> + +<p> +Please read the +<a href="#DIMENSIONS_NOTE">Important note on page dimensions and papersize</a> +for information on ensuring <strong>groff</strong> respects your +<strong>PAGEWIDTH</strong>. +</p> + +<!-- -PAGELENGTH- --> + +<hr width="33%" align="left"/> + +<a name="PAGELENGTH"><h3><u>Page length</u></h3></a> + +<p> +<nobr>Macro: <strong>PAGELENGTH</strong> <kbd><length of printer sheet></kbd></nobr> +<br/> + +<em>*Requires a <a href="definitions.html#TERMS_UNITOFMEASURE">unit of measure</a></em> +</p> + +<p> +<strong>PAGELENGTH</strong> tells <strong>mom</strong> how long your +printer sheet is. It works just like +<strong>PAGEWIDTH</strong>. Therefore, to tell +<strong>mom</strong> your printer sheet is 11 inches long, you +enter + +<pre> + .PAGELENGTH 11i +</pre> +</p> + +<p> +Please read the +<a href="#DIMENSIONS_NOTE">Important note on page dimensions and papersize</a> +for information on ensuring <strong>groff</strong> respects your +<strong>PAGELENGTH</strong>. +</p> + +<!-- -PAPER- --> + +<hr width="33%" align="left"/> + +<a name="PAPER"><h3><u>Paper</u></h3></a> + +<p> +<nobr>Macro: <strong>PAPER</strong> <kbd><paper type></kbd></nobr> +</p> + +<p> +<strong>PAPER</strong> provides a convenient way to set the page +dimensions for some common printer sheet sizes. <nobr><paper +type> can be one of:</nobr> + +<pre> + LETTER + LEGAL + STATEMENT + TABLOID + LEDGER + FOLIO + QUARTO + 10x14 + EXECUTIVE + A3 + A4 + A5 + B4 + B5 +</pre> +</p> + +<p> +Say, for example, you have A4-sized sheets in your printer. It's +shorter (and easier) to enter + +<pre> + .PAPER A4 +</pre> + +than to remember the correct dimensions and enter + +<pre> + .PAGEWIDTH 595p + .PAGELENGTH 842p +</pre> +</p> + +<p> +Please read the +<a href="#DIMENSIONS_NOTE">Important note on page dimensions and papersize</a> +for information on ensuring <strong>groff</strong> respects your +<strong>PAPER</strong> size. +</p> + +<!-- -L_MARGIN- --> + +<hr width="33%" align="left"/> + +<a name="L_MARGIN"><h3><u>Left margin</u></h3></a> + +<p> +<nobr>Macro: <strong>L_MARGIN</strong> <kbd><left margin></kbd></nobr> +<br/> + +<em>*Requires a <a href="definitions.html#TERMS_UNITOFMEASURE">unit of measure</a></em> +</p> + +<p> +<strong>L_MARGIN</strong> establishes the distance from the left edge +of the printer sheet at which you want your type to start. It may +be used any time, and remains in effect until you enter a new value. +</p> + +<p> +<a href="#IL">Left indents</a> +and +<a href="#TABS">tabs</a> +are calculated from the value you pass to <strong>L_MARGIN</strong>, +hence it's always a good idea to invoke it before starting any +serious typesetting. A unit of measure is required. Decimal +fractions are allowed. Therefore, to set the left margin at 3 picas +(1/2 inch), you'd enter either + +<pre> + .L_MARGIN 3P + or + .L_MARGIN .5i +</pre> +</p> + +<p> +If you use the macros +<a href="#PAGE">PAGE</a>, +<a href="#PAGEWIDTH">PAGEWIDTH</a> +or +<a href="#PAPER">PAPER</a> +without invoking <strong>L_MARGIN</strong> (either before +or afterwards), <strong>mom</strong> automatically sets +<strong>L_MARGIN</strong> to 1 inch. +</p> + +<p> +<strong>NOTE: L_MARGIN</strong> behaves in a special way when you're +using the +<a href="docprocessing.html#DOCPROCESSING">document processing macros</a>. +See +<a href="typemacdoc.html#TYPESETTING">Typesetting Macros in Document Processing</a> +for an explanation. +</p> + +<!-- -R_MARGIN- --> + +<hr width="33%" align="left"/> + +<a name="R_MARGIN"><h3><u>Right margin</u></h3></a> + +<p> +<nobr>Macro: <strong>R_MARGIN</strong> <kbd><right margin></kbd></nobr> +<br/> + +<em>*Requires a <a href="definitions.html#TERMS_UNITOFMEASURE">unit of measure</a></em> +</p> + +<p> +<strong>R_MARGIN</strong> establishes the amount of space you +want between the end of typeset lines and the right hand edge +of the printer sheet. In other words, it sets the line length. +<strong>R_MARGIN</strong> requires a unit of measure. Decimal +fractions are allowed. +</p> + +<p> +The +<a href="#LINELENGTH">line length macro</a>, +(<strong>LL</strong>), can be used in place of +<strong>R_MARGIN</strong>. In either case, the last one invoked +sets the line length. The choice of which to use is up to you. In +some instances, you may find it easier to think of a section of type +as having a right margin. In others, giving a line length may make +more sense. +</p> + +<p> +For example, if you're setting a page of type you know should have +6-pica margins left and right, it makes sense to enter a left and +right margin, like this: + +<pre> + .L_MARGIN 6P + .R_MARGIN 6P +</pre> + +That way, you don't have to worry about calculating the line +length. On the other hand, if you know the line length for a +patch of type should be 17 picas and 3 points, entering the line +length with <strong>LL</strong> is much easier than calculating the +right margin, e.g. + +<pre> + .LL 17P+3p +</pre> +</p> + +<p> +If you use the macros +<a href="#PAGE">PAGE</a>, +<a href="#PAGEWIDTH">PAGEWIDTH</a> +or +<a href="#PAPER">PAPER</a> +without invoking <kbd>.R_MARGIN</kbd> afterwards, +<strong>mom</strong> automatically sets <strong>R_MARGIN</strong> to +1 inch. If you set a line length after these macros (with +<a href="#LINELENGTH">LL</a>), +the line length calculated by <strong>R_MARGIN</strong> is, of course, +overridden. +</p> + +<p> +<strong>IMPORTANT: R_MARGIN</strong>, if used, MUST come after +<a href="#PAPER">PAPER</a>, +<a href="#PAGEWIDTH">PAGEWIDTH</a>, +<a href="#L_MARGIN">L_MARGIN</a> +and/or +<a href="#PAGE">PAGE</a> +(if a right margin isn't given to <strong>PAGE</strong>). The +reason is that <strong>R_MARGIN</strong> calculates line length from +the overall page dimensions and the left margin. Obviously, it +can't make the calculation if it doesn't know the page width and the +left margin. +</p> + +<p> +<strong>NOTE: R_MARGIN</strong> behaves in a special way when you're +using the +<a href="docprocessing.html#DOCPROCESSING">document processing macros</a>. +See +<a href="typemacdoc.html#TYPESETTING">Typesetting Macros in Document Processing</a> +for an explanation. +</p> + +<!-- -T_MARGIN- --> + +<hr width="33%" align="left"/> + +<a name="T_MARGIN"><h3><u>Top margin</u></h3></a> + +<p> +<nobr>Macro: <strong>T_MARGIN</strong> <kbd><top margin></kbd></nobr> +<br/> + +<em>*Requires a <a href="definitions.html#TERMS_UNITOFMEASURE">unit of measure</a></em> +</p> + +<p> +<strong>T_MARGIN</strong> establishes the distance from the top of +the printer sheet at which you want your type to start. It requires +a unit of measure, and decimal fractions are allowed. To set a top +margin of 2-1/2 centimetres, you'd enter + +<pre> + .T_MARGIN 2.5c +</pre> +</p> + +<p> +<strong>T_MARGIN</strong> calculates the vertical position of the +first line of type on a page by treating the top edge of the printer +sheet as a <a href="definitions.html#TERMS_BASELINE">baseline</a>. Therefore, + +<pre> + .T_MARGIN 1.5i +</pre> + +puts the baseline of the first line of type 1-1/2 inches beneath +the top of the page. +</p> + +<p> +<strong>IMPORTANT:</strong> <strong>T_MARGIN</strong> does two +things: it establishes the top margin for pages that come after +it AND it moves to that position on the current page. Therefore, +<strong>T_MARGIN</strong> should only be used at the top of a file +(prior to entering text) or after +<a href="#NEWPAGE">NEWPAGE</a>, +like this: + +<pre> + .NEWPAGE + .T_MARGIN 6P + <text> +</pre> +</p> + +<p> +<strong>NOTE:</strong> <strong>T_MARGIN</strong> means something +slightly different when you're using the +<a href="docprocessing.html#DOCPROCESSING">document processing macros</a>. +See +<a href="typemacdoc.html#TB_MARGINS">Top and bottom margins in document processing</a> +for an explanation. +</p> + +<!-- -B_MARGIN- --> + +<hr width="33%" align="left"/> + +<a name="B_MARGIN"><h3><u>Bottom margin</u></h3></a> + +<p> +<nobr>Macro: <strong>B_MARGIN</strong> <kbd><bottom margin></kbd></nobr> +<br/> + +<em>*Requires a <a href="definitions.html#TERMS_UNITOFMEASURE">unit of measure</a></em> +</p> + +<p> +<strong>B_MARGIN</strong> sets a nominal position at the bottom +of the page beyond which you don't want your type to go. When the +bottom margin is reached, <strong>mom</strong> starts a new page. +<strong>B_MARGIN</strong> requires a unit of measure. Decimal +fractions are allowed. To set a nominal bottom margin of 3/4 inch, +enter + +<pre> + .B_MARGIN .75i +</pre> +</p> + +<p> +Obviously, if you haven't spaced the type on your pages so that +the last lines fall perfectly at the bottom margin, the margin will +vary from page to page. Usually, but not always, the last line of +type that fits on a page <em>before</em> the bottom margin causes +<strong>mom</strong> to start a new page. +</p> + +<p> +Occasionally, owing to a peculiarity in <strong>groff</strong>, +an extra line will fall below the nominal bottom margin. If you're +using the +<a href="docprocessing.html#DOCPROCESSING">document processing macros</a>, +this is unlikely to happen; the document processing macros are very +hard-nosed about aligning bottom margins. +</p> + +<p> +<strong>NOTE:</strong> The meaning of <strong>B_MARGIN</strong> is +slightly different when you're using the document processing macros. +See +<a href="typemacdoc.html#TB_MARGINS">Top and bottom margins in document processing</a> +for an explanation. +</p> + +<!-- -PAGE- --> + +<hr width="33%" align="left"/> + +<a name="PAGE"><h3><u>Page</u></h3></a> + +<p> +<nobr>Macro: <strong>PAGE</strong> <kbd><width> [ <length> [ <lm> [ <rm> [ <tm> [ <bm> ] ] ] ] ]</kbd></nobr> +<br/> + +<em>*All arguments require a <a href="definitions.html#TERMS_UNITOFMEASURE">unit of measure</a></em> +</p> + +<p> +<strong>PAGE</strong> lets you establish paper dimensions +and page margins with a single macro. The only required +argument is page width. The rest are optional, <strong>but +they must appear in order and you can't skip over any.</strong> +<nobr><kbd><lm>, <rm>, <tm></kbd></nobr> and +<nobr><kbd><bm></kbd></nobr> refer to the left, right, top and +bottom margins respectively. +</p> + +<p> +Assuming your page dimensions are 11 inches by 17 inches, and that's +all you want to set, enter + +<pre> + .PAGE 11i 17i +</pre> +</p> + +<p> +If you want to set the left margin as well, say, at 1 inch, +<strong>PAGE</strong> would look like this: + +<pre> + .PAGE 11i 17i 1i +</pre> +</p> + +<p> +Now suppose you also want to set the top margin, say, at 1-1/2 +inches. <nobr><tm></nobr> comes after <nobr><rm></nobr> +in the optional arguments, but you can't skip over any arguments, +therefore to set the top margin, you must also give a right margin. +The <strong>PAGE</strong> macro would look like this: + +<pre> + .PAGE 11i 17i 1i 1i 1.5i + | | + required right___| |___top margin + margin +</pre> +</p> + +<p> +Clearly, <strong>PAGE</strong> is best used when you want a +convenient way to tell <strong>mom</strong> just the dimensions of +your printer sheet (width and length), or when you want to tell her +everything about the page (dimensions and all the margins), for +example +</p> + +<pre> + .PAGE 8.5i 11i 45p 45p 45p 45p +</pre> + +<p> +This sets up an 8-1/2 by 11 inch page with margins of 45 points +(5/8-inch) all around. +</p> + +<p> +<strong>NOTE:</strong> Only use <strong>PAGE</strong> at the start +of a document, before entering any text. And remember, when you're +using the +<a href="docprocessing.html#DOCPROCESSING">document processing macros</a>, +top margin and bottom margin mean something slightly different than +when you're using just the typesetting macros (see +<a href="typemacdoc.html#TB_MARGINS">Top and bottom margins in document processing</a>). +</p> + +<p> +Additionally, if you invoke <kbd>.PAGE</kbd> with a top margin +argument, any macros you invoke after <kbd>.PAGE</kbd> will almost +certainly move the +<a href="definitions.html#TERMS_BASELINE">baseline</a> +of the first line of text down by one linespace. To compensate, do + +<pre> + .RLD 1v +</pre> + +immediately before entering any text, or, if it's feasible, make +<strong>PAGE</strong> the last macro you invoke prior to entering text. +</p> + +<p> +Please read the +<a href="#DIMENSIONS_NOTE">Important note on page dimensions and papersize</a> +for information on ensuring <strong>groff</strong> respects your +<strong>PAGE</strong> dimensions and margins. +</p> + +<!-- -NEWPAGE- --> + +<hr width="33%" align="left"/> + +<a name="NEWPAGE"><h3><u>Start a new page</u></h3></a> + +<p> +<nobr>Macro: <strong>NEWPAGE</strong></nobr> +</p> + +<p> +Whenever you want to start a new page, use <strong>NEWPAGE</strong>, +by itself with no argument. <strong>Mom</strong> will finish up +processing the current page and move you to the top of a new one +(subject to the top margin set with +<a href="#T_MARGIN">T_MARGIN</a>. +</p> + +<p> +<strong>Experts:</strong> Prior to version 1.1.9, +<strong>NEWPAGE</strong> was simply an alias of <kbd>.bp</kbd>. As +of 1.1.9, <strong>NEWPAGE</strong>, is its own <strong>mom</strong> +macro. While the new macro should be backwardly compatible with +documents created using pre-1.1.9 <strong>mom</strong>s, I suggest +that from this version onward, if you were in the habit of using +<kbd>.bp</kbd> whenever you wanted to break to a new page, you now +begin to use <strong>NEWPAGE</strong> instead. +</p> + +<hr/> + +<!-- ==================================================================== --> + +<a name="INTRO_BASIC_PARAMS"></a> + +<a name="BASIC_PARAMS"><h2><u>Basic typesetting parameters</u></h2></a> + +<p> +Basic parameter macros deal with the fundamental requirements +for setting type: family, font, point size, leading and line length. +</p> + +<p> +If you're using the typesetting macros only, the arguments passed to +the basic parameter macros remain in effect until you change them. +The document processing macros handle things differently. See +<a href="typemacdoc.html#TYPESETTING">Typesetting Macros in Document Processing</a> +for an explanation. +</p> + +<a name="INDEX_BASIC"><h3><u>Basic parameter macros list</u></h3></a> + +<ul> + <li><a href="#FAMILY">FAMILY</a> (type family)</li> + <li><a href="#FONT">FONT</a> (font)</li> + <li><a href="#FALLBACK_FONT">FALLBACK_FONT</a> (for invalid fonts)</li> + <li><a href="#PS">PT_SIZE</a> (point size of type)</li> + <li><a href="#LEADING">LS</a> (line spacing/leading)</li> + <li><a href="#AUTOLEAD">AUTOLEAD</a> (automatic line spacing)</li> + <li><a href="#LINELENGTH">LL</a> (line length)</li> +</ul> + +<!-- -FAMILY- --> + +<hr width="66%" align="left"/> + +<a name="FAMILY"><h3><u>Type family</u></h3></a> + +<p> +<nobr>Macro: <strong>FAMILY</strong> <kbd><family></kbd></nobr> +<br/> + +Alias: <strong>FAM</strong> +</p> + +<p> +<strong>FAMILY</strong> takes one argument: the name of the +<a href="definitions.html#TERMS_FAMILY">family</a> +you want. Groff comes with a number of PostScript families, each +identified by a 1-, 2-or 3-letter mnemonic. The standard families +are: + +<pre> + A = Avant Garde + BM = Bookman + H = Helvetica + HN = Helvetica Narrow + N = New Century Schoolbook + P = Palatino + T = Times Roman + ZCM = Zapf Chancery +</pre> +</p> + +<p> +The argument you pass to <strong>FAMILY</strong> is the identifier at +left, above. For example, if you want Helvetica, enter + +<pre> + .FAMILY H +</pre> +</p> + +<p> +<strong>NOTE:</strong> The +<a href="#FONT">font macro</a> +(<strong>FT</strong>) lets you specify both the type family +and the desired font with a single macro. While this saves a few +keystrokes, I recommend using <strong>FAMILY</strong> for family, +and <strong>FT</strong> for font, except where doing so is genuinely +inconvenient. <strong>ZCM</strong>, for example, only exists in one +style: Italic (<strong>I</strong>). Therefore, <kbd>.FT ZCMI</kbd> +makes more sense than setting the family to "ZCM", then +setting the font to "I". +</p> + +<a name="FAM_ADD_NOTE"></a> + +<p> +<strong>ADDITIONAL NOTE:</strong> As of <strong>mom, version +1.1.9-a</strong>, if you are running a version of groff lower +than 1.19.2, you <em>MUST</em> follow all <strong>FAMILY</strong> +requests with a <strong>FT</strong> request, otherwise +<strong>mom</strong> will set all type up to the next +<strong>FT</strong> request in the +<a href="#FALLBACK_FONT">fallback font</a>. +</p> + +<p> +If you are running a version of groff greater than or equal +to 1.19.2, when you invoke the <strong>FAMILY</strong> macro, +<strong>mom</strong> "remembers" the font style (Roman, +Italic, etc) currently in use (if the font style exists in the new +family) and will continue to use the same font style in the new +family. For example: + +<pre> + .FAMILY BM \" Bookman family + .FT I \" Medium Italic + <some text> \" Bookman Medium Italic + .FAMILY H \" Helvetica family + <more text> \" Helvetica Medium Italic +</pre> +</p> + +<p> +However, if the font style does not exist in the new family, +<strong>mom</strong> will set all subsequent type in the +<a href="#FALLBACK_FONT">fallback font</a> +(by default, Courier Medium Roman) until she encounters a +<a href="#FONT">.FT</a> +request that's valid for the family. For example, assuming +you don't have the font "Medium Condensed Roman" +(<strong>mom</strong> extension "<strong>CD</strong>") +in the Helvetica family: + +<pre> + .FAMILY UN \" Univers family + .FT CD \" Medium Condensed + <some text> \" Univers Medium Condensed + .FAMILY H \" Helvetica family + <more text> \" Courier Medium Roman! +</pre> +</p> + +<p> +In the above example, you must follow <kbd>.FAMILY H</kbd> with a +<strong>FT</strong> request that's valid for Helvetica. +</p> + +<p> +<strong>Experts:</strong> If you add other PostScript families to +groff's /font/devps directory, I recommend following the groff +standard for naming families and fonts. For example, if you add the +Garamond family, name the font files + +<pre> + GARAMONDR + GARAMONDI + GARAMONDB + GARAMONDBI +</pre> + +GARAMOND then becomes a valid family name you can pass to +<strong>FAMILY</strong>. (You could, of course, shorten GARAMOND to just +G, or GD.) R, I, B, and BI after GARAMOND are the roman, italic, +bold and bold-italic fonts respectively. +</p> + +<p> +Please see the Appendices, +<a href="appendices.html#FONTS">Adding PostScript fonts to groff</a>, +for information on adding fonts and families to groff, as well as +to see a list of the extensions <strong>mom</strong> provides to +groff's basic <strong>R, I, B, BI</strong> styles. +</p> + +<!-- -FT- --> + +<hr width="33%" align="left"/> + +<a name="FONT"><h3><u>Font</u></h3></a> + +<p> +<nobr>Macro: <strong>FT</strong> <kbd>R | I | B | BI | <any other valid font style></kbd></nobr> +</p> + +<p> +By default, groff permits <strong>FT</strong> to take one of four +possible arguments specifying the desired font: + +<pre> + R = (Medium) Roman + I = (Medium) Italic + B = Bold (Roman) + BI = Bold Italic +</pre> +</p> + +<p> +For example, if your +<a href="definitions.html#TERMS_FAMILY">family</a> +is Helvetica, entering + +<pre> + .FT B +</pre> + +will give you the Helvetica bold +<a href="definitions.html#TERMS_FONT">font</a>. +If your family were Palatino, you'd get the Palatino bold font. +</p> + +<p> +(As of <strong>mom, version 1.1.9-a,</strong> the range of arguments +that can be passed to <strong>FT</strong> has been considerably +extended, allowing access to a greater variety of font +<a href="definitions.html#TERMS_WEIGHT">weights</a> +and +<a href="definitions.html#TERMS_SHAPE">shapes</a>. +Please see the +<a href="#FONT_NOTE">NOTE</a>, +below.) +</p> + +<p> +How <strong>mom</strong> reacts to an invalid argument to +<strong>FT</strong> depends on which version of groff you're +using. If your groff version is greater than or equal to 1.19.2, +<strong>mom</strong> will issue a warning and, depending on how +you've set up the +<a href="#FALLBACK_FONT">fallback font</a>, +either continue processing using the fallback font, or abort +(allowing you to correct the problem). If your groff version is +less than 1.19.2, <strong>mom</strong> will silently continue +processing, using either the fallback font or the font that was in +effect prior to the invalid <strong>FT</strong> call. +</p> + +<p> +<strong>FT</strong> will also accept, as an argument, a full +family+font name. For example, + +<pre> + .FT HB +</pre> + +will set subsequent type in Helvetica Bold. However, I strongly +recommend keeping family and font separate except where doing so is +genuinely inconvenient. +</p> + +<p> +For inline control of fonts, see +<a href="inlines.html#INLINE_FONTS_MOM">Inline Escapes, font control</a>. +</p> + +<a name="FONT_NOTE"></a> + +<p> +<strong>NOTE: mom, versions 1.1.9-a</strong> and higher, +considerably extends the range of arguments you can pass to +<strong>FT</strong>, making it more convenient to add and access +fonts of differing +<a href="definitions.html#TERMS_WEIGHT">weights</a> +and +<a href="definitions.html#TERMS_SHAPE">shapes</a> +within the same family. Have a look +<a href="appendices.html#STYLE_EXTENSIONS">here</a> +for a list of the weight/style arguments <strong>mom</strong> +allows. +</p> + +<p> +Be aware, though, that you must have the fonts, correctly +installed and named, in order to use the arguments. (See +<a href="appendices.html#HOWTO">How to create a PostScript font for use with groff</a> +for how to add fonts to groff.) Please also read the +<a href="#FAM_ADD_NOTE">ADDITIONAL NOTE</a> +found in the description of the <strong>FAMILY</strong> macro. +</p> + +<!-- -FALLBACK_FONT- --> + +<hr width="33%" align="left"/> + +<a name="FALLBACK_FONT"><h3><u>Fallback font</u></h3></a> + +<p> +<nobr>Macro: <strong>FALLBACK_FONT</strong> <kbd><fallback font> [ ABORT | WARN ] | ABORT | WARN</kbd></nobr> +</p> + +<p> +In the event that you pass an invalid argument to +<a href="#FONT">.FAMILY</a> +(i.e. a non-existent family), <strong>mom</strong>, by default, uses +the fallback font, Courier Medium Roman (CR), in order to continue +processing your file. +</p> + +<p> +If you'd prefer another fallback font, pass +<strong>FALLBACK_FONT</strong> the <strong>full family+font +name</strong> of the font you'd like. For example, if you'd rather +the fallback font were Times Roman Medium Roman, + +<pre> + .FALLBACK_FONT TR +</pre> + +would do the trick. +</p> + +<p> +Additionally, if your version of groff accepts accepts "<kbd>.if +F</kbd>" and "<kbd>.if S</kbd>" (see +<a href="#FAM_ADD_NOTE">above</a>), +<strong>mom</strong> issues a warning whenever a +<strong>font style</strong> set with +<a href="#FONT">FT</a> +does not exist, either because you haven't registered the style +(see +<a href="appendices.html#REGISTER_STYLE">here</a> +for instructions on registering styles), or because the font style +does not exist in the current family set with +<a href="#FAMILY">FAMILY</a>. +By default, <strong>mom</strong> then aborts, which allows you to +correct the problem. +</p> + +<p> +If you'd prefer that <strong>mom</strong> not abort on non-existent +fonts, but rather continue processing using a fallback font, you can +pass <strong>FALLBACK_FONT</strong> the argument <kbd>WARN</kbd>, +either by itself, or in conjunction with your chosen fallback font. +</p> + +<p> +<strong>Some examples of invoking FALLBACK_FONT:</strong> +</p> + +<ul> + <li><kbd>.FALLBACK_FONT WARN</kbd> + <br/> + + <strong>mom</strong> will issue a warning whenever you try + to access a non-existent font but will continue processing + your file with the default fallback font, Courier Medium Roman. + </li> + <li><kbd>.FALLBACK_FONT TR WARN</kbd> + <br/> + + <strong>mom</strong> will issue a warning whenever you try + to access a non-existent font but will continue processing + your file with a fallback font of Times Roman Medium Roman; + additionally, "TR" will be the fallback font whenever + you try to access a <strong>family</strong> that does not exist. + </li> + <li><kbd>.FALLBACK_FONT TR ABORT</kbd> + <br/> + + <strong>mom</strong> will abort whenever you try to access a + non-existent font, and will use the fallback font + "TR" whenever you try to access a <strong>family</strong> + that does not exist. + </li> +</ul> + +<p> +If, for some reason, you want to revert to ABORT, just enter +<kbd>.FALLBACK_FONT ABORT</kbd> and <strong>mom</strong> will once +again abort on font errors. +</p> + +<!-- -PT_SIZE- --> + +<hr width="33%" align="left"/> + +<a name="PS"><h3><u>Point size of type</u></h3></a> + +<p> +<nobr>Macro: <strong>PT_SIZE</strong> <kbd><size of type in points></kbd></nobr> +<br/> + +<em>*Does not require a <a href="definitions.html#TERMS_UNITOFMEASURE">unit of measure</a></em> +</p> + +<p> +<strong>PT_SIZE</strong> (Point Size) takes one argument: the size +of type in points. Unlike most other macros that establish the size +or measure of something, <strong>PT_SIZE</strong> does not require +that you supply a unit of measure since it's a near universal +convention that type size is measured in points. Therefore, to +change the type size to, say, 11 points, enter + +<pre> + .PT_SIZE 11 +</pre> +</p> + +<p> +Point sizes may be fractional (e.g. 10.25 or 12.5). +</p> + +<p> +You can prepend a plus or a minus sign to the argument to +<strong>PT_SIZE</strong>, in which case the point size will be changed by + +or - the original value. For example, if the point size is 12, +and you want 14, you can do + +<pre> + .PT_SIZE +2 +</pre> + +then later reset it to 12 with + +<pre> + .PT_SIZE -2 +</pre> +</p> + +<p> +The size of type can also be changed inline. See +<a href="inlines.html#INLINE_SIZE_MOM">Inline Escapes, changing point size</a>. +</p> + +<p> +<strong>NOTE:</strong> It is unfortunate that the <kbd>pic</kbd> +pre-processor uses <strong>PS</strong>, and thus +<strong>mom</strong>'s macro for setting point sizes can't use it. +However, if you aren't using <kbd>pic</kbd>, you might want to +<a href="goodies.html#ALIAS">alias</a> +<strong>PT_SIZE</strong> as <strong>PS</strong>, since there'd be no +conflict. For example + +<pre> + .ALIAS PS PT_SIZE +</pre> + +would allow you to set point sizes with <kbd>.PS</kbd>. +</p> + +<!-- -LS- --> + +<hr width="33%" align="left"/> + +<a name="LEADING"><h3><u>Line spacing/leading</u></h3></a> + +<p> +<nobr>Macro: <strong>LS</strong> <kbd><distance between lines></kbd></nobr> +<br/> + +<em>*Does not require a <a href="definitions.html#TERMS_UNITOFMEASURE">unit of measure</a></em> +</p> + +<p> +<strong>LS</strong> (Line Space) takes one argument: the distance you want, typically +in points, from baseline to baseline of type. The argument may +be fractional (e.g. 12.25 or 14.5). Like <strong>PT_SIZE</strong>, +<strong>LS</strong> does not require a unit of measure, since +<a href="definitions.html#TERMS_LEADING">leading</a> +is most often given in points. Therefore, to set the linespace to +14 points, you would enter + +<pre> + .LS 14 +</pre> +</p> + +<p> +However, if you wish, you may specify a unit of measure by appending +it directly to the argument passed to <strong>LS</strong>. For +example, if you want a linespace of 1/4 of an inch, enter + +<pre> + .LS .25i +</pre> +</p> + +<p> +You can prepend a plus or a minus sign to the argument to +<strong>LS</strong>, in which case the line spacing will be changed +by + or - the original value. For example, if the line spacing is +14 points, and you want 17 points, you can do + +<pre> + .LS +3 +</pre> + +then later reset it to 14 points with + +<pre> + .LS -3 +</pre> +</p> + +<p> +<strong>Experts: LS</strong> should not be confused with +the groff primitive <kbd>.ls</kbd>. <strong>LS</strong> acts +like <kbd>.vs</kbd>. <strong>mom</strong> does not provide a +macro analogous to <kbd>.ls</kbd>. +</p> + +<!-- -AUTOLEAD- --> + +<hr width="33%" align="left"/> + +<a name="AUTOLEAD"><h3><u>Automatic line spacing</u></h3></a> + +<p> +<nobr>Macro: <strong>AUTOLEAD</strong> <kbd><amount of automatic leading> [FACTOR]</kbd></nobr> +<br/> + +<em>*Does not require a <a href="definitions.html#TERMS_UNITOFMEASURE">unit of measure</a></em> +</p> + +<p> +Without the <kbd>FACTOR</kbd> argument, <strong>AUTOLEAD</strong> +calculates the linespace for you by adding its argument to the +current point size of type. All subsequent +<a href="#PS">PT_SIZE</a> +requests automatically update the linespacing by the autolead amount. +</p> + +<p> +Used in this way, <strong>AUTOLEAD</strong> does not require a unit +of measure; points is assumed. However, you may use an alternate +unit of measure by appending it to the argument. The argument may +be a decimal fraction (e.g. .5 or 2.75). +</p> + +<p> +As an example, if your current point size of type is 12, entering + +<pre> + .AUTOLEAD 2 +</pre> + +changes the linespace to 14 points, regardless any linespacing +already in effect. From here on, every change to the size of type +(with <strong>PT_SIZE</strong>, not +<a href="definitions.html#TERMS_INLINES">inline</a>) +changes the linespace as well. If you decrease the type size to 9 +points, the leading decreases to 11 points. If you increase the +type size to 16 points, the leading increases to 18 points. +</p> + +<p> +Automatic updating of the linespacing continues until you enter a +"manual" line space value with +<a href="#LEADING">LS</a>. +</p> + +<p> +If you give <strong>AUTOLEAD</strong> the optional +<strong>FACTOR</strong> argument, <strong>AUTOLEAD</strong> +calculates the line space as a factor of the +<a href="definitions.html#TERMS_NUMERICARGUMENT">numeric argument</a> +you gave <strong>AUTOLEAD</strong>. For example, if your point size +is 12, + +<pre> + .AUTOLEAD 1.125 FACTOR +</pre> + +sets the leading at 13.5 points. If you change the point size +to 14, the leading automatically changes to 15.75 (14 x 1.125). +</p> + +<p> +<strong>NOTE:</strong> There's no need to prepend a plus sign +(<kbd>+</kbd>) +to <strong>AUTOLEAD</strong>'s argument, although you may do so if you +wish. +</p> + +<!-- -LL- --> + +<hr width="33%" align="left"/> + +<a name="LINELENGTH"><h3><u>Line length</u></h3></a> + +<p> +<nobr>Macro: <strong>LL</strong> <kbd><line length></kbd></nobr> +<br/> + +<em>*Requires a <a href="definitions.html#TERMS_UNITOFMEASURE">unit of measure</a></em> +</p> + +<p> +<strong>LL</strong> (Line Length) takes one argument: the distance from the +left margin of the page to the maximum allowable point on the +right at which groff should place type. The line length, in +other words, as the macro suggests. +</p> + +<p> +<strong>LL</strong> requires a unit of measure. Therefore, to set the line +length to 39 picas, you would enter + +<pre> + .LL 39P +</pre> +</p> + +<p> +As with other macros that require a unit of measure, the argument to +<strong>LL</strong> may be fractional. For example, + +<pre> + .LL 4.5i +</pre> + +sets the line length to 4-1/2 inches. +</p> + +<p> +Additionally, you may express a new line length relative to the +current line length by prepending a plus or minus sign to the +argument. Thus, if you wanted to increase the line length by 3 +<a href="definitions.html#TERMS_PICASPOINTS">points</a>, you could +do + +<pre> + .LL +3p +</pre> + +This is especially handy when you want to "hang" +punctuation outside the right margin since you can pass groff's +<a href="inlines.html#INLINE_STRINGWIDTH_GROFF"><kbd>\w</kbd></a> +escape as the argument to <strong>LL</strong>, like this: + +<pre> + .LL +\w'.'u +</pre> +</p> + +<p> +The above example increases the current line length by the width of +a period. Notice that you must append the +<a href="definitions.html#TERMS_UNITOFMEASURE">unit of measure</a>, +<strong>u</strong>, to the escape since <strong>LL</strong> requires +a unit of measure. +</p> + +<p> +<strong>NOTE:</strong> The +<a href="#R_MARGIN">right margin macro</a>, +(<strong>R_MARGIN</strong>), can also be used to set line length. +</p> + +<hr/> + +<!-- ==================================================================== --> + +<a name="JUST_QUAD_FILL"><h2><u>Justifying, quadding, filling and breaking lines</u></h2></a> + +<p> +The justification and quadding macros deal with how type aligns +along the left and right margins. In a nutshell, type either aligns +at the left margin, at the right margin, at both margins, or at +neither margin (centred). +</p> + +<p> +These macros also determine whether or not +<a href="definitions.html#TERMS_INPUTLINE">input lines</a> +are joined and +<a href="definitions.html#TERMS_FILLED">filled</a> +during output. +</p> + +<p> +Additionally, macros that deal with how to break +<a href="definitions.html#TERMS_OUTPUTLINE">output lines</a> +are covered in this section, as is the +<a href="definitions.html#TERMS_INLINES">inline escape</a> +for joining input lines. +</p> + +<p> +You may encounter some words here that are unfamiliar. Refer to +<a href="definitions.html#TERMS_TYPESETTING">Typesetting terms</a> +and +<a href="definitions.html#TERMS_GROFF">Groff terms</a> +for an explanation. +</p> + +<a name="INDEX_JUST"><h3><u>Justification, quad, fill, and break macro list</u></h3></a> + +<ul> + <li><strong>Fill modes</strong></li> + <ul> + <li><a href="#JUSTIFY">JUSTIFY</a> (set lines justified)</li> + <li><a href="#QUAD">QUAD</a> (set filled lines flush left, right or centred)</li> + </ul> + <li><strong>Nofill modes</strong></li> + <ul> + <li><a href="#LRC">LEFT</a> (set non-filled lines flush left)</li> + <li><a href="#LRC">RIGHT</a> (set non-filled lines flush right)</li> + <li><a href="#LRC">CENTER</a> (set non-filled lines centred)</li> + </ul> + <li><strong>Breaking lines</strong></li> + <ul> + <li><a href="#BR">BR</a> (manually break an output line)</li> + <li><a href="#EL">EL</a> (break a line without advancing to the next output line)</li> + <li><a href="#SPACE">SPACE</a> (break a line and add space before the next output line)</li> + <li><a href="#SPREAD">SPREAD</a> (break and force-justify an output line)</li> + </ul> + <li><strong>Joining input lines in <a href="definitions.html#TERMS_NOFILL">nofill mode</a></strong></li> + <ul> + <li><a href="#JOIN">\c</a> inline escape</li> + </ul> +</ul> + +<!-- -JUSTIFY- --> + +<hr width="66%" align="left"/> + +<a name="JUSTIFY"><h3><u>Justify lines</u></h3></a> + +<p> +<nobr>Macro: <strong>JUSTIFY</strong></nobr> +<br/> + +(See +<a href="definitions.html#TERMS_FILLED">fill mode</a> +for a definition of the difference between "fill" and +"no-fill" modes.) +</p> + +<p> +<strong>JUSTIFY</strong> doesn't take an argument. +<a href="definitions.html#TERMS_INPUTLINE">Input lines</a> +after <strong>JUSTIFY</strong> are +<a href="definitions.html#TERMS_FILLED">filled</a> +and +<a href="definitions.html#TERMS_JUST">justified</a> +upon output. +</p> + +<p> +To break lines and prevent them from being filled and justified, +use the +<a href="#BR">BR</a> +macro. +</p> + +<!-- -QUAD- --> + +<hr width="33%" align="left"/> + +<a name="QUAD"><h3><u>Quad lines left, right, or centre</u></h3></a> + +<p> +<nobr>Macro: <strong>QUAD</strong> <kbd>L | LEFT | R | RIGHT | C | CENTER | J | JUSTIFY</kbd></nobr> +<br/> + +Alias: <strong>FILL</strong> +<br/> + +(See +<a href="definitions.html#TERMS_FILLED">fill mode</a> +for a definition of the difference between "fill" and +"no-fill" modes.) +</p> + +<p> +<strong>QUAD</strong> takes one argument: the direction in which lines +should be +<a href="definitions.html#TERMS_QUAD">quadded</a>. +<a href="definitions.html#TERMS_INPUTLINE">Input lines</a> +after <strong>QUAD</strong> are +<a href="definitions.html#TERMS_FILLED">filled</a> +upon output. +</p> + +<p> +If <kbd>L</kbd> or <kbd>LEFT</kbd>, type is set flush along the left +margin. +</p> + +<p> +If <kbd>R</kbd> or <kbd>RIGHT</kbd>, type is set flush along the +right margin. +</p> + +<p> +If <kbd>C</kbd> or <kbd>CENTER</kbd> type is set centred on the +current line length. +</p> + +<p> +<kbd>J</kbd> and <kbd>JUSTIFY</kbd> justify text, and are included +as a convenience only. Obviously, if text is justified, it isn't +quadded. <kbd>.QUAD J</kbd> and <kbd>.QUAD JUSTIFY</kbd> have +exactly the same effect as +<a href="#JUSTIFY">JUSTIFY</a>. +</p> + +<p> +To break lines and prevent them from being filled, use the +<a href="#BR">BR</a> +macro. +</p> + +<!-- -LEFT, RIGHT, CENTER- --> + +<hr width="33%" align="left"/> + +<a name="LRC"><h3><u>Set lines flush left, right, or centred in no-fill mode</u></h3></a> + +<p> +<nobr>Macro: <strong>LEFT</strong></nobr> +<br/> +<nobr>Macro: <strong>RIGHT</strong></nobr> +<br/> +<nobr>Macro: <strong>CENTER</strong> (alias <strong>CENTRE</strong>)</nobr> +<br/> + +(See +<a href="definitions.html#TERMS_NOFILL">no-fill mode</a> +for a definition of the difference between "fill" and +"no-fill" modes.) +</p> + +<p> +<strong>LEFT</strong>, <strong>RIGHT</strong> and +<strong>CENTER</strong> let you enter text on a line for line basis +without having to use the +<a href="#BR">BR</a> +macro after each line. Consider the following: + +<pre> + .QUAD LEFT + So runs my dream, but what am I? + .BR + An infant crying in the night + .BR + An infant crying for the light + .BR + And with no language but a cry. + .BR +</pre> +</p> + +<p> +Because text after <kbd>.QUAD LEFT</kbd> is +<a href="definitions.html#TERMS_FILLED">filled</a>, +you have to use the +<a href="#BR">BR</a> +macro to prevent the lines from running together. Not only is this +annoying to type, it's awkward to read in a text editor. Much better +to do + +<pre> + .LEFT + 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. +</pre> +</p> + +<p> +<strong>IMPORTANT:</strong> Because <strong>LEFT</strong>, +<strong>RIGHT</strong> and <strong>CENTER</strong> are nofill +modes, groff does not always respect the current line length. +<a href="definitions.html#TERMS_INPUTLINE">Input lines</a> +that run long may exceed it, or get broken in undesirable ways. +Therefore, when using these three macros, you should preview your +work to ensure that all lines fit as expected. +</p> + +<!-- -BR- --> + +<hr width="33%" align="left"/> + +<a name="BR"><h3><u>Manually break lines</u></h3></a> + +<p> +<nobr>Macro: <strong>BR</strong></nobr> +</p> + +<p> +When using +<a href="#JUSTIFY">JUSTIFY</a> +or +<a href="#QUAD">QUAD</a>, +<strong>BR</strong> tells <strong>mom</strong> about partial lines +that you want broken (as opposed to +<a href="definitions.html#TERMS_FILLED">filled</a>). +Any partial +<a href="definitions.html#TERMS_OUTPUTLINE">output line</a> +that immediately precedes <strong>BR</strong> will be +<a href="definitions.html#TERMS_QUAD">quadded</a> +in the direction of the current quad, or set flush left if text is +<a href="definitions.html#TERMS_JUST">justified</a>. +</p> + +<p> +Most of the time, you won't need the <strong>BR</strong> macro. +In fill modes, <strong>mom</strong> tries to be sensible about +where breaks are needed. If the nature of a macro is such that under +most circumstances you'd expect a break, <strong>mom</strong> puts +it in herself. Equally, in macros where a break isn't normally +desirable, no break occurs. This means text files don't get cluttered +with annoying <strong>BR</strong>'s. +</p> + +<p> +<strong>NOTE:</strong> Lines of text in +<a href="definitions.html#TERMS_NOFILL">nofill mode</a> +never require a <strong>BR</strong>. Furthermore, in nofill mode, +ALL macros cause a break. If a break is not desired, use the +<a href="#JOIN"><kbd>\c</kbd></a> +<a href="definitions.html#TERMS_INLINES">inline escape</a>. +</p> + +<p> +<strong>Experts: BR</strong> is an alias for <kbd>.br</kbd>. +You can use either, or mix 'n' match with impunity. +</p> + +<!-- -EL- --> + +<hr width="33%" align="left"/> + +<a name="EL"><h3><u>Manually break a line without advancing on the page</u></h3></a> + +<p> +<nobr>Macro: <strong>EL</strong></nobr> +<br/> + +<em>*In nofill modes +(</em><a href="#LEFT">LEFT</a>, +<a href="#RIGHT">RIGHT</a>, +<a href="#CENTER">CENTER</a>><em>), +you must terminate the line input preceding</em> <strong>EL</strong> +<em>with the </em><kbd>\c</kbd> <em>inline escape. See</em> +<a href="#EL_NOTES">NOTES</a>, +<em>below. +<br/> + + If you find remembering whether to put in the +</em><kbd>\c</kbd> <em>bothersome, you may prefer to use the +<a href="definitions.html#TERMS_INLINES">inline escape</a> +alternative to </em><strong>EL</strong>, +<a href="inlines.html#B"><kbd>\*[B]</kbd></a>, +<em>which works consistently regardless of the fill mode.</em> +<strong>EL</strong> <em>does not work after the</em> +<a href="goodies.html#PAD">PAD</a> +<em>macro. See</em> +<a href="goodies.html#NOBREAK"><kbd>.PAD NOBREAK</kbd></a> +<em>for the way around this</em>. +</p> + +<p> +The mnemonic "EL" is borrowed from old Compugraphic +typesetting systems, where it stood for "End Line." Conceptually, +<strong>EL</strong> is equivalent to the notion of a carriage return +with no linefeed. +</p> + +<p> +<em>Note to groff jocks:</em> <strong>EL</strong> is unrelated to +groff's <kbd>.el</kbd>. If you find the similarity confusing, +you may want to alias <strong>EL</strong> as something else (but +don't use <strong>EOL</strong>; <strong>mom</strong> uses it +internally.) +</p> + +<p> +<strong>EL</strong>'s function is simple: it breaks a line without +advancing on the page. + +<a name="EL_EXAMPLE"></a> + +As an example of where you might use it, imagine that you're working +from marked-up copy. The markup indicates 24 points of space +between two given lines, but the prevailing line spacing is 12.5 +points. You may find it more convenient to break the first line +with <strong>EL</strong> and instruct <strong>mom</strong> to +advance 24 points to the next line instead of calculating the lead +that needs to be added to 12.5 to get 24. To demonstrate: + +<pre> + .LEFT + .LS 12.5 + A line of text.\c + .EL + .ALD 24p + The next line of text. +</pre> + +may be more intuitive than + +<pre> + .LEFT + .LS 12.5 + A line of text. + .ALD 11.5p + The next line of text. +</pre> +</p> + +<p> +The first example has the further advantage that should you wish +to change the prevailing line space but keep the 24 points lead, +you don't have to recalculate the extra space. +</p> + +<p> +"ALD" in the above examples stands for "<strong>A</strong>dvance +<strong>L</strong>ea<strong>D</strong>" (another mnemonic borrowed +from Compugraphic), which is covered in the section +<a href="#ALDRLD">Vertical movement</a>. +</p> + +<a name="EL_NOTES"><h4><u>NOTES:</u></h4></a> + +<p> +In versions of mom prior to 1.1.9, <strong>EL</strong> did not +always work as advertised on the last +<a name="TERMS_OUTPUTLINE">output line</a> +of pages that contained a footer trap (e.g. one set with +<a href="#B_MARGIN">B_MARGIN</a> +or in documents formatted using the +<a href="docprocessing.html#DOCPROCESSING">document processing macros</a>). +</p> + +<p> +<strong>EL</strong> has been re-written so that this should no longer be the +case. However, in order for it to work in the +<a href="definitions.html#TERMS_NOFILL">nofill</a> +modes +(<a href="#LRC">LEFT</a>, +<a href="#LRC">RIGHT</a> +or +<a href="#LRC">CENTER</a>), +you must always "join" <kbd>.EL</kbd> to the line before +it using the +<a href="#JOIN"><kbd>\c</kbd></a> +<a href="definitions.html#TERMS_INLINES">inline escape</a>, +like this: + +<pre> + .LEFT + A line I don't want to advance\c + .EL +</pre> +</p> + +<p> +Conversely, in +<a href="definitions.html#TERMS_FILLED">fill modes</a> +(<a href="#QUAD">QUAD LEFT</a>, +<a href="#QUAD">QUAD RIGHT</a>, +<a href="#QUAD">QUAD CENTER</a> +or +<a href="#JUSTIFY">JUSTIFY</a>), +the <kbd>\c</kbd> must not be used. +</p> + +<p> +If <strong>EL</strong> is used after most macros or groff +<a href="definitions.html#TERMS_PRIMITIVES">primitives</a> +(see the exception, below), you don't have to worry about this, +regardless of the fill mode. Just type <kbd>.EL</kbd> +</p> + +<!-- -SP- --> + +<hr width="33%" align="left"/> + +<a name="SPACE"><h3><u>Break lines and add space between</u></h3></a> + +<p> +<nobr>Macro: <strong>SPACE</strong> <kbd><space to add between lines></kbd></nobr> +<br/> + +Alias: <strong>SP</strong> +</p> + +<p> +<strong>SPACE</strong> breaks a line, just like +<a href="#BR">BR</a>, +then adds space after the line. With no argument, it adds an extra +line space of a value equal to the current +<a href="definitions.html#TERMS_LEADING">leading</a>. +If you pass it a numeric argument without supplying a +<a href="definitions.html#TERMS_UNITOFMEASURE">unit of measure</a>, +it advances that number of extra line spaces. For example: + +<pre> + .SPACE +</pre> + +breaks the line then adds an extra linespace, whereas + +<pre> + .SPACE 2 +</pre> + +breaks the line and adds two extra linespaces. +</p> + +<p> +If you supply a unit of measure, <strong>SPACE</strong> breaks the +line then advances one linespace (at the current +<a href="definitions.html#TERMS_LEADING">leading</a>) +PLUS the specified amount of extra space given to +<strong>SPACE</strong>, as in + +<pre> + .SPACE 6p +</pre> + +which breaks the line and advances one full linespace plus six +points. +</p> + +<p> +<strong>SUGGESTION: SPACE</strong> and +<a href="#ALD">ALD</a> +can be used interchangeably (<kbd>.SPACE 6p</kbd> and +<kbd>.ALD 6p</kbd> are equivalent). However, +<strong>ALD</strong> without an argument does nothing, whereas +<strong>SPACE</strong> without an argument adds an extra line +space. I recommend using <strong>SPACE</strong> when you +want an extra line space (or multiple thereof), and +<strong>ALD</strong> whenever you want some other value of space +after a line. +</p> + +<p> +<strong>Experts: SPACE</strong> is an alias of <kbd>.sp</kbd>. You +can use either, or mix 'n' match with impunity. +</p> + +<!-- -SPREAD- --> + +<hr width="33%" align="left"/> + +<a name="SPREAD"><h3><u>Break and force justify (spread) lines</u></h3></a> + +<p> +<nobr>Macro: <strong>SPREAD</strong></nobr> +</p> + +<p> +Sometimes, you need to break a line of +<a href="definitions.html#TERMS_JUST">justified</a> +text and have it come out fully justified, not +<a href="definitions.html#TERMS_QUAD">quadded</a> +left the way it would be with the +<a href="#BR">BR</a> +macro. An example of where you'd do this would be when you want +to prevent a word at the end of a line from being hyphenated (say, +a proper name). <strong>SPREAD</strong> is the macro that lets you +break the line and have it came out fully justified. +</p> + +<p> +<strong>Experts: SPREAD</strong> is an alias for <kbd>.brp</kbd> +You can use either, or mix 'n' match with impunity. +</p> + +<!-- -JOIN- --> + +<hr width="33%" align="left"/> + +<a name="JOIN"><h3><u>Join input lines</u></h3></a> + +<p> +Inline: <kbd>\c</kbd> +</p> + +<p> +Sometimes, especially when in one of the +<a href="definitions.html#TERMS_NOFILL">nofill modes</a>, +a macro will cause a break where you don't want one. In order to +prevent this from happening (in other words, to join +<a href="definitions.html#TERMS_INPUTLINE">input lines</a> +together, forming one +<a href="definitions.html#TERMS_OUTPUTLINE">output line</a>), +use the groff +<a href="definitions.html#TERMS_INLINES">inline escape</a> +<kbd>\c</kbd> at the end of each input line to be joined to another, +like this: + +<pre> + .LEFT + .FAMILY T + .FT R + Some lines of text to be \c + .FAMILY H + .FT B + joined \c + .FAMILY T + .FT R + together. +</pre> +</p> + +<p> +Upon output, the lines will be joined together to read + +<pre> + Some lines of text to be joined together. +</pre> + +with the word "joined" in Helvetica bold. Note the space +before <kbd>\c</kbd>. Without it, the last three words of the +output line would read + +<pre> + bejoinedtogether +</pre> +</p> + +<p> +Please also note that had the example been in one of the +<a href="definitions.html#TERMS_FILLED">fill modes</a>, +there'd have been no need for the <kbd>\c</kbd>. +</p> + +<p> +<strong>Addendum:</strong> The example, above, is designed to +demonstrate the use of <kbd>\c</kbd>. However, an easier and more +intuitive way to accomplish the family/font change in the example +would be with the groff +<a href="definitions.html#TERMS_INLINES">inline escape</a>, +<a href="inlines.html#INLINE_FONTS_GROFF">\f</a>, +like this: + +<pre> + Some lines of text to be \f[HB]joined\*[PREV] together. +</pre> +</p> + +<hr/> + +<!-- ==================================================================== --> + +<a name="INTRO_REFINEMENTS"></a> + +<a name="REFINEMENTS"><h2><u>Typographic refinements</u></h2></a> + +<p> +The macros in this section help you tweak groff's behaviour, +ensuring that your documents look typographically professional. +</p> + +<a name="INDEX_REFINEMENTS"><h3><u>Typographic refinements macro list</u></h3></a> + +<ul> + <li><strong>Word and sentence spacing</strong></li> + <ul> + <li><a href="#WS">WS</a> (word spacing)</li> + <li><a href="#SS">SS</a> (sentence space)</li> + </ul> + <li><strong>Letter spacing (track kerning)</strong></li> + <ul> + <li><a href="#RW">RW</a> (reduce whitespace)</li> + <li><a href="#EW">EW</a> (expand whitespace)</li> + <li><a href="#BR_AT_LINE_KERN">BR_AT_LINE_KERN</a></li> + </ul> + <li><strong>Hyphenation</strong></li> + <ul> + <li><a href="#HY">HY</a> (turn auto hyphenation on/off, or set specific hyphenation parameters)</li> + <li><a href="#HY_SET">HY_SET</a> (set all hyphenation parameters)</li> + </ul> + <li><strong>Automatic kerning and ligatures</strong></li> + <ul> + <li><a href="#KERN">KERN</a> (turn automatic pairwise kerning on or off)</li> + <li><a href="#LIGATURES">LIGATURES</a> (turn automatic generation of ligatures on or off)</li> + </ul> +</ul> + +<!-- -WS- --> + +<hr width="66%" align="left"/> + +<a name="WS"><h3><u>Word spacing</u></h3></a> + +<p> +<nobr>Macro: <strong>WS</strong> <kbd><+|-wordspace> | DEFAULT</kbd></nobr> +</p> + +<p> +<strong>WS</strong> (Word Space) increases or decreases the amount +of space between words. In +<a href="definitions.html#TERMS_NOFILL">nofill modes</a>, +or if +<a href="#QUAD">QUAD</a> +is in effect, the space between words is fixed. Therefore, if you +change the word spacing with <strong>WS</strong>, the change applies +uniformly to the space between every word on every line. However, +when text is +<a href="definitions.html#TERMS_JUST">justified</a>, +the space between words varies from line to line (in order to +justify the text). Consequently, the change you make with +<strong>WS</strong> represents the minimum (and ideal) space groff +will try to put between words before deciding whether to hyphenate a +final word or to stretch the word spacing. +</p> + +<p> +Word space is relative to type size. Knowing how it's calculated is +unimportant. What matters is having a sense of how the value passed +to <strong>WS</strong> affects the look of your type. Generally, +in/decreasing the word space by a value of 1 or 2 produces a difference +that in many cases is scarcely visible; in/decreasing by a value of 5 +or so produces a subtle but noticeable difference; and in/decreasing +by a value greater than 10 is always apparent. You should preview +your work to assess the effect of <strong>WS</strong>. +</p> + +<a name="WS_USAGE"></a> + +<p> +<strong>WS</strong> takes as its argument a whole number preceded +by a plus or minus sign. Therefore, to decrease the word space +slightly, you might enter + +<pre> + .WS -4 +</pre> +</p> + +<p> +To increase it by a noticeable amount, you might enter + +<pre> + .WS +12 +</pre> +</p> + +<p> +You can reset the word spacing to its previous value by switching +the plus or minus sign, like this: + +<pre> + .WS +4 + A line of text + .WS -4 +</pre> +</p> + +<p> +The <kbd>.WS -4</kbd> undoes the effect of <kbd>.WS +4</kbd>. You +can also reset <strong>WS</strong> to its groff default by entering + +<pre> + .WS DEFAULT +</pre> +</p> + +<p> +This can be particularly useful if you've been playing around +with plus and minus values, and can't remember by how much you +have to in/decrease the word space to get it back to normal. +</p> + +<!-- -SS- --> + +<hr width="33%" align="left"/> + +<a name="SS"><h3><u>Sentence space</u></h3></a> + +<p> +<nobr>Macro: <strong>SS</strong> <kbd><+sentence space> | 0 | DEFAULT</kbd></nobr> +</p> + +<p> +<strong>SS</strong> (Sentence Space) tells groff how to treat double +spaces it encounters between sentences in +<a href="definitions.html#TERMS_INPUTLINE">input lines</a>. +If you use <strong>SS</strong>, input sentences with two spaces +after them AND input sentences that fall at the end of input lines +all receive a normal word space plus an additional amount of space +whose size is determined by the + value passed as an argument to +<strong>SS</strong>. Thus, + +<pre> + .SS +2 +</pre> + +means that input sentences with two spaces after them receive a normal +word space PLUS the +2 value passed to <strong>SS</strong>. +</p> + +<p> +Like +<a href="#WS">WS</a>, +increasing the sentence space by a value of 1 or 2 produces a +difference that in many cases is scarcely visible; increasing by a +value of 5 or so produces a subtle but noticeable difference (i.e. +the space between double-spaced input sentences will be slightly but +visibly greater than the space between words); and increasing by a +value greater than 10 is always apparent. You should preview your +work to assess the effect of <strong>SS</strong>. +</p> + +<p> +There's an additional argument you can pass <strong>SS</strong>: +the number zero (without the + sign). It's the argument you'll +use most often. Typeset copy should never have two spaces between +sentences, and the "zero" argument tells groff to give the extra +spaces no space at all (effectively removing them). Therefore, +if you double-space your sentences (as you should when writing in a +text editor), get in the habit of putting + +<pre> + .SS 0 +</pre> + +at the top of your files. +</p> + +<p> +If you do use <strong>SS</strong> for something other than ensuring +that you don't get unwanted sentence spaces in output copy, you can +set or reset the sentence space to the groff default (the same width +as a word space, i.e. double-spaced input sentences will appear +double-spaced on output as well) with + +<pre> + .SS DEFAULT +</pre> +</p> + +<p> +If you're using the +<a href="docprocessing.html">document processing macros</a> +and your +<a href="docprocessing.html#PRINTSTYLE">PRINTSTYLE</a> +is <strong>TYPEWRITE</strong>, <kbd>.SS DEFAULT</kbd> is +the default, because you <em>do</em> want double spaces between +sentences in copy that imitates the look of a typewritten document. +</p> + +<p> +<strong>IMPORTANT: SS</strong> with an argument other than +"0" should only be used if you're of the old (and wise) +school of typists that puts two spaces between sentences. If you +ignore this advice and use <strong>SS</strong> when you habitually +put only one space between sentences, you risk producing output +where the space between sentences is not equal. +</p> + +<!-- -HY- --> + +<hr width="66%" align="left"/> + +<a name="HY"><h3><u>Automatic hyphenation control</u></h3></a> + +<p> +<nobr>Macro: <strong>HY</strong> <kbd>toggle</kbd></nobr> +<br/> +<nobr>Macro: <strong>HY</strong> <kbd>LINES <max. number of consecutive hyphenated lines></kbd></nobr> +<br/> +<nobr>Macro: <strong>HY</strong> <kbd>MARGIN <size of hyphenation margin></kbd></nobr> +<br/> +<nobr>Macro: <strong>HY</strong> <kbd>SPACE <extra interword spacing to prevent hyphenation></kbd></nobr> +<br/> +<nobr>Macro: <strong>HY</strong> <kbd>DEFAULT</kbd></nobr> +<br/> +Aliases: <strong>HYPHENATE, HYPHENATION</strong> +</p> + +<p> +<strong>HY</strong>, as you can see, can be invoked with a number of +arguments. In all cases, the aliases <strong>HYPHENATE</strong> +or <strong>HYPHENATION</strong> can be used in place of +<strong>HY</strong>. To aid in understanding the various arguments +you can pass to <strong>HY</strong>, I've broken them down into +separate sections. +</p> + +<h4><u>1. HY</u></h4> + +<p> +<strong>HY</strong> by itself (i.e. with no argument) simply turns +automatic hyphenation on. Any argument other than <strong>LINES, +MARGIN, SPACE</strong> or <strong>DEFAULT</strong>, turns +automatic hyphenation off. For example, as explained in <a +href="intro.html#MACRO_ARGS">How to read macro arguments</a>, you +could turn <strong>HY</strong> off by entering + +<pre> + .HY OFF + or + .HY X + or + .HY END +</pre> +</p> + +<p> +<strong>HY</strong> observes the following default hyphenation rules: + +<ol> + <li>Last lines (i.e. ones that will spring a trap — typically + the last line on a page) will not be hyphenated. + </li> + <li>The first and last two characters of a word are never + split off. + </li> +</ol> +</p> + +<h4><u>2. HY LINES</u></h4> + +<p> +<strong>HY LINES</strong> sets the maximum number of consecutive +hyphenated lines that will appear in output copy. 2 is a very +good choice, and you'd set it with + +<pre> + .HY LINES 2 +</pre> +</p> + +<p> +By default, when you turn automatic hyphenation on, there is no +limit to the number of consecutive hyphenated lines. +</p> + +<p> +<strong>NOTE:</strong> +<a href="definitions.html#TERMS_DISCRETIONARYHYPHEN">Discretionary hyphens</a> +count when groff is figuring out how many lines to hyphenate; +explicit hyphens do not. +</p> + +<h4><u>3. HY MARGIN</u></h4> + +<p> +<strong>HY MARGIN</strong> sets the amount of room allowed at +the end of a line before hyphenation is tripped (e.g. if there's +only 6 points left at the end of a line, groff won't try to hyphenate +the next word). <strong>HY MARGIN</strong> only applies if you're +using +<a href="#QUAD">QUAD</a>, and is really only useful if you're +using <strong>QUAD LEFT</strong>. +</p> + +<p> +As an example, if you don't want groff to hyphenate words when there's +only 18 points of space left at the end of a left-quadded line, +you'd enter + +<pre> + .HY MARGIN 18p +</pre> +</p> + +<p> +<strong>NOTE:</strong> The numeric argument after <strong>HY +MARGIN</strong> requires a +<a href="definitions.html#TERMS_UNITOFMEASURE">unit of measure</a>. +</p> + +<h4><u>4. HY SPACE</u></h4> + +<p> +<strong>HY SPACE</strong> sets an amount of extra interword +space that groff will <em>try</em> to put between words on a +line in order to PREVENT hyphenation. <strong>HY SPACE</strong> +applies only to +<a href="definitions.html#TERMS_JUST">justified lines</a>. +Generally speaking, you'll want this value to be quite small, since +too big a value will result in lines with gaping holes between the +words. A reasonable value might be half a point, or one point, +which you'd set with + +<pre> + .HY SPACE .5p + or + .HY SPACE 1p +</pre> +</p> + +<p> +<strong>NOTE:</strong> The numeric argument after <strong>HY +SPACE</strong> requires a +<a href="definitions.html#TERMS_UNITOFMEASURE">unit of measure</a>. +</p> + +<h4><u>5. HY DEFAULT</u></h4> + +<p> +<strong>HY DEFAULT</strong> resets automatic hyphenation +to its default behaviour, cancelling any changes made with +<strong>HY</strong> <kbd>LINES</kbd>, <strong>HY</strong> +<kbd>MARGIN</kbd>, and/or <strong>HY</strong> <kbd>SPACE</kbd>. +</p> + +<h4><u>A note on hyphenation in general</u></h4> + +<p> +Hyphenation is a necessary evil. If it can be avoided, it should be. +If it can't be, it should occur infrequently. That's the reason for +the number of parameters you can set with <strong>HY</strong>. +</p> + +<p> +Furthermore, hyphenation in +<a href="definitions.html#TERMS_RAG">rag</a> +copy requires a great deal of attention. At best, it should be +avoided completely by individually adjusting the number of words +on consecutive lines to achieve a pleasing, natural-looking rag. +Since such adjustments are often too fussy for document processing, +I recommend playing around with <strong>HY MARGIN</strong> a bit if +your copy looks hyphen-heavy. +</p> + +<!-- -HY_SET- --> + +<hr width="33%" align="left"/> + +<a name="HY_SET"><h3><u>Set hyphenation parameters all at once</u></h3></a> + +<p> +<nobr>Macro: <strong>HY_SET</strong> <kbd><lines> [ <margin> [ <space> ] ]</kbd></nobr> +<br/> + +Alias: <strong>HYSET</strong> +</p> + +<p> +<strong>HY_SET</strong> lets you set the parameters for hyphenation +with a single macro. <kbd><nobr><lines>,</nobr></kbd> +<kbd><nobr><margin></nobr></kbd> and +<kbd><nobr><space></nobr></kbd> correspond to the numeric +values required by <kbd>LINES</kbd>, +<kbd>MARGIN</kbd> and <kbd>SPACE</kbd> as described +<a href="#HY">above</a>. +</p> + +<p> +To set just the maximum number of consecutive hyphenated lines, +you'd enter + +<pre> + .HY_SET 2 +</pre> +</p> + +<p> +If you wanted the same number of maximum consecutive hyphenated lines +and a hyphenation margin for use with +<a href="definitions.html#TERMS_RAG">rag</a> +copy, + +<pre> + .HY_SET 2 36p +</pre> + +would set the hyphenation margin to 36 points. +</p> + +<p> +If you wanted the same number of maximum consecutive hyphenated +lines and a hyphenation space of 2 points for use with +<a href="definitions.html#TERMS_JUST">justified</a> +copy, + +<pre> + .HYSET 2 0 2p +</pre> + +is how you'd do it. +</p> + +<!-- -RW- --> + +<hr width="33%" align="left"/> + +<a name="RW"><h3><u>Reduce whitespace</u></h3></a> + +<p> +<nobr>Macro: <strong>RW</strong> <kbd><amount of whitespace reduction between letters></kbd></nobr> +</p> + +<p> +<strong>RW</strong> (Reduce Whitespace) and its corresponding macro, +<strong>EW</strong> (Expand Whitespace), allow you to tighten +(or loosen) +<a href="definitions.html#TERMS_OUTPUTLINE">output lines</a> +by uniformly reducing or expanding the space between characters. +This is particularly useful when you want to squeeze or stretch +lines on a narrow measure. +</p> + +<p> +The value passed to <strong>RW</strong> may be a whole number or a +decimal fraction. Since a value of 1 produces a noticeable reduction +in the space between letters at text sizes, you'll most likely use +small decimal values when tightening lines. For example, + +<pre> + .RW .1 + or + .RW .2 +</pre> + +may be just enough to squeeze an extra character or two on a +line without the change in letter spacing being obvious. I +highly recommend previewing your work to assess the effect of +<strong>RW</strong>. +</p> + +<p> +<strong>IMPORTANT:</strong> In versions prior to 1.1.9-a, +<strong>RW</strong> affected all +<a href="definitions.html#TERMS_FONT">fonts</a> +in the +<a href="definitions.html#TERMS_FAMILY">family</a> +current at the time it was invoked. As of 1.1.9-a, this behaviour +has been changed. <strong>RW</strong> affects only the font current +at the time it's invoked, and remains in effect for that font every +time the font is called, hence must be reset to zero to cancel its +effect (<kbd>.RW 0</kbd>) on that font. +</p> + +<p> +<strong>NOTE:</strong> By default, <strong>RW</strong> does not deposit a +<a href="#BR">break</a> +when it's invoked if you're in one of the +<a href="definitions.html#TERMS_FILL">fill</a> +modes (i.e. +<a href="#QUAD">QUAD</a> +<strong>L, R, C, J</strong> or +<a href="#JUSTIFY">JUSTIFY</a>). +If you want +<strong>RW</strong> to break at the ends of the previous +<a href="definitions.html#TERMS_INPUTLINE">input lines</a> +while you're in a fill mode, tell <strong>mom</strong> +that's what you want by invoking the +<a href="#BR_AT_LINE_KERN"><kbd>.BR_AT_LINE_KERN</kbd></a> +toggle macro. +</p> + +<!-- -EW- --> + +<hr width="33%" align="left"/> + +<a name="EW"><h3><u>Expand whitespace</u></h3></a> + +<p> +<nobr>Macro: <strong>EW</strong> <kbd><amount of whitespace expansion between letters></kbd></nobr> +</p> + +<p> +<strong>EW</strong> (Expand Whitespace) expands the amount of +whitespace between letters, effectively "loosening" lines +of type. +</p> + +<p> +The value passed to <strong>EW</strong> may be a whole number or a +decimal fraction. Since a value of 1 produces a noticeable +expansion in the space between letters at text sizes, you'll most likely use +small decimal values when loosening lines. For example, + +<pre> + .EW .1 + or + .EW .2 +</pre> + +may be just enough to open up a line without the change in letter +spacing being obvious. I highly recommend previewing your work to +assess the effect of <strong>EW</strong>. +</p> + +<p> +<strong>IMPORTANT:</strong> In versions prior to 1.1.9-a, +<strong>EW</strong> affected all +<a href="definitions.html#TERMS_FONT">fonts</a> +in the +<a href="definitions.html#TERMS_FAMILY">family</a> +current at the time it was invoked. As of 1.1.9-a, this behaviour +has been changed. <strong>EW</strong> affects only the font +current at the time it's invoked, and remains in effect for that +font every time the font is called, hence must be reset to zero to +cancel its effect (<kbd>.EW 0</kbd>) on that font. +</p> + +<p> +<strong>NOTE:</strong> By default, <strong>EW</strong> does not deposit a +<a href="#BR">break</a> +when it's invoked if you're in one of the +<a href="definitions.html#TERMS_FILL">fill</a> +modes (i.e. +<a href="#QUAD">QUAD</a> +<strong>L, R, C, J</strong> or +<a href="#JUSTIFY">JUSTIFY</a>). +If you want +<strong>EW</strong> to break at the ends of the previous +<a href="definitions.html#TERMS_INPUTLINE">input lines</a> +while you're in a fill mode, tell <strong>mom</strong> +that's what you want by invoking the +<a href="#BR_AT_LINE_KERN"><kbd>.BR_AT_LINE_KERN</kbd></a> +toggle macro. +</p> + +<!-- -BR_AT_LINE_KERN- --> + +<hr width="33%" align="left"/> + +<a name="BR_AT_LINE_KERN"><h3><u>Break before line kerning</u></h3></a> + +<p> +<nobr>Macro: <strong>BR_AT_LINE_KERN</strong> <kbd>toggle</kbd></nobr> +</p> + +<p> +By default, in +<a href="definitions.html#TERMS_FILLED">fill</a> +modes (i.e. +<a href="#QUAD">QUAD</a> +<strong>L, R, C, J</strong> or +<a href="#JUSTIFY">JUSTIFY</a>) +<strong>mom</strong> does not break +<a href="definitions.html#TERMS_INPUTLINE">input lines</a> +when you invoke +<a href="#RW">RW</a> +or +<a href="#EW">EW</a>. +If you'd like her to break input lines prior to <strong>RW</strong> +or <strong>EW</strong>, invoke <kbd>.BR_AT_INPUT_LINE</kbd> +without any argument. To disable the breaks, invoke +<kbd>.BR_AT_INPUT_LINE</kbd> with any argument (<strong>OFF, QUIT, +Q, X</strong>...), like this + +<pre> + .BR_AT_LINE_KERN OFF + or + .BR_AT_LINE_KERN X +</pre> +</p> + +<p> +With <strong>QUAD L, R</strong> or <strong>C</strong>, +<strong>mom</strong> simply breaks the line. With <strong>QUAD +J</strong> (or just <strong>JUSTIFY</strong>, which is the same +thing), she breaks and +<a href="definitions.html#TERMS_FORCE">force justifies</a> +the line prior to <kbd>.EW</kbd> or <kbd>.RW</kbd>. +</p> + +<!-- -KERN- --> + +<hr width="33%" align="left"/> + +<a name="KERN"><h3><u>Automatic kerning</u></h3></a> + +<p> +<nobr>Macro: <strong>KERN</strong> <kbd>toggle</kbd></nobr> +</p> + +<p> +By itself (i.e. with no argument), <strong>KERN</strong> turns +automatic pairwise +<a href="definitions.html#TERMS_KERN">kerning</a> +on. With any argument (e.g. OFF, Q, X), pairwise kerning is turned +off. +</p> + +<p> +Kerning of individual character pairs can be controlled with +the <a href="definitions.html#TERMS_INLINES">inline escapes</a> +<kbd><nobr>\*[BU <n>]</nobr></kbd> and +<kbd><nobr>\*[FU <n>]</nobr></kbd>. See +<a href="inlines.html#INLINE_KERNING_MOM">Inline Escapes, kerning</a>. +</p> + +<!-- -LIGATURES- --> + +<hr width="33%" align="left"/> + +<a name="LIGATURES"><h3><u>Automatic ligature generation</u></h3></a> + +<p> +<nobr>Macro: <strong>LIGATURES</strong> <kbd>toggle</kbd></nobr> +<br/> + +Alias: <strong>LIG</strong> +</p> + +<p> +Provided your current font has +<a href="definitions.html#TERMS_LIGATURES">ligatures</a>, +<strong>LIGATURES</strong>, by itself, turns on automatic +generation of ligatures. When automatic ligature generation is +on, simply typing the letters of a ligature combination will +produce the correct ligature upon output. For example, if you +type the word "finally", the fi combination will be +output as an fi ligature. Generally speaking, ligatures are A +Good Thing, hence <strong>mom</strong> has them on by default. +</p> + +<p> +<strong>LIGATURES</strong> with any argument turns automatic +ligature generation off. +</p> + +<p> +<strong>NOTE:</strong> Not all fonts support ligatures. +</p> + +<hr/> + +<!-- ==================================================================== --> + +<a name="MODIFICATIONS"><h2><u>Type modifications: +<br/> + +pseudo-italic, -bold, -condensed, -extended</u></h2></a> + +<p> +It sometimes happens that a PostScript +<a href="definitions.html#TERMS_FAMILY">family</a> +doesn't contain all the fonts you need. You might, for example, be +missing an italic font, or a bold font. Or you might not be able to +get your hands on a condensed family. That's where these macros and +inline escapes come in. With them, you can fake the fonts you're +missing. A word of caution, though: "faked" fonts are +just that — faked. You should only use them as a last resort, and +then only sparingly. A word or two or a line or two in a faked font +will pass unnoticed; large patches of type in a faked font look +typographically cheap. +</p> + +<a name="INDEX_MODIFICATIONS"><h3><u>Type modifications macro list</u></h3></a> + +<ul> + <li><strong>Pseudo italic</strong></li> + <ul> + <li><a href="#SETSLANT">SETSLANT</a> — degree of pseudo-italicizing</li> + <li><a href="#SLANT_INLINE">\*[SLANT]</a> — inline escape for pseudo-italicizing type</li> + </ul> + <li><strong>Pseudo bold</strong></li> + <ul> + <li><a href="#SETBOLDER">SETBOLDER</a> — amount of emboldening</li> + <li><a href="#BOLDER_INLINE">\*[BOLDER]</a> — inline escape for emboldening type</li> + </ul> + <li><strong>Pseudo condensed</strong></li> + <ul> + <li><a href="#CONDENSE">CONDENSE</a> — percentage for pseudo-condensed type</li> + <li><a href="#COND_INLINE">\*[COND]</a> — inline escape for pseudo-condensed type</li> + </ul> + <li><strong>Pseudo extended</strong></li> + <ul> + <li><a href="#EXTEND">EXTEND</a> — percentage for pseudo-extended type</li> + <li><a href="#EXT_INLINE">\*[EXT]</a> — inline escape for pseudo-extending</li> + </ul> +</ul> + +<!-- -SETSLANT- --> + +<hr width="66%" align="left"/> + +<a name="SETSLANT"><h3><u>Set degree of slant for pseudo-italicizing</u></h3></a> + +<p> +<nobr>Macro: <strong>SETSLANT</strong> <kbd><degrees to slant type> | RESET</kbd></nobr> +</p> + +<p> +Pseudo-italicizing of type is accomplished by slanting a roman font +a certain number of degrees to the right. <strong>SETSLANT</strong> +lets you fix the number of degrees. <strong>Mom</strong>'s default +is 15, which produces an acceptable approximation of an italic font. +If you want another value — say, 13 degrees — you'd set +it by entering + +<pre> + .SETSLANT 13 +</pre> +</p> + +<p> +If you change the degree of slant and later want to set it back +to the <strong>mom</strong> default, do + +<pre> + .SETSLANT RESET +</pre> +</p> + +<p> +<strong>NOTE:</strong> By itself, <strong>SETSLANT</strong> will not +start pseudo-italicizing type; it merely tells <strong>mom</strong> +what degree of slant you want. To start pseudo-italicizing, use the +<a href="definitions.html#TERMS_INLINES">inline escape</a> +<kbd>\*[SLANT]</kbd>. +</p> + +<!-- -\*[SLANT]- --> + +<hr width="33%" align="left"/> + +<a name="SLANT_INLINE"><h3><u>Pseudo italic on/off</u></h3></a> + +<p> +Inline: <kbd>\*[SLANT] — turn pseudo-italic on</kbd> +<br/> + +Inline: <kbd>\*[SLANTX] — turn pseudo-italic off</kbd> +</p> + +<p> +<kbd>\*[SLANT]</kbd> begins pseudo-italicizing type. +<kbd>\*[SLANTX]</kbd> turns the feature off. Both are +<a href="definitions.html#TERMS_INLINES">inline escapes</a>, +therefore they should not appear as separate lines, but rather be +embedded in text lines, like this: + +<pre> + Not \*[SLANT]everything\*[SLANTX] is as it seems. +</pre> +</p> + +<p> +Alternatively, if you wanted the whole line pseudo-italicized, +you'd do + +<pre> + \*[SLANT]Not everything is as it seems.\*[SLANTX] +</pre> +</p> + +<p> +Once <kbd>\*[SLANT]</kbd> is invoked, it remains in effect until +turned off. +</p> + +<p> +<strong>NOTE:</strong> If you're using the +<a href="docprocessing.html#DOCPROCESSING">document processing macros</a> +with +<a href="docprocessing.html#PRINTSTYLE">PRINTSTYLE TYPEWRITE</a>, +<strong>mom</strong> underlines pseudo-italics by default. To +change this behaviour, use the special macro +<a href="docprocessing.html#TYPEWRITE_CONTROL">SLANT_MEANS_SLANT</a>. +</p> + +<!-- -SETBOLDER- --> + +<hr width="33%" align="left"/> + +<a name="SETBOLDER"><h3><u>Set amount of emboldening</u></h3></a> + +<p> +<nobr>Macro: <strong>SETBOLDER</strong> <kbd><amount of emboldening, in machine units> | RESET</kbd></nobr> +</p> + +<p> +Emboldening of type is accomplished by printing characters +twice; the second printing is slightly offset from the first, +effectively "thickening" the character. +<strong>SETBOLDER</strong> lets you set the number of +<a href="definitions.html#TERMS_UNITS">machine units</a> +for the offset. <strong>Mom</strong>'s default is 700 units, which +produces an acceptable approximation of a bold font. If you want +another value — say, 500 units — you'd set it by entering + +<pre> + .SETBOLDER 500 +</pre> +</p> + +<p> +If you change the emboldening offset and later want to set it back +to the <strong>mom</strong> default, do + +<pre> + .SETBOLDER RESET +</pre> +</p> + +<p> +<strong>NOTE:</strong> By itself, <strong>SETBOLDER</strong> +will not start emboldening type; it merely tells +<strong>mom</strong> what you want the emboldening offset to be. +To start emboldening, use the +<a href="definitions.html#TERMS_INLINES">inline escape</a> +<kbd>\*[BOLDER]</kbd>. +</p> + +<!-- -\*[BOLDER]- --> + +<hr width="66%" align="left"/> + +<a name="BOLDER_INLINE"><h3><u>Emboldening on/off</u></h3></a> + +<p> +Inline: <kbd>\*[BOLDER] — turn emboldening on</kbd> +<br/> + +Inline: <kbd>\*[BOLDERX] — turn emboldening off</kbd> +</p> + +<p> +<kbd>\*[BOLDER]</kbd> begins emboldening type. +<kbd>\*[BOLDERX]</kbd> turns the feature off. Both are +<a href="definitions.html#TERMS_INLINES">inline escapes</a>, +therefore they should not appear as separate lines, but rather +be embedded in text lines, like this: + +<pre> + Not \*[BOLDER]everything\*[BOLDERX] is as it seems. +</pre> +</p> + +<p> +Alternatively, if you wanted the whole line emboldened, +you'd do + +<pre> + \*[BOLDER]Not everything is as it seems.\*[BOLDERX] +</pre> +</p> + +<p> +Once <kbd>\*[BOLDER]</kbd> is invoked, it remains in effect +until turned off. +</p> + +<p> +<strong>NOTE:</strong> If you're using the +<a href="docprocessing.html#DOCPROCESSING">document processing macros</a> +with +<a href="docprocessing.html#PRINTSTYLE">PRINTSTYLE TYPEWRITE</a>, +<strong>mom</strong> ignores <kbd>\*[BOLDER]</kbd> requests. +</p> + +<!-- -CONDENSE- --> + +<hr width="33%" align="left"/> + +<a name="CONDENSE"><h3><u>Set percentage for pseudo-condensed type</u></h3></a> + +<p> +<nobr>Macro: <strong>CONDENSE</strong> <kbd><pseudo-condense percentage></kbd></nobr> +</p> + +<p> +Pseudo-condensing of type is accomplished by reducing the width of +characters at a given point size without reducing their height, +effectively narrowing them so they look like condensed type. +<strong>CONDENSE</strong> tells <strong>mom</strong> what +percentage of the normal character width you want the characters +to be condensed. +</p> + +<p> +<strong>Mom</strong> has no default value for +<strong>CONDENSE</strong>, therefore you must set it before using +the +<a href="definitions.html#TERMS_INLINES">inline escape</a> +<a href="#COND_INLINE"><kbd>\*[COND]</kbd></a>. +80 percent of the normal character width is a good value, and you'd +set it like this: + +<pre> + .CONDENSE 80 +</pre> +</p> + +<p> +<strong>NOTE:</strong> By itself, <strong>CONDENSE</strong> will not +start pseudo-condensing type; it merely tells <strong>mom</strong> +what percentage of the normal character width you want characters to +be condensed. To start pseudo-condensing, use the +<a href="definitions.html#TERMS_INLINES">inline escape</a> +<kbd>\*[COND]</kbd>. +</p> + +<p> +<strong>Additional note:</strong> Make sure that pseudo-condensing +is off (with +<a href="#COND_INLINE"><kbd>\*[CONDX]</kbd></a>) +before before making any changes to the pseudo-condense percentage +with <strong>CONDENSE</strong>. +</p> + +<!-- -\*[COND]- --> + +<hr width="33%" align="left"/> + +<a name="COND_INLINE"><h3><u>Pseudo-condensing on/off</u></h3></a> + +<p> +Inline: <kbd>\*[COND] — turn pseudo-condensing on</kbd> +<br/> + +Inline: <kbd>\*[CONDX] — turn pseudo-condensing off</kbd> +</p> + +<p> +<kbd>\*[COND]</kbd> begins pseudo-condensing type. +<kbd>\*[CONDX]</kbd> turns the feature off. Both are +<a href="definitions.html#TERMS_INLINES">inline escapes</a>, +therefore they should not appear as separate lines, but rather +be embedded in text lines, like this: + +<pre> + \*[COND]Not everything is as it seems.\*[CONDX] +</pre> +</p> + +<p> +<kbd>\*[COND]</kbd> remains in effect until you turn it +off with <kbd>\*[CONDX]</kbd>. +</p> + +<p> +<strong>IMPORTANT:</strong> You MUST turn <kbd>\*[COND]</kbd> +off before making any changes to the point size of your type, either +via the +<a href="#PS">PT_SIZE</a> +macro or with the <kbd>\s</kbd> inline escape. If you wish +the new point size to be pseudo-condensed, simply reinvoke +<kbd>\*[COND]</kbd> afterwards. Equally, <kbd>\*[COND]</kbd> must +be turned off before changing the condense percentage with +<a href="#CONDENSE">CONDENSE</a>. +</p> + +<p> +<strong>NOTE:</strong> If you're using the +<a href="docprocessing.html#DOCPROCESSING">document processing macros</a> +with +<a href="docprocessing.html#PRINTSTYLE">PRINTSTYLE TYPEWRITE</a>, +<strong>mom</strong> ignores <kbd>\*[COND]</kbd> requests. +</p> + +<!-- -EXTEND- --> + +<hr width="33%" align="left"/> + +<a name="EXTEND"><h3><u>Set percentage for pseudo-extended type</u></h3></a> + +<p> +<nobr>Macro: <strong>EXTEND</strong> <kbd><pseudo-extend percentage></kbd></nobr> +</p> + +<p> +Pseudo-extending of type is accomplished by increasing the width +of characters at a given point size without increasing their +height, effectively widening them so they look like extended +type. <strong>EXTEND</strong> tells <strong>mom</strong> what +percentage of the normal character width you want the characters to +be extended. +</p> + +<p> +<strong>Mom</strong> has no default value for +<strong>EXTEND</strong>, therefore you must set it before +using the +<a href="definitions.html#TERMS_INLINES">inline escape</a> +<a href="#EXT_INLINE"><kbd>\*[EXT]</kbd></a>. +120% of the normal character width is a good value, and you'd set it +like this: + +<pre> + .EXTEND 120 +</pre> +</p> + +<p> +<strong>NOTE:</strong> By itself, <strong>EXTEND</strong> will not +start pseudo-extending type; it merely tells <strong>mom</strong> +what percentage of the normal character width you want characters to +be extended. To start pseudo-extending, use the +<a href="definitions.html#TERMS_INLINES">inline escape</a> +<kbd>\*[EXT]</kbd>. +</p> + +<p> +<strong>Additional note:</strong> Make sure that pseudo-extending is +off (with +<a href="#EXT_INLINE"><kbd>\*[EXTX]</kbd></a>) +before before making any changes to the pseudo-extend percentage +with <strong>EXTEND</strong>. +</p> + +<!-- -\*[EXT]- --> + +<hr width="33%" align="left"/> + +<a name="EXT_INLINE"><h3><u>Pseudo-extending on/off</u></h3></a> + +<p> +Inline: <kbd>\*[EXT] — turn pseudo-extending on</kbd> +<br/> + +Inline: <kbd>\*[EXTX] — turn pseudo-extending off</kbd> +</p> + +<p> +<kbd>\*[EXT]</kbd> begins pseudo-extending type. +<kbd>\*[EXTX]</kbd> turns the feature off. Both are +<a href="definitions.html#TERMS_INLINES">inline escapes</a>, +therefore they should not appear as separate lines, but rather +be embedded in text lines, like this: + +<pre> + \*[EXT]Not everything is as it seems.\*[EXTX] +</pre> +</p> + +<p> +<kbd>\*[EXT]</kbd> remains in effect until you turn it off with +<kbd>\*[EXTX]</kbd>. +</p> + +<p> +<strong>IMPORTANT:</strong> You MUST turn <kbd>\*[EXT]</kbd> off +before making any changes to the point size of your type, either via +the +<a href="#PS">PT_SIZE</a> +macro or with the <kbd>\s</kbd> inline escape. If you wish the new +point size to be pseudo-extended, simply reinvoke <kbd>\*[EXT]</kbd> +afterwards. Equally, <kbd>\*[EXT]</kbd> must be turned off before +changing the extend percentage with +<a href="#EXTEND">EXTEND</a>. +</p> + +<p> +<strong>NOTE:</strong> If you're using the +<a href="docprocessing.html#DOCPROCESSING">document processing macros</a> +with +<a href="docprocessing.html#PRINTSTYLE">PRINTSTYLE TYPEWRITE</a>, +<strong>mom</strong> ignores <kbd>\*[EXT]</kbd> requests. +</p> + +<hr/> + +<!-- ==================================================================== --> + +<a name="ALDRLD"><h2><u>Vertical movement</u></h2></a> + +The two macros in this section allow you to move down or up on the +page relative to the current +<a href="definitions.html#TERMS_BASELINE">baseline</a>. + +<a name="INDEX_ALDRLD"><h3><u>Vertical movement macro list</u></h3></a> + +<ul> + <li><a href="#ALD">ALD</a> — Advance Lead</li> + <li><a href="#RLD">RLD</a> — Reverse Lead</li> +</ul> + +<!-- -ALD- --> + +<hr width="66%" align="left"/> + +<a name="ALD"><h3><u>Advance Lead (move downward)</u></h3></a> + +<p> +<nobr>Macro: <strong>ALD</strong> <kbd><distance to move downward></kbd></nobr> +<br/> + +<em>*Requires a <a href="definitions.html#TERMS_UNITOFMEASURE">unit of measure</a></em> +</p> + +<p> +<strong>ALD</strong> takes one argument: the distance to move downward +on the page relative to the current vertical position. +</p> + +<p> +Used by itself, or preceded by +<a href="#BR">BR</a>, +<strong>ALD</strong> will advance by one line space plus the +distance you specify. Preceded by +<a href="#EL">EL</a>, +it will advance by exactly the distance you specify. +</p> + +<p> +<strong>ALD</strong> requires a unit of measure. Decimal fractions +are allowed, and values may be combined. Therefore, to move down +on the page by 1/4 of an inch, you could enter either + +<pre> + .ALD .25i + or + .ALD 1P+6p +</pre> +</p> + +<p> +As the mnemonic (<strong>A</strong>dvance +<strong>L</strong>ea<strong>D</strong>) suggests, you'll most often +use <strong>ALD</strong> with +<a href="definitions.html#TERMS_PICASPOINTS">points</a> +of lead. +</p> + +<p> +<strong>NOTE:</strong> if you want to use <strong>ALD</strong> +at the top of a page (i.e. to advance to the starting position +of type on a page), combine the value you want with -1v (minus +one line space), like this: + +<pre> + .ALD 1i-1v +</pre> +</p> + +<p> +At the top of a page, this will advance one inch from the +top edge of the paper. Without the -1v, the same command would +advance one inch from the top of the page plus the distance of +one line space. +</p> + +<!-- -RLD- --> + +<hr width="33%" align="left"/> + +<a name="RLD"><h3><u>Reverse Lead (move upward)</u></h3></a> + +<p> +<nobr>Macro: <strong>RLD</strong> <kbd><distance to move upward></kbd></nobr> +<br/> + +<em>*Requires a <a href="definitions.html#TERMS_UNITOFMEASURE">unit of measure</a></em> +</p> + +<p> +<strong>RLD</strong> takes one argument: the distance to move +upward on the page relative to the current vertical position. +</p> + +<p> +Used by itself, or preceded by +<a href="#BR">BR</a>, +<strong>RLD</strong> will advance by one line space, then +reverse by the distance you specify. Preceded by +<a href="#EL">EL</a>, +it will reverse by exactly the distance you specify. +</p> + +<p> +<strong>RLD</strong> requires a unit of measure. Decimal fractions +are allowed, and values may be combined. Therefore, to move up +on the page by 1/4 of an inch, you could enter either + +<pre> + .RLD .25i + or + .RLD 1P+6p +</pre> +</p> + +<p> +As the mnemonic (<strong>R</strong>everse +<strong>L</strong>ea<strong>D</strong>) suggests, you'll most often +use <strong>RLD</strong> with +<a href="definitions.html#TERMS_PICASPOINTS">points</a> +of lead. +</p> + +<hr/> + +<!-- ==================================================================== --> + +<a name="TABS"><h2><u>Tabs</u></h2></a> + +<p> +<strong>Mom</strong> provides two different kinds of tab setup: +typesetting tabs and string tabs. Neither one has anything to do +with the tab key on your keyboard, and both are utterly divorced +from groff's notion of tabs. I recommend reading this section +carefully in order to understand how <strong>mom</strong> handles +tabs. +</p> + +<p> +<strong>NOTE:</strong> see the section +<a href="typemacdoc.html#TYPESETTING">Using typesetting macros during document processing</a> +for re-assuring information on the use of tabs during +<a href="docprocessing.html#DOCPROCESSING">document processing</a>. +</p> + +<a name="TYPESETTING_TABS"><h3><u>Typesetting tabs</u></h3></a> + +<p> +Typesetting tabs are defined by both an indent from the left margin and +a line length. This is quite different from typewriter-style tab stops +(the groff norm) that only define the left indent. In conjunction +with the +<a href="#MULTI_COLUMNS">multi-column macros</a>, +typesetting tabs significantly facilitate +tabular and columnar work. +</p> + +<p> +Typesetting tabs are created with the +<a href="#TAB_SET">TAB_SET</a> +macro. <strong>TAB_SET</strong> identifies the tab (by number), +establishes its left indent and line length, and optionally sets a +quad direction and fill mode. After tabs have been created with +<strong>TAB_SET</strong>, they can be called at any time with the +<a href="#TAB">TAB</a> +macro. +</p> + +<a name="TYPESETTING_TABS_TUT"><h3><u>Quickie tutorial on typesetting tabs</u></h3></a> + +<p> +Say you want to set up three tabs to produce an employee evaluation +that looks something like this: + +<a name="TYPSETTING_TABS_SAMPLE"></a> +<pre> + CRITERION EVALUATION COMMENTS + + Service Good Many clients specifically request + support from Joe by name. + + Punctuality Satisfactory Tends to arrive after 8:00am, but + often works through lunch hour. + + Team spirit Needs work Persistently gives higher priority + to helping clients than respecting + organizational hierarchy. +</pre> +</p> + +<p> +You want the first tab ("CRITERION") + +<ul> + <li>to begin at the left margin of the page (i.e. no indent)</li> + <li>to have a line length of 5 picas</li> + <li>to be set flush left</li> +</ul> +</p> + +<p> +Tabs must be numbered, and each has to be set up with a separate +<a href="#TAB_SET">TAB_SET</a> +line. Therefore, to set up tab 1, you enter + +<pre> + .TAB_SET 1 0 5P L + | | | | + tab #__| | | |__direction + | | + indent__| |__length +</pre> +</p> + +<p> +You want the second tab ("EVALUATION") + +<ul> + <li>to begin 8 picas from the left margin</li> + <li>to have a length of 9 picas</li> + <li>to be set centred.</li> +</ul> +</p> + +<p> +You set it up like this: + +<pre> + .TAB_SET 2 8P 9P C + | | | | + tab #__| | | |__direction + | | + indent__| |__length +</pre> +</p> + +<p> +You want the third tab ("COMMENTS") + +<ul> + <li>to begin 19 picas from the left margin</li> + <li>to have a length of 17 picas</li> + <li>to be set flush left, <a href="definitions.html#TERMS_FILLED">filled</a></li> +</ul> +</p> + +<p> +The setup looks like this: + +<pre> + .TAB_SET 3 19P 17P L QUAD + | | | | | + | | | | |__fill output lines + | | | | + tab #__| | | |__direction + | | + indent__| |__length +</pre> +</p> + +<p> +Once the tabs are set up, you can call them in one of two ways: + +<ul> + <li><a href="#TAB">TAB</a> (with the tab + number as an argument) breaks the current line, + advances one linespace, and calls the tab.</li> + <li><a href="#TN">TN</a> (Tab Next) keeps + you on the current line and moves over to the next + tab in sequence (i.e. from 1 to 2, 2 to 3, etc.).</li> +</ul> +</p> + +<p> +To exit from tabs and restore your original left margin, line length, +quad direction and fill mode, use +<a href="#TQ">TQ</a> +(Tab Quit). +</p> + +<p> +Here's how the input for our sample employee evaluation looks +(with some introductory parameters): + +<pre> + .PAGE 8.5i 11i 1i 1i 1i + .FAMILY T + .FT R + .PT_SIZE 14 + .LS 16 + .QUAD LEFT + .KERN + .HY OFF + .SS 0 + .TAB_SET 1 0 5P L + .TAB_SET 2 8P 9P C + .TAB_SET 3 19P 17P L QUAD + .TAB 1 + CRITERION + .TN + EVALUATION + .TN + COMMENTS + .SP + .TAB 1 + Service + .TN + Good + .TN + Many clients specifically request support from Joe by name. + .SP + .TAB 1 + Punctuality + .TN + Satisfactory + .TN + Tends to arrive after 8:00am, but often works through lunch hour. + .SP + .TAB 1 + Team spirit + .TN + Needs work + .TN + Persistently gives higher priority to helping clients + than respecting organizational hierarchy. + .TQ +</pre> +</p> + +<p> +Try setting this up and previewing it with + +<pre> + groff -mom -X <filename> +</pre> +</p> + +<p> +Notice how <kbd>.TN</kbd> simply moves over to the next tab, +while the combination <kbd>.SP/.TAB 1</kbd> breaks the +line, advances by one extra linespace, and calls the first tab. +</p> + +<p> +Notice, too, how the <kbd>QUAD</kbd> argument passed to +tab 3 means you don't have to worry about the length of +<a href="definitions.html#TERMS_INPUTLINE">input lines</a>; +<strong>mom</strong> +<a href="definitions.html#TERMS_FILLED">fills</a> +the tab and sets the type flush left. +</p> + +<a name="STRING_TABS"><h3><u>String tabs (autotabs)</u></h3></a> + +<p> +String tabs let you mark off tab positions with +<a href="definitions.html#TERMS_INLINES">inline escapes</a> +embedded in +<a href="definitions.html#TERMS_INPUTLINE">input lines</a>. +Left indents and line lengths are calculated from the beginning and +end positions of the marks. This is especially useful when tab +indents and lengths need to be determined from the text that goes in +each tab. +</p> + +<p> +Setting up string tabs is a two-step procedure. First, you enter an +input line in which you mark off where you want tabs to begin and +end. (This is often best done in conjunction with the +<a href="goodies.html#SILENT">SILENT</a> +macro.) +</p> + +<p> +Next, you invoke the +<a href="#ST">ST</a> +macro for every string tab you defined, and optionally pass quad and +fill information to it. That done, string tabs are called with the +<a href="#TAB">TAB</a> +macro, just like typesetting tabs. +</p> + +<p> +In combination with the +<a href="goodies.html#PAD">PAD</a> +macro and the groff inline escape +<a href="inlines.html#INLINE_HORIZONTAL_GROFF"><kbd>\h</kbd></a> +(move horizontally across the page) or <strong>mom</strong>'s +<a href="inlines.html#INLINE_HORIZONTAL_MOM"><kbd><nobr>\*[FWD <distance>]</nobr></kbd></a> +(move forward) inline, string tabs provide +tremendous flexibility in setting up complex tab structures. +</p> + +<a name="STRING_TABS_TUT"><h3><u>Quickie tutorial on string tabs</u></h3></a> + +<p> +Say you want to set up tabs for the +<a href="#TYPSETTING_TABS_SAMPLE">employee evaluation form</a> +used as an example in the +<a href="#TYPESETTING_TABS_TUT">typesetting tabs tutorial</a>. +This time, though, you want to play around with the point size of +type, so you can't know exactly how long the tabs will be or where +they should start. All you know is + +<ul> + <li>CRITERION is the longest line in tab 1</li> + <li>EVALUATION is the longest line in tab 2</li> + <li>tab 3 should extend to the current right margin</li> + <li>you want a 1 pica gutter between each tab</li> +</ul> +</p> + +<p> +This is an ideal job for string tabs. +</p> + +<p> +The first thing you need for string tabs is an +<a href="definitions.html#TERMS_INPUTLINE">input line</a> +with tab positions marked on it. Tabs are marked with the +<a href="definitions.html#TERMS_INLINES">inline escapes</a> +<a href="#INLINE_ST"><kbd><nobr>\*[ST<n>]</nobr></kbd></a> +and +<a href="#INLINE_ST"><kbd><nobr>\*[ST<n>X]</nobr></kbd></a>, +where <kbd><n></kbd> +is the number you want the tab to have. (In this example, we +enclose the input line with the +<a href="goodies.html#SILENT">SILENT</a> +macro so the line doesn't print. We also use the +<a href="goodies.html#PAD">PAD</a> +macro to permit defining tab 3 as simply "the amount of +space remaining on the input line.") +</p> + +<p> +The setup looks like this: + +<pre> + .SILENT + .PAD "\*[ST1]CRITERION\*[ST1X]\*[FWD 12p]\*[ST2]EVALUATION\*[ST2X]\*[FWD 12p]\*[ST3]#\*[ST3X]" + .SILENT OFF +</pre> +</p> + +<p> +The long line after <kbd>.PAD</kbd> looks scary, but it isn't. +Here's what it means when broken down into its component parts: + +<ul> + <li>The longest line in tab 1 is "CRITERION", so we + enclose CRITERION with begin/end markers for string tab 1: + + <pre> + \*[ST1]CRITERION\*[ST1X] + </pre> + + </li> + <li>We want a 1 pica (12 points) gutter between tab 1 and 2, + so we insert 12 points of space with \*[FWD 12p] + (<strong>F</strong>or<strong>W</strong>ar<strong>D</strong> 12 points): + + <pre> + \*[FWD 12p] + </pre> + + </li> + <li>The longest line in tab 2 is "EVALUATION", so + we enclose EVALUATION with begin/end markers for string + tab 2: + + <pre> + \*[ST2]EVALUATION\*[ST2X] + </pre> + + </li> + <li>We want 1 pica (12 points) between tab 2 and 3, so we + insert 12 points of space with another <kbd><nobr>\*[FWD 12p]</nobr></kbd> + + <pre> + \*[FWD 12p] + </pre> + + </li> + <li>We want tab 3 to be as long as whatever space remains on + the current line length, so we enclose the + <a href="goodies.html#PAD_MARKER">pad marker</a> + (#) with begin/end markers for string tab 3: + + <pre> + \*[ST3]#\*[ST3X] + </pre> + + </li> +</ul> +</p> + +<p> +The tabs are now defined, but they require +<a href="definitions.html#TERMS_QUAD">quad direction</a> +and +<a href="definitions.html#TERMS_FILLED">fill</a> +information. For each string tab defined above, enter a +separate +<a href="#ST">ST</a> +line, like this: + +<pre> + .ST 1 L + .ST 2 L + .ST 3 L QUAD + | | | + | | |__fill output lines + | | + tab__| |__direction + number +</pre> +</p> + +<p> +From here on in, you call the tabs with +<a href="#TAB">TAB</a> +and +<a href="#TN">TN</a> +just like typesetting tabs (see +<a href="#TYPESETTING_TABS_TUT">typesetting tabs tutorial</a>). +</p> + +<p> +Here's the complete setup and entry for the sample employee +evaluation form utilizing string tabs. + +<pre> + .PAGE 8.5i 11i 1i 1i 1i + .FAMILY T + .FT R + .PT_SIZE 14 + .LS 16 + .QUAD LEFT + .KERN + .HY OFF + .SS 0 + .SILENT + .PAD "\*[ST1]CRITERION\*[ST1X]\*[FWD 12p]\*[ST2]EVALUATION\*[ST2X]\*[FWD 12p]\*[ST3]#\*[ST3X]" + .SILENT OFF + .ST 1 L + .ST 2 L + .ST 3 L QUAD + .TAB 1 + CRITERION + .TN + EVALUATION + .TN + COMMENTS + .SP + .TAB 1 + Service + .TN + Good + .TN + Many clients specifically request support from Joe by name. + .SP + .TAB 1 + Punctuality + .TN + Satisfactory + .TN + Tends to arrive after 8:00am, but often works through lunch hour. + .SP + .TAB 1 + Team spirit + .TN + Needs work + .TN + Persistently gives higher priority to helping clients + than respecting organizational hierarchy. + .TQ +</pre> +</p> + +<p> +Try setting this up and previewing it with + +<pre> + groff -mom -X <filename> +</pre> +</p> + +<p> +Now, change the point size of the above sample to 12 and preview +it again. You'll see that the tab structure remains identical (tab +1=CRITERION, tab 2=EVALUATION, tab 3=space remaining, and the gutter +between tabs is still 1 pica), while the position and length +of the tabs have altered because of the new point size. +</p> + +<p> +Now try increasing the gutters to 2 picas (<kbd>\*[FWD 24p]</kbd> or +<kbd>\*[FWD 2P]</kbd> instead of <kbd>\*[FWD 12p]</kbd>). Preview the +file again, and notice how the tab structure remains the same, but +the gutters are wider. +</p> + +<a name="INDEX_TABS"><h3><u>Tabs macro list</u></h3></a> + +<ul> + <li><a href="#TAB_SET">TAB_SET</a> (create typesetting tabs)</li> + <li><a href="#INLINE_ST">\*[ST]...\*[STX]</a> (inline escapes for marking String Tabs)</li> + <li><a href="#ST">ST</a> (set String Tabs)</li> + <li><a href="#TAB">TAB</a> (call tabs)</li> + <li><a href="#TN">TN</a> (Tab Next; call next tab in a sequence)</li> + <li><a href="#TQ">TQ</a> (Tab Quit)</li> +</ul> + +<!-- -TAB_SET- --> + +<hr width="66%" align="left"/> + +<a name="TAB_SET"><h3><u>Set up typesetting tabs</u></h3></a> + +<p> +<nobr>Macro: <strong>TAB_SET</strong> <kbd><tab number> <indent> <length> L | R | C | J [ QUAD ]</kbd></nobr> +<br/> + +<em>*</em><kbd><indent></kbd> <em>and</em> <kbd><length></kbd> <em>require a <a href="definitions.html#TERMS_UNITOFMEASURE">unit of measure</a></em> +</p> + +<p> +<strong>TAB_SET</strong> creates typesetting tabs that later can be +called with +<a href="#TAB">TAB</a>. +Typesetting tabs are numbered, and defined by an indent, a length, +and a "direction", hence <strong>TAB_SET</strong> has four +required arguments: + +<ul> + <li>a tab number</li> + <li>an indent (measured from the left margin of the page, + or, if you're already in a tab, from the left margin of the tab)</li> + <li>a length</li> + <li>a direction</li> +</ul> + +To set up a centred tab 6 picas long and 9 points from the left +margin, you'd enter + +<pre> + .TAB_SET 1 9p 6P C +</pre> +</p> + +<p> +The tab number in the above ("1") is simply an +identifier. It could have been 4, or 17, or 296. There's no +need to set up tabs in numerical sequence. +</p> + +<p> +By default, tabs are in +<a href="definitions.html#TERMS_NOFILL">nofill</a> +mode, meaning you can enter text in tabs on a line-for-line basis +without having to use the +<a href="#BR">BR</a> +macro. If you want a tab to be +<a href="definitions.html#TERMS_FILLED">filled</a>, +pass the optional argument <kbd>QUAD</kbd>, which will make the tab +behave as if you'd entered <kbd><nobr>.QUAD L | R | C</nobr></kbd>. +</p> + +<p> +For +<a href="definitions.html#TERMS_JUST">justified</a> +tabs, simply pass the argument <strong>J</strong> (without the +<strong>QUAD</strong> argument), like this: + +<pre> + .TAB 1 9p 6P J +</pre> +</p> + +<p> +Once tabs are set, they can be called at any time with the +<a href="#TAB"><nobr>TAB <n></nobr></a> +macro, where <n> is the number of the desired tab. +</p> + +<p> +You can set up any number of typesetting tabs. However, be aware +that +<a href="#STRING_TABS">string tabs</a> +are also called with <strong><nobr>TAB <n></nobr></strong>, +so be careful that you don't set up a typesetting tab numbered, +say, 4, when you already have a string tab numbered 4. Every tab, +typesetting or string, must have a unique numeric identifier. +</p> + +<p> +<strong>NOTE:</strong> If you use <strong>TAB_SET</strong> while +you're currently inside a tab, the indent argument is the distance from +the tab's left margin, not the left margin of the page. Therefore, +you should exit tabs (with +<a href="#TQ">TQ</a>) +before creating new tabs (unless, of course, you want to set +up a tab structure within the confines of an existing tab). +</p> + +<p> +<strong>IMPORTANT:</strong> Turn all indents off (see +<a href="#INDENTS">Indents</a>) +before setting up tabs with <strong>TAB_SET</strong>, or +<strong>mom</strong> may get confused. +</p> + +<!-- -INLINE_ST- --> + +<hr width="33%" align="left"/> + +<a name="INLINE_ST"><h3><u>Mark positions of string tabs</u></h3></a> + +<p> +Inlines: <kbd>\*[ST<number>]...\*[ST<number>X]</kbd> +<br/> + +<em>*The <a href="definitions.html#TERMS_QUAD">Quad</a> +direction must be</em> LEFT <em>or</em> JUSTIFY <em>(see</em> +<a href="#QUAD">QUAD</a> +<em>and</em> +<a href="#JUSTIFY">JUSTIFY</a>) +<em>or the +<a name="definitions.html#TERMS_NOFILL">no-fill mode</a> +set to</em> +<a href="#LRC">LEFT</a> +<em>in order for these inlines to function properly. Please see</em> +<a href="#IMPORTANT">IMPORTANT</a>, +<em>below.</em> +</p> + +<p> +String tabs need to be marked off with +<a href="definitions.html#TERMS_INLINES">inline escapes</a> +before being set up with the +<a href="#ST">ST</a> +macro. Any input line may contain string tab markers. +<kbd><number></kbd>, above, means the numeric identifier of the +tab. The following shows a sample input line with string tab +markers. + +<pre> + \*[ST1]Now is the time\*[ST1X] for all \*[ST2]good men\*ST2X] to come to the aid of the party. +</pre> +</p> + +<p> +String tab 1 begins at the start of the line and ends after the word +"time". String tab 2 starts at "good" and ends +after "men". Inline escapes (e.g. font or point size +changes, or horizontal movements, including +<a href="goodies.html#PAD">padding</a>) +are taken into account when <strong>mom</strong> determines the +position and length of string tabs. +</p> + +<p> +Up to nineteen string tabs may be marked (not necessarily all on +the same line, of course), and they must be numbered between 1 +and 19. +</p> + +<p> +Once string tabs have been marked in input lines, they have to +be "set" with +<a href="#ST">ST</a>, +after which they may be called, by number, with +<a href="#TAB">TAB</a>. +</p> + +<p> +<strong>NOTE:</strong> Lines with string tabs marked off in them are +normal input lines, i.e. they get printed, just like any input line. +If you want to set up string tabs without the line printing, use the +<a href="goodies.html#SILENT">SILENT</a> +macro. +</p> + +<p> +<a name="IMPORTANT"><strong>IMPORTANT:</strong></a> +Owing to the way groff processes +<a href="definitions.html#TERMS_INPUTLINE">input lines</a> +and turns them into +<a href="definitions.html#TERMS_OUTPUTLINE">output lines</a>, +it is not possible for <strong>mom</strong> to "guess" the +correct starting position of string tabs marked off in lines that +are centered or set flush right. +</p> + +<p> +Equally, she cannot guess the starting position if a line is fully +justified and broken with +<a href="#SPREAD">SPREAD</a>. +</p> + +<p> +In other words, in order to use string tabs, +<a href="#LRC">LEFT</a> +must be active, or, if +<a href="#QUAD">QUAD LEFT</a> +or +<a href="#JUSTIFY">JUSTIFY</a> +are active, the line on which the string tabs are marked must be +broken "manually" with +<a href="#BR">BR</a> +(but not +<a href="#SPREAD">SPREAD</a>). +</p> + +<p> +To circumvent this behaviour, I recommend using the +<a href="goodies.html#PAD">PAD</a> +to set up string tabs in centered or flush right lines. Say, for +example, you want to use a string tab to underscore the text of a +centered line with a rule. Rather than this, + +<pre> + .CENTER + \*[ST1]A line of text\*[ST1X]\c + .EL + .ST 1 + .TAB 1 + .PT_SIZE 24 + .ALD 3p + \*[RULE] + .RLD 3p + .TQ +</pre> + +you should do: + +<pre> + .QUAD CENTER + .PAD "#\*[ST1]A line of text\*[ST1X]#" + .EL + .ST 1 + .TAB 1 + .PT_SIZE 24 + .ALD 3p + \*[RULE] \" Note that you can't use \*[UP ] or \*[DOWN] with \*[RULE] + .RLD 3p + .TQ +</pre> +</p> + +<!-- -ST- --> + +<hr width="33%" align="left"/> + +<a name="ST"><h3><u>Set string tabs</u></h3></a> + +<p> +<nobr>Macro: <strong>ST</strong> <kbd><tab number> L | R | C | J [ QUAD ]</kbd></nobr> +</p> + +<p> +After string tabs have been marked off on an input line (see +<a href="#INLINE_ST"><kbd>\*[ST]...\*[STX]</kbd></a>), +you need to "set" them by giving them a direction +and, optionally, the <kbd>QUAD</kbd> argument. In this +respect, <strong>ST</strong> is like +<a href="#TAB_SET">TAB_SET</a> +except that you don't have to give <strong>ST</strong> an indent +or a line length (that's already taken care of, inline, by +<kbd>\*[ST]...\*[STX]</kbd>). If you want string tab 1 to be left, +enter + +<pre> + .ST 1 L +</pre> +</p> + +<p> +If you want it to be left and +<a href="definitions.html#TERMS_FILLED">filled</a>, enter + +<pre> + .ST 1 L QUAD +</pre> +</p> + +<p> +If you want it to be justified, enter + +<pre> + .ST 1 J +</pre> +</p> + +<p> +See the +<a href="#STRING_TABS_TUT">Quickie tutorial on string tabs</a> +for a full explanation of setting up string tabs. +</p> + +<!-- -TAB- --> + +<hr width="33%" align="left"/> + +<a name="TAB"><h3><u>Call tabs</u></h3></a> + +<p> +<nobr>Macro: <strong>TAB</strong> <kbd><tab number></kbd></nobr> +<br/> + +Alias: <strong>TB</strong> +</p> + +<p> +After tabs have been defined (either with +<a href="#TAB_SET">TAB_SET</a> +or +<a href="#ST">ST</a>), +<strong>TAB</strong> moves to whatever tab number you pass it as +an argument. For example, + +<pre> + .TAB 3 +</pre> + +moves you to tab 3. +</p> + +<a name="NOTE_TN"></a> + +<p> +<strong>NOTE:</strong> <strong>TAB</strong> breaks the line preceding +it and advances 1 linespace. Hence, + +<pre> + .TAB 1 + A line of text in tab 1. + .TAB 2 + A line of text in tab 2. +</pre> + +produces, on output + +<pre> + A line of text in tab 1. + A line of text in tab 2. +</pre> +</p> + +<p> +If you want the tabs to line up, use +<a href="#TN">TN</a> +(Tab Next), like this: + +<pre> + .TAB 1 + A line of text in tab 1. + .TN + A line of text in tab 2. +</pre> + +which produces + +<pre> + A line of text in tab 1. A line of text in tab 2. +</pre> +</p> + +<p> +If the text in your tabs runs to several lines, and you want the +first lines of each tab to align, you must use the +<a href="#MULTI_COLUMNS">multi-column</a> macros. +</p> + +<p> +<strong>ADDITIONAL NOTE:</strong> Any indents in effect prior to +calling a tab are automatically turned off by <strong>TAB</strong>. +If you were happily zipping down the page with a left indent of 2 +picas turned on, and you call a tab whose indent from the left margin +is 6 picas, your new distance from the left margin will be 6 picas, +not 6 picas plus the 2 pica indent. +</p> + +<!-- -TN- --> + +<hr width="66%" align="left"/> + +<a name="TN"><h3><u>Tab Next</u></h3></a> + +<p> +<nobr>Macro: <strong>TN</strong></nobr> +<br/> + +<em>*In tabs that aren't given the</em> <kbd>QUAD</kbd> <em>argument +when they're set up with</em> +<a href="#TAB_SET">TAB_SET</a> +<em>or</em> +<a href="#ST">ST</a>, +<em>you must terminate the line preceding</em> <kbd>.TN</kbd> +<em>with the</em> <kbd>\c</kbd> <em>inline escape. See the</em> +<a href="#TN_NOTE">ADDITIONAL NOTE</a>. +<em>If you find remembering +whether to put in the <kbd>\c</kbd> bothersome, you may prefer to +use the</em> +<a href="definitions.html#TERMS_INLINES">inline escape</a> +<em>alternative to</em> +<kbd>.TN</kbd>, +<a href="inlines.html#TB+"><kbd>\*[TB+]</kbd></a>, +<em>which works consistently regardless of the fill mode.</em> +</p> + +<p> +<strong>TN</strong> moves over to the next tab in numeric +sequence (tab n+1) without advancing on the page. See the +<a href="#NOTE_TN">NOTE</a> +in the description of the <strong>TAB</strong> macro for an +example of how <strong>TN</strong> works. +</p> + +<p> +<strong>NOTE:</strong> You <em>must</em> put text in the +<a href="definitions.html#TERMS_INPUTLINE">input line</a> +immediately after <strong>TN</strong>. "Stacking" of +<strong>TN</strong>'s is not allowed. In other words, you cannot +do + +<pre> + .TAB 1 + Some text + .TN + Some more text + .TN + .TN + Yet more text +</pre> +</p> + +<p> +The above example, assuming tabs numbered from 1 to 4, should be entered + +<pre> + .TAB 1 + Some text + .TN + Some more text + .TAB 4 + Yet more text +</pre> +</p> + +<p> +<a name="TN_NOTE"><strong>ADDITIONAL NOTE:</strong></a> +In versions of mom prior to 1.1.9, <strong>TN</strong> did not +always work as advertised on the last +<a name="TERMS_OUTPUTLINE">output line</a> +of pages that contained a footer trap (e.g. one set with +<a href="#B_MARGIN">B_MARGIN</a> +or in documents formatted using the +<a href="docprocessing.html#DOCPROCESSING">document processing macros</a>). +</p> + +<p> +<strong>TN</strong> has been re-written so that this should no longer be the +case. However, in order for it to work in tabs that have not been +given a <kbd>QUAD</kbd> argument (see +<a href="#TAB_SET">TAB_SET</a> +and +<a href="#ST">ST</a>) +you must always "join" <strong>.TN</strong> to the line +before it using the +<a href="#JOIN"><kbd>\c</kbd></a> +<a href="definitions.html#TERMS_INLINES">inline escape</a>, +as in the following example: + +<pre> + .TAB_SET 1 0 1P L + .TAB_SET 2 1P 20P L + .TAB 1 + 1.\c + .TN + The first rule of survival is "make and keep good friends." +</pre> +</p> + +<p> +When output, the example will look like this: + +<pre> + 1. The first rule of survival is "make and keep good friends." +</pre> +</p> + +<p> +Conversely, if you did give a <kbd>QUAD</kbd> argument +to <strong>TAB_SET</strong> or <strong>ST</strong>, the +<kbd>\c</kbd> must not be used. +</p> + +<!-- -TQ- --> + +<hr width="33%" align="left"/> + +<a name="TQ"><h3><u>Tab Quit</u></h3></a> + +<p> +<nobr>Macro: <strong>TQ</strong></nobr> +</p> + +<p> +<strong>TQ</strong> takes you out of whatever tab you were in, +advances 1 linespace, and restores the left margin, line length, +quad direction and +<a href="definitions.html#TERMS_FILLED">fill mode</a> +that were in effect prior to invoking any tabs. +</p> + +<hr/> + +<!-- ==================================================================== --> + +<a name="MULTI_COLUMNS"><h2><u>Multi-Columns</u></h2></a> + +<p> +Tabs are not by nature columnar, which is to say that if the text +inside a tab runs to several lines, calling another tab does not +automatically move to the +<a href="definitions.html#TERMS_BASELINE">baseline</a> +of the first line in the previous tab. To demonstrate: + +<pre> + .TAB 1 + Carrots + Potatoes + Broccoli + .TAB 2 + $1.99/5 lbs + $0.25/lb + $0.99/bunch +</pre> + +produces, on output + +<pre> + Carrots + Potatoes + Broccoli + $1.99/5 lbs + $0.25/lb + $0.99/bunch +</pre> + +<p> +The multi-column macros allow you to set tabs in columnar +fashion, rather than line by line. When you invoke multi-column +mode (with +<a href="#MCO">MCO</a>), +<strong>mom</strong> saves the position of the current baseline. +<a href="#MCR">MCR</a> +(Multi-column return) at any point while multi-columns are on +returns you to the saved position. Exiting multi-columns +(<a href="#MCX">MCX</a>) +quits the current tab (if you're in one) and moves you to the +bottom of the longest column. (Note that you do not have to use +multi-columns in conjunction with tabs.) +</p> + +<p> +Using our example above, but setting it in multi-column mode, + +<pre> + .MCO + .TAB 1 + Carrots + Potatoes + Broccoli + .MCR + .TAB 2 + $1.99/5 lbs + $0.25/lb + $0.99/bunch + .MCX +</pre> + +produces +</p> + +<pre> + Carrots $1.99/5 lbs + Potatoes $0.25/lb + Broccoli $0.99/bunch +</pre> +</p> + +<p> +<strong>NOTE:</strong> Do not confuse <strong>MCO</strong> with +the +<a href="docprocessing.html#COLUMNS">COLUMNS</a> +macro in the +<a href="docprocessing.html#DOCPROCESSING">document processing macros</a>. +</p> + +<a name="INDEX_MULTI_COLUMNS"><h3><u>Columns macro list</u></h3></a> + +<ul> + <li><a href="#MCO">MCO (begin multi-column setting)</a></li> + <li><a href="#MCR">MCR (return to top of column)</a></li> + <li><a href="#MCX">MCX (exit multi-columns)</a></li> +</ul> + +<!-- -MCO- --> + +<hr width="66%" align="left"/> + +<a name="MCO"><h3><u>Begin multi-column setting</u></h3></a> + +<p> +<nobr>Macro: <strong>MCO</strong></nobr> +</p> + +<p> +<strong>MCO</strong> (<strong>M</strong>ulti-<strong>C</strong>olumn +<strong>O</strong>n) is the macro you use to begin multi-column +setting. It marks the current +<a href="definitions.html#TERMS_BASELINE">baseline</a> +as the top of your columns, for use later with +<a href="#MCR">MCR</a>. See the +<a href="#MULTI_COLUMNS">introduction to columns</a> +for an explanation of multi-columns and some sample +input. +</p> + +<p> +<strong>NOTE:</strong> Do not confuse <strong>MCO</strong> with +the +<a href="docprocessing.html#COLUMNS">COLUMNS</a> +macro in the +<a href="docprocessing.html#DOCPROCESSING">document processing macros</a>. +</p> + +<!-- -MCR- --> + +<hr width="66%" align="left"/> + +<a name="MCR"><h3><u>Return to top of column</u></h3></a> + +<p> +<nobr>Macro: <strong>MCR</strong></nobr> +</p> + +<p> +Once you've turned multi-columns on (with +<a href="#MCO">MCO</a>), +<strong>MCR</strong>, at any time, returns you to the top of +your columns. +</p> + +<!-- -MCX- --> + +<hr width="33%" align="left"/> + +<a name="MCX"><h3><u>Exit multi-columns</u></h3></a> + +<p> +<nobr>Macro: <strong>MCX</strong> <kbd>[ <distance to advance below longest column> ]</kbd></nobr> +<br/> + +<em>*Optional argument requires a <a href="definitions.html#TERMS_UNITOFMEASURE">unit of measure</a></em> +</p> + +<p> +<strong>MCX</strong> takes you out of any tab you were in (by +silently invoking +<a href="#TQ">TQ</a>) and advances to the bottom of the longest +column. +</p> + +<p> +Without an argument, <strong>MCX</strong> advances 1 linespace +below the longest column. Linespace, in this instance, is the +<a href="definitions.html#TERMS_LEADING">leading</a> +in effect <em>at the moment <strong>MCX</strong> is +invoked.</em> +</p> + +<p> +If you pass the <kbd><nobr><distance></nobr></kbd> argument to +<strong>MCX</strong>, it advances 1 linespace below the longest +column (see above) PLUS the distance specified by the argument. +The argument requires a unit of measure; therefore, to advance +an extra 6 points below where <strong>MCX</strong> would +normally place you, you'd enter + +<pre> + .MCX 6p +</pre> +</p> + +<p> +<strong>NOTE:</strong> If you wish to advance a precise distance +below the +<a href="definitions.html#TERMS_BASELINE">baseline</a> +of the longest column, use <strong>MCX</strong> with an +argument of 0 (zero; no unit of measure required) in conjunction +with the +<a href="#ALD">ALD</a> +macro, like this: + +<pre> + .MCX 0 + .ALD 24p +</pre> +</p> + +<p> +The above advances to precisely 24 points below the baseline +of the longest column. +</p> + +<hr/> + +<!-- ==================================================================== --> + +<a name="INDENTS"><h2><u>Indents</u></h2></a> + +<p> With <strong>mom</strong>'s indents, you can indent from the +left, the right, or both margins. In addition, <strong>mom</strong> +provides temporary left indents (i.e. only one line is indented, as +at the start of a paragraph) and "hanging" left indents +(the reverse of a temporary indent; the first line isn't indented, +subsequent lines are). +</p> + +<a name="INDENTS_TUT"><h3><u>A brief explanation of how mom handles indents</u></h3></a> + +<p> +<strong>Mom</strong> provides five kinds of indents: left, right, +both, temporary, and hanging. Each is invoked by its own name: + +<ul> + <li><strong>IL</strong> (<strong>I</strong>ndent <strong>L</strong>eft)</li> + <li><strong>IR</strong> (<strong>I</strong>ndent <strong>R</strong>ight)</li> + <li><strong>IB</strong> (<strong>I</strong>ndent <strong>B</strong>oth)</li> + <li><strong>HI</strong> (<strong>H</strong>anging <strong>I</strong>ndent)</li> + <li><strong>TI</strong> (<strong>T</strong>emporary <strong>I</strong>ndent)</li> +</ul> +</p> + +<p> +In addition, there are four macros to control exiting from +indents: + +<ul> + <li><strong>IQ</strong> (quit all active indents)</li> + <li><strong>ILX</strong> (exit indent style left)</li> + <li><strong>IRX</strong> (exit indent style right)</li> + <li><strong>IBX</strong> (exit indent style both)</li> +</ul> +</p> + +<p> +This section deals exclusively with <strong>IL, IR</strong> and +<strong>IB</strong>. For an explanation of hanging and temporary +indents — how they work and how to use them — see +<a href="#HI">Hanging indents</a> +and +<a href="#TI">Temporary indents</a>. +</p> + +<p> +The first time you invoke any of <strong>mom</strong>'s indents, +you must supply a measure. For example, + +<pre> + .IL 2P +</pre> + +indents text 2 picas from the left margin (or current tab +indent). +</p> + +<p> +When you want to exit the above indent, use either + +<pre> + .IQ + or + .ILX +</pre> +</p> + +<p> +The next time you want the same indent, invoke it without the +argument, like this: + +<pre> + .IL +</pre> +</p> + +<p> +As you can see, once you've supplied a measure to an indent macro +<strong>mom</strong> stores the value, obviating the need to repeat +it on subsequent invocations. And <strong>mom</strong> doesn't just +store the measure — she hangs on to it tenaciously. Arguments +passed to <strong>IL, IR</strong> and <strong>IB</strong> are +additive. Consider the following: + +<pre> + .LL 20P + .IR 2P \"Indent right by 2 picas + A first block of text... + ... + ... + .IQ \"Turn indent off + A second block of text... + ... + ... + .IR 2P \"Indent right by an additional 2 picas (i.e. 4 picas) + A third block of text... + ... + ... +</pre> +</p> + +<p> +The first block of text is right indented by 2 picas (i.e. the line +length is shortened by 2 picas to 18 picas). The second block of +text, after <strong>IQ</strong>, is, as you'd expect, set to the +full measure. The third block of text — the one to pay attention +to — is not right indented by 2 picas, but rather by 4 picas. +<strong>Mom</strong> adds the value of arguments to <strong>IL, +IR</strong> and <strong>IB</strong> to whatever value is already in +effect. +</p> + +<p> +If you wanted the third block of text in the example above to be +right indented by just 2 picas (the original measure given to +<strong>IR</strong>), you would enter <kbd>.IR</kbd> without an +argument. +</p> + +<p> +Because indent arguments are additive, putting a minus sign in front +of the argument can be used to subtract from the current value. +In the following example, the first line is indented 18 points, +the second is indented 36 points (18+18), and the third is again +indented 18 points (36-18). + +<pre> + .IL 18p \"Indent left by 18 points = 18 points + Now is the time + .IL 18p \"Indent left by 18 points more = 36 points + for all good men to come + .IL -18p \"Indent left by 18 points less = 18 points + to the aid of the party. +</pre> +</p> + +<p> +Sometimes, you may want to clear out the stored indent values +— let <strong>mom</strong> start indenting with a clean slate, +as it were. Giving the optional argument <kbd>CLEAR</kbd> to any of +the "indent quit" macros resets them to zero. + +<ul> + <li><strong>IQ CLEAR</strong> (quit and clear all indents)</li> + <li><strong>ILX CLEAR</strong> (quit and clear indent style left)</li> + <li><strong>IRX CLEAR</strong> (quit and clear indent style right)</li> + <li><strong>IBX CLEAR</strong> (quit and clear indent style both)</li> +</ul> +</p> + +<p> +Indent styles may be combined and manipulated separately. You could, +for example, have a left indent of 4 picas and a right indent of 6 +picas and control each separately, as in the following example. + +<pre> + .IL 4P \"Indent left 4 picas + .IR 6P \"Indent right 6 picas + Some text + .IRX \"Turn off the right indent only + More text \"Text is still indented 4 picas left +</pre> +</p> + +<p> +If, at <kbd>.IRX</kbd>, you wanted the text afterwards to have no +indents (either left or right), you would enter <kbd>.IQ</kbd>, +which exits all indent styles at once. +</p> + +<p> +<strong>A word of advice:</strong> Indents are best used only +when you have a compelling reason not to change the current left +margin or line length. In many instances where indents might +seem expedient, it's better to use tabs, or actually change the +left margin or the line length. <strong>Mom</strong>'s indenting +macros are flexible and powerful, but easy to get tangled up +in. Personally, I don't use them much, except for cutarounds and +multi-level lists ą la html, at which they excel. +</p> + +<p> +<strong>NOTE:</strong> see the section +<a href="typemacdoc.html#TYPESETTING">Typesetting Macros in Document Processing</a> +for information and advice on using indents with the +<a href="docprocessing.html#DOCPROCESSING">document processing macros</a>. +</p> + +<a name="INDEX_INDENTS"><h3><u>Indents macro list</u></h3></a> + +<ul> + <li><a href="#IL">IL</a> (Indent left)</li> + <li><a href="#IR">IR</a> (Indent right)</li> + <li><a href="#IB">IB</a> (Indent both)</li> + <li><a href="#TI">TI</a> (Temporary indent, left)</li> + <li><a href="#HI">HI</a> (Hanging Indent)</li> + <ul> + <li><a href="#NUM_LISTS">A recipe for numbered lists</a></li> + </ul> + <li><a href="#IQ">IQ</a> (Quit indents, all)</li> + <li><a href="#IQ">ILX</a> (Exit indent style left)</li> + <li><a href="#IQ">IRX</a> (Exit indent style right)</li> + <li><a href="#IQ">IBX</a> (Exit indent style both)</li> +</ul> + +<!-- -IL- --> + +<hr width="66%" align="left"/> + +<a name="IL"><h3><u>Indent left</u></h3></a> + +<p> +<nobr>Macro: <strong>IL</strong> <kbd>[ <measure> ]</kbd></nobr> + +<br/> +<em>*The optional argument requires a <a href="definitions.html#TERMS_UNITOFMEASURE">unit of measure</a></em> +</p> + +<p> +<strong>IL</strong> indents text from the left margin of the +page, or if you're in a tab, from the left edge of the tab. Once +<strong>IL</strong> is on, the left indent is applied uniformly to +every subsequent line of text, even if you change the line length. +</p> + +<p> +The first time you invoke <kbd>.IL</kbd>, you must give it a +measure. Subsequent invocations with a measure add to the previous +measure. A minus sign may be prepended to the argument to subtract +from the current measure. The +<a href="inlines.html#INLINE_STRINGWIDTH_GROFF"><kbd>\w</kbd></a> +<a href="definitions.html#TERMS_INLINES">inline escape</a> +may be used to specify a text-dependent measure, in which case +no unit of measure is required. For example, + +<pre> + .IL \w'margarine' +</pre> + +indents text by the width of the word "margarine". +</p> + +<p> +With no argument, <strong>IL</strong> indents by its last +active value. See the +<a href="#INDENTS_TUT">brief explanation of how mom handles indents</a> +for more details. +</p> + +<p> +<strong>NOTE:</strong> Calling a tab (with +<a href="#TAB">TAB</a>) +automatically cancels any active indents. +</p> + +<p> +<strong>ADDITIONAL NOTE:</strong> Invoking <strong>IL</strong> +automatically turns off <strong>IB</strong>. +</p> + +<!-- -IR- --> + +<hr width="33%" align="left"/> + +<a name="IR"><h3><u>Indent right</u></h3></a> + +<p> +<nobr>Macro: <strong>IR</strong> <kbd>[ <measure> ]</kbd></nobr> +<br/> + +<em>*The optional argument requires a <a href="definitions.html#TERMS_UNITOFMEASURE">unit of measure</a></em> +</p> + +<p> +<strong>IR</strong> indents text from the right margin of the +page, or if you're in a tab, from the end of the tab. +</p> + +<p> +The first time you invoke <kbd>.IR</kbd>, you must give it a +measure. Subsequent invocations with a measure add to the previous +indent measure. A minus sign may be prepended to the argument to +subtract from the current indent measure. The +<a href="inlines.html#INLINE_STRINGWIDTH_GROFF"><kbd>\w</kbd></a> +<a href="definitions.html#TERMS_INLINES">inline escape</a> +may be used to specify a text-dependent measure, in which case +no unit of measure is required. For example, + +<pre> + .IR \w'jello' +</pre> + +indents text by the width of the word "jello". +</p> + +<p> +With no argument, <strong>IR</strong> indents by its last +active value. See the +<a href="#INDENTS_TUT">brief explanation of how mom handles indents</a> +for more details. +</p> + +<p> +<strong>NOTE:</strong> Calling a tab (with +<a href="#TAB">TAB</a>) +automatically cancels any active indents. +</p> + +<p> +<strong>ADDITIONAL NOTE:</strong> Invoking <strong>IR</strong> +automatically turns off <strong>IB</strong>. +</p> + +<!-- -IB- --> + +<hr width="33%" align="left"/> + +<a name="IB"><h3><u>Indent both</u></h3></a> + +<p> +<nobr>Macro: <strong>IB</strong> <kbd>[ <left measure> <right measure> ]</kbd></nobr> +<br/> + +<em>*The optional arguments require a <a href="definitions.html#TERMS_UNITOFMEASURE">unit of measure</a></em> +</p> + +<p> +<strong>IB</strong> allows you to set or invoke a left and a right +indent at the same time. +</p> + +<p> +At its first invocation, you must supply a measure for both +indents; at subsequent invocations when you wish to supply a +measure, both must be given again. As with <strong>IL</strong> and +<strong>IR</strong>, the measures are added to the values previously +passed to the macro. Hence, if you wish to change just one of the +values, you must give an argument of zero to the other. +</p> + +<p> +<strong>A word of advice:</strong> If you need to manipulate +left and right indents separately, use a combination of +<strong>IL</strong> and <strong>IR</strong> instead of +<strong>IB</strong>. You'll save yourself a lot of grief. +</p> + +<p> +A minus sign may be prepended to the arguments to subtract from +their current values. The +<a href="inlines.html#INLINE_STRINGWIDTH_GROFF"><kbd>\w</kbd></a> +<a href="definitions.html#TERMS_INLINES">inline escape</a> +may be used to specify text-dependent measures, in which case +no unit of measure is required. For example, + +<pre> + .IB \w'margarine' \w'jello' +</pre> + +left indents text by the width of the word "margarine" +and right indents by the width of "jello". +</p> + +<p> +Like <strong>IL</strong> and <strong>IR</strong>, <strong>IB</strong> +with no argument indents by its last active values. See the +<a href="#INDENTS_TUT">brief explanation of how mom handles indents</a> +for more details. +</p> + +<p> +<strong>NOTE:</strong> Calling a tab (with +<a href="#TAB">TAB</a>) +automatically cancels any active indents. +</p> + +<p> +<strong>ADDITIONAL NOTE:</strong> Invoking <strong>IB</strong> +automatically turns off <strong>IL</strong> and +<strong>IR</strong>. +</p> + +<!-- -TI- --> + +<hr width="33%" align="left"/> + +<a name="TI"><h3><u>Temporary (left) indent</u></h3></a> + +<p> +<nobr>Macro: <strong>TI</strong> <kbd>[ <measure> ]</kbd></nobr> +<br/> + +<em>*The optional argument requires a <a href="definitions.html#TERMS_UNITOFMEASURE">unit of measure</a></em> +</p> + +<p> +A temporary indent is one that applies only to the first line of +text that comes after it. Its chief use is indenting the first +line of paragraphs. (<strong>Mom</strong>'s +<a href="docelement.html#PP">PP</a> +macro, for example, uses a temporary indent.) +</p> + +<p> +The first time you invoke <kbd>.TI</kbd>, you must give it +a measure. If you want to indent the first line of a +paragraph by, say, 2 +<a href="definitions.html#TERMS_EM">ems</a>, +do + +<pre> + .TI 2m +</pre> +</p> + +<p> +Subsequent invocations of <strong>TI</strong> do not require you +to supply a measure; <strong>mom</strong> keeps track of the +last measure you gave it. +</p> + +<p> +Because temporary indents are temporary, there's no need to turn +them off. +</p> + +<p> +<strong>IMPORTANT:</strong> Unlike <strong>IL, IR</strong> and +<strong>IB</strong>, measures given to <strong>TI</strong> +are NOT additive. In the following example, the second <kbd>.TI +2P</kbd> is exactly 2 picas. + +<pre> + .TI 1P + The beginning of a paragraph... + .TI 2P + The beginning of another paragraph... +</pre> +</p> + +<!-- -HI- --> + +<hr width="66%" align="left"/> + +<a name="HI"><h3><u>Hanging indent</u></h3></a> + +<p> +<nobr>Macro: <strong>HI</strong> <kbd>[ <measure> ]</kbd></nobr> +<br/> + +<em>*The optional argument requires a <a href="definitions.html#TERMS_UNITOFMEASURE">unit of measure</a></em> +</p> + +<p> +A hanging indent looks like this: + +<pre> + The 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, at length I would be avenged... +</pre> +</p> + +<p> +The first line of text "hangs" outside the left +margin. +</p> + +<p> +In order to use hanging indents, you must first have a left indent +active (set with either +<a href="#IL">IL</a> +or +<a href="#IB">IB</a>). +<strong>Mom</strong> will not hang text outside the left margin set with +<a href="#L_MARGIN">L_MARGIN</a> +or outside the left margin of a tab. +</p> + +<p> +The first time you invoke <kbd>.HI</kbd>, you must give it +a measure. If you want the first line of a paragraph to hang by, +say, 1 pica, do + +<pre> + .IL 1P + .HI 1P +</pre> +</p> + +<p> +Subsequent invocations of <strong>HI</strong> do not require you +to supply a measure; <strong>mom</strong> keeps track of the +last measure you gave it. +</p> + +<p> +Generally speaking, you should invoke <strong>HI</strong> +immediately prior to the line you want hung (i.e. without any +intervening +<a href="definitions.html#TERMS_CONTROLLINES">control lines</a>). +And because hanging indents affect only one line, there's no need to +turn them off. +</p> + +<a name="NUM_LISTS"><h4><u>A recipe for numbered lists</u></h4></a> + +<p> +<strong>PLEASE NOTE: mom</strong> now has macros for setting lists (see +<a href="docelement.html#LIST_INTRO">Nested lists</a>), +making this recipe superfluous. It remains here in the hope that +it will clarify the use of hanging indents generally, if no longer +specifically. +</p> + +<p> +Consider the following example: + +<pre> + .PAGE 8.5i 11i 1i 1i 1i 1i + .FAMILY T + .FT R + .PT_SIZE 12 + .LS 14 + .JUSTIFY + .KERN + .SS 0 + .IL \w'\0\0.' \"Indent left by 2 figure spaces and a period + .HI \w'\0\0.' \"Hang first line of text back by 2 figure spaces and a period + 1.\0The most important point to be considered is whether the + answer to the meaning of life, the universe, and everything + really is 42. We have no-one's word on the subject except + Mr. Adams'. + .HI + 2.\0If the answer to the meaning of life, the universe, + and everything is indeed 42, what impact does this have on + the politics of representation? 42 is, after all not a + prime number. Are we to infer that prime numbers don't + deserve equal rights and equal access in the universe? + .HI + 3.\0If 42 is deemed non-exclusionary, how do we present it + as the answer and, at the same time, forestall debate on its + exclusionary implications? +</pre> +</p> + +<p> +First, we invoke a left indent with a measure equal to the width +of 2 +<a href="definitions.html#TERMS_FIGURESPACE">figures spaces</a> +plus a period (using the +<a href="inlines.html#INLINE_STRINGWIDTH_GROFF"><kbd>\w</kbd></a> +inline escape). At this point, the left indent is active; text +afterwards would normally be indented. However, we invoke a hanging +indent of exactly the same width, which hangs the first line (and +first line only!) to the left of the indent by the same distance (in +this case, that means "out to the left margin"). Because +we begin the first line with a number, a period, and a figure space, +the actual text ("The most important point...") starts at +exactly the same spot as the indented lines that follow. +</p> + +<p> +Notice that subsequent invocations of <kbd>.HI</kbd> without a +measure produce exactly the same effect. +</p> + +<p> +Paste the example above into a file and preview it with <kbd>groff +- mom -X <filename></kbd> to see hanging indents in action. +</p> + +<p> +<strong>IMPORTANT:</strong> Unlike <strong>IL, IR</strong> and +<strong>IB</strong>, measures given to <strong>HI</strong> +are NOT additive. Each time you pass a measure to +<strong>HI</strong>, the measure is treated literally. +</p> + +<!-- -IX- --> + +<hr width="33%" align="left"/> + +<a name="IQ"><h3><u>Quitting indents</u></h3></a> + +<p> +<nobr>Macro: <strong>IQ</strong> <kbd>[ CLEAR ]</kbd> (quit any/all indents — see <strong>IMPORTANT NOTE</strong>)</nobr> +<br/> + +<nobr>Macro: <strong>ILX</strong> <kbd>[ CLEAR ]</kbd> (exit <strong>I</strong>ndent <strong>L</strong>eft)</nobr> +<br/> + +<nobr>Macro: <strong>IRX</strong> <kbd>[ CLEAR ]</kbd> (exit <strong>I</strong>ndent <strong>R</strong>ight)</nobr> +<br/> + +<nobr>Macro: <strong>IBX</strong> <kbd>[ CLEAR ]</kbd> (exit <strong>I</strong>ndent <strong>B</strong>oth)</nobr> +</p> + +<p> +<strong>*IMPORTANT NOTE:</strong> <em>Formerly, the macro for +quitting all indents was</em> <strong>IX</strong><em>. This usage +is now deprecated, in favour of</em> <strong>IQ</strong><em>.</em> +<strong>IX</strong> <em>will continue to behave as before, but</em> +<strong>mom</strong> <em>will issue a warning to stderr indicating +that you should update your documents.</em> +</p> + +<p> +<em>As a consequence of this change,</em> <strong>ILX, IRX</strong> +<em>and</em> <strong>IBX</strong> <em>may now also be +invoked as</em> <strong>ILQ, IRQ</strong> <em>and</em> +<strong>IBQ</strong><em>. Both forms are acceptable.</em> +</p> + +<p> +Without an argument, the macros to quit indents merely restore your +original margins and line length. The measures stored in the indent +macros themselves are saved so you can call them again without +having to supply a measure. +</p> + +<p> +If you pass these macros the optional argument <kbd>CLEAR</kbd>, +they not only restore your original left margin and line length, but +also clear any values associated with a particular indent style. +The next time you need an indent of the same style, you have to +supply a measure again. +</p> + +<p> +<kbd>.IQ CLEAR</kbd>, as you'd suspect, quits and clears the values +for all indent styles at once. +</p> + +<hr/> + +<p> +<a href="goodies.html#TOP">Next</a> +<a href="definitions.html#TOP">Prev</a> +<a href="#TOP">Top</a> +<a href="toc.html">Back to Table of Contents</a> +</p> + +</body> +</html> + +<!-- vim: fileencoding=latin1: nomodified: +--> diff --git a/contrib/mom/momdoc/using.html b/contrib/mom/momdoc/using.html new file mode 100644 index 00000000..9ff3e0db --- /dev/null +++ b/contrib/mom/momdoc/using.html @@ -0,0 +1,283 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!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=iso-8859-1"/> +<title>Using mom</title> +</head> +<body bgcolor="#dfdfdf"> + +<!-- ==================================================================== --> + +<a name="TOP"></a> + +<p> +<a href="typesetting.html#TOP">Next</a> +<a href="definitions.html#TOP">Prev</a> +<a href="toc.html">Back to Table of Contents</a> +</p> + +<a name="USING"><h1 align="center"><u>Using mom</u></h1></a> + +<p> +<a href="#USING_INTRO">Introduction</a> +<br/> +<a href="#USING_MACROS">Inputting macros</a> +<br/> +<a href="#USING_INVOKING">Invoking groff</a> +<br/> +<a href="#USING_PREVIEWING">Previewing documents</a> +</p> + +<hr/> + +<h2><a name="USING_INTRO"><u>Introduction</u></a></h2> + +<p> +As explained in the section +<a href="intro.html#INTRO">What is mom?</a>, +<strong>mom</strong> can be used in two ways: for straight +typesetting or for document processing. The difference between +the two is that in straight typesetting, every macro is a literal +typesetting instruction that determines precisely how text +following it will look. Document processing, on the other hand, +uses markup "tags" (e.g. <kbd>.PP</kbd> for paragraphs, +<kbd>.HEAD</kbd> for heads, <kbd>.FOOTNOTE</kbd> for footnotes, +etc.) that make a lot of typesetting decisions automatically. +</p> + +<p> +You tell <strong>mom</strong> that you want to use the document +processing macros with the +<a href="docprocessing.html#START">START</a> +macro, explained below. After <strong>START</strong>, +<strong>mom</strong> determines the appearance of text following +the markup tags automatically, although you, the user, can easily +change how <strong>mom</strong> interprets the tags. This gives you +nearly complete control over document design. In addition, the +typesetting macros, in combination with document processing, let you +meet all sorts of typesetting needs that just can't be covered by +"one macro fits all" markup tags. +</p> + +<a name="USING_MACROS"><h2><u>How to input mom's macros</u></h2></a> + +<p> +Regardless of which way you use <strong>mom</strong>, the +following apply. +</p> + +<ol> + <li> + You need a good text editor for inputting + <strong>mom</strong> files. + + <p> + I cannot recommend highly enough that you use an + editor that lets you write syntax highlighting + rules for <strong>mom</strong>'s macros and + <a href="definitions.html#TERMS_INLINES">inline escapes</a>. + I use the vi clone called elvis, and find it a pure + joy in this regard. Simply colourizing macros and + inlines to half-intensity can be enough to make text stand + out clearly from formatting commands. + </p> + + </li> + + <li> + All <strong>mom</strong>'s macros begin with a period + (dot) and must be entered in upper case (capital) + letters. + </li> + + <li> + Macro + <a href="definitions.html#TERMS_ARGUMENTS">arguments</a> + are separated from the macro itself by spaces. Multiple + arguments to the same macro are separated from each + other by spaces. Any number of spaces may be used. All + arguments to a macro must appear on the same line as the + macro. + </li> + + <li> + Any argument (except a + <a href="definitions.html#TERMS_STRINGARGUMENT">string argument</a>) + that is not a digit must be entered in upper case + (capital) letters. + </li> + + <li> + Any argument that requires a plus or minus sign must + have the plus or minus sign prepended to the argument + with no intervening space (e.g. <kbd>+2, -4</kbd>). + </li> + + <li> + Any argument that requires a + <a href="definitions.html#TERMS_UNITOFMEASURE">unit of measure</a> + must have the unit appended directly to the argument, with + no intervening space (e.g. <kbd>4P, .5i, 2v</kbd>). + </li> + + <li> + <a href="definitions.html#TERMS_STRINGARGUMENT">String arguments</a>, + in the sense that the term is used in this manual, must + be surrounded by double-quotes ("text of + string"). Multiple string arguments are separated + from each other by spaces (each argument surrounded by + double-quotes, of course). + </li> + + <li> + If a string argument, as entered in your text editor, + becomes uncomfortably long (i.e. runs longer than the + visible portion of your screen or window), you may break + it into two or more lines by placing the backslash + character (<kbd>\</kbd>) at the ends of lines to break + them up, like this: + + <pre> + .SUBTITLE "An In-Depth Consideration of the \ + Implications of Forty-Two as the Meaning of Life, \ + The Universe, and Everything" + </pre> + </li> +</ol> + +<p> +It's important that formatted documents be easy to read/interpret +when you're looking at them in a text editor. One way to achieve +this is to group macros that serve a similar purpose together, and +separate them from other groups of macros with a blank comment +line. In groff, that's done with <kbd>\#</kbd> on a line by itself. +Consider the following, which is a template for starting the chapter +of a book. + +<pre> + .TITLE "My Pulitzer Novel" + .AUTHOR "Joe Blow" + .CHAPTER 1 + \# + .DOCTYPE CHAPTER + .PRINTSTYLE TYPESET + \# + .FAM P + .PT_SIZE 10 + .LS 12 + \# + .START +</pre> +</p> + +<a name="USING_INVOKING"><h2><u>Printing — invoking groff with mom</u></h2></a> + +<p> +After you've finished your document, naturally you will want to +print it. This involves invoking groff from the command line. In +all likelihood, you already know how to do this, but in case you +don't, here are two common ways to do it. + +<pre> + groff -mom -l <filename> + groff -mom <filename> | lpr +</pre> +</p> + +<p> +In the first, the <kbd>-l</kbd> option to groff tells groff to +send the output to your printer. In the second, you're doing the +same thing, except you're telling groff to pipe the output to your +printer. Basically, they're the same thing. The only advantage to +the second is that your system may be set up to use something other +than <strong>lpr</strong> as your print command, in which case, you +can replace <kbd>lpr</kbd> with whatever is appropriate to your box. +</p> + +<p> +Sadly, it is well beyond the scope of this manual to tell you +how to set up a printing system. See the README file for +minimum requirements to run groff with <strong>mom</strong>. +</p> + +<p> +<strong>NOTE FOR ADVANCED USERS:</strong> I've sporadically +had groff choke on perfectly innocent sourced files within +<strong>mom</strong> documents. You'll know you have this problem +when groff complains that it can't find the sourced file even when +you can plainly see that the file exists, and that you've given +<kbd>.so</kbd> the right path and name. Should this happen, pass +groff the <kbd>-U</kbd> (unsafe mode) option along with the other +options you require. Theoretically, you only need <kbd>-U</kbd> +with <kbd>.open, .opena, .pso, .sy,</kbd> and <kbd>.pi</kbd>, +however reality seems, at times, to dictate otherwise. +</p> + +<a name="USING_PREVIEWING"><h2><u>How to preview documents</u></h2></a> + +<p> +Other than printing out hard copy, there are two well-established +methods for previewing your work. Both assume you have a working +X server. +</p> + +<p> +Groff itself comes with a quick and dirty previewer called +gxditview. Invoke it with + +<pre> + groff -X -mom filename +</pre> + +It's not particularly pretty, doesn't have many navigation +options, requires a lot of work if you want to use other than +the "standard" groff PostScript fonts, and occasionally +has difficulty accurately reproducing some of +<strong>mom</strong>'s macro effects +(<a href="goodies.html#SMARTQUOTES">smartquotes</a> +and +<a href="goodies.html#LEADER">leaders</a> +come to mind). What it does have going for it is that it's fast and +doesn't gobble up system resources. +</p> + +<p> +A surer way to preview documents is with <strong>gv</strong> +(ghostview). This involves processing documents with groff, +and directing the output to a PostScript file, like this, + +<pre> + groff -mom filename > filename.ps +</pre> + +then opening the .ps file in <strong>gv</strong>. +</p> + +<p> +While that may sound like a lot of work, I've set up my editor +(elvis) to do it for me. Whenever I'm working on a document that +needs previewing/checking, I fire up <strong>gv</strong> with the +"Watch File" option turned on. To look at the file, I +tell elvis to process it (with groff) and send it to a temporary +file (<kbd>groff -mom filename > filename.ps</kbd>), then open +the file inside <strong>gv</strong>. Ever after, when I want to +look at any changes I make, I simply tell elvis to work his magic +again. The Watch File option in <strong>gv</strong> registers that +the file has changed, and automatically loads the new version. +Voilą! — instant previewing. +</p> + +<hr/> + +<p> +<a href="typesetting.html#TOP">Next</a> +<a href="definitions.html#TOP">Prev</a> +<a href="#TOP">Top</a> +<a href="toc.html">Back to Table of Contents</a> +</p> + +</body> +</html> +<!-- vim: fileencoding=latin1: nomodified: +--> |