From 3ba71bae1806d1b02f7d0d0e49d53523bb501c70 Mon Sep 17 00:00:00 2001 From: PTPi Date: Wed, 18 Aug 2010 22:40:25 +0000 Subject: Complete doc overhaul; removed old files --- contrib/mom/momdoc/appendices.html | 802 ---- contrib/mom/momdoc/color.html | 508 --- contrib/mom/momdoc/cover.html | 661 ---- contrib/mom/momdoc/definitions.html | 961 ----- contrib/mom/momdoc/docelement.html | 7004 --------------------------------- contrib/mom/momdoc/docprocessing.html | 3392 ---------------- contrib/mom/momdoc/goodies.html | 1517 ------- contrib/mom/momdoc/graphical.html | 593 --- contrib/mom/momdoc/headfootpage.html | 2256 ----------- contrib/mom/momdoc/inlines.html | 1074 ----- contrib/mom/momdoc/intro.html | 517 --- contrib/mom/momdoc/letters.html | 609 --- contrib/mom/momdoc/macrolist.html | 489 --- contrib/mom/momdoc/rectoverso.html | 321 -- contrib/mom/momdoc/refer.html | 1837 --------- contrib/mom/momdoc/reserved.html | 2705 ------------- contrib/mom/momdoc/toc.html | 463 --- contrib/mom/momdoc/typemacdoc.html | 315 -- contrib/mom/momdoc/typesetting.html | 5099 ------------------------ contrib/mom/momdoc/using.html | 298 -- 20 files changed, 31421 deletions(-) delete mode 100644 contrib/mom/momdoc/appendices.html delete mode 100644 contrib/mom/momdoc/color.html delete mode 100644 contrib/mom/momdoc/cover.html delete mode 100644 contrib/mom/momdoc/definitions.html delete mode 100644 contrib/mom/momdoc/docelement.html delete mode 100644 contrib/mom/momdoc/docprocessing.html delete mode 100644 contrib/mom/momdoc/goodies.html delete mode 100644 contrib/mom/momdoc/graphical.html delete mode 100644 contrib/mom/momdoc/headfootpage.html delete mode 100644 contrib/mom/momdoc/inlines.html delete mode 100644 contrib/mom/momdoc/intro.html delete mode 100644 contrib/mom/momdoc/letters.html delete mode 100644 contrib/mom/momdoc/macrolist.html delete mode 100644 contrib/mom/momdoc/rectoverso.html delete mode 100644 contrib/mom/momdoc/refer.html delete mode 100644 contrib/mom/momdoc/reserved.html delete mode 100644 contrib/mom/momdoc/toc.html delete mode 100644 contrib/mom/momdoc/typemacdoc.html delete mode 100644 contrib/mom/momdoc/typesetting.html delete mode 100644 contrib/mom/momdoc/using.html diff --git a/contrib/mom/momdoc/appendices.html b/contrib/mom/momdoc/appendices.html deleted file mode 100644 index c2af13b8..00000000 --- a/contrib/mom/momdoc/appendices.html +++ /dev/null @@ -1,802 +0,0 @@ - - - - - - -Mom -- Appendices - - - - - - - -

-Next   -Prev   -Back to Table of Contents -

- -

APPENDICES

 - - - -

Further notes on this documentation

 - -

-Some mom users are sure to ask: "Why is this -documentation in html? If mom'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?" -

- -

-Valid questions, to be sure, and mom has -an answer. (Okay — I have an answer, but I speak for -mom.) -

- -

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

- -

-To me, it's essential that people reading mom'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. -

- -
- - - -

Adding PostScript fonts to groff

 - -

-Robert Valiant has set up a web page containing information, -instructions and strategies for adding PostScript and TrueType fonts -to groff. 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 - -

-    http://russia.shaps.hawaii.edu/software/software.html
-
-

- - - -

-Small note: the term -<path_to_groff> in this section refers to the -directory in which groff is installed, typically something -like /usr/share/groff/<version> (for -distro-specific, pre-compiled groff packages) or -/usr/local/share/groff/<version> (if you've -built groff from source). -

- -

-Groff comes with a small library of PostScript -families -(see the -FAMILY -macro for a list). The families have four -fonts -associated with them. These fonts are a combination of -weight -and -shape: - -

-    R  (Roman, usually Medium weight),
-    I  (Italic, usually Medium weight),
-    B  (Bold, usually Roman shape) and
-    BI (Bold Italic)
-
-

- -

-If you do a lot of document processing or typesetting with -mom, 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. -

- -

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

- -

-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 R, -I, B and BI font styles. An example -of this can be seen in the groff PostScript font library itself -(<path_to_groff>/font/devps/): there's one -"family" for Helvetica (HR, HI, HB, HBI) and another for -Helvetica Narrow (HNR, HNI, HNB, HNBI). -

- -

-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 -weights -Helvetica Thin, Helvetic Light, Helvetica Regular, Helvetica Bold, -Helvetica Heavy, etc, and all their associated -shapes -(Roman, Italic, Condensed, Narrow, Extended, Outline, etc). -

- -

-Thus, intuitively, when a typesetter gives mom a -.FAM(ILY) directive, s/he reasonably expects that any -subsequent .FT directive will access the desired font -from the Helvetica family — without the need to state explicitly both -family and font to .FT, as it is explained one can do in -the -FAMILY -and -FT -sections of these documents. -

- -

-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 .FAM(ILY)) and -selecting the desired font (with .FT R -or .FT I), or passing .FT the -lengthy family+fontname (.e.g. .FT HLCDI). -

- -

-Fortunately, groff provides a mechanism whereby it's possible to -extend the basic R, I, B and BI -fonts ("styles" in groff-speak) so that one can, in -fact, create extensive type families, and access all the fonts -in them with .ft (groff) or .FT (mom). -

- -

-Mom uses this mechanism to offer, in addition to -groff's default PostScript font styles, the following: - - - -

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

- -

-Thus, with mom, 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 - -

-    .FAMILY H
-      or
-    .FAM H
-
- -you can access any of those Helvetica fonts simply by -passing the correct argument from the list above to -FT. -

- -

-For example, if you were working in Medium Roman -(.FT R) and you needed Medium Condensed -Italic for a while (assuming it's installed), you'd just type - -

-    .FT CDI
-
- -to access the Medium Condensed Italic font from the Helvetica -family. -

- -

-Mom'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. -

- -

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

- - - -

-However, you may, at needs, want to add to mom'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 - -

-    .sty \n[.fp] L       \" Light Roman
-    .sty \n[.fp] LI      \" Light Italic
-    .sty \n[.fp] LCD     \" Light Condensed Roman
-
-

- -

-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 -How to create a PostScript font for use with groff). -

- -

-For example, if you already have some fonts from the Univers -family installed and have called the family UN, -you might decide at some point to add the Bold Outline font -(UNBO). In which case, you'd add - -

-    .sty \n[.fp] BO      \" Bold Outline
-
- -to the .sty \n[.fp] <font style> list -in om.tmac. -

- -

-Be careful, though, that any styles you add do not conflict -with family names that already exist. -"C", for example, conflicts with the Courier family -(CR, CI, CB, CBI). Were you to create a font -style "C", thinking that .FT C -would give you access to font style once you'd given a -.FAM(ILY) directive, you'd get a nasty surprise: your -type would come out in Courier Roman! -

- -

-VERY IMPORTANT NOTE: mom'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 mom's font extensions -conflict with your own scheme. Should that be the case, comment out -the .sty \n[.fp] <font style> lines -found near the top of the om.tmac file. -

- -

How to create a PostScript font for use with groff

 - -

-These instructions aren't meant to cover all possibilities, merely -to present one way of making PostScript families/fonts available to -groff and mom. -

- -

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

- -

What you need before you start:

- - - -

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

- -

Initial preparation (you only have to do this once):

- -
    -
  1. 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 ~/Fonts, with subdirectories for Type1, - TrueType and Groff fonts. -
    2. - -
  2. 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 -

    - -
      -
    • /usr/share/groff
      • -
    • /usr/local/share/groff
      • -
    • /etc/groff
      • -
    -
    - - 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 /usr/share/groff, - create site-font in /usr/share/groff. -
    3. -
  3. Locate the file <path_to_groff>/font/devps/generate/textmap - and symlink it to textmap in the directory that - contains your personal collection of PostScript fonts. (See the - Small Note, - above, for the meaning of - <path_to_groff>). On my system, - at the time of writing, <path_to_groff> is - /usr/local/share/groff/1.19.2/, - therefore, I symlink it in ~/Fonts/Type1 with - - 
    -ln -s /usr/local/share/groff/1.19.2/font/devps/generate/textmap textmap
-
    -
    4. -
  4. Locate the file <path_to_groff>/font/devps/text.enc and - symlink it to text.enc in your personal font - directory. On my system, in ~/Fonts/Type1 - - 
    -ln -s /usr/local/share/groff/1.19.2/font/devps/text.enc text.enc
-
    -
    5. -
  5. 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 -

    -
      -
    • /usr/lib/ghostscript/fonts
      • -
    • /usr/share/ghostscript/fonts
      • -
    • /usr/share/fonts/type1/gsfonts
      • -
    6. -
- -

Font creation/installation:

- -
    -
  1. Acquire the font in either Type1 (.pfb) or TrueType (.ttf) format.
    2. -
  2. Place the font in your personal font directory; for me, - that's ~/Fonts/Type1 or ~/Fonts/TrueType. -
    3. -
  3. In your personal font directory, run one of the following:
    4. - -
  4. Still in your personal font directory, run
    5. - -
  5. Copy or move GROFF_FONTNAME to your - site-font directory, - or change to the site-font directory and make a symlink to - GROFF_FONTNAME in your personal directory. -
    6. -
  6. 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. -
    7. -
- -

-Written out in full, adding fonts looks like a lot of work. It -isn't. Basically, it's just: - -

-

- -

-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 a rudimentary example, which you can adapt to your own needs. -The script requires an argument (the .pfb filename), then prompts -for the GROFF_FONTNAME. -

- -
-#!/bin/sh
-#
-# Converts .ttf files to .pfb and generates .afm
-# Moves the .afm and .pfb to $HOME/Fonts/Type1
-# Generates a groff font from the .afm file and installs it in $HOME/Fonts/Groff
-# Symlinks the font in 
-# Symlinks the .afm and .pfb in /usr/lib/ghostscript/font/
-#
-
-FONT=`basename $1 .ttf`
-FONTDIR="$HOME/Fonts/TrueType"
-T1_FONTDIR="$HOME/Fonts/Type1"
-GS_FONTDIR="/usr/share/fonts/type1/gsfonts"
-GROFF_SITE_FONTDIR="/usr/local/share/groff/site-font/devps"
-GROFF_FONTS="$HOME/Fonts/Groff"
-TEXTMAP="$T1_FONTDIR/textmap"
-TEXTENC="$T1_FONTDIR/text.enc"
-
-echo -n "Family directory name: "
-read FAMILYDIR
-
-if [ ! -d "$T1_FONTDIR/$FAMILYDIR" ] ; then
-    echo "Creating $FAMILYDIR in $T1_FONTDIR"
-    mkdir $T1_FONTDIR/$FAMILYDIR
-fi
-
-echo -n "Groff name for this font: "
-read FONTNAME
-
-echo "Creating .pfb and .afm files from $FONT.ttf"
-(ttf2pt1 \-b $FONT.ttf)
-
-echo "Moving .afm and .pfb file to $T1_FONTDIR/$FAMILYDIR.."
-mv $FONT.afm $T1_FONTDIR/$FAMILYDIR
-mv $FONT.pfb $T1_FONTDIR/$FAMILYDIR
-
-echo "Changing to $T1_FONTDIR/$FAMILYDIR.."
-cd $T1_FONTDIR/$FAMILYDIR
-
-echo "Creating $FONTNAME.."
-afmtodit -e $TEXTENC $T1_FONTDIR/$FAMILYDIR/$FONT.afm $TEXTMAP $FONTNAME
-mv -i $FONTNAME $GROFF_FONTS
-echo "Linking $FONTNAME in $GROFF_SITE_FONTDIR.."
-sudo ln -s $GROFF_FONTS/$FONTNAME $GROFF_SITE_FONTDIR/$FONTNAME
-
-echo "Linking $FONT.pfb and $FONT.afm in $GS_FONTDIR.."
-cd $GS_FONTDIR
-sudo ln -s $T1_FONTDIR/$FAMILYDIR/$FONT.afm $FONT.afm
-sudo ln -s $T1_FONTDIR/$FAMILYDIR/$FONT.pfb $FONT.pfb
-
-echo "Font installation complete"
-
-exit 0
-
- -
- - - -

Some reflections on mom

 - -

-Mom, 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. -

- -

-If, as Eric Raymond asserts, open source begins with a programmer -scratching a personal itch, then mom 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. -

- -

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

- -

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

- -

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

- -

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

- -

-(ADDENDUM to the previous two paragraphs: A tremendous amount of -effort has gone into creating a groff manual that can be read with -the info browser, as well as creating -truly useful man pages. The info 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.) -

- -

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

- -

-Mom'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 mom's macros should be -able to do so with a minimum of head scratching. -

- -

-Addendum As of version 1.4-a, the main macro -file, om.tmac, is now stripped of comments when groff is built -from sources. om.tmac in the sources themselves still contains the -comments, as do the tarballs posted on mom's -homepage. -

- -
- - - -

Contact the author

 - -

-If you have any questions or comments about mom, -suggestions to make, criticisms to offer, or bugs to report, use the -groff mailing list at -groff@ffii.org -(subscription information available -here) -or contact me, Peter Schaffter, directly at of the following -address: -

- -

-pschaffter@ncf.ca - -

- -

-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. :) -

- -

-If you want to visit mom's homepage, you'll find -it at -

- -

-    http://web.ncf.ca/fs222/mom/mom-01.html. -

- -
- -

-Next   -Prev   -Top   -Back to Table of Contents -

- - - - - diff --git a/contrib/mom/momdoc/color.html b/contrib/mom/momdoc/color.html deleted file mode 100644 index c8b0ea9f..00000000 --- a/contrib/mom/momdoc/color.html +++ /dev/null @@ -1,508 +0,0 @@ - - - - - - -Mom -- Colour - - - - - - - -

-Next   -Prev   -Back to Table of Contents -

- -

Coloured text

- -

-Introduction to coloured text -
- -Index of colour macros -

- -

Introduction to coloured text

 - -

-Mom's support for coloured text is straightforward. -You begin by telling mom about the colours you want -with -NEWCOLOR -or -XCOLOR. -Afterward, any time you want text to be coloured, you either colour -it with an -inline escape -that contains the colour name (e.g. \*[red] or -\*[blue]) or invoke the macro, -COLOR, -with the name of the colour you want. -

- - - -

-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 mom about -the colour, yellow. There are two ways of doing this; see -NEWCOLOR -and -XCOLOR -for a full explanation of the difference between the two. -

- -

-If you use XCOLOR, you'd enter this: - -

-    .XCOLOR yellow
-
-

- -

-If you use NEWCOLOR, you might enter - -

-    .NEWCOLOR yellow RGB #FFFF00
-
-

- - - -

-After "defining" (or "initializing") the colour -"yellow", you'd colourize the name, Jack, either with an -inline escape - -

-    All work and no play makes \*[yellow]Jack\*[black] a dull boy.
-
- -or with the -COLOR -macro - -
-    All work and no play makes
-    .COLOR yellow
-    Jack
-    .COLOR black
-    a dull boy.
-
-

- -

-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. Mom predefines -it for you. -

- -

-For information on using colour during -document processing, -see -Colour support in document processing. -

- -

-Please note: Mom's colour support is for text only. -She doesn't support "fill" (or "background") -colour for solid, enclosed graphical objects (polygons, ellipses) -drawn with groff's \D -inline escapes, -although you may give a colour as one of the arguments to -mom's "box" and "circle" -macros, -DBX -and -DCL -when the first argument to these macros is SOLID. -

- -

-Please also note that if you're accustomed to using groff's -.defcolor to define colours, and groff's inline -\m[<colorname>] to call them, you may continue to -do so without confusing mom. -

- -

Index of colour macros

 - - - - - -
- -

Creating (initializing) a colour with NEWCOLOR

 - -

-Macro: NEWCOLOR <colour name> [<colour scheme>] <colour components> -

- -

-NEWCOLOR lets you create a colour, rather -like an artist mixing paint on a palette. The colour isn't -used immediately; NEWCOLOR merely tells -mom how to mix the colour when you need it. If you -haven't invoked .NEWCOLOR (or -XCOLOR), -mom doesn't have a clue what you mean when you -reference a colour (with -COLOR -or -\*[<color name>]). -

- -

-The first argument to NEWCOLOR 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. -

- -

-The second argument, which is entirely optional, is the "colour -scheme" you want mom to use when mixing the -colour. Valid arguments are - -

-    RBG   (3 components: red green blue)
-    CYM   (3 components: cyan yellow magenta)
-    CMYK  (4 components: cyan magenta yellow black)
-    GRAY  (1 component)
-
- -If you omit the second argument, mom assumes you -want RGB. -

- -

-The final argument is the components of your colour. This can be -hexadecimal string starting with a pound sign (#) (for -colour values in the 0-255 range) or two pound signs (##) -(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 -Tips for newbies.) -

- -

-Thus, to tell mom about a colour named -"YELLOW", you could enter one of the following: - -

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

- -

-After you've told mom about a colour, you can then -get her to set text in that colour either with the -inline escape, -\*[<colorname>], -or the macro, -COLOR. -(See the -example, -above.) -

- -

-Please note: the colorname you give to -NEWCOLOR may be used with groff's -\m[<colorname>] inline escape (the \m -escape is used to set text and rule colours). Thus, assuming a -colorname "blueblack" set with NEWCOLOR, -\*[blueblack] and \m[blueblack] are -equivalent. Furthermore, the colorname can be given as an argument -to groff's -primitive -request, .gcolor (which does the same thing as -\m[<colorname>]). -

- -

-Equally, the colorname may be used with -\M[<colorname>] and .fcolor, which set -the "fill" colour for solid graphical objects. -

- - - -

Tips for newbies

- -

-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 mom's default -RGB colour scheme, and to fire up a color chooser that gives you -the RGB values you want for the colour you select. Plug those -values into the components argument to NEWCOLOR, -and you'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". -

- -

-Alternatively, you can use mom's simpler -XCOLOR -macro to initialize one of the 256 pre-defined X colours by -supplying the name of the color as an argument. -

- - - -
- -

Initializing a colour with XCOLOR

 - -

-Macro: XCOLOR <X colorname> [<alias>] -
- -*<X colorname> must be all one word, all lower case. -
- -(See -Finding X color names -for how to get a list of valid colour names.) -

- -

-XCOLOR is similar to NEWCOLOR in -that it tells mom 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 mom policy, it -must be entered in lower case. -

- -

-For example, if you want to intialize the X colour, coral, all you -have to do is enter - -

-    .XCOLOR coral
-
-

- -

-Afterwards - -

-    .COLOR coral
-
- -will colourize subsequent text coral until you instruct -mom to return to black, or some other pre-defined, -initialized colour. (The -inline escape -\*[coral] will equally colourize text coral after you've -initialized the colour with XCOLOR.) -

- -

-The downside of XCOLOR 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. -

- -

-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 XCOLOR is -a better choice than NEWCOLOR when it comes to -initializing common colors. -

- -

-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 XCOLOR allows you -to come up with more convenient name by which to reference the -colour. For example, you could enter - -

-    .XCOLOR mediumspringgreen mygreen
-        or
-    .XCOLOR mediumspringgreen MYGREEN
-
- -so that whenever you want text mediumspringgreen-ed, you can use -either .COLOR mygreen (or .COLOR MYGREEN) or -the inline escape \*[mygreen] (or -\*[MYGREEN].) -

- -

-Please note: both the colorname and the -alias you give to XCOLOR may be used with -groff's \m[<colorname>] -inline escape (the \m escape is used to set -text and rule colours). Thus, assuming an X-colorname -"mediumspringgreen" set with XCOLOR, and -an alias, "mygreen", \*[mediumspringgreen], -\m[mediumspringgreen], \*[mygreen] and -\m[mygreen] are all equivalent. Furthermore, both -the colorname and the alias can be given as an argument to -groff's -primitive -request, .gcolor (which does the same thing as -\m[<colorname>]). -

- -

-The colorname initialized with XCOLOR -but not the alias may also -be used with groff's inline escape, -\M[<colorname>], and the corresponding primitive, -.fcolor, both of which set the "fill" colour -for solid graphical objects. If you need a colour initialized with -XCOLOR for \M or .fcolor, you -MUST give the full colorname; the alias won't work. - -

-

Finding X color names

 - -

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

- -

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

- -

-Whichever method you use to find X color names, remember that the -names, passed as arguments to XCOLOR, must -be all one word, all in lower case. -

- - - -
- -

Invoking a color

 - -

-Macro: COLOR <colorname> -
- -Inline: \*[<colorname>] -

- - - -

-Once you've told mom about a colour (via -NEWCOLOR -or -XCOLOR, -you use either the macro, COLOR, or the -inline escape, -\*[<colorname>], to cause mom to -set subsequent text in that colour. See the -example, -above, which shows both in action. -

- -

-NOTE: You can use the -\*[<colorname>] inline escape in any -document processing -macro that takes a -string argument. -However, you must remember to reset the colour at the end of the -argument (typically with \*[black]) unless you want all -subsequent invocations of that particular macro to be colourized. -

- -

-Furthermore, if you use \*[<colorname>] in the -string argument passed to -HEAD, -SUBHEAD -or -PARAHEAD, -and you've requested that any of these types of heads be numbered, -the numbers themselves will not be coloured, only the text you -passed the macro. If you wish the numbers to be colourized as -well, you must explicitly tell mom that you wish -all of the head(s), subhead(s) or parahead(s), including the -numbers, colourized by invoking the appropriate -control macro. -

- -

-For colorizing underscored text, see -Colorizing underscored text -in the notes at the end of -UNDERSCORE. -

- -
- -

-Next   -Prev   -Top   -Back to Table of Contents -

- - - - - diff --git a/contrib/mom/momdoc/cover.html b/contrib/mom/momdoc/cover.html deleted file mode 100644 index 3182d084..00000000 --- a/contrib/mom/momdoc/cover.html +++ /dev/null @@ -1,661 +0,0 @@ - - - - - - -Mom -- Document processing, creating a cover page - - - - - - - -

-Next   -Prev   -Back to Table of Contents -

- -

Creating a cover page

 - - - -

Introduction to cover pages

 - -

-As of version 1.19 of mom, you can now have cover -pages generated automatically. -

- -

-Though identical in treatment, mom provides two -kinds of cover pages: section cover pages (which I shall refer to -simply as "cover pages") and document cover pages -("doc covers"). -

- -

-A document cover page -(doc cover) -is what you'd most likely use at the start of a -collated -document, where you might want the name of the complete document, -the author(s) and the copyright line to appear. Another place you -might use a doc cover is for a novel, where you want the title of -the novel, not the chapter title or chapter number, as the first -cover page. -

- -

-A section -cover -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". -

- -

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

- -

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

- -

-Important note: -automatic generation of cover or doc cover pages after the first -one(s) only takes place if you are working with collated documents. -Mom provides no mechanism for saying "print -a section cover here even though I'm still working on the same -(non-collated) document." -

- -

Description of what mom does on cover pages

 - -

-By default, mom typesets cover (and doc cover) -pages identically to -docheaders -(see -How to change the look of docheaders -for a description of what a docheader looks like). The only -differences are - -

-

- -

-You tell mom what you want to appear on cover pages -through the arguments you pass to -COVER -and/or -DOC_COVER. -Provided you have already given mom the -appropriate reference macros (e.g. -TITLE -or -AUTHOR), -she will output cover (and doc cover) pages identically to how she -would output docheaders containing the same information. -

- -

-By default, mom 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 -COVER_ADVANCE/DOC_COVER_ADVANCE. -

- -

-If you request copyright information (and have already given -mom the reference macro, -COPYRIGHT), -she sets it, by default, in a smaller -point size -in the bottom right hand corner of the cover (or doc cover) page. -The default point size and the position can be controlled with -COVER_COPYRIGHT_SIZE/DOC_COVER_COPYRIGHT_SIZE -and -COVER_COPYRIGHT_QUAD/DOC_COVER_COPYRIGHT_QUAD. -

- -

-Similarly, if you request miscellaneous information (and have -already given mom the reference macro, -MISC), -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 -COVER_COPYRIGHT_SIZE/DOC_COVER_COPYRIGHT_SIZE, -but the position can be controlled with -COVER_MISC_QUAD/DOC_COVER_MISC_QUAD. -

- - - -

-NOTE: mom does not set any -headers -or -footers -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 mom that's what you want -with the macros DOC_COVERS_COUNT_PAGES and/or -COVERS_COUNT_PAGES. -

- - - -

-Finally, if you want to design your own cover page(s), you can -always typeset them (using the -typesetting macros), -invoke -.NEWPAGE, -set up your document in full (see -Tutorial — Setting up a mom document), -and lastly invoke -.START. -The cover page (and any typesetting commands on it) will have no -effect on mom's processing of the document itself, -the first page of which, moreover, will be numbered "1" -unless you instruct her otherwise with -PAGENUMBER. -

- - - -
- - - -

-Macro: COVER -
- - - -Macro: DOC_COVER -
- -Required argument: TITLE | DOCTITLE | COVERTITLE | CHAPTER | CHAPTER_TITLE | CHAPTER+TITLE -
- -Optional arguments: [ SUBTITLE AUTHOR DOCTYPE COPYRIGHT MISC BLANKPAGE ] -
- -*Note: these macros should be placed in the -"style-sheet" section of your document setup (see the -Tutorial — Setting up a mom document), -i.e. after PRINTSTYLE (and/or DOCTYPE and/or COPYSTYLE), but -before START. -

- -

-COVER and DOC_COVER behave -identically. The reason mom provides two macros -for automatic cover page generation is so that you can have two -different kinds of covers with different information on each. -

- -

-Imagine, for a moment, you've written a document comprised of three -sections. When you -COLLATE -the document for output, you could use .DOC_COVER -to generate a cover page that contained the name of the entire -document, your (the author's) name, and perhaps the copyright date. -Subsequently, you could use .COVER, after each -.COLLATE but before each -START, -to generate a cover page (or cover "sheet", if you prefer) -containing just the name of the section. -

- -

The required argument

 - -

-Both COVER and DOC_COVER, -whenever invoked, require a first argument, as listed above. -This first argument will become the first bit of information -mom prints on the cover (or doc cover) page (i.e. -it will be the "title"). -

- -

-In order for the information to appear, you must, of course, first -have given mom the appropriate -reference macro. -A list of the arguments with their equivalent reference macros follows. -

- -
-
TITLE
-
- — means the argument you gave to TITLE -
- -
DOCTITLE
-
- — means the argument you gave to DOCTITLE -
- -
COVERTITLE
-
- — means the argument you gave to COVERTITLE - or - DOC_COVERTITLE -
- -
CHAPTER, CHAPTER_TITLE, CHAPTER+TITLE
-
- — see below (How the CHAPTER argument and friends work) -
-
- -
How the CHAPTER argument and friends work
 - -

-CHAPTER, by itself, will print the -CHAPTER_STRING -as well as the chapter number that you gave to -CHAPTER. -For example, assuming a vanilla setup for your chapter - -

-    \# Reference macros
-    .CHAPTER 1
-    .CHAPTER_TITLE "The Bonny Blue Yonder"
-    <other stuff>
-    .COVER CHAPTER \" (or .DOC_COVER CHAPTER)
-    .START
-
- -will simply print - -
-    Chapter 1
-
-

- -

-CHAPTER_TITLE will print the chapter title you -gave to -CHAPTER_TITLE. -For example, assuming a vanilla setup for your chapter - -

-    \# Reference macros
-    .CHAPTER 1
-    .CHAPTER_TITLE "The Bonny Blue Yonder"
-    <other stuff>
-    .COVER CHAPTER_TITLE \" (or .DOC_COVER CHAPTER_TITLE)
-    .START
-
- -will simply print - -
-    The Bonny Blue Yonder
-
-

- -

-CHAPTER+TITLE will print both the -chapter string + number AND the chapter title. For example, -assuming a vanilla setup for your chapter - -

-    \# Reference macros
-    .CHAPTER 1
-    .CHAPTER_TITLE "The Bonny Blue Yonder"
-    <other stuff>
-    .COVER CHAPTER+TITLE \" (or .DOC_COVER CHAPTER+TITLE)
-    .START
-
- -will print - -
-          Chapter 1
-    The Bonny Blue Yonder
-
-

- -

The optional arguments

 - -

-The remainder of the arguments to COVER and -DOC_COVER are optional. They refer specifically to -the information you gave the -reference macros -bearing the same name as the arguments. -

- -

-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 TITLE, AUTHOR, -COPYRIGHT and MISC - -

-    .COVER TITLE AUTHOR COPYRIGHT MISC
-
- -is correct, while - -
-    .COVER TITLE AUTHOR MISC COPYRIGHT
-
- -is not. -

- -
What the DOCTYPE argument means
 - -

-When you pass COVER or DOC_COVER -the argument, DOCTYPE, it refers to the argument you gave -to -DOCTYPE NAMED. -For example, if, in your -docstyle macros -you gave a - -

-    .DOCTYPE NAMED "Abstract"
-
- -the argument, DOCTYPE, in the COVER or -DOC_COVER macros, would mean that you wanted the -word, Abstract, to appear on the cover (or doc cover), just as it -would in the -docheader. -

- -
What the BLANKPAGE argument means
 - -

-If the final argument to DOC_COVER or -COVER is BLANKPAGE, mom -will insert a blank page after the doc cover or cover. This is -particularly useful if you intend to print your document two-sided, -since, in two-sided printing, no text should appear on the reverse -side of cover or title pages. If DOC_COVERS_COUNT_PAGES -and/or COVERS_COUNT_PAGES is enabled, the blank -page will be considered in the pagination scheme. -

- - - -
- - - -

-Macro: COVERS <toggle> -
- -Macro: DOC_COVERS <toggle> -

- -

-By default, if you give mom a -COVER -or -DOC_COVER -macro, she will print it. In a document that contains sections, -articles or chapters formerly treated as "one-off's" but -now being -collated, -such behaviour may not be desirable. -

- -

-Mom lets you selectively enable or disable the -generation of covers and/or doc covers with the toggle macros -COVERS and DOC_COVERS. Because -they're toggle macros, simply invoking them by themselves enables -automatic cover (or doc cover) generation, while invoking them with -any argument at all (OFF, QUIT, X, etc) disables -cover (or doc cover) generation. -

- -

-NOTE: You must place these macros prior to any -instance of -START. -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 OFF, NO, X, etc. argument), is -immediately after the first invocation of START. -By doing so, you ensure they precede all subsequent instances of -START. -

- -
- -

Control macros — changing the defaults for covers and document covers

 - -

-The default typographic appearance of the items on a cover (or doc -cover) page is identical to that of the items in a -docheader. -(See -How to change the look of docheaders -for a description of the defaults.) -

- -

-COPYRIGHT -and -MISC, -which do not appear in docheaders, have the following default -characteristics: - -

    -
  1. The copyright line is set in the bottom right hand corner - of the page, 2 - point sizes - smaller than the size of - running text -
    2. -
  2. 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. -
    3. -
-

- -

-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 -the control macros used for docheaders. -The only difference is the name by which you invoke the control -macro(s). -

- -

-The complete list of cover (and doc cover) page control macros -follows; please refer to the -docheader control macros index -in order to understand how to use them. -

- -

Index of cover and doc cover control macros

 - -
-.COVER_ADVANCE  .DOC_COVER_ADVANCE -+
-.COVER_FAMILY   .DOC_COVER_FAMILY   | like DOCHEADER_
-.COVER_LEAD     .DOC_COVER_LEAD    -+
-
-.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 Notes
-
-.COVER_UNDERLINE    .DOC_COVER_UNDERLINE - like DOCTYPE_UNDERLINE
- - see Notes
-
-.COVERS_COUNT_PAGES .DOC_COVERS_COUNT_PAGES
- - whether to consider cover pages in the pagination scheme; the
-   default is to ignore them
- - see Notes
-
- -
Notes
- - - -

-COVER_MISC and DOC_COVER_MISC -have only two control macros, _COLOR and -_QUAD. The family, font and size of -the MISC argument to COVER -or DOC_COVER are always the same as for -COPYRIGHT. Should you wish the family, font or size -to be different from COPYRIGHT, I suggest setting the -type specs for COPYRIGHT to the ones you want for -MISC, then altering them for COPYRIGHT using -inline escapes -in the -string argument -you pass to the macro, -COPYRIGHT. -(Of course, you could always do the reverse, but if you pass several -arguments to -MISC, -it's more likely you want to get MISC right first.) -

- - - -

-COVER_UNDERLINE and DOC_COVER_UNDERLINE -apply only to the doctype-name that appears on covers or doc -covers, and then only if DOCTYPE is given as one of the -arguments to -COVER -or -DOC_COVER. It is invoked in exactly the -same way as -DOCTYPE_UNDERLINE. -

- - - -

-COVER_COUNTS_PAGES and -DOC_COVER_COUNTS_PAGES are toggle macros, hence -invoking them by themselves means that mom will -consider cover and doc cover pages in the pagination scheme; -invoking them with any argument (OFF, NO, X, -etc.) means they are ignored. The default is to ignore them. -

- -
- -

-Next   -Prev   -Top   -Back to Table of Contents -

- - - - - diff --git a/contrib/mom/momdoc/definitions.html b/contrib/mom/momdoc/definitions.html deleted file mode 100644 index ef762803..00000000 --- a/contrib/mom/momdoc/definitions.html +++ /dev/null @@ -1,961 +0,0 @@ - - - - - - -Mom -- Definitions and Terms - - - - - - - -

-Next   -Prev   -Back to Table of Contents -

- -

Definitions of terms used in this manual

 - -

-Typesetting Terms -
- -Groff Terms -
- -Mom Document Processing Terms -

- -

-I use a number of typesetting-specific and groff-specific terms -throughout this documentation, as well as a few terms that apply -to mom herself. To make life easier, I'll explain -them here. Refer back to this section should you encounter a word -or concept you're not familiar with. -

- -
- -

Typesetting terms

 - - - -
-
Ascender
-
- 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. -
- -
Baseline
-
- The imaginary line on which the bottoms of capital letters and - the bowls of lower case letters rest. -
- -
Ballot box
-
- An unfilled square, usually - cap-height - in size, typically placed beside items in a checklist. -
- -
Bullet
-
- A small, filled circle typically found beside items or points in - a list. -
- -
Cap-height
-
- The height of the tallest capital letter in a given - font - at the current - point size. -
- -
Descender
-
- The portion of a letter that extends beneath the - baseline - (j, q, y are letters with descenders). -
- -
Discretionary hyphen
-
- 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 - - 
-    \%  (backslash followed by a percent)
-
- -
- -
Drop cap
-
- 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. -
- -
Em/en
-
- An em is a relative measurement equal to the width of the - letter M at a given - point size - in a given - font. - 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). -
- -
Family
-
- The collective name by which a collection of - fonts - are known, e.g. Helvetica, Times Roman, Garamond. -
- -
Figure space/Digit space
-
- A - fixed width space - 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 - - 
-    \0  (backslash followed by a zero)
-
- -
- -
Fixed width font
-
- 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. -
- -
Fixed width space
-
- Equal to - word space, - but does not expand or contract when text is - justified. - In groff, fixed width space is entered with - - 
-    \<space> (backslash followed by hitting the the spacebar on your keyboard)
-
- -
- -
Font
-
- The specific - weight - and - shape - of type within a - family, - e.g. light, medium, bold (which are weights), and roman, italic, - condensed (which are shapes). By default, groff knows of four - fonts within its default set of families: R (medium roman), I - (medium italic), B (bold roman) and BI (bold italic). - Mom considerably extends this very basic list. -
- -
Force justify
-
- Sometimes, in - justified - 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. -
- -
Gutter
-
- The vertical whitespace separating columns of type. -
- -
Justify/justification
-
- 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 - quad. -
- -
Kerning
-
- 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. -
- -
Kern Units
-
- A relative distance equal to 1/36 of the current - point size. - Used between individual letters - for - kerning. - Different typesetting systems use different values (1/54 is - popular), and sometimes call kern units by a different name. - -

- Experts: A kern unit has nothing to do with - groff machine units. -

-
- -
Lead/leading
-
- The distance from the - baseline - of one line of type to the line of type immediately beneath - it. Pronounced "ledding." Also called line spacing. Usually - measured in - points. - -

- In case you're interested... 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 - points - 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. -

- -
- -
Leaders
-
- 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. - - 
-    Foreword............... 2
-    Chapter 1.............. 5
-    Chapter 2.............. 38
-    Chapter 3.............. 60
-
- -
- -
Ligature
-
- 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. -
- -
Picas/Points
-
- 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. -
- -
Point Size
-
- The nominal size of type, measured in - points - from the bottom of the longest - descender - to the top of the highest - ascender. - In reality, type is always fractionally smaller than its point - size. -
- -
Quad
-
- 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. -
- -
Rag
-
- 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 - quadded - left. -
- -
Shape
-
- 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.) - -

- Some typical shapes are: - -

    -
  • "Roman", which has no slant, and has letterforms of - average width
    • -
  • "Italic", which is slanted, and has letterforms - of average width
    • -
  • "Condensed", which has no slant, but has - letterforms narrower than the average represented by Roman
    • -
  • "Condensed Italic", which is slanted, with letterforms narrower - than average
    • -
-

- -

- The term - font, - as it is used in these documents, refers to a combination of - weight - and shape. -

- -
- -
Solid/set solid
-
- When no - lead - is added between lines of type (i.e. the - point size - and linespacing are the same), the lines are said to be "set - solid." -
- -
Track kerning/Line kerning
-
- 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. -
- -
Unbreakable space
-
- Equal to - word space, - 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 - - 
-     \~  (backslash followed by a tilde)
-
- -
- -
Weight
-
- 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. -
- -
Word space
-
- The amount of whitespace between words. When text is - justified, - word space expands or contracts to make the margins flush. -
- -
x-height
-
- 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. -
-
- -
- -

Groff terms

 - - - -
-
Alias
-
- A - macro - invoked by a name different from its "official" - name. For example, the official name of the macro to change - family - is FAMILY. Its alias is FAM. - Aliases may be created for any macro (via the - ALIAS - macro) provided the alias uses a name not already taken by the - mom macros or one of the groff - primitives. - For a complete list of words or names you must not use, see the - list of reserved words. -
- -
Arguments
-
- Parameters or information needed by a - macro - to do its job. For example, in the macro - - 
-    .PT_SIZE 12
-
- - 12 is the argument. In the macro - - 
-    .QUAD LEFT
-
- - LEFT is the argument. Arguments are separated from - macros by spaces. Some macros require several arguments; each - is separated by a space. -
- -
Comment Lines
-
- Input lines - introduced with the comment character - - 
-    \#  (backslash followed by the pound sign)
-
- - When processing output, groff silently ignores everything on a - line that begins with the comment character. -
- -
Control Lines
-
- Instructions to groff that appear on a line by themselves, which - means that "control lines" are either - macros - or groff - primitives. - Control lines begin with a period or, occasionally, an apostrophe. -
- -
Filled lines/fill mode
-
- Automatic - justification - or - quadding. - In fill mode, the ends of lines as they appear in your text - editor are ignored. Instead, words from adjoining - input lines - are added one at a time to the output line until no more words - fit. Then, depending whether text is to be - justified - or - quadded - (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). - -

- - Nofill mode (non-filled text) means that groff respects the ends - of lines as they appear in your text editor. -

- -
- -
Inline escapes
-
- Instructions issued to groff that appear as part of an - input line - (as opposed to - macros, - which must appear on a line by themselves). Inline escapes are - always introduced by the backslash character. For example, - - 
-    A line of text with the word T\*[BU 2]oronto in it
-
- - contains the inline escape \*[BU 2] (which means - "move the letter 'o' 2 - kern units - closer to the letter 'T'"). - -

- Mom's inline escapes always take the form - \*[<ESCAPE>], where ESCAPE is - composed of capital letters, sometimes followed immediately by a - digit, sometimes followed by a space and a - numeric argument. - Groff's escapes begin with the backslash - character but typically have no star and are in lower case. For - example, the mom escapes to move forward 6 - points on a line are either - - 

-    \*[FP6]  or  \*[FWD 6p]
-
- - while the groff escape for the same thing is - - 
-        \h'6p'
-
-

- -
- -
Input line
-
- A line of text as it appears in your text editor. -
- -
Macros
-
- Instructions embedded in a document that determine how groff - processes the text for output. mom'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 - primitives. -
- -
Machine units
-
- A machine unit is 1/1000 of a - point - when the groff device is ps. ("ps" means - "PostScript" — the default device for - which groff prepares output, and the device for which - mom was specifically designed.) -
- -
Numeric argument
-
- An - argument - 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 - unit of measure, - a unit of measure must be appended to every digit in - the argument. For example: - - 
-    .ALD 1i-1v
-
- - NOTE: groff does not respect the order of - operations, but rather evaluates arithmetic expressions - from left to right. Parentheses must be used to circumvent - this peculiarity. Not to worry, though. The likelihood of - more than just the occasional plus or minus sign when using - mom's macros is slim. -
- -
Output line
-
- A line of text as it appears in output copy. -
- -
Primitives
-
- 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. -
- -
String Argument
-
- Technically, any - argument - that is not numeric. In this documentation, string argument - means an argument that requires the user to input text. For - example, in the - macro - - 
-    .TITLE "My Pulitzer Novel"
-
- - My Pulitzer Novel is a string argument. - -

- 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 - inline escapes - \(lq and \(rq (leftquote and - rightquote respectively) in place of the double-quote character - ("). -

- -
- -
Unit of measure
-
- The single letter after a - numeric argument - that tells mom what measurement scale the - argument should use. Common valid units are: - - 
-    i (inches)
-    p (points)
-    P (Picas)
-    c (centimetres)
-    m (ems)
-    n (ens)
-    u (machine units)
-    v (the current leading [line space])
-
- -

- 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: - - 

-    .ALD 2v
-    .LL  39P
-    .IL  1i
-
- - The above example advances 2 line spaces and sets the line - length to 39 picas with a left indent of 1 inch. -

- -

- IMPORTANT: Most mom macros - that set the size or measure of something MUST be given a - unit of measure. mom's macros do not have - default units of measure. There are a couple of exceptions, - the most notable of which are PT_SIZE and - LS. Both use - points - as the default unit of measure, which means you don't have to - append "p" to their argument. -

- -

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

- -

- NOTE: 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. -

- -
- -
Zero-width character
-
- The - inline escape - that allows you to print a literal period, apostrophe and, if - output lines - are - filled, - a space that falls at the beginning of an - input line. - It looks like this: - - 
-    \& (backslash followed by an ampersand)
-
- - Normally, groff interprets a period (or an apostrophe) at the - beginning of an input line as meaning that what follows is a - control line. - 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. -
-
- -
- -

Mom's Document Processing Terms

 - - -
-
Blockquote
-
- Cited material other than - quotes. - Typically set at a smaller point size than paragraph text, - indented from the left and right margins. Blockquotes are - filled. -
- -
Control macro
-
- Macros used in - document processing - to control/alter the appearance of document elements (e.g. - heads, quotes, footnotes, - headers, - etc.). -
- -
Document header/docheader
-
- Document information (title, subtitle, author, etc) output at - the top of page one. -
- -
Epigraph
-
- A short, usually cited passage that appears at the beginning of - a chapter, story, or other document. -
- -
Footer/page footer
-
- Document information (frequently author and title) output in - the bottom margin of pages after page one. Not to be - confused with footnotes, which are considered part of - running text. -
- -
Head
-
- A title that introduces a major section of a document. -
- -
Header/page header
-
- Document information (frequently author and title) output in the - top margin of pages after page one. - -

- NOTE: In terms of content and style, headers - and - footers - 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. -

- -
- -
Linebreak/author linebreak
-
- A horizontal gap in - running text, - 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. -
- -
Paragraph head
-
- A title joined to the body of a paragraph; hierarchically one - level beneath - subheads. -
- -
Quote
-
- A quote, to mom, is a line-for-line setting - of quoted material (e.g. poetry, song lyrics, or a snippet of - programming code). You don't have to use - BR - with quotes. -
- -
Running text
-
- In a document formatted with mom, running - text means text that forms the body of the document, including - elements such as heads and subheads. - Docheaders, - headers, - footers - and page numbers are NOT part of running text. -
- -
Subhead
-
- A title used to introduce secondary sections of a document; - hierarchically one level beneath sections introduced by - heads. -
- -
Toggle
-
- 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 - Example 3 - of the section - How to read macro arguments. -
-
- -
- -

-Next   -Prev   -Top   -Back to Table of Contents -

- - - - diff --git a/contrib/mom/momdoc/docelement.html b/contrib/mom/momdoc/docelement.html deleted file mode 100644 index 0e26e38b..00000000 --- a/contrib/mom/momdoc/docelement.html +++ /dev/null @@ -1,7004 +0,0 @@ - - - - - - -Mom -- Document Processing, element tags - - - - - - - -

-Next   -Prev   -Back to Table of Contents -

- -

The document element tags

 - - - -

Introduction to the document element tags

 - -

-Once you've completed the setup for a document (see -Setting up a mom document), -formatting it is a snap. Simply invoke the appropriate tag for -each document element as you need it. The tags are macros that -tell mom, "This is a paragraph, this -is a subhead, this is a footnote," and so on. -

- -

-The list of tags is actually quite small — ideal for the users -mom brought herself into being for (see -Who mom is meant for). -However, the list of macros that control the appearance of the -tags upon output is extensive. Generally, for each tag, -there are -control macros -for the tag's family, font and point size. Where appropriate, there -are macros to control leading, indents, quad and special features as -well. -

- -

-Mom has tasteful defaults for all the tags, hence -you only use the control macros when you want to change the way she -does things. This is usually done prior to -START, -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. -

- -

- -

Control macros — changing defaults

- -

- -

-The control macros for document processing tags let you -"design" the look of all the parts of your documents -— should you wish. At a bare minimum, all tags have macros to -change mom's defaults for family, font, point size -and colour. Where appropriate, there are macros to control leading, -indents and quad as well. -

- -

-In addition, many tags have special macros to control features that -are pertinent to those tags alone. Have a look at the section -dealing with any particular tag to find out what macros control the -tag, and what mom's defaults for the tag are. -

- -

-The control macros may be used at any time during the course of -a document (i.e. before or after -START). 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. -

- -

-And don't forget: the -typesetting macros -can be used at any time, including inside -toggle -tags (affecting only that particular invocation of the tag). -Equally, -inline escapes -can be used in tags that take -string arguments. -

- -

-IMPORTANT NOTE: The family, font, point size, -colour and leading control macros have no effect in -PRINTSTYLE TYPEWRITE, -which sets EVERYTHING in Courier roman, 12/24 (i.e. 12-point type on -a linespace of 24 points). -

- -

-Please also note that the defaults listed with the control macros -apply only to -PRINTSTYLE TYPESET -unless a default for TYPEWRITE is also given. -

- -

-A WORD OF ADVICE: Get familiar with -mom at her default settings before exploring the -control macros. Put her through her paces. See how she behaves. -Get to know what she feels like and how she looks, both in your -text editor and on the printed page. Then, if you don't like -something, use this documentation to find the precise macro you need -to change it. There are tons of control macros. Reading up on -them and trying to remember them all might lead you to think that -mom is complex and unwieldy, which is not only -untrue, but would offend her mightily. -

- -

Arguments to the control macros

 - -
Family and font
 - -

-The arguments to the control macros that end in -_FAMILY or _FONT are the same -as for -FAMILY -and -FT. -

- -
Point size
 - -

-Control macros that end in _SIZE always take -the form +digit or -digit where digit is -the number of -points -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 - -

-    .SUBHEAD_SIZE +1.5
-
-

- -

-There's no need for a -unit of measure -with the _SIZE control macros; points is assumed. -

- -
Colour
 - -

-Control macros that end in _COLOR take as their -argument a colour name pre-defined (or "initialized") -with -NEWCOLOR -or -XCOLOR. -For example, if you want your heads to be red, once you've defined -or initialized the color, red, - -

-    .HEAD_COLOR red
-
- -will turn your heads red. -

- -
Lead/linespacing
 - -

-Control macros that end in _AUTOLEAD take the -same argument as -AUTOLEAD, -viz. a digit that represents the number of points to add to the -tag's point size to arrive at its -lead. -For example, to set footnotes -solid, do - -

-    .FOOTNOTE_AUTOLEAD 0
-
-

- -

-To set footnotes with a 1-point lead (i.e. with the line spacing -one point greater than the footnote's point size), do - -

-    .FOOTNOTE_AUTOLEAD 1
-
-

- -
Indents
 - -

-Except for -PARA_INDENT, -the argument to the control -macros that end in _INDENT can take either a single -digit (whole numbers only; no decimal fractions) with no -unit of measure -appended to it, or a digit with a unit of measure appended. -

- -

-A digit with no unit of measure appended represents by -how much you want your paragraph first-line indents (set with -PARA_INDENT) multiplied to achieve the correct -indent for a particular tag. -

- -

-A digit with a unit of measure appended defines an -absolute indent, relative to nothing. -

- -
Quad/justification style
 - -

-Control macros that end in _QUAD take the same -arguments as -QUAD. -

- -
Underline style, rule weight
 - -

-If mom gives the option to underline a document -element, the weight of the underline and its distance from the -baseline -are controlled by macros -that end in _UNDERLINE. -

- -

-Page elements that are separated from -running text -by a rule (i.e. page headers, page footers and footnotes) are -controlled by macros that end in _RULE_WEIGHT. -

- -

-The weight argument to _UNDERLINE macros is -the same as the argument to -RULE_WEIGHT, -as is the argument to _RULE_WEIGHT macros. -

- -

Document element tags list

 - - - -
- - - -

Epigraphs

 - - - -

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

- -

-By default, mom sets epigraphs centred and -unfilled; -this lets you input them on a line for line basis. This behaviour -can be changed to accomodate -filled -epigraph "blocks." -

- - - -
- - - -

-Macro: EPIGRAPH <toggle> | [ BLOCK ] -

- -

-EPIGRAPH is a toggle, used like this: - -

-    .EPIGRAPH
-    <text of epigraph>
-    .EPIGRAPH OFF
-
-

- -

-OFF, above, could be anything — say, Q -or X — since any argument other than -BLOCK turns it off. -

- -

-If given the argument, BLOCK, EPIGRAPH -sets epigraphs -filled, -justified or quadded in the same direction as paragraphs, indented -equally from both the left and right margins. -

- -

-If a block-style epigraph runs to more than one paragraph (unlikely, -but conceivable), you must introduce every paragraph -— INCLUDING THE FIRST!!! — with the -PP -tag. -

- -

-NOTE: EPIGRAPH should only be used -at the top of a document (i.e. just after -START) -or after -heads. -The latter is not especially recommended, but it does work. In all -other places where you want quotes or cited text, use -QUOTE -or -BLOCKQUOTE. -

- -
- -

Epigraph control macros

 - -

-See -Arguments to the control macros. -

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

Epigraph indent

 - -

-Prior to version 1.4-b, mom allowed -only the passing of an integer to the macro, -EPIGRAPH_INDENT. The integer represented the -amount by which to multiply the argument passed to -PARA_INDENT -to arrive at an indent for block style epigraphs. -

- -

-As of version 1.4-b, you can now append a -unit of measure -to the argument passed to EPIGRAPH_INDENT, -thus setting an absolute indent, relative to nothing. The old -behaviour is still respected, though; in other words, if you pass -EPIGRAPH_INDENT an integer with no unit of measure -appended, the integer represents the amount by which to multiply -PARA_INDENT to arrive at an indent for block style -epigraphs. -

- -

-Please note that if your PARA_INDENT -is 0 (i.e. no indenting of the first line of -paragraphs), you must set an -EPIGRAPH_INDENT yourself, with a unit of measure -appended to the argument. Mom has no default for -EPIGRAPH_INDENT if paragraph first lines are not being -indented. -

- -

-The default value for EPIGRAPH_INDENT is 3 (for -PRINTSTYLE TYPESET) -and 2 (for -PRINTSTYLE TYPEWRITE). -

- -
- - - -

Paragraphs

 - - - -

-The paragraph macro is the one you use most often. Consequently, -it's one of most powerful, yet simplest to use — just -the letters PP. No arguments, nothing. Just -.PP on a line by itself any time, in any document -element, tells mom you want to start a new -paragraph. The spacing and indent appropriate to where you are in -your document are taken care of automatically. -

- -

-By default, mom does not indent the first paragraph -of a document, nor paragraphs that fall immediately after -heads -or -subheads. -The first paragraphs of blockquotes and block-style epigraphs are -also not indented. This behaviour can be changed with the control -macro -INDENT_FIRST_PARAS. -

- -

-In contrast to some other macro sets, mom does -not deposit a blank line between paragraphs. If you want her to do -so, use the control macro PARA_SPACE. (I don't -recommend using this macro with -PRINTSTYLE TYPEWRITE.) -

- -

-Note that mom does not provide "orphan -control" for paragraphs (i.e. even if only one line of a -paragraph fits at the bottom of a page, she will set it on that -page). The reason for this is that writers of fiction often have -single-line paragraphs (e.g. in dialogue). Groff's simplistic -orphan control will break these one-liners — if they fall at -the bottom of the page — to a new page, which is not what you -want. -

- -

-TIP: 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 PP's. The visual -interruption in the flow of text is a serious obstacle to creativity -and critiquing. -

- -

-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 -( ^I ) into .PP (plus a new -line), and pipes the output to groff for processing and printing. -

- -

-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 .blm -primitive -(blank line macro) to instruct groff (and mom) -that blank lines should be interpreted as PP's. - -

-    .blm PP
-
- -tells groff that all blank lines are really the macro PP. -

- - - -
- - - -

-Macro: PP -

- -

-.PP (on a line by itself, of course) tells mom to -start a new paragraph. See -above -for more details. In addition to regular text paragraphs, you can -use PP in -epigraphs, -blockquotes -and -footnotes. -

- -
- -

Paragraph control macros

 - -

-The PP macro being so important, and representing, -as it were, the basis of everything that goes on in a document, -its control is managed in a manner somewhat different from other -document element tags. -

- -
    -
  1. Family control
    2. -
  2. Font control
    3. -
  3. Paragraph colour
    4. -
  4. Leading/linespacing control
    5. -
  5. Justification/quad control
    6. -
  6. First-line indent control
    7. -
  7. Initial paragraphs indent control
    8. -
  8. Paragraph spacing control
    9. -
- -

1. Family

 - -

-The paragraph -family -is set with -FAMILY -prior to -START, -or -DOC_FAMILY -afterwards. Please note that both globally affect the family of -every element in the document. -

- -

-If you wish to change the family for regular text paragraphs only, -invoke .FAMILY immediately after .PP -in EVERY paragraph whose family you wish to differ from the -prevailing document family. -

- -

-Mom's default paragraph (and document) family -is Times Roman. -

- -

2. Font — PP_FONT

 - -

-To change the -font -used in regular text paragraphs, use .PP_FONT, -which takes the same argument as -FT. -PP_FONT may be used before or after -START. -Only regular text paragraphs are affected; paragraphs in -epigraphs, -blockquotes -and -footnotes -remain at their default setting (medium roman) unless you change them -with the appropriate control macros. -

- -

-Mom's default paragraph font is medium roman. -

- -

3. Paragraph colour

 - -

-Mom has no special control macro for colourizing -paragraphs. If you wish a colourized paragraph, you must use the -macro, -COLOR, -or the -inline escape, -\*[<colorname>], -after .PP. The colour must be one pre-defined -(or "initialized") with -NEWCOLOR -or -XCOLOR. -

- -

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

- -

-For example, assuming you have defined the colour, blue, - -

-    .PP
-    .COLOR blue
-    <first paragraph>
-    .HEAD "Monty Python"
-    .SUBHEAD "The Origins of Spam"
-    .PP
-    <second paragraph>
-
- -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. -

- -

-The one document element that is affected by changing the colour of -paragraphs is -paraheads, -since paraheads are attached directly to the body of paragraphs. In -other words, if you change the colour of a paragraph and do not -reset the paragraph colour back to its default, subsequent paraheads -will appear in the same colour as your paragraphs unless you have -explicitly told mom you want a pre-defined (or -"initialized") color (usually black) for your paraheads. -

- -

-See the footnote to -PARAHEAD_COLOR. -

- -

4. Leading

 - -

-The paragraph -leading -is set with -LS -prior to -START, -or -DOC_LEAD -afterwards. Please note that either method globally affects the -leading and spacing of every document element (except -headers -and -footers). -

- -

-If you wish to change the leading of regular text paragraphs only, -invoke .LS immediately after .PP in EVERY -paragraph whose leading you wish to change. -

- -

-HYPER-IMPORTANT NOTE: It is extremely unwise to -change paragraph leading with LS, as it will, -in all cases, screw up mom's ability to balance -the bottom margin of pages. Should you absolutely need to change -paragraph leading with LS, and subsequently want -mom to get back on the right leading track, use the -SHIM -macro. -

- -

-Mom's default paragraph leading (document leading) -is 16 points, adjusted to fill the page. -

- -

5. Justification/quad

 - -

-The justification/quad-direction of regular text paragraphs (i.e. -justified, -or -filled -and -quadded -left/right/centre) is set with -JUSTIFY -or -QUAD -prior to -START, -and with -DOC_QUAD -afterwards. -

- -

-Please note that either method of setting the paragraph -justification/quad-direction also affects -epigraphs -and -footnotes, -but not -blockquotes -(whose default is QUAD LEFT unless you change it with -BLOCKQUOTE_QUAD). -The justification/quad-direction of epigraphs and footnotes may -be changed with their own control macros. -

- -

-If you wish to change the justification/quad-direction of -individual paragraphs, invoke -.JUSTIFY -or -.QUAD -on the line immediately after .PP. Only the paragraph -in question gets justified or quadded differently; subsequent -paragraphs remain unaffected. -

- -

-Mom's default justification/quad-direction for -paragraphs is - -

-

- -

6. First-line indent — PARA_INDENT

 - -

-The first-line indent of paragraphs is controlled by -.PARA_INDENT, which takes one argument: the size of -the indent. PARA_INDENT may be used before or after -START. -A -unit of measure -is required; fractional sizes are allowed. Thus, to set the paragraph -indent to 4-1/2 -ems, do - -

-    .PARA_INDENT 4.5m
-
-

- -

-In addition to establishing the basic first line-indent of -paragraphs, PARA_INDENT also affects -epigraphs, -quotes -and -blockquotes, -whose overall indenting from the left and (where applicable) -right margins is relative to PARA_INDENT if -the _INDENT control macro for these tags has -no unit of -measure appended to it. Furthermore, the first-line indent of -paragraphs within these document elements (as well as footnotes) -is also relative to PARA_INDENT (always 1/2 of -PARA_INDENT)), hence they are also affected. -

- -

-Mom's default PARA_INDENT is 2 ems -for -PRINTSTYLE_TYPESET -and 3 picas (1/2 inch) for -PRINTSTYLE_TYPEWRITE. -

- -

7. Indenting initial paragraphs — INDENT_FIRST_PARAS

 - -

-By default, mom does not indent the first paragraph -of a document, nor the first paragraph after a head or subhead, nor -the first paragraphs of -epigraphs, -blockquotes -or -footnotes -that run to more than one paragraph. - -

- -

-If you wish to have first paragraphs indented, invoke the macro -.INDENT_FIRST_PARAS without an argument, either before or -after -START. -INDENT_FIRST_PARAS is a toggle macro, therefore -passing it any argument (OFF, QUIT, Q, X...) -cancels its effect, meaning that first paragraphs will once again -NOT be indented. -

- -

8. Spacing paragraphs — PARA_SPACE

 - -

-By default, mom does not insert a blank line -between paragraphs. If you would like her to do so, invoke the -macro, .PARA_SPACE, without an argument, either before or -after -START. -PARA_SPACE is a toggle macro, therefore passing -it any argument (OFF, QUIT, Q, X...) cancels its -effect, meaning that paragraphs will once again NOT be separated by -a blank line. -

- -

-NOTE: If PARA_SPACE is on, -mom spaces only those paragraphs that come after -an "initial" paragraph. Initial paragraphs are those -that come immediately after the -docheader, -epigraphs, -heads, -subheads -and -linebreaks. -(The first paragraph after these document elements requires no -blank line to separate it from other paragraphs.) -

- -

-Sometimes, you can be fairly deep into a document before using -PP for the first time, and when you do, because -mom is still waiting for that "initial" -paragraph, she doesn't space it with a blank line, even though -you expect her to. The simple workaround for this is to invoke -.PP twice (in succession) at the point you -expect the blank line to appear. -

- -
- - - -

Main heads

 - - - -

-Main heads — or, in this documentation, just "heads" -— should be used any place you want titles to introduce -major sections of a document. If you wish, mom -can number your heads for you. Head numbers can also be included -hierarchically in numbered -subheads -and -paraheads. -

- -

-By default, heads are centred on the page, underlined, -all in caps. A double linespace precedes each head. In -PRINTSTYLE TYPESET, -heads are bold, slightly larger than paragraph text. -

- -

-If these defaults don't suit you, you can change them with the -head control macros. -

- - - -
- - - -

-Macro: HEAD "<text of head>" [ "<2nd line>" [ "<3rd line>" ... ] ] -

- -

-The argument to HEAD is the text of the head, -surrounded by double-quotes. If you need additional lines for a -head, simply surround each line with double-quotes. -

- -

-NOTE: If a head falls near the bottom of an output -page and mom is unable to fit the head plus at -least one line of text underneath it, she will set the head at -the top of the next page. -

- -

-ADDITIONAL NOTE: If an -input line -in a head (i.e. one of the lines surrounded by double-quotes) has -to be broken by mom in order to fit the current -line-length (say, a narrow column measure), the head underline -(underscore) will not behave. You'll recognize the problem as soon -as you preview your document. If you encounter a head that -misbehaves with respect to underlining, the solution is to -supply each line as you want it as a separate argument -(surrounded by double-quotes) to the HEAD macro. -

- -

-For example, if mom breaks - -

-    .HEAD "This is a very, very, very long head"
-
- -into -
-    This is a very, very, very
-            long head        
-
- -you'll see the misbehaving underscore and should change the -argument to HEAD to - -
-    .HEAD "This is a very, very very" "long head"
-
-

- -
- -

Head control macros

 - -

-There are, in addition to the usual family/font/size/quad control -macros, a number of macros to manage head numbering, spacing, -underlining, and so on. Check them out if you're unhappy with -mom's defaults. -

- -
    -
  1. Family/font/size/colour/quad
    2. -
  2. Caps
    3. -
  3. Pre-head space
    4. -
  4. Underlining
    5. -
  5. Numbering
    6. -
  6. Reset head numbering
    7. -
  7. Vertical inline escapes inside heads
    8. -
- -

1. Family/font/size/colour/quad

 - -

-See -Arguments to the control macros. -

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

2. Capitalizing heads — HEAD_CAPS

 - -

-By default, mom sets heads in caps, regardless -of the -string(s) -you give to -HEAD. -To change this behaviour, do - -

-    .HEAD_CAPS OFF
-
-

- -

-HEAD_CAPS is a toggle macro, therefore you can use -any argument you like instead of OFF (END, -QUIT, Q, X...). To turn HEAD_CAPS back -on, simply invoke it without an argument. -

- -

3. Space before heads — HEAD_SPACE

 - -

-By default, mom deposits 2 blank lines prior to -every head. If you'd prefer just a single blank line, do - -

-    .HEAD_SPACE OFF
-
-

- -

-HEAD_SPACE is a toggle macro, therefore you can use -any argument you like instead of OFF (END, -QUIT, Q, X...). To restore the space before heads to 2 -blank lines, invoke .HEAD_SPACE without an argument. -

- -

4. Underlining heads — HEAD_UNDERLINE

 - -

-By default, mom underlines heads. To change this -behaviour, do - -

-    .HEAD_UNDERLINE OFF
-
-

- -

-HEAD_UNDERLINE can be used as a toggle macro, therefore you can -use any argument you like instead of OFF (END, -QUIT, Q, X...) to turn it off, or invoke it by itself to -turn head underlining on. -

- -

-As of version 1.5 of mom, you can now use -HEAD_UNDERLINE 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 weight, -optionally followed by gap, where "gap" is the -distance from the -baseline -of the head to the underline. -

- -

-The weight argument is given in points, or fractions -thereof, and must NOT have the -unit of measure, -p, appended. Like -RULE_WEIGHT, -weights MUST be greater than 0 and less than 100. -Mom's default for head underlines is 1/2 point. -

- -

-The gap 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. Mom's default -gap for head underlines is 2 points. -

- -

-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: - -

-    .HEAD_UNDERLINE 4 3p
-
- -If you wanted the same thing, but were content with -mom's default gap of 2 points, - -
-    .HEAD_UNDERLINE 4
-
- -would do the trick. -

- -

-Please note that if you supply a weight to -HEAD_UNDERLINE, and optionally a gap, you also turn -the underlining of heads on; if this is not what you want, you must -turn head underlining off manually afterwards. -

- -

5. Number heads — NUMBER_HEADS

 - -

-If you'd like your heads numbered, simply invoke -.NUMBER_HEADS with no argument. Mom -will number all subsequent heads automatically (in ascending order, -naturally). -

- -

-If, in addition to numbering heads, you also request that -subheads -and/or -paraheads -be numbered, the head number will be included in their numbers -(each number separated by a period [dot]). -

- -

-Should you wish to stop head numbering, invoke -.NUMBER_HEADS with any argument (OFF, QUIT, -END, X...). Head numbering will cease, and the head number -will not be included in the numbering of subheads and/or paraheads. -

- -

-See also -PREFIX_CHAPTER_NUMBER -if you'd like chapter numbers prepended to the head numbers. -

- -

6. Reset head numbering — RESET_HEAD_NUMBER

 - -

-Should you wish to reset the head number to "1", invoke -.RESET_HEAD_NUMBER with no argument. If, for some -reason, you want mom to use a head number that is not -the next in ascending order (i.e. the last head number + 1), invoke -.RESET_HEAD_NUMBER with the number you want, e.g. - -

-    .RESET_HEAD_NUMBER 6
-
- -Your next head will be numbered "6" and subsequent heads will -be numbered in ascending order from "6". -

- -

7. Vertical inline escapes inside heads

 - -

-If you need to adjust the -baseline -position of a head (e.g. the head falls at the top of a column and -you want its -ascenders -to line up with the ascenders of -running text -in other columns), you can embed a vertical motion -inline escape -(either -mom's -or -groff's -in the string(s) you pass to HEAD. -

- -

-For example, - -

-    .HEAD "\[ALD3]Text of head"
-        or
-    .HEAD "\[DOWN 3p]Text of head"
-
- -will lower the baseline of the head by three points. Note that -there's no need to reverse the sense of the inline escape. -

- -

-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: - -

-    .HEAD "\[ALD3]First line" "\[ALD3]Next line" 
-        or
-    .HEAD "\[DOWN 3p]First line" "\[DOWN 3p]Next line" 
-
-

- -
- - - -

Subheads

 - - - -

-Subheads should be used any place you want titles to introduce -sections of a document below heads. If you wish, mom -can number subheads for you. Subhead numbers can also be included -hierarchically in numbered -paraheads. -

- -

-By default, subheads are flush left. In -PRINTSTYLE TYPESET, -they are set bold, slightly larger than paragraph text. In -PRINTSTYLE TYPEWRITE, -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. -

- -

-If these defaults don't suit you, you can change them with the -subhead control macros. -

- - - -
- - - -

-Macro: SUBHEAD "<text of subhead>" [ "<2nd line>" [ "<3rd line>" ... ] ] -

- -

-The argument to SUBHEAD is the text of the subhead, -surrounded by double-quotes. If you need additional lines for a -subhead, simply surround each line with double-quotes. -

- -

-NOTE: If a subhead falls near the bottom of an output -page and mom is unable to fit the head plus at -least one line of text underneath it, she will set the subhead -at the top of the next page. -

- -
- -

Subhead control macros

 - -

-In addition to the usual family/font/size/quad control -macros, there are macros to manage subhead numbering. -

- -
    -
  1. Family/font/size/colour/quad
    2. -
  2. Numbering
    3. -
  3. Reset subhead numbering
    4. -
  4. Vertical inline escapes inside subheads
    5. -
- -

1. Family/font/size/quad

 - -

-See -Arguments to the control macros. -

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

2. Number subheads — NUMBER_SUBHEADS

 - -

-If you'd like your subheads numbered, simply invoke -.NUMBER_SUBHEADS with no argument. Mom -will number all subsequent subheads automatically (in ascending -order, naturally). -

- -

-If, in addition to numbering subheads, you also request that -heads -be numbered, the head number will be included in the subhead number -(separated by a period [dot]). -

- -

-Should you wish to stop subhead numbering, invoke -.NUMBER_SUBHEADS with any argument (OFF, QUIT, -END, X...). Subhead numbering will cease, and the subhead -number will not be included in the numbering of paraheads. -

- -

-See also -PREFIX_CHAPTER_NUMBER -if you'd like chapter numbers prepended to the subhead numbers. -

- -

3. Reset subhead numbering — RESET_SUBHEAD_NUMBER

 - -

-Should you wish to reset the subhead number to "1", invoke -.RESET_SUBHEAD_NUMBER with no argument. If, for some -reason, you want mom to use a subhead number that -is not the next in ascending order (i.e. the last subhead number + -1), invoke .RESET_SUBHEAD_NUMBER with the number you -want, e.g. - -

-    .RESET_SUBHEAD_NUMBER 4
-
- -Your next subhead will be numbered "4" and subsequent -subheads will be numbered in ascending order from "4". -

- -

Vertical inline escapes inside subheads

 - -

-See -Vertical inline escapes inside heads. -The information there applies equally to subheads. -

- -
- - - -

Paragraph heads

 - - - -

-Paragraph heads (paraheads) should be used any place you want titles -to introduce paragraphs below heads or subheads. If you wish, -mom can number paraheads for you. -

- -

-By default, paraheads are joined to the body of a paragraph, -slightly indented (provided the paragraph is not a -"first" paragraph as defined in -Indenting initial paragraphs) -and separated from the body of the paragraph by a small amount of -horizontal space. In -PRINTSTYLE TYPESET, -they are set bold italic, slightly larger than paragraph text. In -PRINTSTYLE TYPEWRITE, -they are underlined. -

- -

-If these defaults don't suit you, you can change them with the -parahead control macros. -

- -

-Tip: If you really need a heading level below -subhead (a sub-subhead) that isn't joined to the body of a -paragraph, you can trick PARAHEAD into giving you -one by creating a paragraph that contains only a parahead, like this: - -

-    .PP
-    .PARAHEAD "My Sub-Subhead"
-    .PP
-    <text>
-
-

- - - -
- - - -

-Macro: PARAHEAD "<text of parahead>" -

- -

-PARAHEAD must come AFTER -PP -or it will not work! -

- -

-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 -HEAD -and -SUBHEAD). -

- -
- -

Parahead control macros

 - -

-In addition to the family/font/size/colour/indent control macros, -there are macros to manage parahead numbering. -

- -
    -
  1. Family/font/size/color
    2. -
  2. Indent
    3. -
  3. Horizontal space
    4. -
  4. Numbering
    5. -
  5. Reset parahead numbering
    6. -
- -

-

1. Family/font/size/colour

-

- -

-See -Arguments to the control macros. -

- -
-.PARAHEAD_FAMILY default = prevailing document family; default is Times Roman
-.PARAHEAD_FONT   default = bold italic
-.PARAHEAD_SIZE   default = +.5 (point)
-.PARAHEAD_COLOR  default = black*
-
-*If you colourize paragraph text, paraheads will appear in the same
-colour as the text unless you explicitly tell mom to colour them
-otherwise by invoking .PARAHEAD_COLOR.  If you do want paraheads
-that are coloured the same as paragraph text, it's generally a good
-idea to invoke .PARAHEAD_COLOR anyway (with the same colour used
-for paragraph text), just to let mom know.
-
- -

2. Indent

 - -

-Unlike other control macros that end in -_INDENT, -the argument to the macro that controls indenting of paragraph heads -(PARAHEAD_INDENT) is NOT relative to the first-line -indent of normal paragraphs. In other words, it takes an absolute -value, and requires a -unit of measure. -For example, to set the paragraph head indent to 2-1/2 picas, you -do: - -

-    .PARAHEAD_INDENT 2.5P
-
-

- -

-Mom's default indent for paragraph heads is 1/2 -the first-line indent of normal paragraphs (both printstyles). -However, as stated above, if you choose to change the indent, you -must give an absolute value (unless you're a groff expert and want -to manipulate the number register \n[#PP_INDENT]u -arithmetically as the argument to PARAHEAD_INDENT -for an indent that's relative to PP_INDENT.) -

- -

-NOTE: Paragraph heads in "first -paragraphs", as defined in -Indenting initial paragraphs, -are not indented unless you turn -INDENT_FIRST_PARAS -on. -

- -

3. Horizontal space

 - -

-The default amount of horizontal space between a parahead and the -text that begins the body of a paragraph is 2/3 of an -em -for -PRINTSTYLE TYPESET) -and 1 -figure space -for -PRINTSTYLE TYPEWRITE). -

- -

-The default for TYPEWRITE is fixed, but if the -default for TYPESET doesn't suit you, you can -change it with the macro, PARAHEAD_SPACE. -

-

-PARAHEAD_SPACE takes just one argument: the amount -of space you want, with a -unit of measure -appended. Thus, if you want the horizontal space between a parahead -and the start of paragraph text to be 6 -points, -you'd do: - -

-    .PARAHEAD_SPACE 6p
-
-

- -

4. Number paraheads — NUMBER_PARAHEADS

 - -

-If you'd like your paraheads numbered, simply invoke -.NUMBER_PARAHEADS with no argument. Mom -will number all subsequent paraheads automatically (in ascending -order, naturally). -

- -

-If, in addition to numbering paraheads, you also request that -heads -and -subheads -be numbered, the head and/or subhead number will be included in the -parahead number (separated by a period [dot]). -

- -

-Should you wish to stop parahead numbering, invoke -.NUMBER_PARAHEADS with any argument (OFF, QUIT, -END, X...). Parahead numbering will cease. -

- -

-See also -PREFIX_CHAPTER_NUMBER -if you'd like chapter numbers prepended to the paragraph head -numbers. -

- -

5. Reset paragraph head numbering — RESET_PARAHEAD_NUMBER

 - -

-Should you wish to reset the parahead number to "1", invoke -.RESET_PARAHEAD_NUMBER with no argument. If, for some -reason, you want mom to use a parahead number that is not -the next in ascending order (i.e. the last parahead number + 1), invoke -.RESET_PARAHEAD_NUMBER with the number you want, e.g. - -

-    .RESET_PARAHEAD_NUMBER 7
-
-

- -

-Your next parahead will be numbered "7" and subsequent -paraheads will be numbered in ascending order from "7". -

- - - -
- - - -

-Macro: PREFIX_CHAPTER_NUMBER <none> | <chapter number as digit> | <anything> -

- -

-If you've requested numbering of heads, subheads and/or paragraph -heads (with -NUMBER_HEADS, -NUMBER_SUBHEADS -and/or -NUMBER_PARAHEADS) -and you'd like mom, in addition, to prefix -a chapter number to the numbering scheme, you can do so with -PREFIX_CHAPTER_NUMBERS. After you invoke -.PREFIX_CHAPTER_NUMBERS, mom will -prepend the current chapter number to all subsequent head elements -(main heads, subheads or paragraph heads) for which you have -requested numbering. Thus, assuming chapter number twelve (12), - -

-        1. FIRST MAIN HEAD
-        ------------------
-
-1.1. First Subhead Under Main Head
-
- -becomes - -
-        12.1. FIRST MAIN HEAD
-        ---------------------
-
-12.1.1. First Subhead Under Main Head
-
-

- -

-When you invoke .PREFIX_CHAPTER_NUMBERS without an -argument, mom checks to see whether the argument -you passed to -CHAPTER -is a digit. If it is, she immediately starts pre-pending the -current chapter number to numbered head elements. If it isn't -(say you've called your chapter "One" instead of -"1"), mom will abort with a request that -you pass PREFIX_CHAPTER_NUMBER a digit representing -the current chapter number. -

- -

-In collated documents, mom automatically increments -the digit used by PREFIX_CHAPTER_NUMBER by one -(current chapter digit + 1) every time you invoke -.COLLATE, -even if you've (temporarily) turned off the prefixing of chapter -numbers. Thus, even if you call your chapters "One", -"Two", "Three" instead of "1", -"2", "3", mom will Do -The Right Thing with respect to numbering head elements in -all collated chapters following the first invocation of -PREFIX_CHAPTER_NUMBER (assuming, of course, -that the collated chapters are in incrementing order; if -not, you must must put - -

-    .PREFIX_CHAPTER_NUMBER <chapter number>
-
- -somewhere after the invocation of COLLATE and -before the first numbered head element of each collated document). -

- -

-PREFIX_CHAPTER_NUMBER can be disabled by passing -it any argument other than a digit (e.g. OFF, QUIT, END, -X, etc), although, as noted above, mom -will keep, and — in the case of collated documents — -increment the chapter number, allowing you to turn prefixing of -chapter numbers to numbered head elements off and on according to -your needs or whims. -

- -

-NOTE: Because -PREFIX_CHAPTER_NUMBER takes an (optional) digit -representing the chapter number, it's use need not be restricted to -DOCTYPE CHAPTER. -You can use it with any document type. Furthermore, even if your -doctype isn't "CHAPTER", you can identify the document as -a chapter for the purposes of numbering head elements by -invoking the macro, -.CHAPTER, -with a -numeric argument -in your document setup. -

- -
- - - -

Author linebreaks (section breaks)

 - - - -

-By default, mom marks -author linebreaks -(also called "section breaks") with three centred asterisks. -You can change this behaviour with the linebreak character -control macro. -

- - - -
- - - -

-Macro: LINEBREAK -
- -Alias: SECTION -

- -

-LINEBREAK 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 -LINEBREAK_CHAR -macro. -

- -
- -

Linebreak character control macro

 - -

-Macro: LINEBREAK_CHAR [ <character> ] [ <iterations> [ <vertical adjustment> ] ] -
- -Alias: SECTION_CHAR -
- -*The third optional argument requires a -unit of measure. -

- -

-LINEBREAK_CHAR determines what mom -prints when LINEBREAK is invoked. It takes 3 -optional arguments: the character you want deposited at the line -break, the number of times you want the character repeated, and a -vertical adjustment factor. -

- -

-The first argument is any valid groff character (e.g. * -[an asterisk], \(dg [a dagger], \f(ZD\N'141\fP -[an arbitrary character from Zapf Dingbats], \l'4P' [a -4-pica long rule]). Mom sets the character centred -on the current line length. (See "man groff_char" for a -list of all valid groff characters.) -

- -

-The second argument is the number of times to repeat the character. -

- -

-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 -baseline -(such as asterisks). The argument must be preceded by a plus or -minus sign, and must include a unit of measure. -

- -

-If you enter LINEBREAK_CHAR with no arguments, -sections of text will be separated by two blank lines when you -invoke .LINEBREAK. -

- -

-Mom's default for LINEBREAK_CHAR is - -

-    .LINEBREAK_CHAR * 3 -3p
-
- -i.e. three asterisks, lowered 3 points from their normal vertical -position (for -PRINTSTYLE TYPESET; -the vertical adjustment is -2 points for -

-PRINTSTYLE TYPEWRITE). - -
- -

Linebreak colour control macro

 - -

-Macro: LINEBREAK_COLOR <color name> -

- -

-To change the colour of the linebreak character(s), simply invoke -.LINBREAK_COLOR with the name of a pre-defined (or -"initialized") colour. -

- -
- - - -

Quotes (line for line)

 - - - -

-Quotes -are always set in -nofill mode, -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 -Blockquotes -for how quotes, in the present sense, differ from longer -passages of cited text.) -

- -

-Since mom originally came into being to serve the -needs of creative writers (i.e. novelists, short story writers, etc. -— not to cast aspersions on the creativity of mathematicians -and programmers), she sets quotes in italics -(PRINTSTYLE TYPESET) -or underlined -(PRINTSTYLE TYPEWRITE), -indented from the left margin. Obviously, she's thinking -"quotes from poetry or song lyrics", but with the -quote control macros -you can change her defaults so QUOTE serves other -needs, e.g. entering verbatim snippets of programming code, command -line instructions, and so on. (See the -CODE -for a convenience macro to assist in including programming code -snippets in documents.) -

- - - -

-Besides indenting quotes, mom further sets them -off from -running text -with a small amount of vertical whitespace top and bottom. In -PRINTSTYLE TYPEWRITE, -this is always one full linespace. In -PRINTSTYLE TYPESET, -it's 1/2 of the prevailing -leading -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 -ALWAYS_FULLSPACE_QUOTES. -

- -

-NOTE: ALWAYS_FULLSPACE_QUOTES -applies to both -QUOTE -and -BLOCKQUOTE, -as does the control macro -QUOTE_INDENT. -

- -

-Version 1.3: mom's handling of the -vertical whitespace around quotes has changed slightly. In -versions prior to 1.3, it was not possible to alter the -leading -of quotes and blockquotes (which was the same as the document -leading), ensuring that the vertical whitespace remained consistent, -as described above. -

- -

-In 1.3 and later, it is possible to change the leading of quotes -and blockquote via the QUOTE_AUTOLEAD and -BLOCKQUOTE_AUTOLEAD macros. Now, if your quote -(or blockquote) leading differs from the document leading, -mom attempts to observe the same rules for vertical -whitespace outlined above; however, she will also insert a small, -flexible amount of extra whitespace around the quotes to make sure -the whitespace is equal, top and bottom. Since she does this on a -quote by quote basis, rather than by figuring out how much extra -whitespace is needed to adjust all 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 -running text, -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.) -

- - - -

-If you don't want the behaviour described above (i.e. you don't want -mom shimming [possibly irregularly linespaced] -quotes or blockquotes), issue the macro .NO_SHIM prior -to invoking .QUOTE or .BLOCKQUOTE. -If you've disabled shimming of quotes and blockquotes with -.NO_SHIM and you want mom to return to -her default behaviour in this matter, invoke -.NO_SHIM OFF (or QUIT, END, X, etc). -

- -

-If you don't provide mom with a -QUOTE_AUTOLEAD, quotes are leaded at the default -for normal running text, meaning that multiple quotes on the same -page are all spaced identically. -

- - - -
- - - -

-Macro: QUOTE toggle -

- -

-QUOTE is a toggle macro. To begin a section -of quoted text, invoke it with no argument, then type in your -quote. When you're finished, invoke .QUOTE with any -argument (e.g. OFF, END, X, Q...) to turn it off. Example: - -

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

- -
- -

Quote control macros

 - -
    -
  1. Family/font/size/leading/colour/indent
    2. -
  2. Spacing above and below (typeset only)
    3. -
  3. Underline quotes (typewrite only)
    4. -
  4. Manually break a footnoted quote that crosses pages/columns
    5. -
- -

1. Family/font/size/colour/indent

 - -

-See -Arguments to the control macros. -

- -
-.QUOTE_FAMILY   default = prevailing document family; default is Times Roman
-.QUOTE_FONT     default = italic; underlined in TYPEWRITE
-.QUOTE_SIZE     default = +0 (i.e. same size as paragraph text)
-.QUOTE_AUTOLEAD default = none; leading of quotes is the same as paragraphs
-.QUOTE_COLOR    default = black
-.QUOTE_INDENT   (see below)
-
- -
Quote indent
 - -

-Prior to version 1.4-b, mom allowed only the -passing of an integer to the macro, .QUOTE_INDENT. The -integer represented the amount by which to multiply the argument -passed to -PARA_INDENT -to arrive at an indent for quotes (and blockquotes). -

- -

-As of version 1.4-b, you can now append a -unit of measure -to the argument passed to .QUOTE_INDENT, thus -setting an absolute indent, relative to nothing. The old -behaviour is still respected, though; in other words, if you -pass .QUOTE_INDENT an integer with no unit of measure -appended, the integer represents the amount by which to multiply -.PARA_INDENT to arrive at an indent for quotes (and -blockquotes). -

- -

-Please note that if your PARA_INDENT is 0 -(i.e. no indenting of the first line of paragraphs), you -must set a QUOTE_INDENT -yourself, with a unit of measure appended to the -argument. Mom has no default for -QUOTE_INDENT if paragraph first lines are not being -indented. -

- -

-The default value for QUOTE_INDENT is 3 (for -PRINTSTYLE TYPESET) -and 2 (for PRINTSTYLE -PRINTSTYLE TYPEWRITE). -

- -

-NOTE: QUOTE_INDENT also sets the indent for -BLOCKQUOTES. -

- -

2. Spacing above and below — ALWAYS_FULLSPACE_QUOTES (typeset only)

 - -

-If you'd like mom always to put a full linespace -above and below quotes, invoke .ALWAYS_FULLSPACE_QUOTES -with no argument. If you wish to restore mom's -default behaviour regarding the spacing of quotes (see -above), -invoke the macro with any argument (OFF, QUIT, END, -X...) -

- -

-NOTE: This macro also sets mom's -spacing policy for -blockquotes. -

- -

3. Underlining — UNDERLINE_QUOTES (typewrite only)

 - -

-By default in -PRINTSTYLE TYPEWRITE, -mom underlines quotes. If you'd rather she didn't, -invoke .UNDERLINE_QUOTES with any argument (OFF, -QUIT, END, X...) to disable the feature. Invoke it without -an argument to restore mom's default underlining of -quotes. -

- -

-If you not only wish that mom not underline -quotes, but also that she set them in italic, you must follow each -instance of QUOTE with the typesetting macro -FT I. -Furthermore, since mom underlines all instances of -italics by default in PRINTSTYLE TYPEWRITE, you -must also make sure that ITALIC_MEANS_ITALIC is -enabled (see -PRINTSTYLE TYPEWRITE control macros). -

- -

4. Manually break a footnoted quote — BREAK_QUOTE

 - -

-NOTE: As of version 1.1.9, the macro -BREAK_QUOTE 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 BREAK_QUOTE while running -mom 1.1.9 or higher, please notify me -immediately. -

- -

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

- -

-BREAK_QUOTE may be used with both quotes and -blockquotes, and hence is aliased as BREAK_BLOCKQUOTE, -BREAK_CITATION and BREAK_CITE. -

- -
- - - -

Blockquotes (cited passages)

 - - - -

-BLOCKQUOTES are used to cite passages from another -author's work. So that they stand out well from -running text, -mom indents them from both the left and right margins -and sets them in a different point size -(PRINTSTYLE TYPESET -only). -Output lines -are -filled, -and, by default, -quadded -left. -

- -

-Besides indenting blockquotes, mom further -sets them off from running text with a small amount of vertical -whitespace top and bottom. (See -above -for a complete explanation of how this is managed, and how -to control it. Be sure to read the section Version -1.3.) -

- - - -
- - - -

-Macro: BLOCKQUOTE toggle -
- -Aliases: CITE, CITATION -

- -

-BLOCKQUOTE 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 .BLOCKQUOTE with any -argument (e.g. OFF, END, X, Q...) to turn it off. Example: - -

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

- -

-If the cited passage runs to more than one paragraph, you MUST -introduce each paragraph — including the first! — -with -PP. -

- -

-NOTE: The aliases CITE -and CITATION may be used in place of the -BLOCKQUOTE tag, as well as in any of the control -macros that begin with BLOCKQUOTE_ or end with -_BLOCKQUOTE. -

- -
- -

Blockquote control macros

 - -
    -
  1. Family/font/size/leading/colour/quad/indent
    2. -
  2. Spacing above and below (typeset only)
    3. -
  3. Manually break a footnoted blockquote that crosses pages/columns
    4. -
- -

1. Family/font/size/colour/quad/indent

 - -

-See -Arguments to the control macros. -

- -
-.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)
-
- -
Blockquote indent
 - -

-Prior to version 1.4-b, mom allowed only the -passing of an integer to the macro, .BLOCKQUOTE_INDENT. -The integer represented the amount by which to multiply the argument -passed to -PARA_INDENT -to arrive at an indent for blockquotes (and quotes). -

- -

-As of version 1.4-b, you can now append a -unit of measure -to the argument passed to .BLOCKQUOTE_INDENT, thus -setting an absolute indent, relative to nothing. The old -behaviour is still respected, though; in other words, if you pass -.BLOCKQUOTE_INDENT an integer with no unit of measure -appended, the integer represents the amount by which to multiply -.PARA_INDENT to arrive at an indent for blockquotes (and -quotes). -

- -

-The default value for .BLOCKQUOTE_INDENT is 3 (for -PRINTSTYLE TYPESET) -and 2 (for PRINTSTYLE -PRINTSTYLE TYPEWRITE). -

- -

-Please note that if your PARA_INDENT -is 0 (i.e. no indenting of the first line of -paragraphs), you must set a -BLOCKQUOTE_INDENT yourself, with a unit of measure -appended to the argument. Mom has no default for -BLOCKQUOTE_INDENT if paragraph first lines are not -being indented. -

- -

-NOTE: BLOCKQUOTE_INDENT also sets the indent for -QUOTES. -

- -

2. Spacing above and below — ALWAYS_FULLSPACE_QUOTES (typeset only)

 - -

-If you'd like mom always to put a -full linespace above and below blockquotes, invoke -.ALWAYS_FULLSPACE_QUOTES with no argument. If you wish -to restore mom's default behaviour regarding the -spacing of blockquotes (see -above), -invoke the macro with any argument (OFF, QUIT, END, -X...). -

- -

-NOTE: This macro also sets mom's -spacing policy for -quotes. -

- -
- - - -

Inserting code snippets into documents

 - -

-Macro: CODE [BR | BREAK | SPREAD] toggle -
- -Inline escape: \*[CODE] -

- -

-CODE is a convenience macro that facilitates -entering code snippets into documents. Its use is not restricted to -documents created using mom's document processing -macros; it can be used for "manually" typeset documents as -well. -

- -

-When you invoke .CODE without an argument, or use the -inline escape, -\*[CODE], -mom changes the font to Courier Roman (a -fixed-width font) -and turns -SMARTQUOTES -off. Additionally, if you invoke .CODE inside -QUOTE -while using -PRINTSTYLE TYPEWRITE -with the default underlining of quotes turned on, it disables -the underlining for the duration of CODE. -

- -

-Passing any argument other than BR, BREAK or -SPREAD to .CODE (e.g. OFF, QUIT, END, -X, etc.) turns CODE off and returns the -family, font, smartquotes and (if applicable) underlining of quotes -to their former state. If you've used the inline escape to -initiate a section of code, \*[CODE OFF] equally returns -things to their former state. -

- -

-Please note that .CODE does not cause a line -break when you're in a -fill mode -(i.e. -JUSTIFY -or -QUAD LEFT, CENTER, or RIGHT). -If you want CODE to deposit a break, -invoke .CODE with the argument BR (or -BREAK). If, in addition to having mom -break the line before .CODE, you want her to -force justify -the line as well, invoke .CODE with the argument, -SPREAD. -

- -

-Please also note that BR, BREAK and -SPREAD must NOT be used with the inline escape, -\*[CODE]; the assumption behind \*[CODE] is -that you're inserting a bit of code into a line, not creating a -distinct "code block". -

- -

Changing the family mom uses for CODE

- -

-If you'd prefer to have CODE automatically -load a fixed-width family other than Courier, invoke the macro, -.CODE_FAMILY with the name of the fixed-width family you -want. For example, assuming you have a hypothetical fixed-width -family called "Mono" whose groff name is -simply "M", - -

-    .CODE_FAMILY M
-
- -is how you'd tell mom to use Mono for -CODE, rather than her default, Courier. -(See -Adding PostScript fonts to groff -for information on how you might set up the hypothetical -fixed-width font called "Mono".) -

- -

-NOTE: If your code snippet includes the backslash -character, which is groff's escape character, you -will have to change the escape character temporarily to something -else with the macro, -ESC_CHAR. -Mom has no way of knowing what special characters -you're going to use in code snippets, therefore she cannot -automatically replace the escape character with something else. -

- -
- - - -

Nested lists

 - - - -

-Lists are points or items of interest or importance that are -separated from -running text -by enumerators. Some typical enumerators are -en-dashes, -bullets, -digits and letters. -

- -

-Setting lists with mom is easy. First, you -initialize a list with the LIST macro. Then, for -every item in the list, you invoke the macro, .ITEM, -followed by the text of the item. When a list is finished, -you exit the list with .LIST OFF (or -QUIT, END, BACK, -etc.) -

- -

-By default mom starts each list with the enumerator -flush with the left margin of running text that comes before it, -like this: - -

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

- -

-In other words, mom does not, by default, indent -entire lists. Indenting a list is controlled by the macro, -SHIFT_LIST. -(This is a design decision; there are too many instances where a -default indent is not desirable.) Equally, mom -does not add any extra space above or below lists. -

- -

-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 -LIST OFF (you may prefer to use -LIST BACK) takes you back to the -previous depth (or level) of list, with that list's enumerator and -indent intact. The final LIST OFF -exits lists completely and returns you to the left margin of running -text. -

- -

-Finally, lists can be used in documents created with either the -document processing macros or just the typesetting macros. -

- - - -
- - - -

-Macro: LIST -
- -Macro arguments: -
- -[ BULLET | DASH | DIGIT | ALPHA | alpha | ROMAN<n> | roman<n> | USER <string>] -
- -[ <separator> | <user-defined enumerator> ] [ <prefix> ] [ <off> ] -

- -

-Invoked by itself (i.e. with no argument), .LIST -initializes a list (with bullets as the default enumerator). -Afterwards, each block of input text preceded by -.ITEM, -on a line by itself, is treated as a list item. -

- -

-NOTE: Every time you invoke .LIST -to start a list (as opposed to -exiting one), -you must supply an enumerator (and optionally, a separator) for the -list, unless you want mom's default enumerator, -which is a bullet. Within nested lists, mom -stores the enumerator, separator and indent for any list you return -backwards to (i.e. with LIST OFF), -but does not store any information for lists you move -forward to. -

- -

The first argument — enumerator style

- -

-The optional arguments BULLET, DASH, -DIGIT (for Arabic numerals), ALPHA (for -uppercase letters), alpha (for lowercase letters), -ROMAN<n> (for uppercase roman numerals), -roman<n> (for lowercase roman numerals) tell -mom what kind of enumerator to use for a given list. -

- -

-The arguments, ROMAN<n> and -roman<n>, are special. You must append to -them a digit (arabic, e.g. "1" or "9" or "17") saying how many -items a particular roman-numeralled LIST is going -to have. Mom requires this information in order to -align roman numerals sensibly, and will abort — with a message -— if you don't provide it. -

- -

-A roman-numeralled list containing, say, five items, would be set -up like this: - -

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

- -

-The argument, USER, 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 =>, - -

-    .LIST USER =>
-    .ITEM
-    A list item
-
- -will produce - -
-    => A list item
-
-

- -

-Please note: if the argument to USER -contains spaces, you must enclose the argument in double quotes. -

- -

The second argument — separator style

- -

-If you choose DIGIT, ALPHA, alpha, -ROMAN<n>, or roman<n>, you may -enter the optional argument, separator, to say what kind -of separator you want after the enumerator. The separator can be -anything you like. The default for DIGIT is a period -(dot), like this: - -

-    1. A list item
-
-

- -

-The default separator for ALPHA, alpha, -ROMAN<n> and roman<n> is a right -parenthesis, like this: - -

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

- -

-If you'd prefer, say, digits with right-parenthesis separators -instead of the default period, you'd do - -

-    .LIST DIGIT )
-    .ITEM
-    A numbered list item
-
- -which would produce - -
-    1) A numbered list item
-
-

- -

-Please note: BULLET, DASH and -USER do not take a separator. -

- -

The third argument — prefix style

- -

-Additionally, you may give a prefix (i.e. a character -that comes before the enumerator) when your -enumerator style for a particular list is DIGIT, -ALPHA, alpha, ROMAN<n> -or roman<n>. In the arguments to -LIST, the prefix comes after the -separator, which may seem counter-intuitive, so please be careful. -

- -

-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 DIGIT list with the numbers enclosed in -parentheses, you'd enter - -

-    .LIST DIGIT ) (
-    .ITEM
-    The first item on the list.
-    .ITEM
-    The second item on the list.
-
- -which would produce - -
-    (1) The first item on the list.
-    (2) The second item on the list.
-
-

- -

-Please note: BULLET, DASH and -USER do not take a prefix. -

- - - -

Exiting lists — .LIST OFF/BACK or .QUIT_LISTS

- -

-Any single argument to LIST other than -BULLET, DASH, DIGIT, -ALPHA, alpha, ROMAN<n>, -roman<n> or USER (e.g. LIST -OFF or LIST BACK) takes you out -of the current list. -

- -

-If you are at the first list-level (or "list-depth"), -mom returns you to the left margin of running text. -Any indents that were in effect prior to setting the list are fully -restored. -

- -

-If you are in a nested list, mom moves you -back one list-level (i.e. does not take you out of the -list structure) and restores the enumerator, separator and indent -appropriate to that level. -

- -

-Each invocation of .LIST should be be matched by a -corresponding .LIST OFF in order to fully -exit lists. For example, - -

-    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.
-
- -is created like this: - -
-    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.
-
-

- -

-Alternatively, you may use the single-purpose macro, -.QUIT_LISTS, to get yourself out of a list structure. In -the example above, the two .LIST OFF lines -could be replaced with a single .QUIT_LISTS. -

- -
- - - -

-Macro: ITEM -

- -

-After you've initialized a list with -LIST, -precede each item you want in the list with .ITEM. -Mom takes care of everything else with respect to -setting the item appropriate to the list you're in. -

- -

-In document processing, it is valid to have list items that contain -multiple paragraphs. Simply issue a -PP -request for each paragraph following the first item. -I.e., don't do this: - -

-    .ITEM
-    .PP
-    Some text...
-    .PP
-    A second paragraph of text
-
- -but rather - -
-    .ITEM
-    Some text...
-    .PP
-    A second paragraph of text
-
-

- -
- -

List control macros

 - -
    -
  1. Indenting lists (SHIFT_LIST)
    2. -
  2. Resetting an initialized list's enumerator (RESET_LIST)
    3. -
  3. Padding digit enumerators (PAD_LIST_DIGITS)
    4. -
- -

1. Indenting lists — SHIFT_LIST

 - -

-If you want a list to be indented to the right of running text, or -indented to the right of a current list, use the macro -SHIFT_LIST immediately after -LIST. -SHIFT_LIST takes just one argument: the amount by -which you want the list shifted to the right. The argument requires -a -unit of measure, -

- -

-SHIFT_LIST applies only to the list you -just initialized with LIST. It does not carry -over from one invocation of LIST to the next. -However, the indent remains in effect when you return to a -list level in a nested list. -

- -

-For example, if you want a 2-level list, with each list indented to -the right by 18 -points, - -

-    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.
-
- -produces (approximately) - -
-    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.
-
-

- -

2. Resetting an initialized list's enumerator — RESET_LIST

 - -

-In nested lists, if your choice of list enumerator for a given -level of list is DIGIT, ALPHA, -alpha, ROMAN or -roman, you may sometimes want to reset the list's -enumerator when you return to that list. Consider the following: - -

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

- -

-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 .ITEM — with the macro, -.RESET_LIST. -

- -

-By default, with no argument, .RESET_LIST resets the -enumerator to 1, A, a, I or i depending on the style of enumerator. -You may, if you wish, pass .RESET_LIST a -numeric argument -representing the starting enumerator for the reset (if different -from "1"), although I can't at present think of a use for this -feature. -

- -

3. Padding digit enumerators (PAD_LIST_DIGITS)

 - -
Arabic digits
- -

-When your choice of enumerators is DIGIT AND the -number of items in the list exceeds nine (9), you have to make a -design decision: should mom leave room for the -extra numeral in two-numeral digits to the right or the left of the -single-numeral digits? -

- -

-If you want the extra space to the right, invoke the macro, -.PAD_LIST_DIGITS (with no argument), after -.LIST and before .ITEM. This will produce -something like - -

-    8.  List item
-    9.  List item
-    10. List item
-
-

- -

-If you want the extra space to the left, invoke -.PAD_LIST_DIGITS with the single argument, -LEFT, which will produce - -

-     8. List item
-     9. List item
-    10. List item
-
-

- -

-Of course, if the number of items in the list is less than ten -(10), there's no need for PAD_LIST_DIGITS. -

- -
Roman numerals
- -

-By default, mom sets roman numerals in lists -flush left. The <n> argument appended to -ROMAN<n> or roman<n> -allows her to calculate how much space to put after each numeral in -order to ensure that the text of items lines up properly. -

- -

-If you'd like the roman numerals to line up flush right (i.e. -be padded "left"), simply invoke -.PAD_LIST_DIGITS LEFT -after -.LIST ROMAN<n> -or -.LIST roman<n> -and before .ITEM. -

- -
- - - -

Line numbering

 - - - -

-When you turn line-numbering on, mom, by default - - -

-

- -

-Line numbering may be enabled and disabled for -QUOTE -and/or -BLOCKQUOTE -in one of three styles. See -Line numbering control macros for quotes and blockquotes. -

- -

-The first time you invoke -.NUMBER_LINES -you must, at a minimum, tell it what line number you want the -next -output line -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 -running text. -

- -

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

- - - -
- - - -

-Macro: NUMBER_LINES <start number> [ <which lines to number> [ <gutter> ] ] -
- -Macro: NUMBER_LINES <anything> | RESUME -

- -

-NUMBER_LINES does what it says: prints line -numbers, to the left of -output lines -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 -FOOTNOTE_MARKER_STYLE LINE -for instructions on line-numbered footnotes, and -ENDNOTE_MARKER_STYLE -for instructions on line-numbered endnotes.) -

- -

-Every time you invoke .NUMBER_LINES, unless you are -using the argument OFF (or QUIT, -END, X, etc.) or RESUME -you must, at a minimum, pass it one argument, namely the number -(digit) you want the next -output line -to have. For example, - -

-    .NUMBER_LINES 3
-
- -will prepend the number, 3, to the next output line. -

- -

-Normally, of course, you will number lines of text starting at 1. -All you have to do in that case is ensure that - -

-    .NUMBER_LINES 1
-
- -precedes your first line of input text, which will also be the -first line of output text. -

- -

-You can alter mom's default line numbering -behaviour (see -above) -with the optional arguments <which lines to number> -and <gutter>. -

- -

-<which lines to number> instructs -NUMBER_LINES 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 - -

-    .NUMBER_LINES 1 5
-
- -GOTCHA! The argument to <which lines to -number> only numbers those lines that are multiples of -the argument. Hence, in the above example, line number "1" will -not be numbered, since "1" is not a multiple of "5". -

- -

-If you wanted line number "1" to be numbered, you'd have to invoke -.NUMBER_LINES 1 1 before the first output line, then -study your output copy and determine where best to insert -the following in your input copy: - -

-    .NUMBER_LINES \n(ln 5
-
- -(The escape, \n(ln, ensures that -NUMBER_LINES automatically supplies the correct -value for the first argument, <start number>.) -

- -

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

- -

-The optional argument, <gutter>, tells -mom how much space to put between the line numbers -and the running text. -

- -

-Note: when giving a value for -<gutter>, you cannot skip the <which lines -to number> argument. Either fill in the desired value, or -use two double-quotes ( "" ) to have mom -use the value formerly in effect. -

- -

-<gutter> does not require (or even accept) a -unit of measure. -The argument you pass to it is the number of -figure spaces -you want between line numbers and running text. -Mom's default gutter is two figure spaces. If -you'd like a wider gutter, say, four figures spaces, you'd do - -

-    .NUMBER_LINES 1 1 4
-                    |
-                    +-- Notice you *must* supply a value
-                        for the 2nd argument in order to supply
-                        a value for the 3rd.
-
-

- -

-After you've set up line-numbering, NUMBER_LINES -can be used to control line numbering. -

- -
- - - -

Line-numbering control

- -

-NUMBER_LINES OFF (or END, -QUIT, X, etc.) turns line-numbering off. -

- -

-Sometimes, you merely want to suspend line-numbering. In that -case, turn line numbering off with -.NUMBER_LINES OFF. Later, when you want -it to resume, enter - -

-    .NUMBER_LINES RESUME
-
- -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 .NUMBER_LINES with whatever -arguments are needed for the desired result. -

- -

Extra Notes:

- -
    -
  1. In document processing, you may invoke .NUMBER_LINES - either before or after .START. - Mom doesn't care. -
    2. -
  2. If you're collating documents with - COLLATE, - you should re-invoke, at a minimum, - .NUMBER_LINES 1 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). -
    3. -
  3. Occasionally, you may want to change the current gutter - between line numbers and running text without knowing - what the next output line number should be. Since - NUMBER_LINES requires this number - as its first argument, in such instances, pass - NUMBER_LINES as its first argument the - escape \n(ln. -

    - - 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), -

    - -     .NUMBER_LINES \n(ln 5 4 -

    - would do the trick. -
    4. -
  4. 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. -
    5. -
  5. Mom (groff, actually), only numbers lines - to the left of text. For aesthetic reason, - therefore, the use of line numbering when setting a document - in columns is discouraged. However, should you wish to - number lines when setting in columns, make sure the - gutter(s) - between columns is wide enough to leave room for the - numbers. -
    6. -
- -
- -

Line numbering control macros

 - -

-See -Arguments to the control macros. -

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

Line numbering control macros for QUOTE and BLOCKQUOTE

 - -
    -
  1. NUMBER_QUOTE_LINES
    2. -
  2. NUMBER_BLOCKQUOTE_LINES
    3. -
  3. Setting up line numbering in quotes and blockquotes on a case by case basis
    4. -
- -

1. NUMBER_QUOTE_LINES

 - -

-If you'd like mom to number lines of output text -in a -QUOTE -as part of the same order and sequence as paragraph text, simply -invoke .NUMBER_QUOTE_LINES by itself. -

- -

-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 <gutter> argument. -

- -

-If you'd like to change the gutter for quotes line-numbered in -this way, invoke .NUMBER_QUOTE_LINES with a digit -representing the number of -figure spaces -you'd like between the line numbers and the quoted text, like this: - -

-    .NUMBER_QUOTE_LINES 1
-
-

- -

-With the above, line numbers in quotes (and only quotes) will have -a gutter of 1 figure space. -

- -

-If you are using "line numbering style" for footnotes -(.FOOTNOTE_MARKER_STYLE LINE), -you may not wish to have quotes visibly line-numbered, but -still want to embed footnotes inside quotes. In order to do that, -mom allows you to say .NUMBER_QUOTE_LINES -SILENT. -

- -

-When you invoke .NUMBER_QUOTE_LINES SILENT, -mom continues to increment line numbers while -quotes are being output, but they won't appear in the output copy. -(Compare this with mom's default behaviour of -suspending 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. -

- -

-Once having turned NUMBER_QUOTE_LINES on, you -may disable it with -.NUMBER_QUOTE_LINES OFF -(or QUIT, END, X, -etc). -

- -

2. NUMBER_BLOCKQUOTE_LINES

 - -

-If you'd like mom to number lines of output text -in a -BLOCKQUOTE -as part of the same order and sequence as paragraph text, simply -invoke .NUMBER_BLOCKQUOTE_LINES by itself. -

- -

-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 -<gutter> argument. -

- -

-If you'd like to change the gutter for blockquotes line-numbered in -this way, invoke .NUMBER_BLOCKQUOTE_LINES with a digit -representing the number of -figure spaces -you'd like between the line numbers and the blockquoted text, like -this: - -

-    .NUMBER_BLOCKQUOTE_LINES 1
-
- -With the above, line numbers in blockquotes (and only blockquotes) -will have a gutter of 1 figure space. -

- -

-If you are using "line numbering style" for footnotes -(FOOTNOTE_MARKER_STYLE LINE), -you may not wish to have blockquotes visibly line-numbered, -but still want to embed footnotes inside blockquotes. In -order to do that, mom allows you to say -.NUMBER_BLOCKQUOTE_LINES SILENT. -

- -

-When you invoke -.NUMBER_BLOCKQUOTE_LINES SILENT, -mom continues to increment line numbers while -blockquotes are being output, but they won't appear in the output -copy. (Compare this with mom's default behaviour -of suspending 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. -

- -

-Once having turned NUMBER_BLOCKQUOTE_LINES on, -you may disable it with .NUMBER_BLOCKQUOTE_LINES -OFF (or QUIT, END, -X, etc). -

- -

3. Setting up line numbering in quotes and blockquotes on a case by case basis

 - -

-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 -QUOTE -macro to insert lines of programming code into a document. -

- -

-To enable line numbering within quotes or blockquotes on a case by -case basis, simply invoke .NUMBER_LINES, with the -arguments you need, immediately after entering .QUOTE -or .BLOCKQUOTE. (NUMBER_QUOTE_LINES -and/or NUMBER_BLOCKQUOTE_LINES should be turned -off if you're doing this.) The quote or blockquote will then be -line-numbered according to your specifications: the starting line -number of the quote or blockquote will be the one you give as a -first argument to NUMBER_LINES; which lines to -number will be the value you pass to <which lines to -number> (defaults to "1"); line numbers will hang -to the left of the quote or blockquote, separated from the quote or -blockquote by <gutter> (defaults to "2"). -

- -

-As soon as QUOTE or BLOCKQUOTE -is turned off, line numbering ceases, not only with respect to -subsequent paragraph text (if they are not being line-numbered), -but also for any subsequent invocation of .QUOTE or -.BLOCKQUOTE. In other words, you must re-enable -quote or blockquote line-numbering inside every instance of -QUOTE or BLOCKQUOTE when -line-numbering either of them on a case by case basis. -

- -
- - - -

Footnotes

 - - - -

-For something so complex behind the scenes, footnotes are easy to use. -You just type, for example - - - -

-    ...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.
-
- -and be done with it. -

- -

-(Note the obligatory use of the \c -inline escape. -It is required when your -FOOTNOTE_MARKER_STYLE -is either STAR [star/dagger footnotes] or -NUMBER [superscript numbers]; it is NOT to be used -when the FOOTNOTE_MARKER_STYLE is -LINE, or when footnote markers have been disabled -with -.FOOTNOTE_MARKERS -OFF.) -

- -

-***Version 1.3-d change*** -

- -

-As of version 1.3-d, the manner of entering the line after -.FOOTNOTE OFF has changed to accommodate -users' differing wishes with respect to the order of punctuation and -footnote markers. Please see -Footnote markers and punctuation in the running text -for more information. -

- -

-***End of version 1.3-d change*** -

- -

-After you invoke .FOOTNOTE, mom -takes care of everything: putting footnote markers in the body of -the document, keeping track of how many footnotes are on the page, -identifying the footnotes themselves appropriately, balancing them -properly with the bottom margin, deferring footnotes that don't fit -on the page... Even if you're using -COLUMNS, -mom knows what to do, and Does The Right Thing. -

- -

-Footnotes can be sly little beasts, though. If you're writing a -document that's footnote-heavy, you might want to read the following. -

- -

Footnote behaviour

 - -

-By default, mom marks footnotes with alternating -stars (asterisks), daggers, and double-daggers. The first footnote -gets a star, the second a dagger, the third a double-dagger, the -fourth two stars, the fifth two daggers, etc. If you prefer -numbered footnotes, rest assured mom is happy to -oblige. -

- -

-A small amount of vertical whitespace and a short horizontal rule -separate footnotes from the document body. The amount of whitespace -varies slightly from page to page depending on the number of lines -in the footnotes. Mom tries for a nice balance -between too little whitespace and too much, but when push comes to -shove, she'll usually opt for ample over cramped. The last lines of -footnotes are always flush with the document's bottom margin. -

- - - -

-If mom sees that a portion of a footnote cannot -be fit on its page, she carries that portion over to the next -page. If an entire footnote can't be fit on its page (i.e. -FOOTNOTE has been called too close to the bottom), -she defers the footnote to the next page, but sets it with the -appropriate marker from the previous page. -

- -

-When footnotes occur within cited text, for example a -QUOTE -or a -BLOCKQUOTE, -mom will usually opt for deferring the footnote -over to the next page if it allows her to complete the cited text -on one page. -

- -

-In the unfortunate happenstance that a deferred footnote is the -only footnote on its page (i.e. it's marked in the document body with -a star) and the page it's deferred to has its own footnotes, -mom separates the deferred footnote from the page's -proper footnote(s) with a blank line. This avoids the confusion that -might result from readers seeing two footnote entries on the same page -identified by a single star (or the number 1 if you've requested -numbered footnotes that begin at 1 on every page). The blank line -makes it clear that the first footnote entry belongs to the previous -page. -

- -

-In the circumstance where a deferred footnote is not the only one -on its page, and is consequently marked by something other than a -single star, there's no confusion and mom doesn't -bother with the blank line. (By convention, the first footnote on -a page is always marked with a single star, so if readers see, say, -a dagger or double-dagger marking the first footnote entry, they'll -know the entry belongs to the previous page). -

- -

-Very exceptionally, two footnotes may have to be deferred (e.g. one -occurs on the second to last line of a page, and another on the last -line). In such a circumstance, mom does not add -a blank after the second deferred footnote. If you'd like a blank -line separating both deferred footnotes from any footnotes proper to -the page the deferred ones were moved to, add the space manually by -putting a -.SPACE -command at the end of the footnote text, before .FOOTNOTE -OFF (or X, QUIT, EXIT, etc...). -

- -

-Obviously, deferred footnotes aren't an issue if you request -numbered footnotes that increase incrementally throughout the whole -document — yet another convenience mom has -thought of. -

- -

-While mom's handling of footnotes is sophisticated, -and tries to take nearly every imaginable situation under which they -might occur into account, some situations are simply impossible from -a typographic standpoint. For example, if you have a -HEAD -near the bottom of the page AND that page has some footnotes on it, -mom may simply not have room to set any text under -the head (normally, she insists on having room for at least one line -of text beneath a head). In such an instance, mom -will either set the head, with nothing under it but footnotes, or -transfer the head to the next page. Either way, you'll have a -gaping hole at the bottom of the page. It's a sort of typographic -Catch-22, and can only be resolved by you, the writer or formatter -of the document, adjusting the type on the offending page so as to -circumvent the problem. -

- -

-NOTE: Exceptionally, you may encounter problems -with footnotes inside quotes and blockquotes that cross a page or -column. See -BREAK_QUOTE -for a solution. -

- -

Footnote markers and punctuation in the running text

 - -

-As of version 1.3-d, the manner of entering the line after -.FOOTNOTE OFF has changed. -

- -

"Fill" modes — JUSTIFY, or QUAD LEFT | CENTER | RIGHT

 - -

-In fill modes, the correct way to enter the line after -.FOOTNOTE OFF is to input it as if it's -literally a continuation of the input line you were entering before -you invoked .FOOTNOTE. Therefore, if necessary, the -input line may have to begin with space(s) or a punctuation mark, as -in the two following examples. - -

-       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)
-
-

- -

-Example 1 produces, on output - -

-    A line of text,* broken up with a comma.
-
-

- -

-Example 2 produces - -

-    A line of text*, broken up with a comma.
-
-

- -

-Care must be taken, though, if the punctuation mark that begins the -line after FOOTNOTE OFF is a period -(dot). You must begin such lines with -\&., like this: - -

-    end of a sentence\c
-    .FOOTNOTE
-    A footnote line.
-    .FOOTNOTE OFF
-    \&.  A new sentence...
-
-

- -

-If you omit the \&., the line will vanish! -

- -

-NOTE: The document element tags, -EPIGRAPH -and -BLOCKQUOTE, -imply a "fill" mode, therefore these instructions also apply when -you insert a footnote into epigraphs or blockquotes. -

- -

"No-fill" modes — LEFT, CENTER, RIGHT

 - -

-In no-fill modes, you must decide a) whether text on the -input line after .FOOTNOTE OFF is -to be joined to the output line before .FOOTNOTE -was invoked, or b) whether you want the output text to -begin on a new line. -

- -

-In the first instance, simply follow the instructions, -above, -for fill modes. -

- -

-In the second instance, you must explicitly tell -mom that you want input text after -FOOTNOTE OFF to begin on a new output -line. This is accomplished by passing .FOOTNOTE -OFF (or QUIT, END, X, etc) an -additional argument: BREAK or BR. -

- -

-Study the two examples below to understand the difference. - -

-    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.
-
- -produces, on output - -
-    A line of text* that carries on after the footnote.
-
- -whereas - -
-    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.
-
- -produces the following on output: - -
-    A line of text*
-    that doesn't carry on after the footnote.
-
-

- -

-The distinction becomes particularly important if you like to see -punctuation marks come after footnote markers. In no-fill -modes, that's accomplished like this: - -

-    .LEFT
-    A line of text\c
-    .FOOTNOTE
-    A footnote line
-    .FOOTNOTE OFF
-    ,
-    broken up with a comma.
-
-

- -

-The output of the above looks like this: - -

-    A line of text*,
-    broken up with a comma.
-
-

- -

-NOTE: The document element tag, -QUOTE, -implies a "no-fill" mode, therefore these -instructions also apply when you insert footnotes into quotes. -

- - - -
- - - -

-Tag: FOOTNOTE <toggle> [ BREAK | BR ] | INDENT LEFT | RIGHT | BOTH <indent value> -
- -*See HYPER-IMPORTANT NOTE!!! -
- -<indent value> requires a -unit of measure -

- -

-FOOTNOTE is a toggle macro, therefore invoking it -on a line by itself allows you to enter a footnote in the body of a -document. Invoking it with any argument other than INDENT -(i.e. OFF, QUIT, END, X...) tells mom -you're finished. -

- -

-Footnotes are the only element of -running text -that are not affected by the typesetting -indent macros. -In the unlikely event that you want a page's footnotes to line -up with a running indent, invoke .FOOTNOTE with -the INDENT argument and pass it an indent direction and -indent value. L, R, and B may be used in place -of LEFT, RIGHT, and BOTH. FOOTNOTE -must be invoked with .INDENT for every footnote you want -indented; mom does not save any footnote indent -information from invocation to invocation. -

- -

-NOTE: If a footnote runs to more than one -paragraph(!), DO NOT begin the footnote with -the -PP -tag. Use .PP only to introduce subsequent paragraphs. -

- -

-HYPER-IMPORTANT NOTE: -The final word on the -input line -that comes immediately before FOOTNOTE MUST terminate -with a -\c -inline escape if your -FOOTNOTE_MARKER_STYLE -is either STAR or NUMBER. -See the -footnote example -above. -

- -

-Additionally, in -fill -modes -(JUSTIFY -or -QUAD), -the line after a .FOOTNOTE OFF -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 -here). -

- -

-In -no-fill -modes, the optional argument BREAK or -BR may be used after the OFF (or -QUIT, END, X, etc.) argument to instruct -mom NOT to join the next input line to the previous -output. See -here -for a more complete explanation, with examples. -

- -

-Do NOT use the \c inline escape if your -FOOTNOTE_MARKER_STYLE is LINE, or -if you have disabled footnote markers with -.FOOTNOTE_MARKERS OFF. -In these instances, the line after -FOOTNOTE OFF should be entered normally. -

- -

Footnote control macros

 - -
    -
  1. Family/font/size/colour/lead/quad
    2. -
  2. Footnote markers — on or off
    3. -
  3. Footnote marker style — star+dagger, numbered or by line number
    4. - -
  4. Reset footnote number — set footnote marker number to 1
    5. -
  5. Inter-footnote spacing
    6. -
  6. Footnote rule — on or off
    7. -
  7. Footnote rule length — length of footnote separator rule
    8. -
  8. Footnote rule weight — weight of footnote separator rule
    9. -
  9. Adjust vertical position of footnote separator rule
    10. -
- -

1. Family/font/size/colour/lead/quad

 - -

-See -Arguments to the control macros. -

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

2. Footnote markers — FOOTNOTE_MARKERS

 - -

-If you don't want footnote markers, in either the body of -the document or beside footnote entries themselves, toggle -them off with .FOOTNOTE_MARKERS OFF (or -END, QUIT, X...). This means, of course, that -you'll have to roll your own. If you want them back on, invoke -.FOOTNOTE_MARKERS with no argument. Footnote markers are -on by default. -

- -

-If FOOTNOTE_MARKERS are disabled, do NOT use -the \c inline escape to terminate the line before -.FOOTNOTE. -

- -

3. Footnote marker style — FOOTNOTE_MARKER_STYLE

 - -

-Mom gives you two choices of footnote marker style: -star+dagger (see -footnote behaviour -above), or numbered. -

- -

-.FOOTNOTE_MARKER_STYLE STAR gives you star+dagger (the -default). There is a limit of 10 footnotes per page with this -style. -

- -

-.FOOTNOTE_MARKER_STYLE NUMBER gives you superscript -numbers, both in the document body and in the footnote entries -themselves. By default, footnote numbers increase incrementally -(prev. footnote number + 1) throughout the whole document. You can -ask mom to start each page's footnote numbers at 1 -with .RESET_FOOTNOTE_NUMBER -(see below.) -

- - - -

-.FOOTNOTE_MARKER_STYLE LINE lets you have footnotes which -are identified by line number, rather than by a marker in the text. -(Note that -NUMBER_LINES -must be enabled in order to use this marker style.) -

- -

-With FOOTNOTE_MARKER_STYLE LINE, -mom will identify footnotes either by single line -numbers, or line ranges. If what you want is a single line number, -you need only invoke .FOOTNOTE, without terminating -the text line before it with \c, at the appropriate -place in running text. -

- -

-If you want a range of line numbers (e.g. [5-11] ), -insert, directly into the first line of the range you want, the -inline escape, -\*[FN-MARK]. For the terminating line number of -the range, you need only invoke .FOOTNOTE, (again, -without attaching \c to the text line before it). -Mom is smart enough to figure out that where -.FOOTNOTE was invoked represents the terminating -line number. Range-numbered footnotes are always output on the -page where .FOOTNOTE was invoked, not the page where -\*[FN-MARK] appears (subject, of course, to the rules for -footnotes that fall too close to the bottom of a page, as outlined -here). -

- - - -

-Mom, by default, puts footnote line numbers inside -square brackets. The style of the brackets may be changed with -the macro, FOOTNOTE_LINENUMBER_BRACKETS, which -takes one of three possible arguments: PARENS ("round" -brackets), SQUARE (the default) or BRACES -(curly braces). If you prefer a shortform, the arguments, -(, [ or { may be used instead. -

- - - -

-If you don't want the numbers enclosed in brackets, you may tell -mom to use a "separator" instead. A common -separator would be the colon, but it can be anything you like. The -macro to do this is FOOTNOTE_LINENUMBER_SEPARATOR, -which takes, as its single argument, the separator you want. For -safety and consistency's sake, ALWAYS enclose the argument in -double-quotes. -

- -

-The separator can be composed of any valid groff character, or any -combination of characters. A word of caution: when -using a separator, mom doesn't insert a space -after the separator. Hence, if you want the space (you probably -do), you must make the space part of the argument you pass to -FOOTNOTE_LINENUMBER_SEPARATOR. For example, -to get a colon separator with a space after it, you'd do - -

-    .FOOTNOTE_LINENUMBER_SEPARATOR ": "
-
-

- -
RUN-ON FOOTNOTES
 - -

-Finally, if your footnote marker style is LINE, you -may instruct mom to do "run-on style" footnotes. -Run-on footnotes do not treat footnotes as discrete entities, i.e. -on a line by themselves. Rather, each footnote is separated from -the footnote before it by a space, so that the footnotes on any -given page form a continuous block, like lines in a paragraph. -The macro to get mom to run footnotes on is -.FOOTNOTES_RUN_ON. Invoked by itself, it turns the -feature on. Invoked with any other argument (OFF, -NO, etc.), it turns the feature off. It is -generally NOT a good idea to turn the feature on and off during the -course of a single document. If you do, mom will -issue a warning if there's going to be a problem. However, it is -always perfectly safe to enable/disable the feature after -COLLATE. -

- -

-The usual reason for wanting run-on footnotes is that you're -using them to hold many, short references. (See -here -for instructions on using the groff program, -refer, to set up references.) -

- -

4. Reset footnote number — RESET_FOOTNOTE_NUMBER

 - -

-.RESET_FOOTNOTE_NUMBER, by itself, resets -footnote numbering so that the next footnote you enter is -numbered 1. -

- -

-.RESET_FOOTNOTE_NUMBER PAGE tells -mom to start every page's footnote numbering at 1. -

- -

5. Inter-footnote spacing — FOOTNOTE_SPACE

 - -

-If you'd like a little extra space between footnotes, you can have -mom put it in for you by invoking -.FOOTNOTE_SPACE with an argument representing the -amount of extra space you'd like. The argument to -FOOTNOTE_SPACE requires a -unit of measure. -

- -

-In the following example, footnotes will be separated from each -other by 3 -points. - -

-    .FOOTNOTE_SPACE 3p
-
-

- -

6. Footnote rule — FOOTNOTE_RULE

 - -

-If you don't want a footnote separator rule, toggle it off with -.FOOTNOTE_RULE OFF (or END, -QUIT, X...). Toggle it back on by invoking -.FOOTNOTE_RULE with no argument. The default is to print -the rule. -

- -

7. Footnote rule length — FOOTNOTE_RULE_LENGTH

 - -

-If you want to change the length of the footnote separator rule, -invoke .FOOTNOTE_RULE_LENGTH with a length, like -this, - -

-    .FOOTNOTE_RULE_LENGTH 1i
-
- -which sets the length to 1 inch. Note that a -unit of measure -is required. The default is 4 -picas -for both -PRINTSTYLES. -

- -

8. Footnote rule weight — FOOTNOTE_RULE_WEIGHT

 - -

-If you want to change the weight ("thickness") of the -footnote separator rule, invoke .FOOTNOTE_RULE_WEIGHT -with the desired weight. The weight is measured in -points; -however, do NOT append the -unit of measure, -p, to the argument. -

- -

-Mom's default footnote rule weight is 1/2 point. -If you'd like a 1-point rule instead, -

-    .FOOTNOTE_RULE_WEIGHT 1
-
- -is how you'd get it. -

- -

9. Adjust vertical position of footnote separator rule — FOOTNOTE_RULE_ADJ

 - -

-The footnote separator rule is a rule whose bottom edge falls -on -the -baseline -(at the footnote -leading) -one line above the first line of a page's footnotes. By default, -mom raises the rule 3 -points -from the baseline so that the separator and the footnotes don't -look jammed together. If you'd prefer a different vertical -adjustment, invoke .FOOTNOTE_RULE_ADJ with the -amount you'd like. For example - -

-    .FOOTNOTE_RULE_ADJ 4.25p
-
- -raises the rule by 4-1/4 points. Note that you can only raise -the rule, not lower it. A -unit of measure -is required. -

- -

-Tip: If your document -leading -is 2 -points -or less (e.g your -point size -is 10 and your linespacing is 10, 11, or 12), lowering -mom's default footnote rule adjustment will -almost certainly give you nicer looking results than leaving -the adjustment at the default. Furthermore, you can invoke -.FOOTNOTE_RULE_ADJ 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. -

- -
- - - -

Endnotes

 - - - -

-Embedding endnotes into mom documents is accomplished -the same way as embedding -footnotes. The example below is -identical to the one shown in the -introduction to footnotes, -except that .FOOTNOTE has been replaced with -.ENDNOTE. - - -

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

- -

-As with footnotes, note the obligatory use of the \c -inline escape -when your -ENDNOTE_MARKER_STYLE -is NUMBER (which marks endnotes references in -running text -with superscript numbers). When the marker style is -LINE, you must not use the \c -escape. -

- -

-***Version 1.3-d change*** -

- -

-As of version 1.3-d, the manner of entering the line after -.ENDNOTE OFF has changed to accommodate -users' differing wishes with respect to the order of punctuation and -endnote markers. Mom handles endnotes and footnotes -identically in this regard, so please read the footnote section, -Footnote markers and punctuation in the running text, -for an explanation. -

- -

-***End version 1.3-d change*** -

- -

-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): -

- -
    -
  1. When your ENDNOTE_MARKER_STYLE is - NUMBER, endnotes are always numbered - incrementally, starting at "1". -
    2. -
  2. Endnotes MUST be output explicitly; mom does - not output them for you. In - collated - 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. -
    3. -
- -

-Within endnotes, you may use the document element tags -PP, -QUOTE -and -BLOCKQUOTE. -This provides the flexibility to create endnotes that run to several -paragraphs, as well as to embed cited text within endnotes. -

- -

-Should you wish to change the appearance of quotes or blockquotes -that appear within endnotes, you may do so with the -quote control macros -or -blockquote control macros. -HOWEVER... you must make the changes within each endnote, -prior to invoking .QUOTE or .BLOCKQUOTE, -and undo them prior to terminating the endnote (i.e. before -.ENDNOTE OFF), otherwise the changes will -affect subsequent quotes and blockquotes that appear in the document -body as well. -

- -

Endnote behaviour

 - -

-When you output endnotes (with -ENDNOTES), -mom finishes processing the last page of your document, -then breaks to a new page for printing the endnotes. If the document -type is -CHAPTER, -the centre part of the -header -(or footer), which, by default, contains a chapter number or title, -is removed. -

- -

-By default, mom 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. -

- -

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

- -

-Of course, all the defaults, as well as the overall style of the -endnotes page, can be changed with the -endnote control macros. -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. -

- -

A Note on Endnote Spacing

 - -

-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 -PARA_SPACE, -where mom allows unequal bottom alignment of pages. -Should you wish to correct this, by adding or subtracting small amounts -of space between endnotes that appear together on an endnotes page, make -the adjustment (with -ALD, -RLD -or -SPACE) -at the end of each endnote (i.e. just before invoking -.ENDNOTE OFF) -rather than at the top. -

- -

Endnotes and columnar documents

 - -

-Formerly (pre 1.1.6), there was no way to set a document in columns -(see -COLUMNS) -and then turn off column mode for endnotes. As of version 1.1.6, -you may now do so. See -ENDNOTES_NO_COLUMNS. -

- - - -
- - - -

-Macro: ENDNOTE <toggle> [ BREAK | BR ] -
- -*See HYPER-IMPORTANT NOTE!!! -

- -

-ENDNOTE is a toggle macro, therefore invoking it -on a line by itself allows you to enter an endnote in the body of a -document. Invoking it with any other argument (i.e. OFF, -QUIT, END, X...) tells mom that you've -finished the endnote. -

- -

-NOTE: If an endnote runs to more than one -paragraph, DO NOT begin the endnote with the -PP -tag. Use PP only to introduce subsequent -paragraphs. -

- -

-HYPER-IMPORTANT NOTE: -If your -ENDNOTE_MARKER_STYLE -is NUMBER (mom's default), the -final word on the -input line -that comes immediately before .ENDNOTE MUST -terminate with a -\c -inline escape. See the -endnote example -above. -

- -

-Additionally, in -fill -modes -(JUSTIFY -or -QUAD, -the line after .ENDNOTE OFF -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 -here). -

- -

-In -no-fill modes, the -optional argument BREAK or BR may be used -after the OFF (or QUIT, END, X, etc.) -argument to instruct mom NOT to join the next input -line to the previous output. See -here -for a more complete explanation, with examples. -

- -

-If your ENDNOTE_MARKER_STYLE is -LINE, do NOT use the \c escape, and -enter the line after .ENDNOTE OFF -normally. -

- - - -
- - - -

-Tag: ENDNOTES -

- -

-Unlike footnotes, which mom automatically outputs -at the bottom of pages, endnotes must be explicitly output by you, -the user. ENDNOTES, by itself (i.e. without any -argument), is the macro to do this. -

- -

-Typically, you'll use ENDNOTES at the end of -a document. If it's a single (i.e. not collated) document, -mom will print the endnotes pertaining to it. If -it's a collated document, mom will print all the -endnotes contained within all sections of the document (typically -chapters), appropriately identified and numbered. -

- -

-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 .ENDNOTES -immediately prior to -COLLATE. -Mom will print the endnotes, identified and -numbered appropriately, on a separate page prior to starting -the next section of the document. Each subsequent invocation -of .ENDNOTES outputs only those endnotes that -mom collected after the previous invocation. -

- -
- -

Endnote control macros

 - -

VERY IMPORTANT NOTE!

- -

-Endnote control macros must always be invoked prior to the first -instance of -.ENDNOTE / .ENDNOTE OFF. -

- -

-When you embed endnotes in the body of a document, -mom collects and processes them for later -outputting (when you invoke -.ENDNOTES). -By the time you do invoke .ENDNOTES, it's much too late -to change your mind about how you want them to look. -

- -

-My advice? If you're planning to change the default appearance of -endnotes pages, set them up prior to -START. -

- -
    -
  1. General endnotes-pages style control
    2. - -
  2. Endnotes-page header/footer control
    3. - -
  3. Endnotes-page head (i.e. the title at the top) control
    4. - -
  4. Endnote document-identification title
    5. - -
  5. Endnotes-pages endnote numbering style
    6. - -
- -

1. General endnotes page style control

 - -
*Endnote family/font/quad
 - -

-See -Arguments to the control macros. -

- -
-.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
-
- - - -
*Endnote point size
 - -

-Macro: ENDNOTE_PT_SIZE <base type size of endnotes> -

- -

-Unlike most other control macros that deal with size of document -elements, ENDNOTE_PT_SIZE takes as its argument -an absolute value, relative to nothing. Therefore, the argument -represents the size of endnote type in -points, -unless you append an alternative -unit of measure. -For example, - -

-    .ENDNOTE_PT_SIZE 12
-
- -sets the base point size of type on the endnotes page to 12 -points, whereas - -
-    .ENDNOTE_PT_SIZE .6i
-
- -sets the base point size of type on the endnotes page to 1/6 of an -inch. -

- -

-The type size set with ENDNOTE_PT_SIZE is the size -of type used for the text of the endnotes, and forms the basis from -which the point size of other endnote page elements is calculated. -

- -

-The default for -PRINTSTYLE TYPESET -is 12.5 points (the same default size used in the body of the -document). -

- - - -
*Endnote lead
 - -

-Macro: ENDNOTE_LEAD <base leading of endnotes> [ ADJUST ] -
- -*Does not require a unit of measure; points is assumed -

- -

-Unlike most other control macros that deal with leading of document -elements, ENDNOTE_LEAD takes as its argument an -absolute value, relative to nothing. Therefore, the argument -represents the -leading -of endnotes in -points -unless you append an alternative -unit of measure. -For example, - -

-    .ENDNOTE_LEAD 14
-
- -sets the base leading of type on the endnotes page to 14 -points, whereas - -
-    .ENDNOTE_LEAD .5i
-
- -sets the base leading of type on the endnotes page to 1/2 inch. -

- -

-If you want the leading of endnotes adjusted to fill the page, pass -ENDNOTE_LEAD the optional argument -ADJUST. (See -DOC_LEAD_ADJUST -for an explanation of leading adjustment.) -

- -

-The default for -PRINTSTYLE TYPESET -is 14 points, adjusted. -

- -

-NOTE: Even if you give mom -a .DOC_LEAD_ADJUST OFF command, she -will still, by default, adjust endnote leading. You MUST enter -.ENDNOTE_LEAD <lead> with no -ADJUST argument to disable this default behaviour. -

- - - -
*Singlespace endnotes (TYPEWRITE only)
 - -

-Macro: SINGLESPACE_ENDNOTES <toggle> -

- -

-If your -PRINTSTYLE -is TYPEWRITE and you use TYPEWRITE's default -double-spacing, endnotes are double-spaced. If your document is -single-spaced, endnotes are single-spaced. -

- -

-If, for some reason, you'd prefer that endnotes be single-spaced -in an otherwise double-spaced document (including double-spaced -collated -documents), invoke .SINGLESPACE_ENDNOTES 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 .SINGLESPACE_ENDNOTES with any argument -(OFF, QUIT, Q, X...). -

- - - -
*Endnote paragraph indenting
 - -

-Macro: ENDNOTE_PARA_INDENT <amount to indent first line of paragraphs in endnotes> -
- -*Requires a unit of measure -

- -

-ENDNOTE_PARA_INDENT works exactly the same way as -PARA_INDENT, -except that the indent given is the amount by which to indent the -first lines of endnote paragraphs, not document body paragraphs. -

- -

-The default is 1.5 -ems -for -PRINTSTYLE TYPESET; -1/2 inch for -PRINTSTYLE TYPEWRITE. -

- -

-NOTE: The first line of the first paragraph of -endnotes (the one attached immediately to the identifying endnote -number) is never indented. Only subsequent paragraphs are affected -by ENDNOTE_PARA_INDENT. -

- - - -
*Endnote paragraph spacing
 - -

-Macro: ENDNOTE_PARA_SPACE <toggle> -

- -

-ENDNOTE_PARA_SPACE works exactly the same way as -PARA_SPACE, -except that it inserts a blank line between endnote paragraphs, not -document body paragraphs. -

- -

-The default is not to insert a blank line between paragraphs in -endnotes. -

- -

-NOTE: Each endnote itself is always -separated from any previous endnote by a line space. -ENDNOTE_PARA_SPACE refers only to paragraphs that -appear within each discrete endnote. -

- - - -
*Turning off column mode during endnotes output
 - -

-Macro: ENDNOTES_NO_COLUMNS <toggle> -

- -

-By default, if your document is -set in columns, -mom sets the endnotes in columns, too. However, -if your document is set in columns and you'd like the endnotes not -to be, just invoke .ENDNOTES_NO_COLUMNS with no argument. -The endnotes pages will be set to the full page measure of your -document. -

- -

-If you output endnotes at the end of each document in a -collated -document set in columns, column mode will automatically -be reinstated for each document, even with -ENDNOTES_NO_COLUMNS turned on. In such -circumstances, you must re-enable it for each collated document. -

- -
*Pagination of endnotes
 - - - -
Endnotes-pages page numbering style
 - -

-Macro: ENDNOTES_PAGENUM_STYLE DIGIT | ROMAN | roman | ALPHA | alpha -

- -

-Use this macro to set the page numbering style of endnotes pages. -The arguments are identical to those for -PAGENUM_STYLE. -The default is digit. You may want to change it to, say, -alpha, which you would do with - -

-    .ENDNOTES_PAGENUM_STYLE alpha
-
-

- - - -
Setting the first page number of endnotes pages
 - -

-Macro: ENDNOTES_FIRST_PAGENUMBER <page # that appears on page 1 of endnotes> -

- -

-Use this macro with caution. If all endnotes for several -collated -documents are to be output at once, i.e. not at the end of each -separate doc, ENDNOTES_FIRST_PAGENUMBER tells -mom what page number to put on the first page of -the endnotes. -

- -

-If you set ENDNOTES_FIRST_PAGENUMBER in collated -documents where the endnotes are output after each separate doc, -you have to reset every separate document's first page number after -COLLATE -and before -START. -

- - - -
Omitting a page number on the first page of endnotes
 - -

-Macro: ENDNOTES_NO_FIRST_PAGENUM <toggle> -

- -

-This macro is for use only if FOOTERS are on. It -tells -ENDNOTES -not to print a page number on the first endnotes page. -Mom's default is to print the page number. -

- - - -
Suspending pagination of endnotes pages
 - -

-Macro: SUSPEND_PAGINATION -
- -Macro: RESTORE_PAGINATION -

- -

-SUSPEND_PAGINATION doesn't take an argument. -Invoked immediately prior to -ENDNOTES, -it turns off endnotes pages pagination. Mom -continues, however to increment page numbers silently. -

- -

-To restore normal document pagination after endnotes, invoke -.RESTORE_PAGINATION (again, with no argument) immediately -after .ENDNOTES. -

- -

2. Endnotes-page header/footer control

 - -

- -If you wish to modify what appears in the header/footer that appears -on endnotes page(s), make the changes before you invoke -.ENDNOTES, -not afterwards. -

- -

-Except in the case of -DOCTYPE CHAPTER, -mom prints the same header or footer used -throughout the document on the endnotes page(s). Chapters get -treated differently in that, by default, mom does -not print the header/footer centre string (normally the chapter -number or chapter title.) In most cases, this is what you want. -However, should you not want mom to remove -the centre string from the endnotes page(s) headers/footers, invoke -.ENDNOTES_HEADER_CENTER -with no argument. -

- -

-An important change you may want to make is to put the word -"Endnotes" in the header/footer centre position. -To do so, do - -

-    .HEADER_CENTER "Endnotes"
-               or
-    .FOOTER_CENTER "Endnotes"
-
- -prior to invoking .ENDNOTES. If your -DOCTYPE -is CHAPTER, you must also invoke -ENDNOTES_HEADER_CENTER -for the HEADER_CENTER to appear. -

- -
*Endnotes page(s) header/footer centre string
 - -

-Macro: ENDNOTES_HEADER_CENTER toggle -

- -

-If your -DOCTYPE -is CHAPTER and you want mom -to include a centre string in the headers/footers that appear -on endnotes pages, invoke .ENDNOTES_HEADER_CENTER -(or .ENDNOTES_FOOTER_CENTER) with no argument. -Mom's default is NOT to print the centre string. -

- -

-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 (OFF, QUIT, Q, X...). -

- -
*Allow headers on endnotes-pages
 - -

-Macro: ENDNOTES_ALLOWS_HEADERS <none> | ALL -

- -

-By default, if HEADERS are on, mom -prints page headers on all endnotes pages except the first. If you -don't want her to print headers on endnotes pages, do - -

-    .ENDNOTES_ALLOWS_HEADERS OFF
-
-

- -

-If you want headers on every page including the first, do - -

-    .ENDNOTES_ALLOWS_HEADERS ALL
-
-

- -

-NOTE: If FOOTERS are on, -mom prints footers on every endnotes page. This is -a style convention. In mom, there is no such beast -as ENDNOTES_ALLOWS_FOOTERS OFF. -

- -

3. Endnotes first page header (title) control

 - - - -
*Endnotes first page header (title) string
 - -

-Macro: ENDNOTE_STRING "<head to print at the top of endnotes>" -

- -

-By default, mom prints the word -"ENDNOTES" as a head at the top of the first page -of endnotes. If you want her to print something else, invoke -.ENDNOTE_STRING 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 .ENDNOTE_STRING with -a blank argument (either two double-quotes side by side — -"" — or no argument at all). -

- - - -
*Endnotes first page header (title) control
 - -

-See -Arguments to the control macros. -

- -
-.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)
-
- - - -
*Endnotes first page header (title) placement
 - -

-Macro: ENDNOTE_STRING_ADVANCE <distance from top of page> -
- -*Argument requires a unit of measusure -

- -

-By default, mom places the title (the docheader, as -it were) of endnotes pages (typically "ENDNOTES") on the same -baseline -that is used for the start of -running text. -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 .ENDNOTE_STRING_ADVANCE -with an argument stating the distance from the top edge of the -page at which you'd like the title placed. -

- -

-The argument requires a unit of measure, so if you'd like the title -to appear 1-1/2 inches from the top edge of the page, you'd tell -mom about it like this: - -

-    .ENDNOTE_STRING_ADVANCE 1.5i
-
-

- - - -
*Endnotes first page header (title) underlining
 - -

-Macro: ENDNOTE_STRING_UNDERLINE [DOUBLE] [<underline weight> [<underline gap> [<distance between double rules]]] | <none> | <anything> -
- -Alias: ENDNOTE_STRING_UNDERSCORE -
- -*The argument <underline weight> must NOT have the unit of measure, p, appended to it -

- -

-Invoked without an argument, .ENDNOTE_STRING_UNDERLINE -will place a single rule underneath the endnotes-page head. Invoked -with the argument DOUBLE, -ENDNOTE_STRING_UNDERLINE will double-underline -the head. Invoked with any other non-numeric argument, (e.g. -OFF, NO, X, etc.) -the macro disables underlining of the head. -

- -

-In addition, you can use ENDNOTE_STRING_UNDERLINE -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. -

- -

-Some examples: - -

-    .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/4 of
-          a point; set the gap between the string and the upper
-          underline to 3 points; leave the gap between the upper
-          and the lower underline at the default
-    
-    .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
-
- -Note, from the above, that in all instances, underlining (single or -double) is enabled whenever ENDNOTE_STRING_UNDERLINE -is used in this way. -

- -

-Mom'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. -

- - - -
*Endnotes first page header (title) automatic capitalization
 - -

-Macro: ENDNOTE_STRING_CAPS toggle -

- -

-Invoked by itself, .ENDNOTE_STRING_CAPS will -automatically capitalize the endnotes-page head. Invoked with any -other argument, the macro disables automatic capitalization of the -head. -

- -

-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 -ENDNOTE_STRING -is in caps/lower case and ENDNOTE_STRING_CAPS is -on, this is exactly what will happen. -

- -

-Mom's default is to capitalize the endnotes-pages -head string. -

- - - -

4. Endnote document-identification title

 - -
*Endnote document-identification title string
 - -

-Macro: ENDNOTE_TITLE "<title to identify a document in endnotes>" -

- -

-By default, mom identifies the document(s) to which -endnotes belong by the document title(s) given to the -TITLE -macro. If you'd like her to identify the document(s) another way, -just invoke .ENDNOTE_TITLE with the identifying title you -want, surrounded by double-quotes. -

- -

-If you don't want any identifying title, invoke -.ENDNOTE_TITLE with a blank argument (either two -double-quotes side by side — "" — -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. -

- - - -
*Endnote document-identification title control
 - -

-See -Arguments to the control macros. -

- -
-.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)
-
- - - -
*Endnotes-page head (title) underlining
 - -

-Macro: ENDNOTE_TITLE_UNDERLINE [DOUBLE] [<underline weight> [<underline gap> [<distance between double rules]]] | <none> | <anything> -
- -Alias: ENDNOTE_TITLE_UNDERSCORE -
- -*The argument <underline weight> must NOT have the unit of measure, p, appended to it -

- -

-Invoked without an argument, .ENDNOTE_TITLE_UNDERLINE -will place a single rule underneath the document identification -title. Invoked with the argument DOUBLE, -ENDNOTE_TITLE_UNDERLINE will double-underline -the title. Invoked with any other non-numeric argument, (e.g. -OFF, NO, X, etc.) -the macro disables underlining of the title. -

- -

-In addition, you can use ENDNOTE_TITLE_UNDERLINE -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. -

- -

-Some examples: - -

-    .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
-
- -Note, from the above, that in all instances, underlining (single or -double) is enabled whenever ENDNOTE_TITLE_UNDERSCORE -is used in this way. -

- -

-Mom's default is to single-underline the title -with a 1/2-point rule place 2 points below its baseline. -

- - - -

5. Endnotes-pages endnote numbering style

 - -
*Endnote marker style
 - -

-The macro to control how endnotes are referenced is -ENDNOTE_MARKER_STYLE. -

- -

-By default, mom places superscript numbers in -running text -to identify endnotes. However, if you have -line-numbering -turned on, you may instruct mom not to put -superscript numbers in the running text, but rather to reference -endnotes by line number. The command to do this is - -

-    .ENDNOTE_MARKER_STYLE LINE
-
-

- -

-With ENDNOTE_MARKER_STYLE LINE, -mom will identify endnotes either by single -line numbers, or line ranges. If what you want is a single line -number, you need only invoke .ENDNOTE, without -terminating the text line before it with \c, -at the appropriate place in running text. (Should you wish to -revert to mom's default behaviour of placing -a superscript number in the text to identify an endnote, you -can invoke .ENDNOTE_MARKER_STYLE with the argument, -NUMBER. 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.) -

- - - -

-If you want a range of line numbers (e.g. [5-11] ), -insert, directly into the first line of the range you want, the -inline escape, -\*[EN-MARK]. For the terminating line number of -the range, you need only invoke .ENDNOTE, (again, -without attaching \c to the text line before it). -Mom is smart enough to figure out that where -.ENDNOTE is invoked represents the terminating line -number. -

- -
*Spacing between line-numbered endnotes and the endnote text
 - -

-Given the impossibility of knowing, in advance, the "string length" -of all the line numbers or ranges of line numbers that will be used -in endnotes (the string length of 12 is two; the string length -of 12-15 is 5), mom cannot "hang" line numbers -and guarantee that they, and the endnote text, will align in a -visually pleasing manner. Consequently, mom sets -the entirety of line-numbered endnotes completely flush left, -including the line numbers themselves. The line -numbers (by default, enclosed in square brackets) are separated from -the beginning of each endnote by a gap, so that a line-numbered -endnote looks approximately like this: - -

-    [1-2]   Notwithstanding, Frye later asserts that Christianity
-    is "a ghost with the chains of a foul historical record of
-    cruelty clanking behind it."
-
-

- -

-You can change the size of the gap with the macro, -ENDNOTE_LINENUMBER_GAP, which takes as its single -argument the size of the gap. The argument requires a -unit of measure. -So, for example, to change the gap to 2 -picas, -you'd do - -

-    .ENDNOTE_LINENUMBER_GAP 2P
-
-

- -

-The default gap for both -PRINTSTYLE TYPESET -and -PRINTSTYLE TYPEWRITE -is 1.5 -ems. -

- -
*Brackets around endnotes line-numbers
 - -

-By default, mom puts endnote line numbers inside -square brackets. The style of the brackets may be changed with the -macro, ENDNOTE_LINENUMBER_BRACKETS, which takes one -of three possible arguments: PARENS ("round" -brackets), SQUARE (the default) or BRACES -(curly braces). If you prefer a shortform, the arguments, -(, [ or { may be used instead. -

- -
*A separator after endnotes line-numbers instead of brackets
 - -

-If you don't want the numbers enclosed in brackets, you may tell -mom to use a "separator" instead. A common -separator would be the colon, but it can be anything you like. The -macro to do this is ENDNOTE_LINENUMBER_SEPARATOR, -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 - -

-    .ENDNOTE_LINENUMBER_SEPARATOR :
-
-

- -
*Endnote numbering style control
 - -

-See -Arguments to the control macros. -

- -

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

- -
-.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)
-
- -
*Endnote numbering alignment
 - -

-By default, mom hangs the numbers on endnotes pages, -aligned right to two placeholders, producing this: - - - -

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

- -

-The macros to alter this behaviour are - -

-

- -
- - - - - -

-Macro: ENDNOTE_NUMBERS_ALIGN_RIGHT <number of placeholders> -

- -

-ENDNOTE_NUMBERS_ALIGN_RIGHT takes one -(non-optional) argument: the number of placeholders to reserve for -right alignment of endnote numbers. -

- -

-For example, if you have fewer than ten endnotes, you might want to do - -

-    .ENDNOTE_NUMBERS_ALIGN_RIGHT 1
-
- -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 - -
-    .ENDNOTE_NUMBERS_ALIGN_RIGHT 3
-
- -to ensure that the numbers hang and are properly right-aligned. -

- -
- - - - - -

-Macro: ENDNOTE_NUMBERS_ALIGN_LEFT -

- -

-If you don't want the endnote numbers to hang and right-align, -invoke .ENDNOTE_NUMBERS_ALIGN_LEFT, which doesn't require -any argument. This disables hanging and right-alignment of endnote -numbers, so that the example -above -comes out like this: - -

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

- -
- - - -

Margin notes

 - - - -

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

- -

-The margin notes macros and routines in om.tmac -(mom) are "mommified" versions of the -margin notes macros and routines written by Werner Lemberg and -patched by Gaius Mulley. -

- -

Margin notes behaviour

 - -

-First things first: before you enter your first margin note, you -must "initialize" margin notes with -MN_INIT. -MN_INIT sets up the style parameters for margin -notes, including things like -font, -family -and -leading. -

- -

-After initializing margin notes, you create margin notes with the -MN -macro. Based on the argument you pass MN, your -margin note will go in either the left or the right margin. -

- -

-Margin notes are tricky from a typographic standpoint with respect -to vertical placement. Since the leading of margin notes may -differ from that of -running text, -it's impossible for mom to guess whether to align -the first lines of margin notes with a document -baseline, -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! -

- -

-Given this difficulty, mom always aligns the first -line of any margin note with a document baseline. If you want a -different behaviour, you must adjust the position(s) of margin -notes yourself, on a note by note basis. (See -Adjusting the vertical position of margin notes.) -

- -

-Generally speaking, mom tries to place margin -notes at the point where you invoke the tag, -.MN. -However, in the event that a margin note runs deep, she may not -be able to place a subsequent margin note exactly where you want. -In such an instance, mom will "shift" the -margin note down on the page, placing it one (margin note) linespace -beneath the previous margin note (plus whatever vertical space -is required to get the first line to line up with a baseline of -running text). A warning will be issued, letting you know this has -happened, and where. -

- -

-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 -.MN is invoked. In that case, mom -ignores the margin note entirely and issues a warning, letting you -know what she's done, and where. -

- -

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

- -

-If your document is being set in two columns, mom -will sensibly and automatically set all margin notes pertaining -to the left column in the left margin, and all margin notes -pertaining to the right column in the right margin, regardless of -the "direction" argument you give the MN -tag. If you try to use MN in documents of more -than two columns, mom will ignore all margin notes, -and issue warning for each. -

- -

Adjusting the vertical position of margin notes

 - -

-When the -leading -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. -

- -

-Adjustments to the vertical position of margin notes must be done -inside the margin note (i.e. after .MN), at the top, -before entering text. The commands to use are - -

-    \!.ALD (to lower the margin note)a
-        and
-    \!.RLD (to raise it)
-
- -The \! must precede the macros, or they won't -have any effect. -

- -
- - - - - -

-Macro: MN_INIT -
- -Macro arguments: -
- -[ RAGGED | SYMMETRIC ] -
- -< left-width right-width gutter family+font point-size lead colour hyphenation-flags > -

- -

-Before you enter your first margin note, you must initialize -all the parameters associated with margin notes with -MN_INIT. If you forget to do so, -mom will issue a warning and abort. -

- -

-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 "" (i.e. two double-quotes with -no space between them). Defaults for each argument are given in the -explanations below. -

- -

[ RAGGED | SYMMETRIC ]

- -

-If the first argument is RAGGED, both left and -right margin notes will be flush left. If the first argument -is SYMMETRIC left margin notes will be set flush -right, and right margin notes will be set flush -left. The effect is something like this: - -

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

- -

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

- -

<left-width>

- -

-The width of left margin notes. A -unit of measure -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. -

- -

<right-width>

- -

-The width of right margin notes. A -unit of measure -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. -

- -

<gutter>

- -

-The -gutter -between margin notes and -running text. -A -unit of measure -must be appended directly onto the argument. The gutter applies to -both left and right margin notes. The default is 1 -em. -

- -

<font>

- -

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

- -

<point size>

- -

-The point size of type for margin notes. There is no need to append a -unit of measure -to the argument; -points -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. -

- -

<lead>

- -

-The -leading -of margin notes. lead uses -points -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, -DOC, to this argument, which indicates that the -leading should be the same as the document's base leading. -

- -

<colour>

- -

-The colour of margin notes. The colour must be pre-initialized -with -NEWCOLOR -or -XCOLOR. -The default is black. -

- -

<hyphenation-flags>

- -

-A number telling groff how you want margin notes -hyphenated. - -

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

- - - -
- - - -

-Macro: MN LEFT | RIGHT -

- -

-Once you've initialized margin notes with -.MN_INIT, -you can enter margin notes any time you like with -.MN. An argument of LEFT will set -a left margin note. An argument of RIGHT will set -a right margin note. -

- -

-Any argument, such as OFF (or -QUIT, END, X, -etc) exits the current margin note. -

- -
- - - - - -

Inserting a blank page into the document

 - - -

-Macro: BLANKPAGE <# of blank pages to insert> | NULL -

- -

-This one does exactly what you'd expect — inserts a blank -page into the document. Unless you give the optional argument, -NULL, mom silently increments the page -number of every blank page and keeps track of -recto/verso -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"). -

- -

-The required argument to BLANK_PAGE is the -number of blank pages to insert. The argument is not optional, -hence even if you only want one blank page, you have to tell -mom: - -

-    .BLANKPAGE 1
-
-

- -

-The optional argument, NULL, allows you to output the -specified number of pages without mom incrementing -the page number for each blank page. She will, however, continue -to keep track of which pages are recto/verso if recto/verso -printing has been enabled. -

- -
- - - -

Document termination string

 - - - -

-The use of FINIS is optional. If you invoke it -(at the end of a document before -TOC -or -ENDNOTES), -mom -deposits the word, END, centred after a blank line, beneath the last -line of the document. END is enclosed between -em-dashes. -

- -

-Please note that in versions of -mom prior to 1.1.9, FINIS used to -turn off -footers -(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. -

- -

-If you're writing in a language other than English, you can -change what mom prints for END with -the control macro FINIS_STRING. -

- -
- - - -

-Macro: FINIS -

- -

-The use of FINIS is optional, but if you use -it, it should be the last macro you invoke in a document (before -ENDNOTES -or -TOC). -See -above -for a description of how FINIS behaves. -

- -

-NOTE: If you don't use FINIS, -and you don't want -footers -(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: - -

-    .FOOTERS OFF
-    .PAGINATE OFF
-
-

- - - -
- -

Changing the FINIS string

 - -

-By default, FINIS prints the word, END, between -em-dashes. -If you'd like mom to print something else -between the dashes, use the FINIS_STRING macro -(anywhere in the document prior to FINIS). -

- -

-For example, if your document's in French, you'd do - -

-    .FINIS_STRING "FIN"
-
- -Double-quotes must enclose the macro's argument. -

- -

-NOTE: If you pass FINIS_STRING -a blank string, i.e. - -

-    .FINIS_STRING ""
-
- -mom will still print the em-dashes if you invoke -.FINIS. This, in effect, produces a short, centred -horizontal rule that terminates the document. (In -PRINTSTYLE TYPEWRITE, -it's a short, dashed line composed of four hyphens.) -

- - - -
- -

Automatic capitalization of the FINIS string

 - -

-By default, mom sets the string you pass to -FINIS all-caps. If you'd prefer that she not -do so, but rather respect the FINIS string exactly as you enter -it, invoke the macro, .FINIS_STRING_CAPS with the -OFF argument, like this: - -

-    .FINIS_STRING_CAPS OFF
-
- -OFF, above, could be anything, e.g. NO -or X. -

- - - -
- -

Changing the FINIS colour

 - -

-Invoking the control macro, FINIS_COLOR, 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 -inline escape, -\*[<colorname>], -in the argument passed to FINIS, only the text -will be in the new colour; the em-dashes will be in the default -document colour (usually black). -

- -
- - - -

Tables of contents

 - - - -

-Want a table of contents for your document? Easy. Just enter - -

-    .TOC
-
- -as the very last macro of your document file. Mom -will have picked up all document titles (in -collated -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! -

- -

-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. Mom is all about -simplicity AND flexibility. -

- -

TOC behaviour

 - -

-When you output a toc (with -TOC), -mom finishes processing the last page of your document, -then breaks to a new page for printing the toc. -

- -

-Mom follows standard typesetting conventions for -tables of contents. To this end, if -HEADERS -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 -FOOTERS -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 -.FOOTER_ON_FIRST_PAGE -immediately before TOC.) Subsequent toc pages have -both page headers or footers and a page number. -

- -

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

- -

-Tocs are never set in columns, regardless of whether the rest of -the document is. Lastly, if -recto/verso -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 -BLANKPAGE -or by using the toc control macro -TOC_RV_SWITCH. -

- -

-The overall toc -family, -point size -and -lead -can be altered with the toc -control macros, -as can the family, -font, -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. -

- -

Using psselect to put the table of contents where you want

 - -

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

- -

-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 psselect -programme provided by the psutils suite of tools -(which you may have to install as a package from your distribution -if it is not already on your system). -

- -

-The procedure for using psselect 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, gv. Once you know the number of pages in the -table of contents, use psselect to re-arrange them -appropriately. -

- -

-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: - -

-     psselect -p _1,1-_2 <PostScript file> > <new PostScript file>
-
-

- -

-The -p option instructs psselect 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." -psselect outputs to stdout, so you have to redirect -the output to a new file. -

- -

-If your table of contents runs to two pages, the command would look -like this: - -

-     psselect -p _1-_2,1-_3 <PostScript file> > <new PostScript file>
-
-

- -

-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: - -

-     psselect -p 1,_1-_2,2-_3 <PostScript file> > <new PostScript file>
-
-

- - - -
- - - -

-Macro: TOC -

- -

-If you want a toc, just put TOC as the last macro -in a document. Mom takes care of the rest. -

- -
- -

TOC control macros

 - -

-TOC control macros must be placed prior to invoking -.START. -

- -

-ERRATUM: In versions of mom prior to -1.3-e_3, the documentation stated that TOC control macros could go -anywhere in a mom file prior to invoking -.TOC. -That convenience has been removed for Very Good Reasons. -

- -
    -
  1. General toc page style control
    2. - -
  2. Toc page numbering
    3. - -
  3. Changing the toc header (title), string and style
    4. - -
  4. Changing the style for toc entries
    5. - -
  5. Additional toc control macros
    6. - -
- -
- -

1. General toc page style control

 - -
*Toc family
 - -

-See -Arguments to the control macros. -

- -

-Set the family of toc pages with TOC_FAMILY, 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. -

- -

-All elements on a toc page also have their own _FAMILY -control macros, which override the default set by -TOC_FAMILY. -

- - - -
*Toc point size
 - -

-Macro: TOC_PT_SIZE <base type size of the toc> -

- -

-Unlike most other control macros that deal with size of document -elements, TOC_PT_SIZE takes as its argument an -absolute value, relative to nothing. Therefore, the argument -represents the size of toc type in -points, -unless you append an alternative -unit of measure. -For example, - -

-    .TOC_PT_SIZE 12
-
- -sets the base point size of type for the toc to 12 points, whereas - -
-    .TOC_PT_SIZE .6i
-
- -sets the base point size of type for the toc to 1/6 of an inch. -

- -

-The type size set with TOC_PT_SIZE forms the basis -from which the point size of other toc page elements are calculated. -

- -

-The default for -PRINTSTYLE TYPESET -is 12.5 points (the same default size used in the body of the -document). -

- - - -
*Toc lead
 - -

-Macro: TOC_LEAD <leading of the toc> [ ADJUST ] -
- -*Does not require a unit of measure; points is assumed -

- -

-Unlike most other control macros that deal with leading of document -elements, TOC_LEAD takes as its argument an -absolute value, relative to nothing. Therefore, the argument -represents the -leading -of tocs in -points -unless you append an alternative -unit of measure. -For example, - -

-    .TOC_LEAD 14
-
- -sets the base leading of type on the endnotes page to 14 -points, whereas - -
-    .TOC_LEAD .5i
-
- -sets the base leading of type on the endnotes page to 1/2 inch. -

- -

-If you want the leading of toc pages adjusted to fill the -page, pass TOC_LEAD the optional argument -ADJUST. (See -DOC_LEAD_ADJUST -for an explanation of leading adjustment.) -

- -

-The default for -PRINTSTYLE TYPESET -is the prevailing document lead (16 by default), adjusted. -

- -

-NOTE: Even if you give mom -a .DOC_LEAD_ADJUST OFF command, she -will still, by default, adjust toc leading. You MUST enter -TOC_LEAD <lead> with no -ADJUST argument to disable this default behaviour. -

- -

-ADDITIONAL NOTE: Tocs are always double-spaced in -PRINTSTYLE TYPEWRITE, -regardless of whether the body of the document is single-spaced. -

- -
- -

2. Toc page numbering

 - -

-The page numbering of toc pages is controlled by the same macros -that control -document page numbering, -except -PAGENUM -(tocs always start on page 1). The defaults are the same as for the -rest of the document. -

- -

-If you wish to change some aspect of toc pagination, use -the document pagination control macros immediately prior to -.TOC. -

- -

-A special macro, -TOC_PAGENUM_STYLE -controls the style of toc pages page numbers. -

- - - -
- - - -

-Macro: PAGINATE_TOC <toggle> -

- -

-By default, mom paginates the toc. If you'd like -her not to, do - -

-    .PAGINATE_TOC OFF
-
-

- -

-NOTE: Simply invoking -.PAGINATION OFF -or -.PAGINATE OFF -disables toc pagination for the first toc page only. You -MUST use .PAGINATE_TOC OFF to disable toc pagination, -even if pagination is turned off elsewhere in your document. -

- - - -
- - - -

-Macro: TOC_PAGENUM_STYLE <DIGIT | ROMAN | roman | ALPHA | alpha> -

- -

-By default, mom uses roman numerals to number toc -pages. Use TOC_PAGENUM_STYLE if you'd prefer -something else. For example, to have standard digits instead of -roman numerals, do the following: - -

-    .TOC_PAGENUM_STYLE DIGIT
-
-

- -
- -

3. Changing the toc header (title) string and style

 - -

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

- -

- -

-    .TOC_HEADER_STRING "Table of Contents"
-
- - -The style of the toc header (title) is managed by the usual control -macros (see -arguments to the control macros). -

- -

-

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

4. Changing the style for toc entries

 -

- -

-"Toc entries" refers to titles, heads, subheads and -paragraph heads as they appear in the toc. Their style is managed -by the usual -control macros, -starting with TOC_ -

- -
*The table of contents _INDENT control macros
 - -

-The toc control macros that end in _INDENT all take a single -argument that requires a -unit of measure. -The argument is the distance to indent the entry, always measured -from the left margin. For example, - -

-    .TOC_HEAD_INDENT 2P
-
- -indents head entries 2 -picas -from the left margin. -

- -
*Changing the style for toc title entries
 - -

-(See -arguments to the control macros). -

- -

-Toc title entries are the titles of documents that have been -collated -together. -

- -
-    .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
-
- -
*Changing the style for toc head entries
 - -

-(See -arguments to the control macros). -

- -

-Toc head entries are main heads that appear in the body of a -document. -

- -
-    .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
-
- -
*Changing the style for toc subhead entries
 - -

-(See -arguments to the control macros). -

- -

-Toc subhead entries are subheads that appear in the body of a -document. -

- -
-    .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
-
- -
*Changing the style for toc paragraph head entries
 - -

-(See -arguments to the control macros). -

- -

-Toc paragraph head entries are paragraph heads that appear in the -body of a document. -

- -
-    .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
-
- -
*Changing the style for toc paragraph page number listings
 - -

-(See -arguments to the control macros). -

- -

-Toc paragraph head entries are paragraph heads that appear in the -body of a document. -

- -
-    .TOC_PN_FAMILY  default = prevailing doc family (Times Roman in TYPEWRITE)
-    .TOC_PN_FONT    default = roman
-    .TOC_PN_SIZE    default = +0
-
- -
- -

5. Additional toc macros

 - -

-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 -mom append author(s) to toc title entries. -

- - - -
- - - -

-Macro: TOC_RV_SWITCH -

- -

-TOC_RV_SWITCH doesn't take an argument. It simply -instructs mom to switch the left and right margins -of -recto/verso -documents should the toc happen to begin on an even page when you -want an odd, or vice versa. -

- -

-The same result can be accomplished by outputting a -BLANKPAGE. -

- - - -
- - - -

-Macro: TOC_TITLE_ENTRY <"alternate wording for a title entry in the toc"> -

- -

-In -collated -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 -docheader. -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 - -

-               Chapter 6
-    Burning Bush — Maybe God Was Right
-
- -you might want only the chapter title, not the chapter number, to -show up in the toc. (By default, TOC generates -both.) -

- -

-If you want to change the wording of a title entry in the toc, -simply invoke .TOC_TITLE_ENTRY with the desired -wording, enclosed in double-quotes. Using the example, above, - -

-    .CHAPTER 6
-    .CHAPTER_TITLE "Burning Bush — Maybe God Was Right"
-    .TOC_TITLE_ENTRY "Burning Bush"
-    .DOCTYPE CHAPTER
-
- -would identify chapter 6 in the toc simply as "Burning -Bush". -

- - - -
- - - -

-Macro: TOC_APPENDS_AUTHOR <none> | <"name(s) of authors"> -

- -

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

- -

-If you invoke .TOC_APPENDS_AUTHOR with no argument, -mom appends the first argument you passed to -AUTHOR -to toc title entries, separated by a front-slash. -

- -

-If you invoke .TOC_APPENDS_AUTHOR with an argument -(surrounded by double-quotes), mom 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 - -

-    .TOC_APPENDS_AUTHOR "Blough et al."
-
- -would be a good way to identify them in the toc. -

- - - -
- - - -

-Macro: TOC_PADDING <number of placeholders to allow for page number listings> -

- -

-By default, mom allows room for 3 digits in the -page number listings of tocs. If you'd like some other number of -placeholders, say 2, do - -

-    .TOC_PADDING 2
-
-

- -
- - - -

Inserting images into a document — the PSPIC macro

- - - -

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

- -

-You can insert images into a document by using the -PSPIC macro. PSPIC isn't -actually part of mom; it comes packaged with -groff itself. Use it whenever you want to insert -images into a mom 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. -

- -

-man groff_tmac contains the documentation for -PSPIC, but I'll repeat it here with a few -modifications. -

- -

----From man groff_tmac--- -

-<file> 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 -units of measure -attached; the default unit of measure is -i. 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 -L -and -R options cause the graphic -to be left-aligned and right-aligned, respectively. The --I option causes the graphic to be -indented by <n> (default unit of measure is -"m"). -

-------------------------- -

- -

-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 -ALD -and -RLD -macros. -

- -

-Additionally, images inserted into -running text -will almost certainly disrupt the baseline placement of running -text. In order to get mom back on track after -invoking .PSPIC, I strongly recommend using the -SHIM -macro so that the bottom margin of running text falls where it -should. -

- -
- -

-Next   -Prev   -Top   -Back to Table of Contents -

- - - - - diff --git a/contrib/mom/momdoc/docprocessing.html b/contrib/mom/momdoc/docprocessing.html deleted file mode 100644 index a968046b..00000000 --- a/contrib/mom/momdoc/docprocessing.html +++ /dev/null @@ -1,3392 +0,0 @@ - - - - - - -Mom -- Document Processing, Introduction and Setup - - - - - - - -

-Next   -Prev   -Back to Table of Contents -

- -

Document processing with mom

 - -

-Introduction to document processing -
- -Some document defaults -
- -***IMPORTANT NOTE on leading/spacing and bottom margins*** -
- -The SHIM macro -

- -

Table of Contents for document processing

- - - -
- - - -

Introduction to document processing

- -

-As explained in -Document processing with mom, -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 -ALIAS -macro.) -

- -

-In addition to the tags themselves, mom has an -extensive array of macros that control how they look and behave. -

- -

-Setting up a mom doc is a simple, four-part procedure. -You begin by entering information about the document itself (title, -subtitle, author, etc.). Next, you tell mom what -kind of document you're creating (e.g. chapter, letter, abstract, -etc...) and what kind of output you want (typeset, typewritten, -draft-style, etc). Thirdly, you make as many or as few changes to -mom's default behaviour as you wish. Lastly, you -invoke the -START -macro. Voilà! You're ready to write. -

- - - -
- -

Some document defaults

- -

-As is to be expected, mom has defaults for -everything. If you want to know a particular default, read about it -in the description of the pertinent tag. -

- -

-I fear the following may not be adequately covered in the -documentation. Just in case, here they are. - -

-

- -

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

- - - -
- -

IMPORTANT NOTE on leading/spacing and bottom margins

 - -

-Mom takes evenly-aligned bottom margins in -running text -very seriously. Only under a very few (exceptional) circumstances -will she allow a bottom margin to "hang" (i.e. to fall -short). -

- -

-In order to ensure even bottom margins, mom -uses the "base" document -leading -in effect at the start of running text on each page (i.e. -the leading used in paragraphs) to calculate the spacing of every -document element. Prior to invoking -START, -this is set with the -typesetting macro -LS, -afterwards with the document -control macro -DOC_LEAD. -

- -

-Because mom relies so heavily on the base document -leading, any change to the leading or spacing on a page will almost -certainly have undesirable consequences on that page's bottom margin -unless the change is fully compensated for elsewhere on the page. -

- -

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

- -

-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" -unit of measure -with whatever spacing macro you choose — -ALD, -RLD, -SPACE -— and mom 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, -provided you compensate for the fractional linespace somewhere -else on the page. -

- -

-If all this seems like too much work, mom -provides a special macro to get you out of trouble if you've played -around with leading and/or spacing. The macro is called -SHIM (like those little pieces of wood carpenters -use to get their work even, level and snug), and it's described -below. -

- - - -
- - - -

-Macro: SHIM -

- -

-SHIM doesn't take any argument. Use it whenever -you've played around with the -leading -or spacing on a page and you -need to get mom's document leading back on track. -

- -

-For example, say you want to insert a picture into a document with -the special groff macro, PSPIC (see man -groff_tmac for usage). -

- -

-Pictures aren't usually conveniently sized in multiples of document -leading, which means that when you insert the picture, you disrupt -mom'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. -

- -

-The solution is to insert SHIM after the picture, -like this: - -

-    <some lines of text>
-    .PSPIC <full path to picture>
-    .SHIM
-    <more lines of text>
-
-

- -

-SHIM instructs mom to insert as -much or a little space after the picture as is needed to ensure that -the baseline of the next -output line -falls where mom would have put it had you not -disrupted the normal flow of output lines with the picture. -

- -

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

-    <some lines of text>
-    .RLD 3p
-    .PSPIC <full path to picture>
-    .SHIM
-    <more lines of text>
-
- -to raise the picture slightly -(Reverse LeaD -3 points; see -RLD), -and still have SHIM ensure that text underneath -falls exactly where it's supposed to. -

- -

-NOTE: For information on disabling the automatic -shimming of quotes and blockquotes during document processing, see -here. -

- -
- - - -

Document setup

 - -

Tutorial — setting up a mom document

 - -

-There are four "parts" to setting up a -mom doc (three, actually, with one optional). -Before we proceed, though, be reassured that something as simple as - -

-    .TITLE     "By the Shores of Lake Attica"
-    .AUTHOR    "Rosemary Winspeare"
-    .PRINTSTYLE TYPESET
-    .START
-
- -produces a beautifully typeset 8.5x11 document, with a -docheader -at the top of page 1, -page headers -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. -

- -

-For the purposes of this tutorial, we're going to set up a short -story — My Pulitzer Winner by Joe Blow. Thankfully, -we don't have to look at story itself, just the setup. -Joe wants the document - -

-

- -

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

- -

Step 1

- -

-The first step in setting up any document is giving mom -some reference information. The reference macros are: - -

-

- -

-You can use as many or as few as you wish, although at a minimum, -you'll probably fill in TITLE (unless the document's -a letter) and AUTHOR. Order doesn't matter. -You can separate the -arguments -from the macros by any number of spaces. The following are -what you'd need to start Joe Blow's story. - -

-    .TITLE    "My Pulitzer Winner"
-    .AUTHOR   "Joe Blow"
-    .DRAFT     7
-    .REVISION  39
-
-

- -

Step 2

- -

-Once you've given mom the reference information she -needs, you tell her how you want your document formatted. What kind -of document is it? Should it be typeset or typewritten? Is this -a "final" copy (for the world to see) or just a draft? -Mom calls the macros that answer these questions -"the docstyle macros." They are: - -

-

- -

-Mom has defaults for DOCTYPE -and COPYSTYLE; if they're what you want, you -don't need to include them here. However, PRINTSTYLE -has no default and MUST be present in every formatted document. -If you omit it, mom won'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> -

- -

-Adding to what we already have, the next bit of setup for Joe -Blow's story looks like this: - -

-    .TITLE    "My Pulitzer Winner"
-    .AUTHOR   "Joe Blow"
-    .DRAFT     7
-    .REVISION  39
-    \#
-    .DOCTYPE     DEFAULT \"Superfluous; mom uses DOCTYPE DEFAULT by default
-    .PRINTSTYLE  TYPESET
-    .COPYSTYLE   DRAFT
-
-

- -

-Notice the use of the -comment line -( \# ), a handy way to keep groups of macros visually -separated for easy reading in a text editor. -

- -

Step 3

- -

-This step — completely optional — is where you, the user, take -charge. Mom has defaults for everything, -but who's ever satisfied with defaults? Use any of the typesetting macros -here to change mom'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 mom a -PRINTSTYLE -directive before making any such changes. -

- -

-Joe Blow wants his story printed in Helvetica, 12 on 14, rag -right, with -page footers -instead of -page headers -and a single asterisk for the -linebreak -character. None of these requirements conforms -to mom's defaults for the chosen -PRINTSTYLE (TYPESET), so we change them here. -The setup for Joe Blow's story now looks like this: - -

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

- -

Step 4

- -

-The final step in setting up a document is telling -mom to start document processing. It's a -no-brainer, just the single macro START. Other -than PRINTSTYLE, it's the only macro required for -document processing (although I can't guarantee you'll like the -results of using just the two). -

- -

-Here's the complete setup for My Pulitzer Winner: - -

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

- -

-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: - -

-    .TITLE    "My Pulitzer Winner"
-    .AUTHOR   "Joe Blow"
-    .DRAFT     7
-    .REVISION  39
-    \#
-    .PRINTSTYLE  TYPEWRITE
-    .COPYSTYLE   DRAFT
-    \#
-    .START
-
-

- -

-.PRINTSTYLE TYPEWRITE, 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). -

- -

-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: - -

-    .TITLE    "My Pulitzer Winner"
-    .AUTHOR   "Joe Blow"
-    .DRAFT     7
-    .REVISION  39
-    \#
-    .PRINTSTYLE  TYPESET  \"first change
-    .COPYSTYLE   FINAL    \"second change
-    \#
-    .START
-
-

- -

-In the above, .DRAFT 7, .REVISION 39, and .COPYSTYLE -FINAL are actually superfluous. The draft and revision -numbers aren't used when COPYSTYLE is -FINAL, and COPYSTYLE FINAL is -mom'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. -

- -
- - - -

The Reference Macros

 - -

-The reference macros give mom the information -she needs to generate -docheaders, -page headers, -and -covers. -They must go at the top of any file that uses mom's -document processing macros. -

- -

Reference macros list

 - - - - - -
- - - -

-Macro: TITLE "<title string>" ["<2nd line>" ["<3rd line>" ... ] ] -
- -*Arguments must be enclosed in double-quotes -

- -

-The title string can be caps or caps/lower-case; it's up to you. In -PRINTSTYLE TYPESET, -the title will appear in the -docheader -exactly as you typed it. However, mom converts -the title to all caps in -page headers -unless you turn that feature off (see -HEADER_<POSITION>_CAPS). -In -PRINTSTYLE TYPEWRITE, -the title always gets converted to caps. -

- -

-TITLE accepts multiple arguments, each surrounded -by double-quotes. Each argument is printed on a separate line, -permitting you to create multi-line titles in your docheaders. -

- -

-NOTE: If your -DOCTYPE -is CHAPTER, TITLE should be the -title of the opus, not "CHAPTER whatever". -

- - - -
- - - -

-Macro: DOCTITLE "<overall document title>" ["<2nd line>" ["<3rd line>" ... ] ] -
- -*Arguments must be enclosed in double-quotes -

- -

-NOTE: This macro should be used only if your -DOCTYPE -is DEFAULT (which is mom's -default). If your DOCTYPE is -CHAPTER, use -TITLE -to set the overall document title for cover pages, document cover -pages, and page headers or footers. -

- -

-When you're creating a single document, say, an essay or a short -story, you have no need of this macro. -TITLE -takes care of all your title needs. -

- -

-However if you're -collating -a bunch of documents together, say, to print out a report containing -many articles with different titles, or a book of short stories with -different authors, you need DOCTITLE. -

- -

-DOCTITLE tells mom the title -of the complete document (as opposed to the title of each article -or entitled section). -

- -

-The doctitle string can be caps or caps/lower-case; it's up to you. -In -PRINTSTYLE TYPESET, -by default, the doctitle appears in the rightmost position of -page headers, -all in caps unless you turn that feature off (see -HEADER_<POSITION>_CAPS). -In -PRINTSTYLE TYPEWRITE, -the doctitle always gets converted to caps. -

- -

-DOCTITLE accepts multiple arguments, each surrounded -by double-quotes. Each argument is printed on a separate line, -permitting you to create multi-line document titles for use on -Covers -and/or -Doc covers. -

- -

-NOTE: If your -DOCTYPE -is CHAPTER, you don't need -DOCTITLE. TITLE takes care of -everything. -

- - - -
- - - -

-Macro: SUBTITLE [COVER | DOC_COVER] "<subtitle>" ["<2nd line>" ["<3rd line>" ... ] ] -
- -*String arguments must be enclosed in double-quotes -

- -

-The subtitle string can be caps or caps/lower-case. I recommend -caps/lower case. -

- -

-SUBTITLE accepts multiple arguments, each surrounded -by double-quotes. Each argument is printed on a separate line, -permitting you to create multi-line subtitles. -

- -

-If the optional argument, COVER or DOC_COVER, -is given to SUBTITLE, the remaining string -arguments represent the subtitle that will appear on cover or -document cover pages (see the -Introduction to cover pages -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: - -

-    .SUBTITLE "The Docheader Subtitle"
-    .SUBTITLE DOC_COVER "The Document Cover Subtitle"
-    .SUBTITLE COVER "The Cover Subtitle"
-
- -The first invocation of .SUBTITLE 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. -

- -

-If you don't require differing subtitles for doc cover and cover -pages, .SUBTITLE, without the optional first argument, is -sufficient, provided you give the word "SUBTITLE" as an -argument to the macro -DOC_COVER -or -COVER -

- - - - -
- - - -

-Macro: AUTHOR [COVER | DOC_COVER] "<author>" [ "<author2>" ["<author3>" ... ] ] -
- -Alias: EDITOR -
- -*String arguments must be enclosed in double-quotes -

- -

-Each author string can hold as many names as you like, e.g. - -

-    .AUTHOR "Joe Blow"
-        or
-    .AUTHOR "Joe Blow, Jane Doe" "John Hancock"
-
-

- -

-Mom prints each string that's enclosed in -double-quotes on a separate line in the -docheader, -however only the first string appears in -page headers. -If you want mom 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 -header/footer control). -

- -

-The strings can be caps or caps/lower-case. I recommend caps/lower -case. -

- -

-If the optional argument, COVER or DOC_COVER, -is given to AUTHOR, the remaining string -arguments represent the author(s) that will appear on cover or -document cover pages (see the -Introduction to cover pages -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: - -

-    .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)"
-
- -The first invocation of .AUTHOR 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. -

- -

-If you don't require differing authors for doc cover and cover -pages, .AUTHOR, without the optional first argument, is -sufficient, provided you give the word "AUTHOR" as an -argument to the macro -DOC_COVER -or -COVER -

- - - -
- - - -

-Macro: CHAPTER <chapter number> -

- -

-The chapter number can be in any form you like — a digit, a roman -numeral, a word. If you choose -DOCTYPE CHAPTER, -mom prints whatever argument you pass -CHAPTER beside the word "Chapter" as a -single line -docheader. -She also puts the same thing in the middle of -page headers. -

- -

-Please note that if your argument to CHAPTER runs -to more than one word, you must enclose the argument in -double-quotes. -

- -

-If you're not using DOCTYPE CHAPTER, the macro can -be used to identify any document as a chapter for the purpose of -prepending a chapter number to numbered head elements, provided -you pass it a -numeric argument. -See -PREFIX_CHAPTER_NUMBER. -

- - - -

The chapter string

 - -

-If you're not writing in English, you can ask mom -to use the word for "chapter" in your own language by -telling her what it is with the CHAPTER_STRING -macro, like this: - -

-    .CHAPTER_STRING "Chapître"
-
-

- -

-You can also use CHAPTER_STRING if you want -"CHAPTER" instead of "Chapter" in the doc-and -page-headers. -

- - - -
- - - -

-Macro: CHAPTER_TITLE "<chapter title>" ["<2nd line>" ["<3rd line>" ... ] ] -
- -*Arguments must be enclosed in double-quotes -

- -

-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 CHAPTER_TITLE, with -your title enclosed in double-quotes, like this: - -

-    .CHAPTER_TITLE "The DMCA Nazis"
-
-

- -

-CHAPTER_TITLE accepts multiple arguments, each -surrounded by double-quotes. Each argument is printed on a separate -line, permitting you to create multi-line chapter titles in your -docheaders. -

- -

-If you've used -CHAPTER -to give the chapter a number, both "Chapter <n>" and -the chapter title will appear at the top of the chapter, like this: - -

-       Chapter 1
-    The DMCA Nazis
-
-

- -

-In such a case, by default, only the chapter's title will appear in -the -page headers, -not "Chapter <n>". -

- -

-If you omit CHAPTER when setting up your reference -macros, only the title will appear, both at the top of page one and -in subsequent page headers. -

- -

-The style of the chapter title can be altered by -control macros, -e.g. CHAPTER_TITLE_FAMILY, -CHAPTER_TITLE_FONT, etc. The default family, -font and point size are Times Roman, Bold Italic, 4 points larger -than -running text. -

- - - -
- - - -

-Macro: DRAFT <draft number> -

- -

-DRAFT only gets used with -COPYSTYLE DRAFT. -If the COPYSTYLE is FINAL (the -default), mom ignores DRAFT. -DRAFT accepts both alphabetic and numeric -arguments, hence it's possible to do either - -

-    .DRAFT 2
-       or
-    .DRAFT Two
-
-

- -

-Mom prints the argument to .DRAFT (i.e. -the draft number) beside the word "Draft" in the middle -part of -page headers. -

- -

-A small word of caution: If your argument to -.DRAFT is more than one word long, you must enclose the -argument in double-quotes. -

- -

-You may, if you wish, invoke .DRAFT without an -argument, in which case, no draft number will be printed beside -"Draft" in headers or footers. -

- - - -

The draft string

 - -

-If you're not writing in English, you can ask mom -to use the word for "draft" in your own language by -telling her what it is with the DRAFT_STRING macro, -like this: - -

-    .DRAFT_STRING "Jet"
-
-

- -

-Equally, DRAFT_STRING 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 - -

-    .DRAFT alpha-three
-    .DRAFT_STRING "Trial run
-
-

- -

-.DRAFT without an argument, above, ensures that only the -DRAFT_STRING gets printed. -

- -

-NOTE: If you define both a blank .DRAFT -and a blank .DRAFT_STRING, mom skips the -draft field in headers entirely. If this is what you want, this is -also the only way to do it. Simply omitting a .DRAFT and -.DRAFT_STRING will result in mom using -her default, which is to print "Draft <number>". -

- - - -
- - - -

-Macro: REVISION <revision number> -

- -

-REVISION only gets used with -COPYSTYLE DRAFT. -If the COPYSTYLE is FINAL -(the default), mom ignores the -REVISION macro. REVISION accepts -both alphabetic and numeric arguments, hence it's possible to do -either - -

-    .REVISION 2
-       or
-    .REVISION Two
-
-

- -

-Mom prints the revision number beside the shortform -"Rev." in the middle part of -page headers. -

- -

-A small word of caution: If your argument to -.REVISION is more than one word long, you must -enclose the argument in double-quotes. -

- -

-You may, if you wish, invoke .REVISION without an -argument, in which case, no revision number will be printed beside -"Rev." in headers or footers. -

- - - -

The revision string

 - -

-If you're not writing in English, you can ask mom -to use the word for "revision," or a shortform -thereof, in your own language by telling her what it is with the -REVISION_STRING macro, like this: - -

-    .REVISION_STRING "Rév."
-
-

- -

-Additionally, you may sometimes want to make use of -mom's -COPYSTYLE DRAFT -but not actually require any draft information. For example, you -might like mom to indicate only the revision -number of your document. The way to do that is to define an empty -.DRAFT and .DRAFT_STRING in addition to -.REVISION, like this: - -

-    .DRAFT
-    .DRAFT_STRING
-    .REVISION 2
-
-

- -

-Equally, if you want to roll your own solution to what revision -information appears in headers, you could do something like this: - -

-    .DRAFT
-    .DRAFT_STRING
-    .REVISION "two-twenty-two"
-    .REVISION_STRING "Revision"
-
-

- -

-The above, naturally, has no draft information. If you want to roll -your own .DRAFT and/or .DRAFT_STRING as well, -simply supply arguments to either or both. -

- - - -
- - - -

-Macro: COPYRIGHT [COVER | DOC_COVER] "<copyright info>" -
- -*Argument must be enclosed in double-quotes -

- -

-The argument passed to COPYRIGHT is only used on -cover or doc cover pages, and then only if the argument COPYRIGHT is -passed to -COVER -or -DOC_COVER. -Do not include the copyright symbol in the argument passed to -COPYRIGHT; mom puts it in for -you. -

- -

-If the optional argument, COVER or DOC_COVER, -is given to COPYRIGHT, the string argument -represents the copyright information that will appear on cover or -document cover pages (see the -Introduction to cover pages -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: - -

-    .COPYRIGHT DOC_COVER "2006 John Smith and Jane Doe"
-    .COPYRIGHT COVER "2002 Joe Blow"
-
- -The first invocation of .COPYRIGHT establishes the -copyright information that appears on the document cover; the second -establishes the copyright information that appears on the cover -("title") page. -

- -

-If you don't require differing copyright information for doc cover -and cover pages, .COPYRIGHT, without the optional -first argument, is sufficient, provided you give the word -"COPYRIGHT" as an argument to the macro -DOC_COVER -or -COVER -

- - - -
- - - -

-Macro: MISC [COVER | DOC_COVER] "<argument 1>" ["<argument 2>" "<argument 3>" ...] -
- -*String arguments must be enclosed in double-quotes -

- -

-The argument(s) passed to MISC are only used -on cover or doc cover pages, and then only if the argument -MISC is passed to -COVER -or -DOC_COVER. -MISC can contain any information you like. Each -argument appears on a separate line at the bottom of the cover or -doc cover page. -

- -

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

-    .MISC "Music History 101" "Professor Hasbeen" "Dec. 24, 2006"
-
- -and the information would appear on the essay's cover page. -

- -

-If the optional argument, COVER or DOC_COVER, -is given to MISC, the string arguments represent -the miscellaneous information that will appear on cover or document -cover pages (see the -Introduction to cover pages -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: - -

-    .MISC DOC_COVER "Music History 101" "Professor Hasbeen"
-    .MISC COVER "Spring Term Paper"
-
- -The first invocation of .MISC establishes the -miscellaneous information that appears on the document cover; the -second establishes the miscellaneous information that appears on the -cover ("title") page. -

- -

-If you don't require differing miscellaneous information for doc -cover and cover pages, .MISC, without the optional first -argument, is sufficient, provided you give the word "MISC" -as an argument to the macro -DOC_COVER -or -COVER -

- - - -
- - - -

-Macro: COVERTITLE "<user defined cover page title>" ["<2nd line>" ["<3rd line>" ... ] ] -
- - - -Macro: DOC_COVERTITLE "<user defined document cover page title>" ["<2nd line>" ["<3rd line>" ... ] ] -
- -*Arguments must be enclosed in double-quotes -

- -

-The arguments passed to COVERTITLE or -DOC_COVERTITLE are only used on cover or doc cover -pages, and then only if the argument COVERTITLE is passed to -COVER -or -DOC_COVER. -

- -

-The only time you require a COVERTITLE or -DOC_COVERTITLE is when none of the required first -arguments to COVER or DOC_COVER -fits your needs for the title you want to appear on cover (or doc -cover) pages. -

- -

-COVERTITLE and DOC_COVERTITLE -accept multiple arguments, each surrounded by double-quotes. Each -argument is printed on a separate line, permitting you to create -multi-line titles on your cover and/or doc cover pages. -

- -
- - - -

The Docstyle Macros

 - -

-The docstyle macros tell mom 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. -

- -

Docstyle macros list

 - - - - - -
- - - -

-Macro: DOCTYPE DEFAULT | CHAPTER | NAMED "<name>" | LETTER -

- -

-The arguments DEFAULT, CHAPTER and -NAMED tell mom what to put in the -docheader -and -page headers. -LETTER tells her that you want to write a letter. -

- -

-Mom's default DOCTYPE is -DEFAULT. If that's what you want, you don't -have to give a DOCTYPE command. -

- -

DEFAULT

- -

-DEFAULT prints a -docheader -containing the title, subtitle and author information given to the -reference macros, -and page headers with the author and title. -(See -Default specs for headers -for how mom outputs each part of the page header.) -

- -

CHAPTER

- -

-CHAPTER prints "Chapter <n>" in place of a -docheader -(<n> is what you gave to the -reference macro -CHAPTER). -If you give the chapter a title with -CHAPTER TITLE, -mom prints "Chapter <n>" and the -title underneath. If you omit the -CHAPTER -reference macro but supply a -CHAPTER_TITLE, -mom prints only the chapter title. (*For -backward compatibility with pre-1.1.5 versions of -mom, you can also supply a chapter title by -omitting the CHAPTER reference macro and -supplying a chapter title with -CHAPTER_STRING.) -

- -

-The page headers in DOCTYPE CHAPTER contain the author, -the title of the book (which you gave with -TITLE), -and "Chapter <n>" (or the chapter title). See -Default Specs for Headers -for mom's default type parameters for each part of -the page header. -

- -

NAMED

- -

-NAMED takes an additional argument: a name -for this particular kind of document (e.g. outline, synopsis, -abstract, memorandum), enclosed in double-quotes. -NAMED is identical to DEFAULT -except that mom prints the argument to -NAMED beneath the -docheader, -as well as in page headers. -(See -Default specs for headers -for how mom outputs each part of the page header.) -

- -

-Additionally, if you wish the name of this particular kind of -document to be coloured, you can pass DOCTYPE NAMED -a third (optional) argument: the name of a colour pre-defined (or -"initialized") with -NEWCOLOR -or -XCOLOR. -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 DOCTYPE entry would look like: - -

-    .DOCTYPE NAME "Warning" red
-
-

- -

-By default, the string passed to DOCTYPE NAMED is -underlined in the docheader, and on document-cover pages and cover -("title"") pages. (See the -Introduction to covers -for the difference between "doc cover" and "cover" -pages.) -

- -
The DOCTYPE_UNDERLINE macro
 - -

-Formerly, this underlining was carved in stone. As of version -1.5 of mom, you can now use the macro -DOCTYPE_UNDERLINE to set the weight of the -underline and its distance from the doctype-name in the -docheader (doc covers and covers handle underlining of the -doctype-name differently; see -COVER_UNDERLINE), -or simply toggle doctype underlining on or off. -Mom's default is to underline the doctype-name. -

- -

-The order of arguments is weight, optionally followed by -gap, where "gap" is the distance from the -baseline -of the doctype-name to the underline. -

- -

-The weight argument is given in points, or fractions -thereof, and must NOT have the -unit of measure, -p, appended. Like -RULE_WEIGHT, -weights MUST be greater than 0 and less than 100. -Mom's default for head underlines is 1/2 point. -

- -

-The gap 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. Mom's default -gap for named-doctype underlines is 2 points. -

- -

-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: - -

-    .DOCTYPE_UNDERLINE 2 3p
-
- -If you wanted the same thing, but were content with -mom's default gap of 2 points, - -
-    .DOCTYPE_UNDERLINE 4
-
- -would do the trick. -

- -

-If you merely want to toggle the underlining of the doctype-name -in docheaders on or off, invoke .DOCTYPE_UNDERLINE by -itself to turn the underlining on, or .DOCTYPE_UNDERLINE -OFF (or NO, X, etc.) -

- -

-Please note that if you supply a weight to -DOCTYPE_UNDERLINE, and optionally a gap, you also -turn the underlining of the doctype-name in docheaders on; if this -is not what you want, you must turn head underlining off manually -afterwards. -

- -

LETTER

- -

-LETTER tells mom you're writing a letter. See -the section -Writing Letters -for instructions on using mom to format letters. -

- - - -
- - - -

-Macro: PRINTSTYLE TYPESET | TYPEWRITE [ SINGLESPACE ] -
- -*Required for document processing -
- -*Must come before any changes to default document style -

- -

-PRINTSTYLE tells mom whether to typeset -a document, or to print it out "typewritten, doubled-spaced". -

- -

-THIS MACRO MAY NOT BE OMITTED. In order for -document processing to take place, mom requires -a PRINTSTYLE. If you don't give one, -mom will warn you on stderr and print a single -page with a nasty message. -

- -

-Furthermore, PRINTSTYLE must come before any -changes to mom's default typestyle parameters. -(This applies primarily to, but is by no means restricted to, -PRINTSTYLE TYPESET.) PRINTSTYLE -sets up complete "templates" that include default -papersize, margins, family, fonts, point sizes, and so on. -Therefore, changes to any aspect of document style must come -afterwards. -

- -

-TYPESET, as the argument implies, typesets -documents (by default in Times Roman; see -TYPESET defaults). -You have full access to all the -typesetting macros -as well as the -style control macros -of document processing. -

- -

-As mentioned above, PRINTSTYLE TYPESET must come -before any changes to mom's default typographic -settings. For example, - -

-    .PAPER A4
-    .LS 14
-    .PRINTSTYLE TYPESET
-
- -will not changes mom's default paper size to A4, -nor her default document leading 14 points, whereas - -
-    .PRINTSTYLE TYPESET
-    .PAPER A4
-    .LS 14
-
- -will. -

- -

-With TYPEWRITE, mom does her best -to reproduce the look and feel of typewritten, double-spaced copy (see -TYPEWRITE defaults). -Control macros -and -typesetting macros -that alter family, font, point size, and -leading -are (mostly) ignored. An important exception is -HEADER_SIZE -(and, by extension, FOOTER_SIZE), which allows -you to reduce the point size of headers/footers should they become -too crowded. Most of mom's inlines affecting the -appearance of type are also ignored (\*S is an exception; -there may be a few others). -

- -

-In short, TYPEWRITE never produces effects -other than those available on a typewriter. Don't be fooled by -how brainless this sounds; mom is remarkably -sophisticated when it comes to conveying the typographic sense of a -document within the confines of TYPEWRITE. -

- -

-The primary uses of TYPEWRITE 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 TYPEWRITE to -TYPESET and print out a copy. -

- -

-If, for some reason, you would prefer the output -of TYPEWRITE single-spaced, pass -PRINTSTYLE TYPEWRITE the optional argument, -SINGLESPACE. -

- -

-If you absolutely must have a leading other than typewriter double- -or singlespaced, the only way to get it is with the -DOC_LEAD -macro, and then ONLY if DOC_LEAD is set -before you invoke the .START -macro. -

- -

TYPESET defaults

 - -
-    Family            = Times Roman
-    Point size        = 12.5
-    Paragraph leading = 16 points, adjusted
-    Fill mode         = justified
-    Hyphenation       = enabled
-                        max. lines = 2
-                        margin = 36 points
-                        interword adjustment = 1 point
-    Kerning           = enabled
-    Ligatures         = enabled
-    Smartquotes       = enabled
-    Word space        = groff default
-    Sentence space    = 0
-
- -

TYPEWRITE defaults

 - -
-    Family            = Courier
-    Italics           = underlined
-    Point size        = 12
-    Paragraph leading = 24 points, adjusted; 12 points for SINGLESPACE
-    Fill mode         = left
-    Hyphenation       = disabled
-    Kerning           = disabled
-    Ligatures         = disabled
-    Smartquotes       = disabled
-    Word space        = groff default
-    Sentence space    = groff default
-    Columns           = ignored
-
- -

PRINTSTYLE TYPEWRITE control macros

 - -

-In PRINTSTYLE TYPEWRITE, mom, -by default, underlines anything that looks like italics. This -includes the -\*[SLANT] -inline escape -for pseudo-italics. -

- -

-If you'd prefer that mom 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 -.ITALIC_MEANS_ITALIC and .SLANT_MEANS_SLANT. -Neither requires an argument. -

- -

-Although it's unlikely, should you wish to reverse -the sense of these macros in the midst of a document, -.UNDERLINE_ITALIC and .UNDERLINE_SLANT restore -underlining of italics and pseudo-italics. -

- - - -

-Additionally, by default, mom underlines -quotes -(but not -blockquotes) -in PRINTSTYLE TYPEWRITE. -If you don't like this behaviour, turn it off with - -

-    .UNDERLINE_QUOTES OFF
-
-

- -

-To turn underlining of quotes back on, use -UNDERLINE_QUOTES without an argument. -

- -

-While most of the -control macros -have no effect on PRINTSTYLE TYPEWRITE, there -is an important exception: -HEADER_SIZE -(and by extension, FOOTER_SIZE). This is -particularly useful for reducing the point size of -headers/footers should they become crowded (quite likely to -happen if the title of your document is long and your -COPYSTYLE -is DRAFT). -

- - - -
- - - -

-Macro: COPYSTYLE DRAFT | FINAL -

- -

-Mom's default COPYSTYLE is -FINAL, so you don't have to use this macro unless -you want to. -

- -

-COPYSTYLE DRAFT exhibits the following behaviour: - -

    -
  1. documents start on page 1, whether or not you - request a different starting page number with - PAGENUMBER -
    2. -
  2. page numbers are set in lower case roman numerals
    3. -
  3. the draft number supplied by - DRAFT - and a revision number, if supplied with - REVISION - (see - reference macros), - appear in the centre part of - page headers - (or footers, depending on which you've selected) along with - any other information that normally appears there. -
    4. -
-

- -

-IMPORTANT: If you define your own centre part for page -headers with -HEADER_CENTER, -no draft and/or revision number will appear there. If you want draft -and revision information in this circumstance, use -DRAFT_WITH_PAGENUMBER. -

- -

-COPYSTYLE FINAL differs from DRAFT in that: - -

    -
  1. it respects the starting page number you give the document
    2. -
  2. page numbers are set in normal (Arabic) digits
    3. -
  3. no draft or revision number appears in the page headers
    4. -
-

- -

-NOTE: -The centre part of page headers can get crowded, -especially with -DOCTYPE CHAPTER -and -DOCTYPE NAMED, -when the COPYSTYLE is DRAFT. -Three mechanisms are available to overcome this problem. One is to -reduce the overall size of headers (with -HEADER_SIZE). -Another, which only works with -PRINTSTYLE TYPESET, -is to reduce the size of the header's centre part only (with -HEADER_CENTER_SIZE). -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 -DRAFT_WITH_PAGENUMBER). -

- -
- - - -

Initiate document processing

 - -

-In order to use mom's document element macros -(tags), you have to tell her you want them. The macro to do this is -START. -

- -

-START collects the information you gave -mom in the setup section at the top of your file (see -Tutorial — setting up a mom document), -merges it with her defaults, sets up headers and page numbering, -and prepares mom to process your document using -the document element tags. No document processing takes place until -you invoke .START. -

- - - -
- - - -

-Macro: START -
- -*Required for document processing. -

- -

-START takes no arguments. It simply instructs -mom to begin document processing. If you don't -want document processing (i.e. you only want the -typesetting macros), -don't use START. -

- -

-At a barest minimum before START, you must enter a -PRINTSTYLE -command. -

- -
- - - -

Changing global typesetting and formatting parameters before START

 - -

-In the third (optional) part of setting up a document (see -Tutorial — setting up a mom document), -you can use the -typesetting macros -to change mom's document-wide defaults for margins, -line length, family, base point size, -leading, -and justification style. -

- -

-Two additional style concerns have to be addressed here (i.e. in -macros before -START): -changes to the -docheader, -and whether you want you want the document's nominal leading -adjusted to fill pages fully to the bottom margin. -

- - - -
- -

Using the typesetting macros before START

 - -

-From time to time (or maybe frequently), you'll want the overall -look of a document to differ from mom's defaults. -Perhaps you'd like her to use a different -family, -or a different overall -leading, -or have different left and/or right page margins. -

- -

-To accomplish such alterations, use the appropriate -typesetting macros -(listed below) after -PRINTSTYLE -and before -START. -

- -

-More than one user has, quite understandably, not fully grasped -the significance of the preceding sentence. The part they've missed -is "after PRINTSTYLE". -

- -

-Changes to any aspect of the default look and/or formatting -of a mom document must come after -PRINTSTYLE. For example, it might seem natural to -set up page margins at the very top of a document with - -

-    .L_MARGIN 1i
-    .R_MARGIN 1.5i
-
-

- -

-However, when you invoke .PRINTSTYLE, those margins -will be overridden. The correct place to set margins — and -all other changes to the look of a document — is after -PRINTSTYLE. -

- -

-NOTE: Don't use the macros listed in -Changing document-wide typesetting parameters after START -prior to START; they are exclusively for use -afterwards. -

- -

-When used before START, the -typesetting macros -(below) have the following meanings: - -

-    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 FOOTER MARGIN AND BOTTOM MARGIN for an important warning
- **See DOC_LEAD_ADJUST
-***See Special note
-
-

- -

-Other macros that deal with type style, or refinements thereof -(KERN, LIGATURES, HY, WS, SS, etc.), behave normally. -It is not recommended that you set up tabs or indents prior to -START. -

- -

-If you want to change any of the basic parameters (above) -after START and have them affect a -document globally (as if you'd entered them before -START), you must use the macros listed in -Changing document-wide style parameters after START. -

- -

Special note on LEFT, RIGHT and CENTER prior to START

 - -

-In a word, these three macros have no effect on document processing -when invoked prior to START. -

- -

-All mom's document element tags -(PP, HEAD, -BLOCKQUOTE, FOOTNOTE, etc.) -except -QUOTE -set a -fill mode -as soon as they're invoked. If you wish to turn fill mode off for -the duration of any tag (with -LEFT, RIGHT or CENTER) -you must do so immediately after invoking the tag. Furthermore, -the change affects only the current invocation of the tag. -Subsequent invocations of the same tag for which you want the same -change require that you invoke .LEFT, .RIGHT -or CENTER immediately after every invocation of the tag. -

- - - -
- -

Including (sourcing) style sheets and files

 - -

-If you routinely make the same changes to mom'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 -mom documents with the macro, -INCLUDE. The right place for such style sheets is -after -PRINTSTYLE -and before -START -

- -

-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 head_template, in which you'd place the pertinent -HEAD control macros. - -

-    .HEAD_FAMILY    H
-    .HEAD_FONT      BI
-    .HEAD_QUAD      L
-    .HEAD_UNDERLINE OFF
-
- -Then, in the preliminary document set-up section of your main file, -you'd include the style sheet, or template, like this: - -
-    .TITLE      "Sample Document
-    .AUTHOR     "Joe Blow
-    .PRINTSTYLE TYPESET
-    \#
-    .INCLUDE    head_template
-    \#
-    .START
-
- -The blank comment lines ( \# ) aren't -required, but they do make your file(s) easier to read. -

- -

-If the file to be included is in the same directory as the file -you're working, you simply enter the filename after -.INCLUDE. 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 /home/joe/stories and your -style-sheet is in /home/joe/style_sheets, the above -example would have to look like this: - -

-    .TITLE      "Sample Document
-    .AUTHOR     "Joe Blow
-    .PRINTSTYLE TYPESET
-    \#
-    .INCLUDE    /home/joe/style_sheets/head_template
-    \#
-    .START
-
-

- -

-INCLUDE is not restricted to style sheets -or templates. You can include any file at any point into a -document, provided the file contains only text and valid groff or -mom formatting commands. Neither is -INCLUDE restricted to use with -mom's document processing macros. You can use it -in plain typeset documents as well. -

- -

-EXPERTS: INCLUDE is an alias for the groff -request, .so. Mix 'n' match with impunity. -

- - - -
- -

Initializing colours

 - -

-Although it doesn't really matter where you define/initialize -colours for use in document processing (see -NEWCOLOR -and -XCOLOR -in the section -Coloured text), -I recommend doing so before you begin document processing with -START. -

- -

-The macro, -COLOR, -and the -inline escape, -\[<colorname>], -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 -document element control macros. -

- -

-PLEASE NOTE: If you plan to have mom -generate a -table of contents, -do NOT embed colour -inline escapes -(\[<colorname>]) -in the -string arguments -given to any of the -reference macros, -nor in the string arguments given to -HEAD, -SUBHEAD -or -PARAHEAD. -Use, rather, the -control macros -mom provides to automatically colourize these -elements. -

- - - -
- -

Adjust a document's leading to fill pages

 - -

-Macro: DOC_LEAD_ADJUST toggle -
- -*Must come after LS or AUTOLEAD and before START -

- -

-DOC_LEAD_ADJUST is a special macro to adjust -document -leading -so that bottom margins fall precisely where you expect. -

- -

-If you invoke .DOC_LEAD_ADJUST, mom -takes the number of lines that fit on the page at your requested -leading, then incrementally adds -machine units -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 mom's default. -

- -

-Should you NOT want adjusted document leading, you MUST turn it -off manually, like this: - -

-    .DOC_LEAD_ADJUST OFF
-
-

- -

-If you set the document leading prior to START -with -LS -or -AUTOLEAD, -DOC_LEAD_ADJUST OFF must come afterwards, like -this: - -

-    .LS 12
-    .DOC_LEAD_ADJUST OFF
-
-

- -

-In this scenario, the maximum number of lines that fit on a page at -a -leading -of 12 -points -determine where mom ends -a page. The effect will be that last lines usually fall (slightly) -short of the "official" bottom margin. -

- -

-In -PRINTSTYLE -TYPEWRITE, the leading is always adjusted and -can't be turned off. -

- -

-NOTE: DOC_LEAD_ADJUST, if -used, must be invoked after -LS -or -AUTOLEAD -and before -START -

- -

-ADDITIONAL NOTE: Even if you disable -DOC_LEAD_ADJUST, mom will still -adjust the leading of endnotes pages and toc pages. See -ENDNOTE_LEAD -and -TOC_LEAD -for an explanation of how to disable this default behaviour. -

- - - -
- -

Managing the docheader

 - -

-Macro: DOCHEADER <toggle> [ distance to advance from top of page ] -
- -*Must come before START; distance requires a unit of measure -

- -

-By default, mom prints a -docheader -on the first page of any document (see -below -for a description of the docheader). If you don't want a docheader, -turn it off with - -

-    .DOCHEADER OFF
-
-

- -

-DOCHEADER is a toggle macro, so the argument doesn't -have to be OFF; it can be anything you like. -

- -

-If you turn the docheader off, mom, by default, starts -the running text of your document on the same top -baseline -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. - -

-    .DOCHEADER OFF 1.5i
-
-

- -

-This starts the document 1.5 inches from the top of the page PLUS -whatever spacing adjustment mom has to make in -order to ensure that the first baseline of running text falls on a -"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 -baseline -of the first line of type. -

- -

-TIP: Since no document processing happens until -you invoke -.START -— including anything to do with docheaders — you can -typeset your own docheader prior to START (if -you don't like the way mom does things) and use -DOCHEADER OFF 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 .PSPIC; see the -groff_tmac man page for usage). -

- - - -

How to change the look of docheaders: docheader control macros

 - -

-With -PRINTSTYLE TYPEWRITE, -the look of docheaders is carved in stone. -In -PRINTSTYLE TYPESET, -however, you can make a lot of changes. Macros that alter docheaders -MUST come before -START. -

- - - -

-A typeset docheader has the following characteristics. Note that -title, subtitle, author, and document type are what you supply -with the -reference macros. -Any you leave out will not appear; mom will -compensate: - -

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

- -

-If the -DOCTYPE -is CHAPTER, - -

-       Chapter <n>       bold, 4 points larger than running text
-      Chapter Title      bold italic, 4 points larger than running text
-
-

- -

-The -family -is the prevailing family of the whole document. -

- -

-NOTE: If your DOCTYPE is -CHAPTER and you have both "Chapter -<n>" and a "Chapter Title" (as above), -mom inserts a small amount of whitespace between -them, equal to one-quarter of the -leading -in effect. If this doesn't suit you, you can alter the space -by including the -inline escapes, -\*[UP] -or -\*[DOWN], -in the argument you pass to -CHAPTER_TITLE, -like this: - -

-    .CHAPTER_TITLE "\*[DOWN 2p]Why Not Patent Calculus?"
-        or
-    .CHAPTER_TITLE "\*[UP 2p]Why Not Patent Calculus?"
-
-

- -

The docheader macros to:

 - -
    -
  1. Change the starting position of the docheader
    2. -
  2. Change quad direction the entire docheader
    3. -
  3. Change the family of the entire docheader
    4. -
  4. Adjust the docheader leading
    5. -
  5. Change the family of individual docheader elements
    6. -
  6. Change the font of docheader elements
    7. -
  7. Change the colour of the docheader
    8. -
  8. Adjust the size of docheader elements
    9. -
  9. Change the attribution string ("by")
    10. -
- -
1. Change the starting position
 - -

-By default, a docheader starts on the same -baseline -as -running text. -If you'd like it to start somewhere else, use the macro -.DOCHEADER_ADVANCE and give it the distance you want -(measured from the top edge of the paper to the first baseline -of the docheader), like this: - -

-    .DOCHEADER_ADVANCE 4P
-
- -A -unit of measure -is required. -

- -

-NOTE: If -HEADERS -are OFF, mom's normal top -margin for -running text -(7.5 -picas) -changes to 6 picas (visually approx. 1 inch). Since the -first baseline of the docheader falls on the same baseline -as the first line of running text (on pages after page 1), -you might find the docheaders a bit high when headers are off. -Use -DOCHEADER_ADVANCE -to place them where you want. -

- -
2. Change the quad direction of the docheader
 - -

-By default, mom centers the docheader. -If you'd prefer to have your docheaders set flush left or right, or -need to restore the default centering, -invoke .DOCHEADER_QUAD with the quad direction you want, -either LEFT (or L), RIGHT (or -R) or CENTER (or C). -

- -
3. Change the family of the entire docheader
 - -

-By default, mom sets the docheader in the same -family used for -running text. -If you'd prefer to have your docheaders set in a different family, -invoke .DOCHEADER_FAMILY with the family you want. -The argument for DOCHEADER_FAMILY is the same as -for -FAMILY. -

- -

-For example, mom'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, - -

-    .DOCHEADER_FAMILY H
-
- -is how you'd do it. -

- -

-Please note that if you use DOCHEADER_FAMILY, -you can still alter the family of individual parts of the docheader -with the macros listed -here. -

- -
4. Adjust the leading
 - -

-The -leading -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: - -

-    .DOCHEADER_LEAD +2
-
-

- -

-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 -unit of measure -is required; points is assumed. -

- -
5. Change the family of docheader elements
 - -

-The following macros let you change the -family -of each docheader element separately: - -

-

- -

-Simply pass the appropriate macro the family you want, just as you -would with -FAMILY. -

- -
6. Change the font of docheader elements
 - -

-The following macros let you change the -font -of each docheader element separately: - -

-

- -

-Simply pass the appropriate macro the font you want. R, B, -I and BI have the same meaning as they do for -FT. -

- -
7. Change the colour of the docheader elements individually
 - -

-The following macros let you change the color of each docheader -element separately. You must pre-define (or -"initialize") the color with -NEWCOLOR -or -XCOLOR. - -

-

- -

-It is not recommended that you embed colour (with the -inline escape, -\*[<colorname>]) -in the strings passed to -TITLE, CHAPTER_TITLE, -SUBTITLE, AUTHOR or the name you -give DOCTYPE NAMED. The strings passed to these -macros are used to generate page -headers -and -footers. -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.) -

- - - -

-If you want to colourize the entire docheader, use the macro - -

-

- -
8. Adjust the size of docheader elements
 - -

-The following macros let you adjust the point size of each docheader -element separately. -

- -

-Mom calculates the point size -of docheader elements from the point size of paragraphs in running -text, so you must prepend a + or - sign to the argument. Points is -assumed as the -unit of measure, -so there's no need to append a unit to the argument. Fractional point -sizes are allowed. -

- - - -

-Simply pass the appropriate macro the size adjustment you want. -

- -
9. Change the attribution string ("by")
 - -

-If you're not writing in English, you can change what -mom prints where "by" appears in -docheaders. For example, - -

-    .ATTRIBUTE_STRING "par"
-
- -changes "by" to "par". ATTRIBUTE_STRING -can also be used, for example, to make the attribution read -"Edited by". -

- -

-If you don't want an attribution string at all, simply pass -ATTRIBUTE_STRING an empty argument, like this: - -

-    .ATTRIBUTE_STRING ""
-
-

- -

-Mom will deposit a blank line where the -attribution string normally appears. -

- -

-If the optional argument, COVER or DOC_COVER, -is given to ATTRIBUTE_STRING, the string argument -represents the attribution string that will appear on cover or -document cover pages (see the -Introduction to cover pages -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: - -

-    .ATTRIBUTE_STRING ""
-    .ATTRIBUTE_STRING DOC_COVER "Edited by"
-    .ATTRIBUTE_STRING COVER "by"
-
- -The first invocation of .ATTRIBUTE_STRING 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. -

- -

-If you don't require differing attribute strings for doc -cover pages, cover pages, or the first-page docheader, -.ATTRIBUTE_STRING, without either of the optional first -arguments, is sufficient. -

- -

-NOTE: 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 -inline escapes -in the argument to ATTRIBUTE_STRING. For -example, - -

-    .ATTRIBUTE_STRING "\f[HBI]\*[SIZE -2p] by \*[SIZE +2p]\*[PREV]"
-
- -would set "by" in Helvetica bold italic, 2 points -smaller than normal. -

- - - -
- -

Setting documents in columns

 - -

-Setting documents in columns is easy with mom. (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 -gutters). -That's it. Mom takes care of everything else, from -soup to nuts. -

- -

Some words of advice

- -

-If you want your type to achieve a pleasing -justification -or -rag -in columns, reduce the point size of type (and probably the -leading -as well). Mom's default document point -size is 12.5, which works well across her default 39 -pica -full page line length, but with even just two columns on a page, -the default point size is awkward to work with. -

- -

-Furthermore, you'll absolutely need to reduce the indents for -epigraphs, -quotes, -and -blockquotes -(and probably the -paragraph first-line indent -as well). -

- - - -
- - - -

-Macro: COLUMNS <number of columns> <width of gutters> -
- -*Should be the last macro before START -
- -The second argument requires a unit of measure -

- -

-COLUMNS takes two arguments: the number of -columns you want on document pages, and the width of the -gutter -between them. For example, to set up a page with two columns -separated by an 18 point gutter, you'd do - -

-    .COLUMNS 2 18p
-
-

- -

-Nothing to it, really. However, as noted above, -COLUMNS should always be the last document -setup macro prior to -START. -

- -

-NOTE: Mom ignores columns completely -when the -PRINTSTYLE -is TYPEWRITE. The notion of typewriter-style -output in columns is just too ghastly for her to bear. -

- -

Using tabs when COLUMNS are enabled

- -

-Mom's tabs -(both -typesetting tabs -and -string tabs) -behave as you'd expect during document processing, even when -COLUMNS are enabled. Tab structures set up -during document processing carry over from page to page and column -to column. -

- - - -

Breaking columns manually

 - -

-Mom takes care of breaking columns when they reach -the bottom margin of a page. However, there may be times you want to -break the columns yourself. There are two macros for breaking columns -manually: COL_NEXT and COL_BREAK. -

- - - -

-.COL_NEXT breaks the line just before it, -quads -it left (assuming the type is justified or quad left), and moves over -to the top of the next column. If the column happens to be the last -(rightmost) one on the page, mom starts a new page -at the "column 1" position. This is the macro to use when -you want to start a new column after the end of a paragraph. -

- - - -

-.COL_BREAK is almost the same, except that -instead of breaking and quadding the line preceding it, -she breaks and spreads it (see -SPREAD). -Use this macro whenever you need to start a new column in the middle -of a paragraph. -

- -

-If you need COL_BREAK in the middle of a blockquote -or (god help you) an epigraph, you must do the following in order for -COL_BREAK to work: - -

-    .SPREAD
-    \!.COL_BREAK
-
-

- -
- - - -

Changing global style parameters after START

 - -

-In the normal course of things, you change the basic type -parameters of a document before -START, -using -typesetting macros -(L_MARGIN, FAMILY, PT_SIZE, LS, etc). After -START, you MUST use the following macros to make -global changes to the basic type parameters of a document. -

- -

Macro list

 - - - - - -
- - - -

-Macro: DOC_LEFT_MARGIN <left margin> -
- -*Requires a unit of measure -

- - - - - -
- - - -

-Macro: DOC_RIGHT_MARGIN <right margin> -
- -*Requires a unit of measure -

- - - - - -
- - - -

-Macro: DOC_LINE_LENGTH <length> -
- -*Requires a unit of measure -

- - - - - -
- - - -

-Macro: DOC_FAMILY <family> -

- - - - - -
- - - -

-Macro: DOC_PT_SIZE <point size> -
- -*Does not require a unit of measure; points is assumed -

- - - - - -
- - - -

-Macro: DOC_LEAD <points> [ ADJUST ] -
- -*Does not require a unit of measure; points is assumed -

- - - -

-IMPORTANT: Do not use DOC_LEAD -in the middle of a page! It should always and only be invoked -immediately prior to a new page, like this: - -

-    .DOC_LEAD <new value>
-    .NEWPAGE
-
-

- -

-NOTE: Even if you don't pass -DOC_LEAD the optional argument -ADJUST, mom will still adjust the -leading of endnotes pages and toc pages. See -ENDNOTE_LEAD -and -TOC_LEAD -for an explanation of how to disable this default behaviour. -

- - - -
- - - -

-Macro: DOC_QUAD L | R | C | J -

- - - -
- -

-Next   -Prev   -Top   -Back to Table of Contents -

- - - - - diff --git a/contrib/mom/momdoc/goodies.html b/contrib/mom/momdoc/goodies.html deleted file mode 100644 index e809dde2..00000000 --- a/contrib/mom/momdoc/goodies.html +++ /dev/null @@ -1,1517 +0,0 @@ - - - - - - -Mom -- Goodies - - - - - - - -

-Next   -Prev   -Back to Table of Contents -

- -

Goodies

 - -

-The macros in this section are a collection of useful (and sometimes -nearly indispensable) routines to simplify typesetting. -

- -

Goodies list

 - - - - - -
- -

Rename macros

 - -

-Macro: ALIAS <new name> <old name> -

- -

-The ALIAS macro may well be your best friend. -With it, you can change the name of a macro to anything you -like (provided the new name is not already being used by -mom; see the -list of reserved words). -

- -

-Groff has always been a bit intimidating for new users because -its standard macro packages use very terse macro names. -Mom 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, -mom knows that people have their own ways of -thinking, their own preferences, their own habits. Some of her -macro names may not suit you; they might be too long, or aren'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. -

- -

-If you don't like one of mom's macro names, -say, PAGEWIDTH, change it, like this: - -

-    .ALIAS PW PAGEWIDTH
-           |      |
-      new__|      |__official
-     name            name
-
-

- -

-The first argument to ALIAS is the new name you -want for a macro. The second is the "official" name by -which the macro is normally invoked. After ALIAS, -either can be used. -

- -

-Note that in ALIAS, you do NOT include the period -(dot) that precedes the macro when it's a -control line. -

- -

-Tip: A particularly good candidate for -ALIAS is the macro, -PT_SIZE. -A more natural name for it (at least to old-school phototypesetters) -would simply be PS, but PS conflicts with the eqn -equation preprocessor and thus mom uses the longer -form. However, if you're not using eqn, you can -happily rename PT_SIZE to PS: - -

-    .ALIAS PS PT_SIZE
-
-

- -

-NOTE: If you use ALIAS a lot, and -always for the same things, consider creating an aliases file of the -form - -

-    .ALIAS <new name> <old name>
-    .ALIAS <new name> <old name>
-    .ALIAS <new name> <old name>
-    ...etc
-
- -Put the file someplace convenient and source it (include it) at the -beginning of your documents with the -INCLUDE -macro. Assuming that you've created an aliases file -called mom_aliases in your home directory under -a directory called Mom, you'd source it by placing - -
-    .INCLUDE /home/<username>/Mom/mom_aliases
-
- -at the top of your documents. -

- -

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

- -

-EXPERTS: ALIAS is an alias -of .als. You can use either, or mix 'n' match with -impunity. -

- - - -
- -

Hide input lines from output

 - -

-Macro: SILENT toggle -
- -Alias: COMMENT -

- -

-Sometimes, you want to "hide" -input lines -from final output. This is most likely to be the case when setting -up string tabs (see the -quickie tutorial on string tabs -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 SILENT macro. -

- -

-SILENT is a toggle. Invoking it without an argument -turns it on; any argument turns it off. E.g., - -

-    .SILENT
-    A line of text
-    .SILENT OFF
-
-

- -

-The line "A line of text" will not appear in the -output copy. -

- -

-SILENT is aliased as COMMENT. -If you want to insert non-printing comments into your documents, -you may prefer this. -

- -

-NOTE: SILENT does not automatically break an -input line -(see -BR) -when you're in one of the -fill modes -(JUSTIFY -or -QUAD L | R | C | J). -The same applies to tabs -(typesetting -or -string) -to which you've passed the J or -QUAD argument. You must insert .BR -yourself, or risk a portion of your text disappearing into a black -hole. -

- - - -
- -

Suspend/re-invoke traps

 - -

-Macro: TRAP toggle -

- -

-Traps are vertical positions on the output page at which you or -mom have instructed groff to start doing something -automatically. Commonly, this is near the bottom of the page, where -automatic behind-the-scenes processing is needed in order for one -page to finish and another to start. -

- -

-Sometimes, traps get sprung when you don't want them. If this -happens, surround just the offending macros and input lines with - -

-    .TRAP OFF
-    ...
-    .TRAP
-
-

- -

-TRAP is a toggle, therefore any argument -turns it off (i.e. suspends the trap), and no argument turns it -(back) on. -

- - - -
- -

Convert typewriter doublequotes to proper doublequotes

 - -

-Macro: SMARTQUOTES [<off>] [ ,, | >> | << ] -
- -or -
- -Macro: SMARTQUOTES DA | DE | ES | FR | IT | NL | NO | PT | SV -

- -

-If you invoke SMARTQUOTES without an argument, -mom converts all instances of the inch-mark, -(" — also called a "doublequote"), into -the appropriate instances of true Anglo-American open-and -close-doublequotes. (See -Internationalization -for how to get SMARTQUOTES to behave correctly for non-English -quoting styles.) -

- -

-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? -

- -

Internationalization

 - -

-If you invoke SMARTQUOTES with one of the -optional arguments (,, or >> -or <<) you can use " as -"cheap" open-and close-quotes when inputting text in a -language other than English, and have mom convert -them, on output, into the chosen open-and close-quote style. -

- -

-,, opens quotes with "lowered doublequotes" and -closes them with "raised doublequotes", as in this ascii -approximation: - -

-    ,,Hilfe !``
-
- ->> opens quotes with guillemets pointing to the -right, and closes them with guillemets pointing to the left, as in -this ascii approximation: - -
-    >>Zurück !<<
-
-

- -

-<< opens quotes with guillemets pointing to the -left, and closes them with guillemets pointing to the right, as in -this ascii approximation: - -

-    <<Mais monsieur! Je ne suis pas ce genre de fille!>>
-
-

- -

-Please note: the above arguments to SMARTQUOTES -are literal ASCII characters. ,, is two commas, -<< is two less-than signs and >> -is two greater-than signs. -

- -

-Alternatively, you can pass SMARTQUOTES the -two-letter, ISO 639 abbreviation for the language you're writing in, -and mom will output the correct quotes. - -

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

- -

-Turn SMARTQUOTES off by passing it any argument -not in the argument list (e.g. OFF, -QUIT, X, etc.) -

- -

-If you're using the -document processing macros -with -PRINTSTYLE TYPESET, -SMARTQUOTES is on by default (in the Anglo-American -style); with -PRINTSTYLE TYPEWRITE, -it's off by default (and should probably stay that way). -

- -

-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 -inline escapes -for special characters (see man groff_char for a complete -list of special characters). Entering quote marks this way allows -you to use mom's -inline kerning escapes -to fine-tune the look of quotes. -

- -

-NOTE: SMARTQUOTES 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: - -

-    "But she said, `I don't want to!'"    
-
-

- -

-ADDITIONAL NOTE: Whether or not you have -SMARTQUOTES turned on, get into the habit of -entering the foot-and inch-marks, when you need them, with the -inline escapes -\*[FOOT] and \*[INCH], instead of ' -and ". -

- - - -
- -

Convert to upper case

 - -

-Macro: CAPS toggle -

- -

-CAPS converts all lower case letters to upper case. -Primarily, it's a support macro used by the -document processing macros, -but you may find it helpful on occasion. CAPS is -a toggle, therefore no argument turns it on, any argument -(OFF, QUIT, X, etc.) turns it -off. - -

-    .CAPS
-    All work and no play makes Jack a dull boy.
-    .CAPS OFF
-
- -produces, on output - -
-    ALL WORK AND NO PLAY MAKES JACK A DULL BOY.
-
-

- -

-If you wish to capitalise a section of type inline, use the -inline escapes, -\*[UC]...\*[LC] -like this: - -

-    All work \*[UC]and\*[LC] no play makes Jack a dull boy.
-
- -The above produces, on output - -
-    All work AND no play makes Jack a dull boy.
-
-

- - - -
- -

User-defined strings

 - -

-Macro: STRING <name> <what you want in the string> -

- -

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

- -

-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: - -

-    .STRING mw the Montreal/Windsor corridor
-
-

- -

-Once a string is defined, you can call it any time with the -inline escape -\*[<stringname>]. Using the example string above - -

-    The schedule for trains along \*[mw]:
-
- -produces, on output - -
-    The schedule for trains along the Montreal/Windsor corridor:
-
-

- -

-NOTE: 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 STRING goes -into the string, including trailing spaces. -

- -

-Experts: STRING is an alias for ds. -You can use either, or mix 'n' match with impunity. -

- - - -
- -

Change the escape character

 - -

-Macro: ESC_CHAR <new character> | <anything> -

- -

-Groff's and mom'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 -(\\), 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 ESC_CHAR to make the change permanent -(until you decide to restore the escape character to its default, -the backslash). -

- -

-ESC_CHAR with a single character argument -changes the escape character to whatever the argument is. -ESC_CHAR with no argument restores the escape -character to the backslash. -

- -

-Experts: ESC_CHAR is an alias of -.ec. Mix 'n' match the two with impunity. -

- - - -
- -

Get cap-height, x-height and descender depth of a font

 - -

-Macro: SIZESPECS -

- -

-Whenever you need to get the -cap-height, -x-height -or -descender -depth of type at the current point size, invoke -.SIZESPECS, which takes no argument. The dimensions are -stored in the string registers \*[$CAP_HEIGHT], -\*[$X_HEIGHT] and \*[$DESCENDER], -respectively, in -machine units -to which the -unit of measure, -u, is already appended. -

- -

-Thus, if you wanted to advance 2 inches from your current position -on the page plus the cap-height of the current point size of type - -

-    .PT_SIZE <n>
-    .SIZESPECS
-    .ALD 2i+\*[$CAP_HEIGHT]
-
- -would do the trick. -

- - - -
- -

Single underscore

 - -

-Macro: UNDERSCORE [ <distance below baseline> ] "<string>" -
- -*Optional argument requires a unit of measure -

- -

-By default, UNDERSCORE places an underscore 2 -points beneath the required -string argument. -The string must be enclosed in double-quotes, like this: - -

-    .UNDERSCORE "Unmonitored monopolies breed high prices and poor products."
-
-

- -

-If you wish to change the distance of the rule from the -baseline, use the optional argument <distance below -baseline> (with a unit of measure). - -

-    .UNDERSCORE 3p "Unmonitored monopolies breed high prices and poor products."
-
-

- -

-The above places upper edge of the underscore 3 points below the -baseline. -

- - - -

Controlling the weight of underscores

- -

-(Please note that UNDERSCORE_WEIGHT also sets the -weight of -double underscores.) -

- -

-The weight (thickness) of underscores may be controlled with the -macro, UNDERSCORE_WEIGHT. Thus, if you want -underscores with a weight of 1-1/2 points, you'd invoke: - -

-    .UNDERSCORE_WEIGHT 1.5
-
- -prior to invoking .UNDERSCORE. Every subsequent -instance of .UNDERSCORE will use this weight. -

- -

-Mom's default underscore weight is 1/2 point. -

- - - -

NOTES:

- -

-UNDERSCORE 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 UNDERSCORE. Each -output line -or portion of an output line you want underscored must be plugged -separately into UNDERSCORE. Bear in mind, though, -that underscoring should at best be an occasional effect in typeset -copy. If you want to emphasize an entire passage, it's much, much -better to change fonts (e.g. to italic or bold). -

- -

-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 -PRINTSTYLE TYPEWRITE), -with the -UNDERLINE -macro. UNDERLINE is designed specifically for this -purpose, but works only with the monspaced fonts. -

- -

-Mom doesn't always get the position and length -of the underscore precisely right in -justified -copy, although she's fine with all the other -fill modes, -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 after 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 (\) to each word space in the -string passed to UNDERSCORE. The word spacing of -the underscored string may be slightly smaller than the -word space of the remainder of the line, but in many cases, the -difference isn't visually noticeable. -

- -

-UNDERSCORE tends to confuse -gxditview, even though the output, when -printed, looks fine. Generally, I recommend using gv -to preview files anyway. See the section on -previewing. -

- -

-Colorizing underscored text: -If you want underscored text to be in a different colour from the -text around it, use the -COLOR -macro, rather than the -inline escape for changing color. -In other words, assuming your prevailing text color is black and -you want underscored text in red - -

-    .COLOR red
-    .UNDERSCORE "text to underscore"
-    .COLOR black
-
- -rather than - -
-    .UNDERSCORE "\*[red]text to underscore\*[black]"
-
- -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: - -
-    .UNDERSCORE "\*[red]text to underscore\*[blue]"
-    .COLOR black
-
-

- - - -
- -

Double underscore

 - -

-Macro: UNDERSCORE2 [ <distance below baseline> [ <distance between rules> ] ] "<string>" -
- -*Optional arguments require a unit of measure -

- -

-By default, UNDERSCORE2 places a double underscore -2 points beneath the required -string argument. -The string must be enclosed in double-quotes, like this: - -

-    .UNDERSCORE2 "Unmonitored monopolies breed high prices and poor products."
-
-

- -

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

- -

-If you wish to change the distance of the double underscore from -the baseline, use the optional argument <distance below -baseline> (with a unit of measure), e.g., - -

-    .UNDERSCORE2 3p "Unmonitored monopolies breed high prices and poor products."
-
- -which places the upper edge of the first rule of the double -underscore 3 points below the -baseline. -

- -

-If you wish to change the distance between the two rules as -well, use the second optional argument <distance between -rules> (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. -

- -

-The weight (thickness) of double underscores may be controlled with -the macro -UNDERSCORE_WEIGHT -(q.v). -

- -

-NOTE: the same restrictions and caveats apply -to UNDERSCORE2 as to -UNDERSCORE. See the -NOTES -for UNDERSCORE. -

- - - -
- -

Underline text — monospaced fonts only

 - -

-Macro: UNDERLINE toggle -

- -

-If your font is monospaced, like Courier, or you're using the -document processing macro -PRINTSTYLE TYPEWRITE, -UNDERLINE allows you to underline words and -passages that, in typeset copy, would be italicized. You invoke -.UNDERLINE as you do with all toggle macros — by -itself (i.e. with no argument) to initiate underlining, and with any -argument (OFF, QUIT, X, etc) to turn underlining -off. -

- -

-When on, UNDERLINE underlines letters, words -and numbers, but not punctuation or spaces. This makes for more -readable copy than a solid underline. -

- -

-NOTE: Underlining may also be turned on and off -inline -with the escapes -\*[UL]...\*[ULX]. -

- - - -
- -

Inline escape for underlining — monospaced fonts only

 - -

-Inline: \*[UL]...\*[ULX] -

- -

-If your font is a monospaced one, like Courier, or you're using the -document processing macro -PRINTSTYLE TYPEWRITE, -\*[UL]...\*[ULX] underlines words and -passages that, in typeset copy, would be italicized. -

- -

-\*[UL] 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, \*[ULX] turns underlining off. -

- -

-The macro -UNDERLINE -and the inline escape \*[UL] are functionally -identical, hence - -

-    .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
-
- -produces the same result as - -
-    .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]
-
-

- - - -
- -

Insert space into lines

 - -

-Macro: PAD "<string with pad markers inserted>" [ NOBREAK ] -

- -

-With PAD, you can insert unspecified amounts of -whitespace into a line. - - - -The optional NOBREAK argument tells mom -not to advance on the page after the PAD macro has -been invoked. -

- -

-PAD calculates the difference between the length of -text on the line and the distance remaining to its end, then inserts -the difference (as whitespace) at the place(s) you specify. -

- -

-Take, for example, the following relatively common typesetting -situation, found at the bottom of legal agreements: - -

-    Date             Signature                               |
-
-

- -

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

- -

-The -pad marker -(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): - -

-    .LL 30P
-    .PAD "Date#Signature###"
-
-

- -

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

- - - -

-One rarely wants merely to insert space in a line; one usually -wants to fill it with something, hence PAD is -particularly useful in conjunction with -string tabs. -The following uses the Date/Signature example above, but adds -rules into the whitespace through the use of string tabs and -mom's -inline escape -\*[RULE]. -(Instead of \*[RULE], -groff's line drawing function, -\l -could be used.) - -

-    .LL 30P
-    .PAD "Date \*[ST1]#\*[ST1X] Signature \*[ST2]###\*[ST2X]" NOBREAK
-    .ST 1 J
-    .ST 2 J
-    .TAB 1
-    \*[RULE]
-    .TN
-    \*[RULE]
-    .TQ
-
-

- -

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

- -

-Basically, what the example does is: - -

    -
  1. Pads the Date/Signature line (using the pad marker - #), encloses the padded space with two string - tabs markers, and outputs the line without advancing on the - page. -
    2. -
  2. Sets the two string tabs. -
    3. -
  3. Calls the first string tab and draws a rule to its full - length. -
    4. -
  4. Calls the second tab with - TN - (which moves to tab 2 and stays on the same baseline) - then draws a rule to the full length of string tab 2. -
    5. -
-

- -

-Often, when setting up string tabs this way, you don't want the -padded line to print immediately. To accomplish this, use -SILENT. -See the -quickie tutorial on string tabs -for an example. -

- -

-NOTE: Because the pound sign -(#) 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 -PAD_MARKER. -Also, be aware that # as a pad marker only applies -within the PAD macro; at all other times it prints -literally, just as you'd expect. -

- -

-Another important consideration when using PAD is that -because the string must be enclosed in double-quotes, you can't use the -double-quote (") as part of the string. The -way to circumvent this is to use the groff -inline escapes -\(lq and \(rq (leftquote and rightquote -respectively) whenever double-quotes are required in the string -passed to PAD. -

- - - -
- -

Change/set the marker used with PAD

 - -

-Macro: PAD_MARKER <character to use as the pad marker> -

- -

-If you need to change mom's default pad marker -(#), either because you want a literal # in -the padded line, or simply because you want to use another character -instead, use PAD_MARKER, whose argument is the new -pad marker character you want. - -

-    .PAD_MARKER @
-
- -changes the pad marker to @. -

- -

-Once you've changed the pad marker, the new marker remains in -effect for every instance of -PAD -until you change it again (say, back to the pound sign). -

- - - -
- -

Inline escape to add leaders to a line

 - -

-Inline: \*[LEADER] -

- -

-Whenever you want to fill a line or tab with -leaders, -use the -inline escape -\*[LEADER]. The remainder of the line or tab will be -filled with the leader character. Mom's default -leader character is a period (dot), but you can change it to any -character you like with -LEADER_CHARACTER. -

- -

-NOTE: \*[LEADER] 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. -String tabs -are perfect for this. An example follows. - -

-    .LL 30P
-    .PAD "Date\*[ST1]#\*[ST1X]Signature\*[ST2]###\*[ST2X]"
-    .EL
-    .ST 1 J
-    .ST 2 J
-    .TAB 1
-    \*[LEADER]
-    .TN
-    \*[LEADER]
-    .TQ
-
-

- -

-The PAD line sets the words Date and Signature, -and marks string tabs around the pad space inserted in the line. -The string tabs are then "set", called, and filled -with leaders. The result looks like this: - -

-    Date.............Signature.....................................
-
-

- - - -
- -

Change/set the leader character

 - -

-Macro: LEADER_CHARACTER <character> -

- -

-LEADER_CHARACTER takes one argument: a single -character you would like to be used for -leaders. -(See -\*[LEADER] -for an explanation of how to fill lines with leaders.) -

- -

-For example, to change the leader character from mom's -default (a period) to the underscore character, enter - -

-    .LEADER_CHARACTER _
-
-

- - - -
-

Drop caps

 - -

-Macro: DROPCAP <dropcap letter> <number of lines to drop> [ COND <percentage> | EXT <percentage> ] -

- -

-The first two arguments to DROPCAP are the letter you -want to be the -drop cap -and the number of lines you want it to drop. By default, -mom uses the current family and font for the drop -cap. -

- -

-The optional argument (COND or -EXT) indicates that you want the drop -cap condensed (narrower) or extended (wider). If you use -COND or EXT, 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. -

- -

-Mom will do her very best to get the drop cap to -line up with the first line of text indented beside it, then set the -correct number of indented lines, and restore your left margin when -the number of drop cap lines has been reached. -

- -

-Beginning a paragraph with a drop cap "T" looks -like this: - -

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

- -

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

- -

-NOTE: When using the -document processing macro -PP, -DROPCAP only works - -

- -If these conditions aren't met, DROPCAP is silently ignored. -

- -

-WARNING: DROPCAP puts a bit of -a strain on resource-challenged systems. If you have such a -system and use drop caps extensively in a document, be prepared -for a wait while mom does her thing. -

- -

Support macros for DROPCAP

- -

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

- -

-Mom solves the last of these problems with the -COND and EXT arguments. The rest she -solves with macros that change the default behaviour of -DROPCAP, namely -

- -

-DROPCAP_FAMILY -
- -DROPCAP_FONT -
- -DROPCAP_COLOR -
- -DROPCAP_ADJUST -
- -and -
- -DROPCAP_GUTTER. -

- -

-These macros must, of course, come before you invoke -DROPCAP. -

- -

DROPCAP_FAMILY

- -

-Set the drop cap family by giving -DROPCAP_FAMILY the name of the family you want, -e.g. - -

-    .DROPCAP_FAMILY H
-
- -which will set the family to Helvetica for the drop cap only. -

- -

DROPCAP_FONT

- -

-Set the drop cap font by giving -DROPCAP_FONT the name of the font you want, -e.g. - -

-    .DROPCAP_FONT I
-
- -which will set the font to italic for the drop cap only. -

- -

DROPCAP_ADJUST

- -

-If the size mom calculates for the drop cap -isn't precisely what you want, you can increase or decrease it -with DROPCAP_ADJUST, like this: -e.g. - -

-    .DROPCAP_ADJUST +1
-        or
-    .DROPCAP_ADJUST -.75
-
-

- -

-DROPCAP_ADJUST only understands -points, -therefore do not append any -unit of measure -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. -

- -

DROPCAP_COLOR

- -

-If you'd like your drop cap colourized, simply invoke -.DROPCAP_COLOR with the name of a colour you've already -created ("initialized") with -NEWCOLOR -or -XCOLOR. Only the drop cap will be -colourized; all other text will remain at the current colour -default (usually black). -

- -

DROPCAP_GUTTER

- -

-By default, mom puts three points of space -between the drop cap and the text indented beside it. If you -want another value, use DROPCAP_GUTTER (with a -unit of measure), like this: - -

-    .DROPCAP_GUTTER 6p
-
-

- - - -
- -

Superscript

 - -

-Inlines: \*[SUP]...\*[SUPX] -

- -

-Superscripts are accomplished -inline. -Whenever you need one, typically for numerals, all you need to do is -surround the superscript with the inlines above. \*[SUP] -begins superscripting; \*[SUPX] turns it off. -

- - - - -

-If your running type is -pseudo-condensed -or -pseudo-extended -and you want your superscripts to be equivalently pseudo-condensed -or -extended, use \*[CONDSUP]...\*[CONDSUPX] or -\*[EXTSUP]...\*[EXTSUPX]. -

- -

-The superscript inlines are primarily used by the -document processing macros -for automatic generation of numbered footnotes. However, you may -find them useful for other purposes. -

- -

-NOTE: Mom 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 mom 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 -mom will receive eternal blessings not only in this -lifetime, but in all lifetimes to come. -

- -

SUPERSCRIPT RAISE AMOUNT

- -

-By default, mom raises superscripts 1/3 of an -em -above the baseline. If you're not happy with this default, you can -change it by invoking SUPERSCRIPT_RAISE_AMOUNT with -the amount you want them raised. A -unit of measure -must be appended directly to the amount. Thus, you want -superscripts raised by 3 -points -instead of 1/3 em, you'd -do - -

-    .SUPERSCRIPT_RAISE_AMOUNT 3p
-
-and all subsequent superscripts would be raised by 3 points. -

- -
- -Next   -Prev   -Top   -Back to Table of Contents - - - - - diff --git a/contrib/mom/momdoc/graphical.html b/contrib/mom/momdoc/graphical.html deleted file mode 100644 index 1f57b1c5..00000000 --- a/contrib/mom/momdoc/graphical.html +++ /dev/null @@ -1,593 +0,0 @@ - - - - - - -Mom -- Graphical Objects - - - - - - - -

-Next   -Prev   -Back to Table of Contents -

- -

Graphical objects

- -

-Introduction to graphical objects - -

- -Index of graphical object macros -

- -

Introduction to graphical objects

 - -

-Groff has a number of -inline escapes -for drawing rules, polygons, ellipses and splines. All begin with -\D (presumably for "Draw") and are documented -in the groff info manual: - -

-    info groff => Escape index => \D
-
-

- -

-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 consistent manner, they don't -always perform in an expected manner. -

- -

-Experience shows that the most common graphical elements typesetters -need are rules (horizontal and vertical), boxes, and circles (or -ellipses). For this reason, mom provides macros -to draw these objects in an easy-to-understand way; the results are -predictable, and mom's syntax makes fixes or tweaks -painless. -

- - - -

-For example, if you want to draw a 2-inch square outline box at the left -margin using groff's \D escapes, it looks like this: - -

-              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
-
- -Obviously, this isn't very efficient for something as simple as a -box. -

- -

-Here's the same box, drawn with mom's box drawing -macro, -DBX: - -

-left margin indent-+  +-box width
-                   |  |
-          .DBX .5  0  2i  2i
-                |         |
-   rule weight--+         +-box depth
-   (in points)
-
-

- -

-Mom'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. -

- -

-There are no defaults for the arguments to mom'a -graphical object macros, which means you must supply the arguments -every time you invoke them. -

- -

-NOTE: As stated above, mom only -provides macros for commonly-used graphical objects (rules, boxes, -circles) only. More complex objects (polygons, non-straight lines, -splines) must be drawn using groff's \D -escapes. -

- -

Graphical object behaviour

 - -

-Mom's graphical object macros all behave in the -following, carved-in-stone ways: - -

    -
  1. Objects are drawn from the - baseline - down, including horizontal rules.
    2. -
  2. Objects begin precisely at the left indent supplied as - an argument to the macro.
    3. -
  3. Objects are drawn from left to right.
    4. -
  4. Enclosed objects (boxes, circles) are drawn from the - perimeter inward.
    5. -
  5. Objects return to their horizontal/vertical point of origin.
    6. -
- -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. -

- -

Order of arguments

 - -

-The order of arguments to the graphical object macros is the same -for every macro: - -

-

- -

-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, -DRH, -with only the arguments (from the mnemonic) that apply: W-I-L (and -possibly C). -

- -

Index of graphical object macros

 - - - - - -
- -

Drawing horizontal rules

 - -

-Macro: DRH <none> | <rule weight> <indent> <length> [<colour>] -
- -*The argument to <rule weight> is -in -points, -but do NOT append the -unit of -measure, p. -
- -*The arguments, <indent> and -<length>, require a unit of measure. -

- -

-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 .DRH without any -arguments. (Note that DRH 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, -RULE_WEIGHT. -DRH, used this way, is exactly equivalent to -entering the -inline escape, -\*[RULE]. -

- -

-To draw horizontal rules of a specified length, you must, at a -minimum, supply -DRH with the arguments -rule weight, indent (measured from the -current left margin) and length. -

- -

-Optionally, you may give a colour argument. -The colour may be either one defined with -NEWCOLOR, -or a named X-colour inititialized with -XCOLOR, -or an X-colour alias (again, initialized with -XCOLOR). -

- -

-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 .DRH like this: - -

-         weight length
-           |      |
-    .DRH 1.125 2P 3i
-               |
-             indent
-
- -(Note that the rule weight argument, which is expressed in points, -must NOT have the unit of measure p appended to it.) -

- -

-If, in addition, you want the rule blue: - -

-    .DRH 1.125 2P 3i blue
-
-

- -

How mom handles the positioning of horizontal rules

- -

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

- -

-Furthermore, after the rule is drawn, mom returns -you to the current left margin, at the same vertical position on -the page as when DRH was invoked. In other words, -DRH causes no movement on the page, either -horizontal or vertical. -

- - - -
- -

Drawing vertical rules

 - -

-Macro: DRV <rule weight> <indent> <depth> [<colour>] -
- -*The argument to <rule weight> is -in -points, -but do NOT append the -unit of -measure, p. -
- -*The arguments, <indent> and -<depth>, require a unit of measure. -

- -

-To draw vertical rules of a specified length, you must, at a -minimum, supply -DRV with the arguments -rule weight, indent (measured from the -current left margin) and depth. -

- -

-Optionally, you may give a colour argument. -The colour may be either one defined with -NEWCOLOR, -or a named X-colour inititialized with -XCOLOR, -or an X-colour alias (again, initialized with -XCOLOR). -

- -

-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 .DRV like this: - -

-         weight   depth
-           |        |
-    .DRV .75 19P+6p 6c
-               |
-             indent
-
- -(Note that the rule weight argument, which is expressed in points, -must NOT have the unit of measure p appended to it.) -

- -

-If, in addition, you want the rule red: - -

-    .DRV .75 19P+6p 6c red
-
-

- -

How mom handles the positioning of vertical rules

- -

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

- -

-Furthermore, after the rule is drawn, mom returns -you to the current left margin, at the same vertical position -on the page as when DRV was invoked. In other -words, DRV causes no movement on the page, either -horizontal or vertical. -

- - - -
- -

Drawing boxes

 - -

-Macro: DBX < <rule weight> | SOLID > <indent> <length> <depth> [<colour>] -
- -*The argument to <rule weight> is -in -points, -but do NOT append the -unit of -measure, p. -
- -*The arguments, <indent>, -<length> and <depth> -require a unit of measure. -

- -

-To draw boxes of specified dimensions, you must, at a minimum, -supply DBX with the arguments rule -weight or SOLID, indent -(measured from the current left margin), length and -depth. -

- -

-Optionally, you may give a colour argument. -The colour may be either one defined with -NEWCOLOR, -or a named X-colour inititialized with -XCOLOR, -or an X-colour alias (again, initialized with -XCOLOR). -

- -

-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 .DBX like this: - -

-           indent   depth
-             |        |
-    .DBX .5  1i  12P  6P
-          |       |
-       weight   length
-
- -(Note that the box weight argument, which is expressed in points, -must NOT have the unit of measure p appended to it.) -

- -If you want the same box, but solid ("filled") rather -than drawn as an outline: - -
-    .DBX SOLID 1i 12P 6P
-
- -

-Additionally, if you want the box green: - -

-    .DBX .5 1i 12P 6P green
-     or
-    .DBX SOLID 1i 12P 6P green
-
-

- -

How mom handles the positioning of boxes

- -

-Boxes are drawn from the baseline down, from left to right, and -from the perimeter inward. "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 -within the dimensions of the box. -

- -

-Furthermore, after the box is drawn, mom returns -you to the current left margin, at the same vertical position -on the page as when DBX was invoked. In other -words, DBX causes no movement on the page, either -horizontal or vertical. -

- - - -
- -

Drawing circles (ellipses)

 - -

-Macro: DCL < <rule weight> | SOLID > <indent> <length> <depth> [<colour>] -
- -*The argument to <rule weight> is -in -points, -but do NOT append the -unit of -measure, p. -
- -*The arguments, <indent>, -<length> and <depth> -require a unit of measure. -

- -

-To draw circles of specified dimensions, you must, at a minimum, -supply DCL with the arguments rule -weight or SOLID, indent -(measured from the current left margin), length and -depth. -

- -

-Optionally, you may give a colour argument. -The colour may be either one defined with -NEWCOLOR, -or a named X-colour inititialized with -XCOLOR, -or an X-colour alias (again, initialized with -XCOLOR). -

- -

-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 .DCL like this: - -

-           indent  depth
-             |       |
-    .DCL .5  1i  6c  3c
-          |      |
-       weight   ength
-
- -(Note that the box weight argument, which is expressed in points, -must NOT have the unit of measure p appended to it.) -

- -If you want the same box, but solid ("filled") rather -than drawn as an outline: - -
-    .DCL SOLID 1i 6c 3c
-
- -

-Additionally, if you want the circle yellow: - -

-    .DCL .5 1i 6c 3c yellow
-     or
-    .DCL SOLID 1i 6c 3c yellow
-
-

- -

How mom handles the positioning of circles (ellipses)

- -

-Circles (ellipses) are drawn from the baseline down, from left -to right, and from the perimeter inward. "From the -perimeter inward" means that if you request a circle weight of -six points, the 6-point rule used to draw the outline of the circle -or ellipse falls entirely within the dimensions of the -circle or ellipse. -

- -

-Furthermore, after the circle is drawn, mom returns -you to the current left margin, at the same vertical position -on the page as when DCL was invoked. In other -words, DCL causes no movement on the page, either -horizontal or vertical. -

- -
- -

-Next   -Prev   -Top   -Back to Table of Contents -

- - - - - diff --git a/contrib/mom/momdoc/headfootpage.html b/contrib/mom/momdoc/headfootpage.html deleted file mode 100644 index b49d5dc5..00000000 --- a/contrib/mom/momdoc/headfootpage.html +++ /dev/null @@ -1,2256 +0,0 @@ - - - - - - -Mom -- Document processing: headers, footers and pagination - - - - - - - -

-Next   -Prev   -Back to Table of Contents -

- -

Page headers, footers, and pagination

 - - - -

Introduction

 - -

-Headers -and -footers, -as defined in the section -Mom's Document Processing Terms, -are those parts of a document that contain information about the document -itself which appear in the margins either above or below -running text. -They are, in all respects but two, identical. The differences are: - -

    -
  1. headers appear in the margin above running text while - footers appear in the margin beneath running text; -
    2. -
  2. the (optional) rule that separates headers from running - text appears below the header while - the (optional) rule that separates footers from running - text appears above the footer. -
    3. -
-

- - - -

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

- -

-Furthermore, any -control macro -that begins with HEADER_ may be used to control -footers, simply by replacing HEADER_ with -FOOTER_. -

- -

-Author's note: Left to their own devices (i.e. if -you're happy with the way mom does things by default), -headers are something you never have to worry about. You can skip -reading this section entirely. But if you want to change them, be -advised that headers have more macros to control their appearance than -any other document element. The text of this documentation becomes -correspondingly dense at this point. -

- - - -

-NOTE: While the single page number that -mom generates in either the top or bottom margin -above or below running text is technically a kind of header/footer, -mom and this documentation treat it as a -separate page element. -

- -

General description of headers/footers

 - -

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

- -

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

- -

-A note to groff experts: Although -mom's headers resemble the three-part titles -generated by .tl, they're in no way related to -it, nor based upon it. .tl is not used at all in -mom. -

- -

-Normally, mom fills headers with strings appropriate -to the document type selected with -DOCTYPE. -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. -

- -

-By default, mom prints a horizontal rule beneath -headers to separate them visually from running text. In the case of -footers, the rule is above running text. You can increase -or decrease the space between the header and the rule if you like -(with -HEADER_RULE_GAP), -or remove it completely. -

- -

Default specs for headers/footers

 - -

-Mom makes small type adjustments to each part of -the header (left, centre, right) to achieve an aesthetically -pleasing result. The defaults are listed below. (The strings -mom puts by default in each part are explained in -DOCTYPE.) -

- -

-NOTE: Except for capitalization (all caps or -caps/lower-case), these defaults apply only to -PRINTSTYLE TYPESET. -

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

-You can, of course, change any of the defaults using the appropriate -control macros. And should you wish to design headers from the -ground up, mom has a special macro, -HEADER_PLAIN, -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. -

- -

Vertical placement and spacing of headers/footers

 - -

-As explained in the section on -typesetting macros in document processing, -the top and bottom margins of a mom document -are the vertical start and end positions of -running text, -not the vertical positions of headers or footers, which, by definition, -appear in the margins above (or below) running text. -

- -

-The vertical placement of headers -is controlled by the macro -HEADER_MARGIN, -which establishes the -baseline -position of headers relative to the top edge of the page. -The header rule, whose position is relative to the header itself, -is controlled by a separate macro. -FOOTER_MARGIN establishes the baseline position of -footers relative to the bottom edge of the page. -

- -

-HEADER_GAP -establishes the distance between headers and the start -of running text (effectively making HEADER_MARGIN + -HEADER_GAP the top margin of running text unless you give -mom a literal top margin (with -T_MARGIN), -in which case she ignores HEADER_GAP and starts -running text at whatever top margin you gave. -FOOTER_GAP and -B_MARGIN -work similarly, except they determine where running text -ends on the page. (See -FOOTER MARGIN AND BOTTOM MARGIN — VERY IMPORTANT! -for a warning about possible conflicts between the footer margin and -the bottom margin.) -

- -

-Confused? Mom apologizes. It's really quite -simple. By default, mom sets headers 4-1/2 -picas -down from the top of the page and starts running text 3 picas (the -HEADER_GAP) beneath that, which means the effective -top margin of running text is 7-1/2 picas (visually approx. 1 inch). -If you give mom a literal top margin (with -T_MARGIN), -she ignores the HEADER_GAP and starts running -text at whatever top margin you gave. -

- -

-Footers are treated the same way, the only difference being the -default distances. Mom sets footers 3 picas up from -the bottom of the page, and interrupts the processing of running -text 3 picas (the FOOTER_GAP) above that (again, -visually approx. 1 inch). If you give mom a -literal bottom margin (with -B_MARGIN), -she ignores the FOOTER_GAP and interrupts the -processing of running text at whatever bottom margin you gave. -

- -

-If mom is paginating your document (she -does, by default, at the bottom of each page), the vertical -spacing and placement of page numbers, whether at the top -or the bottom of the page, is managed exactly as if the -page numbers were headers (or footers), and are controlled -by the same macros. See -Pagination control. -

- -
- - - -

Managing headers/footers

 - -

Macro list

- - - -

-The following are the basic macros for turning -headers -or -footers -on or off. They should be invoked prior to -START. -

- -

-By default, mom prints page headers. If you turn -them off, she will begin -running text -on each page with a default top margin of 6 -picas -unless you have requested a different top margin (with -T_MARGIN) -prior to -START. -

- -

-Please note that -HEADERS -and -FOOTERS -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 -.FOOTERS; -there's no need to turn headers off first. -

- -

-If you need both headers and footers, there's a special macro, -HEADERS_AND_FOOTERS, -that allows you to set this up. -

- - - -
- - - -

-Macro: HEADERS toggle -

- -

-Page headers -are on by default. If you don't want them, turn them off by -invoking .HEADERS with any argument (OFF, QUIT, -END, X...), e.g. - -

-    .HEADERS OFF
-
-

- -

-NOTE: HEADERS automatically -disables -footers -(you can't have both), but not the page numbers that normally -appear at the bottom of the page. -

- -

-ADDITIONAL NOTE: If HEADERS -are OFF, mom's normal top -margin for -running text -(7.5 -picas) -changes to 6 picas (visually approx. 1 inch). This does NOT apply -to the situation where footers have been explicitly turned on -(with -FOOTERS). -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.) -

- - - -
- - - -

-Macro: FOOTERS toggle -

- -

-Page footers -are off by default. If you want them instead of -headers -(you can't have both), turn them on by invoking -.FOOTERS without an argument, e.g. - -

-    .FOOTERS
-
-

- -

-FOOTERS automatically disables headers, and -mom shifts the placement of page numbers from their -normal position at page bottom to the top of the page. -

- -

-NOTE: By default, when footers are on, -mom does not print a page number on the first -page of a document, nor on first pages after -COLLATE. -If you don't want this behaviour, you can change it with -PAGENUM_ON_FIRST_PAGE. -

- - - -
- - - -

-Macro: FOOTER_ON_FIRST_PAGE toggle -

- -

-If you invoke -.FOOTERS, -mom, by default, does not print a footer on the -first page of the document. (The -docheader -on page 1 makes it redundant.) However, should you wish a footer on -page 1, invoke .FOOTER_ON_FIRST_PAGE without any argument. -

- -
- - - -

User-defined, single string recto/verso headers/footers

 - -

Introduction

 - -

-Sometimes, you'll find you can't get mom'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. -

- -

-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: - -

-    +------------------------+   +------------------------+     
-    |         Author         |   |         Title          |     
-    |                        |   |                        |     
-    |                        |   |                        |     
-    |                        |   |                        |     
-    |                        |   |                        |     
-    |                        |   |                        |     
-    |                        |   |                        |     
-    |                        |   |                        |     
-    |                        |   |                        |     
-    |                        |   |                        |     
-    |                        |   |                        |     
-    |                        |   |                        |     
-    |                        |   |                        |     
-    |                        |   |                        |     
-    +------------------------+   +------------------------+     
-
-

- -

-With mom's standard 3-part headers, this isn't -possible, even when -RECTO_VERSO -is enabled. RECTO_VERSO switches the left and -right parts of headers on alternate pages, but the centre -part remains unchanged. -

- -

-Any time you need distinctly different headers on alternate -pages, mom has macros that let you manually -design and determine what goes into headers on recto pages, and -what goes into headers on verso pages. The macros are -HEADER_RECTO -and -HEADER_VERSO. -Both allow you to state whether the header is flush left, centred, -or flush right, and both take a single -string argument -with which, by combining text and -inline escapes, -you can make the headers come out just about any way you want. -Use of the \*[PAGE#] escape is permitted in the string -argument (see -Including the page number in header-left, -centre or -right), -and as an added bonus, mom provides a special -mechanism whereby it's possible to "pad" the string as -well. -

- - - -
- - - -

-Macro: HEADER_RECTO LEFT | CENTER | RIGHT [ CAPS ] "<header recto string>" -
- -Macro: HEADER_VERSO LEFT | CENTER | RIGHT [ CAPS ] "<header verso string>" -
-

- -

-HEADER_RECTO and HEADER_VERSO -behave identically, hence all references to -HEADER_RECTO in this section also -refer to HEADER_VERSO. Furthermore, -FOOTER_ can be used instead of -HEADER_ to set up recto/verso footers. -

- -

-The first argument to HEADER_RECTO is the -direction in which you want the header -quadded. -L, C and R may be used in place of LEFT, -CENTER and RIGHT. - -

-The second argument (optional) tells mom to -capitalize the text of the header. Please note: -Do NOT attempt to use -\*[UC]...\*[LC] -inside the string passed to HEADER_RECTO. -

- -

-The final argument is a string, surrounded by -double-quotes, containing what you want in the header. -HEADER_RECTO disables mom's normal -3-part headers, therefore anything you want in the headers must be -entered by hand in the string, including colours (via the -inline escape -\*[<colorname>]). -

- -

-By default, HEADER_RECTO is set at the same -size, and in the same family and font, as paragraph text. The -control macros -HEADER_FAMILY -and -HEADER_SIZE -may be used to change the default family and size. Changes to -the font(s) within the string must be accomplished with the -inline escapes -\*[ROM], \*[IT], \*[BD], \*[BDI] and -\*[PREV] (see -Changing fonts). -Additional refinements to the style of the header-recto string, -including horizontal spacing and/or positioning, can also be made -with inline escapes. -

- -

-To include the current page number in the string, use the -\*[PAGE#] -inline escape. -

- -

*Padding the HEADER_RECTO/HEADER_VERSO string

 - -

-You can "pad" the header-recto string, a convenience -you'll appreciate in circumstances such as the following. - -

-               VERSO                       RECTO 
-    +------------------------+   +------------------------+     
-    | Author          Page#  |   | Page#            Title |     
-    |                        |   |                        |     
-    |                        |   |                        |     
-    |                        |   |                        |     
-    |                        |   |                        |     
-    |                        |   |                        |     
-    |                        |   |                        |     
-    |                        |   |                        |     
-    |                        |   |                        |     
-    |                        |   |                        |     
-    |                        |   |                        |     
-    |                        |   |                        |     
-    |                        |   |                        |     
-    |                        |   |                        |     
-    +------------------------+   +------------------------+     
-
-

- -

-To pad the string argument passed to HEADER_RECTO, -begin and end the string (inside the double-quotes) with the caret -character (^). Enter the pound sign (#) -at any point in the string where you want an equalized amount of -whitespace inserted. (If you're unsure what padding is, see -Insert space into lines.) -Note that if you're padding the string, it doesn't matter what quad -direction you give HEADER_RECTO since padding, by -its nature, justifies text to the left and right margins. -

- -

-The situation depicted above is accomplished like this: - -

-    .HEADER_RECTO LEFT "^\*[PAGE#]#\E*[$TITLE]^"
-    .HEADER_VERSO LEFT "^\E*[$AUTHOR]#\*[PAGE#]^"
-
-

- -

-Note that mom does not interpret the # -in \*[PAGE#] as a padding marker (i.e. as a place to -insert whitespace). -

- -

-Also, notice that the argument, LEFT, is used in both -cases. When padding a header, it doesn't matter whether you use -LEFT, CENTER or RIGHT as the argument. -

- -

-Furthermore, should you need a user-defined header of -the sort provided by HEADER_RECTO and -HEADER_VERSO but aren't actually printing -recto/verso, you can use HEADER_RECTO to design the -header that appears at the top of every page. -

- -

-IMPORTANT: The -PAD_MARKER -macro, which changes the default pad marker (#) used by -PAD, -has no effect on the pad marker used in the -HEADER_RECTO string. If you absolutely must -have a literal pound sign in your HEADER_RECTO -string, use the escape sequence for the pound sign -( \[sh] ) where you want the pound sign -to go. -

- - - -
- - - -

-Macro: HEADERS_AND_FOOTERS -
- -Invocation: -

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

- -

-HEADERS_AND_FOOTERS allows you to have both -headers and footers on the same page. -

- -

-Unlike the macros, -HEADERS -and -FOOTERS, -HEADERS_AND_FOOTERS requires that you supply -the information you want in the headers and footers yourself. -Mom does no automatic generation of things like -the title and the author in headers and footers when you're using -HEADERS_AND_FOOTERS. Furthermore, style -changes — family, font, pointsize, colour, capitalization, etc -— are entirely your responsibility and must be made with -inline escapes -in the arguments passed to "<recto -header string>", "<recto -footer string>", etc. By default, -mom sets the headers and footers created with -HEADERS_AND_FOOTERS in the same family, font, -point size, capitalization style and colour as -running text. -

- -

-The manner of entering what you want is identical to the way you -input -single string headers and footers. -I suggest reading up on them, as well as looking at the entries, -HEADER_RECTO -and -Using mom's "reserved" strings in header/footer definitions. -

- -

-The same -padding mechanism -used in HEADER_RECTO and -HEADER_VERSO is available in the -string arguments -passed to -HEADERS_AND_FOOTERS, allowing you to simulate -two- and three-part headers and footers. -

- -

-L | C | R in the arguments to -HEADERS_AND_FOOTERS refers to whether you -want the specific header or footer set flush left, centered, -or flush right. (You can also use the longer forms, -LEFT, CENTER and RIGHT.) The -string you give afterwards is whatever text you want, including -mom's -"reserved" strings, -and whatever -inline escapes -you need to change things like family and font, pointsize, colour, -etc. as you go along. -

- -

-Note the backslashes in the invocation, above. Every set of -arguments given this way to HEADERS_AND_FOOTERS -except the last one 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. -

- -

-If you want to disable having both headers and footers -on the same page, invoke .HEADERS_AND_FOOTERS -with any argument you want (e.g. OFF, QUIT, END, -X...). Mom will restore her default -behaviour of setting automatically generated page headers, -with the page number, centered, at the bottom of the page. If -you would prefer footers instead of headers after turning -HEADERS_AND_FOOTERS off, just invoke -.FOOTERS -afterwards. -

- -

Some examples

- -
Example 1
- -

-If you want the same header and footer on every page, here's how -you'd do it. - -

-    .HEADERS_AND_FOOTERS \          +-----------------------+
-    C "\E*[$TITLE]" \               |         Title         |
-    L "^\E*[$AUTHOR]#\*[PAGE#]^"    |                       |
-                                    |                       |
-                                    |                       |
-                                    |                       |
-                                    |                       |
-                                    |                       |
-                                    |                       |
-                                    |                       |
-                                    |                       |
-                                    |                       |
-                                    |                       |
-                                    |                       |
-                                    | Author          Pg. # |
-                                    +-----------------------+
-
-

- -

-\E*[$TITLE] and \E*[$AUTHOR] will print the -strings you pass to -TITLE -and -AUTHOR; -\*[PAGE#] 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 -here.) -

- -

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

- -
Example 2
- -

-If you want different headers and footers on recto/verso pages, -here's a recipe: - -

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

- -
- -

Control macros for headers/footers

 - -

-Virtually every part of headers (see the paragraph on how -"headers" means "footers" -in the -introduction to headers/footers) -can be designed to your own specifications. -

- -

Header/footer control macros

 - - - - - -
- -

Header/footer strings

 - - - -

-Macro: HEADER_LEFT "<text of header left>" | # -
- - - -Macro: HEADER_CENTER "<text of header centre>" | # -
- - - -Macro: HEADER_RIGHT "<text of header right>" | # -

- -

-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, mom, 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 HEADER_LEFT like this: - -

-    .HEADER_LEFT "R. Stallman, E. Raymond"
-
-

- -

-Because the arguments to HEADER_LEFT, _CENTER, -and _RIGHT are -string arguments, -they must be enclosed in double-quotes. -

- -

-NOTE: Replace HEADER_, above, -with FOOTER_ to change the strings in footers. - -

*Padding the header/footer centre string

- -

-Macro: HEADER_CENTER_PAD LEFT | RIGHT <amount of space by which to pad centre string left or right> -
- -*Requires a unit of measure -

- -

-By default, mom 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 HEADER_CENTER_PAD comes in. With a -bit of experimentation (yes, you have to preview the document), you -can use HEADER_CENTER_PAD to move the header -centre string left or right until it looks acceptably centred -between the two other strings. -

- -

-For example, say your document is an outline for a novel called "By -the Shores of Lake Attica." You've told mom -you want -

- -    .DOCTYPE NAMED "Outline" -

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

-    .HEADER_CENTER_PAD RIGHT 3P
-
-

- -you can scoot the word "Outline" over three -picas -to the left (the padding's added to the right of the string) -so that your head looks nicely spaced out. Invoking -.HEADER_CENTER_PAD with the LEFT argument -obviously puts the padding on the left side of the string. -

- -

-Most reassuring of all is that if you use -HEADER_CENTER_PAD conjunction with -RECTO_VERSO, -mom 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. -

- -

*Using mom's "reserved" strings in header/footer definitions

 - -

-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. Mom usually -knows what to do. -

- -

-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 -collated -documents, and you want the word "Endnotes" to go in the header -centre position of the endnotes, but want, say, the -TITLE -to go back into the centre position for the next output document. -

- -

-In scenarios like the above, mom has a number of -"reserved" strings that you can plug into the -HEADER_LEFT, _CENTER and _RIGHT -macros. They are: - -

-    \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
-
-

- -

-Returning to the scenario above, first, you'd define a centre -string for the endnotes page: - -

-    .HEADER_CENTER "Endnotes"
-
- -Then, you'd output the endnotes: - -
-    .ENDNOTES
-
- -Then, you'd prepare mom for the next document: - -
-    .COLLATE
-    .TITLE "New Doc Title"
-    .AUTHOR "Josephine Blough"
-
- -Then, you'd redefine the header centre string using the reserved -string \*[$TITLE], like this: - -
-    .HEADER_CENTER "\E*[$TITLE]"
-
-

- -

-And last, you'd do: - -

-    .START
-
-

- -

-Voilà! Any argument you pass to TITLE from here -on in (say, for subsequent documents) is back in the header centre -position. Here's the whole routine again: - -

-    .HEADER_CENTER "Endnotes"
-    .ENDNOTES
-    .COLLATE
-    .TITLE         "New Doc Title"
-    .AUTHOR        "Josephine Blough"
-    .HEADER_CENTER "\E*[$TITLE]"
-    .START
-
-

- -

-If need be, you can concatenate the strings, as in the following -example. - -

-    .HEADER_CENTER "\E*[$CHAPTER_STRING] \E*[$CHAPTER]"
-
- -which, assuming a .CHAPTER_STRING of -"Chapter" and a .CHAPTER of -"2", would put "Chapter 2" in the -header centre position. -

- -

*Replacing header-left, -CENTER or -right with the page number

 - -

-If you would like to have the current page number to appear -header-left, -center, or -right instead of a text -string, invoke the appropriate macro, above, with the single -argument # (the "number" or -"pound" sign). Do NOT use -double-quotes. For example, - -

-    .HEADER_CENTER #
-
- -will print the current page number in the CENTER part of -headers. -

- -

*Including the page number in header-left, -CENTER or -right

 - -

-If you would like to include the current page number in -the string you pass to HEADER_LEFT, _CENTER, or -_RIGHT, use the special -inline escape -\*[PAGE#] in the string argument. -

- -

-For example, say you have a document that's ten pages long, and -you want header-right to say "page <whichever> of 10", -invoke .HEADER_RIGHT as follows: - -

-    .HEADER_RIGHT "page \*[PAGE#] of 10"
-
-

- -

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

- - - -
- -

Header/footer style

 - -

Global changes

 - -

-The following macros allow you to make changes that affect all -parts of the header at once. -

- -

-Please note that HEADER_FAMILY and -HEADER_FONT have no effect on -PRINTSTYLE TYPEWRITE. -

- - - -
- - - -

-Macro: HEADER_FAMILY <family> -

- -

-By default, mom uses the default document family -for headers. If you would like her to use another -family -in headers, invoke .HEADER_FAMILY with the identifier -for the family you want. The argument is the same as for the -typesetting macro -FAMILY. -

- -

-NOTE: Replace HEADER_, above, -with FOOTER_ to change the footer family. -

- -
- - - -

-Macro: HEADER_SIZE <+|-number of points> -
- -*Argument is relative to the point size of type in paragraphs -

- -

-By default, mom 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 .HEADER_SIZE with + or - the number of -points -(fractions allowed) by which you want her to in/decrease the size -of headers. For example, - -

-    .HEADER_SIZE +.75
-
- -increases the size of every part of a header by 3/4 of a point while -respecting mom's own little size changes. -

- -

-See -Arguments to the control macros -for an explanation of how control macros ending in -_SIZE work. -

- - - -

-NOTE: Replace HEADER_, above, -with FOOTER_ to change the footer size. -

- -

-ADDITIONAL NOTE: Normally, macros that control headers have no -effect on -PRINTSTYLE TYPEWRITE. -HEADER_SIZE is an exception. While all parts of a -header in PRINTSTYLE TYPEWRITE are always the same -size, you can use HEADER_SIZE with PRINTSTYLE -TYPEWRITE to reduce the header's overall point size. -You'll most likely require this when the -COPYSTYLE -is DRAFT, since portions of the header may overprint -if, say, the title of your document is very long. -

- -
- - - -

-Macro: HEADER_PLAIN -

- -

-By default, mom makes adjustments to the -font, size, and capitalization style of each part of headers -to achieve an aesthetically pleasing look. Should you wish to -design your own headers from the ground up without worrying how -changes to the various elements of header style interact with -mom's defaults, invoke .HEADER_PLAIN -by itself, with no argument. Mom will disable her -default behaviour for headers, and reset all elements of header -style to the same family, font, and point size as she uses in -paragraphs. -

- -

-NOTE: Replace HEADER_, above, with -FOOTER_ to disable mom's default -behaviour for the various elements of footer style. -

- -
- - - -

-Macro: HEADER_COLOR <colorname> -

- -

-If you want your headers in a colour different from the document -default (usually black), invoke .HEADER_COLOR with the -name of a colour pre-defined (or "initialized") with -NEWCOLOR -or -XCOLOR. -

- -

-HEADER_COLOR 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 -HEADER_<POSITION>_COLOR -to colourize each part of the header separately, as well as -HEADER_RULE_COLOR -to change the colour of the header rule. -

- -

-NOTE: Replace HEADER_, above, -with FOOTER_ to colourize footers. -

- -
- -

Part by part changes

 - -

-NOTE: When using the following control -macros, replace "<POSITION>" by LEFT, -CENTER, or RIGHT as appropriate. -

- - - -
- - - -

-Macro: HEADER_<POSITION>_FAMILY <family> -

- -

-Use HEADER_<POSITION>_FAMILY to change the -family -of any part of headers. See -Arguments to the control macros -for an explanation of how control macros ending in -_FAMILY work. -

- -

-NOTE: Replace HEADER_, above, -with FOOTER_ to change a footer part's family. -

- -
- - - -

-Macro: HEADER_<POSITION>_FONT <font> -

- -

-Use HEADER_<POSITION>_FONT to change the -font -of any part of headers. See -Arguments to the control macros -for an explanation of how control macros ending in -_FONT work. -

- -

-NOTE: Replace HEADER_, above, -with FOOTER_ to change a footer part's font. -

- -
- - - -

-Macro: HEADER_<POSITION>_SIZE <+|-number of points> -

- -

-Use HEADER_<POSITION>_SIZE to change the -size of any part of headers (relative to the point size of type in -paragraphs). See -Arguments to the control macros -for an explanation of how control macros ending in -_SIZE work. -

- -

-NOTE: Replace HEADER_, above, -with FOOTER_ to change a footer part's size. -

- -
- - - -

-Macro: HEADER_<POSITION>_CAPS toggle -

- -

-HEADER_<POSITION>_CAPS is a -toggle macro. -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 -reference macros -or as defined by you with the -header string control macros, -simply invoke this macro (using the appropriate position) with no -argument. If you wish to turn capitalization off (say, for the -header-right string that mom capitalizes by -default), invoke the macro with any argument (e.g. OFF, -QUIT, END, X...). -

- -

-NOTE: Replace HEADER_, above, -with FOOTER_ to change a footer part's -capitalization style. -

- -
- - - -

-Macro: HEADER_<POSITION>_COLOR <colorname> -

- -

-HEADER_<POSITION>_COLOR allows you to set a -colour for each of the three possible parts of a page header -separately. For example, say you want the right part of the header -(by default, the document title) in red, this is how you'd get it: - -

-    .HEADER_RIGHT_COLOR red
-
-

- -

-The other parts of the header will be in the default header colour -(usually black, but that can be changed with -HEADER_COLOR). -

- -

-Remember that you have to define (or "initialize") a -colour with -NEWCOLOR -or -XCOLOR -before you can use the colour. -

- -

-If you create a -user-defined header -with -HEADER_RECTO -or -HEADER_VERSO, -and you want various elements within the header to be colourized, -embed the colours in the string passed to HEADER_RECTO -or HEADER_VERSO with the -\*[<colorname>] -inline escape. -

- -

-NOTE: Replace HEADER_, above, -with FOOTER_ to set the colours for the various -elements of footers. -

- -
- - - -

Header/footer vertical placement and spacing

 - -

-See -Vertical placement and spacing of headers/footers -for an explanation of how mom deals with -headers, footers, and top/bottom page margins. -

- - - -
- - - -

-Macro: HEADER_MARGIN <distance to baseline of header> -
- -*Requires a unit of measure -

- -

-Use HEADER_MARGIN to set the distance from the -top edge of the page to the -baseline -of type in headers. A unit of measure is required, and decimal -fractions are allowed. -

- -

-Mom's default header margin is 4-1/2 -picas, -but if you want a different margin, say, 1/2-inch, do - -

-    .HEADER_MARGIN .5i
-
-

- -

-If your document uses -footers, -replace HEADER_, above, with -FOOTER_. The argument to -FOOTER_MARGIN is the distance from the bottom edge -of the page to the baseline of type in footers. -

- -

-Mom's default footer margin is 3 -picas. -

- - - -

FOOTER MARGIN AND BOTTOM MARGIN — VERY IMPORTANT!

- -

-Mom 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). -

- -

-If you set a bottom margin for your document (with -B_MARGIN, -prior to -START) -and the margin's too close to mom's default -footer margin (or a footer margin you set yourself -with FOOTER_MARGIN), mom 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 B_MARGIN or -FOOTER_MARGIN so there's an adequate amount of -space for mom to print the bottom line of running -text and the footer. -

- -

-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 -START, -as in these examples. -

- -
Example 1
- -
-    <reference macros, etc>
-    .PAGINATION    OFF
-    .B_MARGIN      .25i
-    .FOOTER_MARGIN O
-    .START
-
- -
Example 2
- -
-    <reference macros, etc>
-    .HEADERS       OFF
-    .PAGENUM_POS   TOP RIGHT
-    .B_MARGIN      .25i
-    .FOOTER_MARGIN O
-    .START
-
- -

A note on header/footer margins and page numbering

- -

-Mom uses HEADER_MARGIN and -FOOTER_MARGIN to establish the baseline -position of page numbers in addition to the baseline position of -headers and footers. -

- -

-By default, page numbers appear at the bottom of the page, therefore -if you want the default position (bottom), but want to change the -baseline placement, use FOOTER_MARGIN. Conversely, -if page numbers are at the top of the page, either because you turned -FOOTERS -on or because you instructed mom to put them -there with -PAGENUM_POS, -you'd use HEADER_MARGIN to change their -baseline placement. -

- - - -
- - - -

-Macro: HEADER_GAP <distance from header to start of running text> -
- -*Requires a unit of measure -

- -

-Use HEADER_GAP to set the distance from the -baseline -of type in headers to the start of -running text. -A unit of measure is required, and decimal fractions are allowed. -

- -

-As explained in -Vertical placement and spacing of headers/footers, -HEADER_MARGIN + HEADER_GAP determine the default -vertical starting position of running text on the page UNLESS you -have given mom your own top margin (with -T_MARGIN). If you give -a top margin, mom ignores -HEADER_GAP; running text starts at your stated top -margin. -

- -

-Mom's default header gap is 3 -picas, -but if you want a different gap, say, 2 centimetres, do - -

-    .HEADER_GAP 2c
-
-

- -

-If your document uses -footers, -replace HEADER_, above, with -FOOTER_. The argument to -FOOTER_GAP is the distance from the baseline of -type in footers to the last baseline of running text on the page. -

- -

-As explained in -Vertical placement and spacing of headers/footers, -FOOTER_MARGIN + FOOTER_GAP determine the default -vertical end position of running text on the page UNLESS you have -given mom a bottom margin (with -B_MARGIN). If you give -a bottom margin, mom ignores -FOOTER_GAP; running text ends at your stated bottom -margin. -

- -

-Mom's default footer gap is 3 -picas. -

- -

-NOTE: Mom uses -HEADER_GAP and -FOOTER_GAP to establish the start and end baseline -positions of running text with respect to both headers and footers -AND page numbers. If you wish to change the gap between -the last line of running text and a bottom page number, use -FOOTER_GAP. If page numbers are at the top of the -page, change the gap between the number and the first line of running -text with HEADER_GAP. -

- -
- - - -

Header/footer separator rule

 - -

-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 -header -and helps separate it visually from -running text. 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. -

- - - - - -
- - - -

-Macro: HEADER_RULE toggle -

- -

-By default, mom prints a header separator rule -underneath headers (or above footers). If you don't want the -rule, turn it off by invoking .HEADER_RULE with any -argument (OFF, QUIT, END, X...), e.g. - -

-    .HEADER_RULE OFF
-
-

- -

-To turn the rule (back) on, invoke .HEADER_RULE -without any argument. -

- -

-NOTE: Replace HEADER_, above, -with FOOTER_ to enable/disable the printing of -the footer separator rule. (Most likely, if you're using -FOOTERS, you'll want it off.) -

- - - -
- - - -

-Macro: HEADER_RULE_WEIGHT <weight in points> -
- -*Argument must NOT have a unit of measure appended -

- -

-HEADER_RULE_WEIGHT controls the weight -("thickness") of the header rule. Like -RULE_WEIGHT, -it takes a single argument: the weight of the header rule expressed -in -points -but without the unit of measure, p, appended. -The argument to HEADER_RULE_WEIGHT must be -greater than 0 and less than 100; decimal fractions are allowed. -

- -

-Say, for example, you want a really strong header separator rule. - -

-    .HEADER_RULE_WEIGHT 4
-
- -which sets the separator rule weight to 4 points, is how you'd do -it. -

- -

-Mom's default header rule weight is 1/2 point. -

- -

-NOTE: Replace HEADER_, above, with -FOOTER_ to set the weight of the footer separator -rule. -

- - - -
- - - -

-Macro: HEADER_RULE_GAP <distance of rule beneath header> -
- -*Requires a unit of measure -

- -

-HEADER_RULE_GAP is the distance from the -baseline -of type in headers to the top edge of the rule underneath. (If -FOOTER_RULE_GAP, the gap is the distance from the -top of the highest -ascender -to the bottom edge of the rule.) A unit of measure is -required, and decimal fractions are allowed. Please note that -HEADER_RULE_GAP has no effect on -HEADER_GAP -(i.e. HEADER_RULE_GAP is NOT added to -HEADER_GAP when mom calculates the -space between headers and the start of -running text). -

- -

-By default, the header rule gap is 4 -points. -If you'd like to change it to, say, 1/4 -em, do - -

-    .HEADER_RULE_GAP .25m
-
-

- -

-NOTE: Replace HEADER_, above, -with FOOTER_ if you're using -footers -and want to change the separator rule gap. In footers, the gap -is measured from the top of the tallest -ascender -in the footer. -

- -

-ADDITIONAL NOTE: When using -FOOTER_RECTO -and -FOOTER_VERSO, -make sure that the default size for footers -(FOOTER_SIZE) -is set to the largest size of type that will be used in the footer -or mom may not get the rule gap right. Inline -changes to the size of type in FOOTER_RECTO and -FOOTER_VERSO should always be negative (smaller) -than the default. -

- - - -
- - - -

-Macro: HEADER_RULE_COLOR <colorname> -

- -

-If you wish to change the colour of the header rule, invoke -.HEADER_RULE_COLOR with the name of a colour -pre-defined (or "initialized") with -NEWCOLOR -or -XCOLOR. -

- -

-Please note that HEADER_RULE_COLOR overrides the -colour set with -HDRFTR_COLOR, -so that it's possible to have the heads entirely in, say, blue (set -with HEADER_COLOR), and the header rule in, say, -red. -

- -

-NOTE: Replace HEADER_, above, -with FOOTER_ to change the colour of the footer -rule. -

- -
- - - -

Pagination

 - -

-By default, mom paginates documents. Page numbers -appear in the bottom margin of the page, centred between two hyphens. -As with all elements of mom's document processing, -most aspects of pagination style can be altered to suit your taste -with control macros. -

- -

Pagination macros list

 - - - - - -
- - - -

-Macro: PAGINATE toggle -
- -Alias: PAGINATION -

- -

-By default, mom paginates documents (in the bottom -margin). If you'd prefer she not paginate, turn pagination off -by invoking .PAGINATE with any argument (OFF, -NO, QUIT, END, X...), e.g. - -

-    .PAGINATE NO 
-
-

- -

-To (re)start pagination, invoke .PAGINATE without any -argument. -

- - - -
- - - -

-Macro: PAGENUMBER <number> -

- -

-As is to be expected, pagination of documents begins at page 1. If -you'd prefer that mom begin with a different number -on the first page of a document, invoke .PAGENUMBER with -the number you want. -

- -

-PAGENUMBER need not be used only to give -mom a "first page" number. It can be used at any -time to tell mom what number you want a page to -have. Subsequent page numbers will, of course, be incremented by 1 -from that number. -

- - - -
- - - -

-Macro: PAGENUM_STYLE DIGIT | ROMAN | roman | ALPHA | alpha -

- -

-PAGENUM_STYLE lets you tell -mom what kind of page numbering you want. -

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

-Macro: PAGENUM_ON_FIRST_PAGE toggle -

- -

-This macro applies only if you've enabled -FOOTERS. -If FOOTERS are on, mom -automatically places page numbers at the tops of pages except on the -first page of a document (or on first pages after -COLLATE). -If you'd like the page number to appear on "first" pages -when footers are on, invoke .PAGENUM_ON_FIRST_PAGE with -no argument. Any other argument turns the feature off (OFF, -QUIT, END, X...). -

- -

-As with most of the -control macros, -PAGENUM_ON_FIRST_PAGE 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 -COLLATE, omit it before the first -START -of the document, then invoke it either just before or after your -first COLLATE. -

- - - -
- - - -

-Macro: DRAFT_WITH_PAGENUMBER -

- -

-Sometimes, in -COPYSTYLE DRAFT, -the CENTER part of page headers gets overcrowded because of -the draft and revision information that go there by default. -DRAFT_WITH_PAGENUMBER is one way to fix the -problem. -

- -

-Invoked without an argument, .DRAFT_WITH_PAGENUMBER -removes draft/revision information from the page headers and -attaches it instead to the document's page numbering, in the form - -

-    Draft #, Rev. # / <pagenumber>
-
-

- -

-If you have not supplied mom with a draft number -(with -DRAFT) -DRAFT_WITH_PAGENUMBER will assume "Draft -1", and will print it before the page number. -

- -

-See the note in -COPYSTYLE DRAFT -for other ways of dealing with crowded page headers when formatting -draft-style copy. -

- -
- - - -

Pagination control macros

 - -
    -
  1. Family/font/size/colour
    2. -
  2. Page number position (vertical and horizontal)
    3. -
  3. Enclose page numbers with hyphens (on or off)
    4. -
- -

1. Page number family/font/size/colour

 - -

-See -Arguments to the control macros. -

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

2. Page number position

 - -

-Macro: PAGENUM_POS TOP | BOTTOM  LEFT | CENTER | RIGHT -

- -

-Use PAGENUM_POS to change the default position of -automatic page numbering. PAGENUM_POS requires -two arguments: a vertical position (TOP or BOTTOM) and a -horizontal position (LEFT or CENTER or RIGHT). -

- -

-For example, if you turn both -headers -and -footers -off (with .HEADERS OFF and -.FOOTERS OFF) and you want -mom to number your pages at the top right position, -enter - -

-    .PAGENUM_POS TOP RIGHT
-
-

- -

3. Enclose page numbers with hyphens (on or off)

 - -

-By default, mom encloses page numbers between -hyphens. If you don't want this behaviour, invoke the macro -PAGENUM_HYPHENS with any argument (OFF, -QUIT, END, X...), like this: - -

-    .PAGENUM_HYPHENS OFF
-
-

- -

-If, for some reason, you want to turn page number hyphens back -on, invoke the macro without an argument. -

- -
- -

-Next   -Prev   -Top   -Back to Table of Contents -

- - - - - diff --git a/contrib/mom/momdoc/inlines.html b/contrib/mom/momdoc/inlines.html deleted file mode 100644 index d197f739..00000000 --- a/contrib/mom/momdoc/inlines.html +++ /dev/null @@ -1,1074 +0,0 @@ - - - - - - -Mom -- Inline escapes - - - - - - - -

-Next   -Prev   -Back to Table of Contents -

- -

Inline escapes

 - -

-Introduction to inline escapes -
- -Index of inline escapes -

- -

Introduction to inline escapes

 - -

-Inline escapes, as described in the -groff terms -section of this manual, are typesetting commands that appear in text -input lines, -as opposed to macros and other -control lines -that must appear on lines by themselves. -

- -

-Aside from altering type parameters within a line, inlines also tell -groff about special characters — em-dashes, bullets, -figure/digit-width spaces, -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 -canonical reference materials -should you need more information than is contained herein. -

- -

-In groff, the escape character is the backslash (\). -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 (\\). Groff -understands that this means "please print a backslash character." -(You can also use \e to print a literal backslash.) -

- -

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

- -

-Mom recognizes that certain escapes get used more -often than others. For these, she has a consistent input style that -takes the form \*[...], which makes them stand out well -from the text of your documents. These escapes are the ones listed -under -Mom's personal inlines. -

- -

-Despite mom'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 -canonical reference materials -pertaining to groff. -

- -

-HELPFUL BIT OF INFORMATION: Inline escapes can be used -in -document processing macros -that take -string arguments. -

- -

Inlines index

 - - - -
- - - -

Mom's personal inlines

- -

Changing fonts

 - -

-Mom provides five escapes for changing fonts -inline: - -

-    \*[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.
-
-

- -

-These escapes are provided for merely for convenience, legibility, -and consistency when typesetting with mom. For -more complete and flexible inline font control, please see -font control with \f. -

- -

-NOTE CONCERNING DOCUMENT PROCESSING: If you're using the -document processing macros, -inline font changes remain in effect only for the duration of the -current document element tag. -

- -

-Additionally, if you're designing your own -HEADERS or FOOTERS -and want to use mom's inline escapes -for changing fonts inside the left, centre and/or right -strings, or in the strings for -recto -and/or -verso -HEADERS or FOOTERS, or in the strings passed to -HEADERS_AND_FOOTERS, -you must enter the inlines beginning with \E* -rather than just \*, e.g. \E*[BD]. -

- - - -
- -

Changing point size

 - -

-Mom has two inline escapes for changing point -size: - -

-    \*[SIZE <size>]
-
- -and - -
-    \*[S<size>]
-
- -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 - -
-    \*[SIZE 12]
-
- -or - -
-    \*[S12]
-
-

- -

-The advantage of the first form is that it's easy to remember, and -follows mom's usual inline syntax. The advantage -of the second is that it's more concise. -

- -

-Notice that in both cases, the new size does not require a -unit of measure; -points -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. -

- -

-The size given to \*[SIZE <size>] or -\*S[<size>] 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. - -

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

- -

-NOTE CONCERNING DOCUMENT PROCESSING: If you're using the -document processing macros -and wish to design your own -HEADERS or FOOTERS -using mom's inline escape -for changing point size inside the left, centre and/or right -strings, or in the strings for -recto -and/or -verso -HEADERS or FOOTERS, or in the strings passed to -HEADERS_AND_FOOTERS, -you must use the form \*S[<n>] -and enter the inline beginning with \E*, like this: -\E*S[<+|-><n>]. -

- -

-ADDITIONAL NOTE: If you're accustomed to groff's usual way -of handling inline size requests (\sN, \s±N, \s(NN, \s±(NN, -\s[NNN], \s±[NNN]), feel free to continue with your old habits. -Mom doesn't care. -

- - - -
- -

Capitalise a section of type

 - -

-If you need to capitalise a region of type inline, bracket the -region of type with the inline escapes, \*[UC] (Upper Case) -and \*[LC] (Lower Case), like this: - -

-    All work \*[UC]and\*[LC] no play makes Jack a dull boy.
-
- -The above produces, on output - -
-    All work AND no play makes Jack a dull boy.
-
-

- -

-NOTE: \*[UC] and \*[LC] -must not be used inside the -string arguments -passed to the -HEADER_<POSITION> -macro. Instead, use the -control macro -HEADER_<POSITION>_CAPS. -For -HEADER_RECTO -(or _VERSO) or -FOOTER_RECTO -(or _VERSO), supply the CAPS option to the appropriate -macro. -

- - - -
- -

Pairwise kerning

 - -

-Pairwise kerning means moving specific letter pairs closer -together or further apart (see -Typesetting terms, kerning -for more details). -

- -

-Mom permits inline pairwise -kerning through the use of the inline escapes - -

-    \*[BU <n>]  Closes the space between letters (Back Units).
-    \*[FU <n>]   Opens the space between letters (Forward Units).
-
- -"<n>" is the number of -kern units -by which to close or open the space between letters. -

- -

-For example, - -

-    THE HUMAN COST OF COMMODIF\*[FU 1]YING FRESH W\*[BU 4]A\*[BU 5]TER
-
- -moves the letter Y in "COMMODIFYING" -1 kern unit away from the letter F, and the -letter A in "WATER" 4 kern units closer -to the letter W. Additionally, the letter -T in "WATER" is moved 5 kern units closer to the -letter A. -

- -

-For backward compatibility, the forms - -

-    \*[BU1]...\*[BU36]   Move backward 1...36 kern units
-    \*[FU1]...\*[FU36]    Move forward 1...36 kern units
-
- -also exist (i.e. with no space before the number of kern units desired, -up to a limit of 36). -

- -

-NOTE CONCERNING DOCUMENT PROCESSING: If you're using the -document processing macros -and wish to design your own -HEADERS or FOOTERS -using mom's inline escapes -for kerning inside the left, centre and/or right -strings, or in the strings for -recto -and/or -verso -HEADERS or FOOTERS, or in the strings passed to -HEADERS_AND_FOOTERS, -you must use the forms \E*[BU<n>] -and \E*[FU<n>] (i.e. with no space), and enter the -inline beginning with \E* rather than just \*, -e.g. \E*[BU4]. -

- -

-ADDITIONAL NOTE: Using BU or FU -between characters pairs that are already automatically kerned -disables the automatic kerning and uses the value you give to -BU or FU instead. -

- - - -
- -

Horizontal inline movement

 - -

-Sometimes, you may need to insert a specified amount amount of white -space into an -output line, -or — occasionally — back up to a -previous position on an -output -line in order to create special typographic effects. -

- -

-Mom's inline escapes for these horizontal movements are - -

-    \*[BCK <n unit>]   Move backward inline the specified number of
-                       units of measure; decimal fractions are allowed.
-
-    \*[FWD <n unit>]    Move forward inline the specified number of
-                       units of measure; decimal fractions are allowed.
-
-

- -

-For example, - -

-    1.\*[FWD 12p]The Free Trade Play-Offs: WalMart 100, Mexico 0
-
- -puts 12 points of space between 1. and -The. -

- -

-NOTE: For backward compatibility, the forms - -

-    \*[BP.25]...\*[BP12.75]    Move backward .25...12.75 points
-    \*[FP.25]...\*[FP12.75]    Move forward .25...12.75 points
-
- -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, -\*[FP.5] or \*[BP1.25] up to a limit -of 12.75 points. -

- -

-NOTE CONCERNING DOCUMENT PROCESSING: If you're using the -document processing macros -and wish to design your own -HEADERS or FOOTERS -using mom's inline escapes for horizontal movements -inside the left, centre and/or right strings, or in the -strings for -recto -and/or -verso -HEADERS or FOOTERS, or in the strings passed to -HEADERS_AND_FOOTERS, -you must use the forms \E*[BP<n>] -and \E*[FP<n>] (i.e. with no space), and enter the -inline beginning with \E* rather than just \*, -e.g. \E*[BP.755]. -

- - - -
- -

Vertical inline movement

 - -

-If you need to move portions of type up or down on a line, -mom provides the following inline escapes: - -

-    \*[DOWN <n unit>]   Move down inline the specified number of
-                        units of measure
-
-    \*[UP <n unit>]     Move up inline the specified number of
-                        units of measure
-
-

- -

-For example, - -

-    Tel: 905\*[UP 1p]-\*[DOWN 1p]4072
-
- -moves the hyphen in the telephone number up by 1 point, then -moves back down by the same amount. -

- -

-NOTE: \*[UP] and \*[DOWN] do -not work with the inline escape, -\*[RULE]. -See -here -for details. -

- -

-ADDITIONAL NOTE: For backward compatibility, the -following are also available: - -

-    \*[ALD.25]...\*[ALD12.75]   Advance lead .25...12.75 points (move downward)
-    \*[RLD.25]...\*[RLD12.75]   Reverse lead .25...12.75 points (move upward)
-
-

- -

-Both \*[ALD] and \*[RLD] work in points, hence -you mustn't use a unit of measure. -

- -

-NOTE CONCERNING DOCUMENT PROCESSING: If you're using the -document processing macros -and wish to design your own -HEADERS or FOOTERS -using mom's inline escapes for vertical movements -inside the left, centre and/or right strings, or in the -strings for -recto -and/or -verso -HEADERS or FOOTERS, or in the strings passed to -HEADERS_AND_FOOTERS, -you must use the forms \E*[ALD<n>] -and \E*[RLD<n>] (i.e. with no space), and enter the -inline beginning with \E* rather than just \*, -e.g. \E*[ALD.5]. -

- - - -
- -

Terminate a line without advancing on the page

 - -

-Sometimes, you want mom to break a line but not -advance on the page. See -here -for an example of when you might want to do this. -

- -

-In versions of mom prior to 1.2-f, this was -accomplished through the use of the -EL -macro. As of 1.2-f, you can, if you prefer, accomplish the same -thing by using the inline escape, \*[B]. Simply attach -the escape to the end of any input line. Using the example -given in the document entry for EL, you'd use -\*[B] like this: - -

-    .LEFT
-    .LS 12.5
-    A line of text.\*[B]
-    .ALD 24p
-    The next line of text.
-
- -\*[B] works reliably regardless of the current -fill mode. -

- - - -
- -

Call the next sequential tab without advancing on the page

 - -

-Sometimes, you want mom to move to the next tab in -sequence (e.g. from TAB 1 to TAB 2, or TAB 8 to TAB 9) without -mom advancing on the page. (See the NOTE -here -if you're not clear how mom manages tabs and -linebreaks.) -

- -

-In versions of mom prior to 1.2-f, this was -accomplished through the use of -TN. -As of 1.2-f, you can, if you prefer, accomplish the same thing by -using the inline escape, \*[TB+]. Simply attach the -escape to the end of any input line in a tab, like this: - -

-    .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
-
- -\*[TB+] works reliably regardless of the current -fill mode. -

- - - -
- -

Full measure rules

 - -

-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 \l'\n(.lu', -which is annoying to type, and doesn't mean a whole heck of a lot if -you're new to groff. The inline, \*[RULE], is a simple -replacement for \l'\n(.lu'. Use it whenever you need -a rule drawn to the full measure of the current line or tab length, for -example: - -

-    .LL 6P
-    \*[RULE]
-
- -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, -DRH. -

- -

-\*[RULE] must appear on an -input line -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. -

- -

-The weight of the rule drawn with \*[RULE] is controlled -with the macro -RULE_WEIGHT. Mom's -default is 1/2 point. -

- -

-Please note that \*[RULE] draws the rule to the full -measure, hence it cannot be used to fill the remainder of a -partial line with a rule in this way: - -

-    Signature__________________________________________
-
-

- -

-If you wish to accomplish this effect, you have to use -\*[RULE] in conjunction with the -PAD -macro and -string tabs. -(See the -example -provided with PAD.) - -

- -

-Please also note that the inline escapes -\*[UP] -and -\*[DOWN] -cannot be used in conjunction with \*[RULE]. This -doesn't work: - -

-    \*[DOWN 2p]\*[RULE]\*[UP 2p]
-
-

- -

-This does: - -

-    .ALD 2p
-    \*[RULE]
-    .RLD 2p
-
-

- -

-See groff's -Horizontal line drawing function -for more information on drawing horizontal rules. -

- - - -
- - - -

-Macro: RULE_WEIGHT <weight in points> -
- -*Argument must be greater than 0 and less than 100; decimal -fractions are allowed -
- -*Must not have a unit of measure appended -

- -

-RULE_WEIGHT allows you to tell mom -how heavy (in other words, how "thick") you want the rules -drawn with the inline escape, -\*[RULE]. -It takes a single argument: the weight of the rule in -points -but without the -unit of measure -p attached. Thus, to set the weight of rules -drawn with \*[RULE] to 1-1/4 points, you'd do - -

-    .RULE_WEIGHT 1.25
-
-

- -

-RULE_WEIGHT also sets the weight of rules drawn -with -.DRH -when DRH is not given any arguments. -

- -
- - - -

Groff inline escapes

- -

Font control (\f)

 - -

-Groff's basic mechanism for inline font control is the escape -\f[<font>]. -

- -
-    \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])
-
- -

-\f[<font>] can be used with any valid -font style -registered with groff. (See -here -for a list of pre-registered font styles provided by -mom). -

- -

-\f[<font>] 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: - -

-    .FAM T
-    .FT  R
-    The command \f[CBI]ls -l\f[P] gives a "long" directory listing.
-
- -The Unix command ls -l will appear in -Courier Bold Italic in a line that is otherwise in Times Roman. -

- - - -
- -

Inline horizontal motions (\h)

 - -

-Whenever you need to move forward or backward on a line, use -the inline - -

-    \h'<distance>'
-
-

- -

-In order to avoid unpleasant surprises, always append a -unit of measure -to <distance>. For example, - -

-    \h'1.25i'
-
- -moves you 1.25 inches to the right (forward) of the horizontal -position on the current -output line. -\h'<distance>' is exactly equivalent to -\*[FWD n<unit>]. -

- -

-To move backwards by the same amount, do - -

-    \h'-1.25i'
-
- -\h'-<distance>' is exactly equivalent to -\*[BCK n<unit>]. -

- - - -
- -

Inline vertical motions (\v)

 - -

-If you need to raise or lower type on a line (say, for sub- or -superscripts, or any other special effect), use - -

-    \v'<distance>'
-
-

- -

-In order to avoid unpleasant surprises, always append a -unit of measure -to "distance". For example, - -

-    \v'.6m'
-
- -moves you (approx.) 2/3 of an -em -downward on the current -output line. -\v'<distance>' is exactly equivalent to -\*[DOWN n<unit>]. -

- -

-To move upward an equivalent amount, do - -

-    \v'-.6m'
-
-

- -

-\v'<-distance>' is exactly equivalent to \*[UP n<unit>]. -

- -

-IMPORTANT: The vertical motion of \v -affects ONLY type on the current -output line. -When groff breaks the output line, the effect of -\v is cancelled; the baseline of the next output line -is where it would be if you hadn't used \v. -

- -

-TIP: When using \v 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 \v with the minus sign) or too low -(if you used \v without the minus sign). -

- - - -
- -

String width function (\w)

 - - -

-In the context of mom, the string width inline -\w'string' 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 \w inline escape: - -

-    .IL "\w'Examples: '"
-
-

- -

-NOTE: Whenever you pass \w'string' -to a macro that normally requires a -unit of measure, -do NOT add a unit of measure to the -\w'string' argument. -

- -

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

- - - -
- -

Horizontal line drawing function (\l)

 - -

-The \l'distance' inline allows you to draw a -horizontal rule of the specified distance. You must supply a -unit of measure. -Therefore, to set a 3-pica rule into a line of text, you'd do - -

-    A line of text with a superfluous \l'3P' 3-pica rule in it.
-
-

- -

-\l'3P' above not only draws the rule, but advances 3 -picas horizontally as well, just as you'd expect. -

- -

-For an easy way of drawing rules to the full measure of the current -line or tab length, see -Full measure rules. -

- -

-The weight (thickness) of rules varies according to the point -size in effect when you invoke \l, 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). -

- -

-NOTE: Besides \l, groff -provides a number of more sophisticated "drawing" -escapes. It is well beyond the scope of this documentation -to demonstrate their usage; see -info groff => Escape index => \D -for directions concerning their use. The drawing escapes -can be a bit unwieldy, so mom provides -"user-friendly" macros for the -graphical objects -most commonly enountered in typesetting: horizontal and vertical -rules, boxes, and circles (ellipses). -

- -

-Additionally, groff comes with two -"preprocessors" that let you create ruled tables and -vector diagrams (line drawings): tbl and -pic. The documentation -for tbl can be downloaded from - -

-    http://cm.bell-labs.com/cm/cs/doc/76/tbl.ps.gz;
-
- -pic from - -
-    http://www.kohala.com/start/troff/gpic.raymond.ps.
-
- -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 .PSPIC (consult man -groff_tmac for information on this indispensable and -easy-to-use macro). -

- - - -
- -

Special characters and symbols

 - -

-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 -Definitions of Terms. -

- -

-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 -man groff_char. - -

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

- -
- -

-Next   -Prev   -Top   -Back to Table of Contents -

- - - - - diff --git a/contrib/mom/momdoc/intro.html b/contrib/mom/momdoc/intro.html deleted file mode 100644 index c1819e67..00000000 --- a/contrib/mom/momdoc/intro.html +++ /dev/null @@ -1,517 +0,0 @@ - - - - - - -What is mom? - - - - - - - -

-Next   -Back to Table of Contents -

- -

-

What is mom?

- -Who is mom meant for? -
- -Typesetting with mom -
- -Document processing with mom -
- -Mom's philosophy -
- -A note on mom's documentation -
- -Canonical reference materials -
- -How to read macro arguments -

- -

Who is mom meant for?

 - -

-Mom ("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: -

- -
    -
  1. 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 - primitives; -
    2. -
  2. non-scientific writers (novelists, short story writers, - journalists, students) who just want their work to - look good; -
    3. -
  3. newbies to computer typesetting, document processing, or - groff who need a well-documented macro set to help them get - started. -
    4. -
- -

-As might be inferred from the above, mom is two macro -packages in one: a set of typesetting macros, and a set of document -formatting macros. The typesetting macros govern the physical -aspects of page layout and provide sane, comprehensible control over -typographic refinements. The document formatting macros let you focus -on a document's content and logical structure without worrying about -typesetting or page layout at all. -

- -

-Because mom 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 mom's document element tags, you don't have to -read up on groff -primitives -in order to accomplish what you want; the typesetting macros take -care of that. -

- -

Typesetting with mom

 - -

-Mom'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. -

- -

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

- -

-With mom's typesetting macros, you can, if you wish, -create individual output pages that you design from the ground up. -Provided you have not signalled to mom that you -want document processing (via the -START -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. -

- -

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

- -

-Mom does not try to solve the problems posed -by things like hanging punctuation, left-margin adjustments for -upper case letters like T and W, and so on. She merely tries to -provide tools that allow knowledgeable typesetters to come up with -solutions to these problems in ways that are easier and more -intuitive than manipulating groff at the -primitive -level. As a professional typesetter of more than two decades, and a -writer, I have encountered few situations that cannot be handled by -mom's typesetting macros. -

- -

-Author's note: One area where groff itself needs -serious rethinking is in the matter of an algorithm that takes into -account both word and letter spacing when -justifying -lines. At present, only word spacing is adjusted, requiring what I -consider an unnecessary amount of user intervention whenever -letter spacing is required. -

- -

Document processing with mom

 - -

-Mom's document processing macros let you format -documents without having to worry about the typographic details. -In this respect, mom is similar to other groff macro -packages, as well as to html and LaTeX. Where mom -differs is in the degree of control you have over the look and -placement of the various elements of a document. For example, if you -don'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. -

- -

-Mom 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 — -PRINTSTYLE TYPEWRITE -— 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. -

- -

Mom's philosophy

 - -

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

- -

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

- -

-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 -primitives -and -inline escapes -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. -

- -

-Mom aims to make creating documents a simple matter, -but with no corresponding loss of user control. The document -processing macros provide an excellent set of defaults, but if -something is not to your liking, you can change it. And in combination -with the typesetting macros, you have all the tools you need to -massage passages and tweak pages until they look utterly professional. -

- -

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

- -

-Mom does not try to be all things to all people. -In contrast to the normal groff philosophy, she does not try to -produce output that looks good no matter where it's displayed. -She's designed for printed output, although with -PRINTSTYLE TYPEWRITE -she produces acceptable terminal copy. She makes no attempt to be -compatible with older versions of troff. -

- -

-One special feature in mom'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, mom does -avoid them, by clever adjustments to leading ("line spacing") -and the spacing between different elements on the page. -

- -

A note on mom's documentation

 - -

-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 whom the documentation is for. Making the wrong decision can -mean the difference between a program that gets used and a program -that gets tossed. -

- -

-Mom's documentation assumes users know their -way around their own operating system (basic file management, -how to invoke commands, how to use a text editor, etc). I use -GNU/Linux, and while the documentation may exhibit a GNU/Linux bias, -mom and groff can, in fact, be used on a variety of -other popular operating systems, including the one from Redmond, -Virginia, USA. -

- -

-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 mom'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. -

- -

Canonical reference materials

 - -

-The canonical reference materials for groff are -cstr54 (a downloadable PostScript copy of which is -available -here) -and the troff and groff_diff -manpages. Another excellent source of information (maybe the best) -is the groff info pages, available by typing - -

-    info groff
-
- -at the command line (assuming you have the TeXinfo -standalone browser installed on your system, which is -standard for most GNU/Linux distributions). And for -inputting special characters, see man groff_char. -

- -

-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 -mom users up and running. Mea culpa. -

- -

-Note: Mom'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. -

- -

-Addendum: As of version 1.4-a, the main macro -file, om.tmac, is now stripped of comments when groff is built -from sources. om.tmac in the sources themselves still contains -the comments, as do the tarballs posted on mom's -homepage. -

- -
- -

How to read macro arguments

 - -

-The concise descriptions of macros in this documentation typically -look like this: - -

- Macro: NAME arguments -
-

- -

-arguments lists the macro's arguments using conventions that -should be familiar to anyone who has ever read a manpage. Briefly: - -

    -
  1. Macro arguments are separated from each other by spaces. -
    2. -
  2. If an argument is surrounded by chevrons - (< >), it's a description - of the argument, not the argument itself. -
    3. -
  3. If an argument begins with or is surrounded by double-quotes, the - double quotes MUST be included in the argument. -
    4. -
  4. If the user has a choice between several arguments, each of the - choices is separated by the pipe character - (|), which means "or." -
    5. -
  5. Arguments that are optional are surrounded by square brackets. -
    6. -
  6. <off> in an argument list means that any - argument other than those in the argument list turns the - macro off. -
    7. -
-

- -

Toggle macros

 - -

-Some macros don't require an argument. They simply start something. -When you need to turn them off, the same macro with any -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. -

- -

-Since these macros toggle things on and off, the argument list -simply reads - -

- toggle -
-

- -

Example 1: An argument requiring double-quotes

- -
- Macro: TITLE "<title of document>" -
- -

-The required argument to TITLE is the title of your -document. Since it's surrounded by double-quotes, you must -include them in the argument, like this: - -

-    .TITLE "My Pulitzer Novel"
-
-

- -

Example 2: A macro with required and optional arguments

- -
- Macro: TAB_SET <tab number> <indent> <length> [ L | R | C | J [ QUAD ] ] -
- -

-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: - -

-    .TAB_SET 3 6P 3P
-
-

- -

-The remaining two arguments are optional. The first is a single -letter, either L, R, C or J. The second, -which is itself optional after L, R, C or J, -is the word QUAD. Therefore, depending on what -additional information you wish to pass to the macro, you could -enter: - -

-    .TAB_SET 3 6P 3P L
-        or
-    .TAB_SET 3 6P 3P L QUAD
-
-

- -

Example 3: A sample toggle macro:

 - -
- Macro: QUOTE toggle -
- -

-QUOTE begins a section of quoted text in a document -and doesn't require an argument. When the quote's finished, -you have to tell mom it's done. - -

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

- -

-Alternatively, you could have turned the quote off with -END, or X, or something else. -

- -
- -

-Next   -Top   -Table of Contents -

- - - - diff --git a/contrib/mom/momdoc/letters.html b/contrib/mom/momdoc/letters.html deleted file mode 100644 index d06c8cfd..00000000 --- a/contrib/mom/momdoc/letters.html +++ /dev/null @@ -1,609 +0,0 @@ - - - - - - -Mom -- Document Processing, Writing Letters - - - - - - - -

-Next   -Prev   -Back to Table of Contents -

- -

Writing letters with mom

 - -

Introduction

 - -

-Mom's simple but effective letter-writing -macros are a subset of the -document processing macros, -designed to ease the creation of correspondence. -

- -

-Because the letter macros are a subset of the document -processing macros, you can use -control macros -to design correspondence to your own specifications. However, -mom makes no pretence of providing complete design -flexibility in the matter of letters, which are, after all, simple -communicative documents whose only real style requirements are that -they be neat and professional-looking. -

- -
- -

-

Tutorial on writing letters

-

- -

-Mom letters begin, like all -mom-processed documents, with a -reference macro -(in this case, -AUTHOR), -a -DOCTYPE -(LETTER, obviously), the essential -PRINTSTYLE -macro, and -START, -like this: - -

-    .AUTHOR    "Yannick P. Guique"
-    .DOCTYPE    LETTER
-    .PRINTSTYLE TYPESET
-    .START
-
-

- -

-PRINTSTYLE, above, could also be -TYPEWRITE. Mom has no objection to -creating letters that look like they were typed on an Underwood by a -shapely secretary with 1940s gams. -

- -

-After the START macro, you enter headers pertinent -to your letter: the date, the addressee (in business correspondence, -typically both name and address), the addresser (that's you; in -business correspondence, typically both name and address), and a -greeting (in full, e.g. "Dear Mr. Smith," or "Dear -Mr. Smith:"). -

- -

-The macros for entering the headers are simple (they're not even -toggles): - -

-    .DATE
-    .TO
-    .FROM
-    .GREETING
-
-

- -

-You may enter them in any order you like, except for -GREETING, which must come last. -Mom ignores any headers you omit and spaces the -letter's opening according to what you do include. See -Default for letters -to find out how mom formats the headers. -

- -

-(In pre 1.1.7-a releases of mom, the order -of entry was fixed at the above. This has been changed, although -if you do follow the above order, mom will -continue to behave exactly as she did in pre 1.1.7-a.) -

- -

-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 -PP -macro. -

- -

-At the end of the letter, should you wish an indented closing -("Yours truly," "Sincerely," "Hugs and -kisses"), invoke the macro, .CLOSING, on a -line by itself and follow it with the text of the closing. -N.B. Don't put your name here; mom -supplies it automatically from AUTHOR with -enough space to leave room for your signature. -

- -

-Assuming our tutorial letter is for business correspondence, -here's what the complete letter looks like. -

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

-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: - -

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

- -

-Notice the use of .RIGHT after .FROM and -.DATE in this example, used to change the default quad -for these macros. -

- -
- -

Defaults for letters

 - -

-In letters, if the order of header macros is - -

-    .DATE
-    .TO
-    .FROM
-    .GREETING
-
- -mom sets - -
    -
  1. the date flush right, page right, at the top of page one, - with a gap of two linespaces underneath -
    2. -
  2. the addressee in a block flush left, page left, with a gap of - one linespace underneath -
    3. -
  3. the addresser in a block flush left, page left, with a gap of - one linespace underneath -
    4. -
  4. the greeting flush left, with a gap of one linespace - underneath -
    5. -
-

- -

-which is the standard for North American business correspondence. -

- -

-If you switch the order of .DATE, .TO and/or -.FROM, mom sets all the headers -flush left, with a gap of one linespace underneath each. (The -default left quad of any header can be changed by invoking the -.RIGHT macro, on a line by itself, immediately before -inputting the text of the header.) -

- -

-Following the headers, mom sets - -

-

- -

-Other important style defaults are listed below, and may be changed -via the -typesetting macros -or the document processing -control macros -prior to -START. Assume that any -style parameter not listed below is the same as for -PRINTSTYLE TYPESET -or -PRINTSTYLE TYPEWRITE. -

- -
-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 .../#
-
- -
- -

The letter macros

 - -

-All letter macros must come after -START, -except NO_SUITE. -

- - - - - -
- - - -

-Macro: DATE -

- -

-Invoke .DATE on a line by itself, with the date -underneath, like this: - -

-    .DATE
-    October 31, 2002
-
-

- -

-If you wish to change the default quad direction for the date, -enter .LEFT or .RIGHT, on a line by itself, -immediately after .DATE. -

- -

-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: - -

-    .DATE
-    October 31, 2002
-    .SPACE     \"Or, more simply, .SP
-
-

- -

-If you wish to remove the default space, - -

-    .SPACE -1v \"Or, more simply, .SP -1v
-
- -will do the trick. -

- - - -
- - - -

-Macro: TO -

- -

-Invoke .TO on a line by itself, with the name -and address of the addressee underneath, like this: - -

-    .TO
-    JOHN SMITH
-    10 Roberts Crescent
-    Bramladesh, Ont.
-
-

- -

-If you wish to change the default quad direction for the address, -enter .LEFT or .RIGHT, on a line by itself, -immediately after .TO. -

- -

-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: - -

-    .TO
-    JOHN SMITH
-    10 Roberts Crescent
-    Bramladesh, Ont.
-    .SPACE     \"Or, more simply, .SP
-
-

- -

-If you wish to remove the default space, - -

-    .SPACE -1v \"Or, more simply, .SP -1v
-
- -will do the trick. -

- - - -
- - - -

-Macro: FROM -

- -

-Invoke .FROM on a line by itself, with the name -and address of the addresser underneath, like this: - -

-    .FROM
-    JOE BLOW
-    15 Brunette Road
-    Ste-Vieille-Andouille, Québec
-
-

- -

-If you wish to change the default quad direction for the address, -enter .LEFT or .RIGHT, on a line by itself, -immediately after .FROM. -

- -

-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: - -

-    .FROM
-    JOE BLOW
-    15 Brunette Road
-    Ste-Vieille-Andouille, Québec
-    .SPACE     \"Or, more simply, .SP
-
-

- -

-If you wish to remove the default space, - -

-    .SPACE -1v \"Or, more simply, .SP -1v
-
- -will do the trick. -

- - - -
- - - -

-Macro: GREETING -

- -

-Invoke .GREETING on a line by itself, with the -full salutation you want for the letter, like this: - -

-    .GREETING
-    Dear Mr. Smith,
-
-

- - - -
- - - -

-Macro: CLOSING -

- -

-Invoke .CLOSING on a line by itself after the body of the -letter, with the closing you'd like (e.g. "Yours truly,"), -like this: - -

-    .CLOSING
-    Yours truly,
-
-

- -

-There are two macros that may be used to control the behaviour -of .CLOSING: CLOSING_INDENT and -SIGNATURE_SPACE. -

- - -

-The first, CLOSING_INDENT, indicates the distance -from the left margin you'd like to have your closing indented. It -takes a single -numeric argument -and must have a -unit of measure -appended to it, unless you want an indent of 0 (zero). -Mom's default is 1/2 the width of the letter's line -length (i.e. halfway across the page). If you wanted instead an -indent of 6 -picas, -you'd do it like this: - -

-    .CLOSING_INDENT 6P
-
- -Or, if you wanted to have no indent at all: - -
-    .CLOSING_INDENT 0
-
-

- - -

-The second, SIGNATURE_SPACE, controls how much room -to leave for the signature. It takes a single -numeric argument -and must have a -unit of measure -appended to it. Mom's default is 3 line spaces, -but if you wanted to change that to, say, 2 line spaces, you'd do: - -

-    .SIGNATURE_SPACE 2v
-
-

- - - -
- - - -

-Macro: NO_SUITE -

- -

-If you don't want mom to print a "next -page" number at the bottom of multi-page letters, invoke -.NO_SUITE, on a line by itself, prior to -START. -

- -
- -

-Next   -Prev   -Top   -Back to Table of Contents -

- - - - - diff --git a/contrib/mom/momdoc/macrolist.html b/contrib/mom/momdoc/macrolist.html deleted file mode 100644 index 3c79d259..00000000 --- a/contrib/mom/momdoc/macrolist.html +++ /dev/null @@ -1,489 +0,0 @@ - - - - - - -Mom -- Quick reference guide - - - - - - - -

-Next   -Prev   -Back to Table of Contents -

- -

Quick reference guide to mom

- -

-Once you know your way around mom, you may find -this guide preferable to using the Table of Contents. It lists -mom's major user-space macros. The links point to -references found elsewhere in the documentation. -

- -

Index to the quick reference guide

- -
-TYPESETTING MACROS                     DOCUMENT PROCESSING MACROS
-==================                     ==========================
-Paper size, margins, line length       Reference macros
-Family, font, point size               General document formatting directives
-Font modifications                     Line numbering
-Linespacing (leading)                  Set documents in columns
-Justification, quad, breaking lines    TYPEWRITE control macros
-Hyphenation                            Initiate document processing
-Word and sentence spacing              Epigraphs
-Kerning, ligatures, smartquotes        Main heads
-Horizontal/vertical motions, columns   Subheads
-Indents                                Paragraph heads
-Tabs                                   Paragraphs
-Underscoring, underlining              Quotes (line by line verbatim quotes) 
-Superscipts                            Blockquotes (cited passages of text)
-Nested lists                           Code snippets (inserting bits of programming code)
-Colour                                 Author linebreaks (section breaks)
-Dropcaps                               Document termination string
-Utilities                              Footnotes
-Graphical Objects                      Endnotes
-                                       Margin notes
-                                       Bibliographic references
-                                       Tables of contents
-                                       Letter (correspondence) macros
-                                       Changing global print style parameters after START
-                                       Managing a document's first-page header (the "docheader")
-                                       Managing page headers and footers
-                                       Recto/verso page headers and footers
-                                       Pagination
-                                       Document and section cover (title) pages
-                                       Utilities
-
- -
- -

The Quick Reference Guide

- -
-TYPESETTING MACROS
-==================
-
-+++ Paper size, margins, line length
-    PAPER      -- set common paper sizes (letter, A4, etc)
-    PAGEWIDTH  -- set a custom page width
-    PAGELENGTH -- set a custom page length
-    PAGE       -- set explicit page dimensions and margins
-    T_MARGIN   -- set a top margin
-    B_MARGIN   -- set a bottom margin
-    L_MARGIN   -- set a left margin (page offset)
-    R_MARGIN   -- set a right margin
-    LL         -- set a line length
-
-+++ Family, font, point size
-    FAMILY        -- set the family of type
-    FT            -- set the font style (roman, italic, etc)
-    FALLBACK_FONT -- establish a fallback font (for missing fonts)
-    PT_SIZE       -- set the point size
-    \*[SIZE n]    -- change the point size inline
-
-+++ Font modifications
-    * Pseudo italic
-      SETSLANT   -- set the degree of slant
-      \*[SLANT]  -- invoke pseudo italic inline
-      \*[SLANTX] -- turn off pseudo italic inline
-
-    * Pseudo bold
-      SETBOLDER   -- set the amount of emboldening
-      \*[BOLDER]  -- invoke pseudo bold inline
-      \*[BOLDERX] -- turn off pseudo bold inline
-
-    * Pseudo condensed 
-      CONDENSE  -- set the amount to pseudo condense
-      \*[COND]  -- invoke pseudo condensing inline
-      \*[CONDX] -- turn off pseudo condensing inlines
-
-    * Pseudo extended
-      EXTEND   -- set the amount to pseudo extend
-      \*[EXT]  -- invoke pseudo extending inline
-      \*[EXTX] -- turn off pseudo condensing inlinee
-
-+++ Linespacing (leading)
-    LS       -- set the linespacing (leading)
-    AUTOLEAD -- set the linespacing relative to the point size
-
-+++ Justification, quad direction, line-by-line setting, breaking lines
-    JUSTIFY -- justify text to both margins
-    QUAD    -- "justify" text left, centre, or right
-    LEFT    -- set line-by-line quad left
-    CENTER  -- set line-by-line quad centre
-    RIGHT   -- set line-by-line quad right
-    BR      -- break a justified line
-    SPREAD  -- force justify a line
-    EL      -- break a line without advancing on the page
-
-+++ Hyphenation
-    HY     -- turn automatic hyphenation on or off
-    HY_SET -- set automatic hyphenation parameters
-
-+++ Word and sentence spacing
-    WS -- set the minimum word space size
-    SS -- set the sentence space size
-
-+++ Kerning, ligatures, smartquotes
-    KERN            -- turn automatic character pair kerning on or off
-    \*[BU n]        -- move characters pairs closer together inline
-    \*[FU n]        -- move character pairs further apart inline
-    RW              -- uniformly reduce space between characters (tighten)
-    EW              -- uniformly increase space between characters (loosen)
-    BR_AT_LINE_KERN -- break previous line every time RW or EW is invoked
-    LIGATURES       -- turn automatic generation of ligatures on or off
-    SMARTQUOTES     -- turn smartquoting on or off
-
-+++ Horizontal and vertical movements, columnar setting
-    ALD        -- move downards on the page
-    RLD        -- move upwards on the page
-    SPACE      -- insert space between lines on a page
-    \*[DOWN n] -- temporarily move downwards in a line
-    \*[UP n]   -- temporarily move upwards in a line
-    \*[FWD n]  -- move forward in a line
-    \*[BCK n]  -- move backwards in a line
-    MCO        -- turn multiple columns on
-    MCR        -- return to vertical position of column start
-    MCX        -- turn multiple columns off, advance past longest column
-
-+++ Indents
-    IL  -- set and turn on a left indent
-    IR  -- set and turn on a right indent
-    IB  -- set and turn on indents both left and right
-    IQ  -- quit (exit) all indents
-    TI  -- set and turn on a temporary (one line) indent
-    HI  -- set and turn on a hanging indent
-    ILX -- turn left indents off
-    IRX -- turn right indents off
-    IBX -- turn both left and right indents off
-
-+++ Tabs
-    TAB_SET            -- set up a typesetting tab
-    TAB <n>            -- call tab <n>
-    TQ                 -- quit (exit) tabs
-    \*[STn]...\*[STnX] -- mark off tab positions inline
-    TN                 -- move to tab <n+1> without advancing on the page
-    ST                 -- set up tabs whose positions were marked inline
-
-+++ Underscoring, underlining
-    UNDERSCORE       -- underscore type
-    UNDERSCORE2      -- double underscore type
-    UNDERLINE        -- underline type (fixed width fonts only)
-    \*[UL]...\*[ULX] -- invoke underling inline (fixed width fonts only)
-
-+++ Superscipts
-    \*[SUP]...\*[SUPX]         -- set characters superscript (inline)
-    \*[CONDSUP]...\*[CONDSUPX] -- set pseudo condensed characters superscript (inline)
-    \*[EXTSUP]...\*[EXTSUPX]   -- set pseudo extended characters superscript (inline)
-    SUPERSCRIPT_RAISE_AMOUNT   -- set vertical raise of superscript
-
-+++ Nested lists
-    LIST            -- initiate a nested list
-    ITEM            -- begin an item in a list
-    SHIFT_LIST      -- change the indent of a list
-    RESET_LIST      -- clear and reset a list's enumerator
-    PAD_LIST_DIGITS -- space to leave for digits in a digit-enumerated list
-
-+++ Colour
-    NEWCOLOR        -- initialize (define) a colour
-    COLOR           -- begin using an initialized colour
-    XCOLOR          -- initialize a "named" X colour
-    \*[<colorname>] -- being using an initialized colour inline
-
-+++ Dropcaps
-    DROPCAP        -- set a dropcap
-    DROPCAP_FAMILY -- set a dropcap's family
-    DROPCAP_FONT   -- set a dropcap's font style
-    DROPCAP_COLOR  -- set a dropcap's colour
-    DROPCAP_ADJUST -- adjust size of a dropcap
-    DROPCAP_GUTTER -- adjust space between a dropcap and regular text
-
-+++ Utilities
-    ALIAS            -- give a macro a new name
-    CAPS             -- set type all caps
-    COMMENT          -- silently embed comments in a document
-    ESC_CHAR         -- change the default escape character
-    \*[LEADER]       -- insert leaders at the end of a line
-    LEADER_CHARACTER -- change the character used for leaders
-    NEWPAGE          -- break to a new page
-    PAD              -- insert equalized regions of whitespace into a line
-    PAD_MARKER       -- change the character that identifes padding locations
-    \*[RULE]         -- draw a full measure rule
-    SIZESPECS           -- get cap-height, x-height and descender depth of a font
-    SILENT           -- turn output processing off or on
-    TRAP             -- enable or disable page position traps
-
-+++ Graphical objects
-    DRH              -- draw a horizontal rule
-    DRV              -- draw a vertical rule
-    DBX              -- draw a box
-    DCL              -- draw a circle (ellipse)
-    RULE_WEIGHT      -- set weight of rules drawn with \*[RULE]
-    PSPIC            -- insert a PostScript image
-
- -
- -
-DOCUMENT PROCESSING MACROS
-==========================
-
-+++ Reference macros
-    TITLE           -- document title
-    DOCTITLE        -- overall document title (if different from TITLE)
-    ENDNOTE_TITLE   -- document/chapter identification string for endnotes
-    CHAPTER         -- chapter number
-    CHAPTER_TITLE   -- chapter title
-    CHAPTER_STRING  -- what to use in place of "Chapter"
-    SUBTITLE        -- document subtitle
-    AUTHOR          -- document author(s)
-    DOC_COVERTITLE  -- document title cover
-    COVERTITLE      -- section cover title
-    COPYRIGHT       -- copyright
-    MISC            -- miscellaneous cover information
-    DRAFT           -- document's draft number
-    DRAFT_STRING    -- what to use in place of "Draft"
-    REVISION        -- document's revision number
-    REVISION_STRING -- what to use in place of "Revision"
-
-+++ General document formatting directives
-    DOCTYPE    -- general document type
-    COPYSTYLE  -- draft or final copy
-    PRINTSTYLE -- typeset or "typewritten"
-
-+++ Line numbering
-    NUMBER_LINES              -- turn automatic line numbering on or off
-     Control macros
-      NUMBER_QUOTE_LINES      -- turn numbering of lines inside QUOTE on or off
-      NUMBER_BLOCKQUOTE_LINES -- turn numbering of lines inside BLOCKQUOTE on or off
-
-+++ Set documents in columns
-    COLUMNS
-    COL_NEXT
-    COL_BREAK
-
-+++ TYPEWRITE control macros
-    UNDERLINE_ITALIC    -- turn underlining of italics on
-    UNDERLINE_QUOTES    -- turn underlining of line for line quotes on or off
-    ITALIC_MEANS_ITALIC -- turn underlining of italics off (use italics)
-    UNDERLINE_SLANT     -- turn underlining of pseudo italics on
-    SLANT_MEANS_SLANT   -- turn underlining of pseudo italics off (use pseudo italics)
-
-+++ Initiate document processing
-    START -- begin document processing
-
-+++ Epigraphs
-    EPIGRAPH        -- set an epigraph underneath the docheader
-     Control macros -- change default style of epigraphs
-
-+++ Main heads
-    HEAD                    -- set a main head
-     Control macros         -- change default style of heads
-      HEAD_SPACE            -- control spacing around heads
-      NUMBER_HEADS          -- number heads
-      PREFIX_CHAPTER_NUMBER -- prefix chapter number to head numbering scheme
-      RESET_HEAD_NUMBER     -- reset head number to "1"
-
-+++ Subheads
-    SUBHEAD                 -- set a subhead
-     Control macros         -- change default style of subheads
-      NUMBER_SUBHEADS       -- number subheads
-      PREFIX_CHAPTER_NUMBER -- prefix chapter number to subhead numbering scheme
-      RESET_SUBHEAD_NUMBER  -- reset subhead number to "1"
-
-+++ Paragraph heads
-    PARAHEAD                -- set a paragraph head (joined to body of paragraph)
-     Control macros         -- change default style of paraheads
-      NUMBER_PARAHEADS      -- number paraheads
-      PREFIX_CHAPTER_NUMBER -- prefix chapter number to parahead numbering scheme
-      RESET_PARAHEAD_NUMBER -- reset parahead number to "1"
-
-+++ Paragraphs
-    PP                   -- set a paragraph
-     Paragraph style     -- managing paragraph style concerns
-      PP_FONT            -- globally change the font used in regular paragraphs
-      PARA_INDENT        -- set the paragraph first-line indent
-      INDENT_FIRST_PARAS -- indenting of paragraph first-lines on or off
-      PARA_SPACE         -- spacing of paragraphs (single blank line) on or off
-
-+++ Quotes (line by line verbatim quotes)
-    QUOTE                     -- set cited text line by line 
-     Control macros           -- change default style of quotes
-      ALWAYS_FULLSPACE_QUOTES -- control spacing around quotes
-    BREAK_QUOTE               -- deprecated
-
-+++ Blockquotes (cited passages of text)
-    BLOCKQUOTE                -- set longer passages of cited text
-     Control macros           -- change default style of blockquotes
-      ALWAYS_FULLSPACE_QUOTES -- control spacing around quotes
-    BREAK_BLOCKQUOTE          -- deprecated
-
-+++ Code snippets
-    CODE -- set a code snippet
-
-+++ Author linebreaks (section breaks)
-    LINEBREAK       -- insert an author linebreak (section break)
-    LINEBREAK_CHAR  -- character to use for author linebreaks
-    LINEBREAK_COLOR -- colour of author linebreak character
-
-+++ Document termination string
-    FINIS        -- insert a document termination string (e.g. --END--)
-    FINIS_STRING -- set the document termination string
-    FINIS_COLOR  -- set the document termination string colour
-
-+++ Footnotes
-    FOOTNOTE                -- set a footnote
-     Control macros         -- change default style of footnotes
-      FOOTNOTE_MARKERS      -- turn footnote markers on or off
-      FOOTNOTE_MARKER_STYLE -- type of footnote marker to use
-      RESET_FOOTNOTE_NUMBER -- reset footnote numbering
-      FOOTNOTE_RULE         -- turn footnote separator rule on or off
-      FOOTNOTE_RULE_ADJ     -- adjust vertical position of footnote rule
-      FOOTNOTE_RULE_LENGTH  -- adjust length of footnote rule
-      FOOTNOTES_RUN_ON      -- instruct footnotes to be continuous (i.e. not to
-                               begin on a new line; only for use with footnotes
-                               identified by document line number)
-
-+++ Endnotes
-    ENDNOTE                        -- set an endnote
-    \*[EN-MARK]                    -- mark initial line of a range of line numbers
-                                     (for use with line numbered endnotes)
-    ENDNOTES                       -- output endnotes pages
-     Control macros                -- change just about anything to do with endnotes
-      Endnotes pages general style control
-      Pagination of endnotes
-      Endotes pages header/footer control
-      Endnotes pages main title control
-      Endnotes pages document/section identification control
-      Endnote identification style
-
-+++ Margin notes
-    MN_INIT -- initialize margin notes
-    MN      -- set a margin note
-
-+++ Bibliographic references
-    REF                 -- begin a bibliographic reference
-    FOOTNOTE_REFS       -- place bibliographic references in footnotes
-    ENDNOTE_REFS        -- place bibliographic references in endnotes
-    REF( / REF)         -- put parentheses around embedded bibliographic references
-    REF[ / REF]         -- put square brackets around embedded bibliographic references
-    REF{ / REF}         -- put curly braces around mbedded bibliographic references
-    BIBLIOGRAPHY        -- output a bibliography
-     Control macros     -- change just about anything to do with bibliography pages
-      BIBLIOGRAPHY_TYPE -- "plain" or enumerated list bibliography
-      Bibliography pages general style control
-      Bibliography pages header/footer control
-      Bibliography pages main head control
-
-+++ Tables of contents
-    TOC
-     Control macros -- change just about anything to do with table of contents pages
-      Table of contents general style control
-      Table of contents page numbering
-      Table of contents main title control
-      Changing the style of the different table of contents entry types
-      Additional table of contents control macros
-
-+++ Letter (correspondence) macros
-    DATE            -- letter's date
-    FROM            -- letter's addresser
-    TO              -- letter's addressee
-    GREETING        -- letter's salutation
-    CLOSING         -- letter's closing salutation
-    CLOSING_INDENT  -- indentation of the closing salutation
-    SIGNATURE_SPACE -- room to leave for the signature
-    NO_SUITE        -- turn printing of "next page number" off or on
-
-+++ Changing global print style parameters after START
-    DOC_LEFT_MARGIN  -- left margin of everything on the page
-    DOC_RIGHT_MARGIN -- right margin of everything on the page
-    DOC_LINE_LENGTH  -- document's base line length
-    DOC_FAMILY       -- document's base family
-    DOC_PT_SIZE      -- document's base point size
-    DOC_LEAD         -- document's base lead
-    DOC_QUAD         -- document's base quad directions
-
-+++ Managing a document's first-page header
-    DOCHEADER       -- document first-page header on or off
-     Control macros -- change default style of docheader elements
-
-+++ Managing page headers and footers
-    HEADERS             -- turn page headers on or off
-    FOOTERS             -- turn page footers on or off
-    HEADERS_AND_FOOTERS -- enable or disable generation of both headers and footers
-     Header/footer control macros
-      Strings            -- left-right-center strings
-      Style              -- change style defaults for headers and/or footers
-      Global             -- global style changes
-      Part-by-part       -- part-by-part style changes
-      Vertical placement -- vertical location of headers and/or footers
-      Separator rule     -- manage the header/footer separator rule
-
-+++ Recto/verso page headers and footers
-    RECTO_VERSO    -- turn recto/verso headers and/or footers on or off
-    SWITCH_HEADERS -- switch recto or verso header
-    SWITCH_FOOTERS -- switch recto or verso footer
-    HEADER_RECTO   -- string that constitutes a recto header
-    HEADER_VERSO   -- string that constitutes a verso header
-    FOOTER_RECTO   -- string that constitutes a recto footer
-    FOOTER_VERSO   -- string that constitutes a recto footer
-
-+++ Pagination
-    PAGINATE                -- pagination on or off
-     Control macros         -- change default style for pagination
-      PAGENUMBER            -- user-defined (starting) page number
-      PAGENUM_STYLE         -- digits, roman numerals, etc
-      PAGENUM_ON_FIRST_PAGE -- when footers are enabled
-      DRAFT_WITH_PAGENUMBER -- attach draft/revision information to page numbers
-
-+++ Document and section cover (title) pages
-    COVER          -- information to include in a section cover
-    DOC_COVER      -- information to include in a document cover
-    COVERS         -- turn printing of section covers on or off
-    DOC_COVERS     -- turn printing of document covers on or off
-    Control macros -- change style defaults for covers
-
-+++ Utilities
-    ADD_SPACE       -- add space to the top of a page
-    BLANKPAGE       -- output one or more blank pages
-    DOC_LEAD_ADJUST -- adjust document linespacing (lead) to fill pages
-    COLLATE         -- join documents or chapters of a document together
-    SHIM            -- move vertical position to nearest next valid baseline
-
- -
- -

-Next   -Prev   -Top   -Back to Table of Contents -

- - - - - diff --git a/contrib/mom/momdoc/rectoverso.html b/contrib/mom/momdoc/rectoverso.html deleted file mode 100644 index 5eb7f013..00000000 --- a/contrib/mom/momdoc/rectoverso.html +++ /dev/null @@ -1,321 +0,0 @@ - - - - - - -Mom -- Document Processing, Recto/verso printing - - - - - - - -

-Next   -Prev   -Back to Table of Contents -

- -

Recto/verso printing, collating

 - - - - - -

Introduction to recto/verso

 - -

-Recto/verso printing allows you to set up a mom -document in such a way that it can be printed on both sides of a -printer sheet and subsequently bound. -

- -

-With recto/verso, mom automatically takes control -of the following aspects of alternating page layout: -

- - - -

-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 -How to invoke groff with mom) -in gv (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 gv print the -"even pages". If you prefer to work from the command -line, check out the man pages for pstops and -psbook. There are other programs out there as well -to help with two-sided printing. -

- -

Recto/verso macros list

 - - - - - -
- - - -

-Macro: RECTO_VERSO -

- -

-If you want mom to set up alternating pages for -recto/verso printing, simply invoke RECTO_VERSO -with no argument. -

- -

-NOTE: Recto/verso always switches the left and -right parts of -headers -or -footers -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 -L_MARGIN -and -R_MARGIN -(prior to -START) -or with -DOC_LEFT_MARGIN -and -DOC_RIGHT_MARGIN -(before or after START). -

- -

-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 -PAGENUM_POS -(before or after START). -

- - - -
- - - -

-Macro: SWITCH_HEADERS -

- -

-SWITCH_HEADERS switches the location of the -header left string (by default, the author) and the header right -string (by default, the document title). If you don't like -mom's default placement of author and title, use -SWITCH_HEADERS to reverse it. -

- -

-SWITCH_HEADERS can also be useful in conjunction -with -RECTO_VERSO. -The assumption of RECTO_VERSO 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. -

- -

-If mom's behaviour in this matter is not what you -want, simply invoke SWITCH_HEADERS on the first -page of your recto/verso document to reverse her default treatment -of header parts. The remainder of your document (with respect to -headers) will come out as you want. -

- -
- - - -

Introduction to collating

 - -

-The macro COLLATE 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 LETTER). -

- -

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

- -

-When collating chapters, you need only put .COLLATE at -the end of a chapter, follow it with any -reference macros -needed for the new chapter, e.g. -CHAPTER -or -CHAPTER_STRING, -make any pertinent style changes to the document (unlikely, but -possible), and re-invoke the -START -macro. Your new chapter will begin on a fresh page and behave -as expected. -

- -

-COLLATE assumes you are collating documents/files -with similar type-style parameters hence there's no need for -PRINTSTYLE to appear after COLLATE, -although if you're collating documents that were created as separate -files, chances are the PRINTSTYLE's already there. -

- - - -

-Two words of caution: - -

    -
  1. Do not collate documents of differing - PRINTSTYLES (i.e. don't try to - collate a TYPESET document and TYPEWRITE document). -
    2. -
  2. Use .DOC_FAMILY instead of - .FAMILY if, for some reason, you want to - change the family of all the document elements after - .COLLATE. .FAMILY, by itself, will - change the family of paragraph text only. -
    3. -
-

- - - -
- - - -

-Macro: COLLATE -

- -

-The most basic (and most likely) collating situation looks like -this: - -

-    .COLLATE
-    .CHAPTER 17
-    .START
-
-

- -

-A slightly more complex version of the same thing, for chapters -that require their own titles, looks like this: - -

-    .COLLATE
-    .CHAPTER_TITLE "Geek Fatigue: Symptoms and Causes"
-    .START
-
-

- -

-Tip: If the last -output line -of a document before COLLATE falls too close to -the bottom margin for running text, mom may output -a blank page with only a header or footer between collated -documents. In order to avoid this, I recommend always preceding -COLLATE with -.EL, -like this - -

-    .EL
-    .COLLATE
-
-

- -

-NOTE: See the -two words of caution, -above. -

- -
- -

-Next   -Prev   -Top   -Back to Table of Contents -

- - - - - diff --git a/contrib/mom/momdoc/refer.html b/contrib/mom/momdoc/refer.html deleted file mode 100644 index 252098cd..00000000 --- a/contrib/mom/momdoc/refer.html +++ /dev/null @@ -1,1837 +0,0 @@ - - - - - - -Mom -- Bibliographies and References - - - - - - - -Next   -Prev   -Back to Table of Contents - -

Bibliographies and references

- -Introduction to bibliographies and references -
- -Tutorial - - - -Index of bibliography and reference macros - - -

Introduction to bibliographies and references

 - -

-Mom 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 -groff program called "refer". -

- -

-refer is a groff -"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, refer can't do it's -job, and neither can mom. The scanning is done -before any actual mom processing -occurs. -

- -

-refer is a program that's been around for -a long time. It's powerful and has many, many features. -Unfortunately, the manpage (man refer), -while complete and accurate, is dense and not a good introduction -to refer. (It's a classic manpage Catch-22: the -documentation is useful only after you already understand it.) -

- -

-In order to get mom users up and running with -refer, this section of mom's -documentation focuses exclusively, in a recipe-like manner, on -what you need to know to use refer satisfactorily -in conjunction with mom. The information and -instructions are not to be taken as -a manual or tutorial on full refer usage. Much has -been left out, on purpose. -

- -

-It is tempting to provide two levels of documentation, one for -users familiar with refer and one for newcomers -to groff and mom, but such an -approach may muddy the waters for newcomers. Mom's -allegiance, first and foremost, is to newcomers. If you're already -a refer user, the information herein will be useful -for adapting your current refer usage to -mom's way of doing things. If you've never used -refer, the information is essential, and, in many -cases, may be all you need. -

- -

-(For the benefit of old groff-hands: refer -support in mom is heavily based on the -refer module of the "ms" macros. The -choice was deliberate so that those wishing to play around with -mom's bibliography formatting style would be -tinkering with the familiar.) -

- -

-refer requires first that you create a -bibliographic database. From the information contained in the -database, mom formats and generates bibliographies -and references in MLA (Modern Language Association) style. MLA -style is clean, contemporary and flexible, and is widely used in the -humanities, where the range of material that has to be referenced -can run from simple books to live interviews and film. -

- -

-Once you have created your database, you instruct -refer (and mom) to access entries -in it by supplying keywords from the entries. Depending on what -you've instructed mom 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. -

- -

-I encourage anyone interested in what MLA style looks like — -and, by extension, how your bibliographies and references will look -after mom formats them — to check out - -

-    http://www.aresearchguide.com/12biblio.html
-
- -or any other website or reference book on MLA style. -

- -

-NOTE: MLA style requires that second and subsequent -lines of individual references be indented. Mom -takes care of this for you with a default indent, which can be -changed with the macro -INDENT_REFS. -

- -
- -

Tutorial

 - -
    -
  1. Creating a refer database
    2. -
  2. Required "refer" commands
    3. -
  3. Accessing references
    4. -
  4. Telling mom where to put references
    5. -
  5. Creating bibliography pages
    6. -
  6. Invoking groff with mom and refer
    7. -
- -

1. Creating a refer database

 - -

-The first step in using refer with -mom is setting up your bibliographic database. The -database is a file containing separate entries for each reference -you want to access from your mom files. The file -is not a "mom 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. -

- -

-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. -%A or %T. The letter identifies what part -of a bibliographic entry the field refers to: Author, Title, -Publisher, Date, etc. After the field identifier comes a single -space, followed by the information appropriate to field. No -punctuation should go at the ends of fields; mom -adds what's correct automatically. Do note, however, that author(s) -(%A) 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. -

- -

-Here's a sample database containing two records so you can -visualize what the above paragraph says: - -

-%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
-
-

- -

-The order in which you enter fields doesn't matter. -mom and refer will re-arrange them -in the correct order for you. -

- -

-The meaning of the letters follows. There are, with -refer, quite a few — all uppercase -— which have, over time, come to be "standard". -Mom respects these. However, she adds to the list -(mostly the lowercase letters). -

- -
-    %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
-
- - - -

-Tip: If you have hyphenation turned on in your -document (you probably do), mom 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 groff -discretionary hyphen -character, \%, like this: - -

-    %A Hill, \%Reginald
-
-

- -

-Alternatively, you can turn hyphenation off entirely in -references with the macro, -HYPHENATE_REFS OFF. -

- -

2. Required "refer" commands

 - -

-Having set up your database, you now need to put some -refer-specific commands at the top of your -mom file. You cannot skip this step, nor can you -"source" these commands with the groff -primitive, -.so or the mom macro, -INCLUDE. -They must appear, exactly as shown, in -every file requiring bibliographic references. -

- -

-refer commands are introduced with a single -line containing .R1, and concluded with a single line -containing .R2. What you put between the .R1 -and .R2 lines are the commands themselves. The commands -should be entered one per line, in lowercase letters, with -no initial period (dot). -

- -

-Here's an example: - -

-    .R1
-    no-label-in-text
-    no-label-in-reference
-    .R2
-
-

- -

-There are an awful lot of refer commands. We will -focus only on those required to get mom cooperating -with refer. If you're interested, study the -refer manpage to discover what other commands are -available and how to manipulate them. -

- -

-At a minimum, all mom files accessing -a bibliographic database must contain the following -refer commands, exactly as shown: - - - -

-.R1
-no-label-in-text
-no-label-in-reference
-join-authors ", and " ", " ", and "
-database <full path to the database>
-.R2
-
-

- -

-The first two commands tell refer to let -mom handle everything associated with footnote -and endnote markers, both in the body of the document, and in the -footnotes/endnotes themselves. -

- -

-The third command is required for mom to handle -multiple authors in proper, MLA style. -

- -

-The last command, database, 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 including the database -filename, e.g. /home/user/refer/my_database. -

- -

If you're already a refer user, feel free to -enter whatever refer commands are necessary to -access the database(s) you want. -

- -

-With the above refer 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: - -

-.R1
-no-label-in-text
-no-label-in-reference
-join-authors ", and " ", " ", and "
-database <full path to the database>
-sort
-accumulate
-.R2
-
-

- -

3. Accessing references

 - -

-References are accessed by putting keywords, all on one line, -between the refer commands .[ and -.]. Both of these commands must appear on separate -

- -
-    .[
-    keyword(s)
-    .]
-
-lines, by themselves, like this: - -

-Keywords are any word, or set of words, that identify a database -record (i.e. a reference) unambiguously. (refer -doesn't like ambiguity.) -

- -

-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, Fahrenheit 451 and The Martian -Chronicles, 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 The Martian Mission, suitable -keywords to reference The Martian Chronicles might be: - -

-    .[                or    .[                   or  .[
-    Bradbury Martian        Bradbury Chronicles      Martian Chronicles
-    .]                      .]                       .]
-
-

- -

-The database field identifier, %K, 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: - -

-    %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
-
-

- -

-To access the shorter reference, you'd do - -

-    .[
-    Nor short
-    .]
-
-

- -

-To access the longer one, you'd do - -

-    .[
-    Norris
-    .]
-
-

- -

4. Telling mom where to put references

 - -

-Mom provides several mechanisms for outputting -references where you want. -

- -

Embedding references in the document body

- -

-References may be embedded in the document body, surrounded by -parentheses, square brackets, or braces. Use whichever you prefer, -following the recipes below. - -

-    Parentheses    Square brackets    Braces
-    -----------    ---------------    ------
-
-    .REF(          .REF[              .REF{
-    .[             .[                 .[
-    keyword(s)     keyword(s)         keyword(s)
-    .]             .]                 .]
-    .REF)          .REF]              .REF}
-
-

- -

Footnote or endnote references

- -

-Most times, you'll probably want references in either footnotes or -endnotes. Mom provides a simple mechanism whereby -you can choose which, or even switch back and forth. The primary -tag is -REF, which is used like this: - -

-    .REF
-    .[
-    keyword(s)
-    .]
-    .REF
-
-

- -

-REF collects references and outputs them -where you say with the macros, -FOOTNOTE_REFS -or -ENDNOTE_REFS. -Neither FOOTNOTE_REFS nor -ENDNOTE_REFS requires an argument. All they do is -tell REF, whenever it's invoked, where to put the -references. -

- -

-A recipe for footnote references looks like this: -

-    .FOOTNOTE_REFS
-    .REF
-    .[
-    keyword(s)
-    .]
-    .REF
-
-

- -

-When FOOTNOTE_REFS are enabled, -REF behaves identically to -FOOTNOTE, -so please read the -HYPER IMPORTANT NOTE -found in the document entry for FOOTNOTE. -

- -

-The reference between the first and second REF -will be treated as a footnote, as will all subsequent -REF pairs unless you invoke the macro, -.ENDNOTE_REFS. -

- -

-A recipe for endnote references looks like this: - -

-    .ENDNOTE_REFS
-    .REF
-    .[
-    keyword(s)
-    .]
-    .REF
-
-

- -

-The reference between the first and second REF -will be treated as an endnote, as will all subsequent -REF pairs unless you invoke the macro, -.FOOTNOTE_REFS. -

- -

-When ENDNOTE_REFS are enabled, REF -behaves identically to -ENDNOTE, -so please read the -HYPER IMPORTANT NOTE -found in the document entry for ENDNOTE. -

- -

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

- -

Collected references

 - -

-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). -REF is used for this, too, but you have to make -sure your refer commands block is set up properly. -The recipe for this is: - - - -

-.R1
-no-label-in-text
-no-label-in-reference
-join-authors ", and " ", " ", and "
-database <full path to the database>
-sort
-accumulate
-.R2
-
-

- -

-After this set up, and provided you don't issue a -.FOOTNOTE_REFS or .ENDNOTE_REFS command, all -reference between REF pairs will be collected for -later output. -

- -

-As a precaution, mom will issue a message -the first time you call .REF if neither -FOOTNOTE_REFS nor ENDNOTE_REFS -is in effect. If collected references are what you want, and you -have set up your .R1 -.R2 block as above, you may safely -ignore the message. -

- -

-LIMITATION: You cannot combine -"collected" references (plain REF) -with REFs that are instructed to go into -footnotes (with FOOTNOTE_REFS) or endnotes (with -ENDNOTE_REFS). This is a limitation imposed by -refer, not mom. -

- -

5. Creating bibliography pages

 - -

-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 -Control macros for bibliographies.) -A bibliography page that uses mom's defaults -begins with the macro, -BIBLIOGRAPHY, -like this: - -

-    .BIBLIOGRAPHY
-
-

- -

-Following BIBLIOGRAPHY, you have three choices of -how to proceed. -

- -

-If you have elected to have references collected from within the -body of a document (see above, -Collected references, -for instructions), which assumes you have a refer -command block like the one -here -at the top of your document, you need only do - -

-    .BIBLIOGRAPHY
-    .[
-    $LIST$
-    .]
-
-

- -

-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 -refer block like the one -here -at the top of your document: - -

-    .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$
-    .]
-
-

- -

-Your final choice is to output your whole database. Again, -assuming you have a refer block like the one -here -at the top of your file, you need only do: - -

-    .BIBLIOGRAPHY
-    .R1
-    bibliography <full path to database>
-    .R2
-
-

- -

-If you haven't put a refer block in -your file already, you can put the whole thing after -BIBLIOGRAPHY, like this: - -

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

- -

-Whichever option you choose, mom will output a full -bibliography page, complete with a title ("BIBLIOGRAPHY" -by default, but that can be changed). -

- -

6. Invoking groff with mom and refer

 - -

-So, now you've got a document, formatted properly to use references -processed with refer, what do you do to output the -document? -

- -

-It's simple. Instead of invoking groff with just -the -mom option, as explained -here, -invoke groff with the -R option as well, like this: - -

-    groff -R -mom filename
-
-

- -
- -

Index of bibliography and reference macros

 - - - - - -
- -

Marking off references for footnotes, endnotes, or collection

 - -

-Tag: REF -

- -

-The macro, REF, tells mom -that what follows is refer-specific, a -keyword-identified reference from a refer database. -Depending on whether you've issued a -FOOTNOTE_REFS -or -ENDNOTE_REFS -instruction, REF also tells mom -where to place the reference. If FOOTNOTE_REFS, -the reference will be formatted and placed in a footnote. If -ENDNOTE_REFS, the reference will be collected for -output as an endnote. If you have issued neither instruction, the -reference will be collected for later output, most likely on a -bibliography page. -

- -

-Before you use REF, you must create a -refer block containing refer -commands (see -Required refer commands -in the tutorial, above). -

- -

-REF usage always looks like this: - -

-    .REF
-    .[
-    keyword(s)
-    .]
-    .REF
-
-

- -

-Notice that REF "brackets" the -refer call, and never takes an argument. -

- -

-What REF really is is a convenience. One could, -for example, put a reference in a footnote by doing - -

-    .FOOTNOTE
-    .[
-    keyword(s)
-    .]
-    .FOOTNOTE OFF
-
-

- -

-However, if you have a lot of references going into footnotes (or -endnotes), it's much shorter to type .REF/.REF than -.FOOTNOTE/.FOOTNOTE OFF. 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. -

- -

-Additional arguments: If you're using -REF to put references in footnotes and your -footnotes need to be indented, you may (indeed, should) pass -REF the same arguments used to indent footnotes. -See -FOOTNOTE. -

- -

-Note: When REF is used with -FOOTNOTE_REFS, -it behaves identically to -FOOTNOTE, -so please read the -HYPER IMPORTANT NOTE -found in the document entry for FOOTNOTE. -

- -

-When REF is used with -ENDNOTE_REFS, -it behaves identically to -ENDNOTE, -so please read the -HYPER IMPORTANT NOTE -found in the document entry for ENDNOTE. -

- - - -
- -

Instruct REF to put references in footnotes

 - -

-Macro: FOOTNOTE_REFS -

- -

-FOOTNOTE_REFS is an instruction to -REF, -saying, "put all subsequent references bracketed by the -REF macro into footnotes." You invoke it by -itself, with no argument. -

- -

-When FOOTNOTE_REFS is in effect, regular footnotes, -(i.e. those introduced with .FOOTNOTE and terminated with -.FOOTNOTE OFF) continue to behave normally. -

- -

-You may switch between FOOTNOTE_REFS and -ENDNOTE_REFS -at any time. -

- -

-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 -FOOTNOTES_RUN_ON -in conjunctions with FOOTNOTE_REFS. -

- - - -
- -

Instruct REF to put references in endnotes

 - -

-Macro: ENDNOTE_REFS -

- -

-ENDNOTE_REFS is an instruction to -REF, -saying, "add all subsequent references bracketed by the -REF macro to endnotes." You invoke it by -itself, with no argument. -

- -

-When ENDNOTE_REFS is in effect, -mom continues to format regular endnotes, (i.e. -those introduced with .ENDNOTE and terminated with -.ENDNOTE OFF) in the normal way. -

- -

-You may switch between ENDNOTE_REFS and -FOOTNOTE_REFS -at any time. -

- - - -
- -

References embedded in text

 - -

-Macro pair: REF(  ...  REF) -
- -Macro pair: REF[  ...  REF] -
- -Macro pair: REF{  ...  REF} -

- -

-You may sometimes want to embed references directly into the body -of your documents, typically, but not always, inside parentheses. -Mom makes this possible through the use of the -REF<bracket type> macros. -

- -

-All three macro pairs, above, are invoked the same way, namely -by introducing the reference with the first ("open") -macro of the REF<bracket type> -pair, and terminating it with the second ("close") -REF<bracket type> of the pair. For -example - -

-    .REF(
-    .[
-    keyword(s)
-    .]
-    .REF)
-
- -will embed a reference in the body of your document, surrounded by -parentheses. .REF[ ... .REF] will -surround the reference with square brackets. -.REF{ ... .REF} will surround it with -curly braces. -

- - - -
- -

Manage the second-line indent of references

 - -

-Macro: INDENT_REFS FOOTNOTE | ENDNOTE | BIBLIO <indent> -
- -*<indent> requires a unit of measure -

- -

-Proper MLA-style references should have their second, and subsequent -lines, if any, indented. Since mom formats -references in MLA style, she automatically indents second lines. By -default, the indent for the second line of references, regardless -of whether the references appear in footnotes, endnotes, or -bibliographies, is 1.5 -ems -for -PRINSTYLE -TYPESET -and 2 ems for -PRINSTYLE -TYPEWRITE. -

- -

-If you'd like to change the indent for footnotes, endnotes or -bibliographies, just invoke .INDENT_REFS with a -first argument telling mom 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 -picas, - -

-    .INDENT_REFS BIBLIO 3P
-
- -is how you'd set it up. -

- -

-Tip: if you are identifying endnotes by line -number -(ENDNOTE_MARKER_STYLE LINE) -and you have instructed mom to put references -bracketed by -REF -into endnotes (with -ENDNOTE_REFS), -you will almost certainly want to adjust the second-line indent -for references in endnotes, owing to the way mom -formats line-numbered endnotes. Study the output of such documents -to see whether an indent adjustment is required. -

- -

-The same advice applies to references in endnotes when you have enabled -ENDNOTE_NUMBERS_ALIGN_LEFT -in favour of mom's default -ENDNOTE_NUMBERS_ALIGN_RIGHT. -Study the output to determine what size of second-line indent works -best. -

- -

-(Frankly, endnote references formatted in MLA-style combined -with left-aligned endnote numbers is a no-win situation, and so is -best avoided. Wherever you set the indent, you'll end up with -the endnote numbers appearing to hang into the left margin, so you -might as well have them hang, as is the case with -.ENDNOTE_NUMBERS_ALIGN_RIGHT. Ed.) -

- - - -
- -

Enable/disable hyphenation of references

 - -

-Macro: HYPHENATE_REFS <toggle> -

- -

-If you have hyphenation turned on for a document (see -HY), -and in most cases you probably do, mom will -hyphenate references bracketed by the -REF -macro. Since references typically contain quite a lot of proper -names, which shouldn't be hyphenated, you may want to disable -hyphenation for references. -

- -

-HYPHENATE_REFS is a toggle macro; -invoking it by itself will turn automatic hyphenation of -REF-bracketed references on (the default). -Invoking it with any other argument (OFF, -NO, X, etc.) will disable -automatic hyphenation for references bracketed by -REF. -

- -

-An alternative to turning reference hyphenation off is to prepend -to selected proper names in your refer database -the groff -discretionary hyphen -character, \%. (See -here -in the tutorial for an example.) -

- -

-Note: references embedded in the body of a document -with -REF<bracket type> -are considered part of -running text, -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 -HY, -like this: - -

-    .HY OFF
-    .REF(
-    .[
-    keyword(s)
-    .]
-    .REF)
-    .HY
-
-

- -

-Alternatively, sprinkle your database fields liberally with -\%. -

- - - -
- -

Begin a bibliography page

 - -

-Macro: BIBLIOGRAPHY -

- -

-If you want to append a bibliography to your document, all you need -do is invoke .BIBLIOGRAPHY at the place you want -it. BIBLIOGRAPHY breaks to a new page, prints the -title (BIBLIOGRAPHY by default, but that can be changed), and awaits -refer instructions. How to create bibliographies -is covered in the tutorial section, -Creating bibliography pages. -

- -

-See the -Bibliography page style control macros -for macros to tweak, design and control the appearance of -bibliography pages. -

- - - -
- -

Plain, or numbered list bibliography

 - -

-Macro: BIBLIOGRAPHY_TYPE PLAIN | LIST [ <list separator> ] [ <list prefix> ] -

- -

-Mom offers two styles of bibliography output: -plain, or numbered list style. With PLAIN, bibliography -entries are output with no enumerators. With LIST, each -entry is numbered. -

- -

-Entering .BIBLIOGRPHY_TYPE PLAIN gives you a plain -bibliography. -

- -

-Entering .BIBLIOGRAPHY_TYPE LIST gives -you an enumerated bibliography. The two optional -arguments, <list separator> and -<list prefix> have the same meaning as the -equivalent arguments to -LIST -(i.e. <separator> and <prefix>). -

- -

-You may enter .BIBLIOGRAPHY_TYPE either before or -after .BIBLIOGRAPHY. It must, however, always come -before the refer command to output bibliographies. -(See the tutorial section, -Creating bibliography pages, -for instructions on how to output bibliographies.) -

- -

-Mom's default BIBLIOGRAPHY_TYPE -is LIST, with a period (dot) as the separator, and -no prefix. -

- - - -
- -

Bibliography pages style control

 - -

-Mom processes bibliography pages in a manner very -similar to the way she processes endnotes pages. The bibliography -page control macros, therefore, behave in the same way as their -endnotes pages equivalents. -

- -
    -
  1. General bibliography pages style control
    2. - -
  2. Bibliography pages header/footer control
    3. - -
  3. Bibliography page head (i.e. the title at the top) control
    4. - -
- -
- -

1. General bibliography page style control

 - -
*Bibliography family/font/quad
 - -

-See -Arguments to the control macros. -

- -
-.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
-
- - - -
*Bibliography point size
 - -

-Macro: BIBLIOGRAPHY_PT_SIZE <base type size of bibliography> -

- -

-Unlike most other control macros that deal with size of document -elements, BIBLIOGRAPHY_PT_SIZE takes as its -argument an absolute value, relative to nothing. Therefore, the -argument represents the size of bibliography type in -points, -unless you append an alternative -unit of measure. -For example, - -

-    .BIBLIOGRAPHY_PT_SIZE 12
-
- -sets the base point size of type on the bibliography page to 12 -points, whereas - -
-    .BIBLIOGRAPHY_PT_SIZE .6i
-
- -sets the base point size of type on the bibliography page to 1/6 of an -inch. -

- -

-The type size set with BIBLIOGRAPHY_PT_SIZE is the -size of type used for the text of the bibliographies, and forms the -basis from which the point size of other bibliography page elements -is calculated. -

- -

-The default for -PRINTSTYLE TYPESET -is 12.5 points (the same default size used in the body of the document). -

- - - -
*Bibliography lead
 - -

-Macro: BIBLIOGRAPHY_LEAD <base leading of bibliographies> [ ADJUST ] -
- -*Does not require a unit of measure; points is assumed -

- -

-Unlike most other control macros that deal with leading of document -elements, BIBLIOGRAPHY_LEAD takes as its argument -an absolute value, relative to nothing. Therefore, the argument -represents the -leading -of endnotes in -points -unless you append an alternative -unit of measure. -For example, - -

-    .BIBLIOGRAPHY_LEAD 14
-
- -sets the base leading of type on the bibliography page to 14 -points, whereas -

- -

-

-    .BIBLIOGRAPHY_LEAD .5i
-
- -sets the base leading of type on the bibliography page to 1/2 inch. -

- -

-If you want the leading of bibliographies adjusted to fill the page, -pass BIBLIOGRAPHY_LEAD the optional argument, -ADJUST. (See -DOC_LEAD_ADJUST -for an explanation of leading adjustment.) -

- -

-The default for -PRINTSTYLE TYPESET -is 14 points, adjusted. -

- -

-NOTE: Even if you give mom -a .DOC_LEAD_ADJUST OFF command, she -will still, by default, adjust bibliography leading. You MUST enter -BIBLIOGRAPHY_LEAD <lead> with no -ADJUST argument to disable this default behaviour. -

- - - -
*Singlespace bibliographies (TYPEWRITE only)
 - -

-Macro: SINGLESPACE_BIBLIOGRAPHY <toggle> -

- -

-If your -PRINTSTYLE -is TYPEWRITE and you use TYPEWRITE's default -double-spacing, bibliographies are double-spaced. If your document -is single-spaced, bibliographies are single-spaced. -

- -

-If, for some reason, you'd prefer that bibliographies be single-spaced -in an otherwise double-spaced document (including double-spaced -collated -documents), invoke .SINGLESPACE_BIBLIOGRAPHY with with no -argument. -

- - - -
*Adjusting the space between bibliography entries
 - -

-Macro: BIBLIOGRAPHY_SPACING <amount of space> -
- -*Requires a unit of measure -

- -

-By default, mom 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, BIBLIOGRAPHY_SPACING. Say, for example, -you'd prefer only 1/2 linespace. That would be done with - -

-    .BIBLIOGRAPHY_SPACING .5v
-
-

- -

-As with endnotes pages, owing to the space inserted between -bibliography entries, bibliography pages may have hanging -bottom margins. Unlike endnotes pages, mom -is sad to report that there's nothing you can do about -this, except a) pray things work out, or b) set your -BIBLIOGRAPHY_SPACING to zero. -

- - - -
*Turning off column mode during bibliography output
 - -

-Macro: BIBLIOGRAPHY_NO_COLUMNS <toggle> -

- -

-By default, if your document is -set in columns, -mom 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 -.BIBLIOGRAPHY_NO_COLUMNS with no argument. The -bibliography pages will be set to the full page measure of your -document. -

- -

-If you output bibliographies at the end of each document in a -collated -document set in columns, column mode will automatically -be reinstated for each document, even with -BIBLIOGRAPHY_NO_COLUMNS turned on. -

- - - -
*Bibliography-page page numbering style
 - -

-Macro: BIBLIOGRAPHY_PAGENUM_STYLE DIGIT | ROMAN | roman | ALPHA | alpha -

- -

-Use this macro to set the page numbering style of bibliography -pages. The arguments are identical to those for -PAGENUM_STYLE. -The default is digit. You may want to change it to, say, -alpha, which you would do with - -

-    .BIBLIOGRAPHY_PAGENUM_STYLE alpha
-
-

- - - -
*Setting the first page number of bibliography pages
 - -

-Macro: BIBILOGRAPHY_FIRST_PAGENUMBER <page # that appears on page 1 of bibliographies> -

- -

-Use this macro with caution. If all bibliographies for several -collated -documents are to be output at once, i.e. not at the end of each -separate doc, BIBLIOGRAPHY_FIRST_PAGENUMBER tells -mom what page number to put on the first page of -the bibliography. -

- -

-If you set BIBLIOGRAPHY_FIRST_PAGENUMBER in collated -documents where the bibliographies are output after each separate doc, -you have to reset every separate document's first page number after -COLLATE -and before -START. -

- - - -
*Omitting a page number on the first page of bibliographies
 - -

-Macro: BIBLIOGRAPHY_NO_FIRST_PAGENUM <toggle> -

- -

-This macro is for use only if -FOOTERS -are on. It tells -BIBLIOGRAPHY -not to print a page number on the first bibliography page. -Mom's default is to print the page number. -

- - - -
*Suspending pagination of bibliography pages
 - -

-Macro: SUSPEND_PAGINATION -
- -Macro: RESTORE_PAGINATION -

- -

-SUSPEND_PAGINATION doesn't take an argument. -Invoked immediately prior to -BIBLIOGRAPHY, -it turns off pagination for the duration of the bibliography. -Mom continues, however to increment page numbers -silently. -

- -

-To restore normal document pagination after bibliographies, invoke -.RESTORE_PAGINATION (again, with no argument) -immediately after you've finished with your bibliography. -

- -

2. Bibliography page header/footer control

 - - - -

-If you wish to modify what appears in the header/footer that appears -on bibliography pages, make the changes before you invoke -.BIBLIOGRAPHY, -not afterwards. -

- -

-Except in the case of -DOCTYPE CHAPTER, -mom prints the same header or footer used throughout -the document on bibliography pages. Chapters get treated differently -in that, by default, mom does not print the -header/footer centre string (normally the chapter number or chapter -title.) In most cases, this is what you want. However, should you -not want mom to remove the centre string from -the bibliography pages headers/footers, invoke -.BIBLIOGRAPHY_HEADER_CENTER -with no argument. -

- -

-An important change you may want to make is to put the word -"Bibliography" in the header/footer centre position. -To do so, do - -

-    .HEADER_CENTER "Bibliography"
-               or
-    .FOOTER_CENTER "Bibliography"
-
- -prior to invoking .BIBLIOGRAPHY. If your -DOCTYPE -is CHAPTER, you must also invoke -.BIBLIOGRAPHY_HEADER_CENTER -for the HEADER_CENTER to appear. -

- -
*Bibliography page header/footer centre string
 - -

-Macro: BIBLIOGRAPHY_HEADER_CENTER toggle -

- -

-If your -DOCTYPE -is CHAPTER and you want mom to include -a centre string in the headers/footers that appear on bibliography -pages, invoke .BIBLIOGRAPHY_HEADER_CENTER (or -.BIBLIOGRAPHY_FOOTER_CENTER) with no argument. -Mom's default is NOT to print the centre string. -

- -

-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 (OFF, QUIT, Q, X...). -

- -
*Allow headers on bibliography pages
 - -

-Macro: BIBLIOGRAPHY_ALLOWS_HEADERS <none> | ALL -

- -

-By default, if HEADERS are on, mom -prints page headers on all bibliography pages except the first. If you -don't want her to print headers on bibliography pages, do - -

-    .BIBLIOGRAPHY_ALLOWS_HEADERS OFF
-
-

- -

-If you want headers on every page including the first, do - -

-    .BIBLIOGRAPHY_ALLOWS_HEADERS ALL
-
-

- -

-NOTE: If FOOTERS are on, -mom prints footers on every bibliography page. This is -a style convention. In mom, there is no such beast -as BIBLIOGRAPHY_ALLOWS_FOOTERS OFF. -

- -

3. Bibliography page first page head (title) control

 - - - -
*Bibliography pages first page head (title) string
 - -

-Macro: BIBLIOGRAPHY_STRING "<head to print at the top of bibliography pages>" -

- -

-By default, mom 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 .BIBLIOGRAPHY_STRING 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 -.BIBLIOGRAPHY_STRING with a blank argument (either two -double-quotes side by side — "" — -or no argument at all). -

- - - -
*Bibliography page first page head (title) control
 - -

-See -Arguments to the control macros. -

- -
-.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)
-
- - - -
*Bibliography-page head (title) underlining
 - -

-Macro: BIBLIOGRAPHY_STRING_UNDERLINE [DOUBLE] [<underline weight> [<underline gap> [<distance between double rules]]] | <none> | <anything> -
- -Alias: BIBLIOGRAPHY_STRING_UNDERSCORE -
- -*The argument <underline weight> must NOT have the unit of measure, p, appended to it -

- -

-Invoked without an argument, .BIBLIOGRAPHY_STRING_UNDERLINE -will place a single rule underneath the bibliography-page head. Invoked -with the argument DOUBLE, -BIBLIOGRAPHY_STRING_UNDERLINE will double-underline -the head. Invoked with any other non-numeric argument, (e.g. -OFF, NO, X, etc.) -the macro disables underlining of the head. -

- -

-In addition, you can use BIBLIOGRAPHY_STRING_UNDERLINE -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. -

- -

-Some examples: - -

-    .BIBLIOGRAPHY_STRING_UNDERLINE 1
-        - turn underlining on; set the rule weight to 1 point
-
-    .BIBLIOGRAPHY_STRING_UNDERLINE 1 3p
-        - turn underlining on; set the rule weight to 1 point; set
-          the gap between the string and the underline to 3 points
-    
-    .BIBLIOGRAPHY_STRING_UNDERLINE DOUBLE .75 3p
-        - turn double-underlining on; set the rule weight to 3/4 of
-          a point; set the gap between the string and the upper
-          underline to 3 points; leave the gap between the upper
-          and the lower underline at the default
-    
-    .BIBLIOGRAPHY_STRING_UNDERLINE DOUBLE 1.5 1.5p 1.5p
-        - turn double-underlining on; set the rule weight to 1-1/2
-          points; set the gap between the string and the upper
-          underline to 1-1/2 points; set the gap between the upper
-          and the lower underline to 1-1/2 points
-
- -Note, from the above, that in all instances, underlining (single or -double) is enabled whenever BIBLIOGRAPHY_STRING_UNDERLINE -is used in this way. -

- -

-Mom'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. -

- - - -
*Bibliography-page head (title) automatic capitalization
 - -

-Macro: BIBLIOGRAPHY_STRING_CAPS toggle -

- -

-Invoked by itself, .BIBLIOGRAPHY_STRING_CAPS will -automatically capitalize the bibliography page head. Invoked with -any other argument, the macro disables automatic capitalization of -the head. -

- -

-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 -BIBLIOGRAPHY_STRING -is in caps/lower case and BIBLIOGRAPHY_STRING_CAPS is -on, this is exactly what will happen. -

- -

-Mom's default is to capitalize the bibliography-page -head string. -

- -
- -

-Next   -Prev   -Top   -Back to Table of Contents -

- - - - - diff --git a/contrib/mom/momdoc/reserved.html b/contrib/mom/momdoc/reserved.html deleted file mode 100644 index f1372114..00000000 --- a/contrib/mom/momdoc/reserved.html +++ /dev/null @@ -1,2705 +0,0 @@ - - - - - - -Mom -- List of reserved words - - - - - - - -

-Prev   Back to Table of Contents -

- -

LIST OF RESERVED WORDS

 - -

-The following is a list of "reserved" words used by -mom. Before changing the name of any macro or -document element tag with -ALIAS, -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. -

- -

-Anyone interested in playing around inside mom'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 -mom uses, along with brief descriptions of their -functions. -

- -
-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
-SUPERSCRIPT_RAISE_AMOUNT
-                 Change default vertical displacement of superscripts
-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 
-#EW                     Is EW in effect? (boolean)
-#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_ITEM                Are we in a list item? (boolean)
-#IN_ITEM_L_INDENT       Value passed to IL if #IN_ITEM=1
-#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_TRAP           Did we have to disable traps? Used in
-                        graphical object macros (boolean)
-#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
-#RW                     Is RW in effect? (boolean)
-#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>
-$EW                  Value passed to EW
-$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
-$RW                  Value passed to RW
-$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>
-$SUP_LOWER           Vertical displacement amount of superscripts
-$SUP_RAISE           Vertical displacement amount of superscripts
-$SUP_RAISE_AMOUNT    Argument passed to SUPERSCRIPT_RAISE_AMOUNT
-$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,)
-CLOSING_INDENT  Left indent of CLOSING
-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
-SIGNATURE_SPACE Amount of room to leave for signature
-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_RECTO_CAPS         Header/footer recto caps? (boolean)
-#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
-#HDRFTR_VERSO_CAPS         Header/footer verso caps? (boolean)
-#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
-$CLOSE_INDENT                    Argument passed to CLOSING_INDENT
-$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_QUAD                  Quad direction (LRC) of 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
-$PH_FAM                          Parahead family
-$PH_FT                           Parahead font
-$PH_SIZE_CHANGE                  ps in/decrease of paraheads
-$PH_SPACE                        Amount of horizontal space between a parahead
-                                 and the start of paragraph text
-$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
-$SIG_SPACE                       Arg passed to macro, SIGNATURE_SPACE
-$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
-DOCHEADER_QUAD                _QUAD
-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
-
- -
-Prev   -Top   -Back to Table of Contents - - - diff --git a/contrib/mom/momdoc/toc.html b/contrib/mom/momdoc/toc.html deleted file mode 100644 index 20db86d8..00000000 --- a/contrib/mom/momdoc/toc.html +++ /dev/null @@ -1,463 +0,0 @@ - - - - - - -Mom, version 1.5-d -- Table of Contents - - - - - -

Table of Contents for mom, version 1.5-d

- -

-The table of contents has grown quite large. If you've been using -mom for a while, you might prefer the -Quick Reference Guide. -

- -

-If you're new to mom, click on any link in the -Quick Table of Contents -to go to the -appropriate section of the Full Table of Contents. -

- -

-Alternatively, go directly to the -Full Table of Contents. -

- -
- - - -

Quick Table of Contents

 - -INTRODUCTORY STUFF - - - -TYPESETTING WITH MOM - - - -DOCUMENT PROCESSING WITH MOM - - - -
- - - -

Full Table of Contents

 - - -1. WHAT IS MOM? - - - - -2. DEFINITIONS OF TERMS USED IN THIS MANUAL - - - - -3. USING MOM - - - - - - -4. THE TYPESETTING MACROS - - - - - - -5. DOCUMENT PROCESSING WITH MOM - - - - -6. QUICK REFERENCE GUIDE TO MOM -
- - -7. APPENDICES - - - - - - - diff --git a/contrib/mom/momdoc/typemacdoc.html b/contrib/mom/momdoc/typemacdoc.html deleted file mode 100644 index b95844fa..00000000 --- a/contrib/mom/momdoc/typemacdoc.html +++ /dev/null @@ -1,315 +0,0 @@ - - - - - - -Mom -- Typesetting macros in document processing - - - - - - - -

-Next   -Prev   -Back to Table of Contents -

- -

Using the typesetting macros during document processing

 - -

-Typesetting macro behaviour -
- -Top and bottom margins in document processing -
- -Inserting space at the top of a page -
- -    * ADD_SPACE -

- -

Typesetting macro behaviour

 - -

-During document processing, most of the -typesetting macros -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. -

- -

-Typesetting macros that alter margins and line lengths affect -running text -globally (or at least try to), but leave headers/footers and -footnotes alone. (To indent footnotes, see the full explanation of -the -FOOTNOTE -macro.) -

- -

-Mom's tabs -(both -typesetting tabs -and -string tabs) -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 -COLUMNS -are enabled, from column to column. -

- -

-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, -family, -font, -point size, -leading, -and -quad. -

- -

-Mom assumes that any changes to these parameters -stem from a temporary need to set type in a style different from -that provided by mom's -document element tags. -In other words, you need to do a bit of creative typesetting in the -middle of a document. -

- -

-The following lists those typesetting macros whose behaviour during -document processing requires some explanation. -(Please refer to -Top and bottom margins in document processing -for information on how mom interprets -T_MARGIN -and -B_MARGIN -in document processing. Additionally, see -ADD_SPACE -if you encounter the problem of trying to get mom -to put space at the tops of pages after the first.) -

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

Top and bottom margins in document processing

 - -

-Normally, mom establishes the top and bottom -margins of -running text -in documents from the values of HEADER_MARGIN + -HEADER_GAP and FOOTER_MARGIN + FOOTER_GAP -respectively. However, if you invoke -T_MARGIN -or -B_MARGIN -either before or after -START, -they set the top and bottom margins of running text irrespective of -HEADER_GAP and FOOTER_GAP. -

- -

-Put another way, in document processing, T_MARGIN -and B_MARGIN set the top and bottom margins of -running text, but have no effect on the placement of -headers, -footers, -or page numbers. -

- -
- - - -

Inserting space at the top of a page

 - -

-Occasionally, you may want to insert space before the start of -running text -on pages after the first. -

- -

-You might have tried using -ALD -or -SPACE -and found it did nothing. This is because mom -normally inhibits any extra space before the start of running text -on pages after the first. -

- -

-If you need the space, you must use the macro, -ADD_SPACE, in conjuction with -NEWPAGE. -

- - - -
- - - -

-Macro: ADD_SPACE <amount of space> -
- -*Requires a unit of measure -

- -

-ADD_SPACE takes as its single argument the distance -you want mom to advance from the normal -baseline position at the top of any page after the first -(i.e. the one on which the docheader is normally printed). A unit of measure is -required. -

- -

-For example, say you wanted to insert 2 inches of space before the -start of -running text -on a page other than the first. You'd accomplish it with - -

-    .NEWPAGE
-    .ADD_SPACE 2i
-
- -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. -

- -

-Since adding space in this way is almost sure to disrupt -mom's ability to guarantee perfectly flush bottom -margins, I highly recommend using the -SHIM -macro immediately after ADD_SPACE. -

- -
- -

-Next   -Prev   -Top   -Back to Table of Contents -

- - - - - diff --git a/contrib/mom/momdoc/typesetting.html b/contrib/mom/momdoc/typesetting.html deleted file mode 100644 index 7719925a..00000000 --- a/contrib/mom/momdoc/typesetting.html +++ /dev/null @@ -1,5099 +0,0 @@ - - - - - - -Mom -- Typesetting Macros - - - - - - - -

-Next   -Prev   -Back to Table of Contents -

- -

The typesetting macros

 - - - -
- -

Introduction to the typesetting macros

- -

-Mom's typesetting macros provide access to groff's -typesetting capabilities. Aside from controlling basic type -parameters (family, font, line length, point size, leading), -mom's macros fine-tune wordspacing, letterspacing, -kerning, hyphenation, and so on. In addition, mom -has true typesetting tabs, string tabs, multiple indent styles, line -padding, and a batch of other goodies. -

- -

-In some cases, mom'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 -mom. 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 mom, -stay away from groff primitives if mom provides a -macro that accomplishes the same thing. -

- -

-Mom's typesetting macros can be used as a -standalone package, independent of the -document processing macros. -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. -

- -
- - - - - -

Page setup: paper size and page margins

 - -

-The page setup macros establish the physical dimensions of your page -and the margins you want it to have. Groff has -defaults for these, but I recommend setting them at the top of your -files anyway unless you're using mom's -document processing macros -and are content with her defaults. -

- -

-The -PAPER -macro provides a shortcut for setting the page to the correct -dimensions for a number of well-known, established paper sizes. The -PAGE -macro provides a convenient way of setting the page dimensions and -some or all of the page margins with a single macro. -

- -

Important note on page dimensions and papersize

 - -

-Mom's macros for setting up the desired size of -printer sheets (the "papersize") tell mom -and groff about the page dimensions, but not the -driver responsible for generating the final PostScript file. You -must take care of this yourself. -

- -

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

-    <path to groff>/font/devps/DESC
-
- -In it, you will see a line that reads - -
-    papersize <papersize>
-
- -Change <papersize> 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 -man papersize). 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 must have a -unit of measure -appended. Valid units of measure for papersize are -inches (i), -centimeters (c), -picas (P) and -points (p). -

- -

-For example, to set up a routine papersize of 8 inches by 10 inches, -the line would look like this: - -

-    papersize 8i,10i
-
-

- -

-Having set up your routine papersize, if you occasionally need -to print on sheets that do not conform to its dimensions, -you must, in addition to setting -the page dimensions in your mom file, -invoke groff on the command line with the --P-p<papersize> option. -

- -

-For example, suppose your routine papersize is "letter", -and you need to print something on a "legal"-sized sheet. -After telling mom about the legal-size sheet (with -either -PAGELENGTH -and -PAGEWIDTH, -or -PAPER, -or -PAGE, -in your mom file, when you invoke -groff to process the file, the command would look -like this: - -

-    groff -mom -P-plegal
-
-

- -

-Consult man groff, -man grops and -man groff_font for additional information -concerning papersizes, as well as information on printing in -"landscape" orientation. -

- -

Page setup macros list

 - - - - - -
- -

Page width

 - -

-Macro: PAGEWIDTH <width of printer sheet> -
- -*Requires a unit of measure -

- -

-The argument to PAGEWIDTH is the width of your -printer sheet. PAGEWIDTH requires a unit of measure. -Decimal fractions are allowed. Hence, to tell mom -the width of your printer sheet is 8-1/2 inches, you enter - -

-    .PAGEWIDTH 8.5i
-
-

- -

-Please read the -Important note on page dimensions and papersize -for information on ensuring groff respects your -PAGEWIDTH. -

- - - -
- -

Page length

 - -

-Macro: PAGELENGTH <length of printer sheet> -
- -*Requires a unit of measure -

- -

-PAGELENGTH tells mom how long your -printer sheet is. It works just like -PAGEWIDTH. Therefore, to tell -mom your printer sheet is 11 inches long, you -enter - -

-    .PAGELENGTH 11i
-
-

- -

-Please read the -Important note on page dimensions and papersize -for information on ensuring groff respects your -PAGELENGTH. -

- - - -
- -

Paper

 - -

-Macro: PAPER <paper type> -

- -

-PAPER provides a convenient way to set the page -dimensions for some common printer sheet sizes. <paper -type> can be one of: - -

-    LETTER
-    LEGAL
-    STATEMENT
-    TABLOID
-    LEDGER
-    FOLIO
-    QUARTO
-    10x14
-    EXECUTIVE
-    A3
-    A4
-    A5
-    B4
-    B5 
-
-

- -

-Say, for example, you have A4-sized sheets in your printer. It's -shorter (and easier) to enter - -

-    .PAPER A4
-
- -than to remember the correct dimensions and enter - -
-    .PAGEWIDTH  595p
-    .PAGELENGTH 842p
-
-

- -

-Please read the -Important note on page dimensions and papersize -for information on ensuring groff respects your -PAPER size. -

- - - -
- -

Left margin

 - -

-Macro: L_MARGIN <left margin> -
- -*Requires a unit of measure -

- -

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

- -

-Left indents -and -tabs -are calculated from the value you pass to L_MARGIN, -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 - -

-    .L_MARGIN 3P
-      or
-    .L_MARGIN .5i
-
-

- -

-If you use the macros -PAGE, -PAGEWIDTH -or -PAPER -without invoking L_MARGIN (either before -or afterwards), mom automatically sets -L_MARGIN to 1 inch. -

- -

-NOTE: L_MARGIN behaves in a special way when you're -using the -document processing macros. -See -Typesetting Macros in Document Processing -for an explanation. -

- - - -
- -

Right margin

 - -

-Macro: R_MARGIN <right margin> -
- -*Requires a unit of measure -

- -

-R_MARGIN 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. -R_MARGIN requires a unit of measure. Decimal -fractions are allowed. -

- -

-The -line length macro, -(LL), can be used in place of -R_MARGIN. 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. -

- -

-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: - -

-    .L_MARGIN 6P
-    .R_MARGIN 6P
-
- -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 LL is much easier than calculating the -right margin, e.g. - -
-    .LL 17P+3p
-
-

- -

-If you use the macros -PAGE, -PAGEWIDTH -or -PAPER -without invoking .R_MARGIN afterwards, -mom automatically sets R_MARGIN to -1 inch. If you set a line length after these macros (with -LL), -the line length calculated by R_MARGIN is, of course, -overridden. -

- -

-IMPORTANT: R_MARGIN, if used, MUST come after -PAPER, -PAGEWIDTH, -L_MARGIN -and/or -PAGE -(if a right margin isn't given to PAGE). The -reason is that R_MARGIN 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. -

- -

-NOTE: R_MARGIN behaves in a special way when you're -using the -document processing macros. -See -Typesetting Macros in Document Processing -for an explanation. -

- - - -
- -

Top margin

 - -

-Macro: T_MARGIN <top margin> -
- -*Requires a unit of measure -

- -

-T_MARGIN 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 - -

-    .T_MARGIN 2.5c
-
-

- -

-T_MARGIN calculates the vertical position of the -first line of type on a page by treating the top edge of the printer -sheet as a baseline. Therefore, - -

-    .T_MARGIN 1.5i
-
- -puts the baseline of the first line of type 1-1/2 inches beneath -the top of the page. -

- -

-IMPORTANT: T_MARGIN 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, -T_MARGIN should only be used at the top of a file -(prior to entering text) or after -NEWPAGE, -like this: - -

-    .NEWPAGE
-    .T_MARGIN 6P
-    <text>
-
-

- -

-NOTE: T_MARGIN means something -slightly different when you're using the -document processing macros. -See -Top and bottom margins in document processing -for an explanation. -

- - - -
- -

Bottom margin

 - -

-Macro: B_MARGIN <bottom margin> -
- -*Requires a unit of measure -

- -

-B_MARGIN 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, mom starts a new page. -B_MARGIN requires a unit of measure. Decimal -fractions are allowed. To set a nominal bottom margin of 3/4 inch, -enter - -

-    .B_MARGIN .75i
-
-

- -

-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 before the bottom margin causes -mom to start a new page. -

- -

-Occasionally, owing to a peculiarity in groff, -an extra line will fall below the nominal bottom margin. If you're -using the -document processing macros, -this is unlikely to happen; the document processing macros are very -hard-nosed about aligning bottom margins. -

- -

-NOTE: The meaning of B_MARGIN is -slightly different when you're using the document processing macros. -See -Top and bottom margins in document processing -for an explanation. -

- - - -
- -

Page

 - -

-Macro: PAGE <width> [ <length> [ <lm> [ <rm> [ <tm> [ <bm> ] ] ] ] ] -
- -*All arguments require a unit of measure -

- -

-PAGE lets you establish paper dimensions -and page margins with a single macro. The only required -argument is page width. The rest are optional, but -they must appear in order and you can't skip over any. -<lm>, <rm>, <tm> and -<bm> refer to the left, right, top and -bottom margins respectively. -

- -

-Assuming your page dimensions are 11 inches by 17 inches, and that's -all you want to set, enter - -

-    .PAGE 11i 17i
-
-

- -

-If you want to set the left margin as well, say, at 1 inch, -PAGE would look like this: - -

-    .PAGE 11i 17i 1i
-
-

- -

-Now suppose you also want to set the top margin, say, at 1-1/2 -inches. <tm> comes after <rm> -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 PAGE macro would look like this: - -

-    .PAGE 11i 17i 1i 1i 1.5i
-                     |   |
-    required right___|   |___top margin
-            margin
-
-

- -

-Clearly, PAGE is best used when you want a -convenient way to tell mom 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 -

- -
-    .PAGE 8.5i 11i 45p 45p 45p 45p
-
- -

-This sets up an 8-1/2 by 11 inch page with margins of 45 points -(5/8-inch) all around. -

- -

-NOTE: Only use PAGE at the start -of a document, before entering any text. And remember, when you're -using the -document processing macros, -top margin and bottom margin mean something slightly different than -when you're using just the typesetting macros (see -Top and bottom margins in document processing). -

- -

-Additionally, if you invoke .PAGE with a top margin -argument, any macros you invoke after .PAGE will almost -certainly move the -baseline -of the first line of text down by one linespace. To compensate, do - -

-    .RLD 1v
-
- -immediately before entering any text, or, if it's feasible, make -PAGE the last macro you invoke prior to entering text. -

- -

-Please read the -Important note on page dimensions and papersize -for information on ensuring groff respects your -PAGE dimensions and margins. -

- - - -
- -

Start a new page

 - -

-Macro: NEWPAGE -

- -

-Whenever you want to start a new page, use NEWPAGE, -by itself with no argument. Mom will finish up -processing the current page and move you to the top of a new one -(subject to the top margin set with -T_MARGIN. -

- -

-Experts: Prior to version 1.1.9, -NEWPAGE was simply an alias of .bp. As -of 1.1.9, NEWPAGE, is its own mom -macro. While the new macro should be backwardly compatible with -documents created using pre-1.1.9 moms, I suggest -that from this version onward, if you were in the habit of using -.bp whenever you wanted to break to a new page, you now -begin to use NEWPAGE instead. -

- -
- - - - - -

Basic typesetting parameters

 - -

-Basic parameter macros deal with the fundamental requirements -for setting type: family, font, point size, leading and line length. -

- -

-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 -Typesetting Macros in Document Processing -for an explanation. -

- -

Basic parameter macros list

 - - - - - -
- -

Type family

 - -

-Macro: FAMILY <family> -
- -Alias: FAM -

- -

-FAMILY takes one argument: the name of the -family -you want. Groff comes with a number of PostScript families, each -identified by a 1-, 2-or 3-letter mnemonic. The standard families -are: - -

-    A   = Avant Garde
-    BM  = Bookman
-    H   = Helvetica
-    HN  = Helvetica Narrow
-    N   = New Century Schoolbook
-    P   = Palatino
-    T   = Times Roman
-    ZCM = Zapf Chancery
-
-

- -

-The argument you pass to FAMILY is the identifier at -left, above. For example, if you want Helvetica, enter - -

-    .FAMILY H
-
-

- -

-NOTE: The -font macro -(FT) lets you specify both the type family -and the desired font with a single macro. While this saves a few -keystrokes, I recommend using FAMILY for family, -and FT for font, except where doing so is genuinely -inconvenient. ZCM, for example, only exists in one -style: Italic (I). Therefore, .FT ZCMI -makes more sense than setting the family to "ZCM", then -setting the font to "I". -

- - - -

-ADDITIONAL NOTE: As of mom, version -1.1.9-a, if you are running a version of groff lower -than 1.19.2, you MUST follow all FAMILY -requests with a FT request, otherwise -mom will set all type up to the next -FT request in the -fallback font. -

- -

-If you are running a version of groff greater than or equal -to 1.19.2, when you invoke the FAMILY macro, -mom "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: - -

-    .FAMILY BM   \" Bookman family
-    .FT     I    \" Medium Italic
-    <some text>  \" Bookman Medium Italic
-    .FAMILY H    \" Helvetica family
-    <more text>  \" Helvetica Medium Italic
-
-

- -

-However, if the font style does not exist in the new family, -mom will set all subsequent type in the -fallback font -(by default, Courier Medium Roman) until she encounters a -.FT -request that's valid for the family. For example, assuming -you don't have the font "Medium Condensed Roman" -(mom extension "CD") -in the Helvetica family: - -

-    .FAMILY UN    \" Univers family
-    .FT     CD    \" Medium Condensed
-    <some text>   \" Univers Medium Condensed
-    .FAMILY H     \" Helvetica family
-    <more text>   \" Courier Medium Roman!
-
-

- -

-In the above example, you must follow .FAMILY H with a -FT request that's valid for Helvetica. -

- -

-Experts: 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 - -

-    GARAMONDR
-    GARAMONDI
-    GARAMONDB
-    GARAMONDBI
-
- -GARAMOND then becomes a valid family name you can pass to -FAMILY. (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. -

- -

-Please see the Appendices, -Adding PostScript fonts to groff, -for information on adding fonts and families to groff, as well as -to see a list of the extensions mom provides to -groff's basic R, I, B, BI styles. -

- - - -
- -

Font

 - -

-Macro: FT R | I | B | BI | <any other valid font style> -

- -

-By default, groff permits FT to take one of four -possible arguments specifying the desired font: - -

-    R  = (Medium) Roman
-    I  = (Medium) Italic
-    B  = Bold (Roman)
-    BI = Bold Italic
-
-

- -

-For example, if your -family -is Helvetica, entering - -

-    .FT B
-
- -will give you the Helvetica bold -font. -If your family were Palatino, you'd get the Palatino bold font. -

- -

-(As of mom, version 1.1.9-a, the range of arguments -that can be passed to FT has been considerably -extended, allowing access to a greater variety of font -weights -and -shapes. -Please see the -NOTE, -below.) -

- -

-How mom reacts to an invalid argument to -FT depends on which version of groff you're -using. If your groff version is greater than or equal to 1.19.2, -mom will issue a warning and, depending on how -you've set up the -fallback font, -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, mom will silently continue -processing, using either the fallback font or the font that was in -effect prior to the invalid FT call. -

- -

-FT will also accept, as an argument, a full -family+font name. For example, - -

-    .FT HB
-
- -will set subsequent type in Helvetica Bold. However, I strongly -recommend keeping family and font separate except where doing so is -genuinely inconvenient. -

- -

-For inline control of fonts, see -Inline Escapes, font control. -

- - - -

-NOTE: mom, versions 1.1.9-a and higher, -considerably extends the range of arguments you can pass to -FT, making it more convenient to add and access -fonts of differing -weights -and -shapes -within the same family. Have a look -here -for a list of the weight/style arguments mom -allows. -

- -

-Be aware, though, that you must have the fonts, correctly -installed and named, in order to use the arguments. (See -How to create a PostScript font for use with groff -for how to add fonts to groff.) Please also read the -ADDITIONAL NOTE -found in the description of the FAMILY macro. -

- - - -
- -

Fallback font

 - -

-Macro: FALLBACK_FONT <fallback font> [ ABORT | WARN ] -

- -

-In the event that you pass an invalid argument to -.FAMILY -(i.e. a non-existent family), mom, by default, uses -the fallback font, Courier Medium Roman (CR), in order to continue -processing your file. -

- -

-If you'd prefer another fallback font, pass -FALLBACK_FONT the full family+font -name of the font you'd like. For example, if you'd rather -the fallback font were Times Roman Medium Roman, - -

-    .FALLBACK_FONT TR
-
- -would do the trick. -

- -

-Additionally, if your version of groff accepts accepts ".if -F" and ".if S" (see -above), -mom issues a warning whenever a -font style set with -FT -does not exist, either because you haven't registered the style -(see -here -for instructions on registering styles), or because the font style -does not exist in the current family set with -FAMILY. -By default, mom then aborts, which allows you to -correct the problem. -

- -

-If you'd prefer that mom not abort on non-existent -fonts, but rather continue processing using a fallback font, you can -pass FALLBACK_FONT the argument WARN, -either by itself, or in conjunction with your chosen fallback font. -

- -

-Some examples of invoking FALLBACK_FONT: -

- - - -

-If, for some reason, you want to revert to ABORT, just enter -.FALLBACK_FONT ABORT and mom will once -again abort on font errors. -

- - - -
- -

Point size of type

 - -

-Macro: PT_SIZE <size of type in points> -
- -*Does not require a unit of measure -

- -

-PT_SIZE (Point Size) takes one argument: the size -of type in points. Unlike most other macros that establish the size -or measure of something, PT_SIZE 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 - -

-    .PT_SIZE 11
-
-

- -

-Point sizes may be fractional (e.g. 10.25 or 12.5). -

- -

-You can prepend a plus or a minus sign to the argument to -PT_SIZE, 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 - -

-    .PT_SIZE +2
-
- -then later reset it to 12 with - -
-    .PT_SIZE -2
-
-

- -

-The size of type can also be changed inline. See -Inline Escapes, changing point size. -

- -

-NOTE: It is unfortunate that the pic -pre-processor uses PS, and thus -mom's macro for setting point sizes can't use it. -However, if you aren't using pic, you might want to -alias -PT_SIZE as PS, since there'd be no -conflict. For example - -

-    .ALIAS PS PT_SIZE
-
- -would allow you to set point sizes with .PS. -

- - - -
- -

Line spacing/leading

 - -

-Macro: LS <distance between lines> -
- -*Does not require a unit of measure -

- -

-LS (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 PT_SIZE, -LS does not require a unit of measure, since -leading -is most often given in points. Therefore, to set the linespace to -14 points, you would enter - -

-    .LS 14
-
-

- -

-However, if you wish, you may specify a unit of measure by appending -it directly to the argument passed to LS. For -example, if you want a linespace of 1/4 of an inch, enter - -

-    .LS .25i
-
-

- -

-You can prepend a plus or a minus sign to the argument to -LS, 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 - -

-    .LS +3
-
- -then later reset it to 14 points with - -
-    .LS -3
-
-

- -

-Experts: LS should not be confused with -the groff primitive .ls. LS acts -like .vs. mom does not provide a -macro analogous to .ls. -

- - - -
- -

Automatic line spacing

 - -

-Macro: AUTOLEAD <amount of automatic leading> [FACTOR] -
- -*Does not require a unit of measure -

- -

-Without the FACTOR argument, AUTOLEAD -calculates the linespace for you by adding its argument to the -current point size of type. All subsequent -PT_SIZE -requests automatically update the linespacing by the autolead amount. -

- -

-Used in this way, AUTOLEAD 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). -

- -

-As an example, if your current point size of type is 12, entering - -

-    .AUTOLEAD 2
-
- -changes the linespace to 14 points, regardless any linespacing -already in effect. From here on, every change to the size of type -(with PT_SIZE, not -inline) -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. -

- -

-Automatic updating of the linespacing continues until you enter a -"manual" line space value with -LS. -

- -

-If you give AUTOLEAD the optional -FACTOR argument, AUTOLEAD -calculates the line space as a factor of the -numeric argument -you gave AUTOLEAD. For example, if your point size -is 12, - -

-    .AUTOLEAD 1.125 FACTOR
-
- -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). -

- -

-NOTE: There's no need to prepend a plus sign -(+) -to AUTOLEAD's argument, although you may do so if you -wish. -

- - - -
- -

Line length

 - -

-Macro: LL <line length> -
- -*Requires a unit of measure -

- -

-LL (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. -

- -

-LL requires a unit of measure. Therefore, to set the line -length to 39 picas, you would enter - -

-    .LL 39P
-
-

- -

-As with other macros that require a unit of measure, the argument to -LL may be fractional. For example, - -

-    .LL 4.5i
-
- -sets the line length to 4-1/2 inches. -

- -

-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 -points, you could -do - -

-    .LL +3p
-
- -This is especially handy when you want to "hang" -punctuation outside the right margin since you can pass groff's -\w -escape as the argument to LL, like this: - -
-    .LL +\w'.'u
-
-

- -

-The above example increases the current line length by the width of -a period. Notice that you must append the -unit of measure, -u, to the escape since LL requires -a unit of measure. -

- -

-NOTE: The -right margin macro, -(R_MARGIN), can also be used to set line length. -

- -
- - - -

Justifying, quadding, filling and breaking lines

 - -

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

- -

-These macros also determine whether or not -input lines -are joined and -filled -during output. -

- -

-Additionally, macros that deal with how to break -output lines -are covered in this section, as is the -inline escape -for joining input lines. -

- -

-You may encounter some words here that are unfamiliar. Refer to -Typesetting terms -and -Groff terms -for an explanation. -

- -

Justification, quad, fill, and break macro list

 - - - - - -
- -

Justify lines

 - -

-Macro: JUSTIFY -
- -(See -fill mode -for a definition of the difference between "fill" and -"no-fill" modes.) -

- -

-JUSTIFY doesn't take an argument. -Input lines -after JUSTIFY are -filled -and -justified -upon output. -

- -

-To break lines and prevent them from being filled and justified, -use the -BR -macro. -

- - - -
- -

Quad lines left, right, or centre

 - -

-Macro: QUAD L | LEFT | R | RIGHT | C | CENTER | J | JUSTIFY -
- -Alias: FILL -
- -(See -fill mode -for a definition of the difference between "fill" and -"no-fill" modes.) -

- -

-QUAD takes one argument: the direction in which lines -should be -quadded. -Input lines -after QUAD are -filled -upon output. -

- -

-If L or LEFT, type is set flush along the left -margin. -

- -

-If R or RIGHT, type is set flush along the -right margin. -

- -

-If C or CENTER type is set centred on the -current line length. -

- -

-J and JUSTIFY justify text, and are included -as a convenience only. Obviously, if text is justified, it isn't -quadded. .QUAD J and .QUAD JUSTIFY have -exactly the same effect as -JUSTIFY. -

- -

-To break lines and prevent them from being filled, use the -BR -macro. -

- - - -
- -

Set lines flush left, right, or centred in no-fill mode

 - -

-Macro: LEFT -
-Macro: RIGHT -
-Macro: CENTER  (alias CENTRE) -
- -(See -no-fill mode -for a definition of the difference between "fill" and -"no-fill" modes.) -

- -

-LEFT, RIGHT and -CENTER let you enter text on a line for line basis -without having to use the -BR -macro after each line. Consider the following: - -

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

- -

-Because text after .QUAD LEFT is -filled, -you have to use the -BR -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 - -

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

- -

-IMPORTANT: Because LEFT, -RIGHT and CENTER are nofill -modes, groff does not always respect the current line length. -Input lines -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. -

- - - -
- -

Manually break lines

 - -

-Macro: BR -

- -

-When using -JUSTIFY -or -QUAD, -BR tells mom about partial lines -that you want broken (as opposed to -filled). -Any partial -output line -that immediately precedes BR will be -quadded -in the direction of the current quad, or set flush left if text is -justified. -

- -

-Most of the time, you won't need the BR macro. -In fill modes, mom 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, mom 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 BR's. -

- -

-NOTE: Lines of text in -nofill mode -never require a BR. Furthermore, in nofill mode, -ALL macros cause a break. If a break is not desired, use the -\c -inline escape. -

- -

-Experts: BR is an alias for .br. -You can use either, or mix 'n' match with impunity. -

- - - -
- -

Manually break a line without advancing on the page

 - -

-Macro: EL -
- -*In nofill modes -(LEFT, -RIGHT, -CENTER>), -you must terminate the line input preceding EL -with the \c inline escape. See -NOTES, -below. -
- -  If you find remembering whether to put in the -\c bothersome, you may prefer to use the -inline escape -alternative to EL, -\*[B], -which works consistently regardless of the fill mode. -EL does not work after the -PAD -macro. See -.PAD NOBREAK -for the way around this. -

- -

-The mnemonic "EL" is borrowed from old Compugraphic -typesetting systems, where it stood for "End Line." Conceptually, -EL is equivalent to the notion of a carriage return -with no linefeed. -

- -

-Note to groff jocks: EL is unrelated to -groff's .el. If you find the similarity confusing, -you may want to alias EL as something else (but -don't use EOL; mom uses it -internally.) -

- -

-EL's function is simple: it breaks a line without -advancing on the page. - - - -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 EL and instruct mom 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: - -

-    .LEFT
-    .LS 12.5
-    A line of text.\c
-    .EL
-    .ALD 24p
-    The next line of text.
-
- -may be more intuitive than - -
-    .LEFT
-    .LS 12.5
-    A line of text.
-    .ALD 11.5p
-    The next line of text.
-
-

- -

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

- -

-"ALD" in the above examples stands for "Advance -LeaD" (another mnemonic borrowed -from Compugraphic), which is covered in the section -Vertical movement. -

- -

NOTES:

 - -

-In versions of mom prior to 1.1.9, EL did not -always work as advertised on the last -output line -of pages that contained a footer trap (e.g. one set with -B_MARGIN -or in documents formatted using the -document processing macros). -

- -

-EL has been re-written so that this should no longer be the -case. However, in order for it to work in the -nofill -modes -(LEFT, -RIGHT -or -CENTER), -you must always "join" .EL to the line before -it using the -\c -inline escape, -like this: - -

-    .LEFT
-    A line I don't want to advance\c
-    .EL
-
-

- -

-Conversely, in -fill modes -(QUAD LEFT, -QUAD RIGHT, -QUAD CENTER -or -JUSTIFY), -the \c must not be used. -

- -

-If EL is used after most macros or groff -primitives -(see the exception, below), you don't have to worry about this, -regardless of the fill mode. Just type .EL -

- - - -
- -

Break lines and add space between

 - -

-Macro: SPACE <space to add between lines> -
- -Alias: SP -

- -

-SPACE breaks a line, just like -BR, -then adds space after the line. With no argument, it adds an extra -line space of a value equal to the current -leading. -If you pass it a numeric argument without supplying a -unit of measure, -it advances that number of extra line spaces. For example: - -

-    .SPACE
-
- -breaks the line then adds an extra linespace, whereas - -
-    .SPACE 2
-
- -breaks the line and adds two extra linespaces. -

- -

-If you supply a unit of measure, SPACE breaks the -line then advances one linespace (at the current -leading) -PLUS the specified amount of extra space given to -SPACE, as in - -

-    .SPACE 6p
-
- -which breaks the line and advances one full linespace plus six -points. -

- -

-SUGGESTION: SPACE and -ALD -can be used interchangeably (.SPACE 6p and -.ALD 6p are equivalent). However, -ALD without an argument does nothing, whereas -SPACE without an argument adds an extra line -space. I recommend using SPACE when you -want an extra line space (or multiple thereof), and -ALD whenever you want some other value of space -after a line. -

- -

-Experts: SPACE is an alias of .sp. You -can use either, or mix 'n' match with impunity. -

- - - -
- -

Break and force justify (spread) lines

 - -

-Macro: SPREAD -

- -

-Sometimes, you need to break a line of -justified -text and have it come out fully justified, not -quadded -left the way it would be with the -BR -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). SPREAD is the macro that lets you -break the line and have it came out fully justified. -

- -

-Experts: SPREAD is an alias for .brp -You can use either, or mix 'n' match with impunity. -

- - - -
- -

Join input lines

 - -

-Inline: \c -

- -

-Sometimes, especially when in one of the -nofill modes, -a macro will cause a break where you don't want one. In order to -prevent this from happening (in other words, to join -input lines -together, forming one -output line), -use the groff -inline escape -\c at the end of each input line to be joined to another, -like this: - -

-    .LEFT
-    .FAMILY T
-    .FT R
-    Some lines of text to be \c
-    .FAMILY H
-    .FT B
-    joined \c
-    .FAMILY T
-    .FT R
-    together.
-
-

- -

-Upon output, the lines will be joined together to read - -

-    Some lines of text to be joined together.
-
- -with the word "joined" in Helvetica bold. Note the space -before \c. Without it, the last three words of the -output line would read - -
-    bejoinedtogether
-
-

- -

-Please also note that had the example been in one of the -fill modes, -there'd have been no need for the \c. -

- -

-Addendum: The example, above, is designed to -demonstrate the use of \c. However, an easier and more -intuitive way to accomplish the family/font change in the example -would be with the groff -inline escape, -\f, -like this: - -

-    Some lines of text to be \f[HB]joined\*[PREV] together.
-
-

- -
- - - - - -

Typographic refinements

 - -

-The macros in this section help you tweak groff's behaviour, -ensuring that your documents look typographically professional. -

- -

Typographic refinements macro list

 - - - - - -
- -

Word spacing

 - -

-Macro: WS <+|-wordspace> | DEFAULT -

- -

-WS (Word Space) increases or decreases the amount -of space between words. In -nofill modes, -or if -QUAD -is in effect, the space between words is fixed. Therefore, if you -change the word spacing with WS, the change applies -uniformly to the space between every word on every line. However, -when text is -justified, -the space between words varies from line to line (in order to -justify the text). Consequently, the change you make with -WS 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. -

- -

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

- - - -

-WS takes as its argument a number (decimal -fractions are allowed) preceded by a plus or minus sign. Therefore, -to decrease the word space slightly, you might enter - -

-    .WS -4
-
-

- -

-To increase it by a noticeable amount, you might enter - -

-    .WS +12
-
-

- -

-You can reset the word spacing to its previous value by switching -the plus or minus sign, like this: - -

-    .WS +4
-    A line of text
-    .WS -4
-
-

- -

-The .WS -4 undoes the effect of .WS +4. You -can also reset WS to its groff default by entering - -

-    .WS DEFAULT
-
-

- -

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

- - - -
- -

Sentence space

 - -

-Macro: SS <+sentence space> | 0 | DEFAULT -

- -

-SS (Sentence Space) tells groff how to treat double -spaces it encounters between sentences in -input lines. -If you use SS, 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 -SS. Thus, - -

-    .SS +2
-
- -means that input sentences with two spaces after them receive a normal -word space PLUS the +2 value passed to SS. -

- -

-Like -WS, -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 SS. -

- -

-There's an additional argument you can pass SS: -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 - -

-    .SS 0
-
- -at the top of your files. -

- -

-If you do use SS 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 - -

-    .SS DEFAULT
-
-

- -

-If you're using the -document processing macros -and your -PRINTSTYLE -is TYPEWRITE, .SS DEFAULT is -the default, because you do want double spaces between -sentences in copy that imitates the look of a typewritten document. -

- -

-IMPORTANT: SS 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 SS when you habitually -put only one space between sentences, you risk producing output -where the space between sentences is not equal. -

- - - -
- -

Automatic hyphenation control

 - -

-Macro: HY toggle -
-Macro: HY LINES <max. number of consecutive hyphenated lines> -
-Macro: HY MARGIN <size of hyphenation margin> -
-Macro: HY SPACE <extra interword spacing to prevent hyphenation> -
-Macro: HY DEFAULT -
-Aliases: HYPHENATE, HYPHENATION -

- -

-HY, as you can see, can be invoked with a number of -arguments. In all cases, the aliases HYPHENATE -or HYPHENATION can be used in place of -HY. To aid in understanding the various arguments -you can pass to HY, I've broken them down into -separate sections. -

- -

1. HY

- -

-HY by itself (i.e. with no argument) simply turns -automatic hyphenation on. Any argument other than LINES, -MARGIN, SPACE or DEFAULT, turns -automatic hyphenation off. For example, as explained in How to read macro arguments, you -could turn HY off by entering - -

-    .HY OFF
-       or
-    .HY X
-       or
-    .HY END
-
-

- -

-HY observes the following default hyphenation rules: - -

    -
  1. Last lines (i.e. ones that will spring a trap — typically - the last line on a page) will not be hyphenated. -
    2. -
  2. The first and last two characters of a word are never - split off. -
    3. -
-

- -

2. HY LINES

- -

-HY LINES 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 - -

-    .HY LINES 2
-
-

- -

-By default, when you turn automatic hyphenation on, there is no -limit to the number of consecutive hyphenated lines. -

- -

-NOTE: -Discretionary hyphens -count when groff is figuring out how many lines to hyphenate; -explicit hyphens do not. -

- -

3. HY MARGIN

- -

-HY MARGIN 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). HY MARGIN only applies if you're -using -QUAD, and is really only useful if you're -using QUAD LEFT. -

- -

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

-    .HY MARGIN 18p
-
-

- -

-NOTE: The numeric argument after HY -MARGIN requires a -unit of measure. -

- -

4. HY SPACE

- -

-HY SPACE sets an amount of extra interword -space that groff will try to put between words on a -line in order to PREVENT hyphenation. HY SPACE -applies only to -justified lines. -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 - -

-    .HY SPACE .5p
-        or
-    .HY SPACE 1p
-
-

- -

-NOTE: The numeric argument after HY -SPACE requires a -unit of measure. -

- -

5. HY DEFAULT

- -

-HY DEFAULT resets automatic hyphenation -to its default behaviour, cancelling any changes made with -HY LINES, HY -MARGIN, and/or HY SPACE. -

- -

A note on hyphenation in general

- -

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

- -

-Furthermore, hyphenation in -rag -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 HY MARGIN a bit if -your copy looks hyphen-heavy. -

- - - -
- -

Set hyphenation parameters all at once

 - -

-Macro: HY_SET <lines> [ <margin> [ <space> ] ] -
- -Alias: HYSET -

- -

-HY_SET lets you set the parameters for hyphenation -with a single macro. <lines>, -<margin> and -<space> correspond to the numeric -values required by LINES, -MARGIN and SPACE as described -above. -

- -

-To set just the maximum number of consecutive hyphenated lines, -you'd enter - -

-    .HY_SET 2
-
-

- -

-If you wanted the same number of maximum consecutive hyphenated lines -and a hyphenation margin for use with -rag -copy, - -

-    .HY_SET 2 36p
-
- -would set the hyphenation margin to 36 points. -

- -

-If you wanted the same number of maximum consecutive hyphenated -lines and a hyphenation space of 2 points for use with -justified -copy, - -

-    .HYSET 2 0 2p
-
- -is how you'd do it. -

- - - -
- -

Reduce whitespace

 - -

-Macro: RW <amount of whitespace reduction between letters> -

- -

-RW (Reduce Whitespace) and its corresponding macro, -EW (Expand Whitespace), allow you to tighten -(or loosen) -output lines -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. -

- -

-The value passed to RW 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, - -

-    .RW .1
-      or
-    .RW .2
-
- -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 -RW. -

- -

-IMPORTANT: In versions prior to 1.1.9-a, -RW affected all -fonts -in the -family -current at the time it was invoked. As of 1.1.9-a, this behaviour -has been changed. RW 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 (.RW 0) on that font. -

- -

-NOTE: By default, RW does not deposit a -break -when it's invoked if you're in one of the -fill -modes (i.e. -QUAD -L, R, C, J or -JUSTIFY). -If you want -RW to break at the ends of the previous -input lines -while you're in a fill mode, tell mom -that's what you want by invoking the -.BR_AT_LINE_KERN -toggle macro. -

- - - -
- -

Expand whitespace

 - -

-Macro: EW <amount of whitespace expansion between letters> -

- -

-EW (Expand Whitespace) expands the amount of -whitespace between letters, effectively "loosening" lines -of type. -

- -

-The value passed to EW 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, - -

-    .EW .1
-      or
-    .EW .2
-
- -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 EW. -

- -

-IMPORTANT: In versions prior to 1.1.9-a, -EW affected all -fonts -in the -family -current at the time it was invoked. As of 1.1.9-a, this behaviour -has been changed. EW 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 (.EW 0) on that font. -

- -

-NOTE: By default, EW does not deposit a -break -when it's invoked if you're in one of the -fill -modes (i.e. -QUAD -L, R, C, J or -JUSTIFY). -If you want -EW to break at the ends of the previous -input lines -while you're in a fill mode, tell mom -that's what you want by invoking the -.BR_AT_LINE_KERN -toggle macro. -

- - - -
- -

Break before line kerning

 - -

-Macro: BR_AT_LINE_KERN toggle -

- -

-By default, in -fill -modes (i.e. -QUAD -L, R, C, J or -JUSTIFY) -mom does not break -input lines -when you invoke -RW -or -EW. -If you'd like her to break input lines prior to RW -or EW, invoke .BR_AT_INPUT_LINE -without any argument. To disable the breaks, invoke -.BR_AT_INPUT_LINE with any argument (OFF, QUIT, -Q, X...), like this - -

-    .BR_AT_LINE_KERN OFF
-        or
-    .BR_AT_LINE_KERN X
-
-

- -

-With QUAD L, R or C, -mom simply breaks the line. With QUAD -J (or just JUSTIFY, which is the same -thing), she breaks and -force justifies -the line prior to .EW or .RW. -

- - - -
- -

Automatic kerning

 - -

-Macro: KERN toggle -

- -

-By itself (i.e. with no argument), KERN turns -automatic pairwise -kerning -on. With any argument (e.g. OFF, Q, X), pairwise kerning is turned -off. -

- -

-Kerning of individual character pairs can be controlled with -the inline escapes -\*[BU <n>] and -\*[FU <n>]. See -Inline Escapes, kerning. -

- - - -
- -

Automatic ligature generation

 - -

-Macro: LIGATURES toggle -
- -Alias: LIG -

- -

-Provided your current font has -ligatures, -LIGATURES, 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 mom has them on by default. -

- -

-LIGATURES with any argument turns automatic -ligature generation off. -

- -

-NOTE: Not all fonts support ligatures. -

- -
- - - -

Type modifications: -
- -pseudo-italic, -bold, -condensed, -extended

 - -

-It sometimes happens that a PostScript -family -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. -

- -

Type modifications macro list

 - - - - - -
- -

Set degree of slant for pseudo-italicizing

 - -

-Macro: SETSLANT <degrees to slant type> | RESET -

- -

-Pseudo-italicizing of type is accomplished by slanting a roman font -a certain number of degrees to the right. SETSLANT -lets you fix the number of degrees. Mom'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 - -

-    .SETSLANT 13
-
-

- -

-If you change the degree of slant and later want to set it back -to the mom default, do - -

-    .SETSLANT RESET
-
-

- -

-NOTE: By itself, SETSLANT will not -start pseudo-italicizing type; it merely tells mom -what degree of slant you want. To start pseudo-italicizing, use the -inline escape -\*[SLANT]. -

- - - -
- -

Pseudo italic on/off

 - -

-Inline: \*[SLANT] — turn pseudo-italic on -
- -Inline: \*[SLANTX] — turn pseudo-italic off -

- -

-\*[SLANT] begins pseudo-italicizing type. -\*[SLANTX] turns the feature off. Both are -inline escapes, -therefore they should not appear as separate lines, but rather be -embedded in text lines, like this: - -

-    Not \*[SLANT]everything\*[SLANTX] is as it seems.
-
-

- -

-Alternatively, if you wanted the whole line pseudo-italicized, -you'd do - -

-    \*[SLANT]Not everything is as it seems.\*[SLANTX]
-
-

- -

-Once \*[SLANT] is invoked, it remains in effect until -turned off. -

- -

-NOTE: If you're using the -document processing macros -with -PRINTSTYLE TYPEWRITE, -mom underlines pseudo-italics by default. To -change this behaviour, use the special macro -SLANT_MEANS_SLANT. -

- - - -
- -

Set amount of emboldening

 - -

-Macro: SETBOLDER <amount of emboldening, in machine units> | RESET -

- -

-Emboldening of type is accomplished by printing characters -twice; the second printing is slightly offset from the first, -effectively "thickening" the character. -SETBOLDER lets you set the number of -machine units -for the offset. Mom'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 - -

-    .SETBOLDER 500
-
-

- -

-If you change the emboldening offset and later want to set it back -to the mom default, do - -

-    .SETBOLDER RESET
-
-

- -

-NOTE: By itself, SETBOLDER -will not start emboldening type; it merely tells -mom what you want the emboldening offset to be. -To start emboldening, use the -inline escape -\*[BOLDER]. -

- - - -
- -

Emboldening on/off

 - -

-Inline: \*[BOLDER] — turn emboldening on -
- -Inline: \*[BOLDERX] — turn emboldening off -

- -

-\*[BOLDER] begins emboldening type. -\*[BOLDERX] turns the feature off. Both are -inline escapes, -therefore they should not appear as separate lines, but rather -be embedded in text lines, like this: - -

-    Not \*[BOLDER]everything\*[BOLDERX] is as it seems.
-
-

- -

-Alternatively, if you wanted the whole line emboldened, -you'd do - -

-    \*[BOLDER]Not everything is as it seems.\*[BOLDERX]
-
-

- -

-Once \*[BOLDER] is invoked, it remains in effect -until turned off. -

- -

-NOTE: If you're using the -document processing macros -with -PRINTSTYLE TYPEWRITE, -mom ignores \*[BOLDER] requests. -

- - - -
- -

Set percentage for pseudo-condensed type

 - -

-Macro: CONDENSE <pseudo-condense percentage> -

- -

-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. -CONDENSE tells mom what -percentage of the normal character width you want the characters -to be condensed. -

- -

-Mom has no default value for -CONDENSE, therefore you must set it before using -the -inline escape -\*[COND]. -80 percent of the normal character width is a good value, and you'd -set it like this: - -

-    .CONDENSE 80
-
-

- -

-NOTE: By itself, CONDENSE will not -start pseudo-condensing type; it merely tells mom -what percentage of the normal character width you want characters to -be condensed. To start pseudo-condensing, use the -inline escape -\*[COND]. -

- -

-Additional note: Make sure that pseudo-condensing -is off (with -\*[CONDX]) -before before making any changes to the pseudo-condense percentage -with CONDENSE. -

- - - -
- -

Pseudo-condensing on/off

 - -

-Inline: \*[COND] — turn pseudo-condensing on -
- -Inline: \*[CONDX] — turn pseudo-condensing off -

- -

-\*[COND] begins pseudo-condensing type. -\*[CONDX] turns the feature off. Both are -inline escapes, -therefore they should not appear as separate lines, but rather -be embedded in text lines, like this: - -

-    \*[COND]Not everything is as it seems.\*[CONDX]
-
-

- -

-\*[COND] remains in effect until you turn it -off with \*[CONDX]. -

- -

-IMPORTANT: You MUST turn \*[COND] -off before making any changes to the point size of your type, either -via the -PT_SIZE -macro or with the \s inline escape. If you wish -the new point size to be pseudo-condensed, simply reinvoke -\*[COND] afterwards. Equally, \*[COND] must -be turned off before changing the condense percentage with -CONDENSE. -

- -

-NOTE: If you're using the -document processing macros -with -PRINTSTYLE TYPEWRITE, -mom ignores \*[COND] requests. -

- - - -
- -

Set percentage for pseudo-extended type

 - -

-Macro: EXTEND <pseudo-extend percentage> -

- -

-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. EXTEND tells mom what -percentage of the normal character width you want the characters to -be extended. -

- -

-Mom has no default value for -EXTEND, therefore you must set it before -using the -inline escape -\*[EXT]. -120% of the normal character width is a good value, and you'd set it -like this: - -

-    .EXTEND 120
-
-

- -

-NOTE: By itself, EXTEND will not -start pseudo-extending type; it merely tells mom -what percentage of the normal character width you want characters to -be extended. To start pseudo-extending, use the -inline escape -\*[EXT]. -

- -

-Additional note: Make sure that pseudo-extending is -off (with -\*[EXTX]) -before before making any changes to the pseudo-extend percentage -with EXTEND. -

- - - -
- -

Pseudo-extending on/off

 - -

-Inline: \*[EXT] — turn pseudo-extending on -
- -Inline: \*[EXTX] — turn pseudo-extending off -

- -

-\*[EXT] begins pseudo-extending type. -\*[EXTX] turns the feature off. Both are -inline escapes, -therefore they should not appear as separate lines, but rather -be embedded in text lines, like this: - -

-    \*[EXT]Not everything is as it seems.\*[EXTX]
-
-

- -

-\*[EXT] remains in effect until you turn it off with -\*[EXTX]. -

- -

-IMPORTANT: You MUST turn \*[EXT] off -before making any changes to the point size of your type, either via -the -PT_SIZE -macro or with the \s inline escape. If you wish the new -point size to be pseudo-extended, simply reinvoke \*[EXT] -afterwards. Equally, \*[EXT] must be turned off before -changing the extend percentage with -EXTEND. -

- -

-NOTE: If you're using the -document processing macros -with -PRINTSTYLE TYPEWRITE, -mom ignores \*[EXT] requests. -

- -
- - - -

Vertical movement

 - -The two macros in this section allow you to move down or up on the -page relative to the current -baseline. - -

Vertical movement macro list

 - - - - - -
- -

Advance Lead (move downward)

 - -

-Macro: ALD <distance to move downward> -
- -*Requires a unit of measure -

- -

-ALD takes one argument: the distance to move downward -on the page relative to the current vertical position. -

- -

-Used by itself, or preceded by -BR, -ALD will advance by one line space plus the -distance you specify. Preceded by -EL, -it will advance by exactly the distance you specify. -

- -

-ALD 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 - -

-    .ALD .25i
-        or
-    .ALD 1P+6p
-
-

- -

-As the mnemonic (Advance -LeaD) suggests, you'll most often -use ALD with -points -of lead. -

- -

-NOTE: if you want to use ALD -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: - -

-    .ALD 1i-1v
-
-

- -

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

- - - -
- -

Reverse Lead (move upward)

 - -

-Macro: RLD <distance to move upward> -
- -*Requires a unit of measure -

- -

-RLD takes one argument: the distance to move -upward on the page relative to the current vertical position. -

- -

-Used by itself, or preceded by -BR, -RLD will advance by one line space, then -reverse by the distance you specify. Preceded by -EL, -it will reverse by exactly the distance you specify. -

- -

-RLD 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 - -

-    .RLD .25i
-        or
-    .RLD 1P+6p
-
-

- -

-As the mnemonic (Reverse -LeaD) suggests, you'll most often -use RLD with -points -of lead. -

- -
- - - -

Tabs

 - -

-Mom 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 mom handles -tabs. -

- -

-NOTE: see the section -Using typesetting macros during document processing -for re-assuring information on the use of tabs during -document processing. -

- -

Typesetting tabs

 - -

-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 -multi-column macros, -typesetting tabs significantly facilitate -tabular and columnar work. -

- -

-Typesetting tabs are created with the -TAB_SET -macro. TAB_SET 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 -TAB_SET, they can be called at any time with the -TAB -macro. -

- -

Quickie tutorial on typesetting tabs

 - -

-Say you want to set up three tabs to produce an employee evaluation -that looks something like this: - - -

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

- -

-You want the first tab ("CRITERION") - -

-

- -

-Tabs must be numbered, and each has to be set up with a separate -TAB_SET -line. Therefore, to set up tab 1, you enter - -

-   .TAB_SET  1  0  5P  L
-             |  |  |   |
-      tab #__|  |  |   |__direction
-                |  |
-        indent__|  |__length
-
-

- -

-You want the second tab ("EVALUATION") - -

-

- -

-You set it up like this: - -

-   .TAB_SET  2  8P  9P  C
-             |  |   |   |
-      tab #__|  |   |   |__direction
-                |   |
-        indent__|   |__length
-
-

- -

-You want the third tab ("COMMENTS") - -

-

- -

-The setup looks like this: - -

-   .TAB_SET  3  19P  17P  L  QUAD
-             |   |    |   |    |
-             |   |    |   |    |__fill output lines
-             |   |    |   |
-      tab #__|   |    |   |__direction
-                 |    |
-         indent__|    |__length
-
-

- -

-Once the tabs are set up, you can call them in one of two ways: - -

-

- -

-To exit from tabs and restore your original left margin, line length, -quad direction and fill mode, use -TQ -(Tab Quit). -

- -

-Here's how the input for our sample employee evaluation looks -(with some introductory parameters): - -

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

- -

-Try setting this up and previewing it with - -

-    groff -mom -X <filename>
-
-

- -

-Notice how .TN simply moves over to the next tab, -while the combination .SP/.TAB 1 breaks the -line, advances by one extra linespace, and calls the first tab. -

- -

-Notice, too, how the QUAD argument passed to -tab 3 means you don't have to worry about the length of -input lines; -mom -fills -the tab and sets the type flush left. -

- -

String tabs (autotabs)

 - -

-String tabs let you mark off tab positions with -inline escapes -embedded in -input lines. -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. -

- -

-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 -SILENT -macro.) -

- -

-Next, you invoke the -ST -macro for every string tab you defined, and optionally pass quad and -fill information to it. That done, string tabs are called with the -TAB -macro, just like typesetting tabs. -

- -

-In combination with the -PAD -macro and the groff inline escape -\h -(move horizontally across the page) or mom's -\*[FWD <distance>] -(move forward) inline, string tabs provide -tremendous flexibility in setting up complex tab structures. -

- -

Quickie tutorial on string tabs

 - -

-Say you want to set up tabs for the -employee evaluation form -used as an example in the -typesetting tabs tutorial. -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 - -

-

- -

-This is an ideal job for string tabs. -

- -

-The first thing you need for string tabs is an -input line -with tab positions marked on it. Tabs are marked with the -inline escapes -\*[ST<n>] -and -\*[ST<n>X], -where <n> -is the number you want the tab to have. (In this example, we -enclose the input line with the -SILENT -macro so the line doesn't print. We also use the -PAD -macro to permit defining tab 3 as simply "the amount of -space remaining on the input line.") -

- -

-The setup looks like this: - -

-    .SILENT
-    .PAD "\*[ST1]CRITERION\*[ST1X]\*[FWD 12p]\*[ST2]EVALUATION\*[ST2X]\*[FWD 12p]\*[ST3]#\*[ST3X]"
-    .SILENT OFF
-
-

- -

-The long line after .PAD looks scary, but it isn't. -Here's what it means when broken down into its component parts: - -

-

- -

-The tabs are now defined, but they require -quad direction -and -fill -information. For each string tab defined above, enter a -separate -ST -line, like this: - -

-    .ST  1  L
-    .ST  2  L
-    .ST  3  L  QUAD
-         |  |   |
-         |  |   |__fill output lines
-         |  |
-    tab__|  |__direction
-    number
-
-

- -

-From here on in, you call the tabs with -TAB -and -TN -just like typesetting tabs (see -typesetting tabs tutorial). -

- -

-Here's the complete setup and entry for the sample employee -evaluation form utilizing string tabs. - -

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

- -

-Try setting this up and previewing it with - -

-    groff -mom -X <filename>
-
-

- -

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

- -

-Now try increasing the gutters to 2 picas (\*[FWD 24p] or -\*[FWD 2P] instead of \*[FWD 12p]). Preview the -file again, and notice how the tab structure remains the same, but -the gutters are wider. -

- -

Tabs macro list

 - - - - - -
- -

Set up typesetting tabs

 - -

-Macro: TAB_SET <tab number> <indent> <length> L | R | C | J [ QUAD ] -
- -*<indent> and <length> require a unit of measure -

- -

-TAB_SET creates typesetting tabs that later can be -called with -TAB. -Typesetting tabs are numbered, and defined by an indent, a length, -and a "direction", hence TAB_SET has four -required arguments: - -

- -To set up a centred tab 6 picas long and 9 points from the left -margin, you'd enter - -
-    .TAB_SET 1 9p 6P C
-
-

- -

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

- -

-By default, tabs are in -nofill -mode, meaning you can enter text in tabs on a line-for-line basis -without having to use the -BR -macro. If you want a tab to be -filled, -pass the optional argument QUAD, which will make the tab -behave as if you'd entered .QUAD L | R | C. -

- -

-For -justified -tabs, simply pass the argument J (without the -QUAD argument), like this: - -

-    .TAB 1 9p 6P J
-
-

- -

-Once tabs are set, they can be called at any time with the -TAB <n> -macro, where <n> is the number of the desired tab. -

- -

-You can set up any number of typesetting tabs. However, be aware -that -string tabs -are also called with TAB <n>, -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. -

- -

-NOTE: If you use TAB_SET 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 -TQ) -before creating new tabs (unless, of course, you want to set -up a tab structure within the confines of an existing tab). -

- -

-IMPORTANT: Turn all indents off (see -Indents) -before setting up tabs with TAB_SET, or -mom may get confused. -

- - - -
- -

Mark positions of string tabs

 - -

-Inlines: \*[ST<number>]...\*[ST<number>X] -
- -*The Quad -direction must be LEFT or JUSTIFY (see -QUAD -and -JUSTIFY) -or the -no-fill mode -set to -LEFT -in order for these inlines to function properly. Please see -IMPORTANT, -below. -

- -

-String tabs need to be marked off with -inline escapes -before being set up with the -ST -macro. Any input line may contain string tab markers. -<number>, above, means the numeric identifier of the -tab. The following shows a sample input line with string tab -markers. - -

-    \*[ST1]Now is the time\*[ST1X] for all \*[ST2]good men\*ST2X] to come to the aid of the party.
-
-

- -

-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 -padding) -are taken into account when mom determines the -position and length of string tabs. -

- -

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

- -

-Once string tabs have been marked in input lines, they have to -be "set" with -ST, -after which they may be called, by number, with -TAB. -

- -

-NOTE: 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 -SILENT -macro. -

- -

-IMPORTANT: -Owing to the way groff processes -input lines -and turns them into -output lines, -it is not possible for mom to "guess" the -correct starting position of string tabs marked off in lines that -are centered or set flush right. -

- -

-Equally, she cannot guess the starting position if a line is fully -justified and broken with -SPREAD. -

- -

-In other words, in order to use string tabs, -LEFT -must be active, or, if -QUAD LEFT -or -JUSTIFY -are active, the line on which the string tabs are marked must be -broken "manually" with -BR -(but not -SPREAD). -

- -

-To circumvent this behaviour, I recommend using the -PAD -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, - -

-    .CENTER
-    \*[ST1]A line of text\*[ST1X]\c
-    .EL
-    .ST 1
-    .TAB 1
-    .PT_SIZE 24
-    .ALD 3p
-    \*[RULE]
-    .RLD 3p
-    .TQ
-
- -you should do: - -
-    .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
-
-

- - - -
- -

Set string tabs

 - -

-Macro: ST <tab number> L | R | C | J [ QUAD ] -

- -

-After string tabs have been marked off on an input line (see -\*[ST]...\*[STX]), -you need to "set" them by giving them a direction -and, optionally, the QUAD argument. In this -respect, ST is like -TAB_SET -except that you don't have to give ST an indent -or a line length (that's already taken care of, inline, by -\*[ST]...\*[STX]). If you want string tab 1 to be left, -enter - -

-    .ST 1 L
-
-

- -

-If you want it to be left and -filled, enter - -

-    .ST 1 L QUAD
-
-

- -

-If you want it to be justified, enter - -

-    .ST 1 J
-
-

- -

-See the -Quickie tutorial on string tabs -for a full explanation of setting up string tabs. -

- - - -
- -

Call tabs

 - -

-Macro: TAB <tab number> -
- -Alias: TB -

- -

-After tabs have been defined (either with -TAB_SET -or -ST), -TAB moves to whatever tab number you pass it as -an argument. For example, - -

-    .TAB 3
-
- -moves you to tab 3. -

- - - -

-NOTE: TAB breaks the line preceding -it and advances 1 linespace. Hence, - -

-    .TAB 1
-    A line of text in tab 1.
-    .TAB 2
-    A line of text in tab 2.
-
- -produces, on output - -
-    A line of text in tab 1.
-                               A line of text in tab 2.
-
-

- -

-If you want the tabs to line up, use -TN -(Tab Next), like this: - -

-    .TAB 1
-    A line of text in tab 1.
-    .TN
-    A line of text in tab 2.
-
- -which produces - -
-    A line of text in tab 1.   A line of text in tab 2.
-
-

- -

-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 -multi-column macros. -

- -

-ADDITIONAL NOTE: Any indents in effect prior to -calling a tab are automatically turned off by TAB. -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. -

- - - -
- -

Tab Next

 - -

-Macro: TN -
- -*In tabs that aren't given the QUAD argument -when they're set up with -TAB_SET -or -ST, -you must terminate the line preceding .TN -with the \c inline escape. See the -ADDITIONAL NOTE. -If you find remembering -whether to put in the \c bothersome, you may prefer to -use the -inline escape -alternative to -.TN, -\*[TB+], -which works consistently regardless of the fill mode. -

- -

-TN moves over to the next tab in numeric -sequence (tab n+1) without advancing on the page. See the -NOTE -in the description of the TAB macro for an -example of how TN works. -

- -

-NOTE: You must put text in the -input line -immediately after TN. "Stacking" of -TN's is not allowed. In other words, you cannot -do - -

-    .TAB 1
-    Some text
-    .TN
-    Some more text
-    .TN
-    .TN
-    Yet more text
-
-

- -

-The above example, assuming tabs numbered from 1 to 4, should be entered - -

-    .TAB 1
-    Some text
-    .TN
-    Some more text
-    .TAB 4
-    Yet more text
-
-

- -

-ADDITIONAL NOTE: -In versions of mom prior to 1.1.9, TN did not -always work as advertised on the last -output line -of pages that contained a footer trap (e.g. one set with -B_MARGIN -or in documents formatted using the -document processing macros). -

- -

-TN 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 QUAD argument (see -TAB_SET -and -ST) -you must always "join" .TN to the line -before it using the -\c -inline escape, -as in the following example: - -

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

- -

-When output, the example will look like this: - -

-    1.  The first rule of survival is "make and keep good friends."
-
-

- -

-Conversely, if you did give a QUAD argument -to TAB_SET or ST, the -\c must not be used. -

- - - -
- -

Tab Quit

 - -

-Macro: TQ -

- -

-TQ takes you out of whatever tab you were in, -advances 1 linespace, and restores the left margin, line length, -quad direction and -fill mode -that were in effect prior to invoking any tabs. -

- -
- - - -

Multi-Columns

 - -

-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 -baseline -of the first line in the previous tab. To demonstrate: - -

-    .TAB 1
-    Carrots
-    Potatoes
-    Broccoli
-    .TAB 2
-    $1.99/5 lbs
-    $0.25/lb
-    $0.99/bunch
-
- -produces, on output - -
-    Carrots
-    Potatoes
-    Broccoli
-               $1.99/5 lbs
-               $0.25/lb
-               $0.99/bunch
-
- -

-The multi-column macros allow you to set tabs in columnar -fashion, rather than line by line. When you invoke multi-column -mode (with -MCO), -mom saves the position of the current baseline. -MCR -(Multi-column return) at any point while multi-columns are on -returns you to the saved position. Exiting multi-columns -(MCX) -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.) -

- -

-Using our example above, but setting it in multi-column mode, - -

-    .MCO
-    .TAB 1
-    Carrots
-    Potatoes
-    Broccoli
-    .MCR
-    .TAB 2
-    $1.99/5 lbs
-    $0.25/lb
-    $0.99/bunch
-    .MCX
-
- -produces -

- -
-    Carrots   $1.99/5 lbs
-    Potatoes  $0.25/lb
-    Broccoli  $0.99/bunch
-
-

- -

-NOTE: Do not confuse MCO with -the -COLUMNS -macro in the -document processing macros. -

- -

Columns macro list

 - - - - - -
- -

Begin multi-column setting

 - -

-Macro: MCO -

- -

-MCO (Multi-Column -On) is the macro you use to begin multi-column -setting. It marks the current -baseline -as the top of your columns, for use later with -MCR. See the -introduction to columns -for an explanation of multi-columns and some sample -input. -

- -

-NOTE: Do not confuse MCO with -the -COLUMNS -macro in the -document processing macros. -

- - - -
- -

Return to top of column

 - -

-Macro: MCR -

- -

-Once you've turned multi-columns on (with -MCO), -MCR, at any time, returns you to the top of -your columns. -

- - - -
- -

Exit multi-columns

 - -

-Macro: MCX [ <distance to advance below longest column> ] -
- -*Optional argument requires a unit of measure -

- -

-MCX takes you out of any tab you were in (by -silently invoking -TQ) and advances to the bottom of the longest -column. -

- -

-Without an argument, MCX advances 1 linespace -below the longest column. Linespace, in this instance, is the -leading -in effect at the moment MCX is -invoked. -

- -

-If you pass the <distance> argument to -MCX, 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 MCX would -normally place you, you'd enter - -

-    .MCX 6p
-
-

- -

-NOTE: If you wish to advance a precise distance -below the -baseline -of the longest column, use MCX with an -argument of 0 (zero; no unit of measure required) in conjunction -with the -ALD -macro, like this: - -

-    .MCX 0
-    .ALD 24p
-
-

- -

-The above advances to precisely 24 points below the baseline -of the longest column. -

- -
- - - -

Indents

 - -

With mom's indents, you can indent from the -left, the right, or both margins. In addition, mom -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). -

- -

A brief explanation of how mom handles indents

 - -

-Mom provides five kinds of indents: left, right, -both, temporary, and hanging. Each is invoked by its own name: - -

-

- -

-In addition, there are four macros to control exiting from -indents: - -

-

- -

-This section deals exclusively with IL, IR and -IB. For an explanation of hanging and temporary -indents — how they work and how to use them — see -Hanging indents -and -Temporary indents. -

- -

-The first time you invoke any of mom's indents, -you must supply a measure. For example, - -

-    .IL 2P
-
- -indents text 2 picas from the left margin (or current tab -indent). -

- -

-When you want to exit the above indent, use either - -

-    .IQ
-     or
-    .ILX
-
-

- -

-The next time you want the same indent, invoke it without the -argument, like this: - -

-    .IL
-
-

- -

-As you can see, once you've supplied a measure to an indent macro -mom stores the value, obviating the need to repeat -it on subsequent invocations. And mom doesn't just -store the measure — she hangs on to it tenaciously. Arguments -passed to IL, IR and IB are -additive. Consider the following: - -

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

- -

-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 IQ, 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. -Mom adds the value of arguments to IL, -IR and IB to whatever value is already in -effect. -

- -

-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 -IR), you would enter .IR without an -argument. -

- -

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

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

- -

-Sometimes, you may want to clear out the stored indent values -— let mom start indenting with a clean slate, -as it were. Giving the optional argument CLEAR to any of -the "indent quit" macros resets them to zero. - -

-

- -

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

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

- -

-If, at .IRX, you wanted the text afterwards to have no -indents (either left or right), you would enter .IQ, -which exits all indent styles at once. -

- -

-A word of advice: 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. Mom'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. -

- -

-NOTE: see the section -Typesetting Macros in Document Processing -for information and advice on using indents with the -document processing macros. -

- -

Indents macro list

 - - - - - -
- -

Indent left

 - -

-Macro: IL [ <measure> ] - -
-*The optional argument requires a unit of measure -

- -

-IL indents text from the left margin of the -page, or if you're in a tab, from the left edge of the tab. Once -IL is on, the left indent is applied uniformly to -every subsequent line of text, even if you change the line length. -

- -

-The first time you invoke .IL, 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 -\w -inline escape -may be used to specify a text-dependent measure, in which case -no unit of measure is required. For example, - -

-    .IL \w'margarine'
-
- -indents text by the width of the word "margarine". -

- -

-With no argument, IL indents by its last -active value. See the -brief explanation of how mom handles indents -for more details. -

- -

-NOTE: Calling a tab (with -TAB) -automatically cancels any active indents. -

- -

-ADDITIONAL NOTE: Invoking IL -automatically turns off IB. -

- - - -
- -

Indent right

 - -

-Macro: IR [ <measure> ] -
- -*The optional argument requires a unit of measure -

- -

-IR indents text from the right margin of the -page, or if you're in a tab, from the end of the tab. -

- -

-The first time you invoke .IR, 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 -\w -inline escape -may be used to specify a text-dependent measure, in which case -no unit of measure is required. For example, - -

-    .IR \w'jello'
-
- -indents text by the width of the word "jello". -

- -

-With no argument, IR indents by its last -active value. See the -brief explanation of how mom handles indents -for more details. -

- -

-NOTE: Calling a tab (with -TAB) -automatically cancels any active indents. -

- -

-ADDITIONAL NOTE: Invoking IR -automatically turns off IB. -

- - - -
- -

Indent both

 - -

-Macro: IB [ <left measure> <right measure> ] -
- -*The optional arguments require a unit of measure -

- -

-IB allows you to set or invoke a left and a right -indent at the same time. -

- -

-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 IL and -IR, 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. -

- -

-A word of advice: If you need to manipulate -left and right indents separately, use a combination of -IL and IR instead of -IB. You'll save yourself a lot of grief. -

- -

-A minus sign may be prepended to the arguments to subtract from -their current values. The -\w -inline escape -may be used to specify text-dependent measures, in which case -no unit of measure is required. For example, - -

-    .IB \w'margarine' \w'jello'
-
- -left indents text by the width of the word "margarine" -and right indents by the width of "jello". -

- -

-Like IL and IR, IB -with no argument indents by its last active values. See the -brief explanation of how mom handles indents -for more details. -

- -

-NOTE: Calling a tab (with -TAB) -automatically cancels any active indents. -

- -

-ADDITIONAL NOTE: Invoking IB -automatically turns off IL and -IR. -

- - - -
- -

Temporary (left) indent

 - -

-Macro: TI [ <measure> ] -
- -*The optional argument requires a unit of measure -

- -

-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. (Mom's -PP -macro, for example, uses a temporary indent.) -

- -

-The first time you invoke .TI, you must give it -a measure. If you want to indent the first line of a -paragraph by, say, 2 -ems, -do - -

-    .TI 2m
-
-

- -

-Subsequent invocations of TI do not require you -to supply a measure; mom keeps track of the -last measure you gave it. -

- -

-Because temporary indents are temporary, there's no need to turn -them off. -

- -

-IMPORTANT: Unlike IL, IR and -IB, measures given to TI -are NOT additive. In the following example, the second .TI -2P is exactly 2 picas. - -

-    .TI 1P
-    The beginning of a paragraph...
-    .TI 2P
-    The beginning of another paragraph...
-
-

- - - -
- -

Hanging indent

 - -

-Macro: HI [ <measure> ] -
- -*The optional argument requires a unit of measure -

- -

-A hanging indent looks like this: - -

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

- -

-The first line of text "hangs" outside the left -margin. -

- -

-In order to use hanging indents, you must first have a left indent -active (set with either -IL -or -IB). -Mom will not hang text outside the left margin set with -L_MARGIN -or outside the left margin of a tab. -

- -

-The first time you invoke .HI, you must give it -a measure. If you want the first line of a paragraph to hang by, -say, 1 pica, do - -

-    .IL 1P
-    .HI 1P
-
-

- -

-Subsequent invocations of HI do not require you -to supply a measure; mom keeps track of the -last measure you gave it. -

- -

-Generally speaking, you should invoke HI -immediately prior to the line you want hung (i.e. without any -intervening -control lines). -And because hanging indents affect only one line, there's no need to -turn them off. -

- -

A recipe for numbered lists

 - -

-PLEASE NOTE: mom now has macros for setting lists (see -Nested lists), -making this recipe superfluous. It remains here in the hope that -it will clarify the use of hanging indents generally, if no longer -specifically. -

- -

-Consider the following example: - -

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

- -

-First, we invoke a left indent with a measure equal to the width -of 2 -figures spaces -plus a period (using the -\w -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. -

- -

-Notice that subsequent invocations of .HI without a -measure produce exactly the same effect. -

- -

-Paste the example above into a file and preview it with groff -- mom -X <filename> to see hanging indents in action. -

- -

-IMPORTANT: Unlike IL, IR and -IB, measures given to HI -are NOT additive. Each time you pass a measure to -HI, the measure is treated literally. -

- - - -
- -

Quitting indents

 - -

-Macro: IQ [ CLEAR ] (quit any/all indents — see IMPORTANT NOTE) -
- -Macro: ILX [ CLEAR ] (exit Indent Left) -
- -Macro: IRX [ CLEAR ] (exit Indent Right) -
- -Macro: IBX [ CLEAR ] (exit Indent Both) -

- -

-*IMPORTANT NOTE: Formerly, the macro for -quitting all indents was IX. This usage -is now deprecated, in favour of IQ. -IX will continue to behave as before, but -mom will issue a warning to stderr indicating -that you should update your documents. -

- -

-As a consequence of this change, ILX, IRX -and IBX may now also be -invoked as ILQ, IRQ and -IBQ. Both forms are acceptable. -

- -

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

- -

-If you pass these macros the optional argument CLEAR, -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. -

- -

-.IQ CLEAR, as you'd suspect, quits and clears the values -for all indent styles at once. -

- -
- -

-Next   -Prev   -Top   -Back to Table of Contents -

- - - - - diff --git a/contrib/mom/momdoc/using.html b/contrib/mom/momdoc/using.html deleted file mode 100644 index 287b0ee9..00000000 --- a/contrib/mom/momdoc/using.html +++ /dev/null @@ -1,298 +0,0 @@ - - - - - - -Using mom - - - - - - - -

-Next   -Prev   -Back to Table of Contents -

- -

Using mom

 - -

-Introduction -
-Inputting macros -
-Invoking groff -
-Previewing documents -

- -
- -

Introduction

- -

-As explained in the section -What is mom?, -mom 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. .PP for paragraphs, -.HEAD for heads, .FOOTNOTE for footnotes, -etc.) that make a lot of typesetting decisions automatically. -

- -

-You tell mom that you want to use the document -processing macros with the -START -macro, explained below. After START, -mom determines the appearance of text following -the markup tags automatically, although you, the user, can easily -change how mom 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. -

- -

How to input mom's macros

 - -

-Regardless of which way you use mom, the -following apply. -

- -
    -
  1. - You need a good text editor for inputting - mom files. - -

    - I cannot recommend highly enough that you use an - editor that lets you write syntax highlighting - rules for mom's macros and - inline escapes. - 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. -

    - -
    2. - -
  2. - All mom's macros begin with a period - (dot) and must be entered in upper case (capital) - letters. -
    3. - -
  3. - Macro - arguments - 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. -
    4. - -
  4. - Any argument (except a - string argument) - that is not a digit must be entered in upper case - (capital) letters. -
    5. - -
  5. - 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. +2, -4). -
    6. - -
  6. - Any argument that requires a - unit of measure - must have the unit appended directly to the argument, with - no intervening space (e.g. 4P, .5i, 2v). -
    7. - -
  7. - String arguments, - 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). -
    8. - -
  8. - 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 (\) at the ends of lines to break - them up, like this: - - 
    -    .SUBTITLE "An In-Depth Consideration of the \
-    Implications of Forty-Two as the Meaning of Life, \
-    The Universe, and Everything"
-
    -
    9. -
- -

-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 \# on a line by itself. -Consider the following, which is a template for starting the chapter -of a book. - -

-    .TITLE   "My Pulitzer Novel"
-    .AUTHOR  "Joe Blow"
-    .CHAPTER  1
-    \#
-    .DOCTYPE    CHAPTER
-    .PRINTSTYLE TYPESET
-    \#
-    .FAM     P
-    .PT_SIZE 10
-    .LS      12
-    \#
-    .START
-
-

- -

Printing — invoking groff with mom

 - -

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

-    groff -mom -l <filename>
-    groff -mom <filename> | lpr
-
-

- -

-In the first, the -l 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 lpr as your print command, in which case, you -can replace lpr with whatever is appropriate to your box. -

- -

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

- -

-NOTE FOR ADVANCED USERS: I've sporadically -had groff choke on perfectly innocent sourced files within -mom 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 -.so the right path and name. Should this happen, pass -groff the -U (unsafe mode) option along with the other -options you require. Theoretically, you only need -U -with .open, .opena, .pso, .sy, and .pi, -however reality seems, at times, to dictate otherwise. -

- -

How to preview documents

 - -

-Other than printing out hard copy, there are two well-established -methods for previewing your work. Both assume you have a working -X server. -

- -

-Groff itself comes with a quick and dirty previewer called -gxditview. Invoke it with - -

-    groff -X -mom filename
-
- -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 -mom's macro effects -(smartquotes -and -leaders -come to mind). What it does have going for it is that it's fast and -doesn't gobble up system resources. -

- -

-A surer way to preview documents is with gv -(ghostview). This involves processing documents with groff, -and directing the output to a PostScript file, like this, - -

-    groff -mom filename > filename.ps
-
- -then opening the .ps file in gv. -

- -

-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 gv 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 (groff -mom filename > filename.ps), then open -the file inside gv. 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 gv registers that -the file has changed, and automatically loads the new version. -Voilà! — instant previewing. -

- -
- -

-Next   -Prev   -Top   -Back to Table of Contents -

- - - - -- cgit v1.2.1