--- contrib/mom/momdoc/appendices.html | 901 ++++ contrib/mom/momdoc/color.html | 505 +++ contrib/mom/momdoc/cover.html | 851 ++++ contrib/mom/momdoc/definitions.html | 995 +++++ contrib/mom/momdoc/docelement.html | 6639 ++++++++++++++++++++++++++++ contrib/mom/momdoc/docprocessing.html | 4420 ++++++++++++++++++ contrib/mom/momdoc/goodies.html | 1785 ++++++++ contrib/mom/momdoc/graphical.html | 689 +++ contrib/mom/momdoc/headfootpage.html | 2341 ++++++++++ contrib/mom/momdoc/images.html | 3515 +++++++++++++++ contrib/mom/momdoc/inlines.html | 1112 +++++ contrib/mom/momdoc/intro.html | 487 ++ contrib/mom/momdoc/letters.html | 577 +++ contrib/mom/momdoc/macrolist.html | 1529 +++++++ contrib/mom/momdoc/rectoverso.html | 350 ++ contrib/mom/momdoc/refer.html | 2129 +++++++++ contrib/mom/momdoc/reserved.html | 2736 ++++++++++++ contrib/mom/momdoc/stylesheet.css | 691 +++ contrib/mom/momdoc/tables-of-contents.html | 1224 +++++ contrib/mom/momdoc/toc.html | 476 ++ contrib/mom/momdoc/typesetting.html | 4988 +++++++++++++++++++++ contrib/mom/momdoc/using.html | 319 ++ contrib/mom/momdoc/version-2.html | 424 ++ 23 files changed, 39683 insertions(+) create mode 100644 contrib/mom/momdoc/appendices.html create mode 100644 contrib/mom/momdoc/color.html create mode 100644 contrib/mom/momdoc/cover.html create mode 100644 contrib/mom/momdoc/definitions.html create mode 100644 contrib/mom/momdoc/docelement.html create mode 100644 contrib/mom/momdoc/docprocessing.html create mode 100644 contrib/mom/momdoc/goodies.html create mode 100644 contrib/mom/momdoc/graphical.html create mode 100644 contrib/mom/momdoc/headfootpage.html create mode 100644 contrib/mom/momdoc/images.html create mode 100644 contrib/mom/momdoc/inlines.html create mode 100644 contrib/mom/momdoc/intro.html create mode 100644 contrib/mom/momdoc/letters.html create mode 100644 contrib/mom/momdoc/macrolist.html create mode 100644 contrib/mom/momdoc/rectoverso.html create mode 100644 contrib/mom/momdoc/refer.html create mode 100644 contrib/mom/momdoc/reserved.html create mode 100644 contrib/mom/momdoc/stylesheet.css create mode 100644 contrib/mom/momdoc/tables-of-contents.html create mode 100644 contrib/mom/momdoc/toc.html create mode 100644 contrib/mom/momdoc/typesetting.html create mode 100644 contrib/mom/momdoc/using.html create mode 100644 contrib/mom/momdoc/version-2.html (limited to 'contrib/mom/momdoc') diff --git a/contrib/mom/momdoc/appendices.html b/contrib/mom/momdoc/appendices.html new file mode 100644 index 0000000..964a2ab --- /dev/null +++ b/contrib/mom/momdoc/appendices.html @@ -0,0 +1,901 @@ + + + + + + + + + Mom -- Appendices + + + + + + + +

+ + + + + + +

+ +

Appendices

+ +

Adding fonts to groff +
Some reflections on mom
Contact the author

+ +

Adding fonts to groff

+ +

+<prefix>, in this section, refers +to the directory in which groff is installed, typically +
+ + /usr/share/groff/ + +(for distro-specific, pre-compiled groff packages) or +
+ + /usr/local/share/groff/ + +(if you’ve built groff from source). +

+ +

+<version> refers to the groff version number, which +can be found, if necessary, by typing +
+ + groff -v + +at the command line. +

+ +

+Groff comes with a small library of +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 work with mom a lot, sooner or later you’ll find 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. +

+ +

Extending groff families / adding new families and fonts

+ +

The traditional approach

+ +

+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, +or 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, which is +found in +
+ + <prefix>/<version>/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 family name. For example, when +a typesetter says “the Helvetica family”, s/he is +including the weights Helvetica Thin, Helvetica 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 +.FAMILY H 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, Helvetica Light Roman and Helvetica Light Italic +as well as Helvetica Light Condensed Roman and Helvetica Light +Condensed Italic, the established groff approach would require two +“partial” families, HL (for Helvetica Light) +and HLCD (for Helvetica Light Condensed), with R and +I fonts for both: +
+ + HLR + HLI + HLCDR + HLCDI + +Accessing these family/font combos routinely +throughout a document would then require changing the family +(with .FAMILY) and selecting the desired font +(with .FT R or .FT I), or +passing .FT the lengthy family+fontname (.e.g. +.FT HLCDI). +

+ +

The simpler way with mom

+ +

+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 font styles, the following: +

+ +

+ +UL = Ultra Light +ULI = Ultra Light Italic +ULCD = Ultra Light Condensed +ULCDI = Ultra Light Condensed Italic +ULEX = Ultra Light Extended +ULEXI = Ultra Light Extended Italic + +XL = Extra Light +XLI = Extra Light Italic +XLCD = Extra Light Condensed +XLCDI = Extra Light Condensed Italic +XLEX = Extra Light Extended +XLEXI = Extra Light Extended Italic + +TH = Thin +THI = Thin Italic +THCD = Thin Condensed +THCDI = Thin Condensed Italic +THEX = Thin Extended +THEXI = Thin Extended Italic + +L = Light Roman +LI = Light Italic +LCD = Light Condensed +LCDI = Light Condensed Italic +LEX = Light Extended +LEXI = Light Extended Italic + +BK = Book Roman +BKI = Book Italic +BKCD = Book Condensed +BKCDI = Book Condensed Italic +BKEX = Book Extended +BKEXI = Book Extended Italic + +CD = Medium Condensed +CDI = Medium Condensed Italic +EX = Medium Extended +EXI = Medium Extended Italic + +DB = DemiBold Roman +DBI = DemiBold Italic +DBCD = DemiBold Condensed +DBCDI = DemiBold Condensed Italic +DBEX = DemiBold Extended +DBEXI = DemiBold Extended Italic + +SB = SemiBold Roman +SBI = SemiBold Italic +SBCD = SemiBold Condensed +SBCDI = SemiBold Condensed Italic +SBEX = SemiBold Extended +SBEXI = SemiBold Extended Italic + +

+ +BCD = Bold Condensed +BCDI = Bold Condensed Italic +BEX = Bold Extended +BEXI = Bold Extended Italic +BO = Bold Outline + +XB = Extra Bold +XBI = Extra Bold Italic +XBCD = Extra Bold Condensed +XBCDI = Extra Bold Condensed Italic +XBEX = Extra Bold Extended +XBEXI = Extra Bold Extended Italic + +UB = Ultra Bold +UBI = Ultra Bold Italic +UBCD = Ultra Bold Condensed +UBCDI = Ultra Bold Condensed Italic +UBEX = Ultra Bold Extended +UBEXI = Ultra Bold Extended Italic + +HV = Heavy +HVI = Heavy Italic +HVCD = Heavy Condensed +HVCDI = Heavy Condensed Italic +HVEX = Heavy Extended +HVEXI = Heavy Extended Italic + +BL = Black +BLI = Black Italic +BLCD = Black Condensed +BLCDI = Black Condensed Italic +BLEX = Black Extended +BLEXI = Black Extended Italic +BLO = Black Outline + +XBL = Extra Black +XBLI = Extra Black Italic +XBLCD = Extra Black +XBLCDI = Extra Black +XBLEX = Extra Black Italic +XBLEXI = Extra Black Italic + +UBL = Ultra Black +UBLI = Ultra Black Italic +UBLCD = Ultra Black Condensed +UBLCDI = Ultra Black Condensed Italic +UBLEX = Ultra Black Extended +UBLEXI = Ultra Black Extended Italic + +SC = Small Caps Roman +SCI = Small Caps Italic +SCDB = Small Caps Demibold +SCDBI = Small Caps Demibold Italic +SCSB = Small Caps Semibold +SCSBI = Small Caps Semibold Italic + +

+ +

+Thus, with mom, if you’ve installed some extra +Helvetica fonts and named them according to the convention +<F><S> (where <F> means +family and <S> means font style), once having +entered +
+ + .FAMILY H + +you can access any of the extra Helvetica fonts simply by passing +the correct argument to +FT +from the list, above. 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. The 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”. +

+ +

+You may, at needs, want to add to mom’s list of font styles. +You can do this by editing the file, om.tmac (typical location: +<prefix>/<version>/tmac/om.tmac). Near the +top, you’ll see lines of the form +
+ + .sty \n[.fp] XL \" Extra Light + .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, above, +and plugging in your new font style (having, of course, +added the font to groff, correctly named); see +Step-by-step instructions). +

+ +

+For example, if you already have some fonts from the Univers family +installed and have called the family Univers, you might decide at +some point to add the Bold Outline font (UniversBO). In which +case, you’d add +
+ + .sty \n[.fp] BO \" Bold Outline + +to the .sty \n[.fp] <font style> list +in om.tmac. +

+ +

+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 +families and fonts 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. +

+ +

+Important: +Be careful 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, CI). Were you to create a font +style “C”, thinking that .FT C +would give you access to font style once you’d given a +.FAMILY directive, you’d get a nasty surprise: +your type would come out in Courier Roman! +

+ +

Step-by-step instructions

+ +

What you need before you start
Initial preparation
1. Acquire the font
2. Prepare to convert the font to the correct format +
- TTF fonts
- Type 1 fonts
3. Convert the font and put it in the right place
4. Update the download file +
Naming groff fonts
Automate the whole process – the install-font script +

+ + +

+There are a number of ways to approach making fonts available +to groff. These instructions aren’t meant to cover all +possibilities, merely one. +

+ +

+GNU/Linux distributions being what they are, directory locations +may differ and the presence of some executable can’t be +guaranteed. I run a Debian-based system. The instructions reflect +that. Users of other distros may have to interpret them according +to the way their distro operates. +

+ +

What you need before you start

+ +

groff, version 1.18 or higher
+ (Debian package: groff) +
ghostscript
+ (Debian package: ghostscript or ghostscript-x) +
fontforge
+ (Debian package: fontforge) +

+ +

Initial preparation (you only need do this once)

+ +

+ 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. Eg, if you find + site-tmac in /usr/share/groff/, create site-font in + /usr/share/groff/ +
+ + sudo mkdir site-font + +
+ Create two files, generate-t42.pe and generate-pfa.pe, + as you see them below. Place them in a convenient and + easily-remembered location, like your home directory. +
+ generate-t42.pe + +
+ +# generate-t42.pe + +Open($1); +Generate($fontname + ".pfa"); +Generate($fontname + ".t42"); + +
+
+ generate-pfa.pe +
+ +# generate-pfa.pe + +Open($1); +Generate($fontname + ".pfa"); + +
+

+ +

Step 1: Acquire the font

+ +

+The two most commonly available types of fonts are PostScript Type1 +(extension .pfb) and TrueType (extension .ttf). Either can be made +available to groff. There are many websites holding collections of +both. +

+ +

Step 2: Prepare to convert the font to the correct format

+ +

+Change into the directory holding the new font. +

+ +

+For convenience in the next step, make a symbolic link to +the file 'textmap': +
+ + ln -s <prefix>/<version>/font/devps/generate/textmap . + +See +here +for an explanation of <prefix> +and <version>. +

+ +

+In addition, unless you’re installing fonts from your home +directory, make links to the files 'generate-t42.pe' and +'generate-pfa.pe'. +
+ + ln -s $HOME/generate-t42.pe . + ln -s $HOME/generate-pfa.pe . + +

+ +

Step 3: Convert the font and put it in the right place

+ +

+TrueType fonts (.ttf) need to be converted to .t42. Type 1 fonts +(.pfa, .pfb) need to be converted to .pfa. +

+ +

• Converting TTF Fonts

+ +

+For .ttf fonts, run +
+ + fontforge -script generate-t42.pe <file>.ttf + +This will create three new files with the extensions .t42, .pfa, and +.afm. Next, run +
+ + afmtodit <afm file> textmap <groff font> + +This will create a groff font with the name you give. (See +here +for advice on naming groff fonts.) +

+ +

+Move the .t42 and groff font files to +<prefix>/site-font/devps/. +

+ +

+If you’re running a recent version of groff that includes +the native pdf device (gropdf), move the .pfa file to <prefix>/site-font/devpdf/. If not, you +may safely remove it. You may also safely remove the .afm file. +

+ +

• Converting Type1 Fonts

+ +

+For .pfb fonts, run +
+ + fontforge -script generate-pfa.pe <file>.pfb + +This will create two new files with the extensions .pfa, and .afm. +Next, run +
+ + afmtodit <afm file> textmap <groff font> + +Move the .pfa and groff font files to +<prefix>/<site-font>/devps/. +(See +here +for advice on naming groff fonts.) +

+ +

+If you’re running a recent version of groff that includes the +native pdf device (gropdf), link the .pfa and groff font files, now +in <prefix>/<site-font>/devps/, +to the <prefix>/site-font/devpdf +directory. +

+ +

+Start by changing into the +<prefix>/site-font/devpdf/ +directory, then: +
+ + ln -s <prefix>/<site-font>/devps/<file>.pfa . + ln -s <prefix>/<site-font>/devps/<groff font> . + +You may safely remove the .afm file. +

+ +

Step 4: Update the download file

+ +

• Get the internal font name

+ +

+Inspect your new groff font file. Near the top, you will see a line +of the form +
+ + internalname <name> + +Usually, the internal name is helpfully descriptive, e.g. +
+ + internalname Optima-Bold + +Make a note of the internal name. +

+ +

• Add the font to the download file

+ +

+If a file called ‘download’ is not already present in +<prefix>/site-font/devps/, +copy over the one found in +<prefix>/<version>/font/devps/. +

+ +

+The download file maps the internal names used by groff to the +actual fonts. To add your new font to the download file, append a +line containing the internal name, followed by a tab (make sure your +text editor is inserting the tab character, not spaces), followed by +the .t42 or .pfa font to which the internal name refers. +

+ +

+For example, if the internal name is Optima-Bold and the font is a +.pfa file called Optima-Bold.pfa, your updated download file will +contain +
+ + Optima-Bold<tab>Optima-Bold.pfa + +

+ +

• Updating the gropdf download file

+ +

+If you’re running a recent version of groff that includes +the native pdf device (gropdf), you must update the +<prefix>/site-font/devpdf/download +file as well. If it does not exist, create it. +

+ +

+Note: +Start with a blank ‘download’ file. Do not copy +over the ‘download’ file from +<prefix>/<version>/font/devpdf/. +

+ +

+The instructions for registering fonts in the +<prefix>/site-font/devpdf/ download +file are identical to those for PostScript fonts (see above), but +with one important difference: the lines must all begin with a tab +character. Thus, using our Optima example, your +<prefix>/site-font/devpdf/download +file download line for the same font is +
+ + <tab>Optima-Bold<tab>Optima-Bold.pfa + +

+ +

Naming groff fonts

+ +

+For convenience when using mom, and to keep your font collection +organized, choose meaningful groff font names following the scheme +<Family><FONT>, where Family is something +like Optima or Univers or Clarendon, and FONT is either +
+ +R  (roman/regular) +
+I  (italic) +
+B  (bold) +
+BI (bold italic) + +or one of the 1–5 character fontstyles listed +here. +Thus, for the fonts Optima Light Italic and Optima Extra Black, your font names would be +
+ + OptimaLI + OptimaXBL + +This scheme allows you to enter .FAMILY Optima to make +Optima the current family, and .FT LI or .FT XBL +when you need the fonts Light Italic or Extra Black. +

+ +

+Groff font names are, in fact, arbitrary; you can call your fonts +anything you like, provided the +internal name +in the +download file +matches the internal name found in the groff font file. When +calling a font that does not follow the recommended naming convention, +you must pass the full font name to .FT whenever you wish +to use it. +

+ +

+For example, the font, Goudy Stout, isn’t really part of the +Goudy family, and while "stout" describes it, Stout is not a +recognized font style. Therefore, its groff name could simply be +GoudyStout, and whenever you needed it, you could call it with +.FT GoudyStout. +

+ +

Automate the whole process – the install-font script

+ +

+A bash script to make the entire process of installing fonts a +painless no-brainer has been posted online at +https://www.schaffter.ca/mom/bin/install-font.sh. +Be sure to make the script executable +(chmod 755 install-font) +after you download it, then type ./install-font.sh -H for +usage. +

+ +

+ + + +

Some reflections on mom

+ +

+If, as Eric Raymond asserts, open source begins with a programmer +scratching a personal itch, then mom can truly be called open +source. +

+ +

+Mom had her origins in a library of groff routines I wrote over +the years to handle various aspects of typesetting and document +processing that weren’t adequately covered by ms, me, mm, and +friends. Typically, I’d use the library to cobble together +macro sets for new challenges as they came my way. +

+ +

+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 rather than the offering from Redmond +is that it has helped enormously to get the most out of my poor +little boxes. +

+ +

+In Linux-land (all Unix variants, in fact), 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. Back in the +Jurassic Period, I ran 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 +—seem to have remained stuck in a time warp. The canonical macro packages +still look as they did back in those decades when memory was exorbitantly +expensive and every byte mattered. +

+ +

+For some time now, groff users and macro writers have had the option +to use “long” names for macros (i.e. longer than two +letters, the original limit), 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. The function of nearly every macro, number register and +string can be inferred simply from its name. The file is heavily +commented. A consistent, if idiosyncratic, indenting style is used +as well, significantly improving readability. Anyone wanting to +futz around with mom’s macros should be able to do so with a +minimum of head scratching. +

+ +

+ + + +

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 (subscription information available +here) +or contact me, Peter Schaffter, directly at the following +address: +
+ + peter@schaffter.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 website, you’ll find a link +to it at +
+ + https://www.schaffter.ca + +The site contains links to some of my fiction, all of which was +typeset with mom and groff. +

+ +

+ + + + + + + +

Back to Table of Contents

Top

+ +

+ + + diff --git a/contrib/mom/momdoc/color.html b/contrib/mom/momdoc/color.html new file mode 100644 index 0000000..f53b5c0 --- /dev/null +++ b/contrib/mom/momdoc/color.html @@ -0,0 +1,505 @@ + + + + + + + + + Mom -- Colour + + + + + + + +

+ + + + + + + +

Back to Table of Contents

Next: Graphical objects

+ +

Coloured text

+ +

+List of color macros +

+ +

Introduction

+ +

+Mom’s support for coloured text is straightforward. You begin +by telling mom about the colours you want with +NEWCOLOR +or +XCOLOR. +Afterwards, 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 +colourise 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 initialize the colour, black. Mom predefines it for you. +

+ +

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

+ +

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

+ +

+Experts: +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. +

+ +

Coloured text macros

+ +

NEWCOLOR
XCOLOR
COLOR
\*[<colourname>] (inline escape)

+ +

+ + + +

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 +\*[<colour 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 +
+ + RGB (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 CMY #0000FF \"or ##0000FFFF0000 or "0 0 1" + .NEWCOLOR YELLOW CMYK #0000FF00 \"or ##00000000FFFF0000 or "0 0 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, +\*[<colourname>], +or the macro +COLOR. +(See the +example, +above.) +

+ +

+Note: +The colourname you give to NEWCOLOR may be used with groff’s +\m[<colourname>] inline escape (the \m +escape is used to set text and rule colours). Thus, assuming +a colourname “blueblack” set with NEWCOLOR, +\*[blueblack] and \m[blueblack] +are equivalent. Furthermore, the colourname can be given as an +argument to groff’s +primitive +request, .gcolor (which does the same thing as +\m[<colourname>]). +

+ +

+Equally, the colourname may be used with +\M[<colourname>] 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 colour +intimidates you, is to stick to using mom’s default RGB colour +scheme, and to fire up a colour 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 colour as an argument. +

+ + + +

Initializing a colour with XCOLOR

+ +

+Macro: XCOLOR <X colourname> [<alias>] +

+ +

+<X colourname> must be all one word, all lower case. +
+(See +Finding X colour 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 initialize the X colour, coral, all you +have to do is enter +
+ + .XCOLOR coral + +Afterwards +
+ + .COLOR coral + + +will colourise subsequent text coral until you instruct mom to +return to black, or some other pre-defined, initialized colour. +(The +inline escape +\*[coral] will equally colourise 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 colours, 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 +colours. +

+ +

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

+ +

Finding X colour 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 colour names, remember that the +names, passed as arguments to XCOLOR, must be all one word, all in +lower case. +

+ +

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

+ +

+The colourname 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 colourname; the alias won’t work. +

+ + + +

Invoking a colour

+ +

+Macro: COLOR <colourname> +

+ +

+Inline: \*[<colourname>] +

+ +

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

+ +

+Note: +You can use the \*[<colourname>] +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 +colourised. +

+ +

+Furthermore, if you use +\*[<colourname>] in the string +argument passed to +HEADING <n> +and you’ve requested that the heading level be numbered, the +numbers themselves will not be colourised, only the text you pass to +the macro. If you wish the numbers to be colourised along with the +text, you must explicitly tell mom with +HEADING_STYLE <n>. +

+ +

+For colourising underscored text, see +Colourising underscored text +in the notes at the end of +UNDERSCORE. +

+ +

+ + + + + + + + +

Back to Table of Contents

Top

Next: Graphical objects

+ +

+ + + diff --git a/contrib/mom/momdoc/cover.html b/contrib/mom/momdoc/cover.html new file mode 100644 index 0000000..7efee1f --- /dev/null +++ b/contrib/mom/momdoc/cover.html @@ -0,0 +1,851 @@ + + + + + + + + + Mom -- Document processing, creating cover pages + + + + + + + +

+ + + + + + + +

Back to Table of Contents

Next: Tables of contents

+ +

Creating cover pages

+ +

Introduction to cover pages +
Doc-cover and cover macros +
Enabling/disabling automatic generation of cover pages
Control macros for covers and doc covers

+ +

Introduction to cover pages

+ +

+Though identical in treatment, mom provides two kinds of cover +pages: document cover pages (”doc covers”) and section +cover pages (“covers”). Section cover pages are +analogous to title pages. +

+ +

+A 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 cover is what you’d use for pages that separate sections +of a collated document, i.e. title pages. A cover page (but not a +doc cover) in a collated document could, for example, simply read: +”PART 1”. +

+ +

+In non-collated documents (say, an essay) you can use either a cover +or doc cover to generate the cover sheet. +

+ +

+In addition, nothing prevents you from generating both a doc cover +and a cover for every document in a collated document. Or you can +selectively disable the automatic generation of either doc covers or +covers in a collated document on-the-fly. +

+ +

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

+ +

Description of cover pages

+ +

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

the position on the page where the information is output
the (optional) addition of copyright and miscellaneous information
there’s no running text underneath, although you can add text + to a cover or doc cover (for example, an Abstract) with + COVERTEXT +

+ +

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

+ +

+By default, mom starts covers and doc covers one-third of the way +down the page. This can be changed through the use of the control +macros DOC_COVER_START_POS / COVER_START_POS (or DOC_COVER_ADVANCE / +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. The +position, as well as all of the standard typesetting parameters, can be +altered via control macros. +

+ +

+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. As with the copyright, the +position and type specs can be altered via control macros. +

+ +

Headers/footers/pagination

+ +

+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, covers and doc covers 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 by invoking +
+ + .DOC_COVER_COUNTS_PAGES + +or +
+ + .COVER_COUNTS_PAGES + +

+ +

Designing your own cover pages

+ +

+Finally, if you want to design your own cover page(s), you can +typeset them by hand inside a +COVERTEXT +block using mom’s typesetting macros to format the text. +

+ +

Persistence of data and formatting

+ +

+Doc-cover and cover data—that is to say, the strings passed to +reference macros that appear on doc cover and cover +pages—does not persist after +START, +however the formatting of the various parts (TITLE, AUTHOR, +COPYRIGHT, etc.) does. +

+ +

Cover and document cover macros

DOC_COVER and COVER +
- The arguments: saying what goes on doc cover and cover pages
DOC_COVERTEXT / COVERTEXT
DOC_COVER_IMAGE / COVER_IMAGE
Enabling/disabling automatic generation of cover pages +
- DOC_COVERS
- COVERS
Control macros for doc covers and covers

+ + + +

DOC_COVER and COVER

+ +

+Macro: DOC_COVER (see argument list, below) +

+ +

+Macro: COVER (see argument list, below) +

+ +

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

+ +

+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 (title page, cover sheet) containing +just the name of the section, for example, “Part 1”. +

+ +

+The arguments to DOC_COVER and COVER tell mom +what you’d like on cover pages. You may give as many or as +few arguments as you need, in any order. A very common setup would +be: +
+ + .COVER TITLE AUTHOR COPYRIGHT + +

+ +

The argument list

+ +

+ +

What the arguments mean

+ +

TITLE: – the string(s) you gave to + TITLE +
DOCTITLE: – the string(s) you gave to + DOCTITLE +
DOC_COVERTITLE / COVERTITLE: – the string(s) you gave to + DOC_COVERTITLE + or + COVERTITLE +
CHAPTER, CHAPTER_TITLE, CHAPTER+TITLE: – see below, + How the CHAPTER argument and friends work +
SUBTITLE: – the string(s) you gave to + SUBTITLE +
AUTHOR: – the string(s) you gave to + AUTHOR +
DOCTYPE: – the string you gave to + DOCTYPE NAMED +
DOC_COVERTEXT / COVERTEXT: – the block of type you entered for + DOC_COVERTEXT + or + COVERTEXT +
DOC_COVER_IMAGE / COVER_IMAGE: – the image file you gave to + DOC_COVER_IMAGE + or + COVER_IMAGE +
COPYRIGHT: – the string you gave to + COPYRIGHT +
MISC: – the string(s) you gave to + MISC +
PDF_OUTLINE_LABEL <label>: + + By default, mom identifies doc covers in the outline panel of PDF + viewers with the prepended label, “Cover:”, and covers + with the label “Title Page:”. If you would like + to change the label, give the PDF_OUTLINE_LABEL + argument to DOC_COVER or COVER along with the new label, in + quotation marks, as in this example: +
+ .COVER TITLE AUTHOR COPYRIGHT PDF_LABEL "Cover Sheet: " + +
BLANKPAGE: + + 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, there may be instances where you do + not want text on the reverse side of cover or title pages + + + If you enable + DOC_COVERS_COUNT_PAGES + and/or + COVERS_COUNT_PAGES, + the blank page will be taken into account in the pagination + scheme, though no page number appears on it. Otherwise, blank + pages are invisible to mom’s pagination. + +

+ +

+Please note that in all cases, if you have passed +a reference macro one of the optional arguments +DOC_COVER or COVER (e.g. +.TITLE DOC_COVER "Title"), mom will print the +appropriate string on the appropriate cover page. Thus, +
+ + .TITLE DOC_COVER "Collected Essays" + .TITLE COVER "1985-2015" + .TITLE "Neo-liberalism: Who Did They Think They Were Fooling?" + .DOC_COVER TITLE + .COVER TITLE + +will print “Collected Essays” on the doc cover page, +“1985-2015” on the cover page, and, assuming the +docheader hasn’t been disabled, “Neo-liberalism: Who +Did They Think They Were Fooling?” as the title in the +docheader. +

+ +

+Note that +
+ + .DOC_COVERTITLE "Collected Essays" + .COVERTITLE "1985-2015" + .TITLE "Neo-liberalism: Who Did They Think They Were Fooling?" + .DOC_COVER DOC_COVERTITLE + .COVER COVERTITLE + +could be used to accomplish the same thing. +

+ +

How the CHAPTER argument and friends work

+ +

+• CHAPTER +
+The CHAPTER argument will print the +CHAPTER_STRING +concatenated with the chapter number you gave to +CHAPTER. +For example, assuming a vanilla setup for your chapter: +
+ + .CHAPTER 1 + .CHAPTER_TITLE "The Bonny Blue Yonder" + .COVER CHAPTER \" (or .DOC_COVER CHAPTER) + +will print (and only print) +
+ + Chapter 1 + +

+ +

+• CHAPTER_TITLE +
+The CHAPTER_TITLE argument will print the chapter title +you gave to +CHAPTER_TITLE. +For example, assuming a vanilla setup for your chapter: +
+ + .CHAPTER 1 + .CHAPTER_TITLE "The Bonny Blue Yonder" + .COVER CHAPTER_TITLE \"(or .DOC_COVER CHAPTER_TITLE) + +will print (and only print) +
+ + The Bonny Blue Yonder + +

+ +

+• CHAPTER+TITLE +
+The CHAPTER+TITLE argument will print both the +concatenated chapter string+number and the chapter title. For +example, assuming a vanilla setup for your chapter: +
+ + .CHAPTER 1 + .CHAPTER_TITLE "The Bonny Blue Yonder" + .COVER CHAPTER+TITLE \"(or .DOC_COVER CHAPTER+TITLE) + +will print +
+ + Chapter 1 + The Bonny Blue Yonder + +

+ +

DOC_COVERTEXT and COVERTEXT

+ +

+Macro: DOC_COVERTEXT [START <starting position>] <toggle> +

+Macro: COVERTEXT [START <starting position>] <toggle> +

+ +

+• Must come after +PRINTSTYLE +

+ +

+DOC_COVERTEXT and COVERTEXT allow you to add +text to doc covers and covers in addition to, or instead of, what is +generated by mom from the arguments you give to +DOC_COVER +and +COVER. +

+ +

+Invoke .DOC_COVERTEXT or .COVERTEXT on a line +by itself, follow it with the text and formatting you desire, and +terminate the text block with .DOC_COVERTEXT OFF or +COVERTEXT OFF (or QUIT, END, DONE, etc.). +

+ +

+By default, cover text is set over the full line length of the +document, using the style parameters of +running text. +Therefore, as noted, these macros must come after PRINTSTYLE +and any global style changes (margins, family, size, leading, +etc.). Formatting within a cover text block must be done +“manually” with mom’s typesetting macros; +PP +is the only allowed document element tag. +

+ +

Placement

+ +

+If you do not instruct mom to put anything on doc cover or cover +pages except DOC_COVERTEXT or COVERTEXT, the +cover text will begin at the document’s top margin. +Equally, if only COPYRIGHT and/or MISC are +to go on the pages, cover text begins at the top margin. In all +other cases, cover text begins below the last element on the page +(excluding COPYRIGHT or MISC), separated by a blank line. +

+ +

+If you wish to change the starting position of the text, you must +use +SP +or +ALD +to move it further down the page. Alternatively, you may use the +optional START argument to give a precise location for the text to +begin. +

+ +

+DOC_COVERTEXT and COVERTEXT are particularly +useful for putting abstracts on cover pages, as technical reports +often require. +

+ +

+Here’s a simple recipe for setting an abstract: +
+ + .COVERTEXT + .FT BI + .PT_SIZE 14 + .LS 14 + .CENTER + Abstract + .SP .5v + .FT R + .PT_SIZE 12 + .IB 6P + .JUSTIFY + Text of Abstract... + .COVERTEXT OFF + +Assuming you have told mom to put the title and author on the +cover page, the abstract will appear beneath the author with a +14-point bold-italic title, centered, with the text of the abstract +medium-roman and justified, indented 6 picas from both margins. +

+ +

DOC_COVER_IMAGE and COVER_IMAGE

+ +

+Macro: DOC_COVER_IMAGE <image> <width> <height> [ -L | -C | -R | -I <indent> <Y-pos> [ <X-pos> ] ] +

+ +

+Macro: COVER_IMAGE <image> <width> <height> [ -L | -C | -R | -I <indent> <Y-pos> [ <X-pos> ] ] +

+ +

+There are times you need a full page image on a cover, for example +the jacket of a book. Equally, there are times when you need a small +image on the cover, perhaps a company logo. +

+ +

+DOC_COVER_IMAGE and COVER_IMAGE take the same arguments +as PDF_IMAGE, and in the same order. Consult +PDF_IMAGE +for a description. +

+ +

+Two additional arguments allow you to place images using x-y +coordinates. Please note that if you use x-y coordinates for +positioning, Y-pos comes before X-pos in the order of +arguments. +

+ +

+Like PDF_IMAGE, the image file must be in PDF format. Mom +apologizes, but PostScript images are not supported for inclusion on +covers. See +Image conversion and file processing +for instructions on converting various image types to PDF, and +here +for instructions on obtaining image dimensions. +

+ +

Positioning of doc cover and cover images

+ +

+With no arguments other than <file name>, +<width>, and <height>, +DOC_COVER_IMAGE and COVER_IMAGE place images flush with the top +left corner of the printer sheet. This allows placing full-page +background images on covers. For example, assuming a US-letter page +size, +
+ + .DOC_COVER_IMAGE image.pdf 612p 792p + .DOC_COVER TITLE AUTHOR DOC_COVER_IMAGE + +will fill the doc cover page with “image.pdf” and set +the title and author in their usual locations. +

+ +

+For smaller images, the horizontal position is established +with one of the -L, -C, -R, or +-I <indent> arguments, just like +PDF_IMAGE. +You may instead use the X-pos argument, provided that it +is preceded by a Y-pos argument. The values given to +-I, Y-pos and X-pos must have a +unit of measure +appended to them. +

+ +

+Vertical positioning of smaller images requires the Y-pos +argument (which is why it precedes X-pos in the order of +arguments) otherwise the image will be flush with the top edge of +the printer sheet +

+ +

+The positioning of images does not effect the placement of type on +doc cover and cover pages. +

+ +

+Tip: +The combination of +COVERTEXT +and COVER_IMAGE make it possible to design covers entirely to your +own specifications. +

+ +

Enabling/disabling automatic generation of cover pages

+ +

+Macro: COVERS <toggle> +

+ +

+Macro: DOC_COVERS <toggle> +

+ +

+By default, if you give mom a +COVER +or +DOC_COVER +directive, she will print the cover or doc cover. 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 meet the requirement of preceding all subsequent +instances of START. +

+ +

Control macros for doc covers and covers

+ +

+The default typographic appearance of the items on a doc cover or +cover is identical to that of the items in a +docheader. +(See +Docheader description +for a description of the defaults.) +

+ +

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

the COPYRIGHT line is set flush with the document’s right + and bottom margins, 2 + point sizes + smaller than the size of + running text +
MISC lines are set flush with the document’s left and bottom + margins, in the same family, font and point size as the + copyright line. +

+ +

+The defaults for the entirety of doc covers and covers, and all the +elements thereon, can be changed with control macros whose defaults +and arguments are identical to the corresponding +Control macros for docheaders +(q.v.) The only difference is the name by which you invoke them. Wherever +DOCHEADER is used for overall changes, replace it +with DOC_COVER or COVER. For part-by-part +changes, prepend DOC_COVER_ or COVER_ to the +part/parameter. +

+ +

+Thus, to change the overall family, color, leading, quad, and +starting position of a doc cover, you’d do +
+ + .DOC_COVER_FAMILY H + .DOC_COVER_COLOR blue + .DOC_COVER_LEAD +2 + .DOC_COVER_QUAD L + .DOC_COVER_ADVANCE 3i \" or .DOC_COVER_START_POS 3i + +To change the style parameters for selected parts of a cover, you +might do something like this: +
+ + .COVER_TITLE_FONT B + .COVER_TITLE_SIZE +4 + .COVER_SUBTITLE_FONT I + .COVER_AUTHOR_FONT R + .COVER_AUTHOR_SPACE_BEFORE 6p + .COVER_DOCTYPE_COLOR red + .COVER_MISC_SIZE -1 + .COVER_MISC_LEAD 12 + .COVER_COPYRIGHT_SIZE -2 + .COVER_COPYRIGHT_QUAD L + .COVER_MISC_QUAD R + +Note in the above example that _COPYRIGHT_QUAD and _MISC_QUAD set +both the horizontal position on the page and the quad direction, +either L (or LEFT) or R (or RIGHT), and have no corresponding +docheader control macro. +

+ +

+Tip: +As with the docheader control macros, DOC_COVER_ and +COVER_ part/parameter style changes may be +grouped, +for example +
+ + .DOC_COVER_TITLE_STYLE \ + FAMILY A \ + FONT B \ + SIZE +4 \ + CAPS + +

+ + + + + + + + +

Back to Table of Contents

Top

Next: Tables of contents

+ +

+ + + diff --git a/contrib/mom/momdoc/definitions.html b/contrib/mom/momdoc/definitions.html new file mode 100644 index 0000000..b85a089 --- /dev/null +++ b/contrib/mom/momdoc/definitions.html @@ -0,0 +1,995 @@ + + + + + + + + + Mom -- Definitions and Terms + + + + + + + +

+ + + + + + + +

Back to Table of Contents

Next: Using mom

+ +

Definitions of terms used in this manual

+ +

+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 + Baseline + Ballot box + Bullet + Cap-height + Descender + Discretionary hyphen + Drop cap + Em/en + Family + Figure space/Digit space + Fixed width font + Fixed width space + Font + Force justify + Justify/justification + Gutter + Kerning + Kern Units + Lead/leading + Leaders + Ligature + Picas/Points + Point Size + Quad + Rag + Shape + Solid/set solid + Track kerning/Line kerning + Unbreakable space + Weight + Word space + x-height +

Typesetting terms

+ Ascender
+ Baseline
+ Ballot box
+ Bullet
+ Cap-height
+ Descender
+ Discretionary hyphen
+ Drop cap
+ Em/en
+ Family
+ Figure space/Digit space
+ Fixed width font
+ Fixed width space
+ Font
+ Force justify
+ Justify/justification
+ Gutter
+ Kerning
+ Kern Units
+ Lead/leading
+ Leaders
+ Ligature
+ Picas/Points
+ Point Size
+ Quad
+ Rag
+ Shape
+ Solid/set solid
+ Track kerning/Line kerning
+ Unbreakable space
+ Weight
+ Word space
+ x-height
+

+ +

+ + + + + +

Groff terms
+ Alias + Arguments + Comment lines + Control Lines + Filled lines + Inline escapes + Input line + Macros + Machine units + Numeric argument + Output line + Primitives + Pre-processor + String Argument + Unit of measure + Zero-width character +

+ +

+ + + + + +

Mom terms
+ Baseline grid + Blockquote + Control macro + Docheader + Epigraph + Float + Footer + Head + Header + Linebreak + Paragraph head + PDF link + PDF outline + Quote + Running text + Toggle +

+ +

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 + \% (i.e. a backslash followed by the percent sign). +

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 (i.e. a backslash followed by a zero) +

Fixed-width font

+ A family or font in which every character occupies exactly the + same amount of horizontal 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> (i.e. a backslash followed by a space) +

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, which, by default, is 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. + It is possible to change the default size of the kern unit with the + KERN_UNIT + macro. +

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 \~ (i.e. a 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 + headings 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 \# (i.e. a + 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 exactly 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 originally 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 + + +

+ IMPORTANT: 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. +

Pre-processor

+ Pre-processors are used by groff to generate tables + (tbl), diagrams (pic), graphs + (grap), and equations (eqn). + These pre-processors are fully supported by mom. In addition, + the “refer” pre-processor is used to generate + bibliographies and lists of cited works. The PDF_IMAGE macro, + which allows insertion of graphics into a document, is not + strictly a pre-processor but behaves similarly to tbl, pic, and + eqn. +

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 since most of the 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: + + + \& (i.e. a 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. + to 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 terms

Baseline grid: + Virtual guide lines spaced according to the + leading + established for running text. Adherence to the grid ensures that + text fills the page completely to the bottom margin. Uncorrected + deviations from the grid result in bottom margins that fall short. +
Control macro: + Macros used in + document processing + to control/alter the appearance of document elements (e.g. + headings, 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. +
Float: + A float is material intended to be kept together as a block. + Floated material that fits on a page in position is output on that + page. Floats that do not fit in position are deferred to the top + of the next page. +
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. +
Heading: + The title used to identify a section of a document. Headings + are hierarchic, corresponding to the notion of head, subhead, + subsubhead, etc. +
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 gap in the vertical flow of + 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 heading joined to the body of a paragraph. +
PDF link: + A portion of text that, when clicked on in a PDF viewer, + navigates to a bookmarked location in a document, generally but not + exclusively a heading. PDF links are usually coloured to make + them stand out from the surrounding text. +
PDF outline: + The hierarchically-arranged navigation outline provided by most PDF + viewers (e.g. Okular, Evince), typically in a panel to the left of + the document window, and usually labelled “Contents”. +
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 headings. + Docheaders, + headers, + footers + and page numbers are not part of running text. +
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. +

+ +

+ + + + + + + + +

Back to Table of Contents

Top

Next: Using mom

+ +

+ + + diff --git a/contrib/mom/momdoc/docelement.html b/contrib/mom/momdoc/docelement.html new file mode 100644 index 0000000..43f79d4 --- /dev/null +++ b/contrib/mom/momdoc/docelement.html @@ -0,0 +1,6639 @@ + + + + + + + + + Mom -- Document processing, element tags + + + + + + + +

+ + + + + + + +

Back to Table of Contents

Next: Graphics, floats, preprocessor support

+ +

The document element tags

+ +

Introduction to the document element tags
Control macros – changing the tag defaults +
- Arguments to the control macros +
  - family and font
  - point size
  - colour
  - quad/justification
  - underline style, rule weight
- Grouping control macros

+ +

Document element tags table of contents

+ +

+ +

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 heading; this is a +footnote,” and so on. +

+ +

+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 the tag 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. +

+ +

+Tip: +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. +

+ +

+Important: +The family, font, point size, colour and leading control macros have +no effect in +PRINTSTYLE TYPEWRITE, +except where noted throughout this documentation. +

+ +

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

+ +

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 +<n> or -<n> where +<n> is the number of +points +larger (+) or smaller (-) than the point size of paragraphs +you want the document element to be. For example, to set +blockquotes 2 points smaller than the type in paragraphs, do +
+ + .BLOCKQUOTE_SIZE -2 + +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 +author linebreaks +to be red, once you’ve defined or initialized the colour, red, +
+ + .LINEBREAK_COLOR red + +will turn them 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 +leading. +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 + +

+ +

+Note: +_AUTOLEAD control macros do not have a FACTOR argument. +

+ + +

Indents

+ +

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

+ +

+A digit without a unit of measure appended represents by +how much you want your paragraph first-line indents (set with +PARA_INDENT) multiplied to achieve the correct indent for a +particular tag. For example, +
+ + .PARA_INDENT 2m + .BLOCKQUOTE_INDENT 2 + +means that blockquotes will be indented from the left and right +margins by twice the size of the paragraph indent, or 4 +ems. +

+ +

+A digit with a unit of measure appended defines an absolute +indent, relative to nothing. In the following, blockquotes will be +indented by 3 +picas +and 6 +points, +regardless of the paragraph indent. +
+ + .PARA_INDENT 2m + .BLOCKQUOTE_INDENT 3P+6p + +

+ +

Quad / justification style

+ +

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

+ +

Underscore style, rule weight

+ +

+If mom gives the option to underscore a document element, the weight +of the underline and its distance from the +baseline +are controlled by macros that end in _UNDERSCORE or _UNDERLINE, the +two being synonymous. These macros take the following arguments: +
+ + DOUBLE - double underscore + <weight> - the underscore weight (in points, no unit of measure required + <distance> - distance from baseline (unit of measure required) + <rule gap> - distance between double underscore rules (unit of measure required) + +DOUBLE by itself will double-underscore the element. The +remaining arguments must be entered in the order given. You may not +skip over any of them, which means that if you only wish to change +<rule gap>, you must still enter a +<weight> and <distance> argument. +

+ +

+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 _UNDERSCORE macros is the same as the +argument to +RULE_WEIGHT, +as is the argument to _RULE_WEIGHT macros. +

+ +

Grouping control macros

+ +

+As of version 2.1, it is possible to group control macros for a +particular tag into a single <element>_STYLE macro. +For example, rather than setting the family, size, and indent of +BLOCKQUOTES +with +
+ + .BLOCKQUOTE_FAMILY H + .BLOCKQUOTE_SIZE -2 + .BLOCKQUOTE_INDENT 4P + +you can enter the same style parameter changes with +
+ + .BLOCKQUOTE_STYLE \ + FAMILY H \ + SIZE -2 \ + INDENT 4P + +<element>_STYLE macros use +“keyword/value” pairs (FAMILY is a keyword, +H is a value), and may be entered entirely on one line, +or, as the example shows, broken into several readable lines using +the backslash. The macro itself and all but the last keyword/value +pair require the backslash when this style is used. +

+ +

+Not all the control macros for a particular tag may be available +with an <element>_STYLE macro. Generally speaking, +though, if a tag has control macros for +

+ + + + + + + + + + + + + + + + + + +

FAMILY	LEAD	INDENT	SMALLCAPS
FONT	AUTOLEAD	COLOR	UNDERSCORE or UNDERLINE
SIZE	QUAD	CAPS

+those parameters may be used within an +<element>_STYLE macro. +

+ +

+Note: +If you need to reverse the sense of CAPS, +SMALLCAPS or UNDERSCORE/UNDERLINE, which +do not take a value after the keyword, use NO_CAPS, +NO_SMALLCAPS, and NO_UNDERSCORE/NO_UNDERLINE. +

+ +

+ + + +

Epigraphs

+ +

Tag: EPIGRAPH
Epigraph control macros and defaults

+ +

+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 accommodate +filled +epigraph “blocks.” +

+ + + +

EPIGRAPH

+ +

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

+ +

+Tips on vertical spacing around epigraphs: +If you wish to change the vertical position of an epigraph with +SPACE, +ALD, or +RLD, +do so before invoking .EPIGRAPH, like this: +
+ + .SP -6p + .EPIGRAPH + A notable quote. + .EPIGRAPH OFF + +If you’re setting a document in +columns +and you’d like to add or subtract space after the +epigraph, which is centred over the top of both columns, the place +to do it is inside the epigraph, like this: +
+ + .EPIGRAPH + A notable quote. + .SP 1v + .EPIGRAPH OFF + +If you were to add the .SP 1v outside the epigraph, the +space would be added to the top of the leftmost column only, +resulting in unbalanced columns. +

+ +

EPIGRAPH control macros and defaults

+ +

+See +Arguments to the control macros. +
+The following EPIGRAPH control macros may also be +grouped +using EPIGRAPH_STYLE. +

+ + +.EPIGRAPH_FAMILY default = prevailing document family; default is Times Roman +.EPIGRAPH_FONT default = roman +.EPIGRAPH_SIZE default = -1.5 (points) +.EPIGRAPH_COLOR default = black +.EPIGRAPH_AUTOLEAD default = 2 points +(The next two apply to “block” style epigraphs only) +.EPIGRAPH_INDENT* (see Note on EPIGRAPH_INDENT, below) + +*Indent here refers to the indent from both the left and right margins + that centres block style epigraphs on the page. + +

+ +

Note on EPIGRAPH_INDENT

+ +

+If you pass EPIGRAPH_INDENT an integer with no unit of measure +appended, the integer represents the amount by which to multiply +PARA_INDENT to arrive at an indent for block style epigraphs. If +you append a unit of measure to the argument, the indent will be +precisely the amount specified. +

+ +

+Please also 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

+ +

Tag: PP
Paragraph control macros and defaults

+ +

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

+ +

+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 widow or orphan control for +paragraphs (i.e., even if only one line of a paragraph fits at the +bottom of a page, she will set it on that page). The reason for +this is that writers of fiction often have single-line paragraphs +(e.g. in dialogue). Groff’s simplistic orphan control will +break these one-liners—if they fall at the bottom of the +page—to a new page, which is not what you want. +

+ + + +

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, +endnotes +and +footnotes. +

+ +

PP control macros and defaults

+ +

+The PP macro being so important, and representing, as it were, the +basis of everything that goes on in a document, its control is +managed in a manner somewhat different from other document element +tags. As a result, the control macros for PP may not be +grouped +within a _STYLE macro. +

+ +

Family control
Font control
Paragraph colour
Leading/linespacing control
Justification/quad control
First-line indent control
Initial paragraphs indent control
Inter-paragraph spacing

+ +

1. Family control

+ +

+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. Alternatively, set the family and font for +paragraphs with PP_FONT, giving it a complete family+font name, e.g. +
+ + PP_FONT TI + +which would make the font used in paragraphs Times Roman Italic. +

+ +

+Mom’s default paragraph (and document) family is Times Roman. +

+ +

+Note: +Neither FAMILY nor DOC_FAMILY has any effect when the PRINTSTYLE is +TYPEWRITE. +

+ +

2. Font control

+ +

+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, +endnotes, +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. +

+ +

+Note: +PP_FONT has no effect when the PRINTSTYLE is TYPEWRITE. +If you wish to set whole typewritten paragraphs in italic, invoke +.FT I immediately after .PP. Depending +on which of +UNDERLINE_ITALIC +or +ITALIC_MEANS_ITALIC +is currently enabled, the paragraph will be set underlined or in +italic. Neither persists past the end of the paragraph. +

+ +

3. Paragraph colour

+ +

+Mom has no special control macro for colourising paragraphs. If you +wish a colourised paragraph, you must use the macro +COLOR +or the +inline escape, +\*[<colourname>], +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> + .HEADING 1 "Monty Python" + .HEADING 2 "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. +

+ +

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 any +paragraph whose leading you wish to change. +

+ +

+Warning: +Changing a paragraph’s leading will almost certainly screw up +mom’s ability to balance the bottom margin of pages. Should +you absolutely require a change to a paragraph’s leading and +need to get mom back on track leading-wise afterwards, use the +SHIM +or +FLEX +macro, depending on which +vertical whitespace management +strategy you are using. +

+ +

+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, +footnotes, +and +endnotes, +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 +when the +PRINTSTYLE +is TYPESET is justified; for PRINTSTYLE +TYPEWRITE, the default is quad left. +

+ +

6. First-line 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

+ +

+By default, mom does not indent the first paragraph of a document, +nor the first paragraph after a heading or +linebreak, +nor the first paragraphs of +epigraphs, +blockquotes, +endnotes +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. Inter-paragraph spacing

+ +

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

+ +

+If you would like to space paragraphs by less than a full linespace, +invoke PARA_SPACE with the amount of space you want as a numeric +argument. A +unit of measure +is required. For example, to space paragraphs by one-quarter +linespace + + .PARA_SPACE .25v + +is how you’d do it, or, if you want six points between +paragraphs + + .PARA_SPACE 6p + +

+ +

+If +flex-spacing +is enabled, additional flexible vertical whitespace can be inserted +between spaced paragraphs with the +FLEX +macro. +

+ +

+PARA_SPACE is not recommended for use with PRINTSTYLE TYPEWRITE +unless you give PRINTSTYLE the SINGLESPACE option. +

+ +

+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 +(i.e. the start of a document), +epigraphs, +headings, +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. +

+ +

+ + + +

Headings

+ +

Tag: HEADING
Spacing of headings
Heading control macros and defaults
Prefixing chapter numbers
Oldstyle headings +
- Important information about PARAHEAD +
  - Correct usage of paraheads

+ +

+Heads, subheads, and deeper levels of section headings are +handled by a single macro, HEADING, to which you pass an argument +stating the desired level. +.HEADING 1 "<text>", +for example, would be a main head; +.HEADING 2 "<text>" +would be a subhead; etc. +

+ +

+In addition to printing headings in the body of your document, +HEADING collects the heading as an entry for the Table of Contents, +if the document is to have one, and the +PDF outline. +With the NAMED argument, it furthermore acts as a +bookmark for +PDF links. +

+ +

+Headings can also be numbered on a per-heading-level basis, +hierarchically and concatenatively, e.g. +
+ + 1. + 1.1 + 1.2 + 1.2.1 + 2. + 2.1 + 2.2 + 2.2.1 + +By default, a blank line precedes headings, regardless of the level. +Mom initially sets up a very basic style for nine levels of heading, +of which you can have an infinite number, although as has been said, +if you need more than four levels of heading, you should consider +re-organising your material. The pared-down style of mom’s +defaults is intentional; it is expected that you will design +headings to your own specifications with the +control macro, +HEADING_STYLE. +

+ +

+It is very good practice, and strongly recommended, that you respect +the hierarchy of headings, using level-1 for main heads, level-2 for +subheads, level-3 for subsubheads, etc. The ease of designing and +re-designing the style for each level, plus mom’s very basic +defaults, are meant, in part, to prevent the whimsical misuse of +a particular heading level just because its style appeals to you. +

+ + + +

HEADING

+ +

+Macro: HEADING <level> [ +PARAHEAD ] [ NAMED <pdf-id> ] "<heading text>" +

+ +

+The first argument to HEADING is the level. Level 1 is +analogous to a main head; level 2 is analogous to a subhead; level 3 +is analogous to a subsubhead; etc. +

+ +

+The second (optional) argument, PARAHEAD, instructs mom +that the heading should be treated as a +paragraph head. +If HEADING is being used to create a parahead, it must come after +PP, +not before. +

+ +

+The indent applied to a parahead is the same as what would be +expected from a paragraph without the parahead (see +Indenting initial paragraphs). +If you wish that a paragraph introduced by a parahead not be +indented, use +PARA_INDENT +to set the paragraph indent to zero, then reset the indent for +subsequent paragraphs. +

+ +

+The optional third argument, NAMED <id>, gives +the heading a unique, non-printing identifier that allows it to be +referenced from anywhere in the final PDF document with the PDF_LINK +macro, provided the mom file is processed with +pdfmom. +PDF_LINK usage is explained in the manual, +Producing PDFs with groff and mom. +

+ +

+The final argument is the text of the heading, surrounded by double +quotes. Long headings that are likely to exceed the current +line length should be broken into chunks, each surrounded by +double-quotes, like this: +
+ + .HEADING 1 "A needlessly long but instructive" "first level heading" + +

+ +

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

+ +

Spacing of headings

+ +

+As described above, mom inserts a blank line before each heading. +If the leading of your document never changes, and you introduce no +additional space into the text—as, for example, between +paragraphs—this will result in perfectly equal whitespace before +each heading. +

+ +

+If, however, you disrupt the regular placement of text on +mom’s +baseline grid, +HEADING adds extra whitespace to the blank line according to the +vertical whitespace management +strategy in effect. This, along with a similar strategy for +whitespace around quotes, blockquotes, and +floated +and +pre-processor material +is what allows mom to balance the bottom +margins of pages effectively. +

+ +

+It occasionally happens that the extra whitespace becomes +noticeable. This typically occurs when the amount of whitespace +adjustment approaches the value of the current leading. The result +looks like two blank lines instead of one. When this happens, a +simple but effective fix is to reduce the space before the heading +by backing up one line, either with +
+ + .SPACE -1v + +or +
+ + .RLD -1v + +This results in slightly less whitespace than normal, but the +difference is usually not apparent. Alternatively, you may pass the +NO_SHIM or NO_FLEX argument to +HEADING_STYLE +to prevent shimming or flex-spacing of any particular heading level +either globally or selectively. If shimming/flex-spacing is +disabled selectively with +
+ + .HEADING_STYLE <n> NO_SHIM | NO_FLEX + +it can be re-enabled for the heading level with +
+ + .HEADING_STYLE <n> SHIM | FLEX + +

+ +

HEADING control and defaults

+ +

+By default, mom pre-initializes nine levels of headings to use +the bold font of the prevailing document family, with a baseline +adjustment of 1/10 of the current +leading. +In addition, level-1 headings are 3 points larger than running text, +level-2 headings 2 points larger, and level 3-headings 1 point +larger. The remaining 6 levels are the same size as running text. +A single blank line precedes all levels of heading. +

+ +

The HEADING_STYLE macro

+ +

+Styling heads is accomplished with a single macro +
+ + .HEADING_STYLE <level> + +where <level> is the numeric heading level to which +the style applies. +

+ +

+HEADING_STYLE takes any or all of the following arguments, +which may be given in any order: +
+ + FAMILY <family> \ + FONT <font> \ + SIZE <+|-size> \ + QUAD <direction> \ + COLOR <colour> \ + UNDERSCORE <weight> <gap> | NO_UNDERSCORE \ + UNDERSCORE2 <weight> <gap1> <gap2> | NO_UNDERSCORE2 \ + CAPS | NO_CAPS \ + SMALLCAPS | NO_SMALLCAPS \ + BASELINE_ADJUST <amount to raise heading from the baseline> \ + NEEDS <lines of text required beneath the heading> \ + PREFIX_CHAPTER [<n>] \ + SPACE_AFTER | NO_SPACE_AFTER \ + NUMBER | NO_NUMBER \ + NO_SHIM | SHIM \ + NO_FLEX | FLEX + +

+ +

+You may enter your entire argument list on a single line, or, if it +is very long, break it into shorter lines with the +“line-continued” backslash (\), as shown +above. +

+ +

+The arguments to FAMILY, FONT, +SIZE, QUAD, and +COLOR are the same as +those you’d give to the +control macros +ending in _FAMILY, _FONT, _SIZE, _QUAD, or _COLOR. See +Arguments to the control macros. +

+ +

+UNDERSCORE and UNDERSCORE2 require that a +weight for the underscore be given, in points (decimal fractions +allowed), but without the unit of measure p appended. +They also require that the underscore’s distance from the +baseline be supplied; in the case of UNDERSCORE2, an additional gap +argument representing the distance between the two underscores must +be provided. +

+ +

+The CAPS argument capitalizes the text of a heading +level in the body of a document but not in the Table of +Contents, where capitalization of entries is controlled by +TOC_ENTRY_STYLE <n>. +

+ +

+BASELINE_ADJUST allows you to raise a heading slightly +above the baseline on which it would otherwise sit. For aesthetic +reasons, it is often desirable to introduce a small amount of space +between a heading and the text following it. Since headings are +preceded by a blank line, it is preferable to move the heading +upward than to lower the text following it. The argument to +BASELINE_ADJUST is the amount by which to raise the heading. It +requires no + or - sign, and must have a +unit of measure +appended to it. +

+ +

+NEEDS lets you reserve the number of lines of text +required beneath a heading, including fractions thereof (e.g. +“1.5” for one line of text plus half a linespace). +If a heading falls near the bottom margin and there isn’t +sufficient room for both the heading and the reserved space, mom +will break to a new page for the heading. A +unit of measure +should not be appended to the argument. +Note: If you have +DROPCAPs +after headings, you must increase the value of NEEDS +to match the number of dropcap lines. +

+ +

+PREFIX_CHAPTER instructs mom to prefix the current +chapter number to numbered headings. If mom is unable to determine +a chapter number, she will ask for one. +

+ +

+Note that using PREFIX_CHAPTER with an explicit chapter +number will also set the chapter number for subsequent +automatically-generated image and pre-processor labels +as well. +

+ +

+SPACE_AFTER inserts a blank line equal to the current +leading after a HEADING. +If you’d like a full linespace after a heading level, use +SPACE_AFTER. If you’d like additional space before +a heading level, you must introduce it yourself with +SPACE +or +ALD. +

+ +

+NUMBER and NO_NUMBER allow you to determine +whether mom prepends a hierarchic numbering scheme to a heading +level in the body of a document. Numbering of Table of Contents +entries is controlled separately with +TOC_ENTRY_NUMBERS. +Mom also has a special macro to toggle whether to prefix a chapter +number to numbered headings and Table of Contents entries, +PREFIX_CHAPTER_NUMBER. +

+ +

+SHIM is not necessary if shimming is enabled +globally, which it is by default; it exists to re-enable +shimming for the heading level if you have previously passed +HEADING_STYLE <n> a NO_SHIM +argument. The FLEX and NO_FLEX arguments work +the same way if flex-spacing is enabled. +

+ +

+The argument list is long, so you may want to break it into +several lines by using the backslash character (\). +Here’s an example of how you might style a level 1 heading: +
+ + .HEADING_STYLE 1 \ + FONT B \ + QUAD C \ + UNDERSCORE .5 2p \ + BASELINE_ADJUST 3p \ + NUMBER + +This creates a level-1 heading style that’s bold, centred, +underscored and numbered, raised by 3 points from the baseline. +

+ + + +

Prefixing chapter numbers

+ +

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

+ +

+If, in addition to numbering heads, you want mom to prepend the +chapter number, invoke .PREFIX_CHAPTER_NUMBER. +

+ +

+When you invoke .PREFIX_CHAPTER_NUMBER without an +argument, mom checks to see whether the argument you passed to CHAPTER (if it’s been +called) is a digit. If it isn’t (say you’ve numbered your +chapter “One” instead of “1”), mom will +abort with a request that you pass PREFIX_CHAPTER_NUMBER a digit +representing the chapter number. +

+ +

+After you invoke .PREFIX_CHAPTER_NUMBER, mom will prepend +the chapter number to all headings you have requested be numbered +with +.HEADING_STYLE <n> NUMBER. +Thus, assuming chapter number twelve (12): +
+ + 1. LEVEL 1 HEADING + 1.1. Level 2 heading + +would become +
+ + 12.1. LEVEL 1 HEADING + 12.1.1. Level 2 heading + +

+ +

+Note: +If a chapter number is given to PREFIX_CHAPTER_NUMBER, automatically +generated labels with a prepended chapter number are also affected. +

+ +

+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 number your chapters +“One”, “Two”, “Three” instead of +“1”, “2”, “3”, mom will Do The +Right Thing with respect to numbering head (and label) elements +in all collated chapters following the first invocation of +PREFIX_CHAPTER_NUMBER (assuming, of course, that the collated +chapters are in incrementing order; if not, you must put +
+ + .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, Q, +X...), 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. +

+ + + +

Oldstyle headings

+ +

Macro: OLDSTYLE_HEADINGS
Macro: HEAD
Macro: SUBHEAD
Macro: SUBSUBHEAD

+ +

+In versions of mom prior to 2.0, headings were entered by their +commonly used names, viz. HEAD, SUBHEAD, and SUBSUBHEAD. The +new +HEADING +scheme allows for greater flexibility, and permits seamless +integration with PDF output. +

+ +

+Documents created with pre-2.0 versions may still use the oldstyle +heading names, as may new documents, however there are some +differences in their behaviour. +

+ +

+Whenever mom encounters an oldstyle heading, she loads the default +style formerly associated with the oldstyle name. See below for a +description of the default styles in the sections +HEAD (now HEADING 1), +SUBHEAD (now HEADING 2), +and +SUBSUBHEAD (now HEADING 3). +Mom also emits a message to stderr alerting you to what she’s +doing. +

+ +

+The control macros formerly associated with oldstyle headings are no +longer present in mom’s macro file, which means that if you +made changes to mom’s default for those headings, you must +recreate the changes with the +HEADING_STYLE +macro. The entire style need not be recreated, only those +parameters that differed from mom’s defaults. Thus, if your +HEADs were set flush left, instead of the oldstyle default, centred, +but otherwise kept mom’s settings, you need only do +
+ + .HEADING_STYLE 1 QUAD L + +

+ +

+Important: +The macro PARAHEAD is no longer available. You must create paragraph +heads using the +HEADING +macro. Mom will abort with an informational message whenever she +encounters PARAHEAD. Assuming a heading level of 3 for your +paraheads, the former defaults for PARAHEAD can be set up like this: +
+ + .HEADING STYLE 3 FONT BI SIZE -.25 \" For PRINTSTYLE TYPESET + .HEADING STYLE 3 FONT I SIZE +0 \" For PRINTSTYLE TYPEWRITE + +Equally, the macro NUMBER_PARAHEADS is no longer available. You +must enable numbering of the correct level for paraheads with +HEADING_STYLE. Again assuming a heading level of 3 for paraheads, +it’s simply done: +
+ + .HEADING_STYLE 3 NUMBER + +

+ +

Correct usage of paraheads

+ +

+It is tempting to choose an arbitrary heading level for paraheads, +since they are sometimes needed out-of-sequence; for example, +immediately after a main head (level-1) in a document that +subsequently requires subheads (level-2). In such a circumstance, +choosing level-3 for all your paraheads might seem to make sense, +but in fact doesn’t, since it disrupts the hierarchy of +both the Table of Contents (if your document has one) and the PDF +outline. +

+ +

+Correct use of the PARAHEAD option to HEADING under such +circumstances requires always assigning PARAHEAD to +the next logical level in the heading hierarchy. For example, if +there are no headings before the parahead, it should be assigned to +level-1. If subsequently there is a main head to be followed by +more paraheads, the main head should be level-1, and the paraheads +level-2. This will almost certainly require assigning new style +parameters to level-1 (with +HEADING_STYLE) +and to the level now being used for paraheads. The following +example demonstrates. +
+ + .HEADING_STYLE 1 FONT BI SIZE +.25 \" parahead style, level-1 + .PP + .HEADING 1 PARAHEAD <parahead> + <paragraph text> + .PP + .HEADING 1 PARAHEAD <parahead> + <paragraph text> + \# main head style, level-1 + .HEADING_STYLE 1 FONT B SIZE +3 QUAD CENTER UNDERSCORE .5 2p + .HEADING_STYLE 2 FONT BI SIZE +.25 \" parahead style, level-2 + .HEADING 1 <main head> + .PP + <paragraph text> + .PP + .HEADING 2 PARAHEAD <parahead> + <paragraph text> + +

+ + + +

OLDSTYLE HEADINGS

+ +

+Macro: OLDSTYLE_HEADINGS +

+ +

+OLDSTYLE_HEADINGS requires no argument. It instructs mom to set the +first three levels of heading to the parameters of her old defaults +for HEAD, SUBHEAD, and SUBSUBHEAD. Use of OLDSTYLE_HEADINGS will +also prevent mom from generating the message she issues the first +time she encounters HEAD, SUBHEAD, and SUBSUBHEAD. +

+ + + +

+Macro: HEAD [ NAMED <id> ] "<text of head>" "<another line>"... +

+ +

+When invoked for the first time, with or without +OLDSTYLE_HEADINGS, +HEAD sets the parameters for level-1 headings to mom’s old +HEAD defaults, then prints the head as a level-1 heading. +The NAMED <id> optional argument is explained in +the description of +HEADING. +

+ +

+If, prior to invoking HEAD, you have given any parameters to level-1 +heads with +HEADING STYLE, +they will be preserved; any you give afterwards will be respected. +

+ +

+The former style defaults for HEAD were: +
+ + FAMILY = prevailing document family + FONT = bold (TYPESET); roman (TYPEWRITE) + SIZE = +1 (TYPESET); +0 (TYPEWRITE) + QUAD = C + UNDERSCORE .5 2p + CAPS + +

+ +

+Note: +The macro NUMBER_HEADS from pre-2.0 versions of mom, can still be +used, though it is now a wrapper for +
+ + .HEADING_STYLE 1 NUMBER + +Mom will alert you to this on stderr. +

+ + + +

+Macro: SUBHEAD [ NAMED <id> ] "<text of head>" "<another line>"... +

+ +

+When invoked for the first time, with or without +OLDSTYLE_HEADINGS, +SUBHEAD sets the parameters for level-2 headings to mom’s old +SUBHEAD defaults, then prints the subhead as a level-2 heading. +The NAMED <id> optional argument is explained in +the description of +HEADING. +

+ +

+The former style defaults for SUBHEAD were: +
+ + FAMILY = prevailing document family + FONT = bold (TYPESET); italic, i.e. underlined (TYPEWRITE) + SIZE = +.5 (TYPESET); +0 (TYPEWRITE) + QUAD = L + BASELINE_ADJUST = 1/8 the current leading + +

+ +

+Note: +The macro NUMBER_SUBHEADS from pre-2.0 versions of mom, can still be +used, though it is now a wrapper for +
+ + .HEADING_STYLE 2 NUMBER + +Mom will alert you to this on stderr. +

+ + + +

+Macro: SUBSUBHEAD [ NAMED <id> ] "<text of head>" "<another line>"... + +

+ +

+When invoked for the first time, with or without +OLDSTYLE_HEADINGS, +SUBSUBHEAD sets the parameters for level-3 headings to mom’s old +SUBSUBHEAD defaults, then prints the subsubhead as a level-3 heading. +The NAMED <id> optional argument is explained in +the description of +HEADING. +

+ +

+The former style defaults for SUBSUBHEAD were: +
+ + FAMILY = prevailing document family + FONT = italic (TYPESET); roman (TYPEWRITE) + SIZE = +.5 (TYPESET); +0 (TYPEWRITE) + QUAD = L + BASELINE_ADJUST = 1/8 the current leading + +

+ +

+Note: +The macro NUMBER_SUBSUBHEADS from pre-2.0 versions of mom, can still be +used, though it is now a wrapper for +
+ + .HEADING_STYLE 3 NUMBER + +Mom will alert you to this on stderr. +

+ +

+ + + +

Linebreaks (section breaks)

+ +

Tag: LINEBREAK
Linebreak control macros and defaults

+ +

+Linebreaks (“author linebreaks”, “section +breaks”) are gaps in the vertical flow of running text that +indicate a shift in content (e.g. a scene change in story). They +are frequently set off by typographic symbols, sometimes whimsical +in nature. +

+ + + +

LINEBREAK

+ +

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

+ +

LINEBREAK control macros and defaults

+ +

+By default, mom marks +author linebreaks +with three centred asterisks (stars) in the prevailing colour of the +document (by default, black). You can alter this with the control +macros +

LINEBREAK_CHAR
LINEBREAK_COLOR

+ +

1. Linebreak character

+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, raised 3 points from their normal vertical +position (for +PRINTSTYLE TYPESET; +the vertical adjustment is -2 points for +PRINTSTYLE TYPEWRITE). +

+ +

2. Linebreak colour

+ +

+Macro: LINEBREAK_COLOR <colourname> +

+Alias: SECTION_COLOR +

+ +

+To change the colour of the linebreak character(s), simply invoke +.LINEBREAK_COLOR with the name of a colour pre-defined +(or “initialized”) with +NEWCOLOR +or +XCOLOR. + +

+ +

+ + + +

Quotes (line for line, poetry or code)

+ +

Introduction +
Tag: QUOTE
Quote control macros and defaults

+ +

+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 code snippets in +documents.) +

+ +

QUOTE spacing

+ +

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

+ +

Notes on quote spacing

+ +

+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 +(shim or flex-spacing) +around the quotes to make sure the whitespace is equal, top and +bottom. When shimming is enabled, this may result in multiple +quotes or blockquotes on the same page being spaced slightly +differently. +

+ +

Disable shimming/flex-spacing of quotes and blockquotes

+ +

+If you don’t want the behaviour +described above (i.e., you don’t want mom putting additional shim +or flex-spacing around quotes and +blockquotes), put .NO_SHIM or/and .NO_FLEX +in the style sheet section of your document (i.e. after PRINTSTYLE +but before START), which will disable shimming or/and flex-spacing +globally for all tags, or disable shimming/flex-spacing +on a per-instance basis prior to .QUOTE or +.BLOCKQUOTE, re-enabling it after the terminating +.QUOTE OFF or .BLOCKQUOTE OFF with +.NO_SHIM OFF or .NO_FLEX OFF. +

+ +

Keeping QUOTEs and BLOCKQUOTEs together as a block

+ +

+The text of quotes and blockquotes is output immediately, and may therefore +start on one page and finish on the next. If you wish to keep the +text together as a block, deferred to the following page if the +block doesn’t all fit on one page, wrap +(BLOCK)QUOTE...(BLOCK)QUOTE OFF +inside a +float. +If you further wish to force a page break before the floated quote +or blockquote (leaving whitespace at the bottom of the page, pass +FLOAT +the FORCE argument. + + .FLOAT FORCE + .QUOTE + Fly me to the moon + And let me play among the stars + Let me see what life is like + On Jupiter and Mars + .QUOTE END + .FLOAT OFF + +

+ +

Labelling/captioning quotes and blockquotes

+ +

+Quotes and blockquotes may be labelled and/or captioned identically to +floats +with the macros +LABEL +and +CAPTION +(see +Labelling and captioning floats). +

+ + + +

QUOTE

+ +

+Macro: QUOTE [ ADJUST +|-<space> ] | <anything> +

+• The argument to ADJUST requires a +unit of measure +

+ +

+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 + +Mom does her best to equalize whitespace around quotes and make +sure the line following it falls on a valid baseline. On occasion, +you may need to tweak the quote placement slightly, which is done +by passing ADJUST to QUOTE with a plus or minus value. +The quote will be lowered (+) or raised (-) +within the space allotted for it by the given amount. For +example, to lower a quote slightly within the space allotted for it, +you’d do +
+ + .QUOTE ADJUST +3p + There was a soprano named Golda + Whose lovers grew colda and colda + For during love-making + She'd sing the earth-shaking + Love theme from Tristan und Isolde. + .QUOTE off + +

+ +

QUOTE control macros and defaults

+ +

Family/font/size/leading/colour/indent
Spacing above and below quotes (typeset only)
Underlining quotes (typewrite only)

+ +

1. Family/font/size/colour/indent

+ +

+See +Arguments to the control macros. +
+The following QUOTE control macros may also be +grouped +using QUOTE_STYLE. If you do so, QUOTE_LEFT, QUOTE_CENTER, +and QUOTE_RIGHT must be entered as: +
+   QUAD LEFT
+   QUAD CENTER
+   QUAD RIGHT +

+ + +.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") +.QUOTE_LEFT -+ Quad direction of quote. +.QUOTE_CENTER | LEFT observes QUOTE_INDENT; +.QUOTE_RIGHT -+ CENTER and RIGHT do not + +

+ +

Quote indent

+ +

+QUOTE_INDENT takes one of two kinds of argument: an integer +representing the amount by which to multiply the argument passed to +.PARA_INDENT +(by default, 2 +ems +for TYPESET, 3 +picas +for TYPEWRITE) to arrive at the quote indent, or a distance with a +unit of measure +appended. +

+ +

+Be careful when using QUOTE. If a quote is set flush left (the +default), the QUOTE_INDENT applies only to the left margin. Because +quote lines are output as-is (see +no-fill mode), +they do not respect line length and may extend beyond a document's +right margin. Similarly, if a quote is being set flush right, the +indent applies only to the right margin; long lines may extend into +the left margin. Centered quotes are never indented, so long lines +may extend beyond both the left and right margins. +

+ +

+The default value for QUOTE_INDENT is 3 (for +PRINTSTYLE TYPESET) +and 1 (for +PRINTSTYLE TYPEWRITE). +

+ +

+Note: +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. +

+ +

2. Spacing above and below 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 +Quote spacing), +invoke the macro with any argument (OFF, QUIT, +END, X...) +

+ +

+Note: +This macro also sets mom’s spacing policy for +blockquotes. +

+ +

3. Underlining 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). +

+ +

+ + + +

Blockquotes (cited material)

+ +

Introduction
Tag: BLOCKQUOTE
BLOCKQUOTE control macros

+ +

+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 +Quote spacing +for a complete explanation of how this is managed, and how +to control it.) +

+ +

+Additional information concerning blockquotes, floats, and labelling +blockquotes can be found in the sections +Keeping quotes and blockquotes together as a block, +and +Labelling/captioning quotes and blockquotes. +

+ + + +

BLOCKQUOTE

+ +

+Macro: BLOCKQUOTE [ ADJUST +|-<space> ] | <anything> +

+ +

+Aliases: CITE, CITATION +

+ +

+• The argument to ADJUST requires a +unit of measure +

+ +

+BLOCKQUOTE is a toggle macro. To begin a cited passage, invoke +the tag with no argument, then type in your blockquote. When +you’re finished, invoke .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 + \[em]George W. Bush + .BLOCKQUOTE END + +If the cited passage runs to more than one paragraph, you must +introduce each paragraph—including the first—with +.PP. +

+ +

+Mom does her best to equalize whitespace around blockquotes and make +sure the line following it falls on a valid baseline. On occasion, +you may need to tweak the blockquote placement slightly, which is +done by passing ADJUST to BLOCKQUOTE with a plus or minus +value. The blockquote will be lowered (+) or raised +(-) within the space allotted for it by the given +amount. For example, to raise a blockquote slightly within the +space allotted for it, you’d do +
+ + .BLOCKQUOTE ADJUST -3p + True! - nervous - very, very dreadfully nervous I had been and + am; but why will you say that I am mad? The disease had sharpened + my senses - not destroyed - not dulled them. + .RIGHT + \[em]Edgar Allen Poe, The Tell-Tale Heart + .QUOTE off + +

+ +

+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 or end with +BLOCKQUOTE_. +

+ +

BLOCKQUOTE control macros and defaults

+ +

Family/font/size/leading/colour/quad/indent
Spacing above and below (typeset only)

+ +

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

+ +

+See +Arguments to the control macros. +
+The following BLOCKQUOTE control macros may also be +grouped +using BLOCKQUOTE_STYLE. +

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

+ +

+BLOCKQUOTE_INDENT takes one of two kinds of argument: an +integer representing the amount by which to multiply the argument +passed to +PARA_INDENT +(by default, 2 +ems +for TYPESET, 3 +picas +for TYPEWRITE) to arrive at the blockquote indent, or a distance with a +unit of measure +appended. Both result in blockquotes being indented equally from +the left and right margins. +

+ +

+The default value for BLOCKQUOTE_INDENT is 3 (for +PRINTSTYLE TYPESET) +and 1 (for +PRINTSTYLE TYPEWRITE). +

+ +

+Note: +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. +

+ + + +

2. Spacing above and below blockquotes (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 +Quote spacing), +invoke the macro with any argument (OFF, QUIT, +END, X...). +

+ +

+Note: +This macro also sets mom’s spacing policy for +quotes. +

+ +

+ + + +

Inserting code into a document

+ +

Tag: CODE
CODE control macros and defaults

+ +

+CODE is a convenience macro that facilitates entering code blocks +into documents. Its use is not restricted to documents created +using mom’s document processing macros; it can be used for +“manually” typeset documents as well. +

+ +

CODE

+ +

+Macro: CODE [BR | BREAK | SPREAD] <anything> +

+ +

+Inline escape: \*[CODE] +

+ +

+When you invoke the macro CODE or insert +\*[CODE] into running text, mom switches to +a +fixed-width font +(Courier, by default) and turns +SMARTQUOTES +off. +

+ +

+If your code includes the backslash character, which is +groff’s escape character, you will have to change the +escape character temporarily to something else with the macro +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. +

+ +

+The correct order for changing the escape character inside +CODE is + + .CODE + .ESC_CHAR character + <code> + .ESC_CHAR \ + .CODE OFF + +Be aware that changing the escape character prevents subsequent +macros, which require that the backslash be the escape character, +from functioning correctly. Therefore, do not introduce any macros +into your CODE block without first restoring the escape character to +its default. +

+ +

+Alternatively, you can enter the backslash character as +\e or \\ (two backslashes), which tells groff +to print a literal backslash. +

+ +

+Note: +.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 +it as well, invoke .CODE with the argument, +SPREAD. If, in addition to breaking the line before CODE +you want a break afterwards, you must supply it manually with +BR +unless what follows immediately is a macro that automatically causes +a break (e.g. +PP). +

+ +

+In all likelihood, if you want the situation described above (i.e. a +break before and after CODE), what you probably want is to use +QUOTE +in conjunction with CODE, like this: +
+ + .QUOTE + .CODE + $ echo "Hello, world" | sed -e 's/Hello,/Goodbye, cruel/' + .QUOTE OFF + +QUOTE takes care of breaking both the text and the code, as well as +indenting the code and offsetting it from +running text +with vertical whitespace. Notice that .CODE, above, has +no corresponding .CODE OFF. .CODE inside a QUOTE +does not require a terminating .CODE OFF, which risks +introducing unwanted vertical whitespace. +

+ +

+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, and smartquotes back to their former state. +

+ +

Using `\*[CODE]` inline

+ +

+\*[CODE] invokes .CODE, allowing you to +bracket code snippets inline. It does not accept the BR, +BREAK, or SPREAD arguments. It is most useful +for short snippets, as in the following example. +
+ + \*[CODE]apropos\*[CODE X] and \*[CODE]man -k\*[CODE X] are identical. + +

+ +

+\*[CODE] does not permit changing the escape +character, so \e or a doubled backslash must be used. +Furthermore, if your code starts with a period, you must enter it as +“\&.”. +
+ + Registers are created with the \*[CODE]\&.nr\*[CODE X] request. + +

+ +

CODE and punctuation

+ +

+.CODE OFF automatically inserts a word space into +running text. If your CODE block is to be followed by punctuation +with the parameters of +running text, +you must terminate the block with “\c” and +enter the punctuation at the beginning of the next input line. If +the punctuation mark is a period or an apostrophe, you must precede +it with +“\&”. +
+ + ...for example, + .CODE + echo "Hello, world" | sed -e 's/Hello,/Goodbye, cruel/'\c + .CODE OFF + \&. As this demonstrates... + +Use of \*[CODE] inline does not require +the \c, however periods and apostrophes after +\*[CODE X] still need to be introduced +with \&, as in this example: +
+ + ...append the unit of measure \*[CODE]p\*[CODE OFF]\&. New sentence... + +

+ + +

CODE control macros and defaults

+ +

Family/Font/Colour
Size

+ +

1. Family/font/colour

+ +

+See +Arguments to the control macros. +
+The following CODE control macros may also be +grouped +using CODE_STYLE. +

+ +.CODE_FAMILY default = Courier +.CODE_FONT default = roman; see Note +.CODE_COLOR default = black + +Note: Unlike other control macros, CODE_FONT sets the code font for both +PRINTSTYLE TYPESET and PRINTSTYLE TYPEWRITE. + +

+ +

2. Size

+ +

+CODE_SIZE works a little differently from the other _SIZE macros +(see Arguments to the control +macros). The argument you pass it is a percentage of the +prevailing document point size. It does not require a prepended +plus (+) or minus (-) sign, nor an appended +percent sign (%). Thus, if you want the point size of your CODE font to be +90% of the prevailing document point size, you enter: +
+ + .CODE_SIZE 90 + +Fixed-width fonts have notoriously whimsical +x-heights, +meaning that they frequently look bigger (or, in some cases, +smaller) than the type surrounding them, even if they’re +technically the same point size. CODE_SIZE lets you choose a +percentage of the prevailing point size for your fixed-width +CODE font so it doesn’t look gangly or minuscule in relation +to the type around it. All invocations of .CODE or +\*[CODE] will use this size, so that if you +decide to change the prevailing point size of your document, the +CODE font will be scaled proportionally. +

+ +

+ + + +

Nested lists

+ +

Tag: LIST
Tag: ITEM
LIST control macros and defaults

+ +

+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 organising. I can’t + seem to get everything done I want. + o an hour’s worth of exercise + o time to prepare at least one healthy + meal per day + o reading time + o work on mom + o writing + - changes from publisher + - current novel + o a couple of hours at the piano + +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. +

+ +

+If +QUAD CENTER +is in effect when LIST is invoked, the list is set quad left but +centred on the page as a block, based on the longest line of list +text. Equally, if QUAD RIGHT in in effect, the list is +set flush left but quadded right as a block. If you want a centred +or right-quadded list in an otherwise left-quadded or justified +document, simply invoke .QUAD <direction> +before the list and reset the quad afterwards. Do not use +CENTER +or +RIGHT. +

+ +

+Note: +Mom centres lists over the entire line length, disregarding +IB +if it is in effect. If there are lines in the list that exceed +the margins of IB, they must be broken manually with +.BR if you wish to keep them within the indented margins. +

+ +

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

+ + + +

LIST

+ +

+ +

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

+ +

+There are a lot of arguments (be sure to side-scroll through them +all, above), so I’ll discuss them one at a time here. +

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-numeraled LIST is going to have. Mom requires this +information in order to align roman numerals sensibly, and will +abort—with a message — if you don’t provide it. +(For setting roman numeral and digit lists with the enumerators +aligned flush right—the default is flush left—see +PAD_LIST_DIGITS.) +

+ +

+A roman-numeraled 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 VARIABLE <character> lets +you choose different enumerators for the items in a list. +<character> is the widest enumerator to +be used. Thus, if you have a list enumerated by both bullets +and em-dashes, you’d set it up with +
+ + .LIST VARIABLE \[em] + +and select the enumerator you want with +
+ + .ITEM \[em] + +or +
+ + .ITEM \[bu] + +If your enumerator contains spaces, you must enclose the +<character> argument in both LIST and ITEM in +double-quotes, e.g. +
+ + .LIST VARIABLE "\*[UP 1p]\[bu]\*[DOWN 1p]" + .ITEM "\*[UP 1p]\[bu]\*[DOWN 1p]" + +

+ +

+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 + +Some useful special groff characters you might want to pass to +USER are: + + \[sq] - square box + \[rh] - pointing hand + \[->] - right arrow + \[rA] - right double arrow + \[OK] - checkmark + +The size and vertical positioning of special characters may be +adjusted with +inline escapes +in the argument passed to USER. For example, to raise the position +of \[sq] slightly, you might do + + .LIST USER "\*[UP .25p]\[sq]\*[DOWN .25p]" + or + .LIST USER \v'-.25p'\[sq]\v'.25p' + +

+ +

+The argument PLAIN initializes a list with no enumerator. +

+ +

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

+ +

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

+ +

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

+ +

ITEM

+ +

+Macro: ITEM [<enumerator>] [<space>] +

+• The argument to <space> requires a +unit of measure +

+ +

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

+ +

+If you’ve chosen the VARIABLE argument when +invoking LIST, ITEM must be followed by an enumerator character. +

+ +

+If you give ITEM a space argument, either by itself or after a +variable enumerator character, the item will be spaced by the amount +of the argument. +

+ +

+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 and defaults

+ +

+LIST control macros may not be +grouped. +

+ +

Indenting lists (SHIFT_LIST)
Resetting an initialized list’s enumerator (RESET_LIST)
Padding digit enumerators (PAD_LIST_DIGITS)

+ +

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. + • List 1 item + • List 1 item + - List 2 item + - List 2 item + • List 1 item + • List 1 item + Lorem ipsum dolor sit amet, consetetur sadipscing elitr, + sed diam nonumy eirmod tempor invidunt ut labore. + +

+ +

2. Resetting an initialized list’s enumerator – RESET_LIST

+ +

+In nested lists, if your choice of 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: + • take care of the dog + a) walk every day + b) brush once a week + - trim around the eyes every fourth brushing + - don’t forget to check nails + • feed the cat + d) soft food on Mon., Wed. and Fri. + e) dry food on Tues., Thurs. and Sat. + f) canned tuna on Sunday + +

+ +

+The alpha-enumerated items under “Feed the cat” +would be normally a), b), c), but we want d), e), f). The +solution is to reset the second .LIST alpha’s +enumerator—before the first .ITEM—with +the macro RESET_LIST. +

+ +

+With no argument, .RESET_LIST resets an incrementing +enumerator to 1, A, a, I or i depending on the style of enumerator. +If you pass .RESET_LIST a +numeric argument, +it represents the starting position for an incrementing enumerator. In +the example above, .RESET_LIST 4 starts the second +alpha-ed list at d). +

+ +

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 – prepend numbers to output lines

+ +

Macro: NUMBER_LINES +
- Line numbering control (off/suspend, resume)
Control macros and defaults +
- Line numbering control macros for quotes and blockquotes

+ +

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

numbers every line of paragraph text; line-numbering is + suspended for all other document processing tags (like + docheaders, epigraphs, headings, quotes, etc.) and special + pages (covers, endotes, bibliographies, etc.); be aware, + though, that if you turn + docheaders + off (with + DOCHEADER OFF) + and create your own docheader, mom + will line-number your custom docheader, so turn + line numbering on afterwards +
doesn’t touch your line length; line numbers are hung + outside your current left margin (as set with + L_MARGIN, + PAGE + or + DOC_LEFT_MARGIN), + regardless of any indents that may be active +
separates line numbers from running text by two + figure spaces. +

+ +

+Mom expects that +QUOTEs +and +BLOCKQUOTEs +will not be line-numbered, however control macros are provided to +enable line numbering for either. +See +Line numbering control macros for quotes and blockquotes. +

+ + + +

NUMBER_LINES

+ +

+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 +Footnotes by linenumber +for instructions on line-numbered footnotes, and +ENDNOTE_MARKER_STYLE LINE +for instructions on line-numbered endnotes.) +

+ +

+Note: +Do not use NUMBER_LINES inside +QUOTE +or +BLOCKQUOTE. +By default, mom expects that quotes and blockquotes will not be +line numbered. If you wish to enable line numbering for them, you +must invoke +NUMBER_QUOTE_LINES +or +NUMBER_BLOCKQUOTE_LINES. +

+ + +

+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. The optional arguments <which lines to number> +and <gutter> 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. +

+ +

+For example, if you want mom to number output lines using her defaults, + + .NUMBER_LINES 1 + +will prepend the number, 1, to the next output line and number all +subsequent output lines sequentially. +

+ +

+If you want only every five lines numbered, pass mom the optional +<which lines to number> argument, like this: + + .NUMBER_LINES 1 5 + +

+ +

+GOTCHA! +The argument to <which lines to number> instructs +mom to number only 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 want line number 1 to be numbered, you have +to invoke .NUMBER_LINES 1 1 before the +first output line you want numbered, then study your output +copy and determine where best to insert the following in your +input text: +
+ + .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 in your input text. +

+ +

+The optional argument, <gutter>, tells mom how much +space to put between the line numbers and the running text. +<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. + +

+ +

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

+ +

Off/suspend, resume

+ +

+After initializing line numbering, you can suspend it, with the +option to resume, using +
+ + .NUMBER_LINES OFF + +(or END, QUIT, X, etc). +

+ +

To resume line numbering: +
+ + .NUMBER_LINES RESUME + +When you resume, the line number will be the next in sequence +from where you left off. If that is not what you want—say +you want to reset the line number to 1—re-invoke +.NUMBER_LINES with whatever arguments are needed for the +desired result. +

+ +

+Additional notes: +

In document processing, you may invoke + .NUMBER_LINES either before or after + .START. Mom doesn’t care. +
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. +
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. + +
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. +
Mom (groff, actually), only numbers + lines to the left of running text. For aesthetic + reason, therefore, the use of line numbering when setting a + document in columns is discouraged. However, should you wish + to number lines when setting in columns, make sure the + gutter(s) + between columns is wide enough to leave room for the numbers. +

+ +

NUMBER_LINES control macros and defaults

+ +

Family/font/size/colour
Reset line numbering after COLLATE
Line numbering control for quotes and blockquotes +

+ +

1. Family/font/size/colour

+ +

+See +Arguments to the control macros. +
+The following NUMBER_LINES control macros may also be +grouped +using LINENUMBER_STYLE. +

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

+ +

2. Reset line numbering after COLLATE

+ +

+After +COLLATE, +line numbering continues from where it left off. If you would like +each chapter or major document section to begin its line numbering +at “1”, invoke + + .NUMBER_LINES_PER_SECTION + +after +.NUMBER_LINES. +

+ +

3. Line numbering control macros for QUOTE and BLOCKQUOTE

+ +

• Including QUOTEs and BLOCKQUOTEs in the line numbering scheme

+ +

+If you’d like mom to number lines in a +QUOTE +or +BLOCKQUOTE +as part of the same order and sequence as paragraph text, +invoke + + .NUMBER_QUOTE_LINES + +or + + .NUMBER_BLOCKQUOTE_LINES + +either before or after NUMBER_LINES. Both behave identically with +respect to the affected macro (i.e. QUOTE or BLOCKQUOTE). +

+ +

• Selectively enabling line numbering for QUOTEs and BLOCKQUOTEs

+ +

+If you’d like to enable line numbering selectively for quotes +and blockquotes only, invoke .NUMBER_QUOTE_LINES +or .NUMBER_BLOCKQUOTE_LINES first, followed by +.NUMBER_LINES <n>, where <n> +is the first line number of the quote or blockquote. Afterwards, +enter your QUOTE or BLOCKQUOTE. When the quote or blockquote +is finished (i.e. after .QUOTE OFF or +.BLOCKQUOTE OFF), turn line numbering off. Each +subsequent quote or blockquote you want line numbered requires +only .NUMBER_LINES <n> (with a corresponding +.NUMBER_LINES OFF) until you turn NUMBER_QUOTE_LINES or +NUMBER_BLOCKQUOTE_LINES off. +

+ +

+Here’s a recipe where the first line number of quotes starts +repeatedly at “1”. + + <running text> + .NUMBER_QUOTE_LINES + .NUMBER_LINES 1 + .QUOTE + <text of quote> + .QUOTE OFF + .NUMBER_LINES OFF + <further running text> + .NUMBER_LINES 1 + .QUOTE + <text of quote> + .QUOTE OFF + .NUMBER_LINES OFF + <further running text> + +

+ +

• Changing the line number gutter for QUOTEs and BLOCKQUOTEs

+ +

+Owing to groff’s restriction on accepting only the figure +space as the line number +gutter’s +unit of measure, it is not possible for line numbers in quotes +or blockquotes to hang outside a document’s overall left +margin and be reliably flush with the line numbers of paragraph +text. Consequently, line numbers in quotes or blockquotes hang +to the left of the quote, separated by the currently active +gutter for NUMBER_LINES. +

+ +

+If you’d like to change the line number gutter for quotes +or blockquotes, invoke .NUMBER_QUOTE_LINES or +.NUMBER_BLOCKQUOTE_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 3 + +With the above, line numbers in quotes (and only quotes) will have +a gutter of 3 figure spaces. +

+ +

• Silently increment line numbers during QUOTE and BLOCKQUOTE

+ +

+If you’ve asked mom not to line number quotes or blockquotes, +but would like line numbering to continue while they’re +being output (as opposed to mom’s default behaviour of +suspending incrementing of line numbers during the output of +quotes and blockquotes), invoke + + .NUMBER_QUOTE_LINES SILENT + +or + + .NUMBER_BLOCKQUOTE_LINES SILENT + +With these, mom continues to increment line numbers while quotes +or blockquotes are being output, but the line numbers won’t +appear in the output copy. +

+ +

+Once having turned NUMBER_QUOTE_LINES or NUMBER_BLOCKQUOTE_LINES on, +you may disable them with + + .NUMBER_QUOTE_LINES OFF + +or + + .NUMBER_BLOCKQUOTE_LINES OFF + +

+ +

+ + + +

Footnotes

+ +

Footnote behaviour +
- Footnote markers and punctuation in the running text
Tag: FOOTNOTE
Footnote control macros and defaults

+ +

+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, +required whenever your +FOOTNOTE_MARKER_STYLE +is either STAR [star/dagger footnotes] or +NUMBER [superscript numbers].) +

+ +

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

+ +

+Note: +See +refer.html +for information on using footnotes with the refer +bibliographic database. +

+ +

Footnote behaviour

+ +

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

+ +

+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. When +shimming +is enabled, the amount of whitespace +may vary slightly from page to page depending on the number of lines +in the footnotes. Mom tries for a nice balance between too little +whitespace and too much, but when push comes to shove, she’ll +usually opt for ample over cramped. The last lines of footnotes are +always flush with the document’s bottom margin. +

+ +

+When +flex-spacing +is enabled, the distance between the last line of text and the +first footnote is always the same. +

+ +

+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 OFF, QUIT, +END, X, 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 a page and the page has some footnotes on it, mom +may simply not have room to set any text under the head (normally, +she insists on having room for at least one line of text beneath +a head). In such an instance, mom will either set the head, with +nothing under it but footnotes, or transfer the head to the next +page. Either way, you’ll have a gaping hole at the bottom +of the page. It’s a sort of typographic Catch-22, and can +only be resolved by you, the writer or formatter of the document, +adjusting the type on the offending page so as to circumvent the +problem. +

+ +

Footnote markers and punctuation in the running text

+ +

“Fill” modes – JUSTIFY, or QUAD LEFT | CENTER | RIGHT
“No-fill” modes – LEFT, CENTER, RIGHT

+ +

1. “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 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. +

+ +

2. “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 OFF, QUIT, +END, X, etc) an additional argument: +BREAK or BR. +

+ +

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

+ +

Example 1

+ +.LEFT +A line of text\c +.FOOTNOTE +A footnote line +.FOOTNOTE OFF +that carries on after the footnote. + +

+ +

Example 2

+ +.LEFT +A line of text\c +.FOOTNOTE +A footnote line +.FOOTNOTE OFF BREAK +that doesn’t carry on after the footnote. + +

+ +

+Example 1, on output, produces +
+ + A line of text* that carries on after the footnote. + +whereas Example 2 produces + + 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. +

+ + + +

FOOTNOTE

+ +

+Tag: FOOTNOTE <toggle> [ BREAK | BR ] [ INDENT LEFT | RIGHT | BOTH <indent value> ] +

+ +

+• <indent value> requires a unit of measure +
+See HYPER-IMPORTANT NOTE. +

+ +

+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 OFF, +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 and defaults

+ +

Family/font/size/colour/lead/quad
Footnote markers – on or off
Footnote marker style – star+dagger or numbered +
- Left padding of footnote numbers
Footnotes by line number +
- FOOTNOTE_LINENUMBER_BRACKETS
- FOOTNOTE_LINENUMBER_SEPARATOR
- FOOTNOTES_RUN_ON – line-numbered footnotes only
Reset footnote number – set footnote marker number to 1
Inter-footnote spacing
Footnote rule – on or off
Footnote rule length – length of footnote separator rule
Footnote rule weight – weight of footnote separator rule
Adjust vertical position of footnote separator rule

+ +

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

+ +

+See +Arguments to the control macros. +
+The following FOOTNOTE control macros may also be +grouped +using FOOTNOTE_STYLE. +

+ +.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 OFF, +QUIT, END, 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.) +

+ +

+If your +PRINTSTYLE +is TYPEWRITE and you would prefer that the footnotes +themselves not use superscript numbers, you may pass +.FOOTNOTE_MARKER_STYLE NUMBER an additional argument: +NO_SUPERSCRIPT. While the marker in the text will still +be superscript, the footnotes themselves will be identified with +normal-sized, base aligned numbers, surrounded by parentheses. +

+ +

Left padding of footnote numbers

+ +

+When footnote numbering is enabled, in order to ensure that the +left margin of footnote text aligns regardless of the footnote +number, you sometimes have to pad the footnote numbers. This will +be the case any time the footnote numbers change from 9 to 10 on +the same page, or from 99 to 100. Consider this scenario: +
+ + ⁹ Footnote text + ¹⁰ Footnote text + ¹¹ Footnote text + +As you can see, the left margins of the footnotes are not aligned. +

+ +

+In order to correct this, use the macro +.FOOTNOTE_NUMBER_PLACEHOLDERS, which takes a single +argument: the number of placeholders in the longer digit. For +example, placed at an appropriate point in your input file, +.FOOTNOTE_NUMBER_PLACEHOLDERS 2 causes the above +example to come out like this: +
+ + ⁹ Footnote text + ¹⁰ Footnote text + ¹¹ Footnote text + +Given the impossibility of knowing in advance when the number of +placeholders required for footnote numbers will change, you must +study your output file to determine where to insert this +macro into your input file. +

+ +

+Obviously, mom does not provide a default for +.FOOTNOTE_NUMBER_PLACEHOLDERS. +

+ +

+Note: +.FOOTNOTE_NUMBER_PLACEHOLDERS affects both superscript +footnote numbers, and, in +PRINTSTYLE TYPEWRITE, +the normal, base-aligned numbers surrounded by parentheses that you +get with +.FOOTNOTE_MARKER_STYLE NUMBER NO_SUPERSCRIPT. +

+ +

4. Footnotes by line number – FOOTNOTE_MARKER_STYLE LINE

+ +

+FOOTNOTE_MARKER_STYLE with the argument, 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 the terminating \c, +at the appropriate place in running text. Input lines after the +footnote has been terminated (e.g. with +.FOOTNOTE OFF) are entered normally. +

+ +

+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 the terminating \c); 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). +

+ +

+The behaviour of line-numbered footnotes can be controlled with the +macros: +
+FOOTNOTE_LINENUMBER_BRACKETS +
+FOOTNOTE_LINENUMBER_SEPARATOR +
+FOOTNOTES_RUN_ON +

+ +

• FOOTNOTE_LINENUMBER_BRACKETS

+ +

+Mom, by default, surrounds footnote line numbers with 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. +

+ +

Thus, for example, either +
+ + .FOOTNOTE_LINENUMBER_BRACKETS PARENS + +or +
+ + .FOOTNOTE_LINENUMBER_BRACKETS ( + +will surround footnote line numbers with round brackets. +

+ +

• FOOTNOTE_LINENUMBER_SEPARATOR

+ +

+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 any space after the separator. Hence, if you want space +(you probably do), you must make the space part of the argument you +pass to FOOTNOTE_LINENUMBER_SEPARATOR. For example, to get a colon +separator with a space after it, you’d do +
+ + .FOOTNOTE_LINENUMBER_SEPARATOR ": " + +

+ +

• FOOTNOTES_RUN_ON

+ +

+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. each +beginning on a new line. Rather, each footnote is separated from +the footnote before it by horizontal space in the running line, so +that the footnotes on any given page form a continuous block, like +lines in a paragraph. +

+ +

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

+ +

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

+ +

6. Inter-footnote spacing – FOOTNOTE_SPACING

+ +

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

+ +

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

+ +

+Note: +If you’re using footnotes for references generated from the +refer database (see +refer.html), +correct MLA style requires a full linespace between footnotes, which +you can accomplish with .FOOTNOTE_SPACING 1v. +

+ +

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

+ +

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

+ +

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

+ +

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

+ +

+Note: +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. +

+ +

+ + + +

Endnotes

+ +

Endnotes behaviour +
- Endnotes and columnar documents
Tag: ENDNOTE
Macro: ENDNOTES—tell mom to output endnotes
ENDNOTES control macros and defaults

+ +

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

+ +

Example

+ + ...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 or SUPERSCRIPT (both of which mark +endnotes references in +running text +with superscript numbers). When the marker style is +LINE, you must not use the \c +escape. +

+ +

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

+ +

When your ENDNOTE_MARKER_STYLE is NUMBER or + SUPERSCRIPT, endnotes are always numbered + incrementally, starting at “1”. +
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. +

+ +

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

+ +

+Note: +See +refer.html +for information on using endnotes with the refer +bibliographic database. +

+ +

Endnotes 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 head, +“ENDNOTES”. Subsequently, for each section in a +collated +document (e.g. chapters in a book), she identifies the section in bold +type, flush left and underscored, followed by one-half linespace. +Endnotes pertaining to the section are output underneath, identified +by superscript numbers. The text of the endnotes themselves is +indented to the right of the numbers. +

+ +

+Note: +The one-half linespace between section identifiers and the endnotes +themselves, plus the need to group identifiers and endnotes sensibly, +means that mom cannot guarantee perfectly aligned bottom margins. +This is an unavoidable consequence of the structure of endnotes. +

+ +

+Of course, all the defaults, as well as the overall style of the +endnotes pages, 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. +

+ +

Endnotes and columnar documents

+ +

+If your document is set in columns (see +COLUMNS), +mom gives you the option to have endnotes appear in either +the column format or set to the full page width. See +ENDNOTES_NO_COLUMNS. +

+ + + +

ENDNOTE

+ +

+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 or SUPERSCRIPT (mom’s +default is NUMBER unless you have +ENDNOTE_REFS +enabled, in which case it’s SUPERSCRIPT), 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 for footnotes, which apply equally to +endnotes, +here). +

+ +

+If your ENDNOTE_MARKER_STYLE is LINE, do not use the \c +escape, and enter the line after .ENDNOTE OFF normally, +ie at your text editor’s left margin. +

+ + + +

ENDNOTES

+ +

+Macro: 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. +

+ +

ENDNOTES control macros and defaults

+ +

+Important: +Endnotes control macros must always be invoked prior to the first +instance of +.ENDNOTE. +

+ +

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

+ +

General endnotes style control +
Pagination of endnotes +
Header/footer control +
Endnotes header (first-page title) control +
Endnotes document-identification string control +
- Document-identification string(s)
- Document-identification string control macros and defaults
Endnotes referencing style +
- Endnote marker style – by numbers in the text, or by line number +
- Endnote numbering control macros and defaults
- Endnote numbering alignment

+ +

1. General endnotes page style control

+ +

• Base family/font/quad

+ +

+See +Arguments to the control macros. +
+The following ENDNOTE control macros may also be +grouped +using ENDNOTE_STYLE. +

+ +.ENDNOTE_FAMILY default = prevailing document family; default is Times Roman +.ENDNOTE_FONT default = roman +.ENDNOTE_QUAD* default = justified + +*Note: ENDNOTE_QUAD must be set to either L (LEFT) or J (JUSTIFIED); + R (RIGHT) and C (CENTER) will not work. + +

+ + + +

• Base 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). +

+ + + +

• Leading

+ +

+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 the prevailing document leading (16 by default), 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. +

+ + + +

• Spacing between endnotes

+ +

+Macro: ENDNOTE_SPACING <space to insert between endnotes> +

+• Requires a unit of measure +

+ +

+If you’d like some whitespace between endnotes, just invoke +ENDNOTE_SPACING with the amount of space you want, e.g. +
+ + .ENDNOTE_SPACING 6p + +which inserts 6 points of lead between endnotes. Be aware, though, +that inserting space between endnotes means that the bottoms of +endnotes pages will most likely not align. +

+ +

+Mom’s default is not to insert any whitespace between endnotes. +

+ + + +

• 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, END, X...). +

+ + + +

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

+ + + +

• Inter-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. +

+ + + +

• 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 ENDNOTES_NO_COLUMNS +for each separate collated document. +

+ +

2. Pagination of endnotes

+ + + +

• 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

+ +

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

+ +

+However, if you set ENDNOTES_FIRST_PAGENUMBER in collated documents +in which the endnotes are output after each section (chapter, +article, etc), you have to reset every section’s first page +number after +COLLATE +and before +START +with +PAGENUMBER. +

+ + + +

• 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 during endnotes output

+ +

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

+ +

3. Header/footer control

+ +

• Modifying what goes in the endnotes header/footer

+ +

+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, invoke +
+ + .HEADER_CENTER "Endnotes" + +or + + .FOOTER_CENTER "Endnotes" + +prior to invoking .ENDNOTES. +

+ +

+Note: +If your +DOCTYPE +is CHAPTER, you must also invoke +ENDNOTES_HEADER_CENTER +for the ENDNOTES_HEADER_CENTER to appear. +

+ +

• Header/footer centre string when doctype is CHAPTER

+ +

+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, END, +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. +

+ +

4. Endnotes header (first-page title) control

+ + + +

• Header (first-page title) string

+ +

+Macro: ENDNOTES_HEADER_STRING "<title to print at the top of endnotes>" +

+ +

+Alias: ENDNOTE_STRING (for compatibility with older documents) +

+ +

+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 .ENDNOTES_HEADER_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 .ENDNOTES_HEADER_STRING +with a blank argument (either two double-quotes side by +side—""—or no argument at all). +

+ + + +

• Header (first-page title) control macros and defaults

+ +

+See +Arguments to the control macros. +
+The following ENDNOTES_HEADER control macros may also be +grouped +using ENDNOTES_HEADER_STYLE. +

+ +

+Please note that “_HEADER_”, here, refers to the title +that appears at the top of the first endnotes page, not to the page +headers of subsequent endnotes pages. + +.ENDNOTES_HEADER_FAMILY default = prevailing document family +.ENDNOTES_HEADER_FONT default = bold +.ENDNOTES_HEADER_SIZE* default = +1 +.ENDNOTES_HEADER_QUAD default = centred +.ENDNOTES_HEADER_COLOR default = black + +*Relative to the size of the endnotes text (set with ENDNOTE_PT_SIZE) + +

+ +

+Note: For compatibility with older documents, these macros are aliased +as .ENDNOTE_STRING_<SPEC>, e.g. .ENDNOTE_STRING_FAMILY. +

+ + + +

• Header (first-page title) placement

+ +

+Macro: ENDNOTES_HEADER_V_POS <distance from top of page> +

+ +

+• Argument requires a unit of measure +

+ +

+Alias: ENDNOTE_STRING_ADVANCE (for compatibility with older documents) +

+ +

+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 .ENDNOTES_HEADER_V_POS 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: +
+ + .ENDNOTES_HEADER_V_POS 1.5i + +

+ + + +

• Header (first-page title) underscoring

+ +

+Macro: ENDNOTES_HEADER_UNDERSCORE [DOUBLE] [<underscore weight> [<underscore gap> [<distance between double rules]]] | <none> | <anything> +

+ +

+Alias: ENDNOTES_HEADER_UNDERLINE. +(For compatibility with older documents, also +aliased as ENDNOTE_STRING_UNDERSCORE and +ENDNOTE_STRING_UNDERLINE.) +

+ +

+• The argument +<underscore weight> +must not have the +unit of measure, +p, +appended to it; all other arguments require a unit of measure +

+ +

+Invoked without an argument, .ENDNOTES_HEADER_UNDERSCORE +will place a single rule underneath the endnotes page title. Invoked +with the argument, DOUBLE, ENDNOTES_HEADER_UNDERSCORE will +double-underscore the title. Invoked with any other non-numeric +argument, (e.g. OFF, NO, X, etc.) the macro disables +underscoring of the title. +

+ +

+In addition, you can use ENDNOTES_HEADER_UNDERSCORE to control the +weight of the underscore rule(s), the gap between the title and the +underscore, and, in the case of double-underscores, the distance +between the two rules. +

+ +

+Some examples: +
+ + .ENDNOTES_HEADER_UNDERSCORE 1 + - turn underscoring on; set the rule weight to 1 point + + .ENDNOTES_HEADER_UNDERSCORE 1 3p + - turn underscoring on; set the rule weight to 1 point; set + the gap between the title and the underscore to 3 points + + .ENDNOTES_HEADER_UNDERSCORE DOUBLE .75 3p + - turn double-underscoring on; set the rule weight to 3/4 of + a point; set the gap between the title and the upper + underscore to 3 points; leave the gap between the upper + and the lower underscore at the default + + .ENDNOTES_HEADER_UNDERSCORE DOUBLE 1.5 1.5p 1.5p + - turn double-underscoring on; set the rule weight to 1-1/2 + points; set the gap between the title and the upper + underscore to 1-1/2 points; set the gap between the upper + and the lower underscore to 1-1/2 points + +Note, from the above, that in all instances, underscoring (single +or double) is enabled whenever ENDNOTES_HEADER_UNDERSCORE is used in +this way. +

+ +

+By default, mom double-underscores the title if your +PRINTSTYLE +is TYPEWRITE. +

+ + + +

• Header (first-page title) capitalization

+ +

+Macro: ENDNOTES_HEADER_CAPS toggle +

+ +

+Alias: ENDNOTE_STRING_CAPS (for compatibility with older documents) +

+ +

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

+ +

+If you’re generating a table of contents, you may want the +endnotes pages title to be in caps, but the toc entry in caps/lower +case. If the argument to +ENDNOTES_HEADER_STRING +is in caps/lower case and ENDNOTES_HEADER_CAPS is on, this is exactly +what will happen. +

+ +

+Mom’s default is to capitalize the endnotes pages title string. +

+ + + +

5. Endnotes document-identification title control

+ +

• Document-identification title string(s)

+ +

+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, simply invoke .ENDNOTE_TITLE prior to +START +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. +

+ + + +

• Document-identification string control macros and defaults

+ +

+See +Arguments to the control macros. +
+The following ENDNOTE_TITLE_STYLE control macros may also be +grouped +using ENDNOTE_TITLE_STYLE_STYLE. +

+ +.ENDNOTE_TITLE_FAMILY default = prevailing document family; default is Times Roman +.ENDNOTE_TITLE_FONT default = bold +.ENDNOTE_TITLE_SIZE* default = 0 +.ENDNOTE_TITLE_COLOR default = black +.ENDNOTE_TITLE_QUAD default = left +.ENDNOTE_TITLE_CAPS +.ENDNOTE_TITLE_SMALLCAPS +.ENDNOTE_TITLE_UNDERSCORE default = single underscore + +*Relative to the size of the endnotes text (set with ENDNOTE_PT_SIZE) + +

+ + + +

6. Endnotes referencing style

+ +

• Endnote marker style

+ +

+Macro: ENDNOTE_MARKER_STYLE LINE | NUMBER | SUPERSCRIPT +

+ +

+• Argument: LINE +By default, mom places superscript numbers in +running text +to identify endnotes. However, if you have +linenumbering +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 by line ranges. If +what you want is a single line number, you need only invoke +.ENDNOTE at the appropriate place in running +text without the terminating \c. Input lines +after the endnote has been terminated (e.g. with .ENDNOTE +OFF) must begin at the left margin. +

+ +

+(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 the terminating \c). Mom is smart enough +to figure out that where .ENDNOTE is invoked represents +the terminating line number. +

+ +

+Note: +By default, mom reserves a fixed amount of space, equal to 8 +placeholders, for the linenumbers of linenumbered endnotes. Within +that space, the numbers are flush right with each other. The +reserved space is enough to print a range of linenumbers of the form +[nnnn-nnnn], but may be more than you need. +

+ +

+The goal with linenumbered endnotes is to ensure that the longest +linenumber or range of lines is flush with the left margin of the +page. Adjusting the reserved space is done with the macro +ENDNOTE_NUMBERS_ALIGN, +and the rules for getting it right are simple. +

+ +

+If your document runs to less than 100 lines, invoke +
+ + .ENDNOTE_NUMBERS_ALIGN RIGHT 0 + +If your document has between 100 and 999 lines +
+ + .ENDNOTE_NUMBERS_ALIGN RIGHT 1 + +If your document has between 1000 and 9999 lines +
+ + .ENDNOTE_NUMBERS_ALIGN RIGHT 2 + +etc. +

+ +

+• Argument: NUMBER +With the argument NUMBER, mom places superscript numbers +in running text, but identifies endnotes in the endnotes section +of your document with normal-sized, base-aligned numbers. +

+ +

+• Argument: SUPERSCRIPT +With the argument SUPERSCRIPT, mom places superscript +numbers in running text, and identifies endnotes in the endnotes +section of your document with superscript numbers as well. This is +mom’s default. +

+ +

+Note: +By default, mom reserves a fixed amount of space, equal to 2 +placeholders, for the superscript numbers identifying endnotes in +the endnotes section of your document. Within that space, the +numbers are flush right with each other. +

+ +

+If you need less space (the total number of endnotes is less than 10) or +more (the total number of endnotes is greater than 99), use the +macro +ENDNOTE_NUMBERS_ALIGN, +to set the desired amount of reserved space, e.g. +
+ + .ENDNOTE_NUMBERS_ALIGN RIGHT 1 + +or +
+ + .ENDNOTE_NUMBERS_ALIGN RIGHT 3 + +

+ +

• Spacing between line-numbered endnotes and the endnote text

+ +

+Macro: ENDNOTE_LINENUMBER_GAP <size of gap> +

+ +

+• Requires a unit of measure +

+ +

+When your +ENDNOTE_MARKER_STYLE +is LINE, mom, by default, inserts a space equal to +1/2-en +between the linenumber and the text of an endnote. For aesthetic +reasons, you may want to change the size of the gap, which is done +with the macro ENDNOTE_LINENUMBER_GAP. +

+ +

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

+ +

• Brackets around endnote line numbers

+ +

+Macro: ENDNOTE_LINENUMBER_BRACKETS PARENS | SQUARE | BRACES | ( | [ | { +

+ +

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

+ +

• Separator after endnote line numbers instead of brackets

+ +

+Macro: ENDNOTE_LINENUMBER_SEPARATOR <character> +

+ +

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

+ +

+ENDNOTE_LINENUMBER_SEPARATOR takes as its single argument the +separator you want. (If the argument contains spaces, don’t +forget to enclose the argument in double-quotes.) The separator +can be composed of any valid groff character, or any combination of +characters. For example, to get a colon separator after the line +number in line-numbered endnotes, you’d do +
+ + .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 a document. +

+ +Numbered endnotes +.ENDNOTE_NUMBER_FAMILY default = prevailing document family; default Times Roman +.ENDNOTE_NUMBER_FONT default = bold +.ENDNOTE_NUMBER_SIZE* default = 0 +Linenumbered endnotes +.ENDNOTE_LINENUMBER_FAMILY default = prevailing document family; default Times Roman +.ENDNOTE_LINENUMBER_FONT default = bold +.ENDNOTE_LINENUMBER_SIZE* default = 0 + +*Relative to the size of the endnotes text (set with ENDNOTE_PT_SIZE) + +

+ +

• Endnote numbering alignment

+ +

+By default, when your +ENDNOTE_MARKER_STYLE +is NUMBER, 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. + +If you wish to change either the alignment or the number of +placeholders, the macro to use is ENDNOTE_NUMBERS_ALIGN. +

+ + + +

+Macro: ENDNOTE_NUMBERS_ALIGN LEFT | RIGHT <number of placeholders> +

+ +

+ENDNOTE_NUMBERS_ALIGN determines how endnote numbers are aligned. If you invoke +
+ + .ENDNOTE_NUMBERS_ALIGN RIGHT 2 + +the periods (dots) after the numbers will align, 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. + +If you invoke + + .ENDNOTE_NUMBERS_ALIGN LEFT 2 + +the first digits of the numbers will line up flush left, 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. + +The argument <number of placeholders> represents +the maximum size of the numbers, expressed as the number of +digits in the largest number. Numbers in the range 0-9 require +1 placeholder; in the range 10-99, 2 placeholders; in the range +100-999 3 placeholders, and so on. +

+ +

+Therefore, if you have fewer than ten endnotes, +
+ + .ENDNOTE_NUMBERS_ALIGN RIGHT 1 + +would ensure proper right alignment of endnote numbers. +

+ +

+Mom’s default for endnote number alignment is to align the +numbers right to two placeholders. +

+ +

+Note: +ENDNOTE_NUMBERS_ALIGN can also be used to establish the alignment +and number of placeholders when your +ENDNOTE_MARKER_STYLE +is SUPERSCRIPT. Furthermore, it can be used to establish +the number of placeholders to reserve when your ENDNOTE_MARKER_STYLE +is LINE, even though, in such an instance, the numbers +themselves are always aligned right. See +here +for examples. +

+ +

+ + + +

Margin notes

+ +

Margin notes behaviour +
- Adjusting the vertical position of margin notes
Macro: MN_INIT – set margin notes parameters
Tag: MN

+ +

+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. +MN_INIT may be called before or after +START. +

+ +

+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 centre 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 +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, successfully begun on a page, runs +past your bottom margin (or the last line before footnotes begin), +the margin note will “flow” onto the next page. If +it is a “left” margin note, it will continue in the +left margin. If it is a “right” margin note, it will +continue in the right margin. +

+ +

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

+ +

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) and +\!.RLD +(to raise it). + +The \! must precede the macros, or they +won’t have any effect. +

+ + + +

MN_INIT

+ +

+Macro: MN_INIT <arguments> (see list) +

+ +

Argument list:

+ + +RAGGED | SYMMETRIC +<L_WIDTH> <value> +<R_WIDTH> <value> +<GUTTER> <value> +<FONTSTYLE> <value> +<SIZE> <value> +<LEAD> <value> +<COLOR> <value> +<HY> <value> + + +

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

+ +

+The arguments may be entered in any order, and since the list is +long, use of the backslash character ( \ ) to put each on +a separate line is recommended, e.g. +
+ + .MN_INIT \ + SYMMETRIC \ + L_WIDTH 4P \ + SIZE 8 \ + LEAD 9 \ + HY 14 + +All arguments are optional, but since mom requires you to run +MN_INIT before entering margin notes, you should, at a minimum, set +the RAGGED or SYMMETRIC parameter. +You will almost certainly want to set L_WIDTH, R_WIDTH, +SIZE and LEAD as well. +

+ +

`RAGGED | SYMMETRIC`

+ +

+If the argument RAGGED is given, both left and +right margin notes will be flush left. If the argument +SYMMETRIC is given, left margin notes will be set flush +right, and right margin notes 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, 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.) +

+ +

`L_WIDTH <value>`

+ +

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

+ +

`R_WIDTH <value>`

+ +

+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 <value>`

+ +

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

+ +

`FONTSTYLE <value>`

+ +

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

+ +

`SIZE <value>`

+ +

+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 <value>`

+ +

+The +leading +of margin notes. <LEAD> takes +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 as paragraph +text (i.e. the document’s base leading). +

+ +

`COLOR <value>`

+ +

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

+ +

`HY <value>`

+ +

+<value> is a digit telling groff how you want margin +notes hyphenated. +
+ + 0 = do not hyphenate + 1 = hyphenate without restrictions + 2 = do not hyphenate the last word on the page + 4 = do not hyphenate the last two characters of a word + 8 = do not hyphenate the first two characters of a word + +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). +

+ + + +

MN

+ +

+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 OFF, +QUIT, END, X, etc) exits the +current margin note. +

+ +

+ + + + + +

Document termination string

+ +

Tag: FINIS
FINIS control macros +

+ +

+The use of FINIS is optional. If you invoke it at the end of a +document (before +.ENDNOTES, +.BIBLIOGRAPHY +or +.TOC) +mom deposits the word, END, centred after a blank line, +beneath the last line of the document. END is enclosed +between +em-dashes, +like this: +
+ + ...and they all lived happily ever after. + + — END — + +If there is insufficient room for FINIS on the last page of a +document, mom will alert you on stderr. +

+ +

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

+ +

FINIS

+ +

+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, +.BIBLIOGRAPHY +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 + +

+ + + +

Finis control macros

+ +

+Since FINIS is only used once in a document, it has few control +macros. It is expected that you will make changes to style +parameters such as family, font, and size with +inline escapes +in the FINIS string itself (see below). +

+ +

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, +
+ + .FINIS_STRING "" + +mom will still print the em-dashes when 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 “initialized”) colour changes the colour +of both the FINIS string and the em-dashes that surround it. If you +use the +inline escape, +\*[<colourname>], +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). +

+ + + +

Removing the dashes around FINIS

+ +

+If you don’t want the dashes around the FINIS string, you can +remove them with +
+ + .FINIS_NO_DASHES + +

+ +

+ + + + + + + + +

Back to Table of Contents

Top

Next: Graphics, floats, and preprocessor support

+ +

+ + + diff --git a/contrib/mom/momdoc/docprocessing.html b/contrib/mom/momdoc/docprocessing.html new file mode 100644 index 0000000..4d09553 --- /dev/null +++ b/contrib/mom/momdoc/docprocessing.html @@ -0,0 +1,4420 @@ + + + + + + + + + Mom -- Document Processing, Introduction and Setup + + + + + + + +

+ + + + + + + +

Back to Table of Contents

Next: The document element tags

+ +

Document processing with mom

+ +

+
+

Initiate document processing

The START macro

Establishing type and formatting
parameters before START

Behaviour of the typesetting macros before START +
- Including (sourcing) style sheets and files
- Initializing colours

Adjust linespacing to fill pages +
- DOC_LEAD_ADJUST
- SHIM – get document leading back on track +
  - Automatic shimming (headings, etc)
Setting documents in columns +
- COLUMNS
- Marking the first page column start position +
  - COL_MARK
- Breaking columns manually +
  - COL_NEXT and COL_BREAK

Changing basic type and formatting
parameters after START

Behaviour of the typesetting macros during document processing
Changing document-wide typesetting parameters after START +
- Post-START global style change macros +
  - DOC_LEFT_MARGIN
  - DOC_RIGHT_MARGIN
  - DOC_LINE_LENGTH
  - DOC_FAMILY
  - DOC_PT_SIZE
  - DOC_LEAD
  - DOC_LEAD_ADJUST
  - DOC_QUAD

Terminating a document

+ +

+ + + +

Introduction to document processing

+ +

+Document processing with mom uses markup tags to identify document elements +such as headings, paragraphs, blockquotes, 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 metadata about the document itself (title, +subtitle, author, etc.). Next, you tell mom what kind of document +you’re creating (e.g. a chapter, letter, abstract, etc...) and +what kind of output you want (typeset, typewritten, draft-style, +etc) — essentially, templates. Thirdly, you make as many +or as few changes to the templates as you wish; in other words, +create a style sheet. Lastly, you invoke the +START +macro. Voilà! You’re ready to write. +

+ + + +

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 elsewhere in the +documentation, so just in case: +

the paper size is 8.5x11 inches
the left and right margins are 1-inch
the top and bottom margins for document text are plus/minus + visually 1-inch +
pages are numbered; the number appears centred, at the + bottom, surrounded by hyphens (e.g. -6- ) +
the first page of a document begins with a + document header +
subsequent pages have + page headers + with a rule underneath +

+ + + +

Vertical whitespace management

+ +

Macro: SHIM
Macro: NO_SHIM
Macro: FLEX
Macro: NO_FLEX

+ + +

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

+ +

+Mom offers two modes of operation for ensuring flush bottom margins: +shimming and flex-spacing. Shimming means that mom nudges the +next line after a significant break in running text back onto the +baseline grid +(e.g. after the insertion of a graphic). Flex-spacing means that any +vertical whitespace remaining between the end of running text and +the bottom margin is distributed equally at logical points on the +page. +

+ +

+Mom uses the +leading +of running text (the “document leading”) that’s in effect +at the start of running text on each page +to establish the grid and space document elements such as heads or +blockquotes so that they adhere to it. (Prior to invoking +START, +the document leading is set with the +typesetting macro +LS, +afterwards with the +document control macro +DOC_LEAD.) +

+ +

+What this means is that documents whose paragraphs are not separated +by whitespace and which do not contain graphics or +pre-processor material +will fill the page completely to the bottom margin. +However, if your paragraphs are spaced, or if there are any leading +changes on a page, or if graphics or pre-processor material are +inserted, it’s very likely the bottom margins will hang +unless shimming or flex-spacing is enabled. +

+ +

Shimming vs. flex-spacing

+ +

+Shimming is mom’s default mode of operation. She applies it +automatically before headings, around quotes and blockquotes, and +beneath +floats +and +pre-processor material. +In addition, the +SHIM +macro can be inserted into a document at any point to make sure +the text following falls on the baseline grid. +

+ +

+This mode of operation works well in documents whose paragraphs are +not spaced. Deviations from the baseline grid, usually +caused by floats or pre-processor material, are corrected +immediately. If the shimming results in slightly unbalanced +whitespace around them, it can easily be remedied by passing the +ADJUST argument to the appropriate macro. +

+ +

+If you do not want mom shimming automatically, +NO_SHIM +turns shimming off globally and suppresses the SHIM macro. If you +want to disable shimming only for a particular float or +pre-processor, the NO_SHIM argument may be given to the +appropriate macro. +

+ +

+Flex-spacing kicks in automatically whenever you turn shimming +off. In other words, if you want a document flex-spaced, +.NO_SHIM is how you achieve it. If, in addition to not +shimming, you don’t want mom flex-spacing either, +NO_FLEX +lets you disable it, too. +

+ +

+Flex-spacing differs from shimming in that mom doesn’t +correct deviations from the baseline grid. Rather, she distributes +whitespace left at the bottom of the page equally in appropriate +places. Like shimming, flex-spacing is automatically applied +before heads, after floats and pre-processor material, and around +quotes and blockquotes. Like shimming, flex-spacing can be +disabled for individual floats or pre-processor material with the +NO_FLEX flag. +

+ +

+In addition, you can use the +FLEX +macro to insert flex-spacing yourself into the document, which you +will almost certainly want to do if your paragraphs are spaced. +This is because paragraphs are not flex-spaced. Typographically, +the ideal for spaced paragraphs is that the space between them +remain constant. Paradoxically, the only way to achieve flush +bottom margins, or to correct excessive flex-spacing before a +heading, is by adding flex-space between the paragraphs. This +requires human judgment, and mom does not presume to decide for you. +

+ +

+Shimming and flex-spacing are mutually exclusive. If the one is +active, the other isn’t unless you have disabled both. This means +that you cannot use the FLEX macro when shimming is enabled, or the +SHIM macro when flex-spacing is enabled. Mom will issue a warning +if you do. +

+ +

+The choice of whether to use shimming or flex-spacing depends on +whether or not your paragraphs are spaced. In a document with +indented, non-spaced paragraphs, shimming and flex-spacing produce +nearly the same result, with shimming winning by an aesthetic hair. +In documents with spaced paragraphs, flex-spacing is the only way to +achieve flush bottom margins. +

+ + + +

SHIM

+ +

+Macro: SHIM +

+ +

+When shimming is enabled, which it is by default, the SHIM macro +allows you to nudge the line following it back onto the baseline +grid. In documents with non-spaced paragraphs, this prevents +the bottom margins from hanging. +

+ +

+Mom herself automatically applies shimming +

before headings
around quotes and blockquotes
after PDF images, tables, pic diagrams, equations, and floats

+ +

+You may sometimes find the amount of space generated by +SHIM looks too big, whether inserted manually into a +document or as a result of automatic shimming. +The situation occurs when the amount of shimming applied +comes close to the leading currently in effect, making it seem as if +there’s one linespace too much whitespace. +

+ +

+The solution is simply to add .SPACE -1v or +.RLD 1v to the document immediately after +.SHIM. (Both .SPACE -1v and +.RLD 1v back up by one linespace.) +

+ +

NO_SHIM

+ +

+Macro: NO_SHIM <none> | <anything> +

+ +

+NO_SHIM, without an argument, disables automatic shimming, +suppresses the SHIM macro, and enables flex-spacing. +

+ +

+NO_SHIM with any argument (e.g. OFF, QUIT, +END, X, etc) re-enables shimming if it has +been disabled and disables flex-spacing. +

+ + + +

FLEX

+ +

+Macro: FLEX [ FORCE ] +

+ +

+When flex-spacing is enabled, the FLEX macro inserts flexible +vertical whitespace into a document. The amount of flex-space is +determined from any extra whitespace at the bottom of a page divided +by the number of flex points on the same page. +

+ +

+If flex-spacing is enabled, mom herself automatically applies +flex-spacing +

before headings
around quotes and blockquotes
after PDF images, tables, pic diagrams, equations, and floats

+ +

+Near the bottom of some pages, you may find that +floated +or +pre-processor material, +including images, or a single line of text afterwards, is not flush +with the bottom margin. This is a result of mom flex-spacing +after such material but not before. The solution to is +insert .FLEX immediately beforehand. +

+ +

+There are some instances where mom inhibits flex-spacing, notably +after outputting floated material deferred from one page to the +next. Introducing FLEX by itself in these instances—say, +before a head or paragraph—will not have any effect; you must +pass FLEX the FORCE argument. +

+ +

+Important note on flex-spacing policy:
+Mom disables flex-spacing on +

the last page or column of a document, before the Table of Contents, + Endnotes, Bibliography, and/or any “Lists of...” +
the page preceding a + COLLATE +
the page preceding a + NEWPAGE + or + BLANKPAGE +
the column preceding a + COL_NEXT + or + COL_BREAK +

+ +

+If this is not what you want, insert +.NO_FLEX OFF +before the first flex-space point on the affected page or in the +affected column. +

+ +

+Flex-spacing is also disabled for any page or column where +insufficient room at or near the bottom causes a +HEADING +or +table +to be moved to the top of the next page. These situations cannot +be harmonized with flex-spacing except by adjusting your layout +to prevent them. You may try re-enabling flex-spacing for the +page (.NO_FLEX OFF) and manually inserting +flex-spaces at appropriate points, but the original whitespace is +usually large enough that re-distributing it merely changes +one layout gaffe into another. +

+ +

+Very occasionally you may notice that a document element (spaced +paragraph, floated material, pre-processor material, or a PDF image) +near the bottom of page has also caused mom to disable flex-spacing +for that page. This occurs when the document element following it +is a +spaced paragraph. +

+ +

+It is typographically acceptable for there to be space between +insertions in running text (e.g. an image) and the bottom margin when +the next page begins with a paragraph. If you’d like to +nudge the insertion a little closer to the bottom margin—not +all the way; that isn’t possible without pushing it to the +next page and disrupting subsequent flex-spacing—insert a +small amount of space beforehand with +SP. +Do not, in these cases, use the ADJUST +argument (for example to +PDF_IMAGE.) +

+ +

+In the case of a spaced paragraph itself near the bottom of the page +causing a break, re-enabling flex-spacing +(.NO_FLEX OFF) at an appropriate place in your input +file will resolve the issue, provided there is at least one +flex-point on the page. If not, add one or more. +

+ +

NO_FLEX

+ +

+Macro: NO_FLEX <none> | <anything> +

+ +

+NO_FLEX, without an argument, disables automatic flex-spacing +and suppresses the FLEX macro. If, in addition to NO_FLEX, NO_SHIM +has also been given, your document will be neither flex-spaced nor +shimmed. +

+ +

+NO_FLEX with any argument (e.g. OFF, QUIT, +END, X, etc) re-enables flex-spacing if it has +been disabled. +

+ +

+ + + +

Preliminary 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, headings, +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 +

to be draft 7, revision 39;
to use the DEFAULT template;
to print as draft-style output (instead of final-copy output);
to be typeset, in Helvetica, 12 on 14, + rag-right; +
to have footers + instead of + headers; +
to use a single asterisk for + author linebreaks. +

+ +

+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 (metadata). The reference macros are: +

TITLE
SUBTITLE
AUTHOR
CHAPTER – chapter number
CHAPTER_TITLE
DRAFT – draft number
REVISION – revision number

COPYRIGHT – only used on cover pages
MISC – only used on cover pages
DOCTITLE
COVERTITLE
DOC_COVERTITLE
PDF_TITLE

+ +

+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”, and they’re essentially templates. +

PRINTSTYLE—typeset or typewritten
DOCTYPE—the type of document (default, chapter, user-defined, letter, slide)
COPYSTYLE—draft or final copy

+ +

+Mom has defaults for DOCTYPE and COPYSTYLE; if they’re what +you want, you don’t need to include them. 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 reasonable defaults for every document element +and tag, 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 +control macros. +This is the stylesheet section of a document, and +must come after the +PRINTSTYLE +directive. Failure to observe this condition will result in +PRINTSTYLE overriding your 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 \"ie 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. +

+ +

+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 \"ie 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 (metadata)

+ +

+The reference macros give mom the metadata 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

+ +

TITLE – title of a story, article, etc
DOCTITLE – title of a book, or any collated document
SUBTITLE
AUTHOR
CHAPTER – the chapter number +
- CHAPTER_STRING – “Chapter”, “CHAPTER”, “Chapître”, etc
CHAPTER_TITLE
DRAFT +
- DRAFT_STRING – “Draft”, “DRAFT”, “Jet”, etc
REVISION +
- REVISION_STRING – “Revision”, “Rev.”, “Révision”, etc
COPYRIGHT
MISC
COVERTITLE – frontispiece, title page, etc
DOC_COVERTITLE – book cover, collated document cover, etc
PDF_TITLE – window title for PDF viewers
TOC_HEADING – single, non-pagenumbered line of text in table of contents

+ + + +

TITLE

+ +

+Macro: TITLE [COVER | DOC_COVER] "<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”. +

+ +

+If the optional argument, COVER or DOC_COVER, +is given to TITLE, the remaining string arguments represent the +title 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 titles appear on the document cover, the cover +(“title”) page, and in the document header. For +example, +
+ + .TITLE DOC_COVER "Collected Essays" + .TITLE COVER "The Meming of Meaning" + .TITLE "LOL Cat Corruption" + .AUTHOR "D. Rawkins" + .DOC_COVER TITLE AUTHOR + .COVER TITLE + .START + +creates a document cover with “Collected Essays” and the +author, a cover page with “The Meming of Meaning”, +and a docheader title, “LOL Cat Corruption” at the top +of the essay. +

+ +

+Alternatively, you can use the macros +DOC_COVERTITLE +and +COVERTITLE +to accomplish the same thing. +

+ +

Table of Contents exceptions

+Except for standalone documents (i.e. non-collated documents such +as essays), the TITLE string appears as an entry in the Table of +Contents. If you would like a document section not to appear in the +Table of Contents (e.g. the copyright page), invoke the macro +.NO_TOC_ENTRY after .TITLE. +

+ + + + +

DOCUMENT TITLE

+ +

+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), and appears +

+ +

as the window title in PDF viewers (e.g. Okular or Evince)
in the initial rightmost position of page headers in the document

+ +

+Moreover, DOCTITLE does not appear in the +PDF outline, +as its presence in window title would make it redundant. +

+ +

+The doctitle string can be caps or caps/lower-case; it’s up to +you. In +PRINTSTYLE TYPESET, +by default, the doctitle in +page headers +is 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. +

+ + + +

SUBTITLE

+ +

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

+ + + +

AUTHOR

+ +

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

+ + + +

CHAPTER

+ +

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

+ + + +

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

+ +

+If you would like a blank chapter string, i.e., you’d like the +chapter number to appear without “Chapter” beforehand, +enter .CHAPTER_STRING "\&". +

+ + + +

CHAPTER_TITLE

+ +

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

+ + + +

DRAFT

+ +

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

+ +

+If you wanted only “Trial run” to appear, entering +.DRAFT without an argument as well as +.DRAFT_STRING "Trial run" is how you’d do it. +

+ +

+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 invocations of .DRAFT and +.DRAFT_STRING will result in mom using her default, which +is to print “Draft <number>”. +

+ + + +

REVISION

+ +

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

+ + + +

COPYRIGHT

+ +

+Macro: COPYRIGHT [COVER | DOC_COVER] "<copyright info>" +

+ +

+• Argument must be enclosed in double-quotes +

+ +

+The required argument 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. +

+ +

+The optional argument, COVER or DOC_COVER, +should only be used if you have both a doc cover and a cover and want +differing copyright information on each (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 "2010 John Smith and Jane Doe" + .COPYRIGHT COVER "2008 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 +

+ +

+Style parameters for the copyright line may be +entered as individual macros or +grouped, +e.g. +
+ + .COPYRIGHT_FAMILY H + .COPYRIGHT_FONT R + .COPYRIGHT_SIZE -2 + +or +
+ + .COPYRIGHT_STYLE \ + FAMILY H \ + FONT R \ + SIZE -2 + +The vertical position of the copyright line may be raised (-) or +lowered (+) with the macro COPYRIGHT_V_ADJUST. For example, to +raise the copyright line by 3 +points, you’d do +
+ + .COPYRIGHT_V_ADJUST -3p + +Alternatively, the COPYRIGHT_STYLE macro may be used with the +argument V_ADJUST: + + .COPYRIGHT_STYLE \ + FAMILY H \ + FONT R \ + SIZE -2 \ + V_ADJUST -3p + +

+ + + +

MISC

+ +

+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, 2010" + +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 +

+ + + +

COVERTITLE & DOC_COVERTITLE

+ +

+Macro: COVERTITLE "<user defined cover page title>" ["<2nd line>" ["<3rd line>" ... ] ] +

+• Arguments must be enclosed in double-quotes +

+ +

+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 or DOC_COVERTITLE is explicitly +passed to +COVER +or +DOC_COVER. +

+ +

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

+ +

+You only require COVERTITLE or DOC_COVERTITLE if they differ from +TITLE. Note that +TITLE +itself has two optional arguments that accomplish the same thing. +

+ +

PDF Title

+ +

+Macro: PDF_TITLE "<pdf viewer window title>" +

+• Argument must be enclosed in double-quotes +

+ +

+Except for +DOCTITLE, +mom does not, by default, provide PDF viewers with a document title. +You may set one, if you like, with PDF_TITLE. +

+ +

TOC heading

+ +

+Macro: TOC_HEADING "<single line TOC heading>" +

+• Argument must be enclosed in double-quotes +

+ +

+Mom generates tables of contents automatically (see +TOC). +You may sometimes want to insert a line of text into the table of +contents without it referring to a page number, for example to +identify a “Part I” and a “Part II.” +

+ +

+Placed before any instance of +START, +TOC_HEADING inserts its text into the table of contents with a +modest amount of whitespace around it to distinguish it easily +from table of contents entries. +

+ +

+The appearance of the heading may be controlled with +the macro +TOC_HEADING_STYLE. +

+ +

+Macro: TOC_HEADING_STYLE "<arguments>" +

+ +

+TOC_HEADING_STYLE controls the look of TOC headings. It is a +“grouping” +style macro with multiple arguments. It is recommended that +you use the backslash character to separate them into individual +lines rather than entering a single, very long line. +

+ +

+TOC_HEADING_STYLE accepts as many or as few arguments as you need: + + FAMILY <family> \ + FONT <font> \ + SIZE <+|-n> \ + COLOR <colorname>* \ + QUAD L | C | R \ + SPACE_ABOVE <n>** \ + SPACE_BENEATH <n>** + + * COLOR must be pre-initialized with +NEWCOLOR +or +XCOLOR. +
+** SPACE_ABOVE and SPACE_BENEATH require a +unit of measure +to be appended to their numeric argument. +

+ +

+For example, if you want your TOC headings to be bold, slightly +larger than the rest of the table of contents, centred, and with +one linespace beforehand, + + FONT B \ + SIZE +.5 \ + QUAD C \ + SPACE_ABOVE 1v + +

+ +

+ See +Arguments to the control macros +for further information about the arguments. Note that +SPACE_ABOVE and SPACE_BENEATH are unique to +TOC_HEADING_STYLE. + +

+ +

+ + + +

The docstyle macros

+ +

+The docstyle macros tell mom what type of document you’re +writing, whether you want the output typeset or “typewritten, +double-spaced”, and whether you want a draft copy (with draft +and revision information in the headers) or a final copy. +

+ +

Docstyle macros

DOCTYPE
PRINTSTYLE – non-optional macro required for document processing +
- Defaults for PRINTSTYLE TYPESET
- Defaults for PRINTSTYLE TYPEWRITE +
  - PRINTSTYLE TYPEWRITE control macros +
    - Family
    - Point size
    - Underlining of italics
COPYSTYLE

+ + + +

DOCTYPE

+ +

+Macro: DOCTYPE DEFAULT | CHAPTER | NAMED "<name>" | LETTER | SLIDES +

+ +

+The arguments DEFAULT, CHAPTER and +NAMED tell mom what to put in the +docheader +and +page headers. +LETTER and SLIDES tells her you want to write +a letter or create slides. +

+ +

+Mom’s default DOCTYPE is DEFAULT. If that’s +what you want, you don’t have to give a DOCTYPE command. +

+ +

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

+ +

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

+ +

+Note: version 2.1 change +
+DOCTYPE NAMED "string" no longer accepts a colour +argument after "string". Setting the colour +of the string is now done with DOCTYPE_COLOR +<color>. Default underscoring of +"string" in the docheader and on covers +has been removed. Use DOCTYPE_UNDERSCORE, +DOC_COVER_DOCTYPE_UNDERSCORE and/or +COVER_DOCTYPE_UNDERSCORE to re-enable it. All three take +the same arguments listed in the +Underscore style, rule weight +section of +Arguments to the control macros. +

+ +

+LETTER tells mom you’re writing a letter. See the +section +Writing Letters +for instructions on using mom to format letters. +

+ +

Slides

+ +

+PDF slides are a special kind of mom document, formatted for viewing +in a PDF reader’s presentation mode. In most respects, they +behave identically to the other document types. Key differences +are: +

headers, footers, and pagination are disabled by default
type is set +QUAD CENTER +by default
+flex-spacing +and +shimming +are disabled by default; shimming may +be re-enabled (with NO_SHIM OFF), but not flex-spacing
there’s no need for +PRINTSTYLE

+ +

+DOCTYPE SLIDES takes up to five optional arguments, which come +immediately after SLIDES. They may be entered in any order. +
+ + DOCTYPE SLIDES \ + ASPECT 4:3 | 16:9 \ + HEADER "left" "centre" "right" \ + FOOTER "left" "centre" "right" \ + TRANSITION "<slide transition effect>" (mode + parameters) \ + PAUSE "<text reveal effect>" (mode + parameters) + +For convenience, you many want to enter each argument on a single +line as shown above; all but the last must be terminated by a +backslash. +

+ +

Aspect

+ +

+Slides can be formatted for one of two aspect ratios common to +monitors and screens: 4:3 and 16:9. The default is 16:9. + + 4:3 16:9 + media size: 11" x 8.25" media size: 11" x 8.1875" + left/right margins: 36 points left/right margins: 36 points + top margin: 90 points top margin: 80 points + bottom margin: 84 points bottom margin: 72 points + base text size: 16 points base text size: 14 points + autoleading: 6 points, adjusted autoleading: 4 points, adjusted + (header/footer size: -3 points) (header/footer size: -2 points) + +Note that both media sizes fit on either A4 or US LETTER papersizes. +

+ +

Headers, footers, and pagination

+ +

+If you want a header, footer, or both for your slides, pass SLIDES +the HEADER and/or FOOTER argument(s). Both +take three additional +string arguments, +which must be enclosed in double-quotes, defining the left, centre, +and right parts of the header/footer. Any parts you want left blank +should be entered as two double-quotes. For example, + + HEADER "" "My slide presentation" "" + +will result in a header with only the centre part. +

+ +

+Normal pagination is disabled for slides. If you want your slides +numbered, the slide number must be given to one of the header/footer +parts with the +inline escape +
+\*[SLIDE#]. For example: + + HEADER "" "My slide presentation" "" \ + FOOTER "" "" "\*[SLIDE#]" + +will give you a centred header with numbering at the bottom right of +the slide. +

+ +

+The overall family, size, and colour of headers may be set with +HEADER_FAMILY, HEADER_SIZE, and HEADER_COLOR. If you request +FOOTERS, you may use the FOOTER_ equivalent of these macros. +If you request both headers and footers, use one or the other but +not both. For example, in a header/footer situation, HEADER_FAMILY +would determine the family for both headers and footers, but if you +attempted to do this + + .HEADER_FAMILY T + .FOOTER_FAMILY H + +FOOTER_FAMILY would take precedence, and your header family would be +“H”. +

+ +

+All other formatting of individual header/footer parts must be +entered as inline escapes inside the double-quotes. If you want, +say, your headers to be red but your footer page numbering to be +black and two points larger, this is how you’d do it: + + .HEADER_COLOR red + .DOCTYPE SLIDES \ + HEADER "" "My slide presentation" "" \ + FOOTER "" "" "\*[black]\*S[+2]\*[SLIDE#]\*S[-2]" + +

+ +

+Note: +Do not use mom’s +\*[SIZE ±n] +inline escape to change point size in the strings +passed to HEADER or FOOTER. Prefer either mom’s +\*S[±n] or groff’s +\s[±n]. +

+ +

Transition

+ +

+“Transition” refers to how new slides appear during a +presentation. The official PDF specification lists a number of modes, +each with a choice of configurable parameters. Modes include Box, +Blinds, Wipe, Fade, and several others. Parameters include things +like duration, dimension, and direction. There are a total of +twelve modes; for each one there are from one to six configurable +parameters. Consult man gropdf(1) for a complete listing +of modes and parameters. +

+ +

+If you pass SLIDES the TRANSITION argument, you must +at a minimum follow it with a mode. Afterwards, you may give as +many or as few parameters as you wish. Parameters are, in order, + + 1. duration + 2. dimension + 3. motion + 4. direction + 5. scale + 6. bool + +You don’t have to fill them all out. If you only need the +first three, that’s all you need to input. If you need the +first and third, enter the second as a period (dot), which is used +any time you want to leave a parameter at its current default or +when it isn’t applicable. For example, if you want a Box +transition that lasts 1 second, filling the screen from the centre +outwards, you’d enter + + TRANSITION "Box 1 . O" + +because Box does not take a “dimension” parameter but it +does take a motion parameter. +

+ +

+Notice that the entire string (mode+parameters) must be enclosed in +double-quotes. +

+ +

+Note: +Not all PDF viewers support all modes. Any that are not supported +are replaced by the “R” mode, which simply replaces one +slide with the next unless the PDF viewer has a different default +transition mode. +

+ +

Pause

+ +

+A “pause” occurs when material on a slide is halted (see +PAUSE), +awaiting a mouse click, PgDown, Next, or the spacebar to reveal +subsequent material. All the same modes and parameters as +TRANSITION may be used. The manner of entering them is +is identical, including that the entire mode+parameter string must +be enclosed in double-quotes. +

+ +

SLIDE MACROS

+ +

+Macro: NEWSLIDE ["<transition mode and parameters>"] +

+ +

+Unless you want material from one slide to flow onto the next, you +need to tell mom when to start a new slide with the macro NEWSLIDE. +Without any arguments, the new slide will appear with the default +TRANSITION you gave to DOCTYPE SLIDES. +

+ +

+If you would like a different transition, you may pass NEWSLIDE a +new mode and associated parameters, following the same rules as the +TRANSITION argument to DOCTYPE. Note that the new effect becomes +the default. If you wish to return to the original transition, you +must give it explicitly to the appropriate NEWSLIDE. +

+ +

+Macro: PAUSE ["<pause mode and parameters>"] +

+ +

+Pauses in slides are accomplished by entering the macro PAUSE at +desired locations in your input file. Subsequent material will be +revealed using the pause mode given to DOCTYPE SLIDES. +

+ +

+If you would like a different mode, you may pass PAUSE a +new mode and associated parameters, following the same rules as the +PAUSE argument to DOCTYPE. +

+ +

+Macro: TRANSITION ["<transition mode and parameters>"] +

+ +

+If for some reason you have material that flows from one slide to +the next and you want the next slide to have a transition +different from the current one, you can tell mom about the new +transition with the macro TRANSITION anywhere prior to the break to +the next slide. +

+ +

Printing slides

+ +

+If you want to print slides as handouts, you have to tell +pdfmom or gropdf, otherwise printing will +stop at the first pause. Simply precede pdfmom or +gropdf with GROPDF_NOSLIDE=1, like this: +
+ + GROPDF_NOSLIDE=1 pdfmom <options> slidefile.mom > slidefile.pdf + + +

+ + + +

PRINTSTYLE

+ +

+Macro: PRINTSTYLE TYPESET | TYPEWRITE [ SINGLESPACE ] +

+ +

+• Required for document processing, except in the case of +slides +
+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”. +

+ +

+Important: +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. +

+ +

+Just as important: +PRINTSTYLE must precede any and all page and style +parameters associated with a document with the exception of +PAPER, which should be placed at the top of your file. +PRINTSTYLE sets up complete templates that include default margins, +family, fonts, point sizes, and so on. Therefore, changes to any +aspect of document style must come afterwards. For example, +
+ + .PAPER A4 + .LS 14 + .QUAD LEFT + .PRINTSTYLE TYPESET + +will not change mom’s default document leading to 14 points, +nor the default justification style (fully justified) to left +justified, whereas +
+ + .PAPER A4 + .PRINTSTYLE TYPESET + .LS 14 + .QUAD LEFT + +will. +

+ +

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

+ +

+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[<size>] +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. +

+ +

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

+ +

PRINTSTYLE 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

+ +

Family

+ +

+If you’d prefer a monospace +family +for PRINTSTYLE TYPEWRITE other than mom’s +default, Courier, you can change it with +.TYPEWRITER_FAMILY <family> (or +.TYPEWRITER_FAM). Since groff ships with only the +Courier family, you will have to install any other monospace family +yourself. See +Adding fonts to +groff. +

+ +

Point size

+ +

+If you’d like a smaller or larger point size for +PRINTSTYLE TYPEWRITE (mom’s default is 12-point), +you can change it with +.TYPEWRITER_SIZE <size>. There’s no need to +add a +unit of measure +to the <size> argument; points is assumed. Be +aware, however, that regardless of point size, mom’s +leading/linespacing for TYPEWRITE is fixed at 24-point +for double-spaced, and 12-point for single-spaced. +

+ +

Underlining of italics

+ +

+In PRINTSTYLE TYPEWRITE, mom, by default, underlines +anything that looks like italics. This includes the +\*[SLANT] +inline escape +for pseudo-italics. (See +UNDERLINE +for a note on how to process TYPEWRITE files that underline +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). +

+ +

+Finally, note that colour is disabled for TYPEWRITE. If +you would like it enabled, for example so PDF links are colourised, +invoke the groff +primitive +'.color' after PRINTSTYLE. +

+ +

+ + + +

COPYSTYLE

+ +

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

Documents start on page 1, whether or not you + request a different starting page number with + PAGENUMBER. +
Page numbers are set in lower case roman numerals.
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. +

+ +

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

It respects the starting page number you give the document.
Page numbers are set in normal (Arabic) digits.
No draft or revision number appears in the page headers.

+ +

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

+ + + +

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

+ +

+ + + +

Establishing typestyle and formatting parameters before START

+ +

+In the third (optional) part of setting up a document (the +stylesheet; 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. +

+ +

Type & formatting parameters before START

Behaviour of the typesetting macros before START +
Including (sourcing) style sheets and files
DOC_LEAD_ADJUST – adjust linespacing to fill pages and align bottom margins
DOCHEADER +
- Docheader control
COLUMNS +
- COL_NEXT
- COL_BREAK

+ +

Behaviour of 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. +

+ +

+Important: +Do not use the macros listed in +Changing document-wide typesetting parameters after START +prior to START; they are exclusively for use afterwards. +

+ +

Meanings

+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 typesetting 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, +HEADING, +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 stylesheet 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 +HEADIING control macros. +
+ + .HEADING_STYLE 1 \ + FAMILY H \ + FONT BI \ + QUAD L \ + NO_UNDERSCORE + +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 +stylesheet is in /home/joe/stylesheets, the above +example would have to look like this: +
+ + .TITLE "Sample Document + .AUTHOR "Joe Blow + .PRINTSTYLE TYPESET + \# + .INCLUDE /home/joe/stylesheets/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. +

+ +

+Note: +INCLUDE is an alias for the groff request .so. If the +sourced file contains material that requires pre-processing (e.g. +a table made with tbl(1) or non-English characters), use +.so rather than INCLUDE and invoke pdfmom thus: +
+ + soelim file.mom | pdfmom [flags] > file.pdf + +soelim only looks for lines that begin with .so, +which furthermore must not have any space between the period and +the “s”. +

+ + + +

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 colourising 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 that colour is disabled if your +PRINTSTYLE +is TYPEWRITE. If you would like it enabled, for example +so PDF links are colourised, invoke the groff +primitive +'.color' after PRINTSTYLE. +

+ +

+Note: +If you plan to have mom generate a +table of contents, +do not embed colour +inline escapes +(\*[<colourname>]) +in the +string arguments +given to any of the +reference macros, +nor in the string arguments given to +HEADING. +Use, rather, the +control macros +mom provides to automatically colourise these elements. +

+ + + +

Adjust linespacing to fill pages and align bottom margins

+ +

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

+ +

+When 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 +that fit on the page coincides perfectly with the bottom margin of +running text. +

+ +

+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 +and you don’t have to invoke it explicitly. +

+ +

+However, 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 ] [ NO_SHIM ] +

+ +

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

+ +

+With .DOCHEADER OFF, it is possible to create your own +custom docheaders (after +START) +using mom’s typesetting macros. It is recommended that if you +do create a custom docheader, you make +.SHIM +the last macro before the first item of your document (for +example, .PP or .HEADING 1. +

+ +

+Note: +You may have tried DOCHEAHER OFF with a distance argument +and discovered that mom will not budge the starting position of the document +from her chosen default location. This is byproduct of +shimming, +which mom always applies before the first line of running text after +the docheader, regardless of which +vertical whitespace management +strategy is in effect. If you encounter the problem, pass +DOCHEADER OFF <distance> +the additional final argument, NO_SHIM. +

+ + + +

Docheader control: How to change the look of docheaders

+ +

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

+ +

Docheader description

+ +

+A typeset docheader has the following characteristics: +

+ + 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, 3 points larger than running text + +

+ +

+Or, 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. Title, subtitle, +author, and document type are what you supply with the +reference macros. +Any you leave out will not appear; mom will compensate: +

+ +

+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 remove or alter +the space with +CHAPTER_TITLE_SPACE_BEFORE. +

+ +

Docheader control

+ +

+With the docheader control macros, you can change the family, +colour, leading, and quad direction of the entire docheader. You can +also set the style parameters for each part individually. Style +parameters include family, font, size, colour, lead, space before, +caps, smallcaps, and underscoring. +

+ +

1. Changes to the whole docheader +
+
2. Part by part changes +
- List of parameters and arguments
- Grouping part/parameter changes – very handy
+
3. Changing or removing the attribution string (“by”)

+ +

1. Changes to the whole docheader

+ +

Change the starting position of the docheader

+ +

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

+ +

Change the quad direction of the docheader

+ +

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

+ +

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

+ +

Change the colour of the entire docheader

+ +

+The default colour for docheaders is black, as you’d expect. +If you wish to change it, use +.DOCHEADER_COLOR <colour>, where + <colour> is a colour pre-initialized with +XCOLOR +or +NEWCOLOR. +

+ +

Change the leading of the entire docheader

+ +

+By default, mom uses the leading in effect for +running text +for docheaders. If you want to increase or +decrease the overall docheader leading, use +.DOCHEADER_LEAD +|-<amount>, where +<amount> is the number of +points +by which to make the adjustment. +

+ +

2. Part by part changes

+ +

+Whenever you want to change the style parameters for any part of +the docheader, simply join the name of the part to the parameter +you wish to change using an underscore, then supply any necessary +arguments. The subtitle double-underlined? No problem. +
+ + .SUBTITLE_UNDERSCORE DOUBLE + +Author in red? +
+ + .AUTHOR_COLOR red + +Title in smallcaps? + + .TITLE_SMALLCAPS + +

+ +

+Note: +Use ATTRIBUTE as the part name for the attribution string +(“by”) that precedes the author, and DOCTYPE +as the name for the string passed to DOCTYPE NAMED "string". +

+ +

List of parameters with arguments

+ +

_FAMILY: + Takes the same argument as FAMILY. +
_FONT: + Takes the same argument as FT. +
_SIZE: + Takes a + or - value relative to the size of + running text. +
_COLOR: + Takes the same argument as COLOR. + Colours should be pre-initialized with + XCOLOR + or + NEWCOLOR. +
_LEAD: + Takes an absolute leading value, i.e. not relative to the + overall leading of the docheader. The leading applies to + multiple lines of type within the same docheader part, e.g. + several authors or a long title that must be split over two + lines. No + unit of measure + is required; + points + is assumed. +
_SPACE: + Takes a numeric value with a + unit of measure + appended to it. The value may be negative. This allows you + to adjust the whitespace before a docheader part, for example + if you want more whitespace between the title and the author. + + Note that TITLE does not have a _SPACE + parameter; use + DOCHEADER_ADVANCE + to move the title further down on the page. + +
_CAPS: + Capitalizes the entire docheader part. No argument is + required. +
_NO_CAPS: + Only used if you need to reverse the sense of _CAPS, as + can sometimes happen when + collating + documents that have differing docheader style requirements. +
_SMALLCAPS: + Set the entire docheader part in smallcaps. No argument is + required. +
_NO_SMALLCAPS: + Only used if you need to reverse the sense of + _SMALLCAPS, as can sometimes happen when + collating + documents that have differing docheader style requirements. +
_UNDERSCORE: + With no argument, underscores the docheader part. With a + single, possibly decimal numeric argument, sets the weight of + the underscore. A second numeric argument to which a + unit of measure + is appended (most likely p) sets the distance + between the baseline and the underscore. + + If the argument DOUBLE is given, double underscores + the docheader part. With a single, possibly decimal numeric + argument afterwards, sets the weight of the underscore rules. + A third numeric argument to which a + unit of measure + is appended (most likely p) sets the distance + between the baseline and the first underscore rule. A fourth + numeric argument to which a unit of measure is appended sets + the distance between the two underscore rules. + + + You may give _UNDERLINE as the parameter instead of + _UNDERSCORE if you prefer. + +
NO_UNDERSCORE: + Only used if you need to reverse the sense of + _UNDERSCORE, as can sometimes happen when + collating + documents that have differing docheader style requirements. +

+ +

Grouping part/parameter changes

+ +

+If you want to change several parameters for a particular docheader +part, you may group the changes together in a single macro by +joining the name of the part to STYLE with an underscore, +for example TITLE_STYLE or AUTHOR_STYLE. +The following demonstrates: + + .CHAPTER_TITLE_STYLE \ + FAMILY T \ + SIZE +4 \ + UNDERSCORE 2 \ + SMALLCAPS + +Notice the use of the backslash character, which is required after +the macro name and all parameters except the last. Grouping reduces +clutter and the finger fatigue caused by entering + + .CHAPTER_TITLE_FAMILY T + .CHAPTER_TITLE_SIZE +4 + .CHAPTER_TITLE_UNDERSCORE 2 + .CHAPTER_TITLE_SMALLCAPS + +

+ +

3. Changing or removing 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. +

+ +

+ + + +

Setting documents in columns

+ +

+Setting documents in columns is easy with mom. All you have to do +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). +

+ + + +

COLUMNS

+ +

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

+ +

Marking the first page column start position

+ +

+If you insert or remove space after the docheader, i.e. immediately after +START +in your input file, mom needs to know where your first column begins +in order to align subsequent columns on the first page. +

+ +

+Macro: COL_MARK +

+ +

+COL_MARK tells mom where the first column after the +docheader begins, in order for the top of subsequent columns on the +first page to be aligned. Note that if you do not manually add +or remove space after the docheader, there is no need to invoke +COL_MARK. +

+ +

+Note: +If you do add or subtract space after the docheader, e.g. with +ALD +or +SP, +and your +unit of measure +is something other than a multiple of “v”, be +sure to follow the spacing command with +SHIM +before entering .COL_MARK unless shimming has been +disabled with +NO_SHIM. +If your document is being flex-spaced, do not use +FLEX. +Rather, disable flex-spacing temporarily with +
+ + .NO_FLEX + .NO_SHIM off + .SHIM + .COL_MARK + +and re-enable it afterwards with + + .NO_SHIM + .NO_FLEX off + +

+ +

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

+ +

+Macro: COL_NEXT +

+ +

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

+ +

+Macro: COL_BREAK +

+ +

+.COL_BREAK is almost the same as .COL_NEXT, +except that instead of breaking and quadding the line preceding it, +mom breaks and spreads it (see +SPREAD). +Use this macro whenever you need to start a new column in the middle +of a paragraph. +

+ +

+Warning: +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 basic type and formatting parameters after START

+ +

Behaviour of the typesetting macros during document processing +
- Effect of specific typesetting macros
Top and bottom margins in document processing
Inserting space at the top of a new page +
- ADD_SPACE

+ +

Behaviour of the typesetting macros during document processing

+ +

+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 or FLEX macro to get mom back + on track when you’re ready to return to the + document’s default leading. + + AUTOLEAD •Invoked before START, sets the overall document + leading as a function of the overall document + point size (i.e. the point size used in paragraphs); + subsequently disabled after START, except for calls + to DOC_PT_SIZE + + •DOC_LEAD before DOC_PT_SIZE cancels the AUTOLEAD + set before START + + •Invoked after START, remains in effect for all + subsequent point size changes made with PT_SIZE, + but does not affect the leading of the document + element tags (e.g. HEADING, PP, QUOTE...), or calls + to DOC_PT_SIZE + + 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. + +

+ +

Inserting space at the top of a new 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 +conjunction with +NEWPAGE. +

+ + + +

ADD_SPACE/RESTORE_SPACE

+ +

+Macro: ADD_SPACE <amount of space> +
+Macro: RESTORE_SPACE +

+ +

+• Requires a unit of measure +

+ +

+If your +DOCTYPE +is DEFAULT, CHAPTER, NAMED, or LETTER, 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 +or +FLEX +macro immediately after ADD_SPACE, which will add the space plus +whatever correction is required by the +vertical whitespace management +strategy in effect. +

+ +

+If your +DOCTYPE +is SLIDES, ADD_SPACE may be used on any slide including the +first to introduce additional white space at the top. +

+ +

RESTORE_SPACE

+ +

+You may sometimes find that mom refuses to respect +SP, +ALD/RLD, +SHIM, +or +FLEX +after the first element (line of text, floated material) output +at the top of a page. Should this happen, insert the macro +RESTORE_SPACE before issuing the spacing command. +

+ + + +

Changing document-wide typesetting parameters after START

+ +

+In the normal course of things, you establish the basic type style +parameters of a document prior to invoking +START, +using the +typesetting macros +(L_MARGIN, FAMILY, PT_SIZE, LS, etc). After START, you must +use the following macros if you wish to make global changes to the +basic type style parameters, for example changing the overall leading or +the justification style. +

+ +

+Important: +Because these macros globally update the chosen parameter, they +should only be used immediately prior to +COLLATE +or, if an occasional effect is desired, +NEWPAGE. +DOC_PT_SIZE, +for example, updates the point size of every page element, including +headers, footers, page numbers, and so on, which is almost certainly +not what you want in the middle of a page. +

+ +

+ + + +

DOC_LEFT_MARGIN

+ +

+Macro: DOC_LEFT_MARGIN <left margin> +

+ +

+• Requires a unit of measure +

+ +

Arguments and behaviour

+ +

the argument is the same as for + L_MARGIN +
changes all left margins, including headers, footers, and page + numbers to the new value +
any document elements that use a left indent calculate + the indent from the new value +
the line length remains the same (i.e., the right margin + shifts when you change the left margin) +

+ + + +

DOC_RIGHT_MARGIN

+ +

+Macro: DOC_RIGHT_MARGIN <right margin> +

+ +

+• Requires a unit of measure +

+ +

Arguments and behaviour

+ +

the argument is the same as for + R_MARGIN +
changes all right margins, including headers, footers, and + page numbers to the new value; +
any document elements that use a right indent calculate + the indent from the new value +

+ + + +

DOC_LINE_LENGTH

+ +

+Macro: DOC_LINE_LENGTH <length> +

+ +

+• Requires a unit of measure +

+ +

Arguments and behaviour

+ +

the argument is the same as for + LL +
exactly equivalent to changing the right margin with + DOC_RIGHT_MARGIN (see + above); +

+ + + +

DOC_FAMILY

+ +

+Macro: DOC_FAMILY <family> +

+ +

Arguments and behaviour

+ +

the argument is the same as for + FAMILY +
globally changes the type family for +
- the docheader
- all document element tags, including footnotes
- headers and/or footers
- line numbering
- page numbering
does not change the family of +
- document cover pages
- cover pages
- endnotes pages
- table of contents
any page elements (e.g. headers page numbers, footnotes) whose + families you wish to remain at their old values must be + reset with the appropriate + control macros +

+ + + +

DOC_PT_SIZE

+ +

+Macro: DOC_PT_SIZE <point size> +

+ +

+• Does not require a unit of measure; points is assumed +

+ +

Arguments and behaviour

+ +

the argument is the same as for + PT_SIZE, + and refers to the point size of type in paragraphs +
all automatic point size changes (heads, quotes, + footnotes, headers, etc.) are affected by the new size; + anything you do not want affected must be reset to + its former value (see the Control Macros section of + the pertinent document element for instructions on + how to do this) +
if + AUTOLEAD + was invoked before START; the value of AUTOLEAD will be used + to update the leading of all document element tags except + FOOTNOTE and EPIGRAPH +

+ + + +

DOC_LEAD

+ +

+Macro: DOC_LEAD <points> [ ADJUST ] +

+ +

+• Does not require a unit of measure; points is assumed +

+ +

Arguments and behaviour

+ +

the argument is the same as for + LS, + and refers to the + leading + of paragraphs +
because paragraphs will have a new leading, the leading and + spacing of most running text is influenced by the new value +
epigraphs and footnotes remain unaffected; + if you wish to change their leading, use + EPIGRAPH_AUTOLEAD + and + FOOTNOTE_AUTOLEAD. +
the optional argument ADJUST performs + leading adjustment as explained in + DOC_LEAD_ADJUST +
if + AUTOLEAD + was invoked before START; the value of that AUTOLEAD will be + cancelled +

+ +

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

+ + + +

DOC_QUAD

+ +

+Macro: DOC_QUAD L | R | C | J +

+ +

Arguments and behaviour

+ +

the arguments are the same as for + QUAD +
affects paragraphs, epigraphs and footnotes; does not + affect blockquotes +

+ +

Terminating a document

+ +

+You need do nothing special to terminate a document. When groff +finishes processing the last +input line +of a file, the page is ejected, subject to whatever routines are +needed to complete it (e.g. printing footnotes or adding the page +number). +

+ +

+It happens sometimes, however, that a last line of +running text, +falling on or very near the bottom of the page, tricks groff into +breaking to a new page before terminating. The result is a blank +page at the end of the formatted document. +

+ +

+The situation is rare, generally occurring only when some additional +macro is required after the input text, e.g. to exit a +list +or terminate a +quote. +To prevent it from ever happening, I recommend getting into the habit +of following the final input line of all your mom files with +.EL. +Depending on the +fill mode +in effect, you may also have to append the “join line” +escape, +\c, to the final line.

+ +

+Thus, for normal text at the end of a paragraph, which is in fill +mode, +
+ + and they all lived happily ever after. + .EL + +or for ending a +LIST +(also in fill mode) + + .ITEM + peaches, pears, plums + .EL + .LIST OFF + +whereas, at the end of a +QUOTE +(which is in nofill mode), + + Shall be lifted\[em]nevermore!\c + .EL + .QUOTE OFF + +Notice that the .EL comes after the last line of input +text, not any macros following. +

+ +

+Note: +\*[B] +cannot be used as a replacement for .EL when terminating +a document. +

+ + + + + + + + +

Back to Table of Contents

Top

Next: The document element tags

+ +

+ + + diff --git a/contrib/mom/momdoc/goodies.html b/contrib/mom/momdoc/goodies.html new file mode 100644 index 0000000..7c39e14 --- /dev/null +++ b/contrib/mom/momdoc/goodies.html @@ -0,0 +1,1785 @@ + + + + + + + + + Mom -- Goodies + + + + + + + +

+ + + + + + + +

Back to Table of Contents

Next: Inline escapes

+ +

Goodies

+ +

+The macros in this section are a collection of useful (and sometimes +nearly indispensable) routines to simplify typesetting. +

+ +

ALIAS – rename macros
CAPS – convert to upper case
CENTER_BLOCK – centre blocks of type with quad intact
ESC_CHAR – change the escape character to something other than a backslash
HANG – hang character(s) outside right margin (inline escape)
LEFT_HANG – hang character(s) outside left margin
SILENT – hide input lines from output
SIZESPECS – get cap-height, x-height and descender depth of a font
SMARTQUOTES – convert typewriter doublequotes to proper doublequotes
STRING – user-definable strings
TRAP – suspend/re-invoke traps
Underscoring/underlining +
- UNDERSCORE – single underscore +
  - Controlling the weight of underscores
  - Colourising underscores
- UNDERSCORE2 – double underscore
- UNDERLINE +
  - \*[UL] – inline escape to underline
Padding +
- PAD – insert equalized whitespace into lines +
  - PAD_MARKER – change/set the marker used with PAD

Leaders +
- \*[LEADER] – inline escape to add leaders to a line
- LEADER_CHARACTER – change/set the leader character
Drop caps +
- DROPCAP – set a drop cap
- Support macros for DROPCAP +
  - DROPCAP_FAMILY – change drop cap family
  - DROPCAP_FONT – change drop cap font
  - DROPCAP_ADJUST – alter size of drop cap
  - DROPCAP_COLOR – change colour of drop cap
  - DROPCAP_GUTTER – change space between drop cap and running text
Superscripts +
- \*[SUP] – inline escape to set superscripts +
  - SUPERSCRIPT_RAISE_AMOUNT (control superscript raise amount
  - \*[CONDSUP] – condensed superscripts
  - \*[EXTSUP] – extended superscripts

+ +

+ + + +

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

+ +

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

+ +

+Tip: +A particularly good candidate for ALIAS is the macro +PT_SIZE. +A more natural name for it 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. +

+ +

+Tip: +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 +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 +quotation marks—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 +" (i.e. the inch-mark/doublequotes key) +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; +>> 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 are 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. 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. + +

+ +

+Note: +\*[LC] must come after a terminating period. +
+ + \*[UC]All work and no play makes Jack a dull boy.\*[LC] + +not + + \*[UC]All work and no play makes Jack a dull boy\*[LC]. + +Conversely, an initial period must come before +\*[UC], or be preceded by \&, like this: +
+ + .\*[UC]start\*[LC] is used to begin document processing. + +or + + \*[UC]\&.start\*[LC] is used to begin document processing. + +Upon output, either will produce +
+ + START is used to begin document processing. + +

+ + + +

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 +\*[<name>]. 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. It’s a good idea to get into the +habit of using groff’s native commenting mechanism, \", immediately following any string definition +in order to avoid spaces you can’t see, like this +
+ + .STRING mw the Montreal/Windsor corridor\" + +

+ +

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

+ +

+Important: +Changing the escape character prevents macros, which require that +the backslash be the escape character, from functioning correctly. +Do not introduce any subsequent macros without first restoring the +escape character to its default. +

+ +

+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> ] [ PREFIX <prefix> ] [ SUFFIX <suffix> ] "<string>" +

+ +

+• <distance below baseline> 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 the upper edge of the underscore 3 points below the +baseline. +

+ +

+Tip: +UNDERSCORE can also be used for strikethrough effects by supplying a +negative value to the distance argument. +

+ +

+PREFIX and SUFFIX allow you to add +non-underscored punctuation (or other glyphs) to the beginning +and/or end of the underscored string. If the argument to either +PREFIX or SUFFIX contains spaces, surround the +argument with double-quotes. For example, the following underscores +the text string but not the surrounding punctuation. +
+ + .UNDERSCORE PREFIX ( SUFFIX .) "Unmonitored monopolies breed high prices and poor products" + +

+ +

+Note: +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. If you need to underscore several lines of type, use +UNDERLINE. +

+ +

+Additional note: +In +nofill modes, +UNDERSCORE causes a break before and after, meaning the underscored +word or phrase will appear as a separate line in your output. If +you wish to embed an underscored word or phrase into non-filled +text, temporarily change to the corresponding fill mode with +QUAD +and insert breaks manually with +BR +as appropriate, reverting to the original nofill mode afterwards. +

+ +

Controlling the weight of 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. +

+ +

+Note: +UNDERSCORE_WEIGHT also sets the weight of +double underscores. +

+ +

Colourising 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 colour. +In other words, assuming your prevailing text colour 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 but the underscore in black. +You can, of course, use this to create rainbow effects if that's +what 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> ] [ PREFIX <prefix> ] [ SUFFIX <suffix> ] "<string>" +

+ +

+• <distance below baseline> +and +<distance between rules> +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). The distance between the two rules +is measured from the bottom edge of the upper rule to the top +edge of the lower one. Be aware that you must give a value for +<distance below baseline> if you want to +use <distance between rules>. +

+ +

+PREFIX and SUFFIX allow you to add +non-underscored punctuation (or other glyphs) to the beginning +and/or end of the double-underscored string. If the argument to +either PREFIX or SUFFIX contains spaces, +surround the argument with double-quotes. For example, the +following double-underscores the text string but not the surrounding +punctuation. +
+ + .UNDERSCORE2 PREFIX ( SUFFIX .) "Unmonitored monopolies breed high prices and poor products" + +The weight (thickness) of double underscores may be controlled with +the macro +UNDERSCORE_WEIGHT +(q.v). +

+ +

+See +here +for advice on colourising double-underscored text. +

+ +

+Note: +In +nofill modes, +UNDERSCORE2 causes a break before and after, meaning the double-underscored +word or phrase will appear as a separate line in your output. If +you wish to embed a double-underscored word or phrase into non-filled +text, temporarily change to the corresponding fill mode with +QUAD +and insert breaks manually with +BR +as appropriate, reverting to the original nofill mode afterwards. +

+ + +

Underline

+ +

+Macro: UNDERLINE toggle +

+ +

+The distinction between underscoring and underlining is that +underscoring is suitable for occasional effects (a word here, +a phrase there), whereas underlining underlines whole passages +of type. Furthermore, you cannot colourise underlining. +There’s a special macro, +UNDERLINE_SPECS, +to control the weight and distance from the baseline of the +underline. +

+ +

+Lastly, files that use UNDERLINE must be processed with +
+ + pdfmom -Tps filename.mom | ps2pdf - filename.pdf + +since groff’s pdf driver does not recognize UNDERLINE. +

+ +

+Note that +PRINTSTYLE TYPEWRITE +uses UNDERLINE to underline italics +and pseudo-italics (SLANT) +by default. The default may be changed (see +Underlining of italics) +but if it's what you want, you must process your document as shown +above. +

+ +

+UNDERLINE is a toggle macro, therefore you invoke it by itself (i.e. +with no argument) to initiate underlining, and with any argument +(OFF, QUIT, END, X, etc) +to turn it off. +

+ +

+Note: +Underlining may also be turned on and off +inline +with the escapes +\*[UL]...\*[ULX]. +

+ +

+Additional note: +In document processing, neither .UNDERLINE nor +\*[UL] persist past the current document element tag. +For example, if you turn underlining on in a paragraph +(.PP), +your next paragraph will not be underlined. +

+ +

UNDERLINE_SPECS

+ +

+The weight of underlining and the distance from the baseline is +set with +
+ + .UNDERLINE_SPECS <weight> <distance> + +The <weight> argument can be expressed in any +unit of measure +you like, but points is the most usual. Mom’s default is 1/2 point +(.5p). The same holds for the <distance> argument; +mom’s default is 1-1/4 points (1.25p). +

+ + + +

INLINE ESCAPE FOR UNDERLINING

+ +

+The macro pair, +.UNDERLINE / +.UNDERLINE OFF, and the inline escapes, +\*[UL] / \*[ULX], are +functionally identical, hence, in +fill +modes +
+ + Which should I heed? + .UNDERLINE + Just do it + .UNDERLINE OFF + or + .UNDERLINE + just say no? + .UNDERLINE OFF + +produces the same result as +
+ + Which should I heed? \*[UL]Just do it\*[ULX] or \*[UL]just say no?\*[ULX] + +In either case, this is a misuse of UNDERLINE. +UNDERSCORE +is preferable. +

+ + + +

Insert equalized whitespace into lines

+ +

+Macro: PAD "<string with pad markers inserted>" [ NOBREAK ] +

+ +

+With PAD, you can insert proportional 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. +

+ +

Example of PAD usage

+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]. +
+ + .LL 30P + .PAD "Date \*[ST1]#\*[ST1X] Signature \*[ST2]###\*[ST2X]" NOBREAK + .ST 1 J + .ST 2 J + .TAB 1 + \*[RULE] + .TN + \*[RULE] + .TQ + +

+ +

+Here’s what the example does: +

Pads the Date/Signature line with a shorter space for Date + (#) and a longer space for Signature + (###), encloses the padded space with string tabs + markers, and outputs the line without advancing on the page. +
Sets the quad for the two string tabs (in this instance, justified). +
Calls the first string tab and draws a rule to its full + length. +
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. +

+ +

+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]" NOBREAK + .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 _ + +

+ +

+Tip: +A particularly useful function of LEADER_CHARACTER is that it can be +used to increase the spacing of mom’s default leaders. This is +done by assigning to LEADER_CHARACTER both the period (dot) and a +space. The technique requires a little low-level groffing: +
+ + .char \[leader] . \" + .LEADER_CHARACTER \[leader] + +The .char +primitive +allows you to define a character called leader, to which +you assign a period and a space. The \", which, in +groff, is used to add non-printing comments to a line, is not +strictly necessary. Its presence here lets you see that +there’s a space after the period. +

+ + + +

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 +

with initial paragraphs (i.e. at the start of the document, + or after + HEADING),
when .DROPCAP comes immediately after .PP,
the + PRINTSTYLE + is TYPESET.

+If these conditions aren’t met, DROPCAP is silently ignored. +

+ +

+Additional note: +If you have dropcaps after +HEADINGs, +you must increase the NEEDS argument to +HEADING_STYLE +to match the number of dropcap lines. For example, assuming +dropcaps that are three lines tall: +
+ + .HEADING_STYLE 1 NEEDS 3 + +

+ +

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

+ +

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, if 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. +

+ + + +

Centre blocks of type

+ +

+Macro: CENTER_BLOCK <toggle> +

+ +

+Blocks of type sometimes need to be centred on the page with their quad +direction (left, centre, right) left intact. The +document processing macros +QUOTE +and +BLOCKQUOTE +take care of this automatically, but there are other situations +where you may want to centre blocks of type. An example might be +left-quadded +nested lists. +

+ +

+Whenever you want to centre a block of type on the page, surround it +with .CENTER_BLOCK/.CENTER_BLOCK OFF (or QUIT, +X, etc). +

+ +

Hanging characters

+
+

+Macro: LEFT_HANG <character> [ <gutter> ] +

+• left-hung characters +

+ +

+Inline: \*[HANG <character>] +

+• right-hung characters +

+ +

+Hung characters, frequently punctuation, fall outside the left or +right margin. Their purpose is usually to fine-tune justification. +Consider the following: +

+ + + + + + + + +

+“Play the man, Master Ridley; we +shall this day light such a candle, +by God's grace, in England, as I +trust shall never be put out.” +

+ +

+“ +
+
+
+
+

+Play the man, Master Ridley; we +shall this day light such a candle, +by God's grace, in England, as I +trust shall never be put out.”

+ +

+In the right hand example, the opening double-quote hangs outside +the left margin, creating a uniform left margin for the text. +

+ +

Left hung characters

+ +

+LEFT_HANG hangs its first argument, the character to be hung, to +the left of the left margin. The optional second argument lets you +specify an amount of space to insert between the hung character and +the text. +

+ +

+Input text after LEFT_HANG must begin with the character to be hung +PLUS a +horizontal motion +corresponding to <gutter> if one was given. +If the hung character is a left double-quote, \[lq] +must be used as the argument to LEFT_HANG and the usual keyboard +double-quote (") entered as the input text so as not to +confuse +SMARTQUOTES +The following example demonstrates: +
+ + .LEFT_HANG \[lq] 1p + "\*[FWD 1p]This line will have its opening double-quote + plus one point of space hung outside the left margin." + +

+ +

+Note that what follows LEFT_HANG must be an input line and therefore +it cannot be used to left-hang a +HEADING +character. +

+ +

+Important: +Versions of mom lower than 2.5_a that included LEFT_HANG required +that the character and its gutter be entered as a single, +concatenated argument, using horizontal motions to establish the +gutter +(e.g. +FWD, +BCK). +Documents created with versions prior to 2.5_a may have to be +updated. +

+ +

Right hung characters

+ +

+The \*[HANG c] inline escape hangs its argument outside +the right margin of justified or quad right copy. The argument may +be a single character, or a single character preceded by a +horizontal motion, effectively establishing a gutter between the +right margin and the hung character: +
+ + This line will have its closing period hung outside + the right margin with a one point gutter\*[HANG \*[FWD 1p].] + +If the hung character is a right double-quote, "\[rq]" +must be used as the argument (that is, the \[rq] +character surrounded by double-quotes). The double-quotes are +required for all special characters of the form +\[name]. +Horizontal motion, if any, must fall inside the double-quotes: +
+ + ...and they all lived happily ever after.\*[HANG "\*[FWD 1p]\[rq]"] + +

+ +

+If the hung character is a hyphen, +\*[HANG -] +must come at the end of an +input line. +This restriction does not apply to other characters, which may come +anywhere in an input line provided that, on output, the line breaks +at the point you introduced the hung character. +

+ +

+For the exceptionally fussy, \*[HANG] may also be used to +improve visual centring; when text is centred, \*[HANG c] +hangs the character to the right of the centred line instead of the +margin. +

+ +

+ + + + + + + + +

Back to Table of Contents

Top

Next: Inline escapes

+ +

+ + + diff --git a/contrib/mom/momdoc/graphical.html b/contrib/mom/momdoc/graphical.html new file mode 100644 index 0000000..0f373b7 --- /dev/null +++ b/contrib/mom/momdoc/graphical.html @@ -0,0 +1,689 @@ + + + + + + + + + Mom -- Graphical Objects + + + + + + + +

+ + + + + + + +

Back to Table of Contents

Next: Document processing

+ +

Graphical objects

+ +

Introduction to graphical objects
Graphical objects behaviour
Order of arguments
Index of graphical objects 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 \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’s 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). 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: +

Objects are drawn from the + baseline + down, including horizontal rules.
Objects begin precisely at the left indent supplied as + an argument to the macro.
Objects are drawn from left to right.
Enclosed objects (boxes, circles) are drawn from the + perimeter inward.
Objects return to their horizontal/vertical point of origin.

+ +

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

the rule weight +
- the single word SOLID may be used in place + of weight if you want boxes or circles filled
the indent from the current left margin at which to begin + the object +
the width of the object if applicable
the depth of the object if applicable
the colour of the object (optional)

+ +

Graphical objects macros

+ +

DRH + – horizontal rules
DRV + – vertical rules
DBX + – box
DCL + – circles or ellipses

+ + + +

Drawing horizontal rules

+ +

+Macro: DRH <none> | <weight> <indent> <width> [<colour>] +

+ +

+• +the argument to <weight> is in +points, +but do not append the +unit of measure, +p +
+• +<indent> +and +<width> +require a unit of measure +
+• +arithmetic expressions to +<indent> +and +<width> +must be surrounded by parentheses +

+ +

+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: +DRH is the only graphical object macro that may be invoked +without arguments. The weight (“thickness”) 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 width, you must, at +a minimum, supply DRH with the arguments weight, +indent (measured from the current left margin) and +width. +

+ +

+Optionally, you may give a color argument. The colour +may be either one defined with +NEWCOLOR, +or a named X-color initialized with +XCOLOR, +or an X-color 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 width + | | + .DRH 1.25 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.25 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 <weight> <indent> <depth> [<colour>] +

+ +

+• +the argument to <weight> is in +points, +but do not append the +unit of measure, +p +
+• +<indent> +and +<depth> +require a unit of measure +
+• +arithmetic expressions to +<indent> +and +<depth> +must be surrounded by parentheses +

+ +

+To draw vertical rules of a specified depth, you must, at +a minimum, supply DRV with the arguments weight, +indent (measured from the current left margin) and +depth. +

+ +

+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 centimetres. 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 right 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 <weight>|SOLID <indent> <width>|FULL_MEASURE <depth> [<color>] +

+ +

+• +the argument to <weight> is in +points, +but do not append the +unit of measure +p +
+• <indent>, +<width>, +and +<depth> +require a unit of measure +
+• +arithmetic expressions to +<indent>, +<width>, +and +<depth> +must be enclosed in parentheses. +

+ +

+To draw boxes you must, at a minimum, supply DBX with the arguments +weight or SOLID, indent, +width or FULL_MEASURE, and depth. +

+ +

+weight is the rule weight of outlined boxes, given in +points but without the +unit of measure +p appended. +

+ +

+If SOLID is given as the first argument, the box is +filled rather than outlined and no weight argument should +be supplied. +

+ +

+indent is measured from the current left margin. If +FULL_MEASURE is given, indent should be set to +“0”. +

+ +

+width is the width of the box with a +unit of measure +appended, caclculated from indent argument. +

+ +

+If FULL_MEASURE is given instead of width, +it circumvents having to calculate the width when left and/or right +indents are in effect; mom draws the box from the current left +margin to the current right margin. When no indents are in effect, +FULL_MEASURE or \n[.l]u—the groff +way of saying “the current line length”—have the +same effect. +

+ +

+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 width + +(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 <weight>|SOLID <indent> <width>|FULL_MEASURE <depth> [<color>] +

+ +

+To draw circles you must, at a minimum, supply DCL with the arguments +weight or SOLID, indent, +width or FULL_MEASURE, and depth. +

+ +

+weight is the rule weight of outlined circles, given in +points but without the unit of measure +unit of measure +p appended. +

+ +

+If SOLID is given as the first argument, the circle is +filled rather than outlined and no weight argument should +be supplied. +

+ +

+indent is measured from the current left margin. If +FULL_MEASURE is given, indent should be set to +“0”. +

+ +

+width is the width of the circle with a +unit of measure +appended, caclculated from indent argument. +

+ +

+If FULL_MEASURE is given instead of width, +it circumvents having to calculate the width when left and/or right +indents are in effect; mom draws the circle from the current left +margin to the current right margin. When no indents are in effect, +FULL_MEASURE or \n[.l]u—the groff +way of saying “the current line length”—have the +same effect. +

+ +

+Say, for example, you want to draw a 1/2 point outline circle that +starts one inch from the current left margin and has the dimensions +12 picas x 6 picas. To do so, you’d invoke .DCL +like this: +
+ + indent depth + | | + .DCL .5 1i 12P 6P + | | + weight width + +(Note that the circle weight argument, which is expressed in points, +must not have the unit of measure p appended to it.) +

+ +

+If you want the same circle, but solid (“filled”) rather +than drawn as an outline: +
+ + .DCL SOLID 1i 12P 6P + +Additionally, if you want the circle green: +
+ + .DCL .5 1i 12P 6P green + +or + + .DCL SOLID 1i 12P 6P green + +

+ + +

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

+ +

+ + + + + + + + +

Back to Table of Contents

Top

Next: Document processing

+ +

+ + + diff --git a/contrib/mom/momdoc/headfootpage.html b/contrib/mom/momdoc/headfootpage.html new file mode 100644 index 0000000..1c11ab1 --- /dev/null +++ b/contrib/mom/momdoc/headfootpage.html @@ -0,0 +1,2341 @@ + + + + + + + + + Mom -- Document processing, page headers/footers and pagination + + + + + + + +

+ + + + + + + +

Back to Table of Contents

Next: Recto/verso printing, collating

+ +

Page headers/footers, pagination

+ +

Introduction – VERY IMPORTANT; read me!
An important note on pagination
General description of headers/footers
Default specs for headers/footers
Vertical placement and spacing of headers/footers

+ +

Managing page headers and footers

HEADERS – on or off
FOOTERS – on or off
FOOTER_ON_FIRST_PAGE

Control macros for headers/footers

Header/footer control macros and defaults +
- Header/footer strings +
  - Using mom’s reserved strings in header/footer definitions (TITLE, AUTHOR, etc.)
- Header/footer style +
  - Global changes
  - Part-by-part changes
- Vertical placement and spacing of headers/footers +
  - HEADER_MARGIN / FOOTER_MARGIN +
    - – Important: FOOTER_MARGIN and bottom margins
- The header/footer separator rule +
  - HEADER_RULE – on or off
  - HEADER_RULE_WEIGHT – weight of the rule
  - HEADER_RULE_GAP – distance of rule from header/footer
  - HEADER_RULE_COLOR – colour of the header/footer rule

User-defined, single string recto/verso headers/footers

HEADER_RECTO, HEADER_VERSO +
- User-defined, single string headers/footers (no recto/verso)
- Padding the header-recto/header-verso string

Headers and footers on the same page

Pagination

Pagination macros
Pagination control macros and defaults

Inserting blank pages into a document

+ +

Managing page headers and footers

+ +

+Note: +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_. +

+ +

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

headers appear in the margin above running text while + footers appear in the margin beneath running text; +
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. +

+ +

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

+ +

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

+ +

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

+ +

+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 by +DOCTYPE, +with the author left, the document title right, and chapter or +document type information in the centre. 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, caps/lower-case, +or smallcaps) 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. 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 running text + +

+ +

+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 +type specs for running text 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, +Typesetting macros during 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 is the counterpart to HEADER_MARGIN, and establishes +the baseline position of footers relative to the bottom edge of the +page. +

+ +

+The distance between headers and the start +of running text can be controlled with the macro +HEADER_GAP, +effectively making HEADER_MARGIN + HEADER_GAP the top margin of +running text unless you give mom a literal top margin (with +T_MARGIN) +or +PAGE, +in which case she ignores HEADER_GAP and begins the running text at +whatever top margin you give. +

+ +

+FOOTER_GAP and +B_MARGIN +work similarly, except they determine where running text ends +on the page. (See +Important – footer margin and bottom margins +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 begins the running text 3 picas +(the HEADER_GAP) beneath that, which means the effective top margin +of the running text is 7-1/2 picas (visually approx. 1 +inch). However, if you give mom a literal top margin (with +T_MARGIN), +she ignores the HEADER_GAP and starts the running text at whatever +top margin you give. +

+ +

+Footers are treated similarly. Mom sets footers 3 picas up from the +bottom of the page, and interrupts the processing of running text 3 +picas (the FOOTER_GAP) above that (again, visually approx. 1 inch). +However, if you give mom a literal bottom margin (with +B_MARGIN), +she ignores the FOOTER_GAP and interrupts the processing of running +text at whatever bottom margin you give. +

+ +

+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

+ +

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

+ +

+Note: +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 it up. +

+ +

Header/footer macros

HEADERS – on or off
FOOTERS – on or off
FOOTER_ON_FIRST_PAGE
User-defined, single string recto/verso headers/footers +
- HEADER_RECTO, HEADER_VERSO +
  - User-defined, single string headers/footers (no recto/verso)
- Using mom’s reserved strings in header/footer definitions + (title, author, etc.) +
HEADERS_AND_FOOTERS – + putting both headers and footers on document pages +
Header and footer control macros

+ + + +

Headers

+ +

+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 +but not the page numbers that normally appear at the bottom of the +page. If you want both headers and footers, you must use the macro +HEADERS_AND_FOOTERS. +

+ +

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

+ + + +

Footers

+ +

+Macro: FOOTERS toggle +

+ +

+Page footers +are off by default. If you want them instead of +headers, +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: If you want both headers and footers, you must use the +macro +HEADERS_AND_FOOTERS. +

+ +

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

+ +

Control macros for headers/footers

+ +

+Virtually every part of headers (and footers; see the note on how +“headers” means “footers” +in the +Introduction +to headers/footers) can be designed to your own specifications. +

+ +

Header/footer control macros and defaults

+ +

Header/footer strings +
- HEADER_LEFT
- HEADER_CENTER +
  - Padding the header-centre string
- HEADER_RIGHT
- Using mom’s reserved strings in header/footer definitions + (e.g. \E*[$TITLE] when you want + the title, \E*[$AUTHOR] when you want the author, etc.) +
- Replacing header-left, centre or right with the page number
- Including the page number in header-left, centre or right
Header/footer style +
- Global changes +
  - HEADER_PLAIN – disable default adjustments to header parts
  - HEADER_FAMILY – family for entire header
  - HEADER_SIZE – size for entire header
  - HEADER_COLOR – colourize the header
- Part-by-part changes +
  - _FAMILY – left, centre or right family
  - _FONT – left, centre or right font
  - _SIZE – left, centre or right size
  - _CAPS – left, centre or right all caps
  - _SMALLCAPS – left, centre or right smallcaps
  - _COLOR – left, centre or right colour
Header/footer vertical placement and spacing +
- HEADER_MARGIN
- HEADER_GAP
Header/footer separator rule +
- HEADER_RULE
- HEADER_RULE_WEIGHT
- HEADER_RULE_GAP
- HEADER_RULE_COLOR

+ + + +

1. 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 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. By invoking +
+ + .HEADER_CENTER_PAD RIGHT 3P + +you can scoot the word "Outline" over three +picas +to the left (because the padding is added onto the right of the +string) so that your head looks nicely spaced out. Invoking +.HEADER_CENTER_PAD with the LEFT argument puts +the padding on the left side of the string so that it scoots +right. +

+ +

+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 +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*[$DOC_TYPE] —the NAMED argument passed to .DOCTYPE + \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, -centre or -right with the page number

+ +

+If you would like to have the current page number appear in the +header-left, -centre, or -right position instead of a text string, +invoke the appropriate macro, above, with the single argument +# (the “number” or “pound” sign). +Do not surround the pound size with double-quotes, as you would +normally do if the argument to .HEADER_CENTER were a +string. For example, +
+ + .HEADER_CENTER # + +(notice, no double-quotes) will print the current page number in the +centre 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, (as +opposed to replacing the string with the page number), 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" + +The header-right of page two will read “page 2 of 10”, +the header-right of page three will read “page 3 of 10”, +and so on. +

+ + + +

2. Header/footer style

+ +

Global changes

+ +

+The following macros allow you to make changes that affect all parts +of the header at once. +

+ +

HEADER_PLAIN
HEADER_FAMILY
HEADER_SIZE
HEADER_COLOR

+ +

+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, point size and +colour as she uses in paragraphs. +

+ +

+Replace HEADER_, above, with FOOTER_ to disable mom’s default +behaviour for the various elements of footer style. +

+ +

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

+ +

+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. +See +Arguments to the control macros +for an explanation of how control macros ending in +_SIZE work. +

+ +

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

+ +

+Replace HEADER_, above, with FOOTER_ to change the footer size. +

+ +

+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_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 +plus the header rule in the colour you give it as an argument. If +you wish finer control over colour in headers, you can use +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. +

+ +

+Replace HEADER_, above, with FOOTER_ to colourize footers. +

+ +

3. Part by part changes

+ +

+When using the following control ”macros, replace +“<POSITION> by LEFT, CENTER, or RIGHT as +appropriate. +

+ +

HEADER_<POSITION>_FAMILY
HEADER_<POSITION>_FONT
HEADER_<POSITION>_SIZE
HEADER_<POSITION>_CAPS
HEADER_<POSITION>_SMALLCAPS
HEADER_<POSITION>_COLOR
Grouping style parameters for the individual header/footer parts

+ +

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

+ +

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

+ +

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

+ +

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

+ +

+Replace HEADER_, above, with FOOTER_ to change a footer part’s +capitalization style. +

+ +

+Macro: HEADER_<POSITION>_SMALLCAPS toggle +

+ +

+HEADER_<POSITION>_SMALLCAPS is a +toggle macro. +If you want any part of headers to be set in smallcaps, simply +invoke this macro (using the appropriate position) with no argument. +If you wish to turn the smallcaps off, invoke the macro with any +argument (e.g. OFF, QUIT, END, +X...). +

+ +

+Replace HEADER,_ above, with FOOTER_ to invoke smallcaps for footer +parts. +

+ +

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

+ +

+Replace HEADER_, above, with FOOTER_ to set the colours for the +various elements of footers. +

+ +

Grouping style parameters for the individual header parts

+ +

+Instead of using control macros for the style parameters +of an individual header part, the parameters may be +grouped +by invoking HEADER_<POSITION>_STYLE with a list of +keyword/value pairs. Acceptable keywords are +FAMILY FONT SIZE COLOR CAPS and SMALLCAPS. +Keyword/value pairs may appear on the same line as the macro, or +separated into several lines using the backslash character +(\). If you use the latter style, all but the final +parameter must be terminated with the backslash. +

+ +

+Thus, to set the header-left part in Helvetica bold, red, 1 point larger +than +running text +and all caps, you could do either +
+ + .HEADER_LEFT_STYLE FAMILY H FONT B SIZE +1 COLOR red CAPS + +or +
+ + .HEADER_LEFT_STYLE \ + FAMILY H \ + FONT B \ + SIZE +1 \ + COLOR red \ + CAPS + +If you need to reverse the sense of CAPS +or SMALLCAPS, use NO_CAPS or +NO_SMALLCAPS. +

+ + + +

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

+ +

HEADER_MARGIN
HEADER_GAP

+ + + +

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

+ +

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

+ +

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

+ +

+Important – FOOTER_MARGIN and bottom margins +
+Mom requires a footer margin (i.e. the distance from the bottom of +the page at which to place footers) for proper operation, hence she +sets one, even if you don’t. As stated above, her default +footer margin is 3-picas. +

+ +

+If you use +B_MARGIN +or +PAGE +to set a bottom margin for your document (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 + +

+ + + +

+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, subject to the restriction outlined +here. +

+ +

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

+ +

+Additional note: +HEADER_GAP and FOOTER_GAP may only be used once, at the start of a +document. In +collated documents, +this means that HEADER_GAP or FOOTER_GAP cannot be used to change +the gaps once they have been set. The same applies to the Table of +Contents, Endnotes, Bibliographies, and Lists of... . +

+ +

+In the event that you need to change the header or footer gap after +the start of a document, you must do so with +T_MARGIN +or +B_MARGIN, +which raise or lower the top and bottom margins of +running text +but do not affect the placement headers and footers. +(See +here +for a demonstration.) +

+ + + +

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

+ +

HEADER_RULE – on or off
HEADER_RULE_WEIGHT – weight of the rule
HEADER_RULE_GAP – distance of rule from header
HEADER_RULE_COLOR – color of rule header

+ + + +

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

+ +

+HEADER_RULE_COLOR overrides the colour set with +HDRFTR_COLOR, +so 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. +

+ +

+ + + +

User-defined, single string recto/verso headers/footers

+ +

+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. The padding mechanism lets you create headers +that contain left, centre and right parts like mom’s defaults +but entirely of your own design. +

+ +

HEADER_RECTO
HEADER_VERSO +
- User-defined single string headers/footers (no recto/verso)
- Padding the header-recto/header-verso string

+ + + +

+Macro: HEADER_RECTO LEFT | CENTER | RIGHT [ CAPS ] "<header recto string>" +

+ +

+Macro: HEADER_VERSO LEFT | CENTER | RIGHT [ CAPS ] "<header verso string>" +

+ +

+User-defined single string headers/footers (no recto/verso) +
+HEADER_RECTO may be used to create user-defined, single string +headers (or footers, with FOOTER_RECTO), even when recto/verso is +not enabled (with +RECTO_VERSO). +In such cases, the header/footer you create is the one used on +every page, making HEADER_RECTO your “I need to design my own +headers from scratch” solution. +

+ +

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

+ +

+There are two steps to padding the string argument passed to HEADER_RECTO +(if you’re unsure what padding is, see +Insert space into lines). +

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.

+ +

+The situation depicted above is accomplished like this: +
+ + .HEADER_RECTO LEFT "^\*[PAGE#]#\E*[$TITLE]^" + .HEADER_VERSO LEFT "^\E*[$AUTHOR]#\*[PAGE#]^" + +Notice that the quad argument, LEFT, is used in both +cases. When padding a header, it doesn’t matter which +quad argument you use, although you must be sure to supply +one. Also note that mom does not interpret the # in +\*[PAGE#] as a padding marker (i.e. as a +place to insert whitespace). +

+ +

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

+ + + +

Headers and footers on the same page

+ +

+Normally, mom prints either a header or a footer, but not both, depending on whether +HEADERS +or +FOOTERS +is enabled. (Page numbering, whether in the top margin +or the bottom, is not considered a header or a footer.) +Should you need both headers and footers on the same page, the +single macro HEADERS_AND_FOOTERS is the way to set it up. +

+ +

+Macro: HEADERS_AND_FOOTERS (see Invocation) +

+ +

+Invocation: +
+ + .HEADERS_AND_FOOTERS \ + <L | C | R> "<header-recto string>" \ + <L | C | R> "<footer-recto string>" \ + <L | C | R> "<header-verso string>" \ + <L | C | R> "<footer-verso string>" + +or + + .HEADERS_AND_FOOTERS <anything> + +

+ +

+Unlike the macros, +HEADERS +and +FOOTERS, +which are +toggle +macros, HEADERS_AND_FOOTERS requires that you supply the information +you want in the headers and footers yourself. Mom does no automatic +generation of things like the title and the author in headers and +footers when you’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 part on the left, +in the middle, or on the 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 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, invoke +.FOOTERS +afterwards. +

+ +

Examples of HEADERS_AND_FOOTERS usage

+ +

Example 1: Header and footer the same on every page

+ +.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: Different headers and footers on recto/verso pages

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

+ +

+ + + +

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

PAGINATE – pagination on or off
PAGENUMBER – user-defined (starting) page number
PAGENUM_STYLE – digits, roman numerals, etc
PAGENUM_ON_FIRST_PAGE – put page number on first page when numbering is at the top of the page
DRAFT_WITH_PAGENUMBER – attach draft/revision information to page numbers
PAGENUMBER_STRING – user-defined page number string
Pagination control macros and defaults

+ + + +

+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, +etc). +

+ +

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

+ + + +

+Macro: PAGENUMBER_STRING "<text of page number string>" +

+ +

+If you want page numbering to contain text in addition to the page +number itself, use PAGENUMBER_STRING. +

+ +

+The most common use for PAGENUMBER_STRING is to include the total +number of pages along with the page number, for example +“Page 1 of 10, Page 2 of 10...” To accomplish this, +you’d enter +
+ + .PAGENUMBER_STRING "Page \*[PAGE#] of 10" + +Notice that the page number is entered symbolically with the +inline escape +\*[PAGE#], +while the total number of pages must be entered explicitly after the +document is complete and the total number of pages known. +

+ + + +

Pagination control macros and defaults

+ +

Family/font/size/colour
Page number position (vertical and horizontal)
Enclose page numbers with hyphens (on or off)

+ +

1. Page number family/font/size/colour

+ +

+See +Arguments to the control macros. +
+The following control macros may also be +grouped +using PAGENUMBER_STYLE.* +

+ +.PAGENUM_FAMILY default = prevailing document family +.PAGENUM_FONT default = roman +.PAGENUM_SIZE default = +0 (i.e. same size as paragraph text) +.PAGENUM_COLOR default = black + +

+ +

+*Note: Do not confuse PAGENUMBER_STYLE with +PAGENUM_STYLE. +

+ +

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

+ +

+Note: +HEADERS must be OFF for PAGENUM_POS TOP to work. +

+ +

3. Enclose page numbers with hyphens (on or off)

+ +

+Macro: PAGENUM_HYPHENS toggle +

+ +

+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, etc), like this: +
+ + .PAGENUM_HYPHENS OFF + +If, for some reason, you want to turn page number hyphens back +on, invoke the macro without an argument. +

+ + + +

Inserting blank pages into a document

+ +

+Macro: BLANKPAGE <# of blank pages to insert> [DIVIDER [NULL]] +

+ +

+This one does exactly what you’d expect—inserts a blank +page (or pages) into a 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. This is useful for forcing new +sections of a document onto recto pages, but may have other +applications as well. +

+ +

+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 DIVIDER must be given if +you’re inserting a blank page before the start of major +document sections (chapters, endnotes, bibliographies, +or tables of contents–provided the table of contents is not being +autorelocated). +Without the DIVIDER argument, mom simply +inserts the blank pages and prepares the next page to receive +running text. +

+ +

+NULL, which is also optional, 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. +

+ +

+Note: +Do not use BLANKPAGE before TOC if the table of contents is being +autorelocated. +

+ +

+ + + + + + + + +

Back to Table of Contents

Top

Next: Recto/verso printing, collating

+ +

+ + + diff --git a/contrib/mom/momdoc/images.html b/contrib/mom/momdoc/images.html new file mode 100644 index 0000000..dc1837f --- /dev/null +++ b/contrib/mom/momdoc/images.html @@ -0,0 +1,3515 @@ + + + + + + + + + Mom -- Graphics, floats, and preprocessor support + + + + + + + +

+ + + + + + + +

Back to Table of Contents

Next: Page headers/footers, pagination

+ +

Graphics, floats, and preprocessor support

+ +

Inserting images and graphics +
- Image conversion and file processing +
  - PDF
  - EPS
- The PDF_IMAGE macro +
  - PDF_IMAGE_FRAME—set parameters for image frames
- The PSPIC macro
Floats +
- The FLOAT macro
- Labelling and captioning floats +
  - LABEL
  - CAPTION
Preprocessor support +
- tbl +
  - .TS / .TH / .TE macros and arguments
- eqn +
  - .EQ / .EN macros and arguments
- pic +
  - .PS / .PE macros and arguments
  - PIC_TEXT_STYLE—set parameters for text in diagrams
- grap
- refer
Captions and labels +
- AUTOLABEL
- SET_AUTOLABEL
- CAPTION_AFTER_LABEL
- CAPTIONS / LABELS / SOURCES—set parameters for each
- MLA
Lists of Figures, Tables, and Equations +
- Placement of Lists
- Macros to generate Lists
- Formatting and style parameters for Lists +
  - LISTS_STYLE
Shaded backgrounds and frames (boxes) +
- Introduction and description
- The BOX macro
- Additional notes on box usage and behaviour +
  - QUOTE, BLOCKQUOTE, EPIGRAPH, FLOAT
  - CODE
  - Description of boxed BLOCKQUOTEs and EPIGRAPHs +
    - Leftover box syndrome
  - Slides
  - Footnotes
- Page colour
+

+ +

Inserting images and graphics

+ +

+In order to include images in mom documents, the images must be in +either PDF (.pdf) or EPS (.eps) format. Each format requires its own +macro, but both take the same arguments, and in the same order. +

+ +

+Please note that there are differences in the way the files +containing PDF and EPS images must be processed, hence documents may +not contain a mix. +

+ +

Image conversion and file processing

+ +

+When your image files are not in PDF or EPS format—jpgs, +for example—you must convert them before including them in +a mom document. Any utility for converting images may used. The +ImageMagick suite of programmes, present on most GNU/Linux +systems, contains convert, which is simple and effective. +

+ +

PDF

+ +

+Assuming a jpg image, conversion to PDF is done like this: +
+ + convert <image>.jpg <image>.pdf + +Any image type supported by convert may be converted this +way. +

+ +

+Mom files containing PDF images must be processed using +groff’s pdf driver. Use of +pdfmom +is strongly recommended, which natively invokes the pdf driver. +
+ + pdfmom doc.mom > doc.pdf + +

+ +

EPS

+ +

+Assuming a jpg image, conversion to EPS is done like this: +
+ + convert <image>.jpg <image>.eps + +Any image type supported by convert may be converted this +way. There have been reports of trouble with PostScript level 2 +images, so don’t save your images in this format. +

+ +

+Mom files containing EPS images must be processed using +groff’s postscript driver. Use of +pdfmom, +which can be told to use the postscript driver, is strongly +recommended. +
+ + pdfmom -Tps doc.mom > doc.pdf + +

+ + + +

PDF_IMAGE

+ +

+Macro: PDF_IMAGE \ +
+[ -L | -C | -R | -I <indent> ] \ + +<pdf image file> <width> <height> [ SCALE <factor> ] \ + +[ ADJUST +|-<vertical adjustment> ] [ NO_SHIM ] [ NO_FLEX ] \ + +[ FRAME ] \ + +[ CAPTION "<caption>" ] [ SHORT_CAPTION "<short caption>" ] \ + +[ LABEL "<label>" ] [ TARGET "<name>" ] +

+• +<indent>, +<width>, +<height> +and + +<vertical adjustment> +require a +unit of measure +

+ +

+Note: +Mom files with embedded PDF images must be processed with +pdfmom doc.mom > doc.pdf. Arguments may be broken +into several lines using the “line-continued” backslash +(\), as shown above. +

+ +

+Unlike +PSPIC, +which it resembles, PDF_IMAGE requires that the pdf image’s +dimensions (the bounding box, +see below) +be supplied each time it’s called. +

+ +

+The first optional argument tells mom how to align the image +horizontally, with -L, -C, and -R +standing for left, centre and right respectively. If you need more +precise placement, the -I argument allows you to give an +indent from the left margin. Thus, to indent a PDF image 6 +picas +from the left margin +
+ + .PDF_IMAGE -I 6P <remaining arguments> + +If you omit the first argument, the image will be centred. +

+ +

+<pdf image> must be in PDF format, with a .pdf +extension. If it is not, mom will abort with a message. See +here +for instructions on converting image formats to PDF. +

+ +

+<width> and <height> are the +dimensions of the image’s bounding box. The most reliable way +of getting the bounding box is with the utility, pdfinfo: +
+ + pdfinfo <image.pdf> | grep "Page *size" + +This will spit out a line that looks like this: +
+ + Page size: width x height pts + +pts means +points, +therefore the unit of measure appended to <width> +and <height> must be p. +

+ +

+The remaining arguments are optional and may be entered in any +order, although it’s best to put CAPTION, +SHORT_CAPTION, and LABEL last. +

+ +

SCALE

+ +

+SCALE allows you to scale the image by +<factor>. The factor is a percentage of the +image’s original dimensions, thus SCALE 50 +scales the image to 50 percent of its original size. No percent +sign or unit of measure should be appended. +

+ +

ADJUST

+ +

+ADJUST lets you raise (-) or lower +(+) the image +within the space allotted for it +by the amount you specify. This is useful for achieving good +optical centering between surrounding blocks of type. A unit of +measure is required. +

+ +

+Tip: +You may sometimes find that a PDF_IMAGE at the bottom of a page +doesn’t sit flush on the bottom margin, however attempts to lower it +by adding space beforehand result in it being deferred to the next +page. +

+ +

+The solution is to introduce negative space before the image +so that it displays on the page, then lower it to the bottom margin +with PDF_IMAGE’s ADJUST argument. +

+ +

NO_SHIM

+ +

+NO_SHIM instructs mom not to apply +shimming +after an image, which she will do automatically when shimming is +enabled, which it is by default. Shimming ensures that running text +after the image falls properly on the page’s +baseline grid, +but can result in slightly unequal spacing above and below +(correctable with the ADJUST argument). +NO_SHIM is useful when you have several images on the +page and there are visible differences in the spacing beneath them +as a result of shimming. To ensure a flush bottom margin, the last +image on the page should be shimmed, i.e. should not be given the +NO_SHIM argument. +

+ +

NO_FLEX

+ +

+NO_FLEX instructs mom not to apply +flex-spacing +after an image, which she will do automatically when flex-spacing is +enabled. NO_FLEX is useful when you have several images +on the page and you want to distribute excess vertical +whitespace on the page amongst other flex-spacing points on the +page. If there are no others, the final image should be +flex-spaced, i.e. not given the NO_FLEX argument. +

+ +

FRAME

+ +

+FRAME instructs mom to put a frame around the image. +Parameters for the frame are set with +PDF_IMAGE_FRAME. +

+ +

CAPTION

+ +

+CAPTION allows you to give the image a caption. By +default, the caption appears above the image, but may be attached to +the label that appears beneath the image. See +CAPTION_AFTER_LABEL +in +Captions and labels. +The text of the caption must be surrounded by double-quotes. +

+ +

SHORT_CAPTION

+ +

+SHORT_CAPTION allows you to trim long captions for +inclusion in the List of Figures. The text you supply, surrounded +by double-quotes, is what will appear in the List. +

+ +

LABEL

+ +

+LABEL, if given, appears beneath the image. The text you +supply, surrounded by double-quotes, is how the image is labelled +in both the document proper and the List of Figures. Mom provides +an auto-labelling facility for images (see +AUTOLABEL), +which, if enabled, overrides the LABEL argument. +

+ +

TARGET

+ +

+TARGET followed by a unique name surrounded by +double-quotes creates a PDF target for the image so that it may be +linked to from other places in the file (with PDF_LINK; see +Producing PDFs with groff and mom). +

+ +

+Please note: The following functionality is available +only with groff 1.22.4 or later. +

+ +

+When +autolabelling +is enabled and the document is processed with +pdfmom, +the target name can be used to generate the target’s label +number in running text if it is entered as a groff string, i.e. of the +form \*[name]. For example, if you create +a target named “foo” for a pdf image whose autolabel +number would be 3, entering +
+ + See + .PDF_LINK foo "Figure \*[foo]" + +anywhere in running text would result in a pdf link that reads +“Figure 3”. If chapter numbers are being prefixed to +labels, the same string in, say, chapter 5 would produce the pdf +link “Figure 5.3”. +

+ +

+Note: Version 2.0-c change +
+Mom now treats all pdf images identically to +floats, +which is to say that if an image doesn’t fit on the output +page, she will defer it to the top of the next page while continuing +to process +running text. +ADJUST is ignored whenever an image is the first to be +deferred, except when moving from column to column on the same page, +when the image may need to be optically adjusted. Subsequent images +that do not fit, if any, are output in order immediately after the +first. +

+ +

+Prior to 2.0-c, it was recommended that images be wrapped inside +FLOAT, +but this is now no longer required, and should, in fact, be avoided. +

+ + + +

PDF_IMAGE_FRAME

+ +

+Macro: PDF_IMAGE_FRAME <inset amount> <rule weight> <color> +

+• <inset amount> +requires a +unit of measure; +conversely, +<rule weight> +must not have a unit of measure appended +

+ +

+PDF_IMAGE_FRAME establishes the parameters for subsequent invocations of +PDF_IMAGE +when the FRAME argument is given. Arguments must appear +in order, and any you wish left at the current value should be +entered as two adjacent double-quotes. So, for example, +
+ + .PDF_IMAGE_FRAME "" "" blue + +leaves the inset value and rule weight at their current value and +changes the frame colour to blue. +

+ +

+Frames are drawn outside the image at +its requested dimensions inclusive of scaling. Colours must be +pre-initialized with +XCOLOR +or +NEWCOLOR. +

+ +

+The default inset is 6 points, the default rule +weight is .5 (points), and the default colour is black. +

+ + + +

PSPIC

+ +

+Macro: PSPIC [ -L | -R | -I <n> ] <file> [ width [ height ] ] +

+ +

+PSPIC is not actually part of mom, but rather a macro included with +every groff installation. man groff_tmac contains the +documentation for PSPIC, but I’ll repeat it here with a few +modifications for clarity. +

+ +

From groff_tmac

+<file> is the name of the file containing the +image; width and height give the desired +width and height of the image as you wish it to appear within the +document. The width and height arguments may have +units of measure +attached; the default unit of measure is i. PSPIC 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 centred. 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>; +the default unit of measure is m +(ems). +

+ +

+It is not necessary to pass PSPIC the <width> +and <height> arguments unless you are scaling +the image, in which case you will most likely need the original +dimensions of the EPS image’s bounding box. These can be +found with +
+ + gs -q -dBATCH -dNOPAUSE -sDEVICE=bbox <image file>.pdf 2>&1 \ + | grep "%%BoundingBox" | cut -d " " -f4,5 + +The two digits returned are in +points, +therefore the +unit of measure +p must be appended to them. +

+ +

+Because PSPIC lacks the ADJUST option offered by +PDF_IMAGE +a certain amount of manual tweaking of the vertical placement of the +image will probably be required, typically by using the +ALD +and +RLD +macros. Wrapping the image in a +float +and using FLOAT’s ADJUST option can also be used to +correct optical centering. +

+ +

+Additionally, non-floated EPS images +will almost certainly disrupt the baseline placement of +running text. +In order to get mom back on track after inserting a non-floated +.PSPIC image, insert the +SHIM +or +FLEX +macro afterwards, depending on the +vertical whitespace management +strategy in effect, so that the bottom margin of running text falls +where it should. +

+ +

+Remember that mom files with embedded EPS images must be processed +with +
+ + pdfmom -Tps doc.mom > doc.pdf + +

+ +

+Please note: +PSPIC does not support +autolabelling, +labels, captions, or inclusion in the List of Figures. If you wish +this functionality, +convert your images to pdf +and use +PDF_IMAGE +instead, then process the file with +pdfmom +(without the -Tps option). +

+ +

Introduction to floats

+ +

+Non-textual insertions in a document (tables, for example) sometimes +do not fit on the output page of a PDF or PostScript document at +the place they’re inserted in the input file. It’s +necessary, therefore, to defer them to the next page while carrying +on with +running text. +

+ +

+Whenever you need this functionality, mom provides the FLOAT macro. +

+ +

+Floats are usually used for images and graphics, but can contain +anything you like, including text. Whatever’s in the +float will be kept together as a block, output immediately if +there’s room, or deferred to the top of the next output page +when there isn’t; running text continues to the bottom of the +previous page without interruption. +

+ +

+In the case of a float that doesn’t fit being followed by +one that does, both are deferred and output one after the other. +Note that this represents a change from versions 2.1-b_1 and earlier +where the second float was output in position and the first was +deferred. +

+ +

+A key distinction between a float and a +QUOTE +or +BLOCKQUOTE +is that while a float keeps everything together and defers output if +necessary, quotes and blockquotes are output immediately, and may +start on one page and finish on the next. +

+ +

+Floats always begin in +no-fill mode. +Text entered immediately after FLOAT will be set line-for-line +unless a +JUSTIFY +or +QUAD L|R|C +precedes it. Alternatively, any macro that sets a quad direction +may be used, e.g. +PP. +

+ +

+Floats always deposit a break before they begin, which means the +line beforehand will not be +filled. +Floats, therefore, cannot be inserted in the middle of a paragraph +without studying the output file and determining where to break or +spread +the line before the float. Furthermore, if you want a float between +paragraphs, the float should come before .PP, like this: +
+ + .FLOAT + ... + .FLOAT OFF + .PP + +not +
+ + .PP + .FLOAT + ... + .FLOAT OFF + +

+ +

+Floats begin on the baseline immediately below the running text +preceding them. No additional whitespace surrounds them, above or +below. Running text below a float is, however, +shimmed +or +flex-spaced, +depending on the +vertical whitespace management +strategy in effect. This behaviour can be disabled for individual +floats with NO_SHIM or NO_FLEX. +

+ +

+If you’d like more space around a float, you must add it +manually, for example with +ALD +or +SPACE. +

+ + + +

FLOAT

+ +

+Macro: FLOAT <arguments> | <anything> + +Arguments: + +[ ADJUST +|-<amount> ] \ + +[ FORCE ] \ + +[ SPAN ] \ + +[ INDENT <value> ] \ + +[ CENTER ] \ + +[ RIGHT ] \ + +[ NO_SHIM] \ + +[ NO_FLEX ] \ + +[ TARGET "<name>" ] +
+

+ +

+Note: +FLOAT is intended for use with the document processing macros only. +

+ +

+Note: +As a general rule, avoid consecutive floats that have no intervening +running text. +Rather, wrap all the material into a single float. +

+ +

+Note: +Deferred floats are output with the left indent that was in effect +when they were input. If you do not want this behaviour, disable +the indent prior to inputting the float and re-enable it afterward. +

+ +

+Note: +Mom treats pic pre-processor directives and pdf images as +floats so it is not necessary to wrap them inside FLOAT unless +additional material is included in what is floated. +

+ +

+To begin a float, simply invoke .FLOAT and follow it with +whatever you want the float to contain. When you’re done, +invoke .FLOAT OFF (or OFF, +QUIT, END, X, etc). +

+ +

ADJUST

+ +

+The optional ADJUST argument tells mom to raise +(+) or lower (-) the float within +the space allotted to it by the specified amount. +<amount> must have a +unit of measure +appended. ADJUST gives you precise control over +the vertical centering of floats, allowing you to compensate for +unequal spacing that may result from the automatic +shimming +or +flex-spacing +floats. +

+ +

+ADJUST is ignored for the first float deferred to +a following page but respected for subsequent deferred floats +output immediately afterwards. +

+ +

FORCE

+ +

+The FORCE argument instructs mom to output the float +exactly where it occurs in the input file. With FORCE, +mom immediately breaks to a new page to output the float if it does +not fit on the current page. While this is somewhat contrary to the +notion of floats (i.e. that running text should continue to fill the +page), there are circumstances where it may be desirable. +

+ +

+If you need to force a page break after completion of a float that +has been deferred to a subsequent page, insert \!.bp +immediately before terminating the float. +

+ +

SPAN

+ +

+The SPAN argument tells mom that a float, if deferred, +may carry onto multiple pages. Please note that SPAN may +not be used for floats containing a boxed table; mom will abort with +a warning should this occur. Unboxed tables, on the other hand, are +acceptable within floats that are given the SPAN argument. +

+ +

INDENT

+ +

+INDENT allows you to indent a float from the left margin +by a specified value. The value must have a +(unit of measure +appended to it. +

+ +

CENTER

+ +

+CENTER instructs mom to center a float if it is not +already centered by default. +

+ +

RIGHT

+ +

+RIGHT instructs mom to place a float at the right of the +page; the longest line in the float will be flush with the +page’s right margin. +

+ +

NO_SHIM

+ +

+NO_SHIM instructs mom not to apply +shimming +after a float, which she will do automatically when shimming is +enabled, which it is by default. Shimming ensures that running text +after the float falls properly on the page’s +baseline grid, +but can result in slightly unequal spacing above and below +(correctable with the ADJUST argument). +NO_SHIM is useful when you have several floats on the +page and there are visible differences in the spacing beneath them +as a result of shimming. To ensure a flush bottom margin, the last +float on the page should be shimmed, i.e. should not be given the +NO_SHIM argument. +

+ +

NO_FLEX

+ +

+NO_FLEX instructs mom not to apply +flex-spacing +after a float, which she will do automatically when flex-spacing is +enabled. NO_FLEX is useful when you have several floats +on the page and you want to distribute excess vertical +whitespace on the page amongst other flex-spacing points on the +page. If there are no others, the final float should be +flex-spaced, i.e. not given the NO_FLEX argument. +

+ +

TARGET

+ +

+TARGET followed by a unique name surrounded by +double-quotes creates a PDF target for the float so that it may be +linked to from other places in the file (with PDF_LINK; see +Producing PDFs with groff and mom). +

+ +

+Floats cannot be autolabelled, so unlike pdf images and +pre-processor material, the target name cannot be used as a string +to generate the target’s label number in running text. Label +numbers for floats must be entered explicitly running text, however +they may be entered symbolically in the argument to +LABEL. +See +Reserved variables for +labels. +

+ + +

+Note: +Floats use +no-fill mode, +with each input line beginning at the left margin. If this is not +what you want, you must specify the preferred horizontal alignment +within the float (e.g. +CENTER +or +RIGHT). +

+ +

+Furthermore, if you want text +filled, +you must specify +.QUAD L|R|C +or +.JUSTIFY—again, +within the float. +

+ +

Labelling and captioning floats

+ +

+Labelling and captioning of tables (tbl), equations +(eq), diagrams (pic) and pdf images +(PDF_IMAGE) +are handled by the macros that initiate them, regardless of whether +they’re wrapped inside a float. However, since a float may +contain any valid input, it is sometimes necessary to add a label +and/or caption to the float itself. +

+ +

+Important: +Always use the native labelling/captioning facilities for +preprocessor output and pdf images rather than labelling the +containing float, if any. +

+ +

+The macros to label and caption floats are +LABEL +and +CAPTION. +If a label or caption is to appear above the float, the appropriate +macro is entered immediately after +FLOAT. +If a label or caption is to appear beneath the float, the appropriate +macro is entered immediately before ending the float with +FLOAT OFF. +

+ +

+If a label and caption are to be joined, the LABEL macro is +used to enter both by passing the CAPTION argument to +LABEL. +

+ +

+It is impossible for mom to know the contents of a float, so +floats cannot be autolabelled. Each label must be entered +explicitly. Mom does, however, provide a way to enter both +chapter numbers and incrementing label numbers +symbolically, +easing the burden of keeping the numbering scheme intact as +labelled floats are added to or subtracted from a document. +

+ +

+Tip: +QUOTE +and +BLOCKQUOTE +may also be labelled and captioned using LABEL and +CAPTION. +

+ +

Spacing

+ +

+If a float has a caption at the top, the caption is whitespaced +1/4 linespace from running text and the float itself begins +an additional 1/4 linespace below the caption. If the float has +no corresponding label at the bottom, the float observes the +bottom-spacing rules for all floats, namely that no extra space is +added other than +shimming +or +flex-spacing, +depending on the +vertical whitespace management +in effect. +

+ +

+If a float has a label at the bottom but no caption at the top, the +float begins exactly where started, i.e. with no extra whitespace +between running text and the float. The label (and attached +caption, if any) are whitespaced 1/4 linespace below the float, +with an additional 1/4 linespace underneath plus shimming or +flex-spacing. +

+ +

+Labelled/captioned quotes and blockquotes inside floats treat the +labels/captions as part of the quote so the spacing above and +below the whole float block is what you’d expect from quotes +normally, while the spacing between the label/caption and the quote +is 1/4 linespace. +

+ +

LABEL

+ +

+Macro: LABEL +"<label>" [ CAPTION "<caption>" ] [ SHORT_CAPTION ] \ + +[ TO_LIST FIGURES | TABLES | EQUATIONS ] +

+ +

+The placement of a float’s label depends on where you put it +inside the float. +

+ +

+If you want a label at the top, put LABEL immediately +underneath +FLOAT +and follow it with the text of the label surrounded by double-quotes: +
+ + .FLOAT + .LABEL "Fig. 1" + +If you want a label at the bottom, put LABEL immediately +before ending the float: +
+ + .FLOAT + <contents of float> + .LABEL "Fig. 1" + .FLOAT OFF + +

+ +

Reserved variables for labels

+ +

+Mom reserves strings you may use when entering +label text after the LABEL argument. +\*[chapter] holds the current chapter +or major section number. \*[fig-label], +\*[tbl-label], and +\*[eqn-label] increment the label number of +the appropriate label type by one, and are initially set to zero +after each invocation of +START +when the +DOCTYPE +is CHAPTER. Thus, in every chapter requiring numbered +float labels, you can enter +
+ + .LABEL "Fig. \*[chapter].\*[fig-label]. TO_LIST FIGURES + +which, assuming the third autolabelled float of Chapter 2, will +produce Fig. 2.3. +

+ +

+If your DOCTYPE is DEFAULT or NAMED, +you must reset \*[<type>-label] after +each +COLLATE +by entering +
+ + .AUTOLABEL_<list type> + +before .START. +

+ +

+If +autolabelling +is enabled, e.g. .AUTOLABEL_IMAGES (List +of Figures) or .AUTOLABEL_PIC (also List of Figures), +the prefix is stripped from the label when it appears in +the List. Thus, if you have invoked .AUTOLABEL_PIC, +
+ + .LABEL "Fig. 1.1." + CAPTION "Caption for label \ + TO_LIST FIGURES + +or +
+ + .LABEL "Fig. \*[chapter].\*[label]." \ + CAPTION "Caption for label \ + TO_LIST FIGURES + +will appear in the List of Figures as “1.1. Caption for +label”. +

+ +

CAPTION

+ +

+If you’d like a caption attached to the label, pass +LABEL the optional argument CAPTION followed +by the text of the caption as a single string surrounded by +double-quotes: +
+ + .FLOAT + <contents of float> + .LABEL "Fig. 1" CAPTION "Caption for Fig. 1" + .FLOAT OFF + +Note that the +CAPTION +macro by itself permits entering several strings, each output on +a line by itself, whereas the CAPTION argument to +LABEL accepts only a single string. +

+ +

SHORT_CAPTION

+ +

+If your caption runs long and you’re including the +float in a “List of ...”, (see +TO_LIST, below) +SHORT_CAPTION tells +mom how you’d like the caption to appear in the List. +

+ +

TO_LIST

+ +

+The optional argument TO_LIST tells mom to add the +float’s label and attached caption, if present, to the specified +list, +which may be one of FIGURES, TABLES, or +EQUATIONS. +

+ +

+If, for some reason, you want only the caption appended to the List, +give \& as the first argument to LABEL, followed by +CAPTION “caption”: +
+ + .LABEL \& \ + CAPTION "caption" + +

+ +

+Tip: +TO_LIST can be used to handle situations where labelled +floats need to go to a uniquely named “List of ...”. +

+ +

+Suppose, for example, your document contains figures (e.g. +pic output or pdf-images) and tables, and you need a +“List of Examples” for floats labelled “Example +n.n”. By changing the default title string for +LIST_OF_EQUATIONS +to “List of Examples”, you may include the float in your +List of Examples with +
+ + .TO_FIGURES EQUATIONS + +

+ +

CAPTION

+ +

+Macro: CAPTION +"<caption>" \ + +[ "<additional line>" [ "<additional line>"... ] ] \ + +[ TO_LIST FIGURES | TABLES | EQUATIONS ] +

+ +

+The placement of a float’s caption depends on where you put it +inside the float. +

+ +

+If you want a caption at the top, put CAPTION immediately +underneath +FLOAT +and follow it with the text of the caption surrounded by double-quotes: +
+ + .FLOAT + .CAPTION "Caption at top of float" + +CAPTION can take multiple string arguments, allowing for +captions that run to several lines. There is a caveat: the strings +are not automatically broken into individual lines. You must +provide strings that include literal breaks or spaces: +
+ + .FLOAT + .CAPTION "Caption" ".BR" "at top" ".BR" "of float" + +or, easier to read: +
+ + .FLOAT + .CAPTION "Caption" \ + ".BR" \ + "at top" \ + ".BR" \ + "of float" + +If you want a caption at the bottom, put CAPTION immediately +before ending the float: +
+ + .FLOAT + <contents of float> + .CAPTION "Caption at bottom of float" + .FLOAT OFF + +

+ +

+Note: +If you want a caption attached to a label, do not use +CAPTION by itself. Rather, invoke +.LABEL +with the CAPTION argument. +

+ +

Preprocessor support

+ +

+Mom offers full support for the eqn (equations), pic +(diagrams), grap (graphs), tbl (tables) and +refer (bibliographies/citations) preprocessors, including +captions, labelling, autolabelling, and inclusion in the Lists of +Equations, Figures, and Tables. +

+ +

+Other than refer, which is discussed at length in the Bibliographies and references section, it is +beyond the scope of this documentation to cover full preprocessor +usage. Consult the manpages eqn(1), pic(1), +grap(1) and tbl(1) for instructions. +

+ +

+Version 2.0-c changes +
+Preprocessor support has been revised and expanded as of version 2.0-c. +Please read the following sections thoroughly and update any +documents created with versions prior to 2.0-c as necessary. +

+ +

tbl support

+ +

+Mom documents can include tables generated with the groff +preprocessor tbl. If you are unfamiliar with tbl, I +recommend downloading a copy of +Tbl - A Program to Format Tables, +which, in addition to providing a thorough introduction, contains +some fine examples. If you use tbl, you must pass groff or +pdfmom the -t flag when you process the file. +

+ +

+Tables formatted with tbl begin with the macro +.TS (Table Start) and end with +.TE (Table End). Depending on where you +want your tables output in a document, you may need to wrap +your tbl code inside a +float, +or pass the H argument to .TS. +

+ +

+If you put tbl code inside a float, the table will be +output immediately if it fits on the page, or deferred to the top +of the next page if it doesn’t. If you prefer a table to +begin where you say and span over to the next page, or if you know +for certain a boxed table will run to multiple pages, simply pass the +H argument to .TS, along with a corresponding +TH +and do not wrap the table inside a float. +

+ +

+Note: +If you create a boxed table that will span several pages, do not +wrap the table inside a float. Boxed, multipage tables and FLOAT +should be considered mutually exclusive. This restriction is +imposed by the tbl preprocessor itself, not groff or +mom. Unboxed tables that span several pages, however, are +acceptable within FLOAT. +

+ +

tbl placement in mom docs

+ +

+If you use .TS without the H argument (and +therefore no .TH), tables that fit on the page are output +in position. If there is not enough room to output the table, +tbl will abort with message instructing you to use +.TS H/.TH. Given that .TS without H +may sometimes fail, it is advisable to begin all tbl blocks +with .TS H. +

+ +

+If you give .TS the H argument (with a +corresponding .TH), tables will be output in position and +span as many pages as necessary to complete output. A table header +will be printed at the top of each page’s table output. In the +event that there is not enough room to print the table header and +at least one row of table data near the bottom of a page, mom will +break to a new page before beginning table output, leaving a gap +in +running text. +

+ +

+Boxed tables inside +floats +are output in position if they fit on the page. If not, they are +deferred to the top of the next page without a break in running +text. Boxed tables within floats may not, however, span multiple +pages; mom will abort with a message should a boxed table in a float +run longer than the page. +

+ +

+Unboxed tables inside floats may span multiple pages provided the +SPAN argument has been given to +FLOAT. +

+ +

+Note: +The vertical spacing around unfloated tables may appear slightly +unequal, especially if there are several tables on the page. This +is a result of the +shimming +or +flex-spacing +that mom applies automatically after each table, depending on which +vertical whitespace management +is in effect. You may +disable shimming or flex-spacing with +NO_SHIM +or +NO_FLEX, +or by passing the NO_SHIM or NO_FLEX argument +to .TS. In either case, you will still likely want to +adjust the spacing around with table with the ADJUST +argument to .TS. Tables inside floats should be adjusted +with the ADJUST argument to +FLOAT, +not the ADJUST argument to .TS. +

+ +

.TS / .TH / .TE

+ +

+Macro: TS ++Arguments: + + [ H ] + + [ BOXED ] + + [ CENTER ] + + [ NEEDS ] + + [ ADJUST +|-<vertical adjustment>] + +(unit of measure +required) + ++ [ NO_SHIM ] + + [ NO_FLEX ] + + [ CAPTION "<caption>" ] + + [ SHORT_CAPTION "<short caption>" ] + + [ LABEL "<label>" ] + + [ TARGET "<name>" ] + +
+Macro: TH (optional, only if .TS H) +
+Macro: TE [ SOURCE "<text of table source>" ] +

+ +

+Tables to be formatted with tbl begin with the macro +.TS and end with .TE. Global tbl +options (“flags”), formatting, and data (per +tbl(1)) come between the two macros. +
+ + .TS + <tbl options, formatting, and data> + .TE + +Tables may be wrapped inside a +float, +in which case, the entire table will be output on the current page +if it fits, or deferred to the next page if it doesn’t. +
+ + .FLOAT + .TS + <tbl options, formatting, and data> + .TE + .FLOAT OFF + +

+ +

The .TS macro

+ +

+Note: Version 2.0-c change +
+2.0-c introduces revisions to the handling of labels and/or +captions, which, along with NO_SHIM, must now be given +as arguments to .TS rather than .TE, as was +the case formerly. Please read this section carefully if you have +documents containing tables as they may need to be updated. +

+ +

+IMPORTANT: +All arguments to TS must appear on the same line as +.TS. Do not attempt to break them up with the +“line-continued” backslash. You may want to set your +text editor to “wrap” mode in order to see all your +arguments. This annoyance stems from the preprocessor mechanism +itself, not groff or mom. +

+ +

+The TS macro must be invoked before entering a tbl +block. You may give as many or as few of its arguments as required, +in any order, although it is advisable to put CAPTION, +SHORT_CAPTION, and/or LABEL last. +

+ +

H

+ +

+With the H argument, a table will span as many pages as +necessary, with or without a running header. The placement of the +corresponding +.TH, +which is required whenever the H argument is given, +determines what, if anything, goes in the header. Compare the +following: + + .TS H .TS H + c s s c s s + c s s c s s + c c c c c c + n n n. n n n. + Percent Increase .TH + 2002-2012 Percent Increase + .TH 2002-2012 + <tbl data> <tbl data> + .TE .TE + +The first example will create a table that spans multiple +pages if necessary, with a running header (“Percent +Increase / 2002-2012”) for that table appearing at +the top of each page until the table ends. The second example, +equally, may run to several pages, but without the running header. +See +TH +for an explanation of .TH placement. +

+ +

+Tip: +Generally speaking, it’s a good idea to get into the habit +of using .TS H all the time, since there are no +circumstances under which it fails, whereas .TS without +H will fail on tables that exceed the page length. +

+ +

BOXED

+ +

+If a table is to be boxed (i.e., tbl is given the flags +'box' or 'allbox') you must pass the argument +BOXED to .TS, as in this example: +
+ + .TS BOXED + allbox; + c s s + c c c + n n n. + <tbl data> + .TE + +

+ +

CENTER

+ +

+If a table is to be centered on the page, (i.e., tbl is +given the 'center' flag), you must pass the argument +CENTER to .TS, as in this example, which +creates a (possibly) multipage boxed table, centered on the page, +with a running header. + + .TS H BOXED CENTER + allbox center; + c s s + c s s + c c c + n n n. + Percent Increase + 2002-2012 + .TH + <tbl data> + .TE + +

+ +

NEEDS

+ +

+If a table is not inside a float and you pass .TS the +H argument (which you should; see the tip +here), +mom begins output immediately where the table occurs in the +input file if there is enough room on the output page for the +table header plus at least one row of table data. If there +isn’t enough room, mom breaks to a new page before beginning +the table, leaving a gap in +running text +at the bottom of the previous page. If, for aesthetic reasons, +you would prefer that mom require more than one row of table data +beneath the header near the bottom of a page, you may increase the +number with the NEEDS argument, followed by the desired +number of rows. +

+ +

ADJUST

+ +

+ADJUST lets you raise (-) or lower +(+) the table +within the space allotted for it +by the amount you specify. This is useful for achieving good +optical centering between surrounding blocks of type. A unit of +measure is required. +

+ +

NO_SHIM

+ +

+NO_SHIM instructs mom not to apply +shimming +after a table, which she will do automatically when shimming is +enabled, which it is by default. Shimming ensures that running text +after the table falls properly on the page’s +baseline grid, +but can result in slightly unequal spacing above and below +(correctable with the ADJUST argument). +NO_SHIM is useful when you have several tables on the +page and there are visible differences in the spacing beneath them +as a result of shimming. To ensure a flush bottom margin, the last +table on the page should be shimmed, i.e. should not be given the +NO_SHIM argument. +

+ +

NO_FLEX

+ +

+NO_FLEX instructs mom not to apply +flex-spacing +after a table, which she will do automatically when flex-spacing is +enabled. NO_FLEX is useful when you have several tables +on the page and you want to distribute excess vertical +whitespace on the page amongst other flex-spacing points on the +page. If there are no others, the final table should be +flex-spaced, i.e. not given the NO_FLEX argument. +

+ +

CAPTION

+ +

+CAPTION allows you to give the table a caption. By +default, the caption appears above the table, but may be attached to +the label that appears beneath the table. See +CAPTION_AFTER_LABEL +in +Captions and labels. +The text of the caption must be surrounded by double-quotes. +

+ +

+Please note that if your table has a caption, you must invoke +TS with the H flag, which also entails the use +of +TH. +

+ +

SHORT_CAPTION

+ +

+SHORT_CAPTION allows you to trim long captions for +inclusion in the List of Tables. The text you supply, surrounded +by double-quotes, is what will appear in the List. +

+ +

LABEL

+ +

+LABEL, if given, appears beneath the table. The text you +supply, surrounded by double-quotes, is how the table is labelled +in both the document proper and the List of Tables. Mom provides +an auto-labelling facility for tables (see +AUTOLABEL), +which, if enabled, overrides the LABEL argument. +

+ +

TARGET

+ +

+TARGET followed by a unique name surrounded by +double-quotes creates a PDF target for the table so that it may be +linked to from other places in the file (with PDF_LINK; see +Producing PDFs with groff and mom). +

+ +

+Please note: The following functionality is available +only with groff 1.22.4 or later. +

+ +

+When +autolabelling +is enabled and the document is processed with +pdfmom, +the target name can be used to generate the target’s label +number in running text if it is entered as a groff string, i.e. of +the form \*[name]. For example, if you +create a target called “foo” for a table whose autolabel +number would be 3, entering +
+ + See + .PDF_LINK foo "Table \*[foo]" + +anywhere in running text would result in a pdf link that reads +“Table 3”. If chapter numbers are being prefixed to +labels, the same string in, say, chapter 5 would produce the pdf +link “Table 5.3”. +

+ +

The .TH macro

+ +

+The TH macro (Table Header), which is required +when you begin a table with .TS H, allows you to +determine what goes in a table’s running header if it spans +multiple pages. Placing .TH under the first row of +tbl data makes the first row the header. If placed under +the second row, the first and second rows form the header, and so +on. +

+ +

+As there are sometimes reasons to run .TS H when +you don’t, in fact, want a running header (e.g. when +your table has a caption), you can suppress it by placing +.TH immediately underneath your tbl formatting +specifications, the last line of which always ends with a period +(see tbl(1)). +

+ +

+See the +H +argument to .TS for examples demonstrating .TH +placement. +

+ +

The .TE macro

+ +

+tbl blocks must be terminated with .TE, +which, as of version 2.0-c, takes a single, optional argument, +SOURCE. (Formerly, TE took a label/caption +argument along with arguments controlling placement.) The argument +is followed by the text of the table’s source, surrounded by +double-quotes. The SOURCE argument may only be used if +MLA +(Modern Language Association) style is enabled. +

+ +

pic support

+ +

+Mom documents can include diagrams generated with the groff +preprocessor pic. If you are unfamiliar with pic, I +recommend downloading a copy of +Making Pictures with GNU PIC +which provides a thorough introduction and contains many examples. +If you use pic, you must pass groff or pdfmom the -p +flag when you process the file. + +

+ +

+Diagrams created with pic begin with the macro +.PS (Pic Start) and end with +.PE (Pic End). Everything between them is +interpreted by the preprocessor as pic instructions. Please note: +Making Pictures with GNU PIC says that .PF can +also be used to terminate a pic diagram, but this is not supported +by mom. +

+ +

+Pic diagrams are always centered. Note that this represents a +change from version 2.0-b of mom, where centering diagrams required +passing -mpic to groff or +pdfmom +on the command line. +

+ +

+In addition, mom treats pic diagrams identically to +floats, +which is to say that if a diagram doesn’t fit on the output +page, she will defer it to the top of the next page while continuing +to process +running text. +ADJUST is ignored whenever a diagram is deferred, except +when moving from column to column on the same page, when the diagram +may need to be optically adjusted. Subsequent diagrams that do not +fit, if any, are output in order immediately after the first. +

+ +

+Lastly, if your diagrams contain text, you may set all the type +parameters for the text (family, font, size, leading) separately +from the pic block with the macro +PIC_TEXT_STYLE. +If you need to change the type parameters within the block +on-the-fly, you must use pic’s native facilities for +doing so. +

+ +

.PS / .PE

+ +

+Macro: PS ++ +Arguments: [ <width> <height> ] + + + [ LEFT ] + + [ ADJUST +|-<vertical adjustment>] + +(unit of measure +required) + ++ [ NO_SHIM ] + + [ NO_FLEX ] + + [ CAPTION "<caption>" ] + + [ SHORT_CAPTION "<short caption>" ] + + [ LABEL "<label>" ] + + [ TARGET "<name>" ] + +
+Macro: PE (no arguments; ends +the pic block) +

+ +

+IMPORTANT: +All arguments to PS must appear on the same line as +.PS. Do not attempt to break them up with the +“line-continued” backslash. You may want to set your +text editor to “wrap” mode in order to see all your +arguments. This annoyance stems from the preprocessor mechanism +itself, not groff or mom. +

+ +

'width' and 'height'

+ +

+The width and height arguments to +.PS are idiosyncratic owing to the preprocessor itself. +Both are optional and both expect a value in inches, so neither +argument should have a +(unit of measure +appended. +

+ +

+If the width argument is supplied, the diagram, but +not any text it contains, is scaled to the given width. If a +literal width argument of 0 (zero) is given and a +height argument is supplied, the diagram, but not any +text it contains, will be scaled to the requested height. In the +case of two non-zero arguments being given, only the height scaling +is applied. +

+ +

LEFT

+ +

+By default, pic diagrams are centred on the page. If you would +prefer them to be flush left, pass PS the LEFT +argument. +

ADJUST

+ +

+ADJUST lets you raise (-) or lower +(+) a diagram +within the space allotted for it +by the amount you specify. This is useful for achieving good +optical centering between surrounding blocks of type. A unit of +measure is required. +

+ +

NO_SHIM

+ +

+NO_SHIM instructs mom not to apply +shimming +after a pic diagram, which she will do automatically when +shimming is enabled, which it is by default. Shimming ensures that +running text after the diagram falls properly on the page’s +baseline grid, +but can result in slightly unequal spacing above and below +(correctable with the ADJUST argument). +NO_SHIM is useful when you have several diagrams on the +page and there are visible differences in the spacing beneath them +as a result of shimming. To ensure a flush bottom margin, the last +diagram on the page should be shimmed, i.e. should not be given the +NO_SHIM argument. +

+ +

NO_FLEX

+ +

+NO_FLEX instructs mom not to apply +flex-spacing +after a pic diagram, which she will do automatically when +flex-spacing is enabled. NO_FLEX is useful when you +have several diagrams on the page and you want to distribute excess +vertical whitespace on the page amongst other flex-spacing points +on the page. If there are no others, the final diagram should be +flex-spaced, i.e. not given the NO_FLEX argument. +

+ +

CAPTION

+ +

+CAPTION allows you to give the diagram a caption. By +default, the caption appears above the diagram, but may be attached to +the label that appears beneath it. See +CAPTION_AFTER_LABEL +in +Captions and labels. +The text of the caption must be surrounded by double-quotes. +

+ +

SHORT_CAPTION

+ +

+SHORT_CAPTION allows you to trim long captions for +inclusion in the List of Figures. The text you supply, surrounded +by double-quotes, is what will appear in the List. +

+ +

LABEL

+ +

+LABEL, if given, appears beneath the diagram. The text you +supply, surrounded by double-quotes, is how the diagram is labelled +in both the document proper and the List of Figures. Mom provides +an auto-labelling facility for diagrams (see +AUTOLABEL), +which, if enabled, overrides the LABEL argument. +

+ +

TARGET

+ +

+TARGET followed by a unique name surrounded by +double-quotes creates a PDF target for the diagram so that it may be +linked to from other places in the file (with PDF_LINK; see +Producing PDFs with groff and mom). +

+ +

+Please note: The following functionality is available +only with groff 1.22.4 or later. +

+ +

+When +autolabelling +is enabled and the document is processed with +pdfmom, +the target name can be used to generate the target’s label +number in running text if it is entered as a groff string, i.e. of +the form \*[name]. For example, if you +create a target called “foo” for a diagram whose +autolabel number would be 3, entering +
+ + See + .PDF_LINK foo "Figure \*[foo]" + +anywhere in running text would result in a pdf link that reads +“Figure 3”. If chapter numbers are being prefixed to +labels, the same string in, say, chapter 5 would produce the pdf +link “Figure 5.3”. +

+ + + +

PIC_TEXT_STYLE

+ +

+Macro: PIC_TEXT_STYLE \ +
++ [ FAMILY ] "<family>" \ + + [ FONT ] "<font>" \ + + [ SIZE ] "+|-<size>" \ + + [ AUTOLEAD ] "<value>" + +

+ +

+Diagrams drawn with pic may contain text, and groff +inline escapes +may be used to alter the text parameters. A problem that arises +from so doing is that, in many cases, it clutters up the pic +code unnecessarily. +

+ +

+PIC_TEXT_STYLE lets you establish the type parameters for text +inside a pic block all at once in cases where so doing +improves the readability of your mom source files. +

+ +

+The arguments to PIC_TEXT_STYLE behave identically to the arguments +to other control macros, explained +here. +They may be given in any order, and you may use as many or as few as +you like. +

+ +

+Note: +Text within pic diagrams does not scale when you provide a +scaling argument to .PS. This is a limitation of the +preprocessor itself, not groff or mom. +

+ +

grap support

+ +

+Grap is a pic preprocessor for creating graphs. Grap +usage is covered in the grap(1) manpage. Its mom +implementation is the same as for pic except that instead of +enclosing directives between +.PS / .PE, +they are enclosed between .G1/.G2. If you use grap, +you must pass groff or pdfmom the -G flag when you process +the file. + +

+ +

+.G1 takes all the same arguments as +PS +with one exception: the argument GRAP must always be given to +.G1. So, for example, a skeleton grap block raised 2 points +and with a caption would be entered: +
+ + .G1 GRAP ADJUST +2p CAPTION "Graph caption" + <grap directives> + .G2 + + +

+ +

eqn support

+ +

+Support for eqn is provided via extensions to the standard +.EQ/.EN macros. eqn usage itself is beyond +the scope of this documentation, but is covered in the manpage +eqn(1). You can also download a copy of Ted +Harding’s + +A Guide to Typesetting Mathematics Using GNU eqn +, +which contains useful examples. If you use eqn, you must give groff or +pdfmom the -e flag. + +

+ +

.EQ / .EN

+ +

+Macro: EQ +
+Arguments: + + [ -L | -C | -I <indent> ] + +(unit of measure +required) + ++ [ ADJUST +|-<vertical adjustment>] + +(unit of measure +required) + ++ [ NO_SHIM ] + + [ NO_FLEX ] + + [ CAPTION "<caption>" ] + + [ LABEL "<label>" ] + + [ SHIFT_LABEL +|-<vertical adjustment> ] + + [ SHORT_CAPTION "<short caption>" ] + + [ TARGET "<name>" ] + + [ CONTINUED | CONT | ... ] +

+ +

+Note: Version 2.0-c change +
+2.0-c introduces revisions to EQ, including the addition +of a dash (-) to the positioning arguments +(-L, -C, and -I) and the removal of a +default value for -I. Other changes include passing all +options to .EQ (including the label) such that +.EN takes only a single, optional argument saying whether +the equation is to be continued at the next invocation of +.EQ. Please read this section carefully if you have +documents containing equations as they may need to be updated. +

+ +

+IMPORTANT: +All arguments to EQ must appear on the same line as +.EQ. Do not attempt to break them up with the +“line-continued” backslash. You may want to set your +text editor to “wrap” mode in order to see all your +arguments. This annoyance stems from the preprocessor mechanism +itself, not groff or mom. +

+ +

The .EQ macro

+ +

+Equations to be set with eqn begin with .EQ, +followed by eqn code. Equations are centered by default, +but may be set flush left or indented from the left margin +if -L or -I are passed as arguments to +.EQ. +

+ +

ADJUST

+ +

+ADJUST lets you raise (-) or lower +(+) an equation +within the space allotted for it +by the amount you specify. This is useful for achieving good +optical centering between surrounding blocks of type. A unit of +measure is required. +

+ +

NO_SHIM

+ +

+NO_SHIM instructs mom not to apply +shimming +after an equation, which she will do automatically when shimming is +enabled, which it is by default. Shimming ensures that running text +after the equation falls properly on the page’s +baseline grid, +but can result in slightly unequal spacing above and +below (correctable with the ADJUST argument). +NO_SHIM is useful when you have several equations on the +page and there are visible differences in the spacing beneath them +as a result of shimming. To ensure a flush bottom margin, the last +equation on the page should be shimmed, i.e. should not be given the +NO_SHIM argument. +

+ +

NO_FLEX

+ +

+NO_FLEX instructs mom not to apply +flex-spacing +after an equation, which she will do automatically when flex-spacing +is enabled. NO_FLEX is useful when you have several +equations on the page and you want to distribute excess vertical +whitespace on the page amongst other flex-spacing points on +the page. If there are no others, the final equation should be +flex-spaced, i.e. not given the NO_FLEX argument. +

+ +

CAPTION

+ +

+CAPTION allows you to give the equation a caption. +Equation captions always appear beneath the equation. +

+ +

SHORT_CAPTION

+ +

+SHORT_CAPTION allows you to trim long captions for +inclusion in the List of Equations. The text you supply, surrounded +by double-quotes, is what will appear in the List. +

+ +

LABEL

+ +

+LABEL, if given, appears on the same baseline as the last line of the +equation, flush with the left or right margin, depending on the +equation’s horizontal position. The text you supply, surrounded by +double-quotes, is how +the equation is labelled in both the document proper and the List of +Equations. Mom provides an auto-labelling facility for equations (see +AUTOLABEL), +which, if enabled, overrides the LABEL argument. +

+ +

SHIFT_LABEL

+ +

+SHIFT_LABEL allows you to raise (-) or lower +(+) the equation label. It’s primary use is to +center equation labels vertically on the equation rather than flush +with the last line. Assuming a three-line equation, +.EQ SHIFT_LABEL -1v would raise the label by +one line, thus centering it vertically on the equation. +

+ +

TARGET

+ +

+TARGET followed by a unique name surrounded by +double-quotes creates a PDF target for the equation so that it may +be linked to from other places in the file (with PDF_LINK; see +Producing PDFs with groff and mom). +

+ +

+Please note: The following functionality is available +only with groff 1.22.4 or later. +

+ +

+When +autolabelling +is enabled and the document is processed with +pdfmom, +the target name can be used to generate the target’s label +number in running text if it is entered as a groff string, i.e. of +the form \*[name]. For example, if you +create a target called “foo” for an equation whose +autolabel number would be 3, entering +
+ + See + .PDF_LINK foo "Equation \*[foo]" + +anywhere in running text would result in a pdf link that reads +“Equation 3”. If chapter numbers are being prefixed to +labels, the same string in, say, chapter 5 would produce the pdf +link “Equation 5.3”. +

+ + +

The .EN macro

+ +

+A block of eqn code is terminated with .EN. +

+ +

+If an equation needs to span multiple lines, possibly aligned +with eqn’s 'mark' and 'lineup' +directives, separate invocations of .EQ/.EN +are required for each line, and the optional argument, +CONTINUED (or CONT, or ... [three +dots, an ellipsis]), must be passed to .EN. +

+ +

+If -L or -I is given to the first +.EQ of a multi-line equation, they remain in effect +until an .EN without the CONTINUED argument +is reached. +

+ +

+Mom does not treat equations as floats, therefore it is possible to +begin an equation on one page and terminate it on the next. If you +wish to keep all lines of an equation together, you must wrap the +equation, including all invocations of .EQ/.EN, inside +a +float. +

+ +

refer support

+ +

+refer support is covered in the section +Bibliographies and references. +

+ +

Captions and labels

+ +

AUTOLABEL
CAPTION_AFTER_LABEL
MLA—MLA-style captioning and labelling
Set style parameters for captions, labels, and sources

+ +

+Mom includes facilities for adding captions and labels to figures, +tables, equations, and pdf images, including auto-labelling. If +Lists of Figures, Tables, and Equations are desired, captions (if +any) and labels (if any) are collected and output in the Lists with +the appropriate page number. +

+ +

+The distinction between a caption and a label is that labels are +identifiers, e.g. “Fig. 1” or “Table 3”, +while captions are descriptive or informative. For most types of +writing, it is usual to provide both. +

+ +

+By default, mom sets captions above figures (i.e. pic output and +pdf images) and tables. This behaviour may be modified with the +macro +CAPTION_AFTER_LABEL. +Equations always have their captions set underneath. All aspects of +the text style for captions may be set with the macro +CAPTIONS. +

+ +

+Labels for tables are set underneath the table unless the +MLA +macro has been invoked, in which case the label and caption appear +above the table, per MLA style, and the source for the table, if +any, appears underneath. Labels for figures are set underneath. +Equation labels, by default, are set on the same baseline as the +last line of the equation. Like captions, all aspects of text style +for labels may be established with a single macro +LABELS. +Furthermore, mom can autolabel figures, tables, and equations, with +or without a prefixed chapter number. +

+ +

Autolabel

+ +

+Macro: AUTOLABEL_EQUATIONS +
+Macro: AUTOLABEL_IMAGES +
+Macro: AUTOLABEL_PIC +
+Macro: AUTOLABEL_TABLES +
+Arguments: + +[ PREFIX "<string>"] [ SUFFIX "<string>"] [ PREFIX_CHAPTER [ <n> ] ] + +

+ +

+AUTOLABEL_<type> takes care of labelling <type> by +identifying each with a separate, incrementing numeric scheme, which +is also collected for output in Lists of Figures, Equations, and +Tables. +

+ +

+Autolabelling may be disabled on-the-fly by giving any argument +other than PREFIX, SUFFIX, or +PREFIX_CHAPTER to the appropriate macro. For example, +
+ + .AUTOLABEL_IMAGES NO + +would disable autolabelling of images. +

+ +

Prefixes and suffixes

+ +

+By default, when AUTOLABEL is enabled, the label numbers are +prefixed, and, in the case of equations, suffixed, with strings such +that they appear for tables as “Table <n>”, for +pic diagrams and pdf images as “Fig. <n>”, +and for equations as “Eq. (<n>)”. +

+ +

+You can use PREFIX <"string"> to change what +comes before the automatic numbering. For example, if you are +including musical excerpts in your document, MLA style requires that +they be labelled “Ex. <n>”. Since musical +excerpts are likely to be scanned images (in pdf format, don’t +forget), you have to change the prefix string for pdf images: +
+ + .AUTOLABEL_IMAGES \ + PREFIX "Ex. " \ + SUFFIX "" + +If you need a suffix after the automatic numbering, use +SUFFIX <"string">, like this: +
+ + .AUTOLABEL_IMAGES \ + PREFIX "(Fig. " \ + SUFFIX ")" + +Note from the above that both arguments, PREFIX and +SUFFIX, are required should you want either. Two +adjacent double-quotes leaves the string blank. +

+ +

+Note: +In automatically formatted +“Lists of ...”, +label number prefixes are stripped when autolabelling is enabled. +

+ +

Prefixing chapter numbers

+ +

+If you would like mom to prefix chapter numbers to the label, +pass AUTOLABEL_<type> the argument +PREFIX_CHAPTER. +

+ +

+If for some reason you need to specify the chapter number, +you may do so by passing the number as an argument to +PREFIX_CHAPTER. Subsequent chapters or major sections +will increment by one as expected. +

+ +

+Note: +For the purposes of labelling, mom treats +DOCTYPE DEFAULT +as if it were DOCTYPE CHAPTER, hence, with +PREFIX_CHAPTER, each collated DEFAULT +doctype’s prefixed “chapter” number is +incremented and the label number itself reset to “1”. +If you do not supply the PREFIX_CHAPTER argument, the +label number is not reset automatically. To reset it, invoke +.AUTOLABEL_<type> after each +COLLATE. +

+ +

+Macro: SET_AUTOLABEL FIG | TBL | PIC | EQN <n> +

+ +

+You may sometimes need to set or reset the autolabel number for a +particular type of pre-processor or for PDF images. This is likely +to occur if you are using +FLOAT +in conjunction with the TO_LIST argument. +

+ +

+For example, if your document has Figures (PDF images, pic diagrams) +and you want your tables to be labelled as Figures as well, you have +to wrap the tables inside a float and label the float manually as +“Fig. n”, sending it to the List of Figures with +TO_LIST FIGURES. +

+ +

+Mom does not autolabel floats or assign them automatically +to a list, so she doesn’t know you’ve interrupted the +auto-incrementing label numbers. Use SET_AUTOLABEL get her back on +track. The number you give as an argument after telling her which +kind of label number to set is the one you want to appear next. +
+ + .SET_AUTOLABEL FIG 6 + +means the next autolabelled Figure will be “Fig. 6.” +

+ +

Captions after labels

+ +

+Macro: CAPTION_AFTER_LABEL IMG | PIC | TBL | ALL [ <anything> ] +

+ +

+By default, mom sets captions above figures (pic output +and pdf images) and tables; labels are always underneath. +

+ +

+.CAPTION_AFTER_LABEL, with one of the required arguments, +instructs mom to attach captions directly to the appropriate +labels, beginning on the same line. Any argument after the first +disables this behaviour, restoring caption placement to mom’s +default. For example, +
+ + .CAPTION_AFTER_LABEL ALL + +would enable captions after labels globally, while a subsequent +
+ + .CAPTION_AFTER_LABEL IMG OFF + +would disable captions after labels for pdf images only. +OFF can be anything you like (X, +NO, etc). +

+ +

+If +MLA +is enabled, there’s no need to invoke +CAPTION_AFTER_LABEL as this is implied. +

+ +

+Note: +A separate invocation of .CAPTION_AFTER_LABEL is required +for each one of the required first arguments. You cannot, for +example, do +
+ + .CAPTION_AFTER_LABEL IMG TBL + +Rather, you must do +
+ + .CAPTION_AFTER_LABEL IMG + .CAPTION_AFTER_LABEL TBL + +

+ +

MLA-style captioning and labelling

+ +

+Macro: MLA [ <anything> ] +

+ +

+Modern Language Association style dictates that captions should +always go after labels. Furthermore, labels and captions for tables +should go above the tables, with the source for the table, if +any, underneath. +

+ +

+Invoking .MLA by itself takes care of these details. If +you need to disable MLA-style captioning and labelling mid-document, +.MLA OFF does the trick. OFF can be +anything you like (X, NO, etc). +

+ +

Style parameters for captions, labels and sources

+ +

+ +

+Note: +Arguments may be broken into several lines using the +“line-continued” backslash (\), as shown above. +

+ +

+Additional note: +Mom’s default style for labels, captions, and sources is +the same as the style used for running text, with two exceptions: +labels are set in bold, except for eqn which is roman medium, and +the autolead value for all three is “2”, effectively +tightening the lead. Furthermore, they are quadded left (except +eqn, which is quadded right.) +

+ +

+With the exception of ADJUST and QUAD (which +requires a bit of explanation), the style arguments to CAPTIONS, +LABELS, and SOURCES (which is only available +for tables) behave identically to the +arguments to control macros. +

+ +

+The first, required argument after CAPTIONS, +LABELS, or SOURCES indicates the preprocessor +type for which you are setting the parameters. (For convenience +PDF_IMAGE—argument IMG—is here treated as a +preprocessor.) FLOATING sets the style for the macros +CAPTION +and +LABEL, +which are used to label floats, quotes, and blockquotes. +

+ +

+An argument of ALL sets a unified style for all +preprocessors, floats, quotes, and blockquotes. If the +ALL argument is given, arguments to subsequent +invocations of CAPTIONS, LABELS, or +SOURCES overwrite only the explicitly named style +parameters. +

+ +

QUAD — quadding of labels, captions, and sources

+ +

• pic, tbl, pdf images

+ +

+By default, figures (pic output and pdf images) and tables +have their captions and labels set quad left. Sources (for +tables) are also set quad left. Equations have their labels +set quad right, and their captions centered. +

+ +

+Regardless of the quad direction, captions, labels and sources +are set on the width of the figure, table, or pdf image +unless you pass the optional ON_LL argument to +QUAD <direction>, in which case +the prevailing document line length is used instead. +

+ +

• eqn

+ +

+Equations behave differently. By default, equation labels are +set flush right with the page’s right margin regardless of +equation positioning, which is, again by default, centered. If the +equation is positioned left, the label will appear at the right +margin regardless of the direction you give to QUAD. If +the equation is indented with the +-I <indent> option, a quad +direction of LEFT is observed, but may overprint the last +line of the equation. +

+ +

+Note that there is no CENTER option for equation labels, +and that captions are always quadded over the prevailing document +line length. +

+ +

• quotes and blockquotes

+ +

+Floating labels attached to QUOTEs are quadded on the +prevailing document line length, and require the INDENT +argument if you want to align them with the left and/or right edges +the quote. +

+ +

+Floating labels attached to BLOCKQUOTEs are always quadded on +the indent and line length of the blockquote. +

+ +

• floats

+ +

+Floating labels and captions attached to FLOATs are always +quadded over the prevailing document line length, and require the +INDENT argument if you want to align them with the left +and/or right edges of the float’s contents. +

+ +

INDENT

+ +

+The INDENT argument may only be used if the label +or caption type is FLOATING, and only applies to +FLOATs and QUOTEs, not BLOCKQUOTEs. +

+ +

+It is not possible for mom to know the width of a float before +setting a label or caption attached to a float. She therefore sets +it on the prevailing document line length. While this isn’t +much of an issue when the label or caption quad is CENTER, +you may want to adjust the horizontal positioning when the quad is +LEFT or RIGHT. +

+ +

+INDENT, with a numeric value to which a +unit of measure +is appended, allows you to indent a floating label or caption so +it lines up with the left edge of a FLOAT or QUOTE. +INDENT RIGHT (with a value) allows you to shorten the +line length to the appropriate width. If you need both a left and +right indent, invoke LABELS or CAPTIONS twice, +one instance containing INDENT <indent> and +the other INDENT RIGHT <indent>. +

+ +

ADJUST

+ +

+The ADJUST argument allows you to add(+) or +subtract (-) vertical space between labels and captions +and the output to which they are attached. The argument requires a +unit of measure. +For example, if you find that table labels are a bit too close to +the table itself, +
+ + .LABELS TBL ADJUST +3p + +would put three extra points of space between the bottoms of tables +and the labels that appear beneath them. +

+ +

Lists of Figures, Tables, and Equations

+ +

+Besides a +Table of Contents, +mom can generate Lists of Figures, Tables, and Equations. Labels +and captions are collected and concatenated, and output in lists +with the appropriate page number, just like a Table of Contents. +Including such lists in a document is as simple as adding whichever +you need of +
+ + .LIST_OF_FIGURES + .LIST_OF_EQUATIONS + .LIST_OF_TABLES + +to the end of your input file. +

+ +

+Also like the Table of Contents, entries in the Lists’ output +are clickable PDF links when a document is viewed at the screen. +

+ +

Placement of Lists

+ +

+Lists normally appear after the Table of Contents, and continue +the page numbering scheme used for it. By default, the Table of +Contents begins on roman-numeral page “i”. +

+ +

+If you are using mom’s +AUTO_RELOCATE_TOC +feature, you have two options for placement of the Lists within the +document. If you want the Lists shifted to the top of the document +along with the Table of Contents, invoke the Lists macros after +.TOC. +If you prefer to have the Lists at the end of the document, invoke +the Lists macros before .TOC. +

+ +

+Lists shifted with the Table of Contents do not appear in the Table +of Contents itself, but do appear as clickable links in the PDF +outline typically available in the left panel of most PDF viewers. +Lists that are not shifted with the Table of Contents appear in both +the Table of Contents itself and the PDF outline. +

+ +

Macros to generate Lists

+ +

+Macro: LIST_OF_EQUATIONS +
+Macro: LIST_OF_FIGURES +
+Macro: LIST_OF_TABLES +
+Arguments: + + [ TITLE_STRING "<string>" ] [ START_PAGENUM <page number> ] + +

+ +

+The first optional argument to the LIST_OF_<type> +macros allows you to change the title that appears at the top of the +page. This is useful not only for internationalization, or to meet +the requirements of various style guides, but is also useful +for, say, documents containing musical examples, which, per +MLA-style, should be labelled “Example ” or +“Ex. ”. When it comes time to output the List of +Figures (to which musical examples, usually scanned pdf images, belong), +
+ + LIST_OF_FIGURES TITLE_STRING "List of Examples" + +ensures that the title of the List is correct. +

+ +

+The second optional argument allows you to give a starting page +number for a list in cases where mom’s pagination scheme does +not provide the List with the starting page number you want. +

Formatting and style parameters for Lists

+ +

+Like the Table of Contents, nearly every aspect of Lists can be +designed independently of a document’s overall style. By +default, Lists follow the formatting and style parameters of the +Table of Contents, both mom’s defaults and any changes you may +have made to the Table of Contents. +

+ +

+If you wish to make changes to any aspect of Lists formatting +or styling, the macro LISTS_STYLE provides all the +tools necessary. It is unlikely that you’ll want the +formatting of the various list types to differ one from the other, +so LISTS_STYLE applies to all Lists. In the event that +you do need to change some aspect of the formatting for different +list types, simply invoke LISTS_STYLE immediately prior +to each list whose formatting needs to be changed. +

+ +

Lists style

+ +

+Macro: LISTS_STYLE + +Arguments: + + FAMILY <family> \ + + FONT <font> \ + + PT_SIZE <size> \ + + LEAD <leading> \ + + TITLE_FAMILY <family> \ + + TITLE_FONT <font> \ + + TITLE_SIZE +|-<size> \ + + TITLE_QUAD LEFT | CENTER | RIGHT \ + + TOC_HEADER_UNDERSCORE default = none + + TITLE_COLOR <color> \ + + PN_FAMILY <family> \ + + PN_FONT <font> \ + + PN_SIZE +|-<size> \ + + EQN_PN_PADDING <placeholders> \ + + FIG_PN_PADDING <placeholders> \ + + TBL_PN_PADDING <placeholders> \ + + PAGENUM_STYLE DIGIT | ROMAN | roman | ALPHA | alpha \ + + NO_PAGINATION + +

+ +

+Note: +Arguments may be broken into several lines using the +“line-continued” backslash (\), as shown above. +

+ +

+FAMILY is the family for the entirety of Lists pages. +

+ +

+FONT is the font for the entirety of Lists pages. +

+ +

+PT_SIZE is the base point size for the entirety of Lists +pages. +

+ +

+LEAD is the base leading for the entirety of Lists pages. +

+ +

+TITLE_FAMILY is the family for the Lists titles if you +want it different from the family otherwise used for the Lists +pages. +

+ +

+TITLE_FONT is the font for the Lists titles if you want +it different from the font otherwise used for the Lists pages. +

+ +

+TITLE_SIZE tells mom by how much to increase +(+) or decrease (-) the point size of the +titles relative to the overall point size of Lists pages. +

+ +

+TITLE_QUAD tells mom how to position the title +horizontally. +

+ +

+TITLE_COLOR sets the colour for the titles. The colour +must be pre-initialized with +NEWCOLOR +or +XCOLOR. +

+ +

+PN_FAMILY sets the family for entry pagenumbers. +

+ +

+PN_FONT sets the font for entry pagenumbers. +

+ +

+PN_SIZE tells mom by how much to increase (+) +or decrease (-) the point size of entry pagenumbers +relative to the overall point size of Lists pages. +

+ +

+EQN_PN_PADDING, FIG_PN_PADDING, and +TBL_PN_PADDING tells mom how many placeholders to reserve +for the entry pagenumbers in their respective Lists. If, for example, +a document with both tables and figures runs to over a hundred +pages, but there are no tables after page 99, +
+ + LISTS_STYLE FIG_PN_PADDING 3 + LISTS_STYLE TBL_PN_PADDING 2 + +would prevent an unneeded, reserved placeholder from putting too +much space between the leader and the entry pagenumber in the List of +Tables. +

+ +

+The padding in effect, unless you change it, is whatever was set for +the Tables of Contents; mom’s default is “3”. +

+ +

+PAGENUM_STYLE tells mom which pagination format to use +for the page numbers of the Lists pages themselves. By default, +since Lists observe what is in effect for the Table of Contents, the +pagination format is “roman”. Please note that the +starting page number for any of the Lists is given as an argument to +the +LISTS_0F_<type> +macro. +

+ +

+NO_PAGINATION disables pagination of Lists pages. +

+ +

Shaded backgrounds and frames (boxes)

+ +

+Mom lets you add shaded backgrounds and frames to text and other +material. For convenience, she calls backgrounds and frames +“boxes.” Entire passages may be boxed, or individual +document elements like headings, quotes, or pre-processor output. +Furthermore, boxes may be nested. +

+ +

+Boxes start on the baseline where the boxed material would have +started were it not for the box, subject to minor aesthetic +corrections mom takes the liberty of making. +

+ +

+Boxes extend from the current left margin to the current right +margin, respecting any active left and/or right indents. There are +two exceptions, +EPIGRAPH BLOCK +and +BLOCKQUOTE, +which are discussed +here. +

+ +

+After a box is started, active left and right indents are +cleared. The box’s inset determines the new left and right +margins. Indents set inside a box are relative to the inset. +When a box is stopped, formerly active left and right indents +are restored. +

+ +

+Frames are drawn from the perimeter inward. The inset is +relative to the inner edge of the frame. +

+ +

+If a box (including the bottom inset) can complete on a page, it +does, even if there is no further room for type. This may, on +occasion, result in slight deviations from normal bottom margin +alignment. +

+ +

+Boxes span pages whenever the boxed material continues on the next +page. Spanning boxes extend fully to the bottom margin of the page +on which they begin, leaving a slightly larger inset at the bottom +than around the other sides. +

+ +

+When there is not enough room to set at least one line of type +inside a box, mom defers starting the box until the next page, +leaving a gap. +

+ +

+Boxed material is not +shimmed +or +flexed. +If either was active prior to the box, it is restored when the box +ends and mom automatically shims or flexes whatever comes next. +

+ +

+NOTE: +Shaded backgrounds and frames are not available when your +PRINTSTYLE +is TYPEWRITE or when +COLUMNS are enabled. +

+ +

BOX

+ +

+ +

+Without arguments, BOX begins a shaded grey background. +The material inside is inset by one +pica. +Any other type of box requires at a minimum either +SHADED or OUTLINED. In the case of boxes +that are to contain pdf images or pre-processor material for +eqn, +pic, +or +grap, +IMG, EQN, PIC, or GRAP +must also be given. Note that +tbl +does not have this requirement. +

+ +

+BOX is a +toggle macro, +so any argument other than one in the list completes the box +(QUIT, END, X, etc). +

+ +

+Boxes should be started inside toggle macros like +QUOTE +or +FLOAT +just after the macro is called, and terminated just before toggling +the macro off (unless you wish the box to enclose further material). +

+ +

+Non-toggle macros like +HEADING +or +PP +require that the box be started beforehand. Boxed pre-processor +material must be fully enclosed by BOX / BOX OFF, as +in this recipe for a one-off boxed pic diagram: + +.BOX +.PS +<pic commands> +.PE +.BOX OFF + +Arguments to BOX are not sticky. Each time you invoke BOX, you +must invoke it with arguments unless you want mom’s default grey +background. If all or several boxes in a document require the same +arguments, create a macro at the top of the input file that calls +BOX with the arguments you want, e.g. + + .de PINK_BOX + .BOX \ + SHADED pink \ + OUTLINED darkred \ + WEIGHT 1p \ + INSET 9p + .. + +.PINK_BOX may then be used instead of .BOX any +time you want a box with those arguments. +

+ +

SHADED | OUTLINED

+ +

+SHADED or OUTLINED are required. Both may +be given, resulting in a shaded background with a frame, and both +require a colour, e.g. + + .BOX SHADED blue OUTLINED black + +The colour may be +

+ +

an xcolor name
a colour initialized with + NEWCOLOR + or + XCOLOR +
an RGB hexadecimal string beginning with (e.g. #FF0000)

+ +

+Note that without SHADED, the above would simply draw a +black frame. +

+ +

WEIGHT

+ +

+Mom’s default weight for OUTLINED is 1/2 +point. +If you’d like to change it, give WEIGHT the desired +value with a unit of measure appended, typically points, e.g. + + .BOX OUTLINED black WEIGHT 1p + +

+ +

INSET

+ +

+Mom’s default inset for boxes is one +pica +on all sides. If you’d like a larger or smaller inset, give +INSET the distance you want with a unit of measure +appended, e.g. + + .BOX SHADED pink INSET 2m + +

+ +

ADJUST

+ +

+If you are not happy with the starting position of a box, you can +change it by giving ADJUST the distance you want it +raised (-) or lowered (+) with a unit of measure appended. For +example, to lower a box three points, + + .BOX OUTLINED black ADJUST +3p + +To raise it, + + .BOX OUTLINED black ADJUST -3p + +

+ +

PIC / GRAP / EQN / IMG

+ +

+The PIC argument must be given to BOX if the box contains +any +pic +diagrams. Likewise, graphs made with +grap, +equations made with +eqn, +and +pdf images +require a corresponding GRAP, EQN, or +IMG argument. +

+ +

+If you’re boxing a single diagram, graph, or pdf image, wrap +it in a float, like this: + + .FLOAT + .BOX PIC <other parameters> + .PS + <pic input> + .PE + .BOX OFF + .FLOAT OFF + +Notice that in the case of pdf images, pic, and grap, this +represents a change from the norm, where the use of FLOAT may be +destructive and is discouraged. +

+ +

Additional notes on BOX usage and behaviour

+ +

QUOTE, BLOCKQUOTE, EPIGRAPH, FLOAT

+ +

+QUOTE, +BLOCKQUOTE, +EPIGRAPH, +and +FLOAT +require that boxes be started after they are +invoked and stopped just before they are toggled off: + + .QUOTE + .BOX <parameters> + Text of quote + .BOX OFF + .QUOTE OFF + +

+ +

CODE

+ +

+If you’re boxing +CODE +that’s wrapped inside +QUOTE, +as described +here, +set the quote indent to “0” with + + .QUOTE_STYLE INDENT 0 + +so that the box’s leftmost inset is respected. +

+ +

+Here’s a recipe for setting boxed code with an 18-point inset: + + .QUOTE_STYLE INDENT 0 + .QUOTE + .CODE + .BOX INSET 18p + Hello, world. + .BOX OFF + .QUOTE OFF + +Note that CODE, wrapped inside QUOTE, does not require a corresponding CODE OFF. +

+ +

Description of boxed BLOCKQUOTES and EPIGRAPH BLOCKS

+ +

+When you box a BLOCKQUOTE, or an EPIGRAPH with the BLOCK +argument, the box is centred on the page and is only as wide as the +blockquote or epigraph plus the box’s inset. +

+ +

+QUOTE and EPIGRAPH (without the BLOCK argument), on the +other hand, set the box fully to the left and right margins. +

+ +

Leftover box syndrome

+ +

+Boxed quotes and blockquotes sometimes exhibit leftover box +syndrome, where the page after a fully terminated boxed quote or +blockquote begins with an empty bit of box. Equally, you may +sometimes see the lower edge of a quote’s or +blockquote’s box falling slightly below the page’s +bottom margin. +

+ +

+The solution in both situations is to use the ADJUST +argument to raise or lower the box’s starting position. +Leftover box syndrome is usually fixed by raising the box slightly. +When the box runs too deep, lowering it is generally recommended, +although this will result in a widowed line at the top of the next +page. In either case, some experimentation is necessary. +

+ +

SLIDES

+ +

+On a slide with no pauses, boxes behave as they do in printed +documents. +

+ +

+When a slide contains pauses, only the material up to the first +pause is boxed. As subsequent material is revealed, the box changes +location, moving down to surround each new item. This behaviour +persists until the box is stopped, making it useful for highlighting +material as it is revealed. +

+ +

Footnotes

+ +

+You don’t have to worry about boxes encroaching on footnotes. +Mom makes sure they don’t. +

+ +

Page colour

+ +

+Mom lets you change the page (“paper”) colour +from white to anything you like. While this has limited application +in printed documents, it can be effective in +slide presentations. +

+ +

PAGE_COLOR

+ +

+Macro: PAGE_COLOR <color> | OFF | off +

+Aliased as PAGE_COLOUR, SLIDE_COLOR, +and SLIDE_COLOUR. +

+ +

+When you invoke PAGE_COLOR with a color argument, the +current and subsequent pages turn the colour you request. If +more than one instance of PAGE_COLOR appears before a page break, +including PAGE_COLOR OFF, only the last applies. +

+ +

+Note: +Unlike other +toggle macros, +PAGE_COLOR requires the use of OFF or off +to terminate it rather than an arbitrary string (OFF, +QUIT, END, X, etc). +

+ +

+ + + + + + + + +

Back to Table of Contents

Top

Next: Page headers/footers, pagination

+ +

+ + + diff --git a/contrib/mom/momdoc/inlines.html b/contrib/mom/momdoc/inlines.html new file mode 100644 index 0000000..8613161 --- /dev/null +++ b/contrib/mom/momdoc/inlines.html @@ -0,0 +1,1112 @@ + + + + + + + + Mom -- Inline escapes + + + + + + + +

+ + + + + + + +

Back to Table of Contents

Next: Coloured text

+ +

Inline escapes

+ +

+List of inline escapes +

+ +

Introduction

+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, or use +ESC_CHAR to change the escape +character to something other than the backslash, which lets you +use a single backslash as 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 inline escapes. +

+ +

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

+ +

List of inline escapes

+ +

Mom’s personal inline escapes +
Commonly-used groff inline escapes +
- \f Font control
- \h Inline horizontal motions
- \v Inline vertical motions
- \w String width function
- \l Horizontal line drawing function
- Special characters

+ +

+ + + +

Mom’s personal inline escapes

+ +

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

+ +

Notes 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 as +part of 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]. You may, in such cases, prefer to +use the simpler groff inline escape +\f. +

+ + + +

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 +
+ + \*S[12] + +Entering either \*[SIZE] or +\*S[] with no argument reverts to the former +point size. +

+ +

+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. + +Please note that inline size changes do not update the leading if +AUTOLEAD +is enabled. +

+ +

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 as part of +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” one kern unit away +from the letter F, and the letter A in “WATER” four +kern units closer to the letter W. Additionally, the letter T in +“WATER” is moved five 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). +

+ +

+The default size of a kern unit is 1/36 of the current point size; +this may be changed by invoking the macro .KERN_UNIT +with the desired value, which represents a fraction of the current +point size. For example, to change the kern unit to 1/54 of the +current point size, +
+ + .KERN_UNIT 54 + +To restore the kern unit to its default, invoke +.KERN_UNIT with an argument of DEFAULT. +

+ + +

Notes 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 as part of 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 the BU or FU escapes between characters +pairs that are already automatically kerned (see +KERN) +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 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. + +and + + \*[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 as part of +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.75]. You may, in such cases, prefer +to use the native groff inline escape +\h. +

+ + + +

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 in conjunction with the inline escape, +\*[RULE]. +

+ +

+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 as part of +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]. +You may, in such cases, prefer to use the native groff inline +escape +\v. + +

+ + + +

Terminate a line without advancing on the page

+Sometimes, you want mom to break a line but not advance on the page. +This can be accomplished with the macro +EL +or with the escape \*[B]. Simply attach +\*[B] 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.) To +do so, simply attach the escape \*[TB+] to +the end of the input line in previous tab, like this: +
+ + .TAB 1 + Some text\*[TB+] \" In tab 1 + Some more text \" In tab 2, same baseline. + + +\*[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[.l]u', 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[.l]u'. 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. +

+ +

+Note: +\*[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] + +whereas 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> +

+ +

+• Must not have a +unit of measure +appended. +
+ Argument must be greater than 0 and less than 100; decimal +fractions are allowed. +

+ +

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

+ +

+ + + +

Commonly-used 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[<family><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. +

+ +

+Note: +\h'<distance>' is exactly equivalent to a +\*[FWD n<unit>]. +

+ +

+To move backwards by the same amount, do +
+ + \h'-1.25i' + +

+ +

+Note: +\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. +

+ +

+Note: +\v'<distance>' is exactly equivalent to +\*[DOWN n<unit>]. +

+ +

+To move upward an equivalent amount, do +
+ + \v'-.6m' + +

+ +

+Note: +\v'<-distance>' is exactly equivalent to +\*[UP n<unit>]. +

+ +

+Important: +The vertical motion of \v only affects 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 in 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 \w is used in place of a +numeric argument +to a macro and 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 \\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 encountered 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 +
+and 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 +PDF_IMAGE +or +PSPIC. +

+ + + +

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 \# or .\" + Fixed-width space \<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] + Open (left) single-quote \[oq] + Close (right) single-quote \[cq] + 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] + +
+ +

+ + + + + + + + +

Back to Table of Contents

Top

Next: Coloured text

+ +

+ + + diff --git a/contrib/mom/momdoc/intro.html b/contrib/mom/momdoc/intro.html new file mode 100644 index 0000000..3e25631 --- /dev/null +++ b/contrib/mom/momdoc/intro.html @@ -0,0 +1,487 @@ + + + + + + + + + What is mom? + + + + + + + +

+ + + + + + + +

Back to Table of Contents

Next: Definitions

+ +

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 in Portable Document Format (.pdf) and +PostScript (.ps). She’s aimed at three kinds of users: +

+ +

Typesetters who suspect groff might be the right + tool for the job but who are frustrated, + intimidated, or puzzled by groff’s terse, + not-always-typographically-intuitive + primitives; +
Writers who need to format their work easily, with a + minimum of clutter; +
Newcomers to groff, typesetting, or document processing + who need a well-documented macro set to get them started. +

+ +

+Mom is actually two macro packages in one: a very complete set +of typesetting macros, and an equally thorough set of document +formatting macros. The typesetting macros afford fine-grained +control over all visible aspects of page layout and design (margins, +fonts, sizes, kerning, etc), while the document formatting macros +focus on the logical structure of a document (titles, headings, +paragraphs, lists, etc) and call on groff to render logical +structure into pleasing type. +

+ +

Typesetting with mom

+ +

+Mom’s typesetting macros control the basic parameters +of type: margins, line lengths, 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. +

+ +

+The typesetting macros also provide the means to create horizontal +and vertical rules, rectangles (boxes, frames), and ellipses +(circles). +

+ +

+In terms of typographic control, the typesetting macros provide +access to groff’s primitives in a way that’s consistent, +sensible, and easy to use. With them, you can create individual +pages designed from the ground up. Provided you have not signalled +to mom that you want document processing (via the +START +macro; see below), every typesetting 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 experience have convinced me that no program can ever +replace the human eye and human input when it comes to high quality +typesetting. Words and punctuation on the printed page are too +variable, too fluid, to be rendered flawlessly by any algorithm, +no matter how clever. +

+ +

+Mom, therefore, does not try to guess solutions for issues like +hanging punctuation, or left-margin adjustments for troublesome +letters like T, V and W. Rather, she provides tools that allow +knowledgeable typesetters to handle these typographic challenges in +ways that are easier and more intuitive than manipulating groff at +the primitive level. +

+ +

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’d like your headings underlined, +or in caps, or centred rather than flush left, 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 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 an +old-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 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 as an encrypted password. This does +not make for happy-camper writers, who either find themselves stuck +with a formatting style they don’t 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 initial set of reasonable defaults, but anything that +is not to your liking can be changed. 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 term “user interface” in +conjunction with document processing. Since formatting takes +place inside a text editor, little thought is given to the +look and feel of the formatting commands. Mom attempts to +rectify this by providing users with a consistent, readable +“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 easier to decipher, +typographically and structurally. +

+ +

+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 primarily for PDF or PostScript output, although +with +PRINTSTYLE TYPEWRITE +she produces acceptable terminal copy. No attempt is made 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 unavoidable (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? At some point, one has to decide for whom +the documentation is intended. Making the wrong choice 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 use +the command line, how to use a text editor, etc). I run GNU/Linux, +and while the documentation may exhibit a GNU/Linux bias, mom +and groff can, in fact, be run on other platforms. +

+ +

+The documentation further assumes users 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. The most complete and up-to-date source of information 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. +

+ +

+Groff has ancillary programmes (pre-processors) for generating +tables (tbl), diagrams (pic), and +equations (eqn), which may be used in conjunction +with mom. The manuals describing their usage are found at: +
+ +  tbl http://www.kohala.com/start/troff/v7man/tbl/tbl.ps +
+  pic http://www.kohala.com/start/troff/gpic.raymond.ps +
+  eqn http://www.kohala.com/start/troff/v7man/eqn/eqn2e.ps + +

+ +

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

+ +

How to read macro arguments

+ +

+The concise descriptions of macros in this documentation typically +look like this: +

+ +

+Macro: MACRO_NAME arguments +

+ +

+arguments lists the macro’s +arguments using conventions that should be familiar to anyone who +has ever read a manpage. Briefly: +

+ +

Macro arguments are separated from each other by spaces.
If an argument is surrounded by chevrons + (< >), it’s a description + of the argument, not the argument itself. +
If an argument begins with or is surrounded by double-quotes, the + double quotes must be included in the argument. +
If the user has a choice between several arguments, each of the + choices is separated by the pipe character + (|), which means “or.” +
Arguments that are optional are surrounded by square brackets.
<off> or <anything> in an argument + list means that any argument other than those in the argument + list turns the macro off. +

+ +

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 (in caps, lowercase, or a mixture thereof). This permits +choosing whatever works for you: OFF, end, +Quit, Q, X, and so on. +

+ +

+Since these macros toggle things on and off, the argument list +simply reads toggle. +

+ +

Examples

+ +

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

+ + + + + + + + +

Back to Table of Contents

Top

Next: Definitions

+ +

+ + + diff --git a/contrib/mom/momdoc/letters.html b/contrib/mom/momdoc/letters.html new file mode 100644 index 0000000..3021eb2 --- /dev/null +++ b/contrib/mom/momdoc/letters.html @@ -0,0 +1,577 @@ + + + + + + + + + Mom -- Writing letters + + + + + + + +

+ + + + + + + +

Back to Table of Contents

Next: Quick reference guide

+ +

Writing letters

+ +

Introduction
Tutorial
Mom’s default letter style
The letter macros

+ +

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 – writing letters

+ +

+Mom letters begin, like all mom-processed documents, with +reference macros +(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. +

+ +

+Please note that if you choose PRINTSTYLE TYPEWRITE, +there’s no need to give the SINGLESPACE option, as +this is the unalterable default for letters. +

+ +

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

+ +

+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 a 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. If you omit the +closing, mom simply adds your name (from AUTHOR), again with enough +space 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, 2010 + .TO + GUILLAUME BARRIÈRES + Minidoux Corporation + 5000 Pannes Drive + Redmond, Virginia + .FROM + Y.P. GUIQUE + 022 Umask Road + St-Sauveur-en-dehors-de-la-mappe, Québec + .GREETING + Dear Mr. Barrières, + .PP + It has come to my attention that you have once again been + lobbying the US government to prohibit the use of open source + software by endeavouring to outlaw so-called "warranty + free" applications. + .PP + I feel it is my duty to inform you that the success of your + operating system relies heavily on open source programs and + protocols, notably TCP/IP. + .PP + Therefore, in the interests of your corporation’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. +

+ +

Default letter style

+ +

+In letters, if the order of header macros is +

.DATE
.TO (the addressee)
.FROM (the addresser)
.GREETING (“Dear Whoever,” “To Whom It May Concern,” etc.)

+mom sets +

the date flush right, page right, at the top of page one, + with a gap of two linespaces underneath +
the addressee (.TO) in a block flush left, page + left, with a gap of one linespace underneath +
the addresser (.FROM) in a block flush left, page + left, with a gap of one linespace underneath +
the greeting flush left, with a gap of one linespace + underneath +

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

the body of the letter justified
in multi-page letters: +
- a footer indicating there’s a next page (of the form .../#)
- the page number at the top of every page after page one
the closing/signature lines flush left, indented halfway across the page

+ +

+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 +any document processed with +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, which must come after +PRINTSTYLE +and before +START. +

+ +

DATE
TO
FROM
GREETING
CLOSING +
- CLOSING_INDENT
- SIGNATURE_INDENT
NO_SUITE – turn the “next page” footer off

+ + + +

+Macro: DATE +

+ +

+Invoke .DATE on a line by itself, with the date +underneath, like this: +
+ + .DATE + October 31, 2012 + +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, 2012 + .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 underneath, 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,”) underneath, like this: +
+ + .CLOSING + Yours truly, + +

+ +

+CLOSING control macros and defaults +
+Two macros control the behaviour of .CLOSING: +

CLOSING_INDENT
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 one half 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. +

+ +

+ + + + + + + + +

Back to Table of Contents

Top

Next: Quick reference guide

+ +

+ + + diff --git a/contrib/mom/momdoc/macrolist.html b/contrib/mom/momdoc/macrolist.html new file mode 100644 index 0000000..81ebd7c --- /dev/null +++ b/contrib/mom/momdoc/macrolist.html @@ -0,0 +1,1529 @@ + + + + + + + + + Mom -- Quick reference guide + + + + + + + +

+ + + + + + + +

Back to Table of Contents

Next: Appendices

+ +

Quick reference guide

+ +

+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

Paper size, margins, line length
Family, font, point size
Font modifications
Linespacing (leading)
Justification, quad, breaking lines
Hyphenation
Word and sentence spacing
Kerning, ligatures, smartquotes
Horizontal/vertical motions, columns
Indents
Tabs
Underscoring, underlining
Superscipts
Nested lists
Colour
Dropcaps
Smallcaps
Utilities
Graphical objects and images

DOCUMENT PROCESSING MACROS

Reference macros (metadata)
Document type and initial defaults
– Slides
TYPEWRITE control macros
Vertical whitespace management
Document and section cover (title) pages
Set documents in columns
Line numbering
Initiate document processing

Global print style changes after START
Managing the docheader
Epigraphs
Headings
Paragraphs
Quotes (line for line quotes)
Blockquotes (cited passages of text)
Code snippets (inserting bits of programming code)
Author linebreaks (section breaks)
Document termination string
Footnotes
Endnotes
Margin notes
Floats
Images and graphics
Shaded backgrounds, frames, page colour
eqn support
pic support
grap support
tbl support
Captions and labels
Bibliographic references
Tables of contents
Lists of Figures, Tables, and Equations
Letter (correspondence) macros
Managing page headers and footers
Recto/verso page headers and footers
Pagination
Utilities

+ +

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 inline
Pseudo extended
EXTEND	-- set the amount to pseudo extend
\*[EXT]	-- invoke pseudo extending inline
\*[EXTX]	-- turn off pseudo condensing inline

+ + + + + + + + + + + +

++++ Linespacing (leading)
LS	-- set the linespacing (leading)
AUTOLEAD	-- set the linespacing relative to the point size

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

++++ Justification, quad, 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	-- automatic hyphenation on/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	-- automatic character pair kerning on/off
\*[BU n]	-- move characters pairs closer together inline
\*[FU n]	-- move character pairs further apart inline
RW	-- uniformly tighten space between characters
EW	-- uniformly loosen space between characters
BR_AT_LINE_KERN	-- break previous line when RW or EW is invoked
LIGATURES	-- automatic generation of ligatures on/off
SMARTQUOTES	-- smartquoting on/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	-- multiple columns on
MCR	-- recto vertical position of column start
MCX	-- 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	-- left indents off
IRX	-- right indents off
IBX	-- both left and right indents off

+ + + + + + + + + + + + + + + + + + + + + + + + + + +

++++ Tabs
TAB_SET	-- set up a typesetting tab
TAB <n>	-- call tab <n>
TQ	-- quit (exit) tabs
\*[ST<n>]...	-- string tabs (mark tab positions inline)
\*[ST<n>X]
TN	-- move to tab<n+1> without advancing on the page
ST	-- set quad/fill for string tabs

+ + + + + + + + + + + + + + + + + + + + +

++++ Underscoring, underlining
UNDERSCORE	-- underscore
UNDERSCORE2	-- double underscore
UNDERLINE	-- underline (fixed width fonts only)
\*[UL]...	-- invoke underlining inline (fixed width fonts only)
\*[ULX]

+ + + + + + + + + + + + + + + + + +

++++ Superscipts
\[SUP]...\[SUPX]	-- superscript
\[CONDSUP]...\[CONDSUPX]	-- pseudo-condensed superscript
\[EXTSUP]...\[EXTSUPX]	-- pseudo extended supercript
SUPERSCRIPT_RAISE_AMOUNT	-- vertical offset of superscripts

+ + + + + + + + + + + + + + + + + + + + +

++++ Nested lists
LIST	-- begin a 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	-- reserve space for digits

+ + + + + + + + + + + + + + + + + +

++++ Colour
NEWCOLOR	-- initialize (define) a colour
COLOR	-- begin using an initialized colour
XCOLOR	-- initialize a "named" X colour
\*[<colorname>]	-- begin 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

+ + + + + + + + + + + +

++++ Smallcaps
SMALLCAPS
SMALLCAPS_STYLE

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

+++ 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
NEWSLIDE	-- break to a new slide
PAUSE	-- pause slide presentation
TRANSITION	-- transition effect for slides
PAD	-- insert equalized whitespace into a line
PAD_MARKER	-- change the pad marker
\*[RULE]	-- draw a full measure rule
SIZESPECS	-- cap-height, x-height, descender depth
SILENT	-- output processing off or on
TRAP	-- enable or disable page position traps
LEFT_HANG / \*[HANG]	-- hanging punctuation

+ + + + + + + + + + + + + + + + + + + + + + + + + + +

++++ Graphical objects and images
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]
PDF_IMAGE	-- insert a PDF image
PSPIC	-- insert a PostScript image

+ +

DOCUMENT PROCESSING MACROS

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

++++ Reference macros
TITLE	-- document title
DOCTITLE	-- document title (if different from TITLE)
ENDNOTE_TITLE	-- document/chapter id 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”
PDF_TITLE	-- PDF viewer window title
TOC_HEADING	-- non-pagenumbered line inserted into the TOC

+ + + + + + + + + + + + + + + + + +

++++ General document formatting directives
DOCTYPE	-- general document type
DOCTYPE SLIDES	-- create slide presentation
COPYSTYLE	-- draft or final copy
PRINTSTYLE	-- typeset or “typewritten”

+ + + + + + + + + + + + + + + + + +

++++ Line numbering
NUMBER_LINES	-- automatic line numbering on/off
NUMBER_QUOTE_LINES	-- numbering of QUOTE lines on/off
NUMBER_BLOCKQUOTE_LINES	-- numbering of BLOCKQUOTE lines on/off
Control macros

+ + + + + + + + + + + + + + +

++++ Set documents in columns
COLUMNS
COL_NEXT
COL_BREAK

+ + + + + + + + + + + + + + + + + + + + + + + + + + +

+++ TYPEWRITE control macros
TYPEWRITER_FAMILY	alternative to Courier
TYPEWRITER_SIZE	point size of typewriter font
UNDERLINE_ITALIC	-- underlining of italics on
UNDERLINE_QUOTES	-- underlining of QUOTEs on/off
ITALIC_MEANS_ITALIC	-- use real italics (not underlining)
UNDERLINE_SLANT	-- underlining of pseudo-italics on
SLANT_MEANS_SLANT	-- use pseudo italics (not underlining)

+ + + + + + + + +

++++ Initiate document processing
START	-- begin document processing

+ + + + + + + + + + + +

++++ Epigraphs
EPIGRAPH	-- set an epigraph underneath the docheader
Control macros	-- change default style of epigraphs

+ + + + + + + + + + + + + + + + + +

++++ Headings
HEADING	-- hierarchical headings
Control macros	-- style heading levels
HEADING_STYLE	-- set style parameters for heading levels
PREFIX_CHAPTER_NUMBER	-- add chapter number to heading numbering

+ + + + + + + + + + + + + + + + + + + + + + + +

++++ Paragraphs
PP	-- set a paragraph
Control macros	-- managing paragraph style concerns
PP_FONT	-- globally change font of regular paragraphs
PARA_INDENT	-- set the paragraph first-line indent
INDENT_FIRST_PARAS	-- indenting of paragraph first-lines on/off
PARA_SPACE	-- linespace between paragraphs on/off

+ + + + + + + + + + + + + + +

++++ Quotes (line for line verbatim quotes)
QUOTE	-- set quoted text line for line
Control macros	-- change default style of quotes
ALWAYS_FULLSPACE_QUOTES	-- control vertical space around quotes

+ + + + + + + + + + + + + + +

++++ Blockquotes (cited passages of text)
BLOCKQUOTE	-- set passages of cited text
Control macros	-- change default blockquote style
ALWAYS_FULLSPACE_BLOCKQUOTES	-- control vertical spacing

+ + + + + + + + +

++++ Floats
FLOAT	-- keep blocks of input together, output on next page + + if necessary

+ + + + + + + + + + + + + + +

++++ Images and graphics
PDF_IMAGE	-- inserting pdf images
PDF_IMAGE_FRAME	-- set parameters for pdf image frames
PSPIC	-- inserting PostScript images

+ + + + + + + + + + + + +

++++ Shaded backgrounds, frames, page colour
BOX -- shaded backgrounds and frames
PAGE_COLOR

+ + + + + + + + + + +

++++ eqn support
EQ	-- begin an eqn block
EN	-- end an eqn block

+ + + + + + + + + + + + + + +

++++ pic support
PS	-- begin a pic block
PE	-- end a pic block
PIC_TEXT_STYLE	-- set style for pic text

+ + + + + + + + + + + +

++++ grap support
G1	-- begin a grap block
G2	-- end a grap block

+ + + + + + + + + + + + + + +

++++ tbl support
TS	-- begin a tbl block
TH	-- running table header (after TS H)
TE	-- end tbl block

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

++++ Captions and labels
AUTOLABEL	-- auto-label figures, tables, equations
SET_AUTOLABEL	-- set or reset autolabel numbers
CAPTION_AFTER_LABEL	-- place captions after labels
MLA	-- MLA-style labelling and captioning
CAPTION	-- add a caption to a float or (block)quote
LABEL	-- add a label to a float or (block)quote
CAPTIONS	-- set style for captions
LABELS	-- set style for labels
SOURCES	-- set style for sources (tbl only)

+ + + + + + + + + + + + + + + + + +

++++ Lists of Figures, Tables, and Equations
LIST_OF_FIGURES	-- generate a List of Figures
LIST_OF_TABLES	-- generate a List of Tables
LIST_OF_EQUATIONS	-- generate a List of Equations
LISTS_STYLE	-- set style parameters for Lists

+ + + + + + + + + + + + + + + + + +

++++ Code snippets
CODE	-- set a code snippet
Control macros	-- change default style of code snippets
General	-- family, font, and colour
CODE_SIZE	-- code size as a percentage of prevailing text

+ + + + + + + + + + + + + + + + + +

++++ Author linebreaks (section breaks)
LINEBREAK	-- insert an author linebreak (section break)
Control macros	-- change default style of linebreaks
LINEBREAK_CHAR	-- character to use for author linebreaks
LINEBREAK_COLOR	-- colour of author linebreak character

+ + + + + + + + + + + + + + + + + + + + +

++++ Document termination string
FINIS	-- insert a document termination string
Control macros	-- change default style finis string
FINIS_STRING	-- set the document termination string
FINIS_STRING_CAPS	-- capitalization of termination string
FINIS_COLOR	-- set the document termination string colour

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

++++ Footnotes
FOOTNOTE	-- set a footnote
Control macros	-- change default style of footnotes
FOOTNOTE_MARKERS	-- footnote markers on/off
FOOTNOTE_MARKER_STYLE	-- type of footnote marker to use
RESET_FOOTNOTE_NUMBER	-- reset footnote numbering
FOOTNOTE_RULE	-- footnote separator rule on/off
FOOTNOTE_RULE_ADJ	-- adjust position of footnote rule
FOOTNOTE_RULE_LENGTH	-- adjust length of footnote rule
FOOTNOTES_RUN_ON	-- instruct footnotes to be continuous

+ + + + + + + + + + + + + + + + + + +

++++ 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
Control macros

+ + + + + + + + + + + + + + + + + + + + +

General style control

Pagination

Header/footer control

Title control

Document/section identification control

Identification style

+ + + + + + + + + + + +

++++ Margin notes
MN_INIT	-- initialize margin notes
MN	-- set a margin note

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

++++ Bibliographic references
REF	-- begin a reference
FOOTNOTE_REFS	-- place references in footnotes
ENDNOTE_REFS	-- place references in endnotes
REF( / REF)	-- put parentheses around embedded references
REF[ / REF]	-- put square brackets around embedded references
REF{ / REF}	-- put curly braces around embedded references
BIBLIOGRAPHY	-- output a bibliography
Control macros

+ + + + + + + + + + + + + + +

BIBLIOGRAPHY_TYPE -- "plain" or enumerated list

General style control

Header/footer control

Main head control

+ + + + + + + + + + + + + + + + + +

++++ Tables of contents
TOC	-- output a table of contents
NO_TOC_ENTRY	-- omit a document section from the TOC
TOC_HEADING	-- insert a heading into the TOC
Control macros

+ + + + + + + + + + + + + + + + + + + + + + + + + + +

General style control

Page numbering

Header string control

Entries and reference page numbers style control

TOC_TITLE_STYLE

TOC_ENTRY_STYLE

TOC_HEADING_STYLE

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	-- 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/off
Control macros	-- change default style of docheader elements

+ + + + + + + + + + + + + + + + + +

++++ Managing page headers and footers
HEADERS	-- page headers on/off
FOOTERS	-- page footers on/off
HEADERS_AND_FOOTERS	-- enable generation of both headers and + footers
Control macros

+ + + + + + + + + + + + + + + + + + + + +

Strings	-- left-right-center strings
Style	-- change defaults for headers and/or footers
Global	-- global style changes
Part-by-part	-- part-by-part style changes
Vertical placement	-- adjust position of headers and/or footers
Separator rule	-- manage the header/footer separator rule

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

++++ Recto/verso page headers and footers
RECTO_VERSO	-- recto/verso headers and/or footers on/off
FORCE_RECTO	-- insert blank pages so chapters start recto
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/off
Control macros	-- change default style for pagination
PAGENUMBER	-- user-defined (starting) page number
PAGENUM_STYLE	-- digits, roman numerals, etc
PAGENUMBER_STRING	-- user-defined page numbering string
PAGENUM_ON_FIRST_PAGE	-- when page numbering is at page top
DRAFT_WITH_PAGENUMBER	-- attach draft/revision to page number

+ + + + + + + + + + + +

++++ Vertical whitespace management
SHIM	-- align to the baseline grid
FLEX	-- insert flexible whitespace

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

++++ Document and section cover (title) pages
DOC_COVER	-- information to include in a document cover
COVER	-- information to include in a section cover
DOC_COVERS	-- printing of document covers on/off
COVERS	-- printing of section covers on/off
DOC_COVERTEXT	-- user-added text for document covers
COVERTEXT	-- user-added text for section covers
DOC_COVER_IMAGE	-- add images to document covers
COVER_IMAGE	-- add images to document covers
Control macros	-- change style defaults for covers

+ + + + + + + + + + + + + + + + + + + + + + + +

+++ Utilities
ADD_SPACE	-- add space to the top of a page
RESTORE_SPACE	-- restore spacing at the top of a page
BLANKPAGE	-- output one or more blank pages
DOC_LEAD_ADJUST	-- adjust leading to fill pages
COLLATE	-- join documents (chapters/sections)
CENTER_BLOCK	-- centre blocks of type

+ +

+ + + + + + + + +

Back to Table of Contents

Top

Next: Appendices

+ +

+ + + diff --git a/contrib/mom/momdoc/rectoverso.html b/contrib/mom/momdoc/rectoverso.html new file mode 100644 index 0000000..92cf80f --- /dev/null +++ b/contrib/mom/momdoc/rectoverso.html @@ -0,0 +1,350 @@ + + + + + + + + + Mom -- Recto/verso printing, collating + + + + + + + +

+ + + + + + + +

Back to Table of Contents

Next: Cover pages

+ +

Recto/verso printing, collating

+ +

Introduction to recto/verso printing +
- Macro list
Introduction to collating +
- The COLLATE macro

+ +

Introduction to recto/verso printing

+ +

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

switching left and right margins (if they’re not equal)
switching the left and right parts of the default 3-part + headers + or + footers + (see the + General description of headers) +
switching + HEADER_RECTO + and + HEADER_VERSO + if user-defined, single string recto/verso headers + or footers are used in place of the default 3-part + headers or footers +
switching the page number position (if page numbers are not centred)

+
+ +

Recto/verso macros

RECTO_VERSO
FORCE_RECTO
SWITCH_HEADERS (also FOOTERS) + – switch starting position of the header parts (left and right) +

+ + + +

+Macro: RECTO_VERSO +

+ +

+If you want mom to set up alternating pages for recto/verso +printing, simply invoke RECTO_VERSO, with no argument, anywhere in +your document (most likely before +START). +

+ +

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

+ +

+It is a common convention with two-sided printing to ensure that +cover pages, title pages, and chapters or major sections of a document +always begin on the recto side of a page. This sometimes +necessitates inserting a blank page before the start of a new +chapter or major section. +

+ +

+If you would like mom to take care of this for you automatically, +simply invoke FORCE_RECTO before the first +START +of the document. +

+ + + +

+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 +(i.e. recto/odd) represents the norm for header-left and header-right, +meaning that the second (and all subsequent verso/even) pages of the +document will reverse the order of header-left and header-right. +

+ +

+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

+ +

+Many people wisely keep chapters of a long work in separate +files, previewing or printing them as needed during the draft +phase. However, when it comes to the final version, mom requires +a single, collated file in order to keep track of page numbering +and recto/verso administration, generating tables of contents and +endnotes, ensuring that +docheaders +get printed correctly, and a host of other details. +

+ +

+The COLLATE macro, which can be used with any +DOCTYPE +except LETTER, lets you glue mom-formatted input files +together. You need only concatenate chapters into a single file +(most likely with cat(1)), and put +.COLLATE at the end of each concatenated chapter. +Assuming all the files begin with the required +reference macros +(metadata), style parameters, and +START, +each chapter will begin on a fresh page and behave as expected. +

+ +

+Even if you work with monolithic, multi-chapter files, every +chapter and its associated metadata plus .START +still needs to be preceded by .COLLATE. +

+ +

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

Do not collate documents of differing + PRINTSTYLES (i.e., don’t try to + collate a TYPESET document and TYPEWRITE + document). +
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. +

+ + + +

collate

+ +

+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 line of text before .COLLATE +falls too close to the bottom margin, or if the line is followed +by a macro likely to cause a linebreak (e.g. .LIST OFF or +.IQ), mom may output a superfluous blank page before +the start of the following document. +

+ +

+In order to avoid this, insert +.EL +after the last line of text, before .COLLATE and/or any +concluding macros. For example, +
+ + some concluding text.\c + .EL + .COLLATE + +or +
+ + some concluding text.\c + .EL + .LIST OFF + .COLLATE + +

+ +

+Note: +See the +two words of caution, +above. +

+ +

+ + + + + + + + +

Back to Table of Contents

Top

Next: Cover pages

+ +

+ + + diff --git a/contrib/mom/momdoc/refer.html b/contrib/mom/momdoc/refer.html new file mode 100644 index 0000000..5f11814 --- /dev/null +++ b/contrib/mom/momdoc/refer.html @@ -0,0 +1,2129 @@ + + + + + + + + + Mom -- Document processing, bibliographies and references + + + + + + + +

+ + + + + + + +

Back to Table of Contents

Next: Writing letters

+ +

Bibliographies and references

+ +

Introduction to bibliographies and references
Tutorial on refer usage with mom +
MLA (Modern Language Association) style +
- Types of references (endnote, footnote, or embedded in text)
- Inserting parenthetical references into the text
The refer database +
The bibliography and reference macros +
- Bibliography control macros and defaults

+ +

Introduction to bibliographies and references

+ +

+Mom provides the ability to format and generate bibliographies, as +well as footnote or endnote references, in MLA (Modern Language +Association) style. She accomplishes this by working in conjunction +with a special groff program called refer. +

+ +

+Refer requires first that you create a database of works +that will be cited in your documents. Once that’s done, special +macros let you briefly key in references to entries in the database +and have mom format them with respect to order, punctuation and +italicization in footnotes, endnotes, or a full bibliography. +

+ +

+Refer has 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. (It’s a classic manpage +Catch-22: the manpage is useful only after you know how to use the +program.) +

+ +

+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 instructions are not to +be taken as a manual on full refer usage. +

+ +

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

+ +

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

+ +

Tutorial on refer usage with mom

Create a refer database +
- example refer database
Insert a refer block +
Tell mom where you want your references (if footnotes or endnotes)
Accessing references in the database
Entering footnote/endnote references
Parenthetical insertions
Generating a bibliography from parenthetical insertions
Generating a comprehensive bibliography
Invoking groff with mom and refer

+ +

1. Create a refer database

+ +

+The first step in using refer with mom is creating a +database. The database is a text file containing entries for the +works you will be citing. You may set up separate databases for +individual documents, or create a large database that can be +accessed by many documents. +

+ +

+Entries (“records” in refer-speak) in the database +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. +

+ + + +

+Here’s an example database containing two records so you can +visualize what the above paragraph says. +

+ +

Example refer database

+ +%A Terry Pratchett +%A Neil Gaiman +%T Good Omens +%C London +%I Gollancz +%D 1990 + +%A Peter Schaffter +%T The Schumann Proof +%C Toronto +%I RendezVous Press +%D 2004 + +

+ +

+The order in which you enter fields doesn’t matter. +Refer will re-arrange them for you. +

+ +

2. Insert a refer block

+ +

+Having set up your database, you now need to put some +refer-specific commands in your mom file. +

+ +

+Refer commands are introduced by a single line +containing .R1, and concluded with a single line +containing .R2. What goes between the .R1 +and .R2 lines is called a “refer block”. +Refer commands in a refer block should be entered one per +line, in lowercase letters, with no initial period (dot). +The actual commands depend on whether you want your references +

in footnotes/endnotes
parenthetically inserted (in abbreviated form) into running text, +referring to a works-cited list (bibliography)
to generate a comprehensive bibliography (a reading list)

+ +

Refer block for footnotes/endnotes

+ +

+If you want footnote or endnote references, place this block at +the top of your mom file. +

+ +

+ +.R1 +no-label-in-text +no-label-in-reference +join-authors " and " ", " ", and " +database <full path to database> +.R2 + +

+<full path to the database> +means the full path including the filename, e.g. +/home/user/refer/my-database-file. +

+ +

Refer block for parenthetical insertions into running text

+ +

+If you want short, parenthetical insertions into running text, +referring to works cited in a bibliography, place this block at +the top of your mom file. +

+ +

+ +.R1 +label "(A.n|Q)" +bracket-label " (" ")" ", " +join-authors ", and " ", " ", and " +move-punctuation +reverse A1 +sort A1Q1T1B1E1 +database <full path to database> +.R2 + +

+<full path to the database> +means the full path including the filename, e.g. +/home/user/refer/my-database-file. +

+ +

Refer block for comprehensive bibliographies

+ +

+If you want to output an entire refer database, or +generate a comprehensive bibliography (a reading list) from a +database, place this block at the bottom of your mom file, +either prior to or immediately after invoking +BIBLIOGRAPHY. +

+ +

+ +.R1 +no-label-in-text +no-label-in-reference +join-authors ", and " ", " ", and " +sort A1Q1T1B1E1 +reverse A1 +database <full path to database> +.R2 + +

+ +

+<full path to the database> +means the full path including the filename, e.g. +/home/user/refer/my-database. +

+ +

3. Tell mom where you want your references

+ +

+If you want references in footnotes, issue the instruction +
+ + .FOOTNOTE_REFS + +anywhere before the first citation in your file. Footnote markers +will be inserted into the text, and the bibliographic information +for the citation will appear as a footnote. +

+ +

+If you want references in endnotes, issue the instruction +
+ + .ENDNOTE_REFS + +anywhere before the first citation in your file. Endnote markers +will be inserted into the text, and the bibliographic information +for the citation will appear as an endnote entry. +

+ +

+Note that if you want references parenthetically inserted +into running text, referring to entries in a works-cited list +(bibliography) that mom and refer assemble +automatically, no special instructions are required. See +Generating a bibliography from parenthetical insertions +for how to output the collected references. +

+ +

+For outputting an entire refer database, or +generating a comprehensive reading list from a database, see the +macro +BIBLIOGRAPHY. +

+ +

4. Accessing references in the database

+ +

+References are accessed by putting keywords from the desired database +record between two special refer commands: +
+ + .[ + +and +
+ + .] + +Keywords are any word, or set of words, that identify a database +record unambiguously. Thus, if you have only one database record for +the author Ray Bradbury, +
+ + .[ + bradbury + .] + +is sufficient. However, if your database contains several records +for books by Bradbury, say, Fahrenheit 451 and The +Martian Chronicles, +“bradbury 451” and +“bradbury martian” would identify the two records unambiguously. +

+ +

+A special database field identifier, %K, lets you create +unique keywords for database records to help clear up any ambiguity. +

+ +

+Notice that you don’t have to worry about capitalization when +entering keywords. +

+ +

5. Entering footnote/endnote references

+ +

+Depending on which you have issued, a +.FOOTNOTE_REFS +or an +.ENDNOTE_REFS +command, entering references is done like this: +
+ + .REF + .[ + keyword(s) + .] + .REF + +If FOOTNOTE_REFS is in effect, the reference between the first +and second .REF will be treated as a footnote. If +ENDNOTE_REFS, it will be treated as an endnote. Endnote references +must be explicitly output with +ENDNOTES +at the end of your file, before +TOC. +

+ +

+Important: +REF behaves identically to +FOOTNOTE +and +ENDNOTE +with respect to the use of the \c inline escape. Please +read the +HYPER IMPORTANT NOTE +found in the document entry for FOOTNOTE (which also applies to +ENDNOTE). +

+ +

6. Parenthetical insertions

+ +

+See +Inserting parenthetical references into +text. +

+ +

7. Generating a bibliography from parenthetical insertions

+ +

+To generate a bibliography from works cited by parenthetical +insertions in the text, put this at the end of your document, before +.TOC. +
+ + .BIBLIOGRAPHY + .[ + $LIST$ + .] + .BIBLIOGRAPHY OFF + +

+ +

8. Generating a comprehensive bibliography

+ +

+You can also generate a comprehensive bibliography, which is to say a +bibliography containing more works than are actually cited (a +“reading list”), by placing references between +.BIBLIOGRAPHY +and +.BIBLIOGRAPHY OFF. +Once you have input the desired references, insert +
+ + .[ + $LIST$ + .] + +and follow it with .BIBLIOGRAPHY OFF. Study the +example below if you’re having trouble visualizing this. +

+ +

Example bibliography

+ +.BIBLIOGRAPHY +.R1 +no-label-in-text +no-label-in-reference +join-authors ", and " ", " ", and " +sort A1Q1T1B1E1 +reverse A1 +database <full path to database> +.R2 +.[ +bradbury +.] +.[ +pratchett +.] +.[ +$LIST$ +.] +.BIBLIOGRAPHY OFF + +

+ +

+Alternatively, you can output an entire database as a +bibliography. Do the following at the end of your document, before +.TOC. +
+ + .BIBLIOGRAPHY + .R1 + no-label-in-text + no-label-in-reference + join-authors ", and " ", " ", and " + sort A1Q1T1B1E1 + reverse A1 + bibliography <full path to database> + .R2 + .BIBLIOGRAPHY OFF + +

+ +

9. 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. Pass the -R flag to pdfmom or groff, +like this: +
+ + pdfmom -R <filename> ... + +

+ +

MLA (Modern Language Association) style

+ +

Types of references (endnote, footnote, or embedded in text)

+ +

+MLA allows for three types of references, or referencing styles: +

short, parenthetical references in the text, linked to a + works-cited list (bibliography) at the end of the document
footnote references
endnote references

+ +

+There are significant differences between the way footnote/endnote +references should be formatted, and the formatting style of +bibliographies. One example is that footnote/endnote references +should have their first lines indented, whereas bibliographic +references should have their second lines indented. Fortunately, +with mom, there’s no need to concern yourself with the differences; +they’re taken care of automatically. +

+ +

+In terms of inserting references into your documents, +footnote/endnote references are input in a manner similar to +entering any other kind of +footnote +or +endnote. +Parenthetical references, however, need to be handled differently. +See the next section. +

+ +

Inserting parenthetical references into the text

+ +

+MLA style prefers restricting the information in parenthetical +references to the barest minimum needed to identify works +in the works-cited list (the bibliography). Typically, a +parenthetical insertion is just the author’s last name +followed by the page number of the cited work (if only one work by +that author is cited), or by the author, a shortened title of the +work, and the page number (if more than one work is cited). +

+ +

+This necessitates a slightly fiddly way of entering parenthetical +references, though not by any means difficult or hard to make sense +of. +

+ +

+The refer block suggested +here +for parenthetical references prints only the author’s +last name from the database record identified by your keywords +(the label command), surrounded by parentheses (the +bracket-label command). Therefore, assuming you are +citing Ray Bradbury’s The Martian Chronicles, and it is +the only work by Bradbury mentioned in the text, +
+ + ...end of sentence. + .[ + martian chronicles + .] + A new sentence... + +will insert “...end of sentence (Bradbury). A new sentence...” into the text. +The Martian Chronicles will be added +to the works-cited list generated at the end of the document if it +is not already present as the result of an earlier reference. +

+ +

+If you need a page number to identify where in The Martian +Chronicles to find a specific quote +
+ + "...aluminum roaches and iron crickets." + .[ + [ martian chronicles + .] 168) + A new sentence... + +results in “...aluminum roaches and iron crickets.” (Bradbury 168) A new sentence...” +(which is excruciatingly correct MLA style). The +“[” before martian chronicles tells +refer to print the opening parenthesis; any text immediately +following the “.]”, including spaces, +replaces the closing parenthesis. (Notice that you have to +add the closing parenthesis yourself after the page number.) +

+ +

+If your document cites more than one work by Bradbury and you need +a title and page number in addition to the author’s name in +the inline reference, +
+ + "...aluminum roaches and iron crickets." + .[ + [ bradbury martian + .], \fIChronicles\fP 168) + A new sentence... + +will produce ““...aluminum roaches and iron crickets.” (Bradbury, Chronicles 168) A new sentence...”. +

+ +

The ‘label’ and ‘bracket-label’ commands

+ +

+The label and bracket-label commands in +the refer block allow you to customize what information goes +into parenthetical references, and how they should be formatted. +label dictates which fields from the database record +to print and how to punctuate them. bracket-label +controls the bracketing style. Users are encouraged to consult +man refer for usage. +

+ +

+Here’s an example of how to set up APA-style references, which +require the author and date of publication, optionally with a page +number or range of pages. +
+ + .R1 + label "(A.n|Q) ', ' D.y" + bracket-label " (" ")" ", " + join-authors ", and " ", " ", and " + move-punctuation + reverse A1 + sort A1Q1T1B1E1 + database /home/peter/Groff-mom/Testing/Refer/refer-database + .R2 + +Assuming a reference to a work by Ursula Leguin published in 1980 +
+ + .[ + leguin + .] + +produces + +(Leguin, 1980) +. +If a page number is also required +
+ + .[ + [ leguin + .], p. 73) + +produces +(Leguin, 1980, p. 73). +

+ +

The refer database

+ +

Introduction

+ +

+The heart and soul of refer is the bibliographic +database. Knowing how to create records (i.e. the entries for works +cited in a document) is largely a question matching data (author, +title, publisher, etc) with the correct field identifier. For +example, if you’re citing from a scholarly journal, you need to know +that %J is the field identifier for journal names and +%N is the field identifier for the journal number. Use +the +Quick list of field identifiers +as your guide. +

+ +

The rules

+ +

+Entering the data correctly is also important. Fortunately, there +are very few rules, and those there are make sense. In a nutshell: +

enter the data in each field in natural order; author John Smith is + “John Smith”, editor Jane Doe is “Jane Doe”
capitalize all proper nouns and words in titles as you expect + to see them; otherwise, use lowercase
use no terminating punctuation unless required; typically, + required punctuation is the period after a shortform + (“ed.” or “eds.”, “Jr.”, + etc) or a question mark or exclamation mark at the end of a + title
if part of a field needs to be set off in single-quotes, use + \[oq] and \[cq] (openquote, closequote) rather than the + single-quote (or apostrophe) character on your keyboard
if part of a field needs to be forced into italics, use the + escapes \*[IT] and + \*[PREV]; if the italicized portion + concludes the field, omit \*[PREV]
if you require characters with accents, ligatures or special + symbols, use groff’s “named” glyphs (e.g. + \['e] for é); a full list can be found in + man groff_char

+ +

Quick guide to field identifiers (click on any that are links for more information)

+ +

+ +%A author – records may contain multiple authors, + one per line +%Q non-human author – corporate author, e.g. National Geographic; + may also be used for exceptional reference types +%m multiple authors – whenever "et al." is desirable +%i idem – multiple works by the same author +%p post-author – post-author information (e.g. appendix, + foreword, letter) +%T title – primary title (of a book) or the + title of an article (within a scholarly + journal or a magazine) +%B book title – when %T contains the title of an article; +%q force quote – force a title into double-quotes +%t reprint title – if different from a work's original title +%b main author – when citing a preface, foreword, + introduction, or afterword, the author of + the complete original work +%E editor – records may contain multiple editors, + one per line +%l translator – if more than one translator, all the + names +%r translator – if tr. and ed. are one in the same + and editor +%M magazine or – when %T contains the title of an article + newspaper +%J journal – when %T contains the title of an article +%e edition – number or name of an edition + (e.g. Second, 2nd, Collector's, etc.) +%S series – series name of books or journals +%V volume – volume number (of books) +%N journal number – journal or magazine number +%R report number – technical report number +%G gov’t. – government ordering number +%O other – information for which there is no appropriate + field letter +%C city – city of publication +%I publisher – publisher +%D date – publication date +%d original + publication date – if different from date of publication +%P page(s) – page number or range +%n annotation – annotation to the reference +%s site name – for internet references, the website name +%c content – for internet references, the source of + the material (e.g. Web or Email); for websites, + the content, if unclear +%o organization – for internet sites, the organization, group + or sponsor of the site +%a access date – for internet sites, the date of access +%u URL – for internet sites, the full URL +%K keywords – words that help clear up ambiguities in + the database + +

+ +

Field identifiers: specifics, usage and examples

+ +

%A – author field

+ +

+For multiple authors, enter each in a separate %A +field in the order in which they should appear. If the author on +the title page is the editor (say, a book of short stories edited by +Ray Bradbury), add , ed. to the end of the +%A field, like this: +
+ + %A Ray Bradbury, ed. + +Do not use the %E field in these instances. If the work +has several such editors, enter each in a separate %A +field, as for multiple authors, and add , eds. to the +last one, like this: +
+ + %A Jane Dearborne + %A Bill Parsons, eds. + +

+ +

%Q – exceptional entries

+ +

+Sometimes, a work has no author or title information, for example a +book review in a newspaper. In such cases, use %Q, like +this: +
+ + %Q Rev. of \*[IT]Mean Streets Omnibus\*[PREV], ed. Raymond Hammett + %M Times Literary Supplement + %D 7 July 1972 + +

+ +

%m – multiple authors (et al.)

+ +

+Whenever it’s desirable to abbreviate a list of authors with +“et al.” enter it in the %m field, like this: +
+ + %A Paul Lauter + %A Doug Scofield + %m et al. + +

+ +

%i – idem

+ +

+Whenever there are several works by the same author, fill out the +%A field with the author’s name and follow it with the +%i idem, like this: +
+ + %A Jonathon Schmidt + %i idem + +Per MLA style, the author’s name will be replaced by a long dash. +

+ +

+If it’s necessary to state the role the author served (say, +editor or translator), fill out the %i field with the +information minus idem, like this: +
+ + %A Ray Bradbury + %i ed. + %T Timeless Stories for Today and Tomorrow + +

+ +

%p – post-author information

+ +

+When citing from a preface, foreword, introduction, afterword, +or appendix, MLA requires that the information come between the +author’s name and the work’s title, like this: +
+ + %A Martin Packham, Jr. + %p appendix + %T Why the West was Won + +Do not capitalize the first word in the %p field unless +it is a proper noun. +

+ +

%q – force title into double-quotes

+ +

+Occasionally, you may not be able to use %T for the +title because doing so will cause it to come out in italics when +double-quotes are called for. An example of this is when citing +from a dissertation. Use %q to get around the problem, +like this: +
+ + %A Carol Sakala + %q Maternity Care Policy in the United States + %O diss., Boston U, 1993 + +

+ +

%E – editor

+ +

+Use this only if the author and the editor are not one in the same, +e.g. +
+ + %A Geoffrey Chaucer + %T The Works of Geoffrey Chaucer + %E F. W. Robinson + +

+ +

%l – translator

+ +

+If there is more than one translator, enter all the names, with +appropriate conjunctions and punctuation, like this: +
+ + %A Feodor Dostoevsky + %T Crime and Punishment + %l Jessie Coulson, Marjorie Benton, and George Bigian + +

+ +

%O – other

+ +

+Occasionally, MLA requires additional information after the title +but before the publication data (city/publisher/date), for instance, +the number of volumes in a series, or the fact that the work cited +is a dissertation. Here are two examples: +
+ + %A Arthur M. Schlesinger + %T History of U.S. Political Parties + %O 4 vols. + %C New York + %I Chelsea + %D 1973 + + %A Carol Sakala + %q Maternity Care Policy in the United States + %O diss., Boston U, 1993 + +Do not capitalize the first word of the %O field unless +it is a proper noun. +

+ +

+Generally, consider %O a catch-all for information that +does not match the criterion of any existing field identifier. +

+ +

%C – city

+ +

+Normally, %C takes the name of the city of publication, +and that’s all. In the case of a republished book, if new material +has been added, put such information in the %C +field, like this: +
+ + %A Theodore Dreiser + %T Sister Carrie + %d 1900 + %C Introd. E. L. Doctorow, New York + +

+ +

%d – original date of publication

+ +

+Normally, all that is required in the %d field is the +original date of publication. However, if supplementary original +publication data is desired, include it in the field, like this: +
+ + %A Kazuo Ishiguro + %T The Remains of the Day + %d London: Faber, 1989 + %C New York + %I Knopf + %D 1990 + +

+ +

%K – keywords

+ +

+Refer hates ambiguity, and complains when encountering +it. Ambiguities result from the duplication of any word in more +than one database record when that word is used to identify a +reference in your input file. Use %K to create unique +keywords found nowhere else in the database. +

+ +

+Imagine, for example, that your database contains records for +Ray Bradbury’s The Illustrated Man, another record for +The Illustrated Bradbury and a third for Bradbury, +Illustrated. %K can be used to clear up any +ambiguities by assigning a unique word to each record, for example +%K ill-man for the first, %K ill-brad for the +second, and %K brad-ill for the third. +

+ +

%P – pages

+ +

+When citing page numbers, which is often the case with footnotes +and endnotes, it is not necessary to put the numbers in the database +records. The %P field can be added underneath the +keyword(s) in the .[ / .] entries in your +input file, allowing you to recycle database records. For example, +
+ + %A Frye + %T Anatomy + %K frye-anat + +could be your short record for Northrop Frye’s The Anatomy of +Criticism. Any time you wanted to cite a particular page or +range of pages from that work in a footnote or endnote, you can +put +
+ + .REF + .[ + frye-anat + %P 67-8 + .] + .REF + +in your input file, and have it show up with the correct page(s). +

+ +

%n – annotations

+ +

+Annotations come at the very end of references. Capitalize all +words that require it, including, for bibliographic references (but not +for footnotes/endnotes) the first. +

+ +

The bibliography and reference macros

REF – begin/end a refer reference that will go in a footnote or endnote
FOOTNOTE_REFS – instruct mom to put REFs in footnotes
ENDNOTE_REFS – instruct mom to put REFs in endnotes
INDENT_REFS – manage indenting of references, per MLA standards
HYPHENATE_REFS – enable/disable hyphenation of references
BIBLIOGRAPHY – begin a bibliography
BIBLIOGRAPHY_TYPE – plain, or numbered list bibliography
Bibliography control macros and defaults

+ + + +

Begin/end a reference that goes in a footnote or endnote

+ +

+Macro: REF +

+ +

+The macro REF tells mom that what follows is +refer-specific, a keyword-identified reference to a +refer database record. Depending on whether you’ve issued +a +.FOOTNOTE_REFS +or +.ENDNOTE_REFS +instruction, the reference will be formatted and placed in a +footnote, or collected for output in the endnotes. Parenthetical +insertion of references into the text do not require +.REF (see +Inserting parenthetical references into the text.) +

+ +

+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 instructions, +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. +

+ +

+Note: +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. +

+ +

+Additional note: +REF behaves identically to +FOOTNOTE +or +ENDNOTE, +so please read the HYPER IMPORTANT NOTE found in the document entry +for +FOOTNOTE +and/or +ENDNOTE +for instructions on correct entry of text preceding and following REF. +

+ + + + +

Instruct mom 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. +

+ +

+By default, FOOTNOTE_REFS sets the +FOOTNOTE_MARKER_STYLE +to NUMBER (i.e. superscript numbers). You may change +change that if you wish by invoking FOOTNOTE_MARKER_STYLE, with the +argument you want, after FOOTNOTE_REFS. +

+ +

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

+ + + +

Manage indenting of references, per MLA standards

+ +

+Macro: INDENT_REFS FOOTNOTE | ENDNOTE | BIBLIO <indent> +

+ +

+• <indent> requires a unit of measure +

+ +

+MLA-style requires that footnote or endnote references should +have their first lines indented, whereas bibliographic references +should have their second and subsequent lines indented. Thus, if +you invoke INDENT_REFS with a first argument of FOOTNOTE +or ENDNOTE, the value you give to +<indent> sets the indent of the first line for +those types of references; if you invoke it with BIBLIO, +the value you give <indent> sets the indent of +second and subsequent lines in bibliographies. +

+ +

+By default, the indent for all three types of references is 1/2-inch +for +PRINTSTYLE TYPEWRITE +and 2 +ems +for +PRINTSTYLE TYPESET. +

+ +

+If you’d like to change the indent for footnote, endnote or +bibliography references, just invoke .INDENT_REFS with +a first argument saying which one you want the indent changed for, 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 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, which is to align them 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 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 + .[ + keyword(s) + .] + .HY + +Alternatively, sprinkle your database fields liberally with +\%. +

+ + + +

Begin a bibliography

+ +

+Macro: BIBLIOGRAPHY toggle +

+ +

+To append a bibliography to your document, whether of references +inserted parenthetically into text or a comprehensive reading list +derived from a large refer database, all you need +do is invoke .BIBLIOGRAPHY. .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, +Generating a bibliography from parenthetical insertions +and +Generating a comprehensive bibliography. +When all the required data has been entered, type +
+ + .BIBLIOGRAPHY OFF + +to complete the bibliography. +

+ +

+See the +Bibliography control macros and defaults +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 the argument, PLAIN, bibliography entries are output +with no enumerators. With the argument, LIST, each entry is numbered. +

+ +

+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 the BIBLIOGRAPHY_TYPE either before or after +.BIBLIOGRAPHY. It must, however, always come before +any refer commands. See +Generating a bibliography from parenthetical insertions +and +Generating a comprehensive bibliography. +

+ +

+Mom’s default BIBLIOGRAPHY_TYPE is PLAIN. +

+ + + +

Bibliography control macros and defaults

+ +

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

+ +

General bibliography style control +
Pagination of bibliographies +
Header/footer control +
Bibliography first-page title control +

+ +

1. General bibliography page style control

+ +

• Base 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 (LEFT) or J (JUSTIFIED); + R (RIGHT) and C (CENTER) will not work. + +

+ + + +

• Base 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). +

+ + + +

• Leading

+ +

+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 bibliographies 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 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 bibliography leading. You +must enter BIBLIOGRAPHY_LEAD <lead> +with no ADJUST argument to disable this default +behaviour. +

+ + + +

• Adjust the space between bibliography entries

+ +

+Macro: BIBLIOGRAPHY_SPACING <amount of space> +

+ +

+• Requires a unit of measure +

+ +

+By default, mom inserts no space between bibliography entries. +If you’d prefer she add some, instruct her to do so with +BIBLIOGRAPHY_SPACING. Say, for example, you want a half a linespace +between entries, +
+ + .BIBLIOGRAPHY_SPACING .5v + +would do the trick. +

+ +

+Note: +As with endnotes pages, inserting space between bibliography entries +will most likely result in hanging bottom margins. +

+ + + +

• Singlespace bibliography (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 no +argument. +

+ + + +

• 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. In such circumstances, you must re-enable +BIBLIOGRAPHY_NO_COLUMNS for each separate collated document. +

+ +

2. Pagination of bibliographies

+ + + +

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

+ +

+Macro: BIBILOGRAPHY_FIRST_PAGENUMBER <page # that appears on page 1 of bibliographies> +

+ +

+Use this macro with caution. If the bibliography for a +collated +document is to be output at the document’s end, +BIBLIOGRAPHY_FIRST_PAGENUMBER tells mom what page number to put on +the first page of the bibliography. +

+ +

+However, if you’re outputting a bibliography at the end of each +section (chapter, article, etc) of a collated document, +you have to reset every section’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 during bibliography output

+ +

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

+ +

3. Header/footer control

+ +

• Modifying what goes in the bibliography header/footer

+ +

+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, or +you would like her to add one in cases where there hasn’t been +one before (e.g. DOCTYPE DEFAULT) 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, invoke +
+ + .BIBLIOGRAPHY_HEADER_CENTER + .HEADER_CENTER "Bibliography" + +or + + .BIBLIOGRAPHY_FOOTER_CENTER + .FOOTER_CENTER "Bibliography" + +prior to invoking .BIBLIOGRAPHY. +

+ +

+Important: +Unless you have a running centre string in your headers or footers, you must invoke + + .BIBLIOGRAPHY_HEADER_CENTER + +or + + .BIBLIOGRAPHY_FOOTER_CENTER + +in order for the centre string to appear, as demonstrated above. +

+ +

• Header/footer centre string when doctype is CHAPTER

+ +

+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, or if you do not have a running header/footer +centre string in the body of the document, invoke +.BIBLIOGRAPHY_HEADER_CENTER (or +.BIBLIOGRAPHY_FOOTER_CENTER) with no argument before +defining the centre string . 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. +

+ +

4. Bibliography first-page title control

+ + + +

• Title string

+ +

+Macro: BIBLIOGRAPHY_STRING "<title to print at the top of bibliography pages>" +

+Alias: BIBLIOGRAPHY_HEADER +

+ +

+By default, mom prints the word “BIBLIOGRAPHY” as a title +at the top of the first page of a bibliography. If you want her to +print something else, invoke .BIBLIOGRAPHY_STRING with +the title you want, surrounded by double-quotes. +

+ +

+If you don’t want a title 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). +

+ + + +

• Title string control macros and defaults

+ +

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

+ + + +

• Title string placement

+ +

+Macro: BIBLIOGRAPHY_STRING_ADVANCE <distance from top of page> +

+ +

+• Argument requires a unit of measure +

+ +

+By default, mom places the title (the docheader, as it were) of +bibliographies (typically "BIBLIOGRAPHY") 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 +bibliography itself), invoke .BIBLIOGRAPHY_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: +
+ + .BIBLIOGRAPHY_STRING_ADVANCE 1.5i + +

+ + + +

• Title string underscoring

+ +

+Macro: BIBLIOGRAPHY_STRING_UNDERSCORE [DOUBLE] [<underline weight> [<underline gap> [<distance between double rules]]] | <none> | <anything> +

+ +

+Alias: BIBLIOGRAPHY_STRING_UNDERLINE +

+ +

+• The argument +<underscore weight> +must not have the +unit of measure, +p, appended to it +

+ +

+Invoked without an argument, +.BIBLIOGRAPHY_STRING_UNDERSCORE will place a single rule +underneath the bibliography’s first-page title. Invoked with the +argument, DOUBLE, BIBLIOGRAPHY_STRING_UNDERSCORE will +double-underscore 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 BIBLIOGRAPHY_STRING_UNDERSCORE to control +the weight of the underscore rule(s), the gap between the title and +the underscore, and, in the case of double-underscores, the distance +between the two rules. +

+ +

+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, underscoring (single or +double) is enabled whenever BIBLIOGRAPHY_STRING_UNDERSCORE is used +in this way. +

+ +

+By default, mom double-underscores the title if your +PRINTSTYLE +is TYPEWRITE. +

+ + + +

• Title string capitalization

+ +

+Macro: BIBLIOGRAPHY_STRING_CAPS toggle +

+ +

+Invoked by itself, .BIBLIOGRAPHY_STRING_CAPS will +automatically capitalize the bibliography first-page title. Invoked +with any other argument, the macro disables automatic capitalization +of the title. +

+ +

+If you’re generating a table of contents, you may want the +bibliography first-page title to be in caps, but the toc entry in +caps/lower case. If the argument to +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 first-page +title. +

+ +

+ + + + + + + + +

Back to Table of Contents

Top

Next: Writing letters

+ +

+ + + diff --git a/contrib/mom/momdoc/reserved.html b/contrib/mom/momdoc/reserved.html new file mode 100644 index 0000000..4cdab3b --- /dev/null +++ b/contrib/mom/momdoc/reserved.html @@ -0,0 +1,2736 @@ + + + + + + + + + Mom -- Reserved words (macros, strings, registers) + + + + + + + +

+ + + + + + +

Back to Table of Contents

+ +

List of reserved words (macros, strings, registers)

+ +

+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, choose something +else instead. +

+ +

+Anyone interested in hacking/patching mom’s macro file +(om.tmac) will also find this list useful since it lists most of +the macros, strings, diversions, aliases, and number registers +mom uses, along with brief descriptions of their functions. +

+ +

+The list is not exhaustive. PDF-related macros, strings, registers, +and diversions, as well as those associated with preprocessor +support and “Lists of” are not included. +

+ +

+ + +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 + +*Quad, fill, justification + JUSTIFY Justified text + QUAD Filled text, left, right, or centre + +*Quad, no-fill + CENTER Line-for-line, non-filled text, centre + LEFT Line-for-line, non-filled text, left + RIGHT Line-for-line, 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 + +*Vertical motions + 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 + +*Columnar tabs + 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 circle filled? (boolean) + #CODE_FAM Use different family from Courier for CODE? (boolean) + #CODE_FT Use different font from roman 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 or .AUTOLEAD + #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) + #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_FILL Used to restore \[.u] state if temporarily changed + #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 + tbl Are we in a tbl? (boolean) + #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 + $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 (reference macros) + 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 + EQ/EN eqn block + FINIS Prints --END-- + FLOAT Keep material together as a block; defer output + to following page if not enough room to print + 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 + SUBSUBHEAD Subsubheads + TH Running tbl header + TS/TE Begin/end a tbl block + +*Headers/footers + 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 + +*Control macros +-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 + +-eqn- + EQ_INDENT Indent value if 'EQ I' + +-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 + FOOTNOTE_SPACING Post endnotenote item spacing + ENDNOTE_STRING Endnotes page head + ENDNOTE_STRING_ADVANCE Distance of title string "ENDNOTES" from top + edge of page + 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_ADVANCE Distance of title string "BIBLIOGRAPHY" from + top edge of page + 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 + HEADER_GAP Space between header and running text + HEADER_MARGIN Space from top of page to header + 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- + 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 + HEAD_BASELINE_ADJUST Amount to raise head above baseline + +-Subheads- + NUMBER_SUBHEADS Print subhead numbers + RESET_SUBHEAD_NUMBER Reset subhead number + SUBHEAD_BASELINE_ADJUST Amount to raise subhead above baseline + +-Subsubheads- + NUMBER_SUBSUBHEADS Print subhead numbers + RESET_SUBSUBHEAD_NUMBER Reset subhead number + SUBSUBHEAD_BASELINE_ADJUST Amount to raise subhead above baseline + +-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 header/footer control macros + 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 + ++++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 + TBL*CLEANUP Remove selected registers and strings created + by TS/TH/TE + TBL*GET_QUAD Establish quad of tbl caption + tbl*float-warning If tbl in a float exceeds page limits + tbl*print-header Administrivia for printing tbl headers + tbl@top-hook Trap-invoked (HEADER); prints running tbl header + and moves FOOTER/FN_OVERFLOW_TRAP_POS traps + to accommodate tbl + 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_TEXT Closing (i.e. Yours truly,) + EPI_TEXT Epigraph text + END_NOTES Endnotes text + FLOAT*DIV Float content + 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 + tbl*header-div Running tbl header + 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 defining + $AUTHOR_COVER_<n> strings + #AUTHOR_DOCCOVER_NUM Incrementing register used in defining + $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_ADVANCE Vertical position of "BIBLIOGRAPHY" string + (relative to the top edge of the page) + #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) + #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) + #CODE_COLOR Colorize CODE? (boolean) + #CODE_SIZE_ADJ Percentage by which to scale CODE font + #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 + DD Vert. space before and after eqn blocks + defer / new-defer Appended to FLOAT*DIV: if float deferred + #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 + D-float Depth of float containing/ending with + DRH, DRV, DBX, or DCL + DI eqn indent if EQ I + #DIVER_FN Register that tells FOOTNOTE whether to + "move" or "defer" a footnote collected + inside a diversion + #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 reserve 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) + float*after-shim / \n[nl]; tests if SHIM has stayed on the same + float*before-shim baseline + float-span Float can run to multiple pages? (boolean) + float*with-tbl Float contains a tbl block + #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_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) + #FORCE Force float? (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 + #H_BASELINE_ADJ Vertical spacing adjustment for heads (default=0) + #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 + #LB_CHAR_ITERATIONS Number of linebreak character iterations + #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 Test 1st arg to NUMBER_LINES for digit or string + 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) + #NUMBER_SSH Are subsubheads numbered? (boolean) + #NUM_COLS Number of columns per page + #NUMBERED If set to 1, lets PARAHEAD know that + main-, sub-, and subsubhead 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_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_BASELINE_ADJ #DOC_LEAD/8 (TYPESET) or /5 (TYPEWRITE) + (used for subhead vertical 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 ENTRY If one, don't print the first entry (the + document title) in the TOC of uncollated docs. + #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. + #SSH_BASELINE_ADJ #DOC_LEAD/8 (TYPESET) or /5 (TYPEWRITE) + (used for subsubhead vertical spacing) + #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 + #SUBHEAD Was subhead the last macro invoked? (boolean) + Controls vert. space between SUBHEAD and + SUBSUBHEAD + #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) + tbl*boxed tbl has box or allbox (boolean) + tbl*center-label-on-table Is tbl caption centered? (boolean) + tbl*have-header tbl has a running header (boolean) + tbl*header-ht Depth of tbl*header-div + tbl*left-label-on-table Is tbl caption quad left? (boolean) + tbl*move-fn-overflow-trap Whether to move FN_OVERFLOW_TRAP_POS + to accommodate tbl + tbl*move-fn-overflow Amount by which to change + FN_OVERFLOW_TRAP_POS to accommodate tbl + tbl*move-footer Amount by which to change FOOTER trap + to accommodate tbl + tbl*move-footer-trap Whether to move FOOTER trap to accommodate + tbl + tbl*no-shim Whether to SHIM tbl (boolean) + tbl*right-label-on-table Is tbl caption quad 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 + @TOP Controls .ns at page top; + trap-invoked (FOOTER); mostly trap-removed + (RR_@TOP) + #TOTAL_FIELDS Total number of letter header fields + #TRAP \n[.t]-1 (used in DO_QUOTE) + #TW Width of tbl block + #UNADJUSTED_DOC_LEAD Argument passed to DOC_LEAD prior to + adjusting (set in TRAPS) + #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 Was underlining on prior to the + invocation of current macro? (boolean) + #UNDERLINE_WAS_ON_FN As above, but for footnotes only + #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 + $CODE_FT Font to use with CODE + $CODE_COLOR Color of 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_LN_SIZE_CHANGE Size change (+ or -) for line-numbers in + line-number identified endnotes + $EN_OPEN_BRACKET Open bracket for line-number enumerated + 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 + float-adj:bottom A + or - sign + float-adj:top A + or - sign + float*type Used with tbl; 'boxed' or 'table' + 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 + $FN_SPACE Post footnote space + $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> Position of args pass to MISC + $MISC_COLOR Misc color + $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 + $REF_STYLE MLA bibliography-style or footnote/endnote + style; used in ref*add-<x> + $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_DOC_FAM Document family in effect before COLLATE + $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 + tbl*center 'C' if set + tbl*label Text of tbl caption + tbl*needs # of rows of tbl data required to print + tbl near bottom of page + tbl*user-add-space User-added space before a tbl caption + $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 + ++++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. + + ++++These aliases are for convenience, and header/footer management+++ + + BIBLIOGRAPHY_STRING_UNDERSCORE BIBLIOGRAPHY_STRING_UNDERLINE + CITATION BLOCKQUOTE + CITE BLOCKQUOTE + COL_BREAK COL_NEXT + DOC_FAM DOC_FAMILY + DOC_L_LENGTH DOC_LINE_LENGTH + DOC_L_LENGTH DOC_LINE_LENGTH + DOC_L_MARGIN DOC_LEFT_MARGIN + DOC_L_MARGIN DOC_LEFT_MARGIN + DOC_LS DOC_LEAD + DOC_PS DOC_PT_SIZE + DOC_R_MARGIN DOC_RIGHT_MARGIN + DOC_R_MARGIN 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 + ++++These aliases 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 + ++++These aliases 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 + + +

+ + + + + + + +

Back to Table of Contents

Top

+ +

+ + + diff --git a/contrib/mom/momdoc/stylesheet.css b/contrib/mom/momdoc/stylesheet.css new file mode 100644 index 0000000..9d9efa3 --- /dev/null +++ b/contrib/mom/momdoc/stylesheet.css @@ -0,0 +1,691 @@ +/* Copyright (C) 2004-2020 Free Software Foundation, Inc. */ +/* This file is part of mom, which is part of groff, a free software */ +/* project. */ + +/* You can redistribute it and/or modify it under the terms of the */ +/* "GNU General Public License" as published by the "Free Software */ +/* Foundation", version 2. + +/* The license text is available in the internet at */ +/* */ + +/* stylesheet for the mom macros documentation */ + +a:link { color: blue; text-decoration: none; } +a:hover { color: red; text-decoration: underline; } +a:visited { color: purple; text-decoration: none; } +a:visited:hover { color: purple; text-decoration: underline; } +a.header-link:visited { color: #6e70cc ; } +a.header-link:visited:hover { color: #6e70cc ; } + +a:link.quick { text-decoration: underline; } +.version /* version number for top of toc.html */ +{ + font-size: 90% ; + text-align: center ; +} + +.page /* Page setup: page color, size and border */ +{ + width: 67% ; + position: relative ; + top: 12px ; + bottom: 12px ; + margin: auto ; + padding: 12px ; + border: solid 1px #ceac8d ; + color: #302419 ; + background-color: #ffffeb ; + font: 1em/1.5em arial,sans-serif ; + font-variant-ligatures: none; +} + +.nobr /* Make a class property */ +{ + white-space: nowrap ; + hyphens: none ; +} + +/* Heads */ + +h1.docs +{ + font-family: arial,sans-serif ; + font-size: 125% ; + text-align: center ; + color: #002b56 ; + background-color: #e2f1ff ; + outline: solid 1px #99cccc ; + padding: 6px ; +} +h2.docs +{ + margin-bottom: -.25em ; + font-size: 105% ; + color: #000056 ; +} +h2.macro-group /* ie "Page setup" or "Indents" or "Multi-columns" */ +{ + margin-top: 1em ; + font-size: 120% ; + color: #000056 ; + background-color: #dfccad ; + padding: 6px ; +} +h3.docs +{ + margin-bottom: -.5em ; + font-size: 95% ; + color: #000056 ; + text-transform: uppercase ; +} +h3.appendices +{ + font-size: 100% ; + text-transform: none ; +} +h3.notes +{ + display: inline-block ; + margin-top: .5em ; +} +h3.control +{ + padding-top: .5em ; + font-size: 100% ; + text-transform: none ; +} +h3.numbered +{ + font-size: 100% ; + margin-bottom: -.5em ; +} +h3.macro-id +{ + font-size: 105% ; + color: #000056 ; + text-transform: uppercase ; + margin-top: 3px ; + margin-bottom: 0px ; +} +h4.docs +{ + font-size: 95% ; + margin-bottom: -.5em ; + color: #000056 ; +} +h4.doc-param-macros +{ + margin-top: -.5em ; +} +h4.arg-list +{ + margin-top: -.5em ; +} +h4.fields +{ + color: #302419 ; +} +h5.docs +{ + margin-bottom: -.5em ; + font-size: 95% ; + color: #000056 ; + text-transform: uppercase ; +} +ul.doc-param-macros +{ + margin-top: .75em ; + margin-left: -.5em ; +} +.control-macros-header +{ + display: inline-block ; + margin-bottom: -.25em ; + padding: 2px 6px 0 6px ; + outline: 1px solid #000058 ; + font-size: 100% ; + background-color: #e2f1ff ; +} +.control-macro +{ + font-size: 100% ; + margin-bottom: -.75em ; + color: #2f2f71 ; +} +.macro-id-overline +{ + display: inline-block ; + border-top: solid 2px #8d8775 ; + margin-bottom: .5em ; +} + +/* Paragraphs */ + +p.no-indent +{ + text-indent: 0px ; +} +p.requires +{ + font-family: arial,sans-serif ; + font-style: italic ; + text-indent: 0px ; + margin-top: .25em ; +} +p.alias +{ + font-family: arial,sans-serif ; + font-style: normal ; + text-indent: 0px ; + margin-top: .25em ; +} + +/* Horizontal rules */ + +hr /* horizontal rules need a border to be colorized) */ +{ + border: solid 1px #8d8775 ; +} +div.rule-short /* for section breaks; top/bottom margins set manually */ +{ + display: block ; + width: 25% ; + margin: auto; + clear: both ; +} +div.rule-medium /* underneath mini-tocs; top/bottom margins set manually */ +{ + display: block ; + width: 40% ; + margin: auto; + clear: both ; +} +div.rule-long /* precedes nav bar at bottom of page */ +{ + display: block ; + width: 90% ; + margin: auto; +} + +/* Boxed text */ + +.box-macro-args /* Macro name+args */ +{ + display: block ; + border: solid 1px #302419 ; + padding-top: 5px ; + padding-bottom: 3px ; + padding-left: 15px ; + padding-right: 15px ; + background-color: #ffffff ; + white-space: nowrap ; + overflow: auto ; +} +.box-code +{ + display: block ; + width: 100% ; + border: solid 1px #302419 ; + padding-top: 5px ; + padding-bottom: 18px ; + padding-left: 15px ; + padding-right: 15px ; + color: #6f614a ; + background-color: #ffffff ; + white-space: nowrap ; +} +.box-tip +{ + outline: solid 1px #ceac8d ; + padding-left: 15px ; + padding-right: 15px ; + text-align: justify ; + background-color: #f9f9d9 ; + margin-bottom: 1.5em ; + } +.box-example-layout +{ + outline: solid 1px #ceac8d ; + padding-left: 15px ; + padding-right: 15px ; + text-align: justify ; + background-color: #f9f9d9 ; + margin-bottom: 2.5em ; + } +.box-notes +{ + outline: solid 1px #ceac8d ; + padding-left: 15px ; + padding-right: 15px ; + text-align: justify ; + background-color: #f9f9d9 ; + margin-bottom: 1.5em ; + } +.box-important +{ + outline: solid 1px #ce7a65 ; + padding-left: 15px ; + padding-right: 15px ; + text-align: justify ; + background-color: #f9f9d9 ; + margin-bottom: 1.5em ; +} +p.tip +{ + padding-top: 9px ; + padding-bottom: 9px ; + text-indent: 0px ; +} +p.tip-top +{ + padding-top: 9px ; + text-indent: 0px ; +} +p.tip-bottom +{ + padding-bottom: 9px ; + text-indent: 0px ; +} + +/* Pre-formatted code */ + +span.pre /* pre-formatted multi-line blocks; indent must be exactly 2 spaces */ +{ + display: block ; + position: relative ; + top: -1em ; + margin-bottom: -1.5em ; + font-family: "Lucida Console",monospace ; + font-weight: bolder ; + font-size: 95% ; + white-space: pre ; + overflow: auto ; +} +span.defaults +{ + margin-left: 6px ; + padding-bottom: 1em ; + font-size: 95% ; +} +span.pre-in-pp +{ + display: block ; + position: relative ; + top: -1em ; + margin-bottom: -.5em ; + font-family: "Lucida Console",monospace ; + font-weight: bolder ; + font-size: 95% ; + white-space: pre ; + overflow: auto ; +} +span.important +{ + font-family: arial,sans-serif ; + font-weight: bolder ; + color: #8b0000 ; +} +span.note +{ + font-family: arial,sans-serif ; + font-weight: bolder ; + color: #443526 ; +} +span.additional-note +{ + font-family: arial,sans-serif ; + font-weight: bolder ; + font-style: italic ; + color: #443526 ; +} +span.tip +{ + font-family: arial,sans-serif ; + font-weight: bolder ; + color: #443526 ; +} +span.experts +{ + font-family: arial,sans-serif ; + font-weight: bolder ; + color: #443526 ; +} +/* Mini-tocs (usually at top of page) */ + +/* 1-column, centered mini-toc */ +ul.mini-toc-centered +{ + text-align: center ; + list-style-type: none ; + margin-left: -40px ; +} + +/* 2-column mini-toc column defs*/ +.mini-toc-col-1 +{ + float: left ; + width: 49% ; + margin-left: -10px ; +} +.mini-toc-col-2 +{ + float: left ; + width: 51% ; + clear: right ; +} + +/* 3-column mini-toc column defs */ +.col-1-definitions +{ + float: left ; + width: 32% ; + height: 55em ; + padding-bottom: 9px; + background-color: #ded4bd ; + margin-right: 2% ; +} +.col-2-definitions +{ + float: left ; + width: 32% ; + height: 55em ; + padding-bottom: 9px; + background-color: #ded4bd ; + margin-right: 2% ; +} +.col-3-definitions +{ + float: left ; + width: 32% ; + height: 55em ; + padding-bottom: 9px; + background-color: #ded4bd ; + margin-bottom: 24px ; +} + +/* List styles */ + +ul.toc +{ + margin-top: .5em ; +} +ul.no-enumerator +{ + list-style-type: none ; +} +.list-head +{ + font-family: arial,sans-serif ; + font-weight: bolder ; + font-size: 110% ; + color: #000056 ; +} +.list-head-goodies +{ + font-family: arial,sans-serif ; + font-weight: normal ; + font-size: 110% ; + color: #000056 ; +} +.no-anchor +{ + color: #302419 ; + font-weight: bold ; +} +.text-color +{ + color: #302419 ; +} +li.item +{ + font-family: arial,sans-serif ; + font-weight: normal ; + font-size: 100% ; + margin-left: -10px ; + list-style-type: disc ; +} +.mini-toc +{ + margin-top: -1em ; + font-size: 90% ; +} +.sublist +{ + margin-left: -1em ; + font-size: 90% ; + color: #302419 ; + list-style-type: disc ; +} +.sub +{ + list-style-type: circle ; +} +.normal +{ + font-style: normal ; + font-size: 100% ; +} +.normal-smaller +{ + font-weight: normal ; + color: #302419 ; + font-size: 90% ; +} +.normal-sub-sub +{ + font-weight: normal ; + color: #302419 ; + font-size: 90% ; +} + +/* Macro lists / defaults */ + +div.macro-list-container +{ + background-color: #ded4bd ; + margin-bottom: 1.5em ; +} +h3.macro-list +{ + font-size: 100% ; + color: #000056 ; + text-transform: uppercase ; + padding: 9px ; +} +ul.macro-list +{ + margin-left: -21px ; + padding-right: 12px ; + list-style-type: none ; + font-family: arial,sans-serif ; + margin-top: -1.25em ; + padding-bottom: 6px ; +} +ol.macro-list +{ + font-family: arial,sans-serif ; + margin-top: -1.25em ; + padding-bottom: 6px ; +} + +.defaults-container +{ + background-color: #e3d2b1 ; + border: 1px solid #3f2c00 ; + margin-bottom: 2.5em ; +} +h3.defaults +{ + font-size: 100% ; + color: #000056 ; + text-transform: uppercase ; + padding: 9px ; +} +p.defaults +{ + margin-top: .25em ; + margin-left: 6px ; + margin-right: 12px ; + margin-bottom: 0 ; +} +#toc-title, #toc-head, #toc-subhead, #toc-parahead +{ + display: block ; + margin-top: -1em ; + margin-bottom: -1em ; +} + +/* Bottom of page spacer */ + +div.bottom-spacer +{ + display: block ; + height: 24px ; +} + +/* General markup */ + +kbd +{ + font-family: "Lucida Console",monospace ; + font-weight: bold ; + font-size: 98% ; +} +kbd.macro-args +{ + margin-right: .5em ; + color: #6f614a ; + white-space: nowrap ; + overflow: auto ; +} + +/* tocs */ + +h1.toc +{ + font-family: arial,sans-serif ; + font-size: 175% ; + text-align: center ; + color: #002b56 ; + background-color: #e2f1ff ; + outline: solid 1px #99cccc ; + padding: 6px ; +} +h2.toc +{ + font-size: 120% ; + color: #000056 ; +} +h3.toc +{ + margin-top: -.5em ; + margin-bottom: -.5em ; + font-size: 100% ; + color: #6e70cc ; +} +.highlight +{ + font-weight: bold ; +} +.fourth-level +{ + margin-left: -1.25em ; + list-style-type: none ; +} +ul.toc-docproc +{ + margin-left: -1em ; +} +.toc-docproc-header +{ + margin-top: -.5em ; + text-transform: uppercase ; +} +a.header-link +{ + color: #6e70cc ; + font-size: 95% ; +} + +/* Examples */ + +.examples-container +{ + border: solid 1px #917963 ; + background-color: #f9f9d9 ; + padding-left: 24px ; + padding-right: 24px ; + padding-top: 3px ; + padding-bottom: 3px ; +} + +.examples +{ + font-weight: bolder ; + font-size: 98% ; + color: #524b3f ; + margin-top: 12px ; + margin-bottom: 3px ; +} + +/* definitions.html */ + +table.definitions /* mini-toc is set up as a table */ +{ + margin-top: 12px ; + text-align: left ; + margin-left: 12px ; +} +th.definitions +{ + padding-bottom: 6px ; + font-size: 120% ; + color: #000056 ; +} +dt /* definition terms in italic*/ +{ + font-style: italic ; +} +dt.no-italic +{ + font-style: normal ; +} + +/* Tables */ +table.quick-ref +{ + margin-top: .25em ; +} +table.quick-ref, th.quick-ref +{ + padding-bottom: .25em ; + font-family: "Lucida Console",monospace ; + font-weight: bold ; + text-align: left ; +} + +td +{ + padding: 0 ; + padding-left: .5em ; +} + +/* Misc */ + +span.book-title +{ + font-style: italic ; +} + +dt.params +{ + font-style: normal ; + font-weight: bold ; +} + +dd.cover-args +{ + margin-bottom: .25em; + margin-left: 1.25em ; +} diff --git a/contrib/mom/momdoc/tables-of-contents.html b/contrib/mom/momdoc/tables-of-contents.html new file mode 100644 index 0000000..1f9affb --- /dev/null +++ b/contrib/mom/momdoc/tables-of-contents.html @@ -0,0 +1,1224 @@ + + + + + + + + + Mom -- Document processing, tables of contents + + + + + + + +

+ + + + + + + +

Back to Table of Contents

Next: Bibliographies and references

+ +

Tables of contents

+ +

Introduction to tables of contents
Tables of contents appearance and behaviour
PDF output +
The TOC macro +
- TOC_HEADING
Control macros for tables of contents +
- Table of contents control macros

+ +

Introduction to tables of contents

+ +

+Want a table of contents for your document? Easy. Just enter +
+ + .TOC + +as the very last macro of your input file. Mom will have picked +up all document titles (in +collated +documents) and headings, as well as the endnotes section and +bibliography, if they exist, and assigned them the appropriate page +number. Talk about a no-brainer! +

+ +

+That said, tables of contents 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 table of +contents’ typographic appearance, you can. +

+ +

Tables of contents appearance and behaviour

+ +

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

+ +

+Mom follows standard typesetting conventions for tables of contents. +To this end, if +HEADERS +are enabled for the document, the first page of the table of +contents has no page header, but does have a first page number +(roman numeral), always “i”, in the bottom margin. If +FOOTERS +are enabled 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 table of contents, simply +invoke +.FOOTER_ON_FIRST_PAGE +immediately before .TOC.) Subsequent table of contents +pages have both page headers or footers and a page number. +

+ +

+Entries in a table of contents are hierarchically indented, as you +would expect, and if headings are numbered in the body of the document, +you can instruct mom to number them in the table of contents as +well (see +TOC_ENTRY_NUMBERS). +

+ +

+Tables of contents are never set in columns, regardless of whether +the rest of the document is. Lastly, if +recto/verso +printing is enabled, the table of contents respects it. This +sometimes leads to tables of contents that begin with the wrong +margins, but the margins can be corrected either by outputting a +BLANKPAGE +or by using the control macro +TOC_RV_SWITCH. +

+ +

+The overall table of contents +family, +point size +and +lead +can be altered with +control macros, +as can the family, +font, +point size and indent of each level of entry. Furthermore, the page +numbering style can be changed, as can the amount of visual space +reserved for entry page numbers. +

+ +

PDF output

+ +

+When files containing a table of contents are processed with +pdfmom, +entries in the table of contents are clickable links when the +document is viewed at the screen. The colour of the links is the +last .PDF_LINK_COLOR in effect, so if you wish another +colour, it should be set just before issuing .TOC. +

+ +

+When preparing files for printing, coloured links in both the table +of contents and elsewhere in the document may not be desirable. +You can disable the colour by passing +pdfmom +the -c option, like this:
+ + pdfmom -c doc.mom > doc.pdf + +

+ +

Positioning the Table of Contents

+ +

+Because a table of contents can’t be generated until the +end of a document (hence the last macro in the file), it is also +the last page of the document. While this is desirable for some +language conventions—French, for example—it is not +desirable for others. +

+ +

Automatic PDF relocation of the Table of Contents

+ +

+When +pdfmom +is used to process files with a table of contents, the macro +.AUTO_RELOCATE_TOC can be used to reposition the table +of contents to the top of the output document, with the presence +of a cover and/or title page sensibly taken into account. Full +AUTO_RELOCATE_TOC usage is described in the manual, +Producing PDFs with groff and mom. +

+ +

+In order to take advantage of automatic table of contents +repositioning, you must use +pdfmom +with groff’s native PDF driver (i.e. without the +-Tps flag). Files that need to be processed with +the -Tps flag require you to reposition the table +of contents yourself with psselect, described +below. +

+ +

+Note: +AUTO_RELOCATE_TOC must come before +START. +

+ +

Using psselect to relocate the Table of Contents in PostScript documents

+ +

+To change the location of the table of contents in files +processed with pdfmom -Tps, you have two choices: +rearrange the pages by hand (okay for one or two hard copies), +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 to put the +table of contents near the beginning of a document begins by +you determining how many pages it contains. You can do this by +previewing the document with the document viewer of your choice +(gv, Okular, Evince, etc). +

+ +

+Once you know the number of pages in the table of contents, you use +psselect to place them where you want. +

+ +

+Say, for example, the table of contents runs to just one page. The +command to place a one-page table of contents at the start of a +document is: +
+ + psselect -p _1,1-_2 + +The -p option instructs psselect that what +follows is a comma-separated list of the order in which you want +pages of a document rearranged. 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 +(i.e. the last page before the table of contents)." +

+ +

+If your table of contents runs to two pages, the option to +psselect would look like this: +
+ + psselect -p _1-_2,1-_3 + +If your table of contents runs to two pages and you have a cover +page, the command would look like this: +
+ + psselect -p 1,_1-_2,2-_3 + +

+ +

+Note: +psselect outputs to stdout, so you have to redirect the +output to a new file. +
+ + psselect -p <page list> <file>.ps > <new-file>.ps + +

+ + + +

The TOC macro

+ +

+Macro: TOC [ INCLUDE_TITLE ] +

+ +

+If you want a table of contents, just place .TOC at the +very end of your document. Mom takes care of the rest. +

+ +

+The optional argument, INCLUDE_TITLE, is needed only +if your document is standalone, i.e. is not collated, for example +an essay. By default, mom does not include the title (and page +number) of standalone documents in the Table of Contents since it +is largely redundant. If you would like her to include the title, +invoke .TOC with INCLUDE_TITLE. +

+ +

+Note: +If the last line of text in a document, before .TOC, +falls too close to the bottom margin, or if the line is followed +by a macro likely to cause a linebreak (e.g. .LIST OFF or +.IQ), mom may output a superfluous blank page before the +Table of Contents. +

+ +

+In order to avoid this, insert +.EL +after the last line of text, before .TOC and/or any +concluding macros. For example, +
+ + some concluding text. + .EL + .TOC + +or +
+ + some concluding text. + .EL + .LIST OFF + .TOC + +

+ +

TOC heading

+ +

+Macro: TOC_HEADING "<single line TOC heading>" +

+• Argument must be enclosed in double-quotes +

+ +

+You may sometimes want to insert a line of text into the table of +contents without it referring to a page number, for example to +identify a “Part I” and a “Part II”. +

+ +

+Placed before any instance of the +START +macro, TOC_HEADING inserts its text into the table of contents +before the next section title or heading. A modest amount of +whitespace is introduced above and beneath to distinguish it easily +from table of contents entries. +

+ +

+The appearance of the heading may be controlled with +the macro +TOC_HEADING_STYLE. +

+ + +

+ +

Control macros for tables of contents

+ +

+Aside from allowing you to set the style of table of contents +entries on a per-level basis, the control macros let you design +the table of contents as if they were a complete document unto +themselves (overall family, headers/footers, pagination, etc). +

+ +

Table of contents control macros

+ +

General table of contents style control +
- TOC_FAMILY – base family for tables of contents
- TOC_PT_SIZE – base point size for tables of contents
- TOC_LEAD – leading of tables of contents
Page numbering +
- PAGINATE_TOC – turn table of contents pagination on or off
- TOC_PAGENUM_STYLE – table of contents page numbering style
Header string (e.g. “Contents”) and style +
Entries and reference page number style +
- Reference page numbers style control
- Title entry style control
- Heading entry style control
- Numbering table of contents items +
  - Prefix chapter/section numbers +
    - Pad chapter/section numbers
  - Numbering heading entries
Additional table of contents control macros +
I still need more!

+ +

1. General tables of contents style control

+ + + +

+Macro: TOC_FAMILY <family> +

+ +

+TOC_FAMILY establishes the default family for every page element in +a table of contents, including the table of contents’ header +string (by default, “Contents”) and the page +number in the top or bottom margin. The default is the prevailing +document family. +

+ +

+All page elements in the table of contents also have their own +_FAMILY control macros, which can be used on a case-by-case basis to +override the default family set with TOC_FAMILY. +

+ + + +

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

+ +

+• Does not require a unit of measure; points is assumed +

+ +

+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. (Compare this with the +_SIZE +control macros.) The argument represents the base point size +of tables of contents from which the size of all other table of +contents elements are calculated. +

+ +

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

+ + + +

+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 tables of contents in +points +unless you append an alternative +unit of measure. +For example, +
+ + .TOC_LEAD 14 + +sets the base leading of tables of contents to 14 points, whereas +
+ + .TOC_LEAD .5i + +sets the base leading of tables of contents to 1/2 inch. +

+ +

+If you want the leading of tables of contents 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 the leading of the table of +contents. You must enter +TOC_LEAD <lead> with no ADJUST +argument to disable this default behaviour. +

+ +

+Additional note: +Tables of contents are always double-spaced in +PRINTSTYLE TYPEWRITE, +regardless of whether the body of the document is single-spaced. +

+ +

2. Page numbering

+ +

+The pagination style of tables of contents is controlled by the same +macros that control +document page numbering, +except +PAGENUM +(tables of contents always start on page 1). The defaults are the +same as for the rest of the document, with the exception that tables +of contents, by default, have roman numeral page numbers. +

+ +

+Therefore, if you wish to change some aspect of table of contents +pagination style, use the +document pagination control macros +immediately prior to .TOC. +

+ +

+A special macro, +TOC_PAGENUM_STYLE, +controls the style of table of contents pagination (i.e. the actual +table of contents pages’ numbers, not the page number +references of entries). +

+ + + +

+Macro: PAGINATE_TOC <toggle> +

+ +

+By default, mom paginates tables of contents. If you’d like +her not to, do +
+ + .PAGINATE_TOC OFF + +(or NO, X, etc). +

+ +

+Note: +Simply invoking +.PAGINATION OFF +or +.PAGINATE OFF +disables table of contents pagination for the first +page of the table of contents only. You must use +.PAGINATE_TOC OFF to disable table of contents +pagination completely, even if pagination is turned off elsewhere in +your document. +

+ + + +

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

+See +PAGENUM_STYLE +for an explanation of the arguments. +

+ +

+By default, mom uses roman numerals to number table of contents +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. Header string and style

+ +

+The table of contents header string is the title that appears at the top of the +table of contents. By default, it’s “Contents”.

+ +

+Macro: TOC_HEADER_STRING <string> +

+ +

+If you’d like the title of the table of contents to read +something other than “Contents”, do, for +example +
+ + .TOC_HEADER_STRING "Table of Contents" + +

+ +

Header string vertical placement

+ +

+Macro: TOC_HEADER_V_POS <distance from top of page> +

+• Requires a unit of measure +

+ +

+Normally, the TOC header string falls at the same vertical position +as the +docheader. +If you’d like it to fall at a different position, say 2 inches, use +
+ + .TOC_HEADER_V_POS 2i + +

+ +

Header string control macros and defaults

+ +

+See +Arguments to the control macros. +
+The following TOC_HEADER control macros may also be +grouped +using TOC_HEADER_STYLE. +

+ +.TOC_HEADER_FAMILY default = prevailing doc family +.TOC_HEADER_FONT default = bold +.TOC_HEADER_SIZE default = +4 +.TOC_HEADER_QUAD default = left +.TOC_HEADER_COLOR default = black +.TOC_HEADER_CAPS default = no +.TOC_HEADER_SMALLCAPS default = no +.TOC_HEADER_UNDERSCORE default = none + +

+ +

4. Entries and reference page numbers style

+ +

+“Entries” refers to the hierarchical arrangement of +section titles (in +collated +documents) and headings as they appear in the table of contents: + + Section title + Head level 1 + Head level 2 + Head level 3 + ... + +The style for title entries (e.g. chapter numbers or titles) and +heading levels is controlled by +TOC_TITLE_STYLE +and +TOC_ENTRY_STYLE +respectively. +

+ +

+“Reference page numbers” means the page numbers +associated with entries. Macros to control their style take the +form .TOC_PN_<SPEC>, and the defaults are listed +here. +

+ +

+See +Arguments to the control macros. + + +.TOC_PN_FAMILY default = prevailing doc family +.TOC_PN_FONT default = roman +.TOC_PN_SIZE default = 0 + +

+ + + +

+Macro: TOC_TITLE_STYLE <see below for args> +

+ +

+TOC_TITLE_STYLE allows you to set all the style parameters for +title entries in the tables of contents with one macro. The +number of arguments can run long, so you may want to break them into +several lines with the backslash character (\). The +arguments are: +
+ + FAMILY <family> + FONT <font> + SIZE +|-<n> + COLOR <color> + INDENT <amount> + CAPS | NO_CAPS + +The arguments may be entered in any order. +

+ +

+The family, font, size, and color arguments behave identically +to the individual control macros that govern other tags, therefore see +Arguments to the control macros +for usage. Their defaults are the same as for paragraphs in +running text. +

+ +

+INDENT lets you indent title entries by the amount specified, and +requires a +unit of measure. +The default is zero. +

+ +

+CAPS instructs mom to capitalize title entries. +Capitalization may be enabled or disabled on a per-entry-level +basis. +

+ +

+As an example, if you want title entries bold, slightly larger than other +entries and capitalized, you could do either +
+ + .TOC_TITLE_ENTRY FONT B SIZE +.5 CAPS + +or +
+ + .TOC_TITLE_ENTRY \ + FONT B \ + SIZE +.5 \ + CAPS + +

+ + + +

+Macro: TOC_ENTRY_STYLE <level> <see below for remaining args> +

+ +

+TOC_ENTRY_STYLE allows you to set individually all the style +parameters for any level of entry (beneath titles) in the tables +of contents. The number of arguments can run long, so you may +want to break them into several lines with the backslash character +(\). +

+ +

+<level> corresponds to a +HEADING +level assigned in the body of the document. The remaining arguments +are as follows. +
+ + FAMILY <family> + FONT <font> + SIZE +|-<n> + COLOR <color> + INDENT <amount> + CAPS | NO_CAPS + +The arguments may be entered in any order. +

+ +

+INDENT lets you indent entries by the amount specified, and +requires a +unit of measure. +Mom sensibly indents and aligns all levels of entry. If you change +the indent for any level, all levels beneath it are still indented +according to mom’s normal arrangement, but with the indent +assigned to level taken into account. When you use +INDENT, the indent is measured from the left edge of +the text of the previous level, including numbering, if any. +

+ +

+CAPS instructs mom to capitalize title entries. +Capitalization may be enabled or disabled on a per-title basis. +

+ +

+As an example, if you want a particular entry level, say +“2”, to be in Helvetica, italics, and slightly larger +than other entries, you could do either +
+ + .TOC_ENTRY_STYLE 2 FAMILY H FONT I SIZE +.25 + +or +
+ + .TOC_ENTRY_STYLE 2 \ + FAMILY H + FONT I \ + SIZE +.25 + +

+ + + +

+Macro: TOC_PREFIX_CHAPTER_NUMBER <none> <anything> +

+Alias: TOC_PREFIX_SECTION_NUMBER +

+ +

+By default, mom does not prefix a chapter number to chapters or +section titles in the table of contents. If you would like her to +do so, invoke .TOC_PREFIX_CHAPTER_NUMBER without an +argument before +START. +

+ +

+You may subsequently disable the prefixing of chapter numbers +by supplying the macro with any argument (OFF, +QUIT, Q, X...) prior to the +.START that comes after +.COLLATE. +

+ +

+This macro is useful you want chapters numbered in the table of +contents but the chapters themselves are identified by title only. +It can be used with both +DOCTYPE CHAPTER +and +DOCTYPE DEFAULT. +The alias TOC_PREFIX_SECTION_NUMBER may be preferable +in the latter case. +

+ + + +

+Macro: PAD_TOC_CHAPTER_NUMBERS <number of chapters> +

+Alias: PAD_TOC_SECTION_NUMBERS +

+ + +

+If the number of chapters or major sections +(DOCTYPE DEFAULT) +exceeds 9, you can have mom pad the numbers so the rightmost +numerals of the chapter numbers align. Simply invoke +PAD_TOC_CHAPTER_NUMBERS with the number of chapters in +the document. +

+ +

+Without padding: +
+ + 9. Chapter Title.....................100 + 10. Chapter Title....................123 + +With padding: +
+ + 9. Chapter Title....................100 + 10. Chapter Title....................123 + +

+ + + +

+Macro: TOC_ENTRY_NUMBERS <FULL> <TRUNCATE> <NONE> +

+ +

+If numbering is enabled for any level of +HEADING, +mom, by default, includes the numbering in that level’s +entries in table of contents. If you would prefer that +numbering not be included in the table of contents, +issue .TOC_ENTRY_NUMBERS NONE. If +you’d like to include numbering, but not the full, +concatenated numbering used in the body of the document, issue +.TOC_ENTRY_NUMBERS TRUNCATE. +

+ +

+Assuming numbering is enabled for HEADINGs 1, 2, and 3, +.TOC_ENTRY_NUMBERS FULL (mom’s default), would +result in +
+ + 1. Level-1 entry + 1.1. Level-2 entry + 1.1.1. Level-3 entry + 2. Level-1 entry + 2.1. Level-2 entry + 2.1.1. Level-3 entry + +whereas .TOC_ENTRY_NUMBERS TRUNCATE would produce +
+ + 1. Level-1 entry + 1. Level-2 entry + 1. Level-3 entry + 2. Level-1 entry + 1. Level-2 entry + 1. Level-3 entry + +and .TOC_ENTRY_NUMBERS NONE would remove numbering +completely. +
+ + Level-1 entry + Level-2 entry + Level-3 entry + Level-1 entry + Level-2 entry + Level-3 entry + +

+ +

+Note: +.TOC_ENTRY_NUMBERS TRUNCATE removes the numbering +associated with table of contents chapter or section titles +when +PREFIX_CHAPTER_NUMBER +is enabled. To enable the numbering of chapter or section titles +in this circumstance, use +TOC_PREFIX_CHAPTER_NUMBER. +

+ +

5. Additional table of contents control macros

+ +

+The following five macros allow you to +

instruct mom to append author(s) to TITLE entries
alter the wording of TITLE entries
instruct mom to space table of contents entries pleasingly
establish how many placeholders to leave for page number references
switch table of contents page margins should they be incorrect for recto/verso printing

+ + + +

+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 table of contents’ title entry for each story or +article. +

+ +

+If you invoke .TOC_APPENDS_AUTHOR without an +argument, mom appends the first argument you passed to +AUTHOR +to table of contents 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 table of +contents 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 table of contents. +

+ + + +

+Macro: TOC_TITLE_ENTRY "<alternate wording for a title entry in the toc>" +

+ +

+In +collated +documents, the title of each chapter appears in the table of +contents. It may sometimes happen that you don’t want the +title as it appears in the table of contents 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 table of contents. (By default, .TOC +generates both.) +

+ +

+If you want to change the wording of a title entry in the table of +contents, 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 table of contents simply as +“Burning Bush”. +

+ + + +

+Macro: SPACE_TOC_ITEMS +

+ +

+If you’d like mom to add a small amount of space between table +of contents entry levels, use .SPACE_TOC_ITEMS. Mom will +visually group entry levels in a way that’s pleasing to the +eye. The only catch to this macro is that the bottom margins of +table of contents pages may not align perfectly. +

+ +

+Please note that +SPACE_TOC_ITEMS is only available with +PRINTSTYLE TYPESET. +

+ + + + +

+Macro: TOC_PADDING <number of placeholders to allow for page number listings> +

+ +

+By default, mom allows room for 3 digits in the page number +references of table of contents entries. If you’d like some +other number of placeholders, say 2 (if your document runs to less +than 100 pages), do +
+ + .TOC_PADDING 2 + +

+ + + +

+Macro: TOC_RV_SWITCH +

+ +

+TOC_RV_SWITCH doesn’t take an argument. It simply instructs +mom to switch the left and right margins of the first table of +contents page in +recto/verso +documents should the table of contents 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. +

+ +

6. I still need more!

+ +

+If there is some aspect of Table of Contents formatting for which +no TOC control macros are provided, mom has a special +toggle macro +to help out: TOC_PAGE_SETTINGS. +

+ +

+TOC_PAGE_SETTINGS allows you to enter extra formatting changes for +the Table of Contents as if it were simply another collated section +or chapter of a document. Because it’s a toggle macro, +invoking it by itself begins collecting your formatting directives, +and invoking it with any argument (OFF, QUIT, +END...) stops the collection. +

+ +

+TOC_PAGE_SETTINGS is special in that the formatting commands +contained within it must be preceded by \! (that’s +backslash-exclamation point). +

+ +

+For example, say you want to redesign the default page headers for +the Tables of Contents so that it only contains the document title +on the left and “Contents” in italics on the right, and +furthermore adjust the footer margin and footer gap, this is how +you’d do it: +
+ + .TOC_PAGE_SETTINGS + \!.HEADER_RECTO L "^\E*[$TITLE]#\*[IT]Contents\*[PREV]^" + \!.FOOTER_MARGIN 3P + \!.B_MARGIN 6P+3p + .TOC_PAGE_SETTINGS END + +(For an explanation of why the example uses .B_MARGIN to +set/change the footer gap, see +here.) +

+ +

+TOC_PAGE_SETTINGS can be put in the stylesheet section of a document +(i.e. after +PRINTSTYLE +and before +START) +or invoked just before +TOC. +

+ +

+ + + + + + + + +

Back to Table of Contents

Top

Next: Bibliographies and references

+ +

+ + + diff --git a/contrib/mom/momdoc/toc.html b/contrib/mom/momdoc/toc.html new file mode 100644 index 0000000..6273751 --- /dev/null +++ b/contrib/mom/momdoc/toc.html @@ -0,0 +1,476 @@ + + + + + + + + + Mom, version 2.5_d -- Table of Contents + + + + + + + +

+ +

+ mom, version 2.5_d +

+ +

+ The table of contents is large. To ease navigation, + click on any link in the +
+ Quick Table of Contents +
+ which will take you to the corresponding entry in the +
+ Detailed Table of Contents. +
+ If you’ve been using mom for a while, you may prefer the +
+ Quick Reference Guide, +
+ which gives a convenient, categorized list of mom’s + user-space macros with links to corresponding entries in the + documentation. +

+ +

+ + + +

Quick Table of Contents

+ +

VERSION 2.0 NOTES

+
+ +

INTRODUCTION TO MOM

+ +

What is mom?
Definitions of terms used in this manual
Using mom

+ +

TYPESETTING WITH MOM

+ +

Introduction to the typesetting macros
Page setup
Basic typesetting parameters
Justifying, quadding, etc.
Refinements
Modifying type
Vertical movements
Tabs
Multiple columns
Indents
Goodies
Inline escapes
Coloured text
Graphical objects

+ +

DOCUMENT PROCESSING WITH MOM

+ +

Introduction to document processing
Document defaults
Vertical whitespace management
Preliminary document setup
Behaviour of the typesetting macros during document processing
The document element tags – headings, paragraphs, quotes, etc.
Graphics, floats, and preprocessor support
Shaded backgrounds and frames
Page headers and footers
Pagination
Recto/verso printing and collating
Cover pages
Tables of contents
Bibliographies and references
Writing letters +
Quick reference guide
Appendices

+ +

+ + + +

Detailed Table of Contents

+ +

VERSION 2.0 NOTES

+ +

Prefatory comments
Differences between 2.0 and 1.x +
- PDF Support
- Covers
- Headings
- Margin notes
- Floats
- Table of Contents
The pdfmom wrapper around groff
The install-font script

+ +

1. WHAT IS MOM?

+ +

2. DEFINITIONS OF TERMS USED IN THIS MANUAL

+ +

3. USING MOM

+ +

+ + + +

4. TYPESETTING WITH MOM

+ +

4.1 Introduction to the typesetting macros
4.2 Page setup – paper size and page margins +
- 4.2.1 Macro list
4.3 Basic typesetting parameters – family, font, fallback font, point size, line space, line length, autolead +
- 4.3.1 Macro list
4.4 Justifying, quadding, filling and breaking lines +
- 4.4.1 Macro list
4.5 Refinements – word space, sentence space, letter spacing (track kerning), hyphenation, kerning, ligatures +
- 4.5.1 Macro list
4.6 Modifying Type – pseudo-italic, -bold, -condensed, and -extended +
- 4.6.1 Macro list
4.7 Vertical Movements – moving up and down on the page +
- 4.7.1 Macro list
4.8 Tabs +
- 4.8.1 Typesetting tabs +
  - 4.8.1.1 Quickie tutorial
- 4.8.2 String tabs (autotabs) +
  - 4.8.2.1 Quickie tutorial
- 4.8.3 Macro list
4.9 Multiple columns +
- 4.9.1 Macro list
4.10 Indents +
- 4.10.1 A brief explanation of how mom handles indents
- 4.10.2 Macro list
4.11 Goodies + – aliases, transparent (comment) lines, smartquotes, caps, + underscoring/underlining, padding lines, leaders, drop + caps, superscripts, user-definable strings, changing the + escape character +
- 4.11.1 Macro list
4.12 Inline Escapes +
4.13 Coloured text +
- 4.13.1 Introduction to coloured text
- 4.13.2 Macro list
4.14 Graphical objects + – horizontal and vertical rules, boxes, ellipses (circles) +
- 4.14.1 Introduction to graphical objects
- 4.13.2 Macro list

+ + + +

5. DOCUMENT PROCESSING WITH MOM

5.1 Introduction to document processing
5.2 Document defaults – papersize, margins, etc. +
- 5.2.1 Vertical whitespace management +
  - 5.2.1.1 SHIM
  - 5.2.1.2 FLEX
5.3 PRELIMINARY DOCUMENT SETUP +
- 5.3.1 Tutorial – setting up a mom document
- 5.3.2 The reference macros – metadata mom needs to do her job +
  - 5.3.2.1 TITLE
  - 5.3.2.2 DOCTITLE
  - 5.3.2.3 SUBTITLE
  - 5.3.2.4 AUTHOR
  - 5.3.2.5 CHAPTER
  - 5.3.2.6 CHAPTER_TITLE
  - 5.3.2.7 DRAFT
  - 5.3.2.8 REVISION
  - 5.3.2.9 COPYRIGHT
  - 5.3.2.10 MISC
  - 5.3.2.11 COVERTITLE
  - 5.3.2.12 DOC_COVERTITLE
  - 5.3.2.13 PDF_TITLE
  - 5.3.2.14 TOC_HEADING
- 5.3.3 The docstyle macros – base templates; what kind of document you’re creating, how you want it to look overall +
  - 5.3.3.1 DOCTYPE – the kind of document (default, chapter, named, letter) +
    - DOCTYPE SLIDES
  - 5.3.3.2 PRINTSTYLE – typeset or “typewritten, double-spaced”
  - 5.3.3.3 COPYSTYLE – draft or final
- 5.3.4 Initiate document processing +
  - 5.3.4.1 START – the required macro to initiate document processing
- 5.3.5 Managing the DOCHEADER – title, author, etc. on first page +
  - 5.3.5.1 DOCHEADER control
- 5.3.6 Setting documents in columns
- 5.3.7 Establishing type and formatting parameters before START +
  - 5.3.7.1 Use of the typesetting macros before START +
    - – 5.3.7.1.1 Including (sourcing) style sheets and files
    - – 5.3.7.1.2 Initializing colours
  - 5.3.7.2 DOC_LEAD_ADJUST – adjust document + leading + to fill pages
- 5.3.8 Changing basic type and formatting parameters after START
- - 5.3.8.1 Behaviour of the typesetting macros during document processing
  - 5.3.8.2 Post-START global style-change macros
5.4 THE DOCUMENT ELEMENT TAGS +
- 5.4.1 Introduction to the document element tags +
  - 5.4.1.1 Control macros – changing style defaults for document element tags
  - 5.4.1.2 Arguments to the control macros
- 5.4.2 Epigraphs
- 5.4.3 Paragraphs
- 5.4.4 Headings
- 5.4.5 Linebreaks – author linebreaks (section breaks)
- 5.4.6 Quotes – line for line poetic quotes or unformatted, verbatim text (e.g. blocks of code)
- 5.4.7 Blockquotes – cited material
- 5.4.8 Code – inserting code snippets
- 5.4.9 Lists – nested lists
- 5.4.10 Line numbering
- 5.4.11 Footnotes
- 5.4.12 Endnotes
- 5.4.13 Margin notes
- 5.4.14 Document termination string – FINIS
5.5 GRAPHICS, FLOATS, AND PREPROCESSOR SUPPORT +
5.6 SHADED BACKGROUNDS AND FRAMES +
+
5.7 PAGE HEADERS AND FOOTERS +
5.8 PAGINATION +
5.9 RECTO/VERSO PRINTING, COLLATING +
- 5.9.1 Introduction to recto/verso printing +
  - 5.9.1.1 Macro list
- 5.9.2 Introduction to collating +
  - 5.9.2.1 The COLLATE macro
5.10 COVER PAGES
5.11 TABLES OF CONTENTS +
5.12 BIBLIOGRAPHIES AND REFERENCES
5.13 WRITING LETTERS +

6. QUICK REFERENCE GUIDE

7. APPENDICES

+ +

+ + + diff --git a/contrib/mom/momdoc/typesetting.html b/contrib/mom/momdoc/typesetting.html new file mode 100644 index 0000000..51d199e --- /dev/null +++ b/contrib/mom/momdoc/typesetting.html @@ -0,0 +1,4988 @@ + + + + + + + + + Mom -- Typesetting Macros + + + + + + + +

+ + + + + + + +

Back to Table of Contents

Next: Goodies

+ +

The typesetting macros

+ +

Introduction
Paper and page setup +
- Important note on page dimensions & papersize
- Macro list
Basic typesetting parameters +
- Macro list
Justification and quadding/ +
+ breaking and joining lines +
- Macro list
Typographic refinements +
- Macro list
Type modifications (pseudo font styles) +
- Macro list
Vertical movements +
- Macro list +

Tabs +
- Typesetting tabs +
  - Quickie tutorial on typesetting tabs
- String tabs +
  - Quickie tutorial on string tabs
- Macro list
Multiple columns +
- Macro list +
Indents +
- How mom handles indents
- Macro list +
Goodies +
- Macro list +
Inline escapes +
- List of inline escapes +
Coloured text +
- Macro list

+ +

Introduction

+ +

+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, +headings, footnotes, etc). What they do demand is precise control over +every element on the page. The typesetting macros give you that +control. +

+ +

+ + + +

Paper and page setup: paper size & page margins

+ +

+The page setup macros establish the physical dimensions of your page +and the margins you want it to have. The +PAPER +macro provides a shortcut for setting the page to the correct +dimensions for a number of common 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

+ +

+When mom files are processed with +pdfmom, +which is recommended (see +Producing PDFs with groff and mom), +page dimensions are automatically passed to groff, and you +don’t have to worry about them. +

+ +

+Mom documents processed directly with groff, or with +pdfroff, or with pdfmom ‑Tps, require +that the papersize be given on the command line as well if the +papersize is different from the default on your system. You can +verify—or change—the default papersize by inspecting the +files +
+ + <path to groff>/font/devps/DESC + +and +
+ + <path to groff>/font/devpdf/DESC + +(See man papersize for list of valid papersize +names, as well as for instructions on how to enter a non-standard +size.) +

+ +

+If you occasionally need to print on sheets that do not +conform to your default papersize, you must, in addition +to setting the page dimensions in your mom file, pass the +-P-p<papersize> option to groff, +pdfroff, or pdfmom -Tps. +

+ +

+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), +you must include -P-p<papersize> on whichever +command line you use, e.g. +
+ + pdfmom -Tps -mom -P-plegal + +Remember, though, that +pdfmom, +with no -Tps option, is smart enough to know the +papersize from the dimensions provided in your mom file. +

+ +

+Consult man groff, man grops and man +groff_font for additional information concerning papersizes, +as well as information on printing in “landscape” +orientation. +

+ +

Paper and page setup macros

+ +

PAGEWIDTH – page width
PAGELENGTH – page length
PAPER – common paper sizes
L_MARGIN – left margin
R_MARGIN – right margin
T_MARGIN – top margin
B_MARGIN – bottom margin
PAGE – page dimensions and margins all in one fell swoop
NEWPAGE – start a new page

+ + + +

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 that 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> [ LANDSCAPE ] +

+ +

+PAPER provides a convenient way to set the dimensions for some +common printer sheet sizes. <paper type> can +be one of: +
+ + LETTER EXECUTIVE + LEGAL 10x14 + STATEMENT A3 + TABLOID A4 + LEDGER A5 + FOLIO B4 + QUARTO 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 + +If you’d like landscape orientation for your paper type, +pass PAPER the LANDSCAPE argument. +

+ +

+Please read the +Important note on page dimensions and papersize +for information on ensuring groff respects your PAPER size. +

+ +

+Important: If you need PAPER, +it should always be placed at the very top of your file. +

+ + + +

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. +Left indents +and +tabs +are calculated from the value you pass to L_MARGIN. +If you use the macros +PAGEWIDTH +or +PAPER +without setting L_MARGIN, mom automatically sets the left margin to +1 inch. +

+ +

+A unit of measure is required and 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 + +

+ +

+Note: L_MARGIN behaves in a special way +when you’re using the +document processing macros. +See +Typesetting macros during document processing +for an explanation. +

+ + + +

Right margin

+ +

+Macro: R_MARGIN <right margin> +

+• Requires a unit of measure +

+ +

+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. Mom can’t make the calculation if +she doesn’t know the page width and the left margin. +

+ +

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

+ +

+Note: R_MARGIN behaves in a special way when you’re +using the +document processing macros. +See +Typesetting macros during 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. +

+ +

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

+ +

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

+ + + +

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 +

+ +

+IMPORTANT: If you’re using the +document processing macros, +PAGE must come after +PRINTSTYLE. +Otherwise, it should go at the top of a document, prior to 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). +

+ +

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

+ +

+Additionally, if you are not using the +document processing macros +and invoke PAGE with a top margin argument, any macro you invoke +after PAGE will likely move the +baseline +of the first line of text down by one linespace. To compensate, do +
+ + .RLD 1v + +immediately before entering any 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). +

+ +

+ + + +

Basic typesetting parameters

+ +

+The basic typesetting parameter macros deal with 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 during document processing +for an explanation. +

+ +

Basic parameter macros

FAMILY – type family
FT – font
FALLBACK_FONT – for invalid fonts
PT_SIZE – point size of type
LS – line spacing/leading
AUTOLEAD – automatic line spacing
LL – line length

+ + + +

Type family

+ +

+Macro: FAMILY <family> +

+Alias: FAM +

+ +

+FAMILY takes one argument: the name of the +family +you want. Groff comes with a small set of basic 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. +

+ +

+Furthermore, if you need to access a character from groff's Zapf +Dingbats font directly, use .FT ZD or the +inline escape +\f[ZD]. Commonly-used dingbats are +available without changing to the ZD font by using groff's +pre-defined character escapes, e.g. \[rh] for a pointing +right hand; see man groff_char for a complete list. +Dingbats that have not been pre-defined must be accessed with the +\N escape. For example, \f[ZD]\N'37' prints +the (undefined) telephone dingbat. +

+ +

+Additional note: +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. +

+ +

+Please see the Appendices, +Adding 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. +

+ +

+Suggestion: When adding +families to groff, I recommend following the established standard +for the 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. +

+ + + +

FT

+ +

+Macro: FT R | I | B | BI | <any other valid font style> +

+Alias: FONT +

+ +

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

+ +

+Mom 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 +Adding fonts to groff +for instructions and information.) Please also read the +Additional note +found in the description of the FAMILY macro. +

+ +

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

+ + + + +

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

+ +

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

+ +

+.FALLBACK_FONT WARN +
+mom will issue a warning whenever you try to access a non-existent +font but will continue processing your file with the default +fallback font, Courier Medium Roman. +
+
+.FALLBACK_FONT TR WARN +
+mom will issue a warning whenever you try to access a non-existent +font but will continue processing your file with a fallback font of +Times Roman Medium Roman; additionally, “TR” will be +the fallback font whenever you try to access a family that does not +exist. +
+.FALLBACK_FONT TR ABORT +
+mom will abort whenever you try to access a non-existent font, and +will use the fallback font “TR” whenever you try to +access a family that does not exist. +

+ +

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

+ +

+If you invoke PT_SIZE without an argument, it reverts to its former +value. For example, if your point size is 10 and you change it to +12 with .PT_SIZE 12, entering .PT_SIZE +(i.e. without an argument) resets the point size to 10. +

+ +

+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 + +or, more simply, just + + .PT_SIZE + +The size of type can also be changed inline. See +Inline Escapes, changing point size. +

+ +

+Note: It is unfortunate that the +pic preprocessor has already taken the name, +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 +
+(Please see +here +for information on using +AUTOLEAD during document +processing.) +

+ +

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

+ +

+Experts: Please note that the groff +primitives, +.vs and .ps, are unaffected by, and have no +effect, on AUTOLEAD. +

+ +

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

+ +

+ + + +

Justification and quadding/breaking and joining 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 and quadding/breaking and joining lines macros

Fill modes +
- JUSTIFY – set lines justified
- QUAD – set filled lines flush left, right or centred
Nofill modes +
- LEFT – set non-filled lines flush left
- RIGHT – set non-filled lines flush right
- CENTER – set non-filled lines centred
Breaking lines +
- BR – manually break an output line
- EL – break a line without advancing to the next output line
- SPACE – break a line and add space before the next output line
- SPREAD – break and force-justify an output line
Joining input lines in nofill mode +
- \c inline escape

+ + + +

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

+ +

+ +

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

+ +

+Suggestion: 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. +

+ +

+EL (“End Line”) +is conceptually equivalent to the notion of a carriage return with +no linefeed. Its 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”, +which is covered in the section +Vertical movements. +

+ + + +

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. 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 and advances +the specified vertical distance, as in +
+ + .SPACE 6p + +which breaks the line and advances six points further. +

+ +

+Tip: 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. Because SPACE aliases .sp, it may be used +with groff’s absolute position modifier +“|” (the pipe +character) to move to a specified vertical location on the page. +Consult + + info groff “Manipulating Spacing” + +or, more simply, + + info groff sp. + +

+ + + +

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 +spaces before \c. Without them, 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. 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. + +

+ +

+ + + + + +

+The macros in this section help you tweak groff’s behaviour, +ensuring that your documents look typographically professional. +

+ + + + + +

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 point size. 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 between 3 and 5 +produces a subtle but noticeable difference. In/decreasing by a +value greater than 6 is almost always apparent. You should preview +your work to assess the effect of WS. +

+ +

+WS takes as its argument a whole number preceded by a plus or minus +sign. Therefore, to decrease the word space slightly, you might +enter +
+ + .WS -2 + +To increase it by a noticeable amount, you might enter +
+ + .WS +6 + +You can reset the word spacing to its previous value by switching +the plus or minus sign, like this: +
+ + .WS +2 + A line of text + .WS -2 + +The .WS -2 undoes the effect of +.WS +2. 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 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). 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 plus 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 (zero) 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 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 +
+Macro: HY toggle +

+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 + +A subsequent call to HY restores hyphenation with the parameters for +LINES, MARGIN, or SPACE that were formerly in effect (see below). +

+ +

+HY observes the following default hyphenation rules: +

Last lines (i.e. ones that will spring a trap—typically + the last line on a page) will not be hyphenated. +
The first and last two characters of a word are never + split off. +

+ +

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 (i.e. the actual hyphen character) 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. +

+ +

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

+ +

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

+ +

+IMPORTANT: +RW (and its complement, EW, see below) only affects the current +font, and remains in effect for that font every time it’s +called, hence it must be reset to zero to cancel its effect +(.RW 0). +

+ + + +

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

+ +

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

+ +

+IMPORTANT: +EW (and its complement, RW, see above) only affects the current +font, and remains in effect for that font every time it’s +called, hence it must be reset to zero to cancel its effect +(.RW 0). +

+ + + +

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, END, +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 two +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 font styles)

+ +

+It sometimes happens that a +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 the condensed version. 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 macros

+ +

Pseudo italic +
- SETSLANT – degree of pseudo-italicizing
- \*[SLANT] – inline escape for pseudo-italicizing type
Pseudo bold +
- SETBOLDER – amount of emboldening
- \*[BOLDER] – inline escape for emboldening type
Pseudo condensed +
- CONDENSE – percentage for pseudo-condensed type
- \*[COND] – inline escape for pseudo-condensed type
Pseudo extended +
- EXTEND – percentage for pseudo-extended type
- \*[EXT] – inline escape for pseudo-extending
Smallcaps +
- SMALLCAPS – enable smallcaps
- SMALLCAPS_STYLE – size, weight, and width of smallcaps

+ + + +

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] +
+Inline: \*[SLANTX] +

+ +

+\*[SLANT] begins pseudo-italicizing. \*[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] +
+Inline: \*[BOLDERX] +

+ +

+\*[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 making any changes to the pseudo-condense percentage +with CONDENSE. +

+ + + +

Pseudo-condensing on/off

+ +

+Inline: \*[COND] +
+Inline: \*[CONDX] +

+ +

+\*[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 re-invoke +\*[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 making any changes to the pseudo-extend percentage +with EXTEND. +

+ + + +

Pseudo-extending on/off

+ +

+Inline: \*[EXT] +
+Inline: \*[EXTX] +

+ +

+\*[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 re-invoke +\*[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. +

+ + + +

Smallcaps

+ +

+Macro: SMALLCAPS <toggle> +

+ +

+To begin setting type in pseudo-smallcaps, simply invoke +.SMALLCAPS. When you no longer want them, invoke +SMALLCAPS OFF (or END, STOP, +DONE, etc). If you are currently in a +no-fill mode, +(i.e. +LEFT, +CENTER, +or +RIGHT) +and you want the smallcaps to continue on the same line, +append a \c to the line, like this +
+ + A line of type\c + .SMALLCAPS + with a few words in smallcaps. + .SMALLCAPS OFF + +The line preceding .SMALLCAPS OFF should also have a +\c appended to it if you wish it to continue unbroken. +

+ +

+Note: +SMALLCAPS does not have an inline equivalent to + +\*[UC] / \*[LC] +. +Furthermore, if you’re using the +document processing macros +with +PRINTSTYLE TYPEWRITE, +mom ignores SMALLCAPS. +

+ +

+Additionally, be aware that no automatic +kerning +takes place while pseudo-smallcaps are in effect. +

+ +

Set size, weight, and width of smallcaps

+ +

+Macro: SMALLCAPS_STYLE SIZE <percentage> WEIGHT_ADJ <percentage> EXTEND <percentage> +

+ +

+True smallcaps are not a font effect, but, like designer cuts of +bold, condensed, and extended, actual fonts provided with some +families. It is highly recommended that you acquire real smallcaps +fonts rather than relying on mom’s pseudo version. +

+ +

+To achieve a reasonable facsimile of designer-cut smallcaps fonts, +mom needs to know the percentage of regular caps at a given point +size by which to reduce the small caps. To make adjustments for +the difference in weight and width of the smaller caps, she also +needs to know by how much to embolden (“fatten”) the +smallcaps, and by how much to increase their width. +

+ +

+All three arguments to SMALLCAPS_STYLE reflect a +percentage of the point size in effect when +SMALLCAPS +is invoked. Mom’s defaults for pseudo-smallcaps are: +
+ + SIZE = 74% + WEIGHT_ADJ = .3% + EXTEND = 5% + +To change any or all of the defaults, you might enter +
+ + .SMALLCAPS_STYLE SIZE 80 WEIGHT_ADJ .25 EXTEND 3 + +or, more readably, +
+ + .SMALLCAPS_STYLE + SIZE 80 \ + WEIGHT_ADJ .25 \ + EXTEND 3 + +Note that you do not have to give SMALLCAPS_STYLE all three +arguments, and that the arguments may be entered in any order. Any +arguments you omit will remain at their former value. +

+ +

+ + + +

Vertical movements

+ +The two macros in this section allow you to move down or up on the +page relative to the current +baseline. + +

Vertical movements macros

ALD – Advance Lead
RLD – Reverse Lead
(see also SPACE)

+ + + +

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

+ +

+ALD causes a line break, which means the argument is added to the +current +leading. +For example, if your current leading is 12 points, a line of type +after .ALD 6p will be 18 points distant from the previous +line. +

+ +

+If you wish to advance the argument's distance from the +current baseline, it should be preceded by +EL. +For example, +
+ + .LEFT + .LS 12 + First line. + Second line.\c + .EL + .ALD 15p + Third line. + +would place the third line exactly 15 points beneath the second. +

+ +

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

+ +

+RLD causes a line break, which means the argument is subtracted from +the current +leading. +For example, if your current leading is 12 points, a line of type +after .RLD 6p will be 6 points distant from the previous +line. +

+ +

+If you wish to move upward from the current baseline by the +argument's distance, RLD should be preceded by +EL. +For example, +
+ + .LEFT + .LS 18 + First line. + Second line.\c + .EL + .RLD 3p + Third line. + +would raise the third line by 3 points relative to the baseline of +the second line. Put another way, if the .RLD in the +example were 18p, the third line would fall on the same baseline as +the second. +

+ +

+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 +Typesetting macros during document processing +for reassuring 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, +

to begin at the left margin of the page – i.e. no indent
to have a line length of 5 picas
to be set flush left

+ +

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

to begin 8 picas from the left margin
to have a length of 9 picas
to be set centered

+ +

to begin 19 picas from the left margin
to have a length of 17 picas
to be set flush left, filled

+ +

with .TAB (passing the tab + number as an argument), which breaks the current line, + advances one linespace and calls the tab.
with .TN (Tab Next), which keeps + you on the current line and moves over to the next + tab in sequence (i.e. from 1 to 2, 2 to 3, etc.), or, more + conveniently, with the + \*[TB+] + inline escape

+ +

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

+ +

Code:

+ +.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\*[TB+] +EVALUATION\*[TB+] +COMMENTS +.SP +.TAB 1 +Service\*[TB+] +Good\*[TB+] +Many clients specifically request support from Joe by name. +.SP +.TAB 1 +Punctuality\*[TB+] +Satisfactory\*[TB+] +Tends to arrive after 8:00am, but often works through lunch hour. +.SP +.TAB 1 +Team spirit\*[TB+] +Needs work\*[TB+] +Persistently gives higher priority to helping clients +than respecting organizational hierarchy. +.TQ + +

+ +

+Try setting this up and processing it with +
+ + pdfmom filename.mom > filename.pdf + +then previewing the .pdf file. 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 +

CRITERION is the longest line in tab 1
EVALUATION is the longest line in tab 2
tab 3 should extend to the current right margin
you want a 1 pica gutter between each tab

+ +

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

+ +

Code:

+ +

+ +.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 really. Here’s what it means when broken down +into its component parts: +

The longest line in tab 1 is “CRITERION”, so we + enclose CRITERION with begin/end markers for string tab 1: +
+ + \*[ST1]CRITERION\*[ST1X] + +
We want a 1 pica (12 points) gutter between tab 1 and 2, + so we insert 12 points of space with \*[FWD 12p]: +
+ + \*[FWD 12p] + +
The longest line in tab 2 is “EVALUATION”, so + we enclose EVALUATION with begin/end markers for string + tab 2: + + \*[ST2]EVALUATION\*[ST2X] + +
We want 1 pica (12 points) between tab 2 and 3, so we + insert it with: +
+ + \*[FWD 12p] + +
We want tab 3 to be as long as whatever space remains on + the current line length, so we enclose the + pad marker + (#) with begin/end markers for string tab 3: + + \*[ST3]#\*[ST3X] + +

+ +

+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 + +From here on in, you call the tabs with +.TAB, +.TN, +or +\*[TB+] +just like typesetting tabs (see +typesetting tabs tutorial). +

+ +

+Here’s the complete setup and entry for the sample employee +evaluation form utilizing string tabs. +

+ +

Code:

+ +.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\*[TB+] +EVALUATION\*[TB+] +COMMENTS +.SP +.TAB 1 +Service\*[TB+] +Good\*[TB+] +Many clients specifically request support from Joe by name. +.SP +.TAB 1 +Punctuality\*[TB+] +Satisfactory\*[TB+] +Tends to arrive after 8:00am, but often works through lunch hour. +.SP +.TAB 1 +Team spirit\*[TB+] +Needs work\*[TB+] +Persistently gives higher priority to helping clients +than respecting organizational hierarchy. +.TQ + +

+ +

+Try setting this up and processing it with +
+ + pdfmom filename.mom > filename.pdf + +and previewing the .pdf file. +

+ +

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

+ +

TAB_SET – create typesetting tabs
\*[ST]...\*[STX] – inline escapes for marking String Tabs
ST – set String Tabs
TAB – call tabs
TN – Tab Next; call next tab in sequence
\*[TB+] – inline escape to call next tab in sequence
TQ – Tab Quit

+ +

+ + + +

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 quad direction, hence TAB_SET has four required arguments: +

a tab number
an indent (measured from the left margin of the page, + or, if you’re already in a tab, from the left margin of the tab)
a length
a direction

+ +

+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) +or, more conveniently, the inline escape +\*[TB+]: +
+ + .TAB 1 + A line of text in tab 1.\*[TB+] + 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 +
Inline escape: \*[TB+] +

+ +

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

+ +

+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. Conversely, +if you did give a QUAD argument to TAB_SET or ST, the +\c must not be used. +

+ +

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

+ +

+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\c + .TN + Some more text\c + .TN + .TN + Yet more text + +The above example, assuming tabs numbered from 1 to 4, should be entered +
+ + .TAB 1 + Some text\c + .TN + Some more text\c + .TN + \&\c + .TN + Yet more text + + +\& is a zero-width, non-printing character that groff +recognizes as valid input, hence meets the requirement for input +text following .TN. +

+ + + +

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

+ +

+ + + +

Multiple 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 – +Multi-Column On), +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 – +Multi-Column eXit) +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. +

+ +

+Additional Note: +Do not use multi-columns with +DOCTYPE SLIDES +because MCX uses the lowest line on the page to determine column +depth. Owing to the fact that both headers and footers are printed +prior to slides receiving text, MCX will always go to the +footer position. If you need functionality similar to MCO/MCX, use +the groff requests .mk and .rt. See +info groff mk. +

+ +

Multi-columns macros

+ +

MCO – begin multi-column setting
MCR – return to top of column
MCX – exit multi-columns

+ + + +

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

+ +

How mom handles indents

+ +

+Mom provides five kinds of indents: left, right, both, temporary, +and hanging. Each is invoked by its own name: +

IL – Indent Left
IR – Indent Right
IB – Indent Both
HI – Hanging Indent
TI – Temporary Indent

+ +

+In addition, there are four macros to control exiting from +indents: +

IQ – quit all active indents
ILX – exit indent style left
IRX – exit indent style right
IBX – exit indent style both

+ +

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

IQ CLEAR – quit and clear all indents
ILX CLEAR – quit and clear indent style left
IRX CLEAR – quit and clear indent style right
IBX CLEAR – quit and clear indent style both

+ +

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

+ +

+Note: see the section +Typesetting macros during document processing +for information and advice on using indents with the +document processing macros. +

+ +

Indents macros

+ +

IL – Indent left
IR – Indent right
IB – Indent both
TI – Temporary indent, left
HI – Hanging Indent +
- Recipe: a numbered list using hanging indents
IQ – Quit indents, all
ILX – Exit indent style left
IRX – Exit indent style right
IBX – Exit indent style both

+ + + +

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 after an ILX indents by its last active value. See the +explanation of how mom handles indents +for more details. +

+ +

+Note: Calling a tab (with +.TAB <n>) +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 after an IRX indents by its last active value. See the +explanation of how mom handles indents +for more details. +

+ +

+Note: Calling a tab (with +.TAB <n>) +automatically cancels any active indents. +

+ +

+Additional note: Invoking IR +automatically turns off IB. +

+ + + +

Indent both

+ +

+Macro: IB [ <indent-1> <indent-2> ] +

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

+ +

+If you supply only an indent-1 argument, the argument is +the amount to indent from both the left and right margins. If you +give both indent-1 and indent-2, the first is +the indent from the left margin and the second is the indent from +the right margin. +

+ +

+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 after an IBX indents by its +last active values. See the +explanation of how mom handles indents +for more details. +

+ +

+Note: Calling a tab (with +.TAB <n>) +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. +

+ +

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

+ +

Recipe: A numbered list using hanging indents

+ +

+Note: mom has macros for setting lists (see +Nested lists). +This recipe exists to demonstrate the use of hanging indents only. +

+ +

+ + .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.' + .HI \w'\0\0.' + 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 don’t +require a measure to be given. +

+ +

+Paste the example above into a file and preview it with +
+ + pdfmom filename.mom > filename.pdf + +to see hanging indents in action. +

+ + + +

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: The original macro +for quitting all indents was IX. This usage has been 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. +

+ +

+ + + + + + + + +

Back to Table of Contents

Top

Next: Goodies

+ +

+ + + diff --git a/contrib/mom/momdoc/using.html b/contrib/mom/momdoc/using.html new file mode 100644 index 0000000..c93e385 --- /dev/null +++ b/contrib/mom/momdoc/using.html @@ -0,0 +1,319 @@ + + + + + + + + + Using mom + + + + + + + +

+ + + + + + + +

Back to Table of Contents

Next: The typesetting macros

+ +

Using mom

+ +

Introduction
How to input mom’s macros
Processing and viewing documents +
- Mom and PDF
- pdfmom
Automatic previewing of documents

+ +

Introduction

+ +

+As explained in the section +What is mom?, +mom can be used in two ways: for straightforward typesetting or for +document processing. The difference between the two is that in +straightforward typesetting, every macro is a literal instruction +that determines precisely how text following it will look. Document +processing, on the other hand, uses markup tags (e.g. .PP +for paragraphs, .HEADING for different levels of heads, +.FOOTNOTE for footnotes, etc.) that perform typesetting +operations automatically. +

+ +

+You tell mom that you want to use the document processing macros +with the +START +macro. After START, mom determines the appearance of +text following the markup tags automatically, although you, the +user, can easily change how the tags are interpreted. +

+ +

How to input mom’s macros

+ +

+Regardless of whether you’re preparing a term paper or making a +flyer for your lost dog, the following apply. +

+ +

+ 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. + Simply colourizing macros and inlines to half-intensity can be + enough to make text stand out clearly from formatting commands. + Mom herself comes with a complete set of syntax highlighting + rules for the vim editor. A number of freely available editors + come with groff syntax highlighting rules, which are sufficient + for mom files, though not as colourful or complete as the vim + rules that ship with mom. + +
+ Macros begin with a period (dot) at the left margin of your text + editor’s screen, and must be entered in upper case (capital) + letters. +
+ 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. +
+ Arguments to a macro must appear on the same line as the + macro. +
+ + If the argument list is very long, you may use the + backslash character (\) to break the line visually. + From groff’s point of view, the backslash and newline are + invisible. Thus, for example, + + .HEADING_STYLE 1 FAMILY Garamond FONT B SIZE +2 + + and + + .HEADING_STYLE 1 \ + FAMILY Garamond \ + FONT B \ + SIZE +2 + + + are exactly equivalent. +
+ Any argument (except a + string argument) + that is not a digit must be entered in upper case + (capital) letters. +
+ 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). +
+ Any argument that requires a + unit of measure + must have the unit appended directly to the argument, with no + intervening space (e.g. .5i). +
+ String arguments, + in the sense of this manual, must be surrounded by double-quotes + (e.g. "text"). Multiple + string arguments are separated from each other by spaces (with + each argument surrounded by double-quotes). +
+ + If a string argument becomes + uncomfortably long, you may break it into two or more lines + with the backslash character. + + .SUBTITLE "An In-Depth Consideration of the \ + Implications of Forty-Two as the Answer to Life, \ + The Universe, and Everything" + + +

+ +

+Tip: +It’s important that your documents be easy to read and +understand 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 comment line. In groff, that’s +done with \# (backslash-pound) or .\" +(period-backslash-doublequote) on a line by itself. Either +instructs groff to ignore the remainder of the line, which may or +may not contain text. Consider the following, which is a template +for starting the chapter of a book. +
+ + \# Reference/meta-data + .TITLE "My Pulitzer Novel" + .AUTHOR "Joe Blow" + .CHAPTER 1 + \# Template + .DOCTYPE CHAPTER + .PRINTSTYLE TYPESET + \# Type style + .FAM P + .PT_SIZE 10 + .LS 12 + \# + .START + +You may also, if you wish, add a comment to the end of a line with +\" (no period), like this: +
+ + .FAMILY P \" Maybe Garamond instead? + +

+ +

Processing and viewing documents

+ +

+The most basic command-line usage for processing a file formatted +with the mom macros is +
+ + groff -mom filename.mom > filename.ps + +which processes the .mom file and dumps the output into a +viewable/printable PostScript file. +

+ +

Mom and PDF

+ +

+Adobe’s Portable Document Format (PDF) has largely supplanted +PostScript, of which it is a subset, as the standard for typeset +documents. While printed versions of documents in either format +will be identical, PDF documents, when viewed at the screen, may +also contain clickable links and a number of other special features. +

+ +

+As of version 2.0, mom supports full PDF integration. The creation +and processing of mom files into PostScript documents remains +unchanged from 1.x, but the expected and recommended format of final +documents is now PDF. +

+ +

+The manual, +Producing PDFs with groff and mom, +explains and demonstrates the PDF-specific macros that are available +in mom, as well as the use of pdfmom, the +recommended way to process mom files. +

+ +

pdfmom

+ +

+Groff provides more than one way to generate PDF documents, +but when processing files formatted with the mom macros, +pdfmom is the recommended and most robust way to do +it: +
+ + pdfmom filename.mom > filename.pdf + +pdfmom is a wrapper around groff, and accepts all +groff’s command-line options as listed in the groff manpage. +Full usage is explained in the manual, +Producing PDFs with groff and mom. +

+ +

+PDF links in a document, including linked entries in the +Table of Contents, are identified by colour. When printing +documents with links, you will most likely not want the link +text coloured. The groff option, -c, disables colour +throughout a document; thus, when preparing a document for printing, +you should use: +
+ + pdfmom -c filename.mom > filename.pdf + +pdfmom tends to produce large files. You may +reduce their size by piping them through ps2pdf: +
+ + pdfmom -c filename.mom | ps2pdf - filename.pdf + +Be aware, though, that files piped through ps2pdf will lose some pdf +metadata, notably the document window title set with PDF_TITLE. +

+ +

Automatic previewing of documents

+ +

+Most PDF viewers have a “Watch File” option, which +automatically updates a displayed document whenever there’s +a change. This is useful when preparing documents that require +judgment calls. I recommend creating a keymapping in your +text editor that both saves the mom file and processes it with +pdfmom. The displayed PDF then automatically +reflects whatever changes you save to the mom file. +

+ +

+ + + + + + + + +

Back to Table of Contents

Top

Next: The typesetting macros

+ +

+ + + diff --git a/contrib/mom/momdoc/version-2.html b/contrib/mom/momdoc/version-2.html new file mode 100644 index 0000000..bd1cb8d --- /dev/null +++ b/contrib/mom/momdoc/version-2.html @@ -0,0 +1,424 @@ + + + + + + + + + Mom -- Version 2.0 notes + + + + + + + +

+ + + + + + + +

Back to Table of Contents

Next: Introduction to mom

+ +

Version 2.0 notes

+ +

Prefatory comments
Differences between 2.0 and 1.x +
- 2.1 PDF support +
  - 2.1.1 The manual, Producing PDFs with groff and mom
  - 2.1.2 PDF_IMAGE
- 2.2 Covers
- 2.3 Headings
- 2.4 Margin notes
- 2.5 Floats
- 2.5 Tables of contents
Version 2.1 changes
Version 2.2 changes
Version 2.5 changes
The pdfmom wrapper around groff
The install-font.sh script

+ +

1. Prefatory comments

+ +

+Version 2.0 comes about as a result of Deri James’ +contribution of gropdf to groff, +and his subsequent work integrating the device with +mom. +

+ +

+Whereas the 1.x releases were oriented toward PostScript output, +2.0 focuses on PDF output, a bias reflected throughout this +documentation. Users are strongly encouraged to process their files +with +pdfmom, +a wrapper around groff -Tpdf, in order to take +full advantage of all PDF has to offer. +

+ +

+While portions of mom have been rewritten, and new features +introduced, 2.0 is backwardly compatible with 1.x releases. Changes +are either transparent, or accompanied by notifications on stderr. +

+ +

+The implementation of nested heads has been completely rethought, +as has the manner of styling of them. There are no limits on +how deep the nesting can go. The 1.x macros HEAD, +SUBHEAD, and SUBSUBHEAD may still be used, but +must be re-designed with the new HEADING_STYLE macro +if their 1.x defaults are not desired. +

+ +

+In conjunction with the changes to nested heads, Table of Contents +generation has also been rethought. Greater flexibility in the +inclusion of toc entry numbering been added. Like nested heads, +there’s a new macro TOC_ENTRY_STYLE that permits +styling of each level in the toc hierarchy separately. The default +overall layout has also been significantly improved, achieving a +level of typographical elegance formerly lacking. Best of all, the +Table of Contents can now be repositioned to the correct spot at the +top of a document from within the mom source file. +

+ +

+When mom files are processed with pdfmom, a PDF +outline for the Contents panel of PDF viewers is automatically +generated. In addition, entries in the Table of Contents +are clickable links when a document is viewed at the screen. +pdfmom also permits setting a document’s +papersize within the source file without the corresponding need for +-P-p<papersize> on the command line. +

+ +

+Lastly, while not strictly part of mom, a bash script, +install-font.sh, has been posted at the +mom site. +The script significantly eases the installation of new +groff families and fonts, with conversion to .pfa +and .t42 being performed by fontforge. +

+ +

2. Differences between v2.0 and v1.x

+ +

2.1. PDF support

+ +

+PDF support has been added, with features including the automatic +generation of PDF outlines, embedding of images in PDF format (via +the +PDF_IMAGE +macro) and PDF linking (internal and external). +

+ +

2.1.1. Producing PDFs with groff and mom

+ +

+A manual in PDF format, +Producing PDFs with groff and mom, +has been added to the documentation. The file, +mom-pdf.pdf can be found in +
+ + /usr/local/share/doc/groff-<version>/pdf/ + +or +
+ + /usr/share/doc/groff-base/pdf/ + +or at +
+ + http://www.schaffter.ca/mom/momdoc/mom-pdf.pdf + +PDF usage, and all associated macros except +PDF_IMAGE, +are fully explained in the manual, which should be considered an +integral part of the present documentation. In addition, the mom +source file for the manual can be found in +
+ + /usr/local/share/doc/groff-<version>/examples/mom + +or +
+ + /usr/share/doc/groff-base/examples/mom/ + +and provides an excellent demonstration of mom usage. +

+ +

2.1.2. PDF_IMAGE

+ +

+A new macro for embedding PDF images has been added, +PDF_IMAGE. +

+ +

+PDF_IMAGE functions similarly to PSPIC and accepts the same +arguments. Differences in implementation are that PDF_IMAGE +requires the image dimensions (the bounding box) to be supplied. +Instructions for getting the bounding box are included in the +documentation entry for PDF_IMAGE. Two additional options, +SCALE and ADJUST, allow scaling of the image +and optical centering. +

+ +

2.2. Covers

+ +

+Arguments to +COVER +and +DOC_COVER +may now be given in any order. +

+ +

2.3. Headings

+ +

+The 1.x macros HEAD, SUBHEAD, SUBSUBHEAD, are now deprecated and +have been replaced by the single macro +HEADING <n>, +where <n> is the heading level. The deprecated +macros may still be used, and conform in style to their original +defaults; they are, however, wrappers around HEADING levels 1 +– 3. Both the wrappers and HEADING itself can take a +NAMED <id> argument, specifying a PDF link +destination. +

+ +

+Styling of headings is managed by the single macro HEADING_STYLE <n> where +<n> conforms to a heading level. The control +macros for HEAD, SUBHEAD and SUBSUBHEAD have been removed. Users +wishing to style the wrappers must use HEADING_STYLE. +

+ +

+PARAHEAD is no longer valid. Paragraph heads in 2.0 are created +by passing the PARAHEAD argument to HEADING. Mom +will abort with an informational message whenever she encounters +.PARAHEAD. +

+ +

2.4. Margin notes

+ +

+The macro for setting margin note parameters, +MN_INIT, +has been re-written such that each parameter now has the form +<PARAMETER> <value>. This differs +from 1.x where parameters were entered without a preceding +<PARAMETER> flag. Parameters may be entered in any +order. Any that are skipped are set to default values. Documents +created with 1.x will have to have their MN_INIT updated +accordingly. +

+ +

2.5. Floats

+ +

+A +FLOAT +macro has been added, which functions similarly to the ms +macros’ .KF/.KE, i.e., the contents of the float are +output immediately if there’s room on the page, otherwise +normal text processing continues and the contents are output at the +top of the next page. An ADJUST argument to FLOAT allows +for optical centering. +

+ +

2.6. Tables of contents

+ +

+The default look of the Table of Contents has been overhauled to +produce a more typographically pleasing result. All control macros +for TOC title and entry styles have been removed, replaced by +TOC_TITLE_STYLE +and +TOC_ENTRY_STYLE <n> +where <n> corresponds to a heading level. Both +macros permit setting any or all of the style parameters for TOC +titles (i.e. chapters or major sections/divisions of a collated +document) and TOC entries (nested heading levels) at once. +Documents created with 1.x that contain TOCs will need to have their +TOC style updated if the new defaults are unsatisfactory. +

+ +

+Two new TOC control macros have been added, +SPACE_TOC_ITEMS +and +AUTO_RELOCATE_TOC. +SPACE_TOC_ITEMS groups TOC entry levels and separates them with a +discrete amount of whitespace. This leads to improved legibility, +and is highly recommended even though it is not mom’s +default. AUTO_RELOCATE_TOC intelligently repositions the Table +of Contents to the top of a document when the mom source file is +processed with +pdfmom. +

+ +

3. Version 2.1 changes

Version 2.1 adds these features:

expansion of cover, docheader, page header, and heading + control macros to permit caps, smallcaps, color, and + underscoring
the ability to style every element appearing in docheaders and + automatically-generated cover/title pages separately
macros to place images on cover/title pages
a new macro COVERTEXT that allows adding text (e.g. an + Abstract) to automatically-generated cover/title pages or to + create cover/title pages entirely by hand
separate indent control macros for QUOTES and BLOCKQUOTES
pseudo-smallcaps, including a control macro to choose the + size, weight, and width of the small caps
new <element>_STYLE macros that allow setting + parameters for <element> with a single macro using + keyword/value pairs

+ +

+The following changes have been made: +

+ +

MISC_AUTOLEAD (including COVER_MISC_AUTOLEAD and + DOC_COVER_MISC_AUTOLEAD) has been replaced in favour of MISC_LEAD, + which takes an absolute leading value rather than one derived + from the point size.
COVER_UNDERLINE and DOC_COVER_UNDERLINE have been + removed in favour of COVER_DOCTYPE_UNDERLINE and + DOC_COVER_DOCTYPE_UNDERLINE.
DOCTYPE NAMED <string> no longer accepts a + color argument; setting the colour for + <string> is accomplished with DOCTYPE_COLOR + <color>. In addition, the string now has a + complete set of control macros.
Default underscoring of the DOCTYPE NAMED string has been + removed, both in the docheader and on cover/title pages.
No cover/title page data persists, however formatting for the + elements on them does.

+ +

4. Version 2.2 changes

+ +

+Version 2.2 adds these features: +

flex-spacing, an alternative to mom’s default shimming + policy; flex-spacing balances vertical whitespace on the page by + distributing any excess equally at sensible points so that running + text always fills the page to the bottom margin (see + + vertical whitespace management) +
improvements to auto-labelling, such that it is now possible + to link symbolically to auto-labelled preprocessor material and + PDF images (note that you must be running groff 1.22.4 or higher + for this feature) +

+ +

5. Version 2.5 changes

+ +

+Version 2.5 adds shaded backgrounds and frames that span pages +appropriately when necessary, and a macro to set page or slide +background colour. +

+ +

6. pdfmom

+ +

+Deri James has provided pdfmom, a wrapper around +groff that processes mom source files with all the PDF bells and +whistles. Its use is highly recommended. Usage is explained in the +manual, + + Producing PDFs with groff and mom +. +A significant convenience of pdfmom is that it can, with the +-Tps flag, be used to pass processing over to Keith +Marshall’s pdfroff. This is useful when +processing files that contain PostScript images embedded with +PSPIC. +pdfmom, without the flag, uses groff’s PDF device +(gropdf), which only recognizes PDF images that +have been embedded with +PDF_IMAGE. +

+ +

7. install-font.sh

+ +

+A bash script, install-font.sh, has been posted at the +mom site. +There’s nothing mom-specific about the script, and it is not +an official part of groff. +

+ +

+Installing groff fonts is a multi-step procedure, which, while not +difficult, can be a nuisance. install-font.sh takes +care of all the details, including converting fonts to formats +acceptable to grops and gropdf, +creating and installing the groff fonts in the appropriate +directories, updating the download files, and installing the +original fonts in a system-wide directory, if desired. +

+ +

+ + + + + + + + +

Back to Table of Contents

Top

Next: Introduction to mom

+ +

+ + + -- cgit v1.2.3