Appendices

Next: Reserved words

+ +

+ + + + diff --git a/contrib/mom/momdoc/color.html b/contrib/mom/momdoc/color.html new file mode 100644 index 00000000..45e74163 --- /dev/null +++ b/contrib/mom/momdoc/color.html @@ -0,0 +1,506 @@ + + + + + + + + Mom -- Colour + + + + + + + +

+ + + + + + + +

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. +Afterward, any time you want text to be coloured, you either colour +it with an +inline escape +that contains the colour name (e.g. \*[red] +or \*[blue]) or invoke the macro, +COLOR, +with the name of the colour you want. +

+ +

+For example, say you want to have the name “Jack” in the +sentence “All work and no play makes Jack a dull boy” +appear in yellow. You'd begin by telling mom about the colour, +yellow. There are two ways of doing this; see +NEWCOLOR +and +XCOLOR +for a full explanation of the difference between the two. +

+ +

+If you use XCOLOR, you'd enter this: +
+ + .XCOLOR yellow + +If you use NEWCOLOR, you might enter: +
+ + .NEWCOLOR yellow RGB #FFFF00 + +

+ +

+After “defining” (or “initializing”) the +colour “yellow”, you'd colourize the name, Jack, either +with an inline escape +
+ + All work and no play makes \*[yellow]Jack\*[black] a dull boy. + +or with the +COLOR +macro +
+ + All work and no play makes + .COLOR yellow + Jack + .COLOR black + a dull boy. + +Notice, in both examples, that a) you have to set the colour back +to black after “Jack”, and b) you don’t have to +define or intialize the colour, black. Mom predefines it for you. +

+ +

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

+ +

+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
\*[<colorname>] (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 +\*[<color name>]). +

+ +

+The first argument to NEWCOLOR is a name for your colour. It +can be anything you like—provided it’s just one word +long—and can be caps, lower case, or any combination of the +two. +

+ +

+The second argument, which is entirely optional, is the +“colour scheme” you want mom to use when mixing the +colour. Valid arguments are +
+ + RBG (3 components: red green blue) + CYM (3 components: cyan yellow magenta) + CMYK (4 components: cyan magenta yellow black) + GRAY (1 component) + +If you omit the second argument, mom assumes you +want RGB. +

+ +

+The final argument is the components of your colour. This can be +hexadecimal string starting with a pound sign (#) (for +colour values in the 0-255 range) or two pound signs (##) +(for colour values in the 0-65535 range), or it can be a series of +decimal digits, separated by spaces, one digit per component, with +the argument enclosed in double quotes. (If this is all gibberish +to you, see +Tips for newbies.) +

+ +

+Thus, to tell mom about a colour named “YELLOW”, you +could enter one of the following: +
+ + .NEWCOLOR YELLOW #FFFF00 \"or ##FFFFFFFF0000 or "1 1 0" + .NEWCOLOR YELLOW RGB #FFFF00 \"or ##FFFFFFFF0000 or "1 1 0" + .NEWCOLOR YELLOW CYM #00FF00 \"or ##0000FFFF0000 or "0 1 0" + .NEWCOLOR YELLOW CYMK #00FF0000 \"or ##0000FFFF00000000 or "1 1 0" + +After you've told mom about a colour, you can then get her to set +text in that colour either with the +inline escape, +\*[<colorname>], +or the macro, +COLOR. +(See the +example, +above.) +

+ +

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

+ +

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

+ +

+Tips for newbies: +Colour manipulation can be tremendously confusing if you don’t +have a background in graphic arts or computing. My advice, if color +intimidates you, is to stick to using mom’s default RGB colour +scheme, and to fire up a color chooser that gives you the RGB values +you want for the colour you select. Plug those values into the +components argument to NEWCOLOR, and you’ll get the colour +you want. Both the KDE and gnome desktops have colour selectors +that provide you with the shorter RGB hexadecimal string. If +you’re not running KDE or gnome, the X utility, xcolorsel, +provides you with a similar functionality, although it only provides +RGB values for 256 pre-defined colours. If you use xcolorsel, be +sure to click the button “Display format” and select +“8 bit truncated rgb”. +

+ +

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

+ + + +

Initializing a colour with XCOLOR

+ +

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

+ +

+<X colorname> must be all one word, all lower case. +
+(See +Finding X color names +for how to get a list of valid colour names.) +

+ +

+XCOLOR is similar to NEWCOLOR in that it tells mom to initialize a +colour, but it’s easier to use. All you have to do is pass +it, as an argument, the valid name of one of the 256 pre-defined +X colours. The name must be all one word, and, breaking with mom +policy, it must be entered in lower case. +

+ +

+For example, if you want to intialize the X colour, coral, all you +have to do is enter +
+ + .XCOLOR coral + +Afterwards +
+ + .COLOR coral + + +will colourize subsequent text coral until you instruct mom to +return to black, or some other pre-defined, initialized colour. +(The +inline escape +\*[coral] will equally colourize text coral after you've +initialized the colour with XCOLOR.) +

+ +

+The downside of XCOLOR is that you can’t create custom +colours. This restriction, however, is mitigated by the fact that +for many users, 256 colours is more than enough to play around with. +

+ +

+While some X colours have fanciful names (peachpuff, papayawhip, +thistle, snow), many are self-explanatory and self-descriptive +in ordinary colour terms. “blue” is pure (rgb) +blue, “green” is pure (rgb) green, and so on. +Furthermore, for many X colors, there exist four variants, each +representing increasingly darker shades of the same colour. +For example, “blue1” is a relatively bright blue; +“blue2”, “blue3” and “blue4” are +increasingly darker shades. For that reason, you may find XCOLOR is +a better choice than NEWCOLOR when it comes to initializing common +colors. +

+ +

+The whimsical nature of X colour names sometimes makes for names +that are long to type in, e.g. “mediumspringgreen”. The +optional second argument to XCOLOR allows you to come up with more +convenient name by which to reference the colour. For example, you +could enter +
+ + .XCOLOR mediumspringgreen mygreen + +or + + .XCOLOR mediumspringgreen MYGREEN + +so that whenever you want text mediumspringgreen-ed, you +can use either .COLOR mygreen (or +.COLOR MYGREEN) or the inline escape +\*[mygreen] (or \*[MYGREEN].) +

+ +

Finding X color names

+ +

+There are two ways of finding the names of the pre-defined X +colours. One is to consult the file, rgb.txt, included with all +X11 installations. The location of the file on a Debian GNU/Linux +distribution is typically /etc/X11/rgb.txt. Other distributions and +other X installations may have the file in another location. The +file lists the colour names, but doesn’t show you what the +colours actually look like. +

+ +

+A better way to get the colour names, as well as to see what the +colours look like, is to fire up a colour chooser (like xcolorsel) +that both lists the colour names and shows a swatch of the colour +as well. +

+ +

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

+ +

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

+ +

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

+ + + +

Invoking a color

+ +

+Macro: COLOR <colorname> +

+ +

+Inline: \*[<colorname>] +

+ +

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

+ +

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

+ +

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

+ +

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

+ +

+ + + + + + + + +

Next: Graphical objects

+ +

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

+ + + + + + + +

Next: Tables of contents

+ +

Creating cover pages

+ +

Introduction to cover pages +
Cover and document cover macros +
- COVER / DOC_COVER +
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: section cover pages (which I shall refer to simply as +cover pages) and document cover pages (”doc +covers”). +

+ +

+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

+ +

+You tell mom what you want to appear on cover pages through the +arguments you pass to +COVER +and/or +DOC_COVER. +Provided you have already given mom the appropriate reference macros +(e.g. +TITLE +or +AUTHOR), +she will output 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 COVER_ADVANCE / DOC_COVER_ADVANCE. +

+ +

+If you request copyright information (and have already given mom the +reference macro, +COPYRIGHT), +she sets it, by default, in a smaller +point size +in the bottom right hand corner of the cover or doc cover. 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 and cover pages

+ +

+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 with the +macros DOC_COVERS_COUNT_PAGES and/or COVERS_COUNT_PAGES. +

+ +

Designing your own cover pages

+ +

+Finally, if you want to design your own cover page(s), you can +always typeset them (using the +typesetting macros), +invoke +.NEWPAGE, +set up your document (see +Tutorial – Setting up a mom document), +and lastly invoke +.START. +The cover page, and any typesetting commands on it, will have no +effect on mom’s processing of the document after you invoke +.START. +

+ +

Cover and document cover macros

COVER and DOC_COVER +
- Required and optional arguments
Enabling/disabling automatic generation of cover pages +
- COVERS
- DOC_COVERS
Control macros for covers and doc covers

+ + + +

COVER and DOC_COVER

+ +

+Macro: COVER (see required and optional arguments, below) +

+ +

+Macro: DOC_COVER (see required and optional arguments, below) +

+ +

+ +

+Optional arguments: [ SUBTITLE AUTHOR DOCTYPE COPYRIGHT MISC BLANKPAGE ] +

+ +

+Note: +These macros should be placed in the +“style-sheet” section of your document setup (see +Tutorial – Setting up a mom document), +i.e. after PRINTSTYLE (and/or DOCTYPE and/or COPYSTYLE), but before START. +

+ +

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

+ +

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

+ +

The required argument

+ +

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

+ +

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

+ +

TITLE: + – means the argument you gave to TITLE +
DOCTITLE: + – means the argument you gave to DOCTITLE +
COVERTITLE: + – means the argument you gave to COVERTITLE + or + DOC_COVERTITLE +
CHAPTER, CHAPTER_TITLE, CHAPTER+TITLE: + – see below, How the CHAPTER argument and friends work +

+ +

How the CHAPTER argument and friends work

+ +

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

+ +

The optional arguments

+ +

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

+ +

+You may enter as many or as few as you would like to see on your +cover or doc cover. The only hitch is—pay attention, +class—they must be entered in the order given above. +For example, if you want TITLE, AUTHOR, +COPYRIGHT and MISC +
+ + .COVER TITLE AUTHOR COPYRIGHT MISC + + +is correct, while +
+ + .COVER TITLE AUTHOR MISC COPYRIGHT + + +is not. +

+ +

What the DOCTYPE argument means

+ +

+When you pass COVER or DOC_COVER +the argument, DOCTYPE, it refers to the argument you gave +to +DOCTYPE NAMED. +For example, if, in your +docstyle macros +you gave a +
+ + .DOCTYPE NAMED "Abstract" + +the argument, DOCTYPE, given to the COVER or DOC_COVER +macros, would mean that you wanted the word, Abstract, to appear on +the cover or doc cover underneath the title and/or author(s), just +as it would in the +docheader. +

+ +

What the BLANKPAGE argument means

+ +

+If the final argument to DOC_COVER or COVER is BLANKPAGE, +mom will insert a blank page after the doc cover or cover. This is +particularly useful if you intend to print your document two-sided, +since, in two-sided printing, 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. +

+ + + +

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 covers and doc covers

+ +

+The default typographic appearance of the items on a cover or doc +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 in the bottom right hand corner + of the page, 2 + point sizes + smaller than the size of + running text +
MISC lines are set in the bottom left hand + corner of the page, in the same family, font and point size + as the copyright line. +

+ +

+The defaults for the entirety of covers and doc covers, and all the +elements thereon, can be changed with control macros whose defaults +and arguments are identical to the corresponding control macros +governing docheaders. The only difference is the name by which you +invoke them. +

+ +

+A complete list of cover and doc cover control macros follows. +Please refer to +docheader control +in order to get the defaults and any special instructions for usage. +

+ +

Cover / doc cover control macros and defaults

+ +

+ + +COVER_ADVANCE DOC_COVER_ADVANCE -+ +COVER_FAMILY DOC_COVER_FAMILY | like +COVER_LEAD DOC_COVER_LEAD | DOCHEADER_<spec> +COVER_QUAD DOC_COVER_QUAD -+ + +COVER_TITLE_FAMILY DOC_COVER_TITLE_FAMILY -+ +COVER_TITLE_FONT DOC_COVER_TITLE_FONT | like +COVER_TITLE_COLOR DOC_COVER_TITLE_COLOR | TITLE_<spec> +COVER_TITLE_SIZE DOC_COVER_TITLE_SIZE -+ + +COVER_CHAPTER_TITLE_FAMILY DOC_COVER_CHAPTER_TITLE_FAMILY -+ +COVER_CHAPTER_TITLE_FONT DOC_COVER_CHAPTER_TITLE_FONT | like +COVER_CHAPTER_TITLE_COLOR DOC_COVER_CHAPTER_TITLE_COLOR | CHAPTER_TITLE_<spec> +COVER_CHAPTER_TITLE_SIZE DOC_COVER_CHAPTER_TITLE_SIZE -+ + +COVER_SUBTITLE_FAMILY DOC_COVER_SUBTITLE_FAMILY -+ +COVER_SUBTITLE_FONT DOC_COVER_SUBTITLE_FONT | like +COVER_SUBTITLE_COLOR DOC_COVER_SUBTITLE_COLOR | SUBTITLE_<spec> +COVER_SUBTITLE_SIZE DOC_COVER_AUTHOR_SIZE -+ + +COVER_ATTRIBUTE_COLOR DOC_COVER_ATTRIBUTE_COLOR - like ATTRIBUTE_COLOR + - the macro, ATTRIBUTE_STRING, controls the attribution string + for both docheaders and cover pages; cover pages have no + separate ATTRIBUTE_STRING macro + +COVER_AUTHOR_FAMILY DOC_COVER_AUTHOR_FAMILY -+ +COVER_AUTHOR_FONT DOC_COVER_AUTHOR_FONT | like +COVER_AUTHOR_COLOR DOC_COVER_AUTHOR_COLOR | AUTHOR_<spec> +COVER_AUTHOR_SIZE DOC_COVER_AUTHOR_SIZE -+ + +COVER_DOCTYPE_FAMILY DOC_COVER_DOCTYPE_FAMILY -+ +COVER_DOCTYPE_FONT DOC_COVER_DOCTYPE_FONT | like +COVER_DOCTYPE_COLOR DOC_COVER_DOCTYPE_COLOR | DOCTYPE_<spec> +COVER_DOCTYPE_SIZE DOC_COVER_DOCTYPE_SIZE -+ + +COVER_COPYRIGHT_FAMILY DOC_COVER_COPYRIGHT_FAMILY -+ +COVER_COPYRIGHT_FONT DOC_COVER_COPYRIGHT_FONT | +COVER_COPYRIGHT_COLOR DOC_COVER_COPYRIGHT_COLOR | like any of the above +COVER_COPYRIGHT_SIZE DOC_COVER_COPYRIGHT_SIZE | +COVER_COPYRIGHT_QUAD DOC_COVER_COPYRIGHT_QUAD -+ + - copyright quad sets both the position on the page and the quad + direction and can be either L (left) or R (right); default is right + +COVER_MISC_FAMILY DOC_COVER_MISC_FAMILY -+ +COVER_MISC_FONT DOC_COVER_MISC_FONT | +COVER_MISC_COLOR DOC_COVER_MISC_COLOR | like any of the above +COVER_MISC_SIZE DOC_COVER_MISC_SIZE | +COVER_MISC_QUAD DOC_COVER_MISC_QUAD -+ + - misc quad sets both the position on the page and the quad + direction and can be either L (left) or R (right); default is left + +COVER_UNDERLINE DOC_COVER_UNDERLINE - like DOCTYPE_UNDERLINE + - cover underline controls underlining of the argument given to + DOCTYPE NAMED "<name>" only + +COVER_COUNTS_PAGES DOC_COVER_COUNTS_PAGES + - whether to consider cover pages in the pagination scheme; the + default is to ignore them + - see Note + +

+ +

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

+ +

+ + + + + + + + +

Next: Tables of contents

+ +

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

+ + + + + + + +

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 + String Argument + Unit of measure + Zero-width character +

+ +

+ + + + + +

Mom terms
+ Blockquote + Control macro + Docheader + Epigraph + Footer + Head + Header + Linebreak + Paragraph head + Quote + Running text + Subhead + 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 + + + \% (backslash followed by a percent) + +

Drop cap

+ A large, usually upper-case letter that introduces the first + paragraph of a document or section thereof. The top of the + drop cap usually lines up with the top of the first line of the + paragraph, and typically “drops” several lines lower. + Text adjacent to the drop cap is indented to the right of the + letter until the bottom of the drop cap is reached, at which + point text reverts to the left margin. +

Em/en

+ An em is a relative measurement equal to the width of the + letter M at a given + point size + in a given + font. + Since most Ms are designed square, an em is usually (but + sometimes erroneously) considered to be the same size as the + current point size (i.e. if the point size of the type is 12, + one em equals 12 points). An en is equal to the width of a + letter N (historically 2/3 of an em, although groff treats an en + as 1/2 of an em). Typically, ems and ens are used to measure + indents, or to define the length of dashes (long hyphens). +

Family

+ The collective name by which a collection of + fonts + are known, e.g. Helvetica, Times Roman, Garamond. +

Figure space/Digit space

+ A + fixed width space + that has the width of one digit. Used for aligning numerals in, + say, columns or numbered lists. In groff, the figure space is + entered with + + + \0 (backslash followed by a zero) + +

Fixed width font

+ A family or font in which every character occupies exactly the + same amount of vertical space on the line. Courier is the + best-known, if not the most elegant, fixed-width font. +

Fixed width space

+ Equal to + word space, + but does not expand or contract when text is + justified. + In groff, fixed width space is entered with + + + \<space> (backslash followed by hitting the spacebar) + +

Font

+ The specific + weight + and + shape + of type within a + family, + e.g. light, medium, bold (which are weights), and roman, italic, + condensed (which are shapes). By default, groff knows of four + fonts within its default set of families: R (medium roman), I + (medium italic), B (bold roman) and BI (bold italic). + Mom considerably extends this very basic list. +

Force justify

+ Sometimes, in + justified + text, a line needs to be broken short of the right margin. + Force justifying means telling a typesetting program (like + groff) that you want the line broken early AND that you want the + line’s word spacing stretched to force the line flush with the + right margin. +

Gutter

+ The vertical whitespace separating columns of type. +

Justify/justification

+ Lines of type are justified when they’re flush at both the left + and right margins. Justification is the act of making both + margins flush. Some people use the terms "left justified" and + "right justified" to mean type where only the left (or right) + margins align. I don’t. See + quad. +

Kerning

+ Moving pairs of letters closer together to remove excess + whitespace between them. In the days before phototypesetting, + type was set from small, rectangular blocks of wood or metal, + each block having exactly one letter. Because the edge of + each block determined the edge of each letter, certain letter + combinations (TA, for example) didn’t fit together well and had + to be mortised by hand to bring them visually closer. Modern + typesetting systems usually take care of kerning automatically, + but they’re far from perfect. Professional typesetters still + devote a lot of time to fitting letters and punctuation together + properly. +

Kern Units

+ A relative distance equal to 1/36 of the current + point size. + Used between individual letters + for + kerning. + Different typesetting systems use different values (1/54 is + popular), and sometimes call kern units by a different name. +

Lead/leading

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

+ In case you’re interested... In previous centuries, + lines of type were separated by thin strips of—you guessed + it—lead. Lines of type that had no lead between them were said + to be “set solid.” Once you began separating them with + strips of lead, they were said to be “leaded”, and the + spacing was expressed in terms of the number of + points + of lead. For this reason, “leading” and “line + spacing” aren’t, historically speaking, synonymous. + If type was set 10 on 12, for example, the leading was 2 + points, not 12. Nowadays, however, the two terms are used + interchangeably to mean the distance from baseline to baseline. +

+ +

Leaders

+ Single characters used to fill lines, usually to their end. So + called because they “lead” the eye from one element + of the page to another. For example, in the following (brief) + Table of Contents, the periods (dots) are leaders. + + + Foreword............... 2 + Chapter 1.............. 5 + Chapter 2.............. 38 + Chapter 3.............. 60 + +

Ligature

+ Ligatures are letters joined together to form a single + character. The commonest are fi, fl, ff, ffi and ffl. Others + are ae and oe. Occasionally, one sees an st ligature, but this + is archaic and quite rare. +

Picas/Points

+ There are twelve points in a pica, and six picas in an inch + (hence 72 points to the inch). In the same way that gem-dealers + have always used their own system of measurement for weight + (carats), typographers have always used their own system of + measurement for type. +

Point Size

+ The nominal size of type, measured in + points + from the bottom of the longest + descender + to the top of the highest + ascender. + In reality, type is always fractionally smaller than its point + size. +

Quad

+ When only one margin of type is flush, lines of type are quadded + in the direction of the flush margin. Therefore, quad left + means the left margin is flush, the right isn’t. Quad right + means the right margin is flush, the left isn’t. Quad centre + means neither the left nor the right margin is flush; rather, + lines of type are quadded on both sides so that type appears + centred on the page. +

Rag

+ Describes a margin that isn’t flush. Rag right means the right + margin isn’t flush. Rag left means the left margin isn’t flush. + The expression "flush left/rag right" is sometimes used to + describe type that is + quadded + left. +

Shape

+ The degree of slant and/or the width of characters. + (Technically speaking, this is not a proper typesetting term; + however, it may help clarify some concepts presented in these + documents.) + +

+ Some typical shapes are: +

+ +

“Roman”, which has no slant, and has letterforms of + average width
“Italic”, which is slanted, and has letterforms + of average width
“Condensed”, which has no slant, but has + letterforms narrower than the average represented by Roman
“Condensed Italic”, which is slanted, with letterforms narrower + than average

+ +

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

+ +

Solid/set solid

+ When no + lead + is added between lines of type (i.e. the + point size + and linespacing are the same), the lines are said to be “set + solid.” +

Track kerning/Line kerning

+ Sometimes, it’s advantageous to increase or decrease the amount + of space between every letter in a line by an equal (usually + small) amount, in order to fit more (or fewer) characters on the + line. The correct term is letter spacing, but track kerning and + line kerning (and sometimes, just "kerning") have come to mean + the same thing. +

Unbreakable space

+ Equal to + word space, + however words separated by an unbreakable space will always be + kept together on the same line. Expands and contracts like word + space. Useful for proper names, which one should, whenever + possible, avoid splitting onto two lines. In groff, unbreakable + space is entered with + + + \~ (backslash followed by a tilde) + +

Weight

+ The thickness of the strokes of letterforms. Medium and Book + have average thicknesses and are the weights used for most + of the text in books, magazines, newspapers, etc. Light has + strokes slightly thinner than Medium or Book, but is still + acceptable for most text. Semibold, Bold, Heavy and Black all + have strokes of increasing thickness, making them suitable for + heads, subheads, headlines and the like. +

Word space

+ The amount of whitespace between words. When text is + justified, + word space expands or contracts to make the margins flush. +

x-height

+ The height of a lower case letter x in a given font at a given + point size. Generally used to mean the average height of the + bowl of lower case letters. +

+ +

Groff terms

+ +

Alias

+ A + macro + invoked by a name different from its “official” + name. For example, the official name of the macro to change + family + is FAMILY. Its alias is FAM. + Aliases may be created for any macro (via the + ALIAS + macro) provided the alias uses a name not already taken by the + mom macros or one of the groff + primitives. + For a complete list of words or names you must not use, see the + list of reserved words. +

Arguments

+ Parameters or information needed by a + macro + to do its job. For example, in the macro + + + .PT_SIZE 12 + + + 12 is the argument. In the macro + + + .QUAD LEFT + + + LEFT is the argument. Arguments are separated from + macros by spaces. Some macros require several arguments; each + is separated by a space. +

Comment Lines

+ Input lines + introduced with the comment character + + + \# (backslash followed by the pound sign) + + + When processing output, groff silently ignores everything on a + line that begins with the comment character. +

Control Lines

+ Instructions to groff that appear on a line by themselves, which + means that “control lines” are either + macros + or groff + primitives. + Control lines begin with a period or, occasionally, an apostrophe. +

Filled lines/fill mode

+ Automatic + justification + or + quadding. + In fill mode, the ends of lines as they appear in your text + editor are ignored. Instead, words from adjoining + input lines + are added one at a time to the output line until no more words + fit. Then, depending whether text is to be + justified + or + quadded + (left, right, or centre), and depending on whether automatic + hyphenation is turned on, groff attempts to hyphenate the last + word, or, barring that, spreads and breaks the line (when + justification is turned on) or breaks and quads the line (when + quadding is turned on). + +

+ Nofill mode (non-filled text) means that groff respects the ends + of lines 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 specifically designed.) +

Numeric argument

+ An + argument + that has the form of a digit. Numeric arguments can be built + out of arithmetic expressions using +, -, *, and / for plus, + minus, times, and divided-by respectively. If a numeric + argument requires a + unit of measure, + a unit of measure must be appended to every digit in + the argument. For example: + + + .ALD 1i-1v + + +

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

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: + + + \& (backslash followed by an ampersand) + + + Normally, groff interprets a period (or an apostrophe) at the + beginning of an input line as meaning that what follows is a + control line. + In fill modes, groff treats a space at the beginning of an input + line as meaning “start a new line and put a space at the + beginning of it.” If you want groff to interpret periods + and apostrophes at the beginning of input lines literally (i.e. + print them), or spaces at the beginning of input lines as just + garden variety word spaces, you must start the line with the + zero-width character. +

+ +

Mom terms

Blockquote: + Cited material other than + quotes. + Typically set at a smaller point size than paragraph text, + indented from the left and right margins. Blockquotes are + filled. +
Control macro: + Macros used in + document processing + to control/alter the appearance of document elements (e.g. + heads, quotes, footnotes, + headers, + etc.). +
Document header/docheader: + Document information (title, subtitle, author, etc) output at + the top of page one. +
Epigraph: + A short, usually cited passage that appears at the beginning of + a chapter, story, or other document. +
Footer/page footer: + Document information (frequently author and title) output in + the bottom margin of pages after page one. Not to be + confused with footnotes, which are considered part of + running text. +
Head: + A title that introduces a major section of a document. +
Header/page header: + Document information (frequently author and title) output in the + top margin of pages after page one. + +
+
+ Note: In terms of content and style, + headers and + footers + are the same; they differ only in their placement on the page. + In most places in this documentation, references to the content + or style of headers applies equally to footers. +
+
+ +
Linebreak/author linebreak: + A 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 title joined to the body of a paragraph; hierarchically one + level beneath + subheads. +
Quote: + A quote, to mom, is a line-for-line setting + of quoted material (e.g. poetry, song lyrics, or a snippet of + programming code). You don’t have to use + BR + with quotes. +
Running text: + In a document formatted with mom, running + text means text that forms the body of the document, including + elements such as heads and subheads. + Docheaders, + headers, + footers + and page numbers are not part of running text. +
Subhead: + A title used to introduce secondary sections of a document; + hierarchically one level beneath sections introduced by + heads. +
Toggle: + A macro or tag that, when invoked without an argument, begins + something or turns a feature on, and, when invoked with ANY + argument, ends something or turns a feature off. See + Example 3 + of the section + How to read macro arguments. +

+ +

+ + + + + + + + +

Next: Using mom

+ +

+ + + + diff --git a/contrib/mom/momdoc/docelement.html b/contrib/mom/momdoc/docelement.html new file mode 100644 index 00000000..7d99277c --- /dev/null +++ b/contrib/mom/momdoc/docelement.html @@ -0,0 +1,6162 @@ + + + + + + + + Mom -- Document processing, element tags + + + + + + + +

+ + + + + + + +

Next: Inserting images

+ +

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

+ +

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

+ +

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

+ +

+Mom has tasteful defaults for all the tags, hence you only use the +control macros when you want to change the way she does things. +This is usually done prior to +START, +but can, in fact, be done at any time in the course of a document. +Any change to a tag’s style affects all subsequent invocations +of the tag. +

+ +

Control macros – changing 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, +which sets everyTHING in Courier roman, 12/24 (i.e. 12-point type on +a linespace of 24 points). +

+ +

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

+ +

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 change +subheads to 1-1/2 points larger than the type in paragraphs, do +
+ + .SUBHEAD_SIZE +1.5 + +There’s no need for a +unit of measure +with the _SIZE control macros; points is assumed. +

+ +

Colour

+ +

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

+ +

Lead/linespacing

+ +

+Control macros that end in _AUTOLEAD take the same argument as +AUTOLEAD, +viz. a digit that represents the number of points to add to +the tag’s point size to arrive at its +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 margin 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. +

+ +

Underline style, rule weight

+ +

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

+ +

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

+ +

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

+ +

+ + + +

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 accomodate +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 +heads. +The latter is not especially recommended, but it does work. In all +other places where you want quotes or cited text, use +QUOTE +or +BLOCKQUOTE. +

+ +

EPIGRAPH control macros and defaults

+ +

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

+ +

Note on EPIGRAPH_INDENT

+ +

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

+ +

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

+ +

+Please 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 +heads +or +subheads. +The first paragraphs of blockquotes and block-style epigraphs are +also not indented. This behaviour can be changed with the control +macro +INDENT_FIRST_PARAS. +

+ +

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

+ +

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

+ +

+Tip: +The last thing you want while you’re writing and editing +drafts of a document (particularly stories and chapters) is a +text file cluttered up with .PP’s. The visual +interruption in the flow of text is a serious obstacle to creativity +and critiquing. +

+ +

+I use the tab key on my keyboard to indent paragraphs by four spaces +when I'm writing, producing a text file that looks pretty much like +what you see on a printed page. When it comes time to format and +print the file, I run it through a sed script that (amongst other +things) converts the intial four spaces into .PP (plus a +new line) and pipes the output to groff for processing and printing. +

+ +

+Another solution would be to insert a blank line between paragraphs +of your text files. The blank lines can then be sedded out at +print time, as above (.PP plus a newline), or, more +conveniently, you could use the .blm +primitive +(blank line macro) to tell groff (and mom) that blank lines should +be interpreted as PP’s. +
+ + .blm PP + +tells groff that blank lines are really the macro PP. +

+ + + +

PP

+ +

+Macro: PP +

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

+ +

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

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

+ +

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

+ +

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

+ +

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 +and +footnotes +remain at their default setting (medium roman) unless you change +them with the appropriate control macros. +

+ +

+Mom’s default paragraph font is medium roman. +

+ +

3. Paragraph colour

+ +

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

+ +

+Please note that unless you change the colour back to it’s +default (usually black) at the end of the paragraph, all subsequent +paragraphs will be set in the new colour, although most other +elements of your document will continue to be set in the default +colour (usually black). +

+ +

+For example, assuming you have defined the colour, blue, +
+ + .PP + .COLOR blue + <first paragraph> + .HEAD "Monty Python" + .SUBHEAD "The Origins of Spam" + .PP + <second paragraph> + +the first paragraph will be blue, the head and subhead will be in +the document’s default colour (usually black), and the second +paragraph will be in blue. +

+ +

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

+ +

+See the footnote to +PARAHEAD_COLOR. +

+ +

4. Leading

+ +

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

+ +

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

+ +

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

+ +

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

+ +

5. Justification/quad

+ +

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

+ +

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

+ +

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

+ +

+Mom’s default justification/quad-direction for paragraphs +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 head or subhead, nor the first +paragraphs of +epigraphs, +blockquotes +or +footnotes +that run to more than one paragraph. +

+ +

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

+ +

8. Spacing paragraphs

+ +

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

+ +

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

+ +

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

+ +

+ + + +

Main heads

+ +

Tag: HEAD
Head control macros and defaults

+ +

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

+ +

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

+ +

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

+ + + +

HEAD

+ +

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

+ +

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

+ +

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

+ +

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

+ +

+For example, if mom breaks +
+ + .HEAD "This is a very, very, very long head" + +into
+ + This is a very, very, very + long head + +you’ll see the misbehaving underscore and should change the +argument to HEAD to +
+ + .HEAD "This is a very, very very" "long head" + +

+ +

HEAD control macros and defaults

+ +

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

Family/font/size/colour/quad
Capitalizing heads
Pre-head space
Underscoring
Numbering
Reset head numbering
Vertical inline escapes inside heads

+ +

1. Family/font/size/colour/quad

+ +

+ +.HEAD_FAMILY default = prevailing document family; default is Times Roman +.HEAD_FONT default = bold +.HEAD_SIZE default = +1 (point) +.HEAD_COLOR default = black +.HEAD_QUAD default = CENTER + +

+ +

2. Capitalizing heads

+ +

+By default, mom sets heads in caps, regardless of the +string(s) +you give to +HEAD. +To change this behaviour, do +
+ + .HEAD_CAPS OFF + +HEAD_CAPS is a toggle macro, therefore you can use any argument you +like instead of OFF (END, QUIT, Q, X...). To turn +HEAD_CAPS back on, simply invoke it without an argument. +

+ +

3. Pre-head space

+ +

+By default, mom deposits 2 blank lines prior to every head. If +you’d prefer just a single blank line, do +
+ + .HEAD_SPACE OFF + +HEAD_SPACE is a toggle macro, therefore you can use any argument +you like instead of OFF (END, QUIT, Q, X...). +To restore the space before heads to 2 blank lines, invoke +.HEAD_SPACE without an argument. +

+ +

4. Underscoring

+ +

+By default, mom underlines heads. To change this behaviour, do +
+ + .HEAD_UNDERLINE OFF + +HEAD_UNDERLINE can be used as a toggle macro, therefore you can +use any argument you like instead of OFF (END, +QUIT, Q, X...) to turn it off, or invoke it by itself to +turn head underlining on. +

+ +

+In addition to toggling head underlining on or off, as of +version 1.5 of mom, you can use HEAD_UNDERLINE to set the weight +of the underline and its distance from the head, like this: +
+ + .HEAD_UNDERLINE <weight> [<gap>] + +The weight argument is in points, or fractions thereof, +and must not have the +unit of measure, +p, appended. Like +RULE_WEIGHT, +weights must be greater than 0 and less than 100. Mom’s +default for head underlines is 1/2 point. +

+ +

+The gap argument determines the distance from the +baseline of the head to the upper edge of the underline. It can +be given using any unit of measure, and must have the unit of +measure appended to the argument. Mom’s default gap for head +underlines is 2 points. +

+ +

+As an example, suppose you want your heads underlined with a +4-point rule separated from the head by 3 points. The way to +accomplish it is: +
+ + .HEAD_UNDERLINE 4 3p + +If you wanted the same thing, but were content with mom’s +default gap of 2 points, +
+ + .HEAD_UNDERLINE 4 + +would do the trick. +

+ +

+Note: +If you supply a weight to HEAD_UNDERLINE, and optionally a gap, you +also turn the underlining of heads on; if this is not what you want, +you must turn head underlining off manually afterwards. +

+ +

5. Numbering

+ +

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

+ +

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

+ +

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

+ +

+See also +Prefixing chapter numbers +if you’d like chapter numbers prepended to the head numbers. +

+ +

6. Reset head numbering

+ +

+Should you wish to reset the head number to “1”, +invoke + + .RESET_HEAD_NUMBER + +with no argument. If, for some reason, you want mom to use a head +number that is not the next in ascending order (i.e. the last head +number + 1), invoke .RESET_HEAD_NUMBER with the number +you want, e.g. +
+ + .RESET_HEAD_NUMBER 6 + +Your next head will be numbered “6” and subsequent heads will +be numbered in ascending order from “6”. +

+ +

7. Vertical inline escapes inside heads

+ +

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

+ +

+For example, +
+ + .HEAD "\*[DOWN 3p]Text of head" + +or + + .HEAD "\v'3p'Text of head" + +will lower the baseline of the head by three points. Note that +there’s no need to reverse the sense of the inline escape. +

+ +

+In the case of heads that run to more than one line, you must embed +the escape in the string for each line, like this: +
+ + .HEAD "\*[DOWN 3p]First line" "\[DOWN 3p]Next line" + +or + + .HEAD "\v'3p'First line" "\v'3p'Next line" + +

+ +

+ + + +

Subheads

+ +

Tag: SUBHEAD
Subhead control macros

+ +

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

+ +

+By default, subheads are flush left. In +PRINTSTYLE TYPESET, +they are set bold, slightly larger than paragraph text. In +PRINTSTYLE TYPEWRITE, +they are underlined. A single linespace precedes them in both +printstyles, and a tiny space adjustment raises them slightly +above text that comes afterwards for greater clarity in document +structuring. +

+ +

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

+ + + +

SUBHEAD

+ +

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

+ +

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

+ +

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

+ +

SUBHEAD control macros and defaults

+ +

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

+ +

Family/font/size/colour/quad
Numbering
Reset subhead numbering
Vertical inline escapes inside subheads

+ +

1. Family/font/size/quad

+ +

+ +.SUBHEAD_FAMILY default = prevailing document family; default is Times Roman +.SUBHEAD_FONT default = bold +.SUBHEAD_SIZE default = +.5 (point) +.SUBHEAD_COLOR default = black +.SUBHEAD_QUAD default = LEFT + +

+ +

2. Number subheads

+ +

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

+ +

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

+ +

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

+ +

+See also +Prefixing chapter numbers +if you’d like chapter numbers prepended to the subhead numbers. +

+ +

3. Reset subhead numbering

+ +

+Should you wish to reset the subhead number to “1”, +invoke + + .RESET_SUBHEAD_NUMBER + +with no argument. If, for some reason, you want mom to use a +subhead number that is not the next in ascending order (i.e. the +last subhead number + 1), invoke .RESET_SUBHEAD_NUMBER +with the number you want, e.g. +
+ + .RESET_SUBHEAD_NUMBER 4 + + +Your next subhead will be numbered “4” and subsequent +subheads will be numbered in ascending order from “4”. +

+ +

4. Vertical inline escapes inside subheads

+ +

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

+ +

+ + + +

Paragraph heads

+ +

Tag: PARAHEAD
Parahead control macros

+ +

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

+ +

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

+ +

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

+ +

+Tip: +If you really need a heading level below subhead (a sub-subhead) +that isn’t joined to the body of a paragraph, you can trick +PARAHEAD into giving you one by creating a paragraph that contains +only a parahead, like this: +
+ + .PP + .PARAHEAD "My Sub-Subhead" + .PP + <text> + +

+ + + +

PARAHEAD

+ +

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

+ +

+PARAHEAD must come after +PP +or it will not work. +

+ +

+The argument is the text of the parahead, surrounded by +double-quotes. Because paraheads are joined to the body of a +paragraph, they accept only one argument (see +HEAD +and +SUBHEAD). +

+ +

PARAHEAD control macros and defaults

+ +

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

+ +

Family/font/size/color
Indent
Horizontal space
Numbering
Reset parahead numbering

+ +

1. Family/font/size/colour

+ +

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

+ +

2. Indent

+ +

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

+ +

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

+ +

+Note: +Paragraph heads in “first paragraphs”, as defined in +Indenting initial paragraphs, +are not indented unless you turn +INDENT_FIRST_PARAS +on. +

+ +

3. Horizontal space

+ +

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

+ +

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

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

+ +

4. Numbering

+ +

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

+ +

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

+ +

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

+ +

+See also +Prefixing chapter numbers +if you’d like chapter numbers prepended to the paragraph head +numbers. +

+ +

5. Reset paragraph head numbering

+ +

+Should you wish to reset the parahead number to “1”, +invoke + + .RESET_PARAHEAD_NUMBER + +with no argument. If, for some reason, you want mom to use a +parahead number that is not the next in ascending order (i.e. the +last parahead number + 1), invoke .RESET_PARAHEAD_NUMBER +with the number you want, e.g. +
+ + .RESET_PARAHEAD_NUMBER 7 + +Your next parahead will be numbered “7” and subsequent +paraheads will be numbered in ascending order from “7”. +

+ + + +

Prefixing chapter numbers

+ +

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

+ +

+If you’ve requested numbering of heads, subheads and/or paragraph +heads (with +NUMBER_HEADS, +NUMBER_SUBHEADS +and/or +NUMBER_PARAHEADS) +and you’d like mom, in addition, to prefix +a chapter number to the numbering scheme, you can do so with +PREFIX_CHAPTER_NUMBER. +

+ +

+After you invoke .PREFIX_CHAPTER_NUMBER, mom will prepend +the current chapter number to all subsequent head elements (main +heads, subheads or paragraph heads) for which you have requested +numbering. Thus, assuming chapter number twelve (12): +
+ + 1. FIRST MAIN HEAD + ------------------ + + 1.1. First Subhead Under Main Head + +becomes +
+ + 12.1. FIRST MAIN HEAD + --------------------- + + 12.1.1. First Subhead Under Main Head + +

+ +

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

+ +

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

+ +

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

+ +

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

+ +

+ + + +

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, lowered 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 <color name> +

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

+ +

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

+ +

Further notes on quote spacing

+As of version 1.3 of mom, handling of the vertical whitespace around +quotes changed slightly from its original implementation. +

+ +

+In versions of mom prior to 1.3, it was not possible to alter the +leading +of quotes and blockquotes (which was the same as the document +leading), ensuring that the vertical whitespace remained consistent, +as described above. +

+ +

+As of version 1.3, it became possible to change the +leading of quotes and blockquotes with .QUOTE_AUTOLEAD and +BLOCKQUOTE_AUTOLEAD, with the following changes in +mom’s behaviour: +

+ +

+If your quote (or blockquote) leading differs from the document +leading, mom attempts to observe the same rules for vertical +whitespace outlined above; however, she will also insert a small, +flexible amount of extra whitespace around the quotes to make sure +the whitespace is equal, top and bottom. Since she does this +on a quote by quote basis, rather than by figuring out how much +extra whitespace is needed to adjust all quotes on a page, +the spacing around multiple quotes on the same page will differ +slightly, although each will be balanced between lines of normal +running text, +top and bottom. (The inability to scan an entire page and insert +equalized whitespace at marked places is a limitation of groff, +which, by and large, processes text on a line-per-line basis.) +

+ +

+If you don’t want the behaviour described above (i.e. you +don’t want mom shimming [possibly irregularly linespaced] +quotes or blockquotes), issue the macro +
+ + .NO_SHIM + +prior to invoking .QUOTE or .BLOCKQUOTE. +

+ +

+If you’ve disabled shimming of quotes and blockquotes with +.NO_SHIM and you want mom to return to her default +behaviour in this matter, invoke .NO_SHIM OFF (or +QUIT, END, X, etc). +

+ +

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

+ + + +

QUOTE

+ +

+Macro: QUOTE toggle +

+ +

+QUOTE is a toggle macro. To begin a section +of quoted text, invoke it with no argument, then type in your +quote. When you’re finished, invoke .QUOTE with any +argument (e.g. OFF, END, X, Q...) to turn it off. Example: +
+ + .QUOTE + Nymphomaniacal Jill + Used a dynamite stick for a thrill + They found her vagina + In North Carolina + And bits of her tits in Brazil. + .QUOTE END + +

+ +

QUOTE control macros and defaults

+ +

Family/font/size/leading/colour/indent
Spacing above and below quotes (typeset only)
Underlining quotes (typewrite only)
Manually break a footnoted quote that crosses pages/columns (deprecated)

+ +

1. Family/font/size/colour/indent

+ +

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

+ +

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

+ +

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

+ +

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

+ +

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

+ +

+Note: +QUOTE_INDENT also sets the indent for +blockquotes. +

+ +

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

+ +

4. Manually break a footnoted quote that crosses pages/columns (deprecated)

+ +

+As of version 1.1.9, the macro BREAK_QUOTE became obsolete +(or, at least, should have become obsolete.) It remains here for +backward compatibility with documents created prior to 1.1.9, and +just in case despite my efforts to make it obsolete you still +encounter the problem it’s supposed to fix. Should you find +yourself having to use BREAK_QUOTE while running mom +1.1.9 or higher, please notify me immediately. +

+ +

+Exceptionally, a quote or blockquote containing a footnote may +cross a page or column. When this happens, the footnote marker may +not be correct for its position relative to other footnotes on the +page, and the footnote itself may appear on the wrong page or at the +bottom of the wrong column. When this happens, study your output to +determine the precise point at which the quote breaks (or at which +you want it to break), and add + + .BREAK_QUOTE + +on a line by itself afterwards. No other intervention is required, +and the footnote(s) will be marked correctly and appear on the +correct page. +

+ +

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

+ +

+ + + +

Blockquotes (cited material)

+ +

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

+ + + +

BLOCKQUOTE

+ +

+Macro: BLOCKQUOTE toggle +

+ +

+Aliases: CITE, CITATION +

+ +

+BLOCKQUOTE is a toggle macro. To begin a cited passage, invoke +the tag with no argument, then type in your 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. +

+ +

+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)
Manually break a footnoted blockquote that crosses pages/columns

+ +

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

+ +

+ +.BLOCKQUOTE_FAMILY default = prevailing document family; default is Times Roman +.BLOCKQUOTE_FONT default = roman +.BLOCKQUOTE_SIZE default = -1 (point) +.BLOCKQUOTE_AUTOLEAD default = none; leading of blockquotes is the same as paragraphs +.BLOCKQUOTE_COLOR default = black +.BLOCKQUOTE_QUAD default = left +.BLOCKQUOTE_INDENT (see below) + +

+ +

Blockquote indent

+ +

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

+ +

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

+ +

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

+ +

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

+ +

+Additional note: +BLOCKQUOTE_INDENT also sets the indent for +QUOTES. +

+ +

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

+ +

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

+ +

+ + + +

Inserting code snippets

+ +

Tag: CODE
CODE control macros and defaults

+ +

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

+ +

CODE

+ +

+Macro: CODE [BR | BREAK | SPREAD] toggle +

+ +

+Inline escape: \*[CODE] +

+ +

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

+ +

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

+ +

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

+ +

+Important: +.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 immeidately 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' + .CODE OFF + .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. +

+ +

+Note: +BR, BREAK and SPREAD have no +effect when used with the inline escape, \*[CODE]. The +assumption behind \*[CODE] is that you’re inserting +a bit of code into a line, not creating a distinct code block. +

+ +

CODE control macros and defaults

+ +

Family/Font/Color
Size

+ +

1. Family/font/colour

+ +

+ +.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 pre-pended +plus (+) or minus (-) sign, nor an appended +percent sign (%). Thus, is 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 miniscule 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 organizing. I can’t + seem to get everything done I want. + o an hour’s worth of exercise + o time to prepare at least one healthy + meal per day + o reading time + o work on mom + o writing + - changes from publisher + - current novel + o a couple of hours at the piano + +In other words, mom does not, by default, indent entire lists. +Indenting a list is controlled by the macro, +SHIFT_LIST. +(This is a design decision; there are too many instances where a +default indent is not desirable.) Equally, mom does not add any +extra space above or below lists. +

+ +

+Lists can be nested (as in the example above). In other words, +you can set lists within lists, each with an enumerator (and +possibly, indent) of your choosing. In nested lists, each +invocation of .LIST OFF (you may prefer to use +.LIST BACK) takes you back to the previous depth +(or level) of list, with that list’s enumerator and indent +intact. The final .LIST OFF exits lists completely +and returns you to the left margin of running text. +

+ +

+Finally, lists can be used in documents created with either the +document processing macros +or 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-numeralled LIST is going to have. Mom requires this +information in order to align roman numerals sensibly, and will +abort—with a message — if you don’t provide it. +

+ +

+A roman-numeralled list containing, say, five items, would be set +up like this: +
+ + .LIST roman5 producing i) Item 1. + .ITEM ii) Item 2. + Item 1. iii) Item 3. + .ITEM iv) Item 4. + Item 2. v) Item 5. + .ITEM + Item 3 + .ITEM + Item 4 + .ITEM + Item 5 + +

+ +

+The argument, USER, lets you make up your own enumerator, +and must be followed by a second argument: what you’d like the +enumerator to look like. +

+ +

+For example, if you want a list enumerated +with =>, +
+ + .LIST USER => + .ITEM + A list item + + +will produce +
+ + => A list item + +

+ +

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

+ +

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

+ +

+In document processing, it is valid to have list items that contain +multiple paragraphs. Simply issue a +.PP +request for each paragraph following the first item. +I.e., don’t do this: +
+ + .ITEM + .PP + Some text... + .PP + A second paragraph of text + +but rather +
+ + .ITEM + Some text... + .PP + A second paragraph of text + +

+ +

LIST control macros and defaults

+ +

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

+ +

2. Resetting an initialized list’s enumerator – RESET_LIST

+ +

+In nested lists, if your choice of list enumerator for a given level +of list is DIGIT, ALPHA, alpha, +ROMAN or roman, you may sometimes want to +reset the list’s enumerator when you return to that list. +Consider the following: +
+ + Things to do religiously each and every day: + 1. Take care of the dog + a) walk every day + b) brush once a week + - trim around the eyes every fourth brushing + - don’t forget to check nails + 2. Feed the cat + a) soft food on Mon., Wed. and Fri. + b) dry food on Tues., Thurs. and Sat. + c) canned tuna on Sunday + +

+ +

+Normally, within a nested list, when you return to an +incrementally-enumerated list, the enumerator continues incrementing +from where it left off. That means, in the example above, the +normal state of affairs for the alpha'ed list under +
+ + 2. Feed the cat + +would be d), e) and f). The solution, in such a case, is simply +to reset the enumerator—before .ITEM—with +the macro, .RESET_LIST. By default, with no argument, +.RESET_LIST resets the enumerator to 1, A, a, I or i +depending on the style of enumerator. You may, if you wish, pass +.RESET_LIST a +numeric argument +representing the starting enumerator for the reset (if different +from "1"), although I can’t at present think of a use for this +feature. +

+ +

3. Padding digit enumerators – PAD_LIST_DIGITS

+ +

Arabic digits

+ +

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

+ +

+If you want the extra space to the right, invoke the macro, +.PAD_LIST_DIGITS (with no argument), after +.LIST and before .ITEM. This will produce +something like +
+ + 8. List item + 9. List item + 10. List item + +If you want the extra space to the left, invoke +.PAD_LIST_DIGITS with the single argument, +LEFT, which will produce +
+ + 8. List item + 9. List item + 10. List item + +

+ +

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

+ +

Roman numerals

+ +

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

+ +

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

+ +

+ + + +

Line numbering – 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, heads, subheads, 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 +
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. +

+ +

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

+ + + +

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

+ +

+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 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
Line numbering control for quotes and blockquotes +

+ +

1. Family/font/size/colour

+ +

+ +.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. Line numbering control macros for QUOTE and BLOCKQUOTE

+ +

Number QUOTE lines

+ +

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

+ +

+There is a catch with numbering quotes, though. Owing to groff’s +restriction on accepting only the figure space as the line number +gutter’s unit of measure, it is not possible for line numbers +in quotes to hang outside a document’s overall left margin and +be reliably flush with the line numbers of paragraph text. +Conseqently, line numbers in quotes hang to the left of the quote, +separated from the quote by the <gutter> argument. +

+ +

+If you’d like to change the gutter for quotes line-numbered in +this way, invoke .NUMBER_QUOTE_LINES with a digit +representing the number of +figure spaces +you’d like between the line numbers and the quoted text, like this: +
+ + .NUMBER_QUOTE_LINES 1 + +With the above, line numbers in quotes (and only quotes) will have +a gutter of 1 figure space. +

+ +

+If you’re using "line numbering style" for footnotes +(FOOTNOTE_MARKER_STYLE LINE), +you may not wish to have quotes visibly line-numbered, but +still want to embed footnotes inside quotes. In order to do that, +mom allows you to say + + .NUMBER_QUOTE_LINES SILENT + +When you invoke .NUMBER_QUOTE_LINES SILENT, +mom continues to increment line numbers while quotes are being +output, but they won’t appear in the output copy. (Compare +this with mom’s default behaviour of suspending +incrementing of line numbers during the output of quotes.) This +allows you to embed line-numbered footnotes inside quotes and have +the line number label in the footnote come out sensibly. +

+ +

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

+ +

Number BLOCKQUOTE lines

+ +

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

+ +

+There is a catch with numbering blockquotes, though. Owing to +groff’s restriction of accepting only the figure space as the +line number gutter’s unit of measure, it is not possible for line +numbers in blockquotes to hang outside a document’s overall left +margin and be reliably flush with the line numbers of paragraph +text. Conseqently, line numbers in blockquotes hang to the +left of the blockquote, separated from the blockquote by the +<gutter> argument. +

+ +

+If you’d like to change the gutter for blockquotes line-numbered in +this way, invoke + + .NUMBER_BLOCKQUOTE_LINES + +with a digit representing the number of +figure spaces +you’d like between the line numbers and the blockquoted text, like +this: +
+ + .NUMBER_BLOCKQUOTE_LINES 1 + + +With the above, line numbers in blockquotes (and only blockquotes) +will have a gutter of 1 figure space. +

+ +

+If you are using "line numbering style" for footnotes +(FOOTNOTE_MARKER_STYLE LINE), +you may not wish to have blockquotes visibly line-numbered, +but still want to embed footnotes inside blockquotes. In order to +do that, mom allows you to say + + .NUMBER_BLOCKQUOTE_LINES SILENT + +When you invoke .NUMBER_BLOCKQUOTE_LINES SILENT, +mom continues to increment line numbers while blockquotes are being +output, but they won’t appear in the output copy. (Compare +this with mom’s default behaviour of suspending +incrementing of line numbers during the output of blockquotes.) +This allows you to embed line-numbered footnotes inside blockquotes +and have the line number label in the footnote come out sensibly. +

+ +

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

+ +

3. Numbering QUOTE and BLOCKQUOTE lines on a case by case basis

+ +

+Sometimes, you may want quotes or blockquotes to have a different +line numbering scheme from the one used in the rest of the document. +Or, you may want line numbering enabled only inside a particular +quote or blockquote. A common reason for this would be if you were +using the +QUOTE +macro to insert lines of programming code into a document. +

+ +

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

+ +

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

+ +

+ + + +

Footnotes

+ +

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

+ +

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

+ +

Footnote behaviour

+ +

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

+ +

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

+ +

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

+ +

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

+ +

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

+ +

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

+ +

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

+ +

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

+ +

+While mom’s handling of footnotes is sophisticated, +and tries to take nearly every imaginable situation under which they +might occur into account, some situations are simply impossible from +a typographic standpoint. For example, if you have a +HEAD +near the bottom of 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. +

+ +

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

+ +

Footnote markers and punctuation in the running text

+ +

“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 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 theOFF (or QUIT, END, X, etc.) +argument to instruct mom not to join the next input line to the +previous output. See +here +for a more complete explanation, with examples. +

+ +

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

+ +

FOOTNOTE control macros macros and defaults

+ +

Family/font/size/colour/lead/quad
Footnote markers – on or off
Footnote marker style – star+dagger or numbered
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

+ +

+ +.FOOTNOTE_FAMILY default = prevailing document family; default is Times Roman +.FOOTNOTE_FONT default = roman +.FOOTNOTE_SIZE default = -2 (points) +.FOOTNOTE_COLOR default = black +.FOOTNOTE_AUTOLEAD default = 2 points (typeset); single-spaced (typewrite) +.FOOTNOTE_QUAD default = same as paragraphs + +

+ +

2. Footnote markers – FOOTNOTE_MARKERS

+ +

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

+ +

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

+ +

3. Footnote marker style – FOOTNOTE_MARKER_STYLE

+ +

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

+ +

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

+ +

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

+ +

4. Footnotes by line number

+ +

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

+ +

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

+ +

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

+ +

Footnote line number brackets

+ +

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

+ +

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

+ +

RUN-ON FOOTNOTES

+ +

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

+ +

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

+ +

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_SPACE

+ +

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

+ +

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

+ +

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 +
- A note on endnotes spacing
- 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 (which marks 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, + 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. +

+ +

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, double-underscored head, “ENDNOTES”. +Underneath—flush left, bold, and underscored—she prints +the document title (or, in the case of chapters, the chapter +number or title). She then prints the endnotes. Each endnote is +identified by its appropriate number, in bold, right aligned to two +placeholders. The text of the endnotes themselves is indented to +the right of the numbers. +

+ +

+If the endnotes are grouped together at the end of a collated +document, each section of the document that contains endnotes is +identified by its own unique title (or chapter number or title), +bold, flush left, and underscored. +

+ +

+Of course, all the defaults, as well as the overall style of the +endnotes page, can be changed with the +endnote control macros. +The attentive will notice that endnotes have an awful lot of control +macros. This is because endnotes are like a mini-document unto +themselves, and therefore need not be bound by the style parameters +of the body of the document. +

+ +

A note on endnotes spacing

+ +

+On the endnotes page(s), each new endnote is separated from the +previous endnote by a full line space. This can result in a bottom +margin that hangs, and is the one instance, other than the use of +PARA_SPACE, +where mom allows unequal bottom alignment of pages. Should you wish +to correct this, by adding or subtracting small amounts of space +between endnotes that appear together on an endnotes page, make the +adjustment (with +ALD, +RLD +or +SPACE) +at the end of each endnote (i.e. just before invoking +.ENDNOTE OFF) +rather than at the top. +

+ +

Endnotes and columnar documents

+ +

+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 (mom’s default), the final word on the +input line +that comes immediately before .ENDNOTE MUST terminate +with a +\c +inline escape. See the +endnote example +above. +

+ +

+Additionally, in +fill +modes +(JUSTIFY +or +QUAD, +the line after .ENDNOTE OFF should be +entered as if there were no interruption in the input text, i.e. +the line should begin with a literal space or punctuation mark (see +explanation and examples for footnotes, which apply equally to +endnotes, +here). +

+ +

+In +no-fill +modes, the optional argument BREAK or BR may +be used after the OFF (or QUIT, END, X, etc.) +argument to instruct mom not to join the next input line to the +previous output. See +here +for a more complete explanation. The examples are for +.FOOTNOTE, but apply equally to .ENDNOTE. +

+ +

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

+ + + +

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' first-page title control +
Endnotes document-identification string control +
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

+ +

+ +.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 14 points, adjusted. +

+ +

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

+ + + +

• Singlespace endnotes (TYPEWRITE only)

+ +

+Macro: SINGLESPACE_ENDNOTES <toggle> +

+ +

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

+ +

+If, for some reason, you’d prefer that endnotes be +single-spaced in an otherwise double-spaced document (including +double-spaced +collated +documents), invoke +
+ + .SINGLESPACE_ENDNOTES + +with no argument. And if, god help you, you want to change endnote +single-spacing back to double-spacing for different spacing of +endnotes output at the ends of separate documents in a collated +document, invoke .SINGLESPACE_ENDNOTES with any argument +(OFF, QUIT, Q, X...). +

+ + + +

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

+ + + +

• Paragraph spacing

+ +

+Macro: ENDNOTE_PARA_SPACE <toggle> +

+ +

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

+ +

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

+ +

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

+ + + +

• Turning off column mode during endnotes output

+ +

+Macro: ENDNOTES_NO_COLUMNS <toggle> +

+ +

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

+ +

+If you output endnotes at the end of each document in a +collated +document set in columns, column mode will automatically be +reinstated for each document, even with ENDNOTES_NO_COLUMNS turned +on. In such circumstances, you must re-enable 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, Q, X...). +

+ +

• Allow headers on endnotes pages

+ +

+Macro: ENDNOTES_ALLOWS_HEADERS <none> | ALL +

+ +

+By default, if HEADERS are on, mom prints page headers on all +endnotes pages except the first. If you don’t want her to +print headers on endnotes pages, do +
+ + .ENDNOTES_ALLOWS_HEADERS OFF + +If you want headers on every page including the first, do +
+ + .ENDNOTES_ALLOWS_HEADERS ALL + +

+ +

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

+ +

4. Endnotes' first-page title control

+ + + +

• Title string

+ +

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

+ +

+By default, mom prints the word “ENDNOTES” as a head +at the top of the first page of endnotes. If you want her to +print something else, invoke .ENDNOTE_STRING with the +endnotes-page head you want, surrounded by double-quotes. If you +don’t want a head at the top of the first endnotes-page, +invoke .ENDNOTE_STRING with a blank argument (either two +double-quotes side by side—""—or no +argument at all). +

+ + + +

• Title control macros and defaults

+ +

+ +.ENDNOTE_STRING_FAMILY default = prevailing document family; default is Times Roman +.ENDNOTE_STRING_FONT default = bold +.ENDNOTE_STRING_SIZE* default = +1 +.ENDNOTE_STRING_QUAD default = centred + +*Relative to the size of the endnotes text (set with ENDNOTE_PT_SIZE) + +

+ + + +

• Title string placement

+ +

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

+ +

+• Argument requires a unit of measusure +

+ +

+By default, mom places the title (the docheader, as it were) of +endnotes pages (typically "ENDNOTES") on the same +baseline +that is used for the start of +running text. +If you’d prefer another location, higher or lower on the page +(thereby also raising or lowering the starting position of the +endnotes themselves), invoke .ENDNOTE_STRING_ADVANCE with +an argument stating the distance from the top edge of the page at +which you’d like the title placed. +

+ +

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

+ + + +

• Title string underscoring

+ +

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

+ +

+Alias: 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, .ENDNOTE_STRING_UNDERSCORE +will place a single rule underneath the endnotes page title. Invoked +with the argument, DOUBLE, ENDNOTE_STRING_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 ENDNOTE_STRING_UNDERSCORE to control the +weight of the underscore rule(s), the gap between the title and the +underscore, and, in the case of double-underscores, the distance +between the two rules. +

+ +

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

+ +

+Mom’s default is to double-underscore the title with 1/2-point +rules placed 2 points apart and 2 points below the baseline of the +title. +

+ + + +

• Title string capitalization

+ +

+Macro: ENDNOTE_STRING_CAPS toggle +

+ +

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

+ +

+Mom’s default is to capitalize the endnotes pages 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

+ +

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

+ + + +

• Endnotes document-identification underscoring

+ +

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

+ +

+Alias: ENDNOTE_TITLE_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, .ENDNOTE_TITLE_UNDERSCORE +will place a single rule underneath the document identification +string. Invoked with the argument DOUBLE, +ENDNOTE_TITLE_UNDERSCORE will double-underscore the string. Invoked +with any other non-numeric argument, (e.g. OFF, NO, X, +etc.) the macro disables underscoring of the string. +

+ +

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

+ +

+Some examples: +
+ + .ENDNOTE_TITLE_UNDERSCORE 1 + - turn underscoring on; set the rule weight to 1 point + + .ENDNOTE_TITLE_UNDERSCORE 1 3p + - turn underscoring on; set the rule weight to 1 point; set + the gap between the string and the underscore to 3 points + + .ENDNOTE_TITLE_UNDERSCORE DOUBLE .75 3p + - turn double-underscoring on; set the rule weight to 3 points + + .ENDNOTE_TITLE_UNDERSCORE DOUBLE 1.5 1.5p 1.5p + - turn double-underscoring on; set the rule weight to 1-1/2 + points; set the gap between the string and the upper + underscore to 1-1/2 points; set the gap between the upper + and the lower underscore to 1-1/2 points + +

+ +

+Note, from the above, that in all instances, underscoring (single or +double) is enabled whenever ENDNOTE_TITLE_UNDERSCORE is used in this +way. +

+ +

+Mom’s default is to single-underscore the string with a +1/2-point rule placed 2 points below its baseline. +

+ + + +

6. Endnotes referencing style

+ +

• Endnote marker style

+ +

+Macro: ENDNOTE_MARKER_STYLE LINE | NUMBER +

+ +

+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, without terminating the text line before +it with \c, at the appropriate place in running +text. +

+ +

+(Should you wish to revert to mom’s default behaviour of +placing a superscript number in the text to identify an endnote, +you can invoke .ENDNOTE_MARKER_STYLE with the argument, +NUMBER. It is not advisable to switch marker styles +within a single document, for aesthetic reasons, but there is +nothing to prevent you from doing so.) +

+ +

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

+ +

• Spacing between line-numbered endnotes and the endnote text

+ +

+Macro: ENDNOTE_LINENUMBER_GAP <size of gap> +

+ +

+• Requires a unit of measure +

+ +

+Given the impossibility of knowing, in advance, the string length +of all the line numbers or ranges of line numbers that will be used +in endnotes (the string length of “12” is two; the string length of +“12-15” is 5), mom cannot “hang” line +numbers and guarantee that they, and the endnote text, will align in +a visually pleasing manner. Consequently, mom sets the entirety of +line-numbered endnotes completely flush left, including the line +numbers themselves. The line numbers (by default, enclosed in +square brackets) are separated from the beginning of each endnote +by a gap, so that a line-numbered endnote looks approximately like +this: +
+ + [1-2] Notwithstanding, Frye later asserts that Christianity + is "a ghost with the chains of a foul historical record of + cruelty clanking behind it." + +You can change the size of the gap with the macro, +ENDNOTE_LINENUMBER_GAP, which takes as its single argument the size +of the gap. The argument requires a +unit of measure. +So, for example, to change the gap to 2 +picas, +you’d do +
+ + .ENDNOTE_LINENUMBER_GAP 2P + +The default gap for both +PRINTSTYLE TYPESET +and +PRINTSTYLE TYPEWRITE +is 1.5 +ems. +

+ +

• Brackets around 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

+ +

+ +

+Please note that the control macros for endnote numbering affect only +the numbers that appear on the endnotes pages themselves, not the +endnote numbers that appear in the body of the document(s). +

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

+ +

• Endnote numbering alignment

+ +

+By default, mom hangs the numbers on endnotes pages, aligned right +to two placeholders, producing this: +
+ + 9. Lorem ipsum dolor sit amet, consetetur sadipscing elitr, + sed diam nonumy eirmod tempor invidunt ut labore et + dolore magna aliquyam erat, sed diam voluptua. + + 10. Lorem ipsum dolor sit amet, consetetur sadipscing elitr, + sed diam nonumy eirmod tempor invidunt ut labore et + dolore magna aliquyam erat, sed diam voluptua. + +The macros to alter this behaviour are +

ENDNOTE_NUMBERS_ALIGN_RIGHT
ENDNOTE_NUMBERS_ALIGN_LEFT

+ + + +

+Macro: ENDNOTE_NUMBERS_ALIGN_RIGHT <number of placeholders> +

+ +

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

+ +

+For example, if you have fewer than ten endnotes, you might want to do +
+ + .ENDNOTE_NUMBERS_ALIGN_RIGHT 1 + +which would ensure that the endnote numbers hang, but are all flush +with the page’s left margin. If, god help you, you have over a hundred +endnotes, you’d want to do +
+ + .ENDNOTE_NUMBERS_ALIGN_RIGHT 3 + +to ensure that the numbers hang and are properly right-aligned. +

+ + + +

+Macro: ENDNOTE_NUMBERS_ALIGN_LEFT +

+ +

+If you don’t want the endnote numbers to hang and right-align, +invoke .ENDNOTE_NUMBERS_ALIGN_LEFT, which doesn’t +require any argument. This disables hanging and right-alignment of +endnote numbers, so that the example +above +comes out like this: +
+ + 9. Lorem ipsum dolor sit amet, consetetur sadipscing elitr, + sed diam nonumy eirmod tempor invidunt ut labore et + dolore magna aliquyam erat, sed diam voluptua. + + 10. Lorem ipsum dolor sit amet, consetetur sadipscing elitr, + sed diam nonumy eirmod tempor invidunt ut labore et + dolore magna aliquyam erat, sed diam voluptua. + +

+ +

+ + + +

Margin notes

+ +

Margin notes behaviour +
- Adjusting the vertical position of margin notes
Macro: MN_INIT—initialize margin notes
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. +

+ +

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

+ +

+Margin notes are tricky from a typographic standpoint with respect +to vertical placement. Since the leading of margin notes may differ +from that of +running text, +it’s impossible for mom to guess whether to align +the first lines of margin notes with a document +baseline, +whether to align the last lines of margin notes with a document +baseline, or whether to center them, vertically, so that neither +first nor last line aligns with anything! +

+ +

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

+ +

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

+ +

+Sometimes, if a margin note has to be shifted down, there simply +isn’t enough room to start the margin note on the page on +which .MN is invoked. In that case, mom ignores the +margin note entirely and issues a warning, letting you know what +she’s done, and where.

+ +

+In the event that a margin note, sucessfully begun on a page, runs +past your bottom margin (or the last line before footnotes begin), +the margin note will “flow” onto the next page. If +it is a “left” margin note, it will continue in the +left margin. If it is a “right” margin note, it will +continue in the right margin. +

+ +

+If your document is being set in two columns, mom will sensibly and +automatically set all margin notes pertaining to the left column in +the left margin, and all margin notes pertaining to the right column +in the right margin, regardless of the “direction” +argument you give the MN tag. If you try to use MN in documents of +more than two columns, mom will ignore all margin notes, and issue +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 ] +<left-width> +<right-width> +<gutter> +<family+font> +<point-size> +<lead> +<colour> +<hyphenation-flags> + + +

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

+ +

+The argument list is quite long; an explanation of each argument +follows. Any argument whose value you want to be the default must +be entered as "" (i.e. two double-quotes with +no space between them). Defaults for each argument are given in the +explanations below. +

+ +

Argument 1: `[ RAGGED | SYMMETRIC ]`

+ +

+If the first argument is RAGGED, both left and +right margin notes will be flush left. If the first argument +is SYMMETRIC left margin notes will be set flush +right, and right margin notes will be set flush +left. The effect is something like this: +
+ + A left This is a meaningless batch A right + margin note of text whose sole purpose is margin note + with just to demonstrate how the sym- with just + a few words metric argument to MN sets left a few words + in it. and right margin notes. in it. + +

+ +

+If the argument is omitted, or given as "", +both left and right margin notes will be set justified. (Justified +is usually not a good idea, since the narrow measure of margin notes +makes pleasing justification a near impossibility.) +

+ +

Argument 2: `<left-width>`

+ +

+The width of left margin notes. A +unit of measure +must be appended directly onto the argument. The default is to set +left margin notes right out to the edge of the page, which is almost +certainly not what you want, so you should give a value for this +argument if using left margin notes. +

+ +

Argument 3: `<right-width>`

+ +

+The width of right margin notes. A +unit of measure +must be appended directly onto the argument. The default is to +set right margin notes right out to the edge of the page, which is +almost certainly not what you want, so you should give a value for +this argument if using right margin notes. +

+ +

Argument 4: `<gutter>`

+ +

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

+ +

Argument 5: `<font>`

+ +

+The family+font for margin notes. Yes, that’s right: the +family plus font combo. For example, if you want Times +Roman Medium, the argument must be TR. If you want Palatino +Medium Italic, the argument must be PI. The default is the same +family+font combo used for a document’s paragraph text. +

+ +

Argument 6: `<point size>`

+ +

+The point size of type for margin notes. There is no need to append a +unit of measure +to the argument; +points +is assumed (although there’s nothing preventing you from +appending an alternative unit of measure directly to the argument). +The default is for margin notes to use the same point size of type +as is used in document paragraphs. +

+ +

Argument 7: `<lead>`

+ +

+The +leading +of margin notes. <lead> uses +points +as its unit of measure, so don’t tack a unit of measure onto +the end of the argument. The default lead is the same leading +as is used for paragraph text (i.e. the document’s base +leading). If you want the default, you may, for convenience +and clarity, give the word, DOC, to this argument, +instead of "" (two double-quotes). Like the +double-quotes, it indicates that the leading should be the same as +the document’s base leading. +

+ +

Argument 8: `<colour>`

+ +

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

+ +

Argument 9: `<hyphenation-flags>`

+ +

+A number telling groff how you want margin notes +hyphenated. +
+ + 1 = hyphenate without restrictions + 2 = do not hyphenate the last word on the page + 4 = do not hyphenate the last two characters of a word + 8 = do not hyphenate the first two characters of a word + +The values can be added together, so, for example, if you want +neither the first two nor the last two characters of words +hyphenated, the hyphenation-flag would be 12. The default value is +14 (i.e. 2+4+8). +

+ + + +

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 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 +.TOC +or +.ENDNOTES), +mom deposits the word, END, centred after a blank line, +beneath the last line of the document. END is enclosed +between +em-dashes, +like this: +
+ + ...and they all lived happily ever after. + — END — + +

+ +

+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 +or +.TOC). +See +above +for a description of how FINIS behaves. +

+ +

+Note: +If you don’t use FINIS, and you don’t want +footers +(if they’re on) or a page number at the bottom of the last +page of a document, you have to turn them off manually, as the last +two lines of your document file, like this: +
+ + .FOOTERS OFF + .PAGINATE OFF + +

+ + + +

Changing the FINIS string

+ +

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

+ +

+For example, if your document’s in French, you’d do +
+ + .FINIS_STRING "FIN" + +Double-quotes must enclose the macro’s argument. +

+ +

+Note: +If you pass FINIS_STRING a blank string, i.e. +
+ + .FINIS_STRING "" + +mom will still print the em-dashes 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 “initalized”) color changes the colour +of both the FINIS string and the em-dashes that surround it. If you +use the +inline escape, +\*[<colorname>], +in the argument passed to FINIS, only the text will be in the +new colour; the em-dashes will be in the default document colour +(usually black). +

+ +

+ + + + + + + + +

Next: Inserting images

+ +

+ + + + diff --git a/contrib/mom/momdoc/docprocessing.html b/contrib/mom/momdoc/docprocessing.html new file mode 100644 index 00000000..6c52b5cc --- /dev/null +++ b/contrib/mom/momdoc/docprocessing.html @@ -0,0 +1,3601 @@ + + + + + + + + Mom -- Document Processing, Introduction and Setup + + + + + + + +

+ + + + + + + +

Next: The document element tags

+ +

Document processing with mom

+ +

Document defaults
Important note on leading/spacing and bottom margins
The SHIM macro

+ +

+
+

Adjust linespacing to fill pages +
- DOC_LEAD_ADJUST
- SHIM – the macro to get document leading back on track
Managing the document header +
- DOCHEADER
- Docheader control +
  - Docheader description
  - Macro list
Setting documents in columns +
- COLUMNS
- Breaking columns manually +
  - COL_NEXT
  - COL_BREAK

Changing basic type and formatting
parameters after START

Behaviour of the typesetting macros during document processing
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

+ +

+ + + +

Introduction to document processing

+ +

+Document processing with mom uses markup tags to identify document elements +such as heads, paragraphs, and so on. The tags are, of course, +macros, but with sensible, readable names that make them easy +to grasp and easy to remember. (And don’t forget: if you +don’t like the “official” name of a tag — +too long, cumbersome to type in, not “intuitive” enough +— you can change it with the +ALIAS +macro.) +

+ +

+In addition to the tags themselves, mom has an extensive array of +macros that control how they look and behave. +

+ +

+Setting up a mom doc is a simple, four-part procedure. You +begin by entering information about the document itself (title, +subtitle, author, etc.). Next, you tell mom what kind of document +you’re creating (e.g. chapter, letter, abstract, etc...) and +what kind of output you want (typeset, typewritten, draft-style, +etc). Thirdly, you make as many or as few changes to mom’s +default behaviour as you wish. Lastly, you invoke the +START +macro. Voilà! You’re ready to write. +

+ + + +

Document defaults

+ +

+As is to be expected, mom has defaults for everything. If you want +to know a particular default, read about it in the description of +the pertinent tag. +

+ +

+I fear the following may not be adequately covered in the +documentation, 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 +

+ + + +

Important note on leading/spacing and bottom margins

+ +

+Mom takes evenly-aligned bottom margins in +running text +very seriously. Only under a very few (exceptional) circumstances +will she allow a bottom margin to “hang” (i.e. to fall +short). +

+ +

+In order to ensure even bottom margins, mom uses the +“base” document +leading +in effect at the start of running text on each page (i.e. +the leading used in paragraphs) to calculate the spacing of every +document element. Prior to invoking +START, +this is set with the +typesetting macro +LS, +afterwards with the document +control macro +DOC_LEAD. +

+ +

+Because mom relies so heavily on the base document +leading, any change to the leading or spacing on a page will almost +certainly have undesirable consequences on that page’s bottom margin +unless the change is fully compensated for elsewhere on the page. +

+ +

+In other words, if you add a few points of space somewhere on a page, +you must subtract the same number of points somewhere else on that +same page, and vice versa. +

+ +

+If it’s a question of adding or subtracting full +line spaces between or within document elements, you +can do so by using the “v” unit of measure with +whatever spacing macro you choose — +ALD, +RLD, +SPACE +— and mom won’t object. “v” means +“the current leading”, so she isn’t confused by it. And +since “v” accepts decimal fractions, you can add/subtract +half linespaces and quarter linespaces with “v” as well, +provided you compensate for the fractional linespace somewhere +else on the page. +

+ +

+If all this seems like too much work, mom provides a special macro +to get you out of trouble if you’ve played around with leading +and/or spacing. The macro is called SHIM (like those little pieces +of wood carpenters use to get their work even, level and snug), and +it’s described below. +

+ + + +

SHIM

+ +

+Macro: SHIM +

+ +

+SHIM doesn’t take any argument. Use it whenever you’ve played +around with the +leading +or spacing on a page and you need to get mom’s document +leading back on track. +

+ +

+For example, say you want to insert a picture into a document with +the special groff macro, PSPIC (see man groff-tmac for +usage). +

+ +

+Pictures aren’t usually conveniently sized in multiples of +document leading, which means that when you insert the picture, you +disrupt mom’s ordered placement of baselines on the page. +This will certainly result in a bottom margin that doesn’t +match the bottom margins of your document’s other pages. +

+ +

+The solution is to insert SHIM after the picture, +like this: +
+ + <some lines of text> + .PSPIC <full path to picture> + .SHIM + <more lines of text> + +

+ +

+SHIM instructs mom to insert as much or a little space after the +picture as is needed to ensure that the baseline of the next +output line +falls where mom would have put it had you not disrupted the normal +flow of output lines with the picture. +

+ +

+And say, on previewing the above example, you find that the picture +doesn’t centre nicely between the lines of text, you can +always do +
+ + <some lines of text> + .RLD 3p + .PSPIC <full path to picture> + .SHIM + <more lines of text> + +to raise the picture slightly (reverse lead 3 points; see +RLD), +and still have SHIM ensure that text underneath falls exactly where +it’s supposed to. +

+ +

+Note: +For information on disabling the automatic shimming of quotes and +blockquotes during document processing, see +here. +

+ +

+ + + +

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, heads, +subheads, citations, quotes, epigraphs, and so on, all come out +looking neat, trim, and professional. +

+ +

+For the purposes of this tutorial, we’re going to set up +a short story—My Pulitzer Winner—by Joe Blow. +Thankfully, we don’t have to look at story itself, just the +setup. Joe wants the document +

to be draft 7, revision 39;
to use the “default” style of document formatting:
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. The reference macros are: +

TITLE
DOCTITLE
COVERTITLE
DOC_COVERTITLE
SUBTITLE
AUTHOR
CHAPTER – the chapter number

DRAFT – the draft number
REVISION – the revision number
COPYRIGHT – only used on cover pages
MISC – only used on cover pages
COVER_TITLE – only on cover pages; only if needed
DOC_COVER_TITLE – only on document cover pages; only if needed

+ +

+You can use as many or as few as you wish, although at a minimum, +you’ll probably fill in TITLE (unless the document’s a +letter) and AUTHOR. Order doesn’t matter. You can separate +the +arguments +from the macros by any number of spaces. The following are what +you’d need to start Joe Blow’s story. +
+ + .TITLE "My Pulitzer Winner" + .AUTHOR "Joe Blow" + .DRAFT 7 + .REVISION 39 + +

+ +

Step 2

+ +

+Once you’ve given mom the reference information she needs, you +tell her how you want your document formatted. What kind of +document is it? Should it be typeset or typewritten? Is this a +final copy (for the world to see) or just a draft? Mom calls +the macros that answer these questions “the docstyle +macros.” They are: +

DOCTYPE—the type of document (default, chapter, user-defined, letter)
PRINTSTYLE—typeset or typewritten
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 here. However, +PRINTSTYLE has no default and must be present in every formatted +document. If you omit it, mom won’t process the document +AND she’ll complain (both to stderr and as a single printed +sheet with a warning). Moms—they can be so annoying +sometimes. <sigh> +

+ +

+Adding to what we already have, the next bit of setup for Joe +Blow’s story looks like this: +
+ + .TITLE "My Pulitzer Winner" + .AUTHOR "Joe Blow" + .DRAFT 7 + .REVISION 39 + \# + .DOCTYPE DEFAULT \"Superfluous; mom uses DOCTYPE DEFAULT by default + .PRINTSTYLE TYPESET + .COPYSTYLE DRAFT + +Notice the use of the +comment line +( \# ), a handy way to keep groups of macros visually +separated for easy reading in a text editor. +

+ +

Step 3

+ +

+This step—completely optional—is where you, the +user, take charge. Mom has defaults for everything, but +who’s ever satisfied with defaults? Use any of the +typesetting macros +here to change mom’s document defaults (paper size, margins, +family, point size, line space, rag, etc), or any of the document +processing macros that set/change/control the appearance of document +elements. Think of this as the “style-sheet ” section +of a document. And please note: you MUST give mom a +PRINTSTYLE +directive before making any such changes. +

+ +

+Joe Blow wants his story printed in Helvetica, 12 on 14, rag right, +with +page footers +instead of +page headers +and a single asterisk for the +linebreak +character. None of these requirements conforms to mom’s +defaults for the chosen PRINTSTYLE (TYPESET), so we change them +here. The setup for Joe Blow’s story now looks like this: +
+ + .TITLE "My Pulitzer Winner" + .AUTHOR "Joe Blow" + .DRAFT 7 + .REVISION 39 + \# + .DOCTYPE DEFAULT + .PRINTSTYLE TYPESET + .COPYSTYLE DRAFT + \# + .FAMILY H + .PT_SIZE 12 + .LS 14 + .QUAD LEFT \"i.e. rag right + .FOOTERS + .LINEBREAK_CHAR * + +

+ +

Step 4

+ +

+The final step in setting up a document is telling mom to start +document processing. It’s a no-brainer, just the single +macro, START. Other than PRINTSTYLE, it’s the only macro +required for document processing (although I can’t guarantee +you’ll like the results of using just the two). +

+ +

+Here’s the complete setup for My Pulitzer Winner: +
+ + .TITLE "My Pulitzer Winner" + .AUTHOR "Joe Blow" + .DRAFT 7 + .REVISION 39 + \# + .DOCTYPE DEFAULT + .PRINTSTYLE TYPESET + .COPYSTYLE DRAFT + \# + .FAMILY H + .PT_SIZE 12 + .LS 14 + .QUAD LEFT \"i.e. rag right + .FOOTERS + .LINEBREAK_CHAR * + \# + .START + +As pointed out earlier, Joe Blow is no typographer. Given that all he +needs is a printed draft of his work, a simpler setup would have been: +
+ + .TITLE "My Pulitzer Winner" + .AUTHOR "Joe Blow" + .DRAFT 7 + .REVISION 39 + \# + .PRINTSTYLE TYPEWRITE + .COPYSTYLE DRAFT + \# + .START + +.PRINTSTYLE TYPEWRITE, above, means that Joe’s +work will come out “typewritten, double-spaced”, +making the blue-pencilling he (or someone else) is sure to do much +easier (which is why many publishers and agents still insist on +typewritten, double-spaced copy). +

+ +

+When J. Blow stops re-writing and decides to print off a final, +typeset copy of his work for the world to see, he need only make two +changes to the (simplified) setup: +
+ + .TITLE "My Pulitzer Winner" + .AUTHOR "Joe Blow" + .DRAFT 7 + .REVISION 39 + \# + .PRINTSTYLE TYPESET \"first change + .COPYSTYLE FINAL \"second change + \# + .START + +In the above, .DRAFT 7, .REVISION 39, and +.COPYSTYLE FINAL are actually superfluous. The draft +and revision numbers aren’t used when COPYSTYLE is FINAL, +and COPYSTYLE FINAL is mom’s default unless you tell +her otherwise. +

+ +

+BUT... to judge from the number of drafts already, +J. Blow may very well decide his “final” version still +isn’t up to snuff. Hence, he might as well leave in the +superfluous macros. That way, when draft 7, rev. 62 becomes draft +8, rev. 1, he’ll be ready to tackle his Pulitzer winner again. +

+ +

+ + + +

The reference macros

+ +

+The reference macros give mom the meta-information she needs to +generate +docheaders, +page headers, +and +covers. +They must go at the top of any file that uses mom’s document +processing macros. +

+ +

Reference macros

+ +

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

+ + + +

TITLE

+ +

+Macro: TITLE "<title string>" ["<2nd line>" ["<3rd line>" ... ] ] +

+• Arguments must be enclosed in double-quotes +

+ +

+The title string can be caps or caps/lower-case; it’s up to you. In +PRINTSTYLE TYPESET, +the title will appear in the +docheader +exactly as you typed it. However, mom converts the title to all +caps in +page headers +unless you turn that feature off (see +HEADER_<POSITION>_CAPS). +In +PRINTSTYLE TYPEWRITE, +the title always gets converted to caps. +

+ +

+TITLE accepts multiple arguments, each surrounded by double-quotes. +Each argument is printed on a separate line, permitting you to +create multi-line titles in your docheaders. +

+ +

+Note: +If your DOCTYPE is CHAPTER, TITLE +should be the title of the opus, not “CHAPTER whatever”. +

+ + + +

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

+ +

+The doctitle string can be caps or caps/lower-case; it’s up to +you. In +PRINTSTYLE TYPESET, +by default, the doctitle appears in the rightmost position of +page headers, +all in caps unless you turn that feature off (see +HEADER_<POSITION>_CAPS). +In +PRINTSTYLE TYPEWRITE, +the doctitle always gets converted to caps. +

+ +

+DOCTITLE accepts multiple arguments, each surrounded +by double-quotes. Each argument is printed on a separate line, +permitting you to create multi-line document titles for use on +Covers +and/or +Doc covers. +

+ +

+Note: +If your +DOCTYPE +is CHAPTER, you don’t need DOCTITLE. TITLE takes care of +everything. +

+ + + +

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

+ +

+You can also use CHAPTER_STRING if you want +“CHAPTER” (all caps) instead of “Chapter” +(caps/lowercase) in the doc- and page-headers. +

+ + + +

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 argument passed to COPYRIGHT is only used on cover or doc cover +pages, and then only if the argument COPYRIGHT is passed to +COVER +or +DOC_COVER. +Do not include the copyright symbol in the argument passed to +COPYRIGHT; mom puts it in for you. +

+ +

+If the optional argument, COVER or DOC_COVER, +is given to COPYRIGHT, the string argument represents the copyright +information that will appear on cover or document cover pages (see +the +Introduction to cover pages +for a description of the difference between “document +covers” and “covers”). Thus, it is possible to +have differing copyright information on the document cover and on +the cover (“title”) page. An example might be: +
+ + .COPYRIGHT DOC_COVER "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 +

+ + + +

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

+ +

+The only time you require a COVERTITLE or DOC_COVERTITLE is when +none of the required first arguments to COVER or DOC_COVER fits +your needs for the title you want to appear on cover (or doc cover) +pages. +

+ +

+COVERTITLE and DOC_COVERTITLE accept multiple arguments, each +surrounded by double-quotes. Each argument is printed on a separate +line, permitting you to create multi-line titles on your cover +and/or doc cover pages. +

+ +

+ + + +

The docstyle macros

+ +

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

+ +

Docstyle macros

DOCTYPE +
- DOCTYPE_UNDERLINE – control DOCTYPE NAMED underlining
PRINTSTYLE – non-optional macro required for document processing +
- Defaults for PRINTSTYLE TYPESET
- Defaults for PRINTSTYLE TYPEWRITE +
  - PRINTSTYLE TYPEWRITE control macros – underlining
COPYSTYLE

+ + + +

DOCTYPE

+ +

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

+ +

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

+ +

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

+ +

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

+ +

+Note: +For backward compatibility with pre-1.1.5 versions of mom, you can +also supply a chapter title by omitting the CHAPTER reference macro +and supplying a chapter title with +CHAPTER_STRING.) +

+ +

+The page headers in DOCTYPE CHAPTER contain the author, +the title of the book (which you gave with +TITLE), +and “Chapter <n>” (or the chapter title). See +Default Specs for Headers +for mom’s default type parameters for each part of +the page header. +

+ +

+NAMED takes an additional argument: a name for this +particular kind of document (e.g. outline, synopsis, abstract, +memorandum), enclosed in double-quotes. NAMED is +identical to DEFAULT except that mom prints the argument +to NAMED beneath the +docheader, +as well as in page headers. +(See +Default specs for headers +for how mom outputs each part of the page header.) +

+ +

+Additionally, if you wish the name of this particular kind of +document to be coloured, you can pass DOCTYPE NAMED a +third (optional) argument: the name of a colour pre-defined (or +“initialized”) with +NEWCOLOR +or +XCOLOR. +For example, if you have a doctype named “Warning”, +and you’d like “Warning” to be in red, assuming you’ve +pre-defined (or “initialized”) the color, red, this is +what the DOCTYPE entry would look like: +
+ + .DOCTYPE NAMED "Warning" red + +

+ +

How to control DOCTYPE NAMED underlining

+ +

+By default, the string passed to DOCTYPE NAMED is +underlined in the docheader, and on document-cover pages and cover +(“title”) pages. (See the +Introduction to covers +for the difference between “doc cover” and +“cover” pages.) +

+ +

+Formerly, this underlining was carved in stone. As of version 1.5 +of mom, you can use the macro DOCTYPE_UNDERLINE to set the weight of +the underline and its distance from where the doctype-name appears +in the docheader (doc covers and covers handle underlining of the +doctype-name differently; see +COVER_UNDERLINE), +or simply toggle doctype underlining on or off. Mom’s default +is to underline the doctype-name. +

+ +

+The order of arguments is weight, optionally followed by +gap, where “gap” is the distance from the +baseline +of the doctype-name to the underline. +

+ +

+The weight argument is given in points, or fractions +thereof, and must not have the +unit of measure, +p, appended. Like +RULE_WEIGHT, +weights must be greater than 0 and less than 100. Mom’s +default for DOCTYPE NAMED underlining is 1/2 point. +

+ +

+The gap argument can be given using any unit of measure, +and must have the unit of measure appended to the argument. +The distance of the gap is measured from the baseline of the +DOCTYPE NAMED name to the upper edge of the underline. +Mom’s default gap for named-doctype underlining is 2 points. +

+ +

+As an example, supposed you want the doctype-name underlined in the +docheader with a 2-point rule separated from the head by 3 points. +The way to accomplish it is: +
+ + .DOCTYPE_UNDERLINE 2 3p + +If you wanted the same thing, but were content with mom’s +default gap of 2 points, +
+ + .DOCTYPE_UNDERLINE 4 + +would do the trick. +

+ +

+If you merely want to toggle the underlining of +the doctype-name in docheaders on or off, invoke +.DOCTYPE_UNDERLINE by itself to turn the underlining on, +or .DOCTYPE_UNDERLINE OFF (or NO, X, etc.) +

+ +

+Please note that if you supply a weight to DOCTYPE_UNDERLINE, and +optionally a gap, you also turn the underlining of the doctype-name +in docheaders on; if this is not what you want, you must turn the +underlining off manually afterwards. +

+ +

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

+ + + +

PRINTSTYLE

+ +

+Macro: PRINTSTYLE TYPESET | TYPEWRITE [ SINGLESPACE ] +

+ +

+• Required for document processing +
+Must come before any changes to default document style +

+ +

+PRINTSTYLE tells mom whether to typeset a document, or to print it +out “typewritten, doubled-spaced”. +

+ +

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

+ +

+Furthermore, PRINTSTYLE must come before any changes to mom’s +default typestyle parameters. (This applies primarily to, but is by +no means restricted to, PRINTSTYLE TYPESET.) PRINTSTYLE +sets up complete templates that include default papersize, margins, +family, fonts, point sizes, and so on. Therefore, changes to any +aspect of document style must come afterwards. +

+ +

+TYPESET, as the argument implies, typesets +documents (by default in Times Roman; see +TYPESET defaults). +You have full access to all the +typesetting macros +as well as the +style control macros +of document processing. +

+ +

+As mentioned above, PRINTSTYLE TYPESET must come before +any changes to mom’s default typographic settings. For +example, +
+ + .PAPER A4 + .LS 14 + .PRINTSTYLE TYPESET + +will not changes mom’s default paper size to A4, +nor her default document leading 14 points, whereas +
+ + .PRINTSTYLE TYPESET + .PAPER A4 + .LS 14 + +will. +

+ +

+With TYPEWRITE, mom does her best to reproduce the look +and feel of typewritten, double-spaced copy (see +TYPEWRITE defaults). +Control macros +and +typesetting macros +that alter family, font, point size, and +leading +are (mostly) ignored. An important exception is +HEADER_SIZE +(and, by extension, FOOTER_SIZE), which allows you to reduce the +point size of headers/footers should they become too crowded. Most +of mom’s inlines affecting the appearance of type are also +ignored +(\*S[<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. +

+ +

+Note: +If you absolutely must have a leading other than typewriter double- +or singlespaced, the only way to get it is with the +DOC_LEAD +macro, and then only if DOC_LEAD is set before you invoke the +START +macro. +

+ +

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

+ +

+In PRINTSTYLE TYPEWRITE, mom, by default, underlines +anything that looks like italics. This includes the +\*[SLANT] +inline escape +for pseudo-italics. +

+ +

+If you’d prefer that mom were less bloody-minded +about pretending to be a typewriter (i.e. you’d like italics and +pseudo-italics to come out as italics), use the control macros +
+ + .ITALIC_MEANS_ITALIC + +and + + .SLANT_MEANS_SLANT + +Neither requires an argument. +

+ +

+Although it’s unlikely, should you wish to reverse +the sense of these macros in the midst of a document, +.UNDERLINE_ITALIC and .UNDERLINE_SLANT restore +underlining of italics and pseudo-italics. +

+ +

+Additionally, by default, mom underlines +quotes +(but not +blockquotes) +in PRINTSTYLE TYPEWRITE. If you don’t like this +behaviour, turn it off with +
+ + .UNDERLINE_QUOTES OFF + +

+ +

+To turn underlining of quotes back on, use UNDERLINE_QUOTES without +an argument. +

+ +

+While most of the +control macros +have no effect on PRINTSTYLE TYPEWRITE, there +is an important exception: +HEADER_SIZE +(and by extension, FOOTER_SIZE). This is +particularly useful for reducing the point size of +headers/footers should they become crowded (quite likely to +happen if the title of your document is long and your +COPYSTYLE +is DRAFT). +

+ + + +

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 type and formatting parameters before START

+ +

+In the third (optional) part of setting up a document (see +Tutorial – Setting up a mom document), +you can use the +typesetting macros +to change mom’s document-wide defaults for margins, +line length, family, base point size, +leading, +and justification style. +

+ +

+Two additional style concerns have to be addressed here (i.e. in +macros before +START): +changes to the +docheader, +and whether you want you want the document’s nominal leading +adjusted to fill pages fully to the bottom margin. +

+ +

Type & formatting parameters before START

Behaviour of the typesetting macros before START +
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. +

+ +

+Note: +Don’t 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 style parameters after START. +

+ +

Special note on LEFT, RIGHT and CENTER prior to START

+ +

+In a word, these three macros have no effect on document processing +when invoked prior to START. +

+ +

+All mom’s document element tags (PP, HEAD, BLOCKQUOTE, +FOOTNOTE, etc.) except +QUOTE +set a +fill mode +as soon as they’re invoked. If you wish to turn fill mode off +for the duration of any tag (with +LEFT, RIGHT or CENTER) +you must do so immediately after invoking the tag. Furthermore, +the change affects only the current invocation of the tag. +Subsequent invocations of the same tag for which you want the same +change require that you invoke .LEFT, .RIGHT +or CENTER immediately after every invocation of the tag. +

+ + + +

Including (sourcing) style sheets and files

+ +

+If you routinely make the same changes to mom’s defaults in +order to create similar documents in a similar style—in other +words, you need a template— you can create style-sheet files +and include, or "source", them into your mom documents with the +macro, INCLUDE. The right place for such style sheets is after +PRINTSTYLE +and before +START. +

+ +

+Say, for example, in a particular kind of document, you always +want main heads set in Helvetica Bold Italic, flush left, +with no underscore. You’d create a file, let’s call it +head-template, in which you’d place the pertinent HEAD +control macros. +
+ + .HEAD_FAMILY H + .HEAD_FONT BI + .HEAD_QUAD L + .HEAD_UNDERLINE OFF + +Then, in the preliminary document set-up section of your main file, +you’d include the style sheet, or template, like this: +
+ + .TITLE "Sample Document + .AUTHOR "Joe Blow + .PRINTSTYLE TYPESET + \# + .INCLUDE head-template + \# + .START + + +The blank comment lines ( \# ) aren’t required, but +they do make your file(s) easier to read. +

+ +

+If the file to be included is in the same directory as the file +you’re working, you simply enter the filename after +.INCLUDE. If the file’s in another directory, you must +provide a full path name to it. For example, if you’re working in +a directory called /home/joe/stories and your +style-sheet is in /home/joe/style-sheets, the above +example would have to look like this: +
+ + .TITLE "Sample Document + .AUTHOR "Joe Blow + .PRINTSTYLE TYPESET + \# + .INCLUDE /home/joe/style-sheets/head-template + \# + .START + +

+ +

+INCLUDE is not restricted to style sheets or templates. You can +include any file at any point into a document, provided the file +contains only text and valid groff or mom formatting commands. +Neither is INCLUDE restricted to use with mom’s document +processing macros. You can use it in plain typeset documents as +well. +

+ +

+Experts: +INCLUDE is an alias for the groff request, .so. Mix 'n' +match with impunity. +

+ + + +

Initializing colours

+ +

+Although it doesn’t really matter where you define/initialize +colours for use in document processing (see +NEWCOLOR +and +XCOLOR +in the section +Coloured text), +I recommend doing so before you begin document processing with +START. +

+ +

+The macro, +COLOR, +and the +inline escape, +\[<colorname>], +can be used at any time during document processing for occasional +colour effects. However, consistent and reliable colourizing of +various document elements (the docheader, heads, linebreaks, +footnotes, pagenumbers, and so on) must be managed through the use +of the +document element control macros. +

+ +

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

+ + + +

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

+ +

+• Must come before +START; distance requires a unit of measure +

+ +

+By default, mom prints a +docheader +on the first page of any document (see +below +for a description of the docheader). If you don’t want a docheader, +turn it off with +
+ + .DOCHEADER OFF + +DOCHEADER is a toggle macro, so the argument doesn’t +have to be OFF; it can be anything you like. +

+ +

+If you turn the docheader off, mom, by default, starts +the running text of your document on the same top +baseline +as all subsequent pages. If you’d like her to start at a different +vertical position, give her the distance you’d like as a second +argument. +
+ + .DOCHEADER OFF 1.5i + +This starts the document 1.5 inches from the top of the page PLUS +whatever spacing adjustment mom has to make in order to ensure that +the first baseline of running text falls on a “valid” +baseline (i.e. one that ensures that the bottom margin of the first +page falls where it should). The distance is measured from the top +edge of the paper to the +baseline +of the first line of type. +

+ +

+Tip: +Since no document processing happens until you invoke +.START—including +anything to do with docheaders—you can +typeset your own docheader prior to START (if +you don’t like the way mom does things) and use +.DOCHEADER OFF with its optional distance +argument to ensure that the body of your document starts where +you want. You can even insert a PostScript image file (see PSPIC). +

+ + + +

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, underscored, 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 alter the space by +including the +inline escapes, +\*[UP] +or +\*[DOWN], +in the argument you pass to +CHAPTER_TITLE, +like this: +
+ + .CHAPTER_TITLE "\*[DOWN 2p]Why Not Patent Calculus?" + +or + + .CHAPTER_TITLE "\*[UP 2p]Why Not Patent Calculus?" + +

+ +

Docheader control

Change the starting position of the docheader
Change quad direction the entire docheader
Change the family of the entire docheader
Change the family of individual docheader elements
Change the font of individual docheader elements
Adjust the size of docheader elements
Adjust the docheader leading
Change the colour of the entire docheader
Change the colour of the individual docheader elements
Change the attribution string (“by”)

+ +

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

+ +

2. Change the quad direction of the docheader

+ +

+By default, mom centers the docheader. If you’d prefer to +have your docheaders set flush left or right, or need to restore +the default centering, invoke .DOCHEADER_QUAD with the +quad direction you want, either LEFT (or L), +RIGHT (or R) or CENTER (or +C). +

+ +

3. Change the family of the entire docheader

+ +

+By default, mom sets the docheader in the same +family used for +running text. +If you’d prefer to have your docheaders set in a different +family, invoke .DOCHEADER_FAMILY with the family you +want. The argument 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 with the macros +listed +here. +

+ +

4. Change the family of individual docheader elements

+ +

+The following macros let you change the +family +of each docheader element separately: +

Macro: TITLE_FAMILY <family>
Macro: CHAPTER_TITLE_FAMILY <family>
Macro: SUBTITLE_FAMILY <family>
Macro: AUTHOR_FAMILY <family>
Macro: DOCTYPE_FAMILY <family> + (if DOCTYPE is NAMED) +

+ +

+Simply pass the appropriate macro the family you want, just as you +would with +FAMILY. +

+ +

5. Change the font of individual docheader elements

+ +

+The following macros let you change the +font +of each docheader element separately: +

Macro: TITLE_FONT R | B | I | BI
Macro: CHAPTER_TITLE_FONT R | B | I | BI
Macro: SUBTITLE_FONT R | B | I | BI
Macro: AUTHOR_FONT R | B | I | BI
Macro: DOCTYPE_FONT R | B | I | BI + (if DOCTYPE is NAMED) +

+ +

+Simply pass the appropriate macro the font you want. R, B, +I and BI have the same meaning as they do for +FT. +

+ +

6. Adjust the size of individual docheader elements

+ +

+The following macros let you adjust the point size of each docheader +element separately. +

+ +

+Mom calculates the point size of docheader elements from the point +size of paragraphs in running text, so you must prepend a + or - +sign to the argument. Points is assumed as the +unit of measure, +so there’s no need to append a unit to the argument. +Fractional point sizes are allowed. +

+ +

Macro: TITLE_SIZE <+/-points> +
+ default = +3.5 (+4 if docheader title is "Chapter <n>") +
Macro: .CHAPTER_TITLE_SIZE <+/-points> +
+ default = +4 +
Macro: .SUBTITLE_SIZE <+/-points> +
+ default = +0 +
Macro: .AUTHOR_SIZE <+/-points> +
+ default = +0 +
Macro: .DOCTYPE_SIZE <+/-points> + (if DOCTYPE is NAMED) +
+ default = +3 +

+ +

+Simply pass the appropriate macro the size adjustment you want. +

+ +

7. Adjust the docheader leading

+ +

+The +leading +of docheaders is the same as running text. If you’d like your +docheaders to have a different leading, say, 2 points more than the +lead of running text, use: +
+ + .DOCHEADER_LEAD +2 + +Since the leading of docheaders is calculated from the lead of running +text, a + or - sign is required before the argument (how much to add +or subtract from the lead of running text). No +unit of measure +is required; points is assumed. +

+ +

8. Change the colour of the entire docheader

+ +

+If you want to colourize the entire docheader: +
+ + .DOCHEADER_COLOR <color name> + +You must pre-define (or “initialize”) the colour with +NEWCOLOR +or +XCOLOR. +

+ + +

9. Change the colour of the docheader elements individually

+ +

+The following macros let you change the colour of each +docheader element separately. You must pre-define (or +“initialize”) the colour with +NEWCOLOR +or +XCOLOR. +

Macro: TITLE_COLOR <colorname>
Macro: CHAPTER_TITLE_COLOR <colorname> +
- Note: CHAPTER_TITLE_COLOR is needed only if you supply both a + CHAPTER + reference macro and a + CHAPTER_TITLE + macro. Otherwise, TITLE_COLOR takes care of colorizing the + chapter header. +
Macro: SUBTITLE_COLOR <colorname>
Macro: ATTRIBUTE_COLOR <colorname> + (the “by” string preceding author[s] name[s]) +
Macro: AUTHOR_COLOR <colorname>
Macro: DOCTYPE_COLOR <colorname> + (if DOCTYPE is NAMED) +

+ +

+It is not recommended that you embed colour (with the +inline escape, +\*[<colorname>]) +in the strings passed to TITLE, CHAPTER_TITLE, SUBTITLE, AUTHOR or +the name you give DOCTYPE NAMED. The strings passed to +these macros are used to generate page +headers +and +footers, +with the result that an embedded colour will cause the string to be +colourized in headers and/or footers as well. (If you want headers +or footers colourized, or parts thereof, use the header/footer +control macros.) +

+ +

10. Change the attribution string (“by”)

+ +

+If you’re not writing in English, you can change what mom +prints where “by” appears in docheaders. For example, +
+ + .ATTRIBUTE_STRING "par" + +changes “by” to “par”. ATTRIBUTE_STRING +can also be used, for example, to make the attribution read +"Edited by". +

+ +

+If you don’t want an attribution string at all, simply pass +ATTRIBUTE_STRING an empty argument, like this: +
+ + .ATTRIBUTE_STRING "" + +Mom will deposit a blank line where the attribution string normally +appears. +

+ +

+If the optional argument, COVER or DOC_COVER, +is given to ATTRIBUTE_STRING, the string argument represents the +attribution string that will appear on cover or document cover pages +(see the +Introduction to cover pages +for a description of the difference between “document +covers” and “covers”). Thus, it is possible to +have different attribution strings on the document cover page, the +cover (“title”) page, and in the first-page docheader. +An extreme example would be: +
+ + .ATTRIBUTE_STRING "" + .ATTRIBUTE_STRING DOC_COVER "Edited by" + .ATTRIBUTE_STRING COVER "by" + +The first invocation of .ATTRIBUTE_STRING establishes a +blank attribution string that will be incorporated in the first-page +docheader. The second will print “Edited by” on the +document cover; the third will print “by” on the cover +(“title”) page. +

+ +

+If you don’t require differing attribute strings for +doc cover pages, cover pages, or the first-page docheader, +.ATTRIBUTE_STRING, without either of the optional first +arguments, is sufficient. +

+ +

+Note: +The type specs for the attribution line in docheaders are the +same as for the author line. Although it’s highly unlikely +you’ll want the attribution line in a different family, font, +or point size, you can make such changes using +inline escapes +in the argument to ATTRIBUTE_STRING. For example, +
+ + .ATTRIBUTE_STRING "\f[HBI]\*[SIZE -2p] by \*[SIZE +2p]\*[PREV]" + +would set “by” in Helvetica bold italic, 2 points +smaller than normal. +

+ +

+ + + +

Setting documents in columns

+ +

+Setting documents in columns is easy with mom. All you have to do +is is say how many columns you want and how much space you want +between them (the +gutters). +That’s it. Mom takes care of everything else, from soup to +nuts. +

+ +

Some words of advice

+ +

+If you want your type to achieve a pleasing +justification +or +rag +in columns, reduce the point size of type (and probably the +leading +as well). Mom’s default document point size is 12.5, which +works well across her default 39 +pica +full page line length, but with even just two columns on a page, the +default point size is awkward to work with. +

+ +

+Furthermore, you’ll absolutely need to reduce the indents for +epigraphs, +quotes, +and +blockquotes +(and probably the +paragraph first-line indent +as well). +

+ + + +

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

+ +

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 macro to get mom back on + track when you’re ready to return to the + document’s default leading. + + QUAD •Changes quad for the duration of the + current tag only. As soon as another document + element tag is entered, the quad reverts to + the current document default for the new + tag. + + N.B. — Line-for-line quadding macros + (LEFT, CENTER, RIGHT) are also temporary, + overridden by the QUAD value of any subsequent + document element tag. + +

+ +

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 +conjuction with +NEWPAGE. +

+ + + +

ADD_SPACE

+ +

+Macro: ADD_SPACE <amount of space> +

+ +

+• Requires a unit of measure +

+ +

+ADD_SPACE takes as its single argument the distance +you want mom to advance from the normal +baseline position at the top of any page after the first +(i.e. the one on which the docheader is normally printed). A +unit of measure is +required. +

+ +

+For example, say you wanted to insert 2 inches of space before the +start of +running text +on a page other than the first. You’d accomplish it with +
+ + .NEWPAGE + .ADD_SPACE 2i + +which would terminate your current page, break to a new page, print +the header (assuming headers are on) and insert 2 inches of space +before the start of running text. +

+ +

+Since adding space in this way is almost sure to disrupt mom’s +ability to guarantee perfectly flush bottom margins, I highly +recommend using the +SHIM +macro immediately after ADD_SPACE. +

+ + +

Changing basic type and formatting parameters after START

+ +

+In the normal course of things, you establish the basic type +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 to make +global changes to the basic type parameters of a document. +

+ +

+ + + +

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 to 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 + docheaders, + headers (or footers) and page numbering to the new value; + for changing the right margin of + running text + only, use + R_MARGIN + (see + typesetting macros during + document processing, + entry for R_MARGIN) +
all mom commands that include 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); + for changing the line length of + running text + only, use + LL + (see + typesetting macros during document processing, + entry for LL) +

+ + + +

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

+ + + +

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 +

+ +

+Important: +Do not use DOC_LEAD in the middle of a page! It should always and +only be invoked immediately prior to a new page, like this: +
+ + .DOC_LEAD <new value> + .NEWPAGE + +

+ +

+Note: +Even if you don’t pass DOC_LEAD the optional argument +ADJUST, mom will still adjust the leading of endnotes +pages and toc pages. See +ENDNOTE_LEAD +and +TOC_LEAD +for an explanation of how to disable this default behaviour. +

+ + + +

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 +

+ +

+ + + + + + + + +

Next: The document element tags

+ +

+ + + + diff --git a/contrib/mom/momdoc/goodies.html b/contrib/mom/momdoc/goodies.html new file mode 100644 index 00000000..69457a13 --- /dev/null +++ b/contrib/mom/momdoc/goodies.html @@ -0,0 +1,1503 @@ + + + + + + + + Mom -- Goodies + + + + + + + +

+ + + + + + + +

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
SILENT – “hide” input lines from output
TRAP – suspend/re-invoke traps
SMARTQUOTES – convert typewriter doublequotes to proper doublequotes
CAPS – convert to upper case
STRING – user-definable strings
ESC_CHAR – change the escape character to something other than a backslash
SIZESPECS – get cap-height, x-height and descender depth of a font
Underscoring/underlining +
- UNDERSCORE – single underscore +
- UNDERSCORE2 – double underscore
- UNDERLINE – fixed-width fonts only +
  - \*[UL] – inline escape to underline; fixed-width fonts only
Padding +
- PAD – insert equalized space 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; see the +list of reserved words). +

+ +

+Groff has always been a bit intimidating for new users because +its standard macro packages use very terse macro names. Mom +doesn’t like people to feel intimidated; she wants them +to feel welcome. Consequently, she tries for easy-to-grasp, +self-explanatory macro names. However, mom knows that people have +their own ways of thinking, their own preferences, their own habits. +Some of her macro names may not suit you; they might be too long, +or aren’t what you automatically think of when you want to do +a particular thing, or might conflict with habits you've developed +over the years. +

+ +

+If you don’t like one of mom’s macro names, say, +PAGEWIDTH, change it, like this: +
+ + .ALIAS PW PAGEWIDTH + | | + new--+ +--official + name name + +The first argument to ALIAS is the new name you want for a macro. +The second is the “official” name by which the macro is +normally invoked. After ALIAS, either can be used. +

+ +

+Note that in ALIAS, you do NOT include the period (dot) that +precedes the macro when it’s a +control line. +

+ +

+Tip: +A particularly good candidate for ALIAS is the macro, +PT_SIZE. +A more natural name for it (at least to old-school phototypesetters) +would simply be PS, but PS conflicts with the eqn equation +preprocessor and thus mom uses the longer form. However, if +you’re not using eqn, you can happily rename PT_SIZE to +PS: +
+ + .ALIAS PS PT_SIZE + +

+ +

+Note: +If you use ALIAS a lot, and always for the same things, consider +creating an aliases file of the form +
+ + .ALIAS <new name> <old name> + .ALIAS <new name> <old name> + .ALIAS <new name> <old name> + ...etc + +Put the file someplace convenient and source it (include it) at the +beginning of your documents with the +INCLUDE +macro. Assuming that you've created an aliases file called +mom-aliases in your home directory under a directory called +Mom, you'd source it by placing +
+ + .INCLUDE /home/<username>/Mom/mom-aliases + +at the top of your documents. +

+ +

+If you share documents that make use of an alias file, remember that +other people don’t have the file. Paste the whole thing at +the top of your documents, please. +

+ +

+Experts: +ALIAS is an alias of .als. You can use either, or mix +'n' match with impunity. +

+ + +

Hide input lines from output

+ +

+ Macro: SILENT toggle +

+ +

+Alias: COMMENT +

+ +

+Sometimes, you want to “hide” +input lines +from final output. This is most likely to be the case when setting +up string tabs (see the +quickie tutorial on string tabs +for an example), but there are other places where you might want +input lines to be invisible as well. Any place you don’t want +input lines to appear in the output, use the SILENT macro. +

+ +

+SILENT is a toggle. Invoking it without an argument turns it on; +any argument turns it off. E.g., +
+ + .SILENT + A line of text + .SILENT OFF + +The line “A line of text” will not appear in the +output copy. +

+ +

+SILENT is aliased as COMMENT. If you want to insert non-printing +comments into your documents, you may prefer this. +

+ +

+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 automatic +behind-the-scenes processing is needed in order for one page to +finish and another to start. +

+ +

+Sometimes, traps get sprung when you don’t want them. If this +happens, surround just the offending macros and input lines with +
+ + .TRAP OFF + ... + .TRAP + +TRAP is a toggle, therefore any argument turns it off (i.e. suspends +the trap), and no argument turns it (back) on. +

+ + + +

Convert typewriter doublequotes to proper doublequotes

+ +

+Macro: SMARTQUOTES [<off>] [ ,, | >> | << ] +

+ +or + +

+Macro: SMARTQUOTES DA | DE | ES | FR | IT | NL | NO | PT | SV +

+ +

+If you invoke SMARTQUOTES without an argument, mom converts all +instances of the inch-mark, ("), also called +a doublequote, into the appropriate instances of true Anglo-American +open-and close-doublequotes. (See +Internationalization +for how to get SMARTQUOTES to behave correctly for non-English +quoting styles.) +

+ +

+Typographically, there is a difference between the inch-mark and +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 is on by default (in the Anglo-American style); with +PRINTSTYLE TYPEWRITE, +it’s off by default (and should probably stay that way). +

+ +

+Finally, if you’re fussy about the kerning of quote marks in +relation to the text they surround, or have special quoting needs, +you have to enter quote marks by hand using groff’s native +inline escapes +for special characters (see man groff-char +for a complete list of special characters). Entering quote marks +this way allows you to use mom’s +inline kerning escapes +to fine-tune the look of quotes. +

+ +

+Note: +SMARTQUOTES does not work on single quotes, which most people +input with the apostrophe (found at the right-hand end of the +“home row” on a QWERTY keyboard). Groff will interpret +all instances of the apostrophe as an apostrophe, making the symbol +useless as an open-single-quote. For open single quotes, input +the backtick character typically found under the tilde on most +keyboards. (Pour nous autres, “backtick” veut dire +l’accent grave.) Here’s an example of correct input +copy with single quotes: +
+ + "But she said, `I don’t want to!'" + +

+ +

+Additional note: +Whether or not you have SMARTQUOTES turned on, get into the habit of +entering the foot-and inch-marks, when you need them, with the +inline escapes +\*[FOOT] and +\*[INCH], instead of +' and ". +

+ + + +

Convert to upper case

+ +

+Macro: CAPS toggle +

+ +

+CAPS converts all lower case letters to upper case. +Primarily, it’s a support macro used by the +document processing macros, +but you may find it helpful on occasion. CAPS is a toggle, therefore +no argument turns it on, any argument (OFF, QUIT, X, etc.) turns +it off. +
+ + .CAPS + All work and no play makes Jack a dull boy. + .CAPS OFF + + +produces, on output +
+ + ALL WORK AND NO PLAY MAKES JACK A DULL BOY. + +If you wish to capitalise a section of type inline, use the +inline escapes, +\*[UC]...\*[LC] +like this: +
+ + All work \*[UC]and\*[LC] no play makes Jack a dull boy. + + +The above produces, on output +
+ + All work AND no play makes Jack a dull boy. + +

+ + + +

User-defined strings

+ +

+Macro: STRING <name> <what you want in the string> +

+ +

+You may find sometimes that you have to type out portions of text +repeatedly. If you'd like not to wear out your fingers, you can +define a string that, whenever you call it by name, outputs whatever +you put into it. +

+ +

+For example, say you’re creating a document that repeatedly uses +the phrase “the Montreal/Windsor corridor”. Instead +of typing all that out every time, you could define a string, like +this: +
+ + .STRING mw the Montreal/Windsor corridor + +Once a string is defined, you can call it any time with the +inline escape +\*[<stringname>]. Using the example +string above +
+ + The schedule for trains along \*[mw]: + +produces, on output +
+ + The schedule for trains along the Montreal/Windsor corridor: + +

+ +

+Note: +Be very careful not to put any spaces at the ends of strings +you’re defining, unless you want them. Everything after +the name argument you pass to STRING goes into the string, +including trailing spaces. 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. +

+ + +

+Experts: +ESC_CHAR is an alias of .ec. Mix 'n' match +the two with impunity. +

+ + + +

Get cap-height, x-height and descender depth of a font

+ +

+Macro: SIZESPECS +

+ +

+Whenever you need to get the +cap-height, +x-height +or +descender +depth of type at the current point size, invoke .SIZESPECS, which takes no argument. +The dimensions are stored in the string registers +\*[$CAP_HEIGHT], \*[$X_HEIGHT] and +\*[$DESCENDER], respectively, in +machine units +to which the +unit of measure, +u, is already appended. +

+ +

+Thus, if you wanted to advance 2 inches from your current position +on the page plus the cap-height of the current point size of type +
+ + .PT_SIZE <n> + .SIZESPECS + .ALD 2i+\*[$CAP_HEIGHT] + +would do the trick. +

+ + + +

Single underscore

+ +

+Macro: UNDERSCORE [ <distance below baseline> ] "<string>" +

+ +

+• Optional argument requires a unit of measure +

+ +

+By default, UNDERSCORE places an underscore 2 points beneath the +required +string argument. +The string must be enclosed in double-quotes, like this: +
+ + .UNDERSCORE "Unmonitored monopolies breed high prices and poor products." + +If you wish to change the distance of the rule from the baseline, +use the optional argumen +<distance below baseline> +(with a unit of measure). +
+ + .UNDERSCORE 3p "Unmonitored monopolies breed high prices and poor products." + +The above places upper edge of the underscore 3 points below the +baseline. +

+ +

Controlling the weight of underscores

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

+ +

Colorizing underscored text

+If you want underscored text to be in a different colour from the +text around it, use the +COLOR +macro, rather than the +inline escape for changing color. +In other words, assuming your prevailing text color is black and +you want underscored text in red +
+ + .COLOR red + .UNDERSCORE "text to underscore" + .COLOR black + +rather than +
+ + .UNDERSCORE "\*[red]text to underscore\*[black]" + +The latter will render the text in red, and the underscore in black. +You can use this to create truly rainbow effects if you want, e.g. +text in red, underscore in blue, and prevailing type in black: +
+ + .UNDERSCORE "\*[red]text to underscore\*[blue]" + .COLOR black + +

+ +

Notes on underscoring

+UNDERSCORE does not work across line breaks in output copy, which is +to say that you can’t underscore a multi-line passage simply +by putting the text of the whole thing in the string you pass to +UNDERSCORE. Each +output line +or portion of an output line you want underscored must be plugged +separately into UNDERSCORE. Bear in mind, though, that underscoring +should at best be an occasional effect in typeset copy. If you want +to emphasize an entire passage, it’s much, much better to +change fonts (e.g. to italic or bold). +

+ +

+You can easily and successfully underline entire passages in +simulated typewriter-style copy (i.e. if your font is a monospaced +one, like Courier, or you’re using the document processing +macro +PRINTSTYLE TYPEWRITE), +with the +UNDERLINE +macro. UNDERLINE is designed specifically for this purpose, but +works only with the monspaced fonts. +

+ +

+Mom doesn’t always get the position and length of the +underscore precisely right in +justified +copy, although she’s fine with all the other +fill modes, +as well as with the no-fill modes. The reason is that when text is +justified, the word spacing may expand to fill the line, but that +doesn’t happen until after the line has been processed +in all other respects—including establishing how long to make +an underscore. A workaround is to prepend the backslash character +(\) to each word space in the string passed +to UNDERSCORE. The word spacing of the underscored string may be +slightly smaller than the word space of the remainder of the line, +but in most cases, the difference isn’t visually noticeable. +

+ +

+UNDERSCORE tends to confuse gxditview, even though the +output, when printed, looks fine. Generally, I recommend using +gv to preview files anyway. See the section on +previewing. +

+ + + +

Double underscore

+ +

+Macro: UNDERSCORE2 [ <distance below baseline> [ <distance between rules> ] ] "<string>" +

+ +

+• Optional arguments require a unit of measure +

+ +

+By default, UNDERSCORE2 places a double underscore 2 points beneath +the required +string argument. +The string must be enclosed in double-quotes, like this: +
+ + .UNDERSCORE2 "Unmonitored monopolies breed high prices and poor products." + +The default distance between the two rules is 2 points, measured +from the bottom edge of the upper rule to the top edge of the lower +one. +

+ +

+If you wish to change the distance of the double underscore from the +baseline, +use the optional argument +<distance below baseline> +(with a unit of measure), e.g., +
+ + .UNDERSCORE2 3p "Unmonitored monopolies breed high prices and poor products." + +which places the upper edge of the first rule of the double +underscore 3 points below the baseline. +

+ +

+If you wish to change the distance between the two rules as well, +use the second optional argument +<distance between rules> +(with a unit of measure). Be aware that you must give a value for +the first optional argument if you want to use the second. The +distance between the two rules is measured from the bottom edge of +the upper rule to the top edge of the lower one. +

+ +

+The weight (thickness) of double underscores may be controlled with +the macro +UNDERSCORE_WEIGHT +(q.v). +

+ +

+Note: +The same restrictions and caveats apply to UNDERSCORE2 as to +UNDERSCORE. See the +NOTES +for UNDERSCORE. +

+ + + +

Underline text — monospaced fonts only

+ +

+Macro: UNDERLINE toggle +

+ +

+If your font is monospaced, like Courier, or you’re using the +document processing macro +PRINTSTYLE TYPEWRITE, +UNDERLINE allows you to underline words and passages that, in +typeset copy, would be italicized. You invoke UNDERLINE as you do +with all toggle macros — by itself (i.e. with no argument) to +initiate underlining, and with any argument (OFF, QUIT, X, etc) to +turn underlining off. +

+ +

+When on, UNDERLINE underlines letters, words and numbers, but not +punctuation or spaces. This makes for more readable copy than a +solid underline. +

+ +

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

+ + + +

Inline escape for underlining — monospaced fonts only

+ +

+Inline: \*[UL]...\*[ULX] +

+ +

+If your font is a monospaced one, like Courier, or you’re +using the document processing macro +PRINTSTYLE TYPEWRITE, +\*[UL]...\*[ULX] underlines words and +passages that, in typeset copy, would be italicized. +

+ +

+\*[UL] underlines all letters, words and numbers +following it, but not punctuation or spaces. This makes for more +readable copy than a solid underline. When you no longer want +underlining, \*[ULX] turns underlining off. +

+ +

+The macro +UNDERLINE +and the inline escape \*[UL] are functionally +identical, hence +
+ + .FAM C + .FT R + .PT_SIZE 12 + .LS 24 + .SS 0 + .QUAD LEFT + Which should I heed? + .UNDERLINE + Just do it + .UNDERLINE OFF + or + .UNDERLINE + just say no? + .UNDERLINE OFF + +produces the same result as +
+ + .FAM C + .FT R + .PT_SIZE 12 + .LS 24 + .SS 0 + .QUAD LEFT + Which should I heed? \*[UL]Just do it\*[ULX] or \*[UL]just say no?\*[ULX] + +

+ + + +

Insert space into lines

+ +

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

+ +

+With PAD, you can insert 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]. +(Instead of \*[RULE], groff’s line +drawing function, +\l'<distance>' +could be used.) +
+ + .LL 30P + .PAD "Date \*[ST1]#\*[ST1X] Signature \*[ST2]###\*[ST2X]" NOBREAK + .ST 1 J + .ST 2 J + .TAB 1 + \*[RULE] + .TN + \*[RULE] + .TQ + +If you’re not a typesetter, and if you’re new to groff, +the example probably looks like gibberish. My apologies. However, +remember that typesetting is a craft, and without having studied the +craft, it takes a while to grasp its concepts. +

+ +

+Basically, what the example does is: +

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]" + .EL + .ST 1 J + .ST 2 J + .TAB 1 + \*[LEADER] + .TN + \*[LEADER] + .TQ + +

+ +

+The PAD line sets the words Date and Signature, and marks string +tabs around the pad space inserted in the line. The string tabs are +then "set", called, and filled with leaders. The result +looks like this: +
+ + Date.............Signature..................................... + +

+ + + +

Change/set the leader character

+ +

+Macro: LEADER_CHARACTER <character> +

+ +

+LEADER_CHARACTER takes one argument: a single character you would +like to be used for +leaders. +(See +\*[LEADER] +for an explanation of how to fill lines with leaders.) +

+ +

+For example, to change the leader character from mom’s +default (a period) to the underscore character, enter +
+ + .LEADER_CHARACTER _ + +

+ + + +

Drop caps

+ +

+Macro: DROPCAP <dropcap letter> <number of lines to drop> [ COND <percentage> | EXT <percentage> ] +

+ +

+The first two arguments to DROPCAP are the letter you want to be the +drop cap +and the number of lines you want it to drop. By default, mom uses +the current family and font for the drop cap. +

+ +

+The optional argument (COND or EXT) indicates +that you want the drop cap condensed (narrower) or extended (wider). +If you use COND or EXT, you must +follow the argument with the percentage of the letter’s normal +width you want it condensed or extended. No percent sign +(%) is required. +

+ +

+Mom will do her very best to get the drop cap to line up with the +first line of text indented beside it, then set the correct number +of indented lines, and restore your left margin when the number of +drop cap lines has been reached. +

+ +

+Beginning a paragraph with a drop cap “T” looks like this: +
+ + .DROPCAP T 3 COND 90 + he thousand injuries of Fortunato I had borne as best I + could, but when he ventured upon insult, I vowed revenge. + You who so well know the nature of my soul will not suppose, + however, that I gave utterance to a threat... + +

+ +

+The drop cap, slightly condensed but in the current family and font, +will be three lines tall, with whatever text fills those three +lines indented to the right of the letter. The remainder of the +paragraph’s text will revert to the left margin. +

+ +

+Note: +When using the +document processing macro +PP, +DROPCAP only works +

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

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

+ +

+Warning: +DROPCAP puts a bit of a strain on resource-challenged systems. If +you have such a system and use drop caps extensively in a document, +be prepared for a wait while mom does her thing. +

+ +

Support macros for DROPCAP

+Drop caps are the bane of most typesetters’ existence. +It’s very difficult to get the size of the drop cap right +for the number of drop lines, especially if the drop cap is in a +different family from the prevailing family of running text. Not +only that, but there’s the gutter around the drop cap to take +into account, plus the fact that the letter may be too wide or too +narrow to look anything but odd or misplaced. +

+ +

+Mom solves the last of these problems with the COND and +EXT arguments. The rest she solves with macros that +change the default behaviour of DROPCAP, namely +

DROPCAP_FAMILY
DROPCAP_FONT
DROPCAP_COLOR
DROPCAP_ADJUST
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. And sorry, there’s +no mom equivalent for subscripts. I'm neither a mathematician +nor a chemist, so I don’t need them. Of course, anyone who +wishes to contribute a subscript routine to mom will receive +blessings not only in this lifetime, but in all lifetimes to come. +

+ +

SUPERSCRIPT RAISE AMOUNT

+By default, mom raises superscripts 1/3 of an +em +above the baseline. If you’re not happy with this default, you can +change it by invoking SUPERSCRIPT_RAISE_AMOUNT with +the amount you want them raised. A +unit of measure +must be appended directly to the amount. Thus, you want +superscripts raised by 3 +points +instead of 1/3 em, you'd +do +
+ + .SUPERSCRIPT_RAISE_AMOUNT 3p + +and all subsequent superscripts would be raised by 3 points. +

+ +

+ + + + + + + + +

Next: Inline escapes

+ +

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

+ + + + + + + +

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 => Escape index => \D + +The escapes allow you to draw just about any simple graphical object +you can think of, but owing to their syntax, they’re not always easy +to read, which can make tweaking them difficult. Additionally, +while they perform in a consistent manner, they don’t +always perform in an expected manner. +

+ +

+Experience shows that the most common graphical elements typesetters +need are rules (horizontal and vertical), boxes, and circles (or +ellipses). For this reason, mom provides macros +to draw these objects in an easy-to-understand way; the results are +predictable, and mom’s syntax makes fixes or tweaks +painless. +

+ +

+For example, if you want to draw a 2-inch square outline box at the left +margin using groff’s \D escapes, it looks like this: +
+ + back up + by + weight + +-------+ + | | + \D't 500'\h'-500u'\D'p 2i 0 0 2i -2i 0 0 -2i' + | | | | + +-------+ +------------------------+ + set rule draw box, 1 line at a time + weight + + +Obviously, this isn’t very efficient for something as simple as a +box. +

+ +

+Here’s the same box, drawn with mom’s box drawing +macro, +DBX: +
+ + left margin indent--+ +--box width + | | + .DBX .5 0 2i 2i + | | + rule weight--+ +--box depth + (in points) + +

+ +

+Mom’s graphical object macros allow—in fact, +require—giving the rule weight (“thickness”) for +the object (or saying that you want it filled), an indent from the +left margin where the object begins, the dimensions of the object, +and optionally a colour for the object. +

+ +

+There are no defaults for the arguments to mom'a graphical object +macros, which means you must supply the arguments every time you +invoke them. +

+ +

+Note: +As stated above, mom only provides macros for commonly-used +graphical objects (rules, boxes, circles). 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 Weight of the rule +
- if the object is enclosed (i.e. is a box or circle), the + weight of the rule if you want the object outlined
- the single word, SOLID, may be used in place + of the weight argument if you want the + object filled
the Indent from the current left margin at + which to begin the object
the Length of the object, if applicable
the Depth of the object, if applicable
the Colour of the object (optional)

+ +

+A simple mnemonic for the order of arguments is “WILD +Card”. If you fix the mnemonic in your brain and apply +a little judicious reasoning, you’ll always remember how to +draw graphical objects. The “judicious reasoning” means +that, for example, horizontal rules don’t require a depth and +vertical rules don’t require a length. Thus, in the case of +drawing a horizontal rule, you supply the macro, +DRH, +with only the arguments (from the mnemonic) that apply: W-I-L (and +possibly C). +

+ +

Graphical objects macros

+ +

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

+ + + +

Drawing horizontal rules

+ +

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

+ +

+• The argument to <weight> is in +points, +but do NOT append the +unit of measure, +p. +
+• The arguments, <indent> and +<length>, require a unit of measure. +

+ +

+If all you want is to draw a rule from your current left +margin to your current right margin (in other words, a "full +measure" rule), you may invoke .DRH without any +arguments. +

+Note: +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 length, you must, at +a minimum, supply DRH with the arguments weight, +indent (measured from the current left margin) and +length. +

+ +

+Optionally, you may give a colour argument. The colour +may be either one defined with +NEWCOLOR, +or a named X-colour inititialized with +XCOLOR, +or an X-colour alias (again, initialized with XCOLOR). +

+ +

+Say, for example, you want to draw a 1-1/4 point horizontal rule +that starts 2 picas from the current left margin and runs for 3 +inches. To do so, you'd invoke .DRH like this: +
+ + weight length + | | + .DRH 1.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. +
+• The arguments, <indent> and +<depth>, require a unit of measure. +

+ +

+To draw vertical rules of a specified length, you must, at +a minimum, supply DRV with the arguments 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 centimeters. To do so, you'd invoke .DRV like this: +
+ + weight depth + | | + .DRV .75 19P+6p 6c + | + indent + +(Note that the rule weight argument, which is expressed in points, +must NOT have the unit of measure p appended to it.) +

+ +

+If, in addition, you want the rule red: +
+ + .DRV .75 19P+6p 6c red + +

+ +

How mom handles the positioning of vertical rules

+ +

+Vertical rules are drawn from the baseline down, and from left to +right. "Left to right" means that if you request a rule +with a weight of four points, the four points of rule fall entirely +to the left of the indent given to DRV. +

+ +

+Furthermore, after the rule is drawn, mom returns you to the current +left margin, at the same vertical position on the page as when DRV +was invoked. In other words, DRV causes no movement on the page, +either horizontal or vertical. +

+ + + +

Drawing boxes

+ +

+Macro: DBX < <weight> | SOLID > <indent> <length> <depth> [<colour>] +

+ +

+• The argument to <weight> is in +points, +but do NOT append the +unit of measure, +p. +
+• The arguments, <indent>, +<length> and +<depth>, require a unit of measure. +

+ +

+To draw boxes of specified dimensions, you must, at a minimum, +supply DBX with the arguments weight or SOLID, +indent (measured from the current left margin), +length and depth. +

+ +

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

+ +

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

+ +

How mom handles the positioning of boxes

+ +

+Boxes are drawn from the baseline down, from left to right, and +from the perimeter inward. “From the perimeter +inward” means that if you request a box weight of six points, +the 6-point rules used to draw the outline of the box fall entirely +within the dimensions of the box. +

+ +

+Furthermore, after the box is drawn, mom returns you to the current +left margin, at the same vertical position on the page as when DBX +was invoked. In other words, DBX causes no movement on the page, +either horizontal or vertical. +

+ + + +

Drawing circles (ellipses)

+ +

+Macro: DCL < <weight> | SOLID > <indent> <length> <depth> [<colour>] +

+ +

+• The argument to <weight> is in +points, +but do NOT append the +unit of measure, +p. +
+• The arguments, <indent>, +length and +<depth>, require a unit of measure. +

+ +

+To draw circles of specified dimensions, you must, at a minimum, +supply DCL with the arguments weight or SOLID, +indent (measured from the current left margin), +length and depth. +

+ +

+Say, for example, you want to draw a 1/2 point outline circle +(ellipse, actually, in this case) that starts one inch from the +current left margin and has the dimensions 6 centimeters x 3 +centimeters. To do so, you'd invoke .DCL like this: +
+ + indent depth + | | + .DCL .5 1i 6c 3c + | | + weight ength + +(Note that the box weight argument, which is expressed in points, +must NOT have the unit of measure p appended to it.) +

+ +

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

+ +

How mom handles the positioning of circles (ellipses)

+ +

+Circles (ellipses) are drawn from the baseline down, from left +to right, and from the perimeter inward. “From the +perimeter inward” means that if you request a circle weight of +six points, the 6-point rule used to draw the outline of the circle +or ellipse falls entirely within the dimensions of the +circle or ellipse. +

+ +

+Furthermore, after the circle is drawn, mom returns you to the +current left margin, at the same vertical position on the page as +when DCL was invoked. In other words, DCL causes no movement on the +page, either horizontal or vertical. +

+ +

+ + + + + + + + +

Next: Document processing

+ +

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

+ + + + + + + +

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 with +DOCTYPE. +You can, however, supply whatever strings you like—including +page numbers—to go in any part of headers. What’s more, +you can set the family, font, size, colour and capitalization style +(caps or caps/lower-case) for each header part individually. +

+ +

+By default, mom prints a horizontal rule beneath headers to separate +them visually from running text. In the case of footers, the rule +is above. You can increase or decrease the space between the header +and the rule if you like (with +HEADER_RULE_GAP), +or remove it completely. +

+ +

Default specs for headers/footers

+ +

+Mom makes small type adjustments to each part of the header (left, +centre, right) to achieve an aesthetically pleasing result. The +defaults are listed below. (The strings mom puts by default in each +part are explained in +DOCTYPE.) +

+ +

+Note: Except for capitalization (all caps or caps/lower-case), +these defaults apply only to +PRINTSTYLE TYPESET. +

+ +TYPE SPEC HEADER LEFT HEADER CENTER HEADER RIGHT +--------- ----------- ------------- ------------ +Family document default document default document default +Font roman italic roman +Colour (black) (black) (black) +All caps no no yes +Size* -.5 (points) -.5 (points) -2 (points) + (-2 if all caps) (-2 if all caps) (-.5 if not all caps) + +*Relative to the point size of type in paragraphs + +

+ +

+You can, of course, change any of the defaults using the appropriate +control macros. And should you wish to design headers from the +ground up, mom has a special macro, +HEADER_PLAIN, +that removes all type adjustments to headers. The straightforward +type specs for paragraphs are used instead, providing a simple +reference point for any alterations you want to make to the family, +font, size and capitalization style of any header part. +

+ +

Vertical placement and spacing of headers/footers

+ +

+As explained in the section, +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), +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 +(you can’t have both), but not the page numbers that normally +appear at the bottom of the page. +

+ +

+ADDITIONAL NOTE: If HEADERS +are OFF, mom’s normal top +margin for +running text +(7.5 +picas) +changes to 6 picas (visually approx. 1 inch). This does NOT apply +to the situation where footers have been explicitly turned on +(with +FOOTERS). +Explicitly invoking footers moves page numbering to the +top of the page, where its placement and spacing are the same as +for headers. (I.e. the top margin of running text remains 7.5 +picas.) +

+ + + +

Footers

+ +

+Macro: FOOTERS toggle +

+ +

+Page footers +are off by default. If you want them instead of +headers +(you can’t have both), turn them on by invoking +.FOOTERS without an argument, e.g. +
+ + .FOOTERS + +

+ +

+FOOTERS automatically disables headers, and +mom shifts the placement of page numbers from their +normal position at page bottom to the top of the page. +

+ +

+NOTE: By default, when footers are on, +mom does not print a page number on the first +page of a document, nor on first pages after +COLLATE. +If you don’t want this behaviour, you can change it with +PAGENUM_ON_FIRST_PAGE. +

+ + + +

+ +

+Macro: FOOTER_ON_FIRST_PAGE toggle +

+ +

+If you invoke +.FOOTERS, +mom, by default, does not print a footer on the +first page of the document. (The +docheader +on page 1 makes it redundant.) However, should you wish a footer on +page 1, invoke .FOOTER_ON_FIRST_PAGE without any argument. +

+ +

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_FAMILY – family for entire header
  - HEADER_SIZE – size for entire header
  - HEADER_PLAIN – disable default adjustments to header parts
  - 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
  - _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*[$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_FAMILY
HEADER_SIZE
HEADER_PLAIN
HEADER_COLOR

+ +

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

+ +

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

+ +

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

+ +

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

+ + + +

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

+ + + +

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> "<header-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 set flush left, +centered, or flush right. (You can also use the longer forms, +LEFT, CENTER and RIGHT.) The +string you give afterwards is whatever text you want, including +mom’s +reserved strings, +and whatever +inline escapes +you need to change things like family and font, pointsize, colour, +etc. as you go along. +

+ +

+Note the backslashes in the invocation, above. Every set of +arguments given this way to HEADERS_AND_FOOTERS except the +last 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 – applies only when footers are enabled
DRAFT_WITH_PAGENUMBER – attach draft/revision information to page numbers
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. +

+ + + +

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

+ +

+ +.PAGENUM_FAMILY default = prevailing document family; default is Times Roman +.PAGENUM_FONT default = roman +.PAGENUM_SIZE default = 0 (i.e. same size as paragraph text) +.PAGENUM_COLOR default = black + +

+ +

2. Page number position

+ +

+Macro: PAGENUM_POS TOP | BOTTOM LEFT | CENTER | RIGHT +

+ +

+Use PAGENUM_POS to change the default position of automatic page +numbering. PAGENUM_POS requires two arguments: a vertical +position (TOP or BOTTOM) and a horizontal +position (LEFT or CENTER or RIGHT). +

+ +

+For example, if you turn both +headers +and +footers +off (with .HEADERS OFF and +.FOOTERS OFF) and you want mom to number your pages +at the top right position, enter +
+ + .PAGENUM_POS TOP RIGHT + +

+ +

3. Enclose page numbers with hyphens (on or off)

+ +

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

+ +

+This one does exactly what you’d expect—inserts a blank +page into the document. Unless you give the optional argument, +NULL, mom silently increments the page number of every +blank page and keeps track of +recto/verso +stuff, but otherwise does nothing. It’s up to you, the user, +to figure out what to do with this feature. However, it’s +worth noting that without it, inserting completely blank pages, +to use a vernacular Québécois phrase, c'est pas +évident. (Somewhere between it isn’t easy, it +isn’t obvious and it isn’t fun). +

+ +

+The required argument to BLANK_PAGE is the number of blank pages to +insert. The argument is not optional, hence even if you only want +one blank page, you have to tell mom: +
+ + .BLANKPAGE 1 + +The optional argument, NULL, allows you to output the +specified number of pages without mom incrementing the page number +for each blank page. She will, however, continue to keep track +of which pages are recto/verso if recto/verso printing has been +enabled. +

+ +

+ + + + + + + + +

Next: Recto/verso printing, collating

+ +

+ + + + diff --git a/contrib/mom/momdoc/images.html b/contrib/mom/momdoc/images.html new file mode 100644 index 00000000..e3af015f --- /dev/null +++ b/contrib/mom/momdoc/images.html @@ -0,0 +1,136 @@ + + + + + + + + Mom -- Inserting images into mom documents + + + + + + + +

+ + + + + + + +

Next: Page headers/footers, pagination

+ +

Inserting images into a document

+ +

+You can insert images into a document by using the PSPIC +macro. PSPIC isn’t actually part of mom; it comes packaged +with groff itself. Images must be in PostScript format, either +straight .ps or .eps (Encapsulated PostScript). If you have the +ImageMagick suite of programmes installed on your system, a simple way +to convert most image formats to .eps is with convert, at +the command line, as in this jpg => eps example: +
+ + convert <filename>.jpg <filename>.eps + +There have been reports of trouble with PostScript level 2 images, +so don’t save your images in this format. +

+ + + +

PSPIC

+ +

+Macro: PSPIC [ -L | -R | -I <n> ] <file> [ width [ height ] ] +

+ +

+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 centered. The -L and +-R options cause the graphic to be left-aligned and +right-aligned, respectively. The -I option causes +the graphic to be indented by <n>; the default unit of +measure is m +(ems). +

+ +

+Unless you’re a PostScript whiz and have futzed around with +bounding boxes and whatnot, it’s unlikely that your image will +occupy an easily predictable and precise amount of space on the +page. This is particularly significant when it comes to the amount +of vertical space occupied by the image. A certain amount of +manual tweaking of the vertical placement of the image will +probably be required, via the +ALD +and +RLD +macros. +

+ +

+Additionally, images inserted into +running text +will almost certainly disrupt the baseline placement of running +text. In order to get mom back on track after +invoking .PSPIC, I strongly recommend using the +SHIM +macro so that the bottom margin of running text falls where it +should. +

+ +

+ + + + + + + + +

Next: Page headers/footers, pagination

+ +

+ + + + diff --git a/contrib/mom/momdoc/inlines.html b/contrib/mom/momdoc/inlines.html new file mode 100644 index 00000000..1349abcb --- /dev/null +++ b/contrib/mom/momdoc/inlines.html @@ -0,0 +1,1076 @@ + + + + + + + Mom -- Inline escapes + + + + + + + +

+ + + + + + + +

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 the left, centre and/or right strings, or in the strings +for +recto +and/or +verso +HEADERS or FOOTERS, or in the strings passed to +HEADERS_AND_FOOTERS, +you must enter the inlines beginning with \E* +rather than just \*, e.g. \E*[BD]. +

+ + + +

Changing point size

+Mom has two inline escapes for changing point size: +
+ + \*[SIZE <size>] + +and +
+ + \*S[<size>] + +where “size” is the new size you want. You can use +either; they behave exactly the same way. For example, to change +the point size of type inline to 12 points, you could enter either +
+ + \*[SIZE 12] + +or +
+ + \*S[12] + +

+ +

+The advantage of the first form is that it’s easy to remember, +and follows mom’s usual inline syntax. The advantage of the +second is that it’s more concise. +

+ +

+Notice that in both cases, the new size does not require a +unit of measure; +points +is assumed. However, a unit of measure may be appended to the size +if that’s what you wish. Fractional sizes are, of course, +allowed. +

+ +

+The size given to \*[SIZE <size>] or +\*S[<size>] may be expressed in plus or minus +terms, which can be very useful. In the following examples, the +word “mom” will be output 2 points larger than the point +size of the rest of the line. +
+ + While she isn't perfect, \*S[+2]mom\*S[-2] isn't half bad. + While she isn't perfect, \*[SIZE +2]mom\*[SIZE -2] isn't half bad. + +

+ +

NOTE CONCERNING DOCUMENT PROCESSING

+If you’re using the +document processing macros +and wish to design your own +HEADERS or FOOTERS +using mom’s inline escape for changing point size 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). +

+ +

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

+ + + +

Vertical inline movement

+If you need to move portions of type up or down on a line, mom +provides the following inline escapes: +
+ + \*[DOWN <n unit>] Move down inline the specified number of + units of measure + + \*[UP <n unit>] Move up inline the specified number of + units of measure + +For example, +
+ + Tel: 905\*[UP 1p]-\*[DOWN 1p]4072 + +moves the hyphen in the telephone number up by 1 point, then +moves back down by the same amount. +

+ +

+Note: +\*[UP] and \*[DOWN] do not work 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]. +

+ + + +

Terminate a line without advancing on the page

+Sometimes, you want mom to break a line but not advance on the page. +See +here +for an example of when you might want to do this. +

+ +

+In versions of mom prior to 1.2-f, this was accomplished through the +use of the +EL +macro. As of 1.2-f, you can, if you prefer, accomplish the same +thing by using the inline escape, \*[B]. Simply attach +the escape to the end of any input line. Using the example given in +the document entry for EL, you'd use \*[B] like this: +
+ + .LEFT + .LS 12.5 + A line of text.\*[B] + .ALD 24p + The next line of text. + + +\*[B] works reliably regardless of the current +fill mode. +

+ + + +

Call the next sequential tab without advancing on the page

+Sometimes, you want mom to move to the next tab in sequence (e.g. +from TAB 1 to TAB 2, or TAB 8 to TAB 9) without mom advancing on the +page. (See the NOTE +here +if you’re not clear how mom manages tabs and linebreaks.) +

+ +

+In versions of mom prior to 1.2-f, this was accomplished through the +use of +TN. +As of 1.2-f, you can, if you prefer, accomplish the same thing by +using the inline escape, \*[TB+]. Simply attach the +escape to the end of any input line in a tab, like this: +
+ + .TAB 1 + Some text\*[TB+] \" This line is in tab 1 + Some more text \" This line is in tab 2, on the same baseline as tab 1 + + +\*[TB+] works reliably regardless of the current +fill mode. +

+ + + +

Full measure rules

+I find I often need rules drawn to the full measure of the current line +or tab length. The official way to do this is \l'\n[.lu]', +which is annoying to type, and doesn’t mean a whole heck of a lot if +you’re new to groff. The inline, \*[RULE], is a simple +replacement for \l'\n[.lu]'. Use it whenever you need +a rule drawn to the full measure of the current line or tab length, for +example: +
+ + .LL 6P + \*[RULE] + + +The above draws a rule the full measure of the 6-pica line length. +For another way to draw full measure rules, see the macro, +DRH. +

+ +

+\*[RULE] must appear on an +input line +by itself, and always causes a break when entered after a normal +input line of text. It does not, however, deposit a break when used +immediately after a macro. +

+ +

+The weight of the rule drawn with \*[RULE] is controlled +with the macro +RULE_WEIGHT. +Mom’s default is 1/2 point. +

+ +

+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[<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 +\*[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 affects ONLY type on the +current +output line. +When groff breaks the output line, the effect of +\v is cancelled; the baseline of the next output line +is where it would be if you hadn’t used \v. +

+ +

+Tip: +When using \v for occasional effects 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 string is composed of several words separated +by spaces, you MUST surround the whole escape with double quotes, +as in the example above. +

+ + + +

Horizontal line drawing function (`\l`)

+ +

+The \l'distance' inline allows you to draw a horizontal +rule of the specified distance. You must supply a +unit of measure. +Therefore, to set a 3-pica rule into a line of text, you'd do +
+ + A line of text with a superfluous \l'3P' 3-pica rule in it. + +\l'3P', above, not only draws the rule, but advances 3 +picas horizontally as well, just as you'd expect. +

+ +

+For an easy way of drawing rules to the full measure of the current +line or tab length, see +Full measure rules. +

+ +

+The weight (thickness) of rules varies according to the point +size in effect when you invoke \l, but you can’t fix +the weight with any real precision. A point size of 12 produces +a tastefully moderate rule weight of between one-half and one +point (depending on your printer). +

+ +

+Note: +Besides \l, groff provides a number of more +sophisticated “drawing” escapes. It is well beyond +the scope of this documentation to demonstrate their usage; see +
+ + info groff => Escape index => \D + +for directions concerning their use. The drawing escapes can be a +bit unwieldy, so mom provides “user-friendly” macros for +the +graphical objects +most commonly enountered in typesetting: horizontal and vertical +rules, boxes, and circles (ellipses). +

+ +

+Additionally, groff comes with two “preprocessors” that +let you create ruled tables and vector diagrams (line drawings): +tbl and pic. The documentation for tbl can be +downloaded from +
+ http://cm.bell-labs.com/cm/cs/doc/76/tbl.ps.gz +
+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 .PSPIC (consult +man groff-tmac for information on this indispensable and +easy-to-use macro). +

+ + + +

Special characters and symbols

+Here follows a short list of commonly-used special characters +available via inline escapes. If you’re not sure of the +meaning of some of these characters, consult the +Definitions of Terms. +

+ +

+For a complete list of special characters and glyphs (i.e. just +about anything you'd ever want to appear on the printed page, +including mathematical symbols, accented characters, unusual +ligatures and letters unique to various European languages), consult +man groff-char. +

+ + + CHARACTER ESCAPE SEQUENCE + --------- --------------- + Comment line \# or .\" + Fixed-width space \<space> (ie backslash followed by a space) + Unbreakable space \~ + Digit-width (figure) space \0 + Zero-width character \& + Discretionary hyphen \% + Backslash \\ or \e + Plus/minus (arithmetic) \(+- + Subtract (arithmetic) \(mi + Multiply (arithmetic) \(mu + Divide (arithmetic) \(di + Em-dash \(em + En-dash \(en + Left double-quote \(lq + Right double-quote \(rq + Bullet \(bu + Ballot box \(sq + One-quarter \(14 + One-half \(12 + Three-quarters \(34 + Degree sign \(de + Dagger \(dg + Foot mark \(fm + Cent sign \(ct + Registered trademark \(rg + Copyright \(co + Section symbol \(se + +
+ +

+ + + + + + + + +

Next: Coloured text

+ +

+ + + + diff --git a/contrib/mom/momdoc/intro.html b/contrib/mom/momdoc/intro.html new file mode 100644 index 00000000..34dd571c --- /dev/null +++ b/contrib/mom/momdoc/intro.html @@ -0,0 +1,526 @@ + + + + + + + + What is mom? + + + + + + + +

+ + + + + + + +

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 for PostScript output. +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 by groff’s terse, geeky, + not-always-typographically-intuitive + primitives; +
Non-scientific writers (novelists, short story writers, + journalists, students) who just want their work to + look good; +
Newbies to computer typesetting, document processing or + groff who need a well-documented macro set to help them get + started. +

+ +

+As might be inferred from the above, mom is two macro packages in +one: a set of typesetting macros, and a set of document formatting +macros. The typesetting macros govern the physical aspects +of page layout and provide sane, comprehensible control over +typographic refinements. The document formatting macros let you +focus on a document’s content and logical structure without +worrying about typesetting or page layout at all. +

+ +

+Because mom provides both typesetting and document formatting +macros, it’s safe to say she blurs the distinction +between document processing and document design. While +her basic document style come with pretty spiffy defaults +(okay—change “spiffy” to “typographically +professional”), you can easily control how all the various +document elements look: titles, page headers and footers, page +numbering, heads, subheads, footnotes and so on can be made to +come out exactly the way you want. And should you need precise +typographic control over elements in a document that fall outside +the range of mom’s document element tags, you don’t +have to read up on groff +primitives +in order to accomplish what you want; the typesetting macros take +care of that. +

+ +

Typesetting with mom

+ +

+Mom’s typesetting macros control the basic parameters +of type: margins, line length, type family, font, point size, +linespacing, and so on. In addition, they allow you to move +around on the page horizontally and vertically, and to set up +tabs, indents, and columns. Finally, they let you adjust such +typographic details as justification style, letter spacing, word +spacing, hyphenation, and kerning. +

+ +

+In terms of typographic control, these macros resemble +the commands used on dedicated typesetting computers like +Compugraphics and Linotronics. Most of them simply give access +to groff’s typesetting primitives in a way that’s +consistent and easy to use. A few of them (tabs and indents, +for example) handle fundamental typesetting requirements in ways +radically different from groff primitives. +

+ +

+With mom’s typesetting macros, you can, if you wish, create +individual output pages that you design from the ground up. +Provided you have not signalled to mom that you want document +processing (via the +START +macro; see below), every macro is a literal command that remains +in effect until you modify it or turn it off. This means that if +you want to create flyers, surveys, tabulated forms, curricula +vitae and so on, you may do so in the good old-fashioned way: one +step at a time with complete control over every element on the +page. +

+ +

+Years of reading various mailing lists dealing with computer +typesetting (groff, TeX, and friends) have convinced me that no +program can ever replace the human eye and human input when it +comes to high quality typesetting. As of this writing, a thread +on the subject of “micro typography” in groff has been +going on for nearly a month. The reason for the lengthy thread +is obvious; words and punctuation on the printed page are too +variable, too fluid, to be rendered flawlessly by any algorithm, +no matter how clever. (For whatever it’s worth, a similar +problem exists with engraving musical scores by computer.) +

+ +

+Mom does not try to solve the problems posed by things like +hanging punctuation, left-margin adjustments for upper case +letters like T and W, and so on. She merely tries to provide +tools that allow knowledgeable typesetters to come up with +solutions to these problems in ways that are easier and more +intuitive than manipulating groff at the +primitive +level. As a professional typesetter of more than two decades, and +a writer, I have encountered few situations that cannot be handled +by mom’s typesetting macros. +

+ +

+Author’s note: One area where groff itself needs serious +rethinking is in the matter of an algorithm that takes into +account both word and letter spacing when +justifying +lines. At present, only word spacing is adjusted, requiring what +I consider an unnecessary amount of user intervention whenever +letter spacing is required. +

+ +

Document processing with mom

+ +

+Mom’s document processing macros let you format documents +without having to worry about the typographic details. In this +respect, mom is similar to other groff macro packages, as well as +to html and LaTeX. Where mom differs is in the degree of control +you have over the look and placement of the various elements of +a document. For example, if you don’t want your heads +underlined, or you want them bigger/smaller, or you’d prefer +them to be in a different font, or you’d rather they were +flush left instead of centred, you can make the changes easily +and have them apply to the whole document. Temporary and one-off +changes are easy, too. +

+ +

+Mom has some nifty features other macro sets don’t provide. +For example, you can switch between draft-style and final-copy +output. If you regularly make submissions to publishers and +editors who insist on "typewritten, double-spaced," there’s +a special macro— +PRINTSTYLE TYPEWRITE— +that changes typeset documents into ones that would make your +high-school typing teacher proud. Footnotes, endnotes, tables of +contents, multiple columns, nested lists, recto/verso printing and +user designable headers and footers are also part of the fun. +

+ +

Mom’s philosophy

+ +

+Formatting documents should be easy, from soup to nuts. Writers +need to focus on what they’re writing, not on how it looks. +From the moment you fire up an editor to the moment you add +"FINIS" to your opus, nothing should interfere with the flow of +your words. The commands needed to format your work should be +easy to remember, comprehensible, and stand out well from the +text. There shouldn’t be too much clutter. Your documents +should be as readable inside a text editor as they are on the +printed page. +

+ +

+Unfortunately, in computerland, “easy,” +“comprehensible,” and “readable” often +mean “you’re stuck with what you get.” No +document formatting system can give you exactly what you want all +the time, every time. Documents, it seems, always need to be +tweaked, either to satisfy a typographic whim or to clarify some +aspect of their content. +

+ +

+Groff has traditionally solved the problem of formatting vs. +tweaking by requiring users of the common macro packages (mm, ms, +me and their offspring) to resort to groff +primitives +and +inline escapes +for their special typesetting needs. Not to put too fine a +point on it, groff primitives tend toward the abstruse, and most +inline escapes are about as readable in-line as an encrypted +password. This does not make for happy-camper writers, who either +find themselves stuck with a document formatting style they +don’t really like, or are forced to learn groff from the +ground up—a daunting task, to say the least. +

+ +

+Mom aims to make creating documents a simple matter, but with +no corresponding loss of user control. The document processing +macros provide an excellent set of defaults, but if something is +not to your liking, you can change it. And in combination with +the typesetting macros, you have all the tools you need to massage +passages and tweak pages until they look utterly professional. +

+ +

+One rarely hears the 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, typographically and +structurally, easier to decipher. +

+ +

+Mom does not try to be all things to all people. In contrast to +the normal groff philosophy, she does not try to produce output +that looks good no matter where it’s displayed. She’s +designed for printed output, although with +PRINTSTYLE TYPEWRITE +she produces acceptable terminal copy. She makes no attempt to be +compatible with older versions of troff. +

+ +

+One special feature in mom’s design is the attention she +pays to aligning the bottom margins of every page. Nothing +screams shoddy in typeset documents louder than bottom margins +that wander, or, in typesetter jargon, “hang.” There +are, of course, situations where whitespace at the bottom of a +page may be desirable (for example, you wouldn’t want a head +to appear at the bottom of the page without some text underneath +it), but in all cases where hanging bottom margins can be avoided, +mom does avoid them, by clever adjustments to leading (“line +spacing”) and the spacing between different elements on the +page. +

+ +

A note on mom’s documentation

+ +

+Writing documentation is tough, no doubt about it. One is never +quite sure of the user’s level of expertise. Is s/he new +to the application, new to its underlying protocols and programs, +new to the operating system, new to computers? At some point, one +has to decide whom the documentation is for. Making the wrong +decision can mean the difference between a program that gets used +and a program that gets tossed. +

+ +

+Mom’s documentation assumes users know their way around +their own operating system (basic file management, how to invoke +commands, how to use a text editor, etc). I use GNU/Linux, +and while the documentation may exhibit a GNU/Linux bias, mom +and groff can, in fact, be used on a variety of other popular +operating systems, including the one from Redmond, Virginia, USA. +

+ +

+The documentation further assumes they at least know what groff +is, even if they don’t know much about it. Lastly, +it assumes that everyone—groff newbies and experts +alike—learns faster from a few well-placed examples than +from manpage-style reference docs. What mom’s documentation +doesn’t assume is that you know everything—not about +groff, not about typesetting, not about document processing. Even +experts have odd lacunae in their knowledge base. Therefore, +whenever I suspect that a term or procedure will cause head +scratching, I offer an explanation. And when explanations +aren’t enough, I offer examples. +

+ +

Canonical reference materials

+ +

+The canonical reference materials for groff are +cstr54 (a downloadable PostScript copy of which +is available +here) +and the troff and groff_diff +manpages. Another excellent source of information (maybe the best) +is the groff info pages, available by typing +info groff +at the command line (assuming you have the TeXinfo standalone +browser installed on your system, which is standard for most +GNU/Linux distributions). And for inputting special characters, +see man groff_char. +

+ +

+I’ve tried to avoid reiterating the information contained +in these documents; however, in a few places, this has proved +impossible. But be forewarned: I have no qualms about +sidestepping excruciating completeness concerning groff usage; +I’m more interested in getting mom users up and running. +Mea culpa. +

+ +

+Note: Mom’s macro file (om.tmac) is heavily +commented. Each macro is preceded by a description of its +arguments, function and usage, which may give you information in +addition to what’s contained in this documentation. +

+ +

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

+ +

How to read macro arguments

+ +

+The concise descriptions of macros in this documentation typically +look like this: +

+ +

+Macro: 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> 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... Hell, it +could even be I_love_mom. +

+ +

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

+ + + + + + + + +

Next: Definitions

+ +

+ + + + diff --git a/contrib/mom/momdoc/letters.html b/contrib/mom/momdoc/letters.html new file mode 100644 index 00000000..95a2e709 --- /dev/null +++ b/contrib/mom/momdoc/letters.html @@ -0,0 +1,567 @@ + + + + + + + + Mom -- Writing letters + + + + + + + +

+ + + + + + + +

Next: Quick reference guide

+ +

Writing letters

+ +

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

+ +

+After the START macro, you enter headers pertinent to your letter: +the date, the addressee (in business correspondence, typically both +name and address), the addresser (that’s you; in business +correspondence, typically both name and address), and a greeting +(in full, e.g. “Dear Mr. Smith,” or “Dear +Mr. Smith:”). +

+ +

+The macros for entering the headers are simple (they’re not even +toggles): +
+ + .DATE + .TO + .FROM + .GREETING + +You may enter them in any order you like, except for GREETING, which +must come last. Mom ignores any headers you omit and spaces the +letter’s opening according to what you do include. See +Default for letters +to find out how mom formats the headers. +

+ +

+(In pre 1.1.7-a releases of mom, the order of entering headers was +fixed at the above. This has been changed, although if you do +follow the above order, mom will continue to behave exactly as she +did in pre 1.1.7-a.) +

+ +

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

+ +

Mom’s 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. +

+ +

+ + + + + + + + +

Next: Quick reference guide

+ +

+ + + + diff --git a/contrib/mom/momdoc/macrolist.html b/contrib/mom/momdoc/macrolist.html new file mode 100644 index 00000000..c320d158 --- /dev/null +++ b/contrib/mom/momdoc/macrolist.html @@ -0,0 +1,1280 @@ + + + + + + + + Mom -- Quick reference guide + + + + + + + +

+ + + + + + + +

Document/section identification control

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
Utilities
Graphical Objects

DOCUMENT PROCESSING MACROS

Reference macros
General document formatting directives
Line numbering
Set documents in columns
TYPEWRITE control macros
Initiate document processing

Epigraphs
Main heads
Subheads
Paragraph heads
Reference macros
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
Bibliographic references
Tables of contents
Letter (correspondence) macros
Changing global print style parameters after
START
Managing a document’s first-page header
(the “docheader”)
Managing page headers and footers
Recto/verso page headers and footers
Pagination
Document and section cover (title) pages
Utilities

+ +

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]	-- off pseudo italic inline
Pseudo bold
SETBOLDER	-- set the amount of emboldening
\*[BOLDER]	-- invoke pseudo bold inline
\*[BOLDERX]	-- off pseudo bold inline
Pseudo condensed
CONDENSE	-- set the amount to pseudo condense
\*[COND]	-- invoke pseudo condensing inline
\*[CONDX]	-- off pseudo condensing inlines
Pseudo extended
EXTEND	-- set the amount to pseudo extend
\*[EXT]	-- invoke pseudo extending inline
\*[EXTX]	-- off pseudo condensing inlinee

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

+++ Linespacing (leading)
LS	-- set the linespacing (leading)
AUTOLEAD	-- set the linespacing relative to the point size

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

+++ Justification, quad direction, line-by-line setting, breaking lines
JUSTIFY	-- justify text to both margins
QUAD	-- "justify" text left, centre, or right
LEFT	-- set line-by-line quad left
CENTER	-- set line-by-line quad centre
RIGHT	-- set line-by-line quad right
BR	-- break a justified line
SPREAD	-- force justify a line
EL	-- break a line without advancing on the page

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

+++ Hyphenation
HY	-- automatic hyphenation on or off
HY_SET	-- set automatic hyphenation parameters

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

+++ Word and sentence spacing
WS	-- set the minimum word space size
SS	-- set the sentence space size

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

+++ Kerning, ligatures, smartquotes
KERN	-- automatic character pair kerning on or off
\*[BU n]	-- move characters pairs closer together inline
\*[FU n]	-- move character pairs further apart inline
RW	-- uniformly reduce space between characters (tighten)
EW	-- uniformly increase space between characters (loosen)
BR_AT_LINE_KERN	-- break previous line every time RW or EW is invoked
LIGATURES	-- automatic generation of ligatures on or off
SMARTQUOTES	-- smartquoting on or off

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

+++ Horizontal and vertical movements, columnar setting
ALD	-- move downards on the page
RLD	-- move upwards on the page
SPACE	-- insert space between lines on a page
\*[DOWN n]	-- temporarily move downwards in a line
\*[UP n]	-- temporarily move upwards in a line
\*[FWD n]	-- move forward in a line
\*[BCK n]	-- move backwards in a line
MCO	-- 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
\[STn]...\[STnX]	-- string tabs (mark tab positions inline)
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]...\[ULX]	-- invoke underling inline (fixed width fonts only)

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

+++ Superscipts
\[SUP]...\[SUPX]	-- superscript (inline)
\[CONDSUP]...\[CONDSUPX]	-- pseudo-condensed superscript (inline)
\[EXTSUP]...\[EXTSUPX]	-- pseudo extended supercript (inline)
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	-- space to leave for digits in a digit-enumerated list

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

+++ Colour
NEWCOLOR	-- initialize (define) a colour
COLOR	-- begin using an initialized colour
XCOLOR	-- initialize a "named" X colour
\*[<colorname>]	-- 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

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

+++ Utilities
ALIAS	-- give a macro a new name
CAPS	-- set type all caps
COMMENT	-- silently embed comments in a document
ESC_CHAR	-- change the default escape character
\*[LEADER]	-- insert leaders at the end of a line
LEADER_CHARACTER	-- change the character used for leaders
NEWPAGE	-- break to a new page
PAD	-- insert equalized regions of whitespace into a line
PAD_MARKER	-- change the pad marker
\*[RULE]	-- draw a full measure rule
SIZESPECS	-- get font's cap-height, x-height and descender depth
SILENT	-- output processing off or on
TRAP	-- enable or disable page position traps

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

+++ Graphical objects
DRH	-- draw a horizontal rule
DRV	-- draw a vertical rule
DBX	-- draw a box
DCL	-- draw a circle (ellipse)
RULE_WEIGHT	-- set weight of rules drawn with \*[RULE]
PSPIC	-- insert a PostScript image

+ +

DOCUMENT PROCESSING MACROS

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

+++ Reference macros
TITLE	-- document title
DOCTITLE	-- overall document title (if different from TITLE)
ENDNOTE_TITLE	-- document/chapter identification string for endnotes
CHAPTER	-- chapter number
CHAPTER_TITLE	-- chapter title
CHAPTER_STRING	-- what to use in place of “Chapter”
SUBTITLE	-- document subtitle
AUTHOR	-- document author(s)
DOC_COVERTITLE	-- document title cover
COVERTITLE	-- section cover title
COPYRIGHT	-- copyright
MISC	-- miscellaneous cover information
DRAFT	-- document’s draft number
DRAFT_STRING	-- what to use in place of “Draft”
REVISION	-- document’s revision number
REVISION_STRING	-- what to use in place of “Revision”

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

+++ General document formatting directives
DOCTYPE	-- general document type
COPYSTYLE	-- draft or final copy
PRINTSTYLE	-- typeset or “typewritten”

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

+++ Line numbering
NUMBER_LINES	-- automatic line numbering on or off
Control macros
NUMBER_QUOTE_LINES	-- numbering of QUOTE lines on or off
NUMBER_BLOCKQUOTE_LINES	-- numbering of BLOCKQUOTE lines on or off

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

+++ Set documents in columns
COLUMNS
COL_NEXT
COL_BREAK

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

+++ TYPEWRITE control macros
UNDERLINE_ITALIC	-- underlining of italics on
UNDERLINE_QUOTES	-- underlining of QUOTEs on or 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

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

+++ Main heads
HEAD	-- set a main head
Control macros	-- change default style of heads
HEAD_SPACE	-- control vertical space around heads
NUMBER_HEADS	-- number heads
PREFIX_CHAPTER_NUMBER	-- prefix chapter number to head numbers
RESET_HEAD_NUMBER	-- reset head number to "1"

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

+++ Subheads
SUBHEAD	-- set a subhead
Control macros	-- change default style of subheads
NUMBER_SUBHEADS	-- number subheads
PREFIX_CHAPTER_NUMBER	-- prefix chapter number to subhead numbers
RESET_SUBHEAD_NUMBER	-- reset subhead number to "1"

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

+++ Paragraph heads
PARAHEAD	-- set a paragraph head
Control macros	-- change default style of paraheads
NUMBER_PARAHEADS	-- number paraheads
PREFIX_CHAPTER_NUMBER	-- prefix chapter number to parahead numbers
RESET_PARAHEAD_NUMBER	-- reset parahead number to "1"

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

+++ 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 or off
PARA_SPACE	-- linespace between paragraphs on or 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
BREAK_QUOTE	-- deprecated

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

+++ Blockquotes (cited passages of text)
BLOCKQUOTE	-- set longer passages of cited text
Control macros	-- change default style of blockquotes
ALWAYS_FULLSPACE_BLOCKQUOTES	-- control vertical space around quotes
BREAK_BLOCKQUOTE	-- deprecated

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

+++ 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 (e.g. --END--)
Control macros	-- change default style finis string
FINIS_STRING	-- set the document termination string
FINIS_COLOR	-- set the document termination string colour

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

+++ Footnotes
FOOTNOTE	-- set a footnote
Control macros	-- change default style of footnotes
FOOTNOTE_MARKERS	-- footnote markers on or off
FOOTNOTE_MARKER_STYLE	-- type of footnote marker to use
RESET_FOOTNOTE_NUMBER	-- reset footnote numbering
FOOTNOTE_RULE	-- footnote separator rule on or off
FOOTNOTE_RULE_ADJ	-- adjust vertical position of footnote rule
FOOTNOTE_RULE_LENGTH	-- adjust length of footnote rule
FOOTNOTES_RUN_ON	-- instruct footnotes to be continuous (i.e. not to + begin on a new line; only for use with footnotes + identified by document line number)

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

+++ Endnotes
ENDNOTE	-- set an endnote
\*[EN-MARK]	-- mark initial line of a range of line numbers + (for use with line numbered endnotes)
ENDNOTES	-- output endnotes
Control macros	-- change just about anything to do with endnotes

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

General style control

Pagination

Header/footer control

Title 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 mbedded references
BIBLIOGRAPHY	-- output a bibliography
Control macros	-- change just about anything to do with bibliographies

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

BIBLIOGRAPHY_TYPE -- "plain" or enumerated list

General style control

Header/footer control

Main head control

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

+++ Tables of contents
TOC	-- output a table of contents
Control macros	-- change just about anything to do with tables of contents

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

General style control

Page numbering

Title control

Changing the style of the different table of contents entry types

Additional table of contents control macros

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

+++ Letter (correspondence) macros
DATE	-- letter’s date
FROM	-- letter’s addresser
TO	-- letter’s addressee
GREETING	-- letter’s salutation
CLOSING	-- letter’s closing salutation
CLOSING_INDENT	-- indentation of the closing salutation
SIGNATURE_SPACE	-- room to leave for the signature
NO_SUITE	-- printing of "next page number" off or on

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

+++ Changing global print style parameters after START
DOC_LEFT_MARGIN	-- left margin of everything on the page
DOC_RIGHT_MARGIN	-- right margin of everything on the page
DOC_LINE_LENGTH	-- document’s base line length
DOC_FAMILY	-- document’s base family
DOC_PT_SIZE	-- document’s base point size
DOC_LEAD	-- document’s base lead
DOC_QUAD	-- document’s base quad directions

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

+++ Managing a document’s first-page header
DOCHEADER	-- document first-page header on or off
Control macros	-- change default style of docheader elements

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

+++ Managing page headers and footers
HEADERS	-- page headers on or off
FOOTERS	-- page footers on or off
HEADERS_AND_FOOTERS	-- enable generation of both headers and footers
Control macros

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

Strings	-- left-right-center strings
Style	-- change style defaults for headers and/or footers
Global	-- global style changes
Part-by-part	-- part-by-part style changes
Vertical placement	-- adjust postion 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 or off
SWITCH_HEADERS	-- switch recto or verso header
SWITCH_FOOTERS	-- switch recto or verso footer
HEADER_RECTO	-- string that constitutes a recto header
HEADER_VERSO	-- string that constitutes a verso header
FOOTER_RECTO	-- string that constitutes a recto footer
FOOTER_VERSO	-- string that constitutes a recto footer

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

+++ Pagination
PAGINATE	-- pagination on or off
Control macros	-- change default style for pagination
PAGENUMBER	-- user-defined (starting) page number
PAGENUM_STYLE	-- digits, roman numerals, etc
PAGENUM_ON_FIRST_PAGE	-- when footers are enabled
DRAFT_WITH_PAGENUMBER	-- attach draft/revision information to page + numbers

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

+++ Document and section cover (title) pages
COVER	-- information to include in a section cover
DOC_COVER	-- information to include in a document cover
COVERS	-- printing of section covers on or off
DOC_COVERS	-- printing of document covers on or off
Control macros	-- change style defaults for covers

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

+++ Utilities
ADD_SPACE	-- add space to the top of a page
BLANKPAGE	-- output one or more blank pages
DOC_LEAD_ADJUST	-- adjust document linespacing (lead) to fill pages
COLLATE	-- join documents or chapters of a document together
SHIM	-- move vertical position to next valid baseline

+ +

+ + + + + + + + +

Next: Appendices

+ +

+ + + + diff --git a/contrib/mom/momdoc/rectoverso.html b/contrib/mom/momdoc/rectoverso.html new file mode 100644 index 00000000..1fbd1460 --- /dev/null +++ b/contrib/mom/momdoc/rectoverso.html @@ -0,0 +1,339 @@ + + + + + + + + Mom -- Recto/verso printing, collating + + + + + + + +

+ + + + + + + +

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)

+ +

+It is beyond the scope of this documentation to cover the different +ways in which you can make your printer print on both sides of +a sheet. A simple but effective method for those of us with +“dumb” printers is to open the document (after +it’s been processed into PostScript by groff—see +How to invoke groff with mom) +in gv (ghostview), click the “odd pages” icon, +then click “Print Marked“. After printing is complete, +rearrange the sheets appropriately, put them back in your printer, +and have gv print the “even pages“. If you +prefer to work from the command line, check out the man pages for +pstops and psbook. There are other programs +out there as well to help with two-sided printing. +

+ +

Recto/verso macros

RECTO_VERSO
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: 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 text files +together. You need only concatenate chapters into a single file +(most likely with the cat command), put .COLLATE at the end of each +concatenated chapter, follow it with the +reference macros +needed for the new chapter, e.g. +CHAPTER +or +CHAPTER_STRING, +make any pertinent style changes to the upcoming chapter (unlikely, +but possible), and re-invoke the +START +macro. (Most likely, the reference macros and .START are +already there.) Each chapter will begin on a fresh page and behave +as expected. +

+ +

+Even if you always work with monolithic, multi-chapter files, every +chapter and its associated reference macros plus .START +still needs to be preceded by a .COLLATE command. +

+ +

+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 +output line +of a document before COLLATE falls too close to the bottom margin +for running text, mom may output a blank page with only a header +or footer between collated documents. In order to avoid this, I +recommend always preceding COLLATE with +.EL, +like this +
+ + .EL + .COLLATE + +

+ +

+Note: +See the +two words of caution, +above. +

+ +

+ + + + + + + + +

Next: Cover pages

+ +

+ + + + diff --git a/contrib/mom/momdoc/refer.html b/contrib/mom/momdoc/refer.html new file mode 100644 index 00000000..9fb53cf9 --- /dev/null +++ b/contrib/mom/momdoc/refer.html @@ -0,0 +1,1853 @@ + + + + + + + + Mom -- Document processing, bibliographies and references + + + + + + + +

+ + + + + + + +

Next: Writing letters

+ +

Bibliographies and references

+ +

Introduction to bibliographies and references
Tutorial – using mom with refer +
Bibliography and reference macros +
- Bibliography control macros and defaults

+ +

Introduction to bibliographies and references

+ +

+Mom provides the ability to automatically format and generate +bibliography pages, as well as footnote or endnote references, or +references embedded in the text. She accomplishes this by working +in conjunction with a special groff program called +refer. +

+ +

+refer is, in groff-speak, a pre-processor, which is to +say that it scans your files, looking for very specific control +lines (i.e. lines that begin with a dot, the same way macros do). +If refer doesn't find them, it can’t do it’s +job and neither can mom. The scanning is done before any other +document processing. +

+ +

+refer is a program that’s been around for a +long time. It’s powerful and has many, many features. +Unfortunately, the manpage (man refer), while +complete and accurate, is dense and not a good introduction. +(It’s a classic manpage Catch-22: the manpage is useful, but +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 information and +instructions are not to be taken as a manual or tutorial on full +refer usage. Much has been left out, on purpose. +

+ +

+If you’re already a refer user, the information +herein will be useful for adapting your current refer +usage to mom’s way of doing things. If you’ve never +used refer, the information is essential, and, in many +cases, may be all you need. +

+ +

+(For the benefit of old groff-hands: refer +support in mom is heavily based on the +refer module of the “ms” macros. The +choice was deliberate so that those wishing to play around with +mom’s bibliography formatting style would be +tinkering with the familiar.) +

+ +

+refer requires first that you create a +bibliographic database. From the information contained in the +database, mom formats and generates bibliographies +and references in MLA (Modern Language Association) style. MLA +style is clean, contemporary and flexible, and is widely used in the +humanities, where the range of material that has to be referenced +can run from simple books to live interviews and film. +

+ +

+Once you have created your database, you instruct refer +(and mom) to access entries in it by supplying keywords associated +with the entries. Depending on what you’ve instructed mom to +do, she will put the entries—fully and properly formatted +with respect to order, punctuation and italicization—in +footnotes, endnotes, or a full bibliography. +

+ +

+I encourage anyone interested in what MLA style looks like—and, by extension, how your bibliographies and references will look +after mom formats them—to check out +
+ + http://www.aresearchguide.com/12biblio.html + +or any other website or reference book on MLA style. +

+ +

Tutorial – Using `refer` with mom

Creating a refer database +
- Example refer database
- Meanings of the field identifiers (%A, %T, etc.)
Required refer commands +
- Required refer block (embedded references)
- Required refer block (bibliographies)
Accessing references in your documents
Telling mom where to put references
Creating bibliography pages
Invoking groff with mom and refer

+ +

1. Creating a refer database

+ +

+The first step in using refer with mom is setting +up your bibliographic database. The database is a text file +containing entries for each reference you want to access from your +mom files. The file is not a “mom file”; it's an +entirely separate database containing no mom macros. You may set +up individual databases for individual documents, or create a large +database that contains every reference you’ll ever use. +

+ +

+Entries (“records” in refer-speak) in the database file +are separated from each other by a single, blank line. The records +themselves are composed of single lines (“fields”) with +no blank lines between them. Each field begins with a percent +sign and a single letter (the "field identifier") +e.g. %A or %T. The letter identifies +what part of a bibliographic entry the field refers to: Author, +Title, Publisher, Date, etc. After the field identifier comes +a single space, followed by the information appropriate to +field. No punctuation should go at the ends of fields; mom adds +what’s correct automatically. Do note, however, that +author(s) (%A) requires that you enter the author +information exactly as you wish it to come out (minus the period), +including the comma after the first author’s last name. +

+ +

+Here’s an example database containing two records so you can +visualize what the above paragraph says. +

+ +

Example refer database

+ +%A Schweitzer, Albert +%A C.M. Widor +%T J.S. Bach +%l Ernest Newman +%V Vol 2 +%C London +%I Adam and Charles Black +%D 1923 +%O 2 vols +%K bach vol 2 + +%A Schaffter, Peter +%T The Schumann Proof +%C Toronto +%I RendezVous Press +%D 2004 +%K schumann schaffter + +

+ +

+The order in which you enter fields doesn’t matter. mom +and refer will re-arrange them in the correct order +for you. The meaning of the letters follows. There are, with +refer, quite a few—all uppercase — which +have, over time, come to be standard. Mom respects these. However, +she adds to the list (mostly using lowercase letters). +

+ +

Meanings of the field identifiers

+ +%A Author – records may contain multiple Author fields, + each beginning with %A, as in the first + entry of the example database, above; mom + and refer will figure out what to do when + there are multiple authors +%T Title – either the primary title (e.g. of a book), + or the title of an article (e.g. within a + book or journal or magazine) +%B Book title – the title of a book when %T contains the + title of an article; otherwise, use %T for + book titles +%R Report number – for technical reports +%J Journal name – the name of a journal or magazine when %T + contains the title of an article +%E Editor – additional editors may be entered on + separate %E lines (like authors); mom and + refer will figure out what to do with them + according to MLA rules +%e Edition – the number or name of a specific edition + (e.g. Second, 2nd, Collector’s, etc.) +%V Volume – volume number of a journal or series of + books +%N Journal number – journal or magazine number +%S Series – series name for books or journals that are + part of a series +%C City – the city of publication +%I Publisher – the publisher; %I stands for "Issuer" +%D Publication date +%P Page number(s) – enter page ranges as, e.g., 22-25 +%G Gov’t. + ordering number – for government publications +%O Other – additional information or comments you want + to appear at the end of the reference +%K Keywords – any words that will clear up ambiguities + resulting from database entries that + contain, say, the same author or the same + title +%d original + publication date – if different from the date of publication +%a additions – for books, any additions to the original + work, such as the preface to a new edition + or a new introduction +%t reprint title – if different from a work’s original title +%l translator – if the translator is not the editor; if more + than one translator, this field should + contain all the names, with appropriate + punctuation +%r translator + and editor – if tr. and ed. are one in the same; +%s site name – for web sites, the site name +%c content + of site – for web sites, the content, if unclear + (i.e. advertisement, cartoon, blog) +%o organization – for web sites, the organization, group or + sponsor of the site +%a access date – for a website, the date you accessed it +%u URL – for websites, the full URL of the site + +

+ +

+Tip: +If you have automatic hyphenation enabled in your document (you +probably do), mom will hyphenate your references. This can be a +problem because references typically contain several proper names, +which shouldn’t be hyphenated. The solution is to prepend to +any proper name in your refer database the groff +discretionary hyphen +character, \%, like this: +
+ + %A Hill, \%Reginald + +

+ +

+Alternatively, you can turn hyphenation off entirely in references +with the macro, +HYPHENATE_REFS OFF. +

+ +

2. Required `refer` commands

+ +

+Having set up your database, you now need to put some +refer-specific commands at the top of your mom file. You +cannot skip this step, nor can you source these commands with the +groff +primitive, +.so or the mom macro, +.INCLUDE. +They must +appear, exactly as shown, at the top of every file containing +references that need to be pre-processed with refer. +

+ +

+refer commands are introduced by a single +line containing .R1, and concluded with a single line +containing .R2. What you put between the .R1 +and .R2 lines are the commands themselves. The commands +should be entered one per line, in lowercase letters, with +no initial period (dot). +

+ +

+Here’s an example: +
+ + .R1 + no-label-in-text + no-label-in-reference + .R2 + +There are an awful lot of refer commands. We will focus +only on those required to get mom cooperating with refer. +If you’re interested, study the refer manpage to +discover what other commands are available and how to manipulate +them. +

+ +

+At a minimum, all mom files accessing a bibliographic database must +contain the following refer commands, exactly as shown: +

+ +

Required refer block (embedded references)

+ +.R1 +no-label-in-text +no-label-in-reference +join-authors ", and " ", " ", and " +database <full path to the database> +.R2 + +

+ +

+The first two commands tell refer to let mom handle +everything associated with footnote and endnote markers, both in the +body of the document, and in the footnotes/endnotes themselves. +

+ +

+The third command is required for mom to handle multiple authors in +proper MLA style. +

+ +

+The last command, database, assumes you have created +your own database, and do not otherwise have a system-wide +default database. +<full path to the database> +means the full path including the filename, e.g. +/home/user/refer/my-database. +

+ +

If you’re already a refer user, feel free to +enter whatever refer commands are necessary to +access the database(s) you want. +

+ +

+With the above refer block, you can embed references +directly into the text of your document, or have them output as +footnotes or endnotes. If, on the other hand, you want to collect +references for output in a bibliography, the block must read: +

+ +

Required refer block (bibliographies)

+ +.R1 +no-label-in-text +no-label-in-reference +join-authors ", and " ", " ", and " +database <full path to the database> +sort +accumulate +.R2 + +

+ +

3. Accessing references in your documents

+ +

+References are accessed by putting keywords, all on one line, +between the refer commands, .[ (dot +left-bracket) and .] (dot right-bracket). Both commands +must appear on separate lines, by themselves, like this: +
+ + .[ + keyword(s) + .] + +Keywords are any word, or set of words, that identify a database +record (i.e. a reference) unambiguously. (refer +doesn’t like ambiguity.) +

+ +

+If, for example, you want to reference a book by Ray Bradbury, +and the database contains only one book by Bradbury, a suitable +keyword would be “Bradbury”. If your database contains +several books by Bradbury, say, Fahrenheit 451 and The +Martian Chronicles, you could reference them with the keywords, +“451” and “Martian”. If, in addition to +the two books by Bradbury, you also had one whose title was The +Martian Mission, suitable keywords to reference The Martian +Chronicles might be: +
+ + .[ or .[ or .[ + Bradbury Martian Bradbury Chronicles Martian Chronicles + .] .] .] + +

+ +

+A special database field identifier, %K, lets you create +unique keywords for references. This can be very handy if you need +both a “short” and a “long” reference to the +same work. The short reference might be used in footnotes, the long +one in a bibliography. Consider the following: +
+ + %A Isherwood, Christopher %A Isherwood + %T Mr. Norris Changes Trains %T Mr. Norris Changes Trains + %d 1935 %K Nor short + %t The Last of Mr. \%Norris + %a Intro. Tom Crawford + %C New York + %I New Directions + %D 1945 + %K Norris + +To access the shorter reference, you’d do +
+ + .[ + Nor short + .] + +To access the longer one, you’d do +
+ + .[ + Norris + .] + +

+ +

4. Telling mom where to put references

+ +

+Mom provides several mechanisms for outputting references where you +want: +

embedded in the body of the document
in footnotes or endnotes +
- recipe for references in footnotes
- recipe for references in endnotes
collected in a bibliography

+ +

Embedding references in the document body

+ +

+References may be embedded in the document body, surrounded by +parentheses, square brackets, or braces. Use whichever you prefer, +following the recipes below. +
+ + Parentheses | Square brackets | Braces + =========== | =============== | ====== + .REF( | .REF[ | .REF{ + .[ | .[ | .[ + keyword(s) | keyword(s) | keyword(s) + .] | .] | .] + .REF) | .REF] | .REF} + +

+ +

Footnote or endnote references

+ +

+Most times, you’ll probably want references in either +footnotes or endnotes. Mom provides a simple mechanism whereby +you can choose which, or even switch back and forth. It’s +a two-step process. First, you instruct mom where you want the +references to go with either +.FOOTNOTE_REFS +or +.ENDNOTE_REFS. +Afterwards, you enclose the refer commands, .[ +and .], with the mom macro, +REF. +Depending on which was the last invoked, .FOOTNOTE_REFS or +.ENDNOTE_REFS, references will either go into footnotes or be +collected for output as endnotes. +

+ +

+The innate flexibility of this scheme allows you to have both +footnote references and endnote references in the same document. +This would be desirable if, say, you wanted truncated +references in footnotes, and full references in endnotes. +

+ +

+A recipe for footnoted references looks like this:
+ + .FOOTNOTE_REFS \"Can be placed anywhere in the file prior to .REF + .REF + .[ + keyword(s) + .] + .REF + +The reference between the first and second .REF will be +treated as a footnote, as will all subsequent .REF pairs +unless you invoke the macro, .ENDNOTE_REFS. +There’s no need to repeat .FOOTNOTE_REFS if all +your references are going into footnotes. +

+ +

+Important: +When FOOTNOTE_REFS are enabled, REF behaves identically to +FOOTNOTE +with respect to the use of the \c inline escape. Please +read the +HYPER IMPORTANT NOTE +found in the document entry for FOOTNOTE. +

+ +

+A recipe for endnote references looks like this: +
+ + .ENDNOTE_REFS \"Can be placed anywhere in the file prior to .REF + .REF + .[ + keyword(s) + .] + .REF + +The reference between the first and second .REF will +be treated as an endnote, as will all subsequent .REF +pairs unless you invoke the macro, .FOOTNOTE_REFS. +There’s no need to repeat .ENDNOTE_REFS if all your +references are going into endnotes. +

+ +

+Important: +When ENDNOTE_REFS are enabled, REF behaves identically to +ENDNOTE +with respect to the use of the \c inline escape. Please +read the +HYPER IMPORTANT NOTE +found in the document entry for ENDNOTE. +

+ +

Collected references (bibliographies)

+ +

+Sometimes, you may want to embed references in input text near the +sections of text to which they pertain, but not have them output +until later (typically, on a bibliography page). REF is used for +this, too, but you have to make sure your refer commands +block is set up properly at the top of your text file. The recipe +for this is: +
+ + .R1 + no-label-in-text + no-label-in-reference + join-authors ", and " ", " ", and " + database <full path to the database> + sort + accumulate + .R2 + +After this set up, and provided you don’t issue a +.FOOTNOTE_REFS or .ENDNOTE_REFS command, all +reference between .REF pairs will be collected for later +output in a bibliography. +

+ +

+As a precaution, mom will issue a message the first time you call +.REF if neither FOOTNOTE_REFS nor ENDNOTE_REFS is in +effect. If collected references are what you want, and you have set +up your .R1/.R2 block as above, you may safely ignore +the message. +

+ +

+LIMITATION: You cannot combine +“collected” references (plain REF) +with REFs that are instructed to go into +footnotes (with FOOTNOTE_REFS) or endnotes (with +ENDNOTE_REFS). This is a limitation imposed by +refer, not mom. +

+ +

5. Creating bibliography pages

+ +

+Bibliographies are processed separately from the main document, like +endnotes. And, like endnotes, just about every element on them can +be designed to your specifications. (See +Bibliography control macros and defaults.) +A mom bibliography begins with the macro, +BIBLIOGRAPHY, +like this: +
+ + .BIBLIOGRAPHY + +Following .BIBLIOGRAPHY, you have three choices of how to +proceed: +

+ +

+ If you have elected to have references collected from within the + body of a document (see above, + Collected references [bibliographies], + for instructions), which assumes you have a refer + command block like the one + here + at the top of your document, you need only do +
+ + .BIBLIOGRAPHY + .[ + $LIST$ + .] +
+ If you want to create the bibliography by hand (which may be the + case if you’ve used footnote and/or endnote references throughout + your document; see + LIMITATION), + follow this recipe. It assumes you already have a + refer block like the one + here + at the top of your document. +
+ + .BIBLIOGRAPHY + .R1 + sort + accumulate + .R2 + .[ -+ + keyword(s) | + .] | "keyword(s)" are keywords identifying the + .[ | particular bibliographic reference you want + keyword(s) | from your database. Order doesn't matter here; + .] | the refer command, sort, takes care of that. + .[ | + keyword(s) | + .] -+ + .[ + $LIST$ + .] +
+ Your final choice is to output your whole database. Again, + assuming you have a refer block like the one + here + at the top of your file, you need only do: +
+ + .BIBLIOGRAPHY + .R1 + bibliography <full path to database> + .R2 + + If you haven’t put a refer block in your + file already, you can, in this instance, put one after + .BIBLIOGRAPHY, like this: +
+ + .BIBLIOGRAPHY + .R1 + join-authors ", and " ", " ", and " + bibliography <full path to database> + .R2 +

+ +

+Whichever option you choose, mom will output a full bibliography +page, complete with a title (“BIBLIOGRAPHY” by default, +but that can be changed). +

+ +

6. Invoking groff with mom and refer

+ +

+So, now you’ve got a document formatted properly to use +references processed with refer, what do you do to output +the document? +

+ +

+It’s simple. Instead of invoking groff with just the +-mom option, as explained +here, +invoke groff with the -R option as well, like this: +
+ + groff -R -mom filename + +

+ +

Bibliography and reference macros

REF – begin/end a refer reference
FOOTNOTE_REFS – instruct mom to put REFs in footnotes
ENDNOTE_REFS – instruct mom to put REFs in endnotes
Embed references in the text +
- REF( – embed a reference in the text between parentheses
- REF[ – embed a reference in the text between square brackets
- REF{ – embed a reference in the text between braces
INDENT_REFS – manage the 2nd line indent 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 `refer` reference

+ +

+Macro: REF +

+ +

+The macro, REF, tells mom that what follows is +refer-specific, a keyword-identified reference from a +refer database. Depending on whether you’ve issued +a +.FOOTNOTE_REFS +or +.ENDNOTE_REFS +instruction, REF also tells mom where to place the reference. If +FOOTNOTE_REFS, the reference will be formatted and placed in a +footnote. If ENDNOTE_REFS, the reference will be collected for +output as an endnote. If you have issued neither instruction, the +reference will be collected for later output, most likely in a +bibliography. +

+ +

+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: +When REF is used with +FOOTNOTE_REFS +or +ENDNOTE_REFS, +it behaves identically to +FOOTNOTE +or +ENDNOTE, +so please read the HYPER IMPORTANT NOTE found in the document entry +for +FOOTNOTE +and/or +ENDNOTE. +

+ + + + +

Instruct mom to put REFs in footnotes

+ +

+Macro: FOOTNOTE_REFS +

+ +

+FOOTNOTE_REFS is an instruction to +REF, +saying, “put all subsequent references bracketed by the REF +macro into footnotes.” You invoke it by itself, with no +argument. +

+ +

+When FOOTNOTE_REFS is in effect, regular footnotes, (i.e. +those introduced with .FOOTNOTE and terminated with +.FOOTNOTE OFF) continue to behave normally. +

+ +

+You may switch between FOOTNOTE_REFS and +ENDNOTE_REFS +at any time. +

+ +

+If you have a lot of footnote references, and are identifying +footnotes by line number rather than by markers in the text, you may +want to enable +FOOTNOTES_RUN_ON +in conjunctions with FOOTNOTE_REFS. +

+ + + +

Instruct REF to put references in endnotes

+ +

+Macro: ENDNOTE_REFS +

+ +

+ENDNOTE_REFS is an instruction to +REF, +saying, “add all subsequent references bracketed by the REF +macro to endnotes.” You invoke it by itself, with no argument. +

+ +

+When ENDNOTE_REFS is in effect, mom continues to format regular +endnotes, (i.e. those introduced with .ENDNOTE and +terminated with .ENDNOTE OFF) in the normal way. +

+ +

+You may switch between ENDNOTE_REFS and +FOOTNOTE_REFS +at any time. +

+ + + +

Embed references in the text

+ +

+Macro pair: REF( ... REF) +

+ +

+Macro pair: REF[ ... REF] +

+ +

+Macro pair: REF{ ... REF} +

+ +

+You may sometimes want to embed references directly into the +body of your document, typically, but not always, inside +parentheses. Mom makes this possible through the use of the +REF<bracket type> macros. +

+ +

+All three macro pairs, above, are invoked the same way, namely +by introducing the reference with the first (“open”) +macro of the REF<bracket type> +pair, and terminating it with the second (“close”) +REF<bracket type> of the pair. For +example +
+ + .REF( + .[ + keyword(s) + .] + .REF) + +will embed a reference in the body of your document, surrounded +by parentheses. .REF[ ... .REF] +will surround the reference with square brackets. +.REF{ ... .REF} will surround it with curly +braces. +

+ + + +

Manage the second-line indent of references, per MLA standards

+ +

+Macro: INDENT_REFS FOOTNOTE | ENDNOTE | BIBLIO <indent> +

+ +

+• <indent> requires a unit of measure +

+ +

+Proper MLA-style references should have their second, and subsequent +lines, if any, indented. Since mom formats references in MLA style, +she automatically indents second lines. By default, the indent for +the second line of references, regardless of whether the references +appear in footnotes, endnotes, or bibliographies, is 1.5 +ems +for +PRINSTYLE TYPESET +and 2 ems for +PRINSTYLE TYPEWRITE. +

+ +

+If you’d like to change the 2nd-line indent for footnotes, +endnotes or bibliographies, just invoke .INDENT_REFS +with a first argument telling mom for which (footnote, endnote, or +bibliography) you want the indent changed, and a second argument +saying what you’d like the indent to be. For example, if you +want the second-line indent of references on a bibliography page to +be 3 +picas, +
+ + .INDENT_REFS BIBLIO 3P + +is how you’d set it up. +

+ +

+Tip: +If you are identifying endnotes by line number +(ENDNOTE_MARKER_STYLE LINE) +and 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 with +.REF <bracket type> +are considered part of +running text, +and are hyphenated (or not) according to whether hyphenation is +turned on or off for running text. Therefore, if you want to +disable hyphenation for such references, you must do so temporarily, +with +HY, +like this: +
+ + .HY OFF + .REF( + .[ + keyword(s) + .] + .REF) + .HY + +Alternatively, sprinkle your database fields liberally with +\%. +

+ + + +

Begin a bibliography

+ +

+Macro: BIBLIOGRAPHY +

+ +

+If you want to append a bibliography to your document, all you need +do is invoke .BIBLIOGRAPHY at the place you want it. +.BIBLIOGRAPHY breaks to a new page, prints the title +(BIBLIOGRAPHY by default, but that can be changed), and awaits +refer instructions. How to create bibliographies is +covered in the tutorial section, +Creating bibliography pages. +

+ +

+See the +Bibliography 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 +the refer command to output bibliographies. (See the +tutorial section, +Creating bibliography pages, +for instructions on how to output bibliographies.) +

+ +

+Mom’s default BIBLIOGRAPHY_TYPE is LIST, with a period (dot) +as the separator, and no prefix. +

+ + + +

Bibliography 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

+ +

+ +.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 14 points, adjusted. +

+ +

+Note: +Even if you give mom a .DOC_LEAD_ADJUST OFF command, +she will still, by default, adjust bibliography leading. You +must enter BIBLIOGRAPHY_LEAD <lead> +with no ADJUST argument to disable this default +behaviour. +

+ + + +

• Adjust the space between bibliography entries

+ +

+Macro: BIBLIOGRAPHY_SPACING <amount of space> +

+ +

+• Requires a unit of measure +

+ +

+By default, mom inserts a linespace between bibliography entries. +If you’d prefer she add a different amount of space, instruct +her to do so with BIBLIOGRAPHY_SPACING. Say, for example, +you’d prefer only 1/2 linespace, +
+ + .BIBLIOGRAPHY_SPACING .5v + +would do the trick. +

+ +Note: +

+Note: +As with endnotes pages, owing to the space inserted between +bibliography entries, bibliography pages may have hanging +bottom margins. Unlike endnotes pages, mom +is sad to report that there’s nothing you can do about +this, except a) pray things work out, or b) set your +BIBLIOGRAPHY_SPACING to zero. +

+ + + +

• 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 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 +ENDNOTES_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, 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 +
+ + .HEADER_CENTER "Endnotes" + +or + + .FOOTER_CENTER "Endnotes" + +prior to invoking .BIBLIOGRAPHY. +

+ +

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

+ +

• 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, invoke .BIBLIOGRAPHY_HEADER_CENTER (or +.BIBLIOGRAPHY_FOOTER_CENTER) with no argument. +Mom’s default is NOT to print the centre string. +

+ +

+If, for some reason, having enabled the header/footer centre string +on bibliography pages, you wish to disable it, invoke the same macro +with any argument (OFF, QUIT, Q, X...). +

+ +

• Allow headers on bibliography pages

+ +

+Macro: BIBLIOGRAPHY_ALLOWS_HEADERS <none> | ALL +

+ +

+By default, if HEADERS are on, mom prints page headers on all +bibliography pages except the first. If you don’t want her to +print headers on bibliography pages, do +
+ + .BIBLIOGRAPHY_ALLOWS_HEADERS OFF + +If you want headers on every page including the first, do +
+ + .BIBLIOGRAPHY_ALLOWS_HEADERS ALL + +

+ +

+Note: +If FOOTERS are on, mom prints footers on every bibliography page. +This is a style convention. In mom, there is no such beast as +BIBLIOGRAPHY_ALLOWS_FOOTERS OFF. +

+ +

4. Bibliography first-page title control

+ + + +

• Title string

+ +

+Macro: BIBLIOGRAPHY_STRING "<title to print at the top of bibliography pages>" +

+ +

+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

+ +

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

+ +

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

+ +

+Mom’s default is to double-underscore the title with 1/2-point +rules placed 2 points apart and 2 points below the baseline of the +title. +

+ + + +

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

+ +

+ + + + + + + + +

Next: Writing letters

+ +

+ + + + diff --git a/contrib/mom/momdoc/reserved.html b/contrib/mom/momdoc/reserved.html new file mode 100644 index 00000000..7dbc6db9 --- /dev/null +++ b/contrib/mom/momdoc/reserved.html @@ -0,0 +1,2658 @@ + + + + + + + + Mom -- Reserved words (macros, strings, registers) + + + + + + + +

+ + + + + + +

+ +

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 playing around inside mom’s macro file +(om.tmac) will find this list useful as well since it lists all (I +hope) the macros, strings, diversions, aliases and number registers +mom uses, along with brief descriptions of their functions. +

+ +

+ + +TYPESETTING ++++MACROS+++ +*Page layout + PAGELENGTH Page width + PAGE Page width/length; left, right, top, bottom margins + PAGEWIDTH Page width + PAPER Letter, legal, or A4 + B_MARGIN Space to leave at page bottom + L_MARGIN Page offset + R_MARGIN Line length as a function of + pagewidth minus pageoffset minus rightmargin + T_MARGIN Advance lead from page top + +*Page control + DO_B_MARGIN Margin at bottom of page; trap-invoked + DO_T_MARGIN Margin at top of page; trap-invoked + +*Style + COLOR Change color of text to predefined value + CONDENSE Set percentage of pseudo-condense (alias of + CONDENSE_OR_EXTEND) + EXTEND Set percentage of pseudo-extend (alias of + CONDENSE_OR_EXTEND) + FAMILY Family + FT Font + FALLBACK_FONT Font to use whenever FAMILY or FT errors occur + LL Line length + LS Leading (.vs) + NEWCOLOR Define a text color + PT_SIZE Point size + SETBOLDER Set degree of emboldening (pseudo-bold) in units + SETSLANT Set degree of pseudo-italic + XCOLOR Initialize a color from rgb.txt + +*Autolead + AUTOLEAD Always lead n points more than .PT_SIZE + +*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 cirlce 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 + #OPEN_CLOSE Manipulates character " to print `` or '' + #ORIGINAL_L_LENGTH Used in LIST for IB processing; holds \n[.l] + p Output line horiz position at end of + $PAD_STRING + #PAD_COUNT Number of times # was included in arg to PAD + #PAD_LIST_DIGITS Pad list digits to the left? (boolean) + #PAD_SPACE Size of padding space + #PAGE_LENGTH Page length (alias) + #PAGE_WIDTH Page width + #PP_ACTIVE Are we in the context of a para? (boolean) + #PRINT_FOOTER_ON_PAGE_1 (boolean) + #PSEUDO_FILL Signals that LEFT, RIGHT or CENTER is + in effect (booleand off, i.e. to 0, when + QUAD <arg> or JUSTIFY is called) + #PT_SIZE Point size (fractional) in units (alias) + #PT_SIZE_SET Was point size set with PT_SIZE? (boolean) + #Q_AT_TOP Does a quote start at the top of a new page? + (boolean) + #QUAD In autoquad mode? (boolean) + #QUIT Tells LIST whether to exit lists completely + (boolean) + #REMOVE Used in LIST OFF cleanup + #RESTORE_LEAD Lead value in effect prior to AUTOLEAD + #RESTORE_LINE_LENGTH Restores actual line length in RULE + #RESTORE_LN_NUMBER Start linenumbering again with stored + #NEXT_LN? (boolean) + #RESTORE_PT_SIZE Stores current point size (in units) prior + to underscore + #R_INDENT Value of right indent + #R_MARGIN Right margin + #RESTORE_PREV_INDENT Tells LIST OFF what kind of indent was active + prior to first invocation of LIST + #RESTORE_TRAP Did we have to disable traps? Used in + graphical object macros (boolean) + #RESTORE_SQ Instructs SMARTQUOTES to restore smartquotes if + SMARTQUOTES invoked without an arg + #RLD RLD value + #RULE_WEIGHT Weight given to RULE_WEIGHT + #RULE_WEIGHT_ADJ RULE_WEIGHT/2 + #RW Is RW in effect? (boolean) + #SHIFT_LIST<n> Value to add to #LIST_INDENT<n> for shifted lists + #SILENT Is silent on? (boolean) + #SIZE_FOR_PAD Used to ensure that the size in effect prior + to PAD is restored at the start of every + iteration of $PAD_STRING + #SLANT_ON Is SLANT on? (boolean) + #SPACE_TO_END Whitespace at end of string passed to PAD + #SQ_WAS_ON Instructs CODE OFF to restore smartquotes if they + were on prior to CODE + #ST<n>_LENGTH Length of ST<n>; calculated during ST <n> + #ST<n>_MARK Page offset of autotab <n> at ST<n>X + #ST_NUM Incrementing counter for autotab identification + #ST<n>_OFFSET Offset (from current tab) to add to #ST<n>_OFFSET + when calculating string indents set from within + tabs + #ST<n>_OFFSET Indent of autotab <n> (page offset) + #STORED_L_INDENT Current left indent at first invocation of LIST + #STORED_R_INDENT Current right indent at first invocation of LIST + #STORED_BL_INDENT Current "both, left" indent at first invocation + of LIST + #STORED_BR_INDENT Current "both, right" indent at first invocation + of LIST + #STORED_HL_INDENT Current hanging indent at first invocation + of LIST + #STORED_T_INDENT Current temporary indent at first invocation + of LIST + #STR_LENGTH Holds string length derived from .length request + #T_INDENT Value of temporary indent + #T_MARGIN Top margin + #TAB_ACTIVE Are we in a tab? (boolean) + #TAB_NUMBER Tab number given to TAB_SET + #TAB_LENGTH Tab length given to TAB_SET + #TAB_OFFSET Tab indent given to TAB_SET + #TEXT_WIDTH Width of string to underscore + #TN Was TN (or \*[T+] called? (boolean) + #TOP Set to 1 in T_MARGIN, DO_T_MARGIN and ALD; tells + the first LS or AUTOLEAD on a page to maintain + the baseline position prior to the LS call + #TOP_BASELINE_ADJ Amount by which to adjust the baseline position + of the first line on the page if an LS or AUTOLEAD + request differs from the lead current at the end of + the previous page + #TOTAL_LISTS Total number of lists in a nest + #UNDERSCORE_WEIGHT Weight of underscores + #UNDERSCORE_WEIGHT_ADJ UNDERSCORE_WEIGHT/2 + #USER_SET_L_LENGTH Did user invoke LL? (boolean) + #USER_SET_TITLE_ITEM Did user invoke TOC_TITLE_ENTRY? + #WEIGHT Weight given to #RULE_WEIGHT + #WEIGHT_ADJ RULE_WEIGHT/2 + u Horiz position of start of underscore + ++++STRINGS+++ + + $ARG String holding substrings derived from .substring + request + $COND_PERCENT Percentage by which to pseudo-condense type + $COLOR_SCHEME Color scheme used in NEWCOLOR + $<colorname>_FILL XCOLOR "alias" with _FILL attached; used to determine if + the alias exists when the alias is passed to DBX SOLID + or DCL SOLID + $CURRENT_QUAD Restores current quad value in RULE + $CURRENT_TAB Current tab number + $DC_ADJUST +|- # of points to subtract from dropcap + $DC_FAM Drop cap family + $DC_FT Drop cap font + $DROPCAP The dropcap letter + $ENUMERATOR<n> String enumerator for depth <n> in lists + $ENUMERATOR_TYPE<n> Type of enumerator used in LIST<n> + $EW Value passed to EW + $EXT_PERCENT Percentage by which to pseudo-extend type + $FAMILY Family + $FAMILY_FOR_PAD Used to ensure that the family in effect prior + to PAD is restored at the start of every + iteration of $PAD_STRING + $FONT Font + $FONT_FOR_PAD Used to ensure that the font in effect prior + to PAD is restored at the start of every + iteration of $PAD_STRING + $PAD_MARKER Character to mark off padding in PAD + $PAD_STRING Arg passed to PAD + $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 + FINIS Prints --END-- + FOOTNOTE Collects footnotes in text for printing at bottom + of page + FOOTNOTE_REFS Send REFs to footnotes + HEAD Section title (main heads) + HYPHENATE_REFS Turn on/off hyphenation of REF references + ITEM Begin a list item + LINEBREAK Break between narrative sections + LIST Initialize a list + MN Margin note + MN_INIT Initialize parameters for margin notes + NUMBER_LINES Number text lines + NUMBER_BLOCKQUOTE_LINES Number blockquote lines + NUMBER_QUOTE_LINES Number quote lines + PAD_LIST_DIGITS Leave space for two-numeral digit enumerators + in a list + PARAHEAD Paragraph head + PP Paragraph + QUOTE Poetic or line for line quotes + REF Wrapper around FOOTNOTE or ENDNOTE, depending + on FOOTNOTE_REFS or ENDNOTE_REFS + REF( Begin embedded reference, parens + REF) End embedded reference, parens + REF[ Begin embedded reference, square brackets + REF] End embedded reference, square brackets + REF{ Begin embedded reference, braces + REF} End embedded reference, braces + REF_INDENT Amount of 2nd line indent of references for + footnote, endnote or bibliography refs + RESET_LIST Reset digit or alpha list enumerator + SHIFT_LIST Move a list over to the right + START Sets doc defaults and prints info collected + with doc info macros + SUBHEAD Subheads + +*Headers/footers + BREAK_QUOTE Manually break a footnoted quote that crosses + a page/column + DO_FOOTER Prints footer (after footnote processing, if any) + FOOTER_ON_FIRST_PAGE Print footer on first page? (boolean) + FOOTER Trap-invoked footer macro + HEADER Trap-invoked header macro + PAGINATE Turns page numbering on or off (doc default=on) + PAGINATE_TOC Turns pagination of toc on or off (default=on) + RECTO_VERSO Enables switch HEADER_LEFT and HEADER_RIGHT on + alternate pages + +*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 + +-Footnotes- + FOOTNOTE_AUTOLEAD Autolead to use in footnotes + FOOTNOTE_LINENUMBER_BRACKETS Brackets for footnote linenumbers + FOOTNOTE_LINENUMBER_SEPARATOR Separator for footnote linenumbers + FOOTNOTE_MARKERS Turns footnote markers on or off + FOOTNOTE_MARKER_STYLE STAR or NUMBER; default=STAR + FOOTNOTE_RULE_ADJ # of points to raise footnote rule from its + baseline + FOOTNOTE_RULE_LENGTH Length of footnote separator rule + FOOTNOTE_RULE Turns printing of fn separator rule on or off; + default is on + FOOTNOTE_SPACING Post footnote item spacing + FOOTNOTES_RUN_ON Run footnotes on (line numbering mode only) + RESET_FOOTNOTE_NUMBER Reset fn# to 1, or, if arg PAGE, reset + automatically to 1 on every page + RUNON_WARNING Utility macro; warns if FOOTNOTES_RUN_ON + was called when fn marker style is STAR or + NUMBER + +-Endnotes- + ENDNOTE_LEAD Leading for endnotes page + ENDNOTE_LINENUMBER_BRACKETS Brackets around line numbers identifying + endnotes and text + ENDNOTE_LINENUMBER_GAP Amount of space to leave between line + ENDNOTE_LINENUMBER_SEPARATOR Separator between line numbers identifying + endnotes and the endnote item text + endnotes and text + ENDNOTE_MARKER_STYLE NUMBER or LINE + ENDNOTE_NUMBERS_ALIGN_RIGHT Hang endnote numbers and align right + ENDNOTE_NUMBERS_ALIGN_LEFT Don't hang endnote numbers and align left + ENDNOTE_PARA_INDENT First line indent of paras in multi-para + endnotes + ENDNOTE_PARA_SPACE Whether to space paras in multi-para endnotes + ENDNOTE_PT_SIZE Base point size for endnotes page + ENDNOTE_STRING Endnotes page head + ENDNOTE_STRING_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 + HEADERS_AND_FOOTERS Enables and permits the creation of + headers and footers that appear on the + same page + SWITCH_HDRFTR Switch HDRFTR_LEFT and HDRFTR_RIGHT + +-Page numbering- + PAGENUM_HYPHENS Turns on/off hyphens surrounding page numbers + PAGENUM_ON_FIRST_PAGE Print page number on first page when footers + are on (boolean) + PAGENUM_POS Controls placement of page numbers; + default=bottom/centred + PAGENUM_SIZE How much to in/decrease point size of page + numbers + PAGENUM_STYLE Page # in roman, Arabic, or alphabetic + RESTORE_PAGINATION Restore pagination after outputting non- + paginated endnotes. + SUSPEND_PAGINATION Suspend pagination prior to outputting + endnotes + +-Heads- + HEADER_GAP Space between header and running text + HEADER_MARGIN Space from top of page to header + HEAD_CAPS Print section titles in caps? (boolean) + HEAD_SPACE Give HEADs 2 line-spaces before. If OFF, + only 1. Default is on. + HEAD_UNDERLINE Underline section titles? (boolean) + NUMBER_HEADS Print head numbers + RESET_HEAD_NUMBER Reset head number + +-Subheads- + NUMBER_SUBHEADS Print subhead numbers + RESET_SUBHEAD_NUMBER Reset subhead number + +-Para heads- + NUMBER_PARAHEADS Print parahead numbers + PARAHEAD_INDENT How much to indent paraheads + RESET_PARAHEAD_NUMBER Reset parahead number + + PREFIX_CH_NUM_WARNING Macro to abort PREFIX_CHAPTER_NUMBER + with a warning if the arg to CHAPTER isn't + a digit, and user hasn't supplied a digit + to PREFIX_CHAPTER_NUMBER + PREFIX_CHAPTER_NUMBER Prefix the chapter number to numbered + heads, subheads and paraheads +-Paragraphs- + INDENT_FIRST_PARAS Indent 1st paras? (doc default=not indented) + PARA_INDENT Size of para indent + PARA_SPACE Put a line space before paras + PP_FONT Overall doc font + +-Quotes- + Q_FITS Utility macro for DO_QUOTE + Q_NOFIT Utility macro for DO_QUOTE + QUOTE_AUTOLEAD Leading of (block)quotes + +-Line/section breaks- + LINEBREAK_CHAR Linebreak character, iterations and positioning + +-Printstyle TYPEWRITE- + ITALIC_MEANS_ITALIC For TYPEWRITE; render .FT I in italic. + SLANT_MEANS_SLANT In TYPEWRITE, render \*[SLANT] as slant + UNDERLINE_ITALIC In TYPEWRITE, render .FT I as underlined + UNDERLINE_QUOTES In TYPEWRITE, underline quotes? (boolean) + UNDERLINE_SLANT In TYPEWRITE, render \*[SLANT] as underlined + +-Table of contents- + TOC_APPENDS_AUTHORS Appends author(s) to toc doc title entries + TOC_LEAD Leading of toc pages + TOC_PADDING Number of placeholders for toc entries page + numbers + TOC_HEAD_INDENT Indent of toc head entries + TOC_HEADER_STRING TOC header string (default=Contents) + TOC_PAGENUM_STYLE Page numbering style (hdrftr nums) of + toc pages + TOC_RV_SWITCH Switch L/R margins of toc pages + TOC_PARAHEAD_INDENT Indent of toc parahead entries + TOC_SUBHEAD_INDENT Indent of toc subhead entries + TOC_TITLE_ENTRY User supplied toc doc title entry + TOC_TITLE_INDENT Indent of toc doc title entries + +*Aliases for 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 + TERMINATE .em that ensures deferred footnotes get output + on final pages + TRAPS Sets hdrftr traps; optionally adjusts #DOC_LEAD + to fill page to #B_MARGIN + TYPEWRITER Sets family (C), font (R) and point size (12) + for PRINTSTYLE TYPEWRITE + VFP_CHECK Trap-sprung macro 1 valid baseline higher than + where FOOTER will be sprung; checks whether + there is, in fact, just enough room for + another line of running text to be added to + the page without jamming footnotes too close + to running text. + ++++DIVERSIONS+++ + + B_QUOTE Block (indented) quote text + CLOSING Closing (i.e. Yours truly,) + EPI_TEXT Epigraph text + END_NOTES Endnotes text + FN_IN_DIVER Footnotes gathered from inside a diversion + FN_OVERFLOW Excess footnotes when B_MARGIN is reached + FOOTNOTES Text of footnotes + GREETING Full salutation (e.g. Dear John Smith,) + LETTERHEAD<n> Date, addresser, addressee or greeting; + <n> is from 1 to 4, supplied by #FIELD + P_QUOTE Line for line (poetic) quote text + RUNON_FOOTNOTES Special diversion for run-on footnotes + RUNON_FN_IN_DIVER Special diversion for run-on footnotes inside + (block)quotes + TOC_ENTRIES TOC entries + ++++NUMBER REGISTERS+++ + + #ADJ_BIB_LEAD Adjust BIB_LEAD? (boolean) + #ADJ_DOC_LEAD Adjust DOC_LEAD? (boolean) + #ADJ_EN_LEAD Adjust EN_LEAD? (boolean) + #ADJ_TOC_LEAD Adjust TOC_LEAD? (boolean) + #ADVANCE_FROM_TOP Distance from page top to start of + running text if no docheader + #ARG_NUM Keeps track of number of args passed to a + macro + #ARGS_TO_LIST Was LIST passed some args? (boolean) + #ATTRIBUTE_COLOR Colorize attribute string? (boolean) + #AUTHOR_<n> Strings passed to AUTHOR + #AUTHOR_COLOR Colorize author(s)? (boolean) + #AUTHOR_COVER_NUM Incrementing register used in definining + $AUTHOR_COVER_<n> strings + #AUTHOR_DOCCOVER_NUM Incrementing register used in definining + $AUTHOR_COVER_<n> strings + #AUTHOR_NUM Keeps track of user-defined string + AUTHOR_<n> in AUTHOR + #AUTHORS Equals final value of AUTHOR_NUM; + used for authors in doc header + #BASELINE_MARK In PP, the vertical position on the page + (when paragraph spacing is on) after a + quote or blockquote has been output and + the post-quote space has been added. + #BMARG Position of unvarying bottom margin + during doc processing; required for + collecting footnotes inside diversions + #BIB_ALLOWS_HEADERS Put headers on bib pages? (boolean) + #BIB_ALLOWS_HEADERS_ALL Put headers on all bib pages? (boolean) + #BIB_FIRST_PAGE Tells PRINT_PAGE_NUMBER about bibliography + first page number + #BIB_FIRST_PN Starting pagenumber for bibliographies + #BIB_HDRFTR_CENTER Put a center string in bib page headers? + (boolean) + #BIB_LEAD Bibliography lead, expressed in points + #BIB_LIST Output bibs in list style? (boolean) + #BIB_NO_COLS De-columnize bibliographies? (boolean) + #BIB_NO_FIRST_PN Put a page number on the first page of + bibliographies? (boolean) + #BIB_SINGLESPACE Single-space TYPEWRITE bibliographies? (boolean) + #BIB_SPACE Post item space for bibliography pages + #BIB_STRING_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) + #BROKEN_QUOTE Did we invoke BREAK_QUOTE? (boolean) + #CAP_HEIGHT_ADJUST Tallest cap height of strings LEFT, CENTER, + and RIGHT in footers; used to place rule + over footer + #CAPS_WAS_ON In HDRFTR, to re-enable running text CAPS + (boolean) + #CENTER_CAP_HEIGHT Cap height of CENTER string in + headers/footers + #CH_NUM The chapter number obtained by + PREFIX_CHAPTER_NUMBER + #CHAPTER_CALLED Has CHAPTER been invoked? (boolean); used + by PREFIX_CHAPTER_NUMBER to see whether + to try to get the chapter number from + the arg passed to CHAPTER + #CHAPTER_TITLE_NUM Incrementing register used to define strings + $CHAPTER_TITLE_<n> + #CHAPTER_TITLE_COLOR Colorize chapter title? (boolean) + #CLOSING Is there a closing (for letters)? (boolean) + #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 + #DIVER_FN Register that tells FOOTNOTE whether to + "move" or "defer" a footnote collected + inside a diversion + #DEFER_BIB_SPACING Tells DEFAULTS to do BIBLIOGRAPHY_SPACING + if it was called before START + #DEFER_PAGINATION Tells COLLATE to restore pagination (from + RESTORE_PAGINATION + #DEFER_SPACE_ADDED Was space added between two "first" footnotes that + appear on the same page? (boolean) + #DELAY_SHIM Instructs DO_QUOTE to delay SHIM when quote + falls at the top of a page + #DEPTH LIST depth + #DEPTH_1 Doc header depth with lead adjustment + (#DOCHEADER_LINES * #DOCHEADER_LEAD) + #DEPTH_2 Doc header depth without lead adjustment + (#DOCHEADER_LINES * #DOC_LEAD) + #DEPTH_TO_B_MARGIN Page length minus #B_MARGIN + #DIVERSIONS_HY_MARGIN A reasonable value for .hym applied to + QUOTE, BLOCKQUOTE and EPIGRAPH to + avoid excessive hyphenation if these are + set quad left + #DIVERTED Set to 1 in DIVERT_FN_OVERFLOW; reset + subsequently in FOOTNOTES when called by + PROCESS_FN_LEFTOVER to 2 or 3 for use by + FOOTER to decide whether to in/decrease + #FN_DEPTH when outputting footnotes + #DOC_COVER Are we doing a DOC_COVER? (boolean) + #DOC_COVER_AUTHOR Put AUTHOR(s) on DOC_COVER? (boolean) + #DOCCOVER_BLANKPAGE Output blank page after DOC_COVER? (boolean) + #DOC_COVER_CHAPTER_TITLE_COLOR Colorize CHAPTER_TITLE on DOC_COVER? (boolean) + #DOC_COVER_COPYRIGHT Put copyright on DOC_COVER? (boolean) + #DOC_COVER_DOCTYPE Put doctype on DOC_COVER? (boolean) + #DOCCOVER_END Are we finishing a DOC_COVER? (boolean) + #DOC_COVER_LEAD Doc cover leading + #DOC_COVER_MISC Put misc on DOC_COVER? (boolean) + #DOC_COVER_START_POS Vertical starting pos of doc cover material + #DOC_COVER_COLOR Colorize cover? (boolean) + #DOC_COVER_START_POS Vertical starting pos of cover material + #DOC_COVER_TITLE_COLOR Colorize doc cover title? (boolean) + #DOC_COVER_SUBTITLE_COLOR Colorize doc cover subtitle? (boolean) + #DOC_COVER_ATTRIBUTE_COLOR Colorize doc cover attribution string? (boolean) + #DOC_COVER_AUTHOR_COLOR Colorize doc cover author(s)? (boolean) + #DOC_COVER_DOCTYPE_COLOR Colorize doc cover doctype? (boolean) + #DOC_COVER_COPYRIGHT_COLOR Colorize doc cover copyright line? (boolean) + #DOC_COVER_MISC_COLOR Colorize doc cover misc line? (boolean) + #DOC_COVER_SUBTITLE Put subtitle on DOC_COVER? (boolean) + #DOC_COVER_TITLE Put title on DOC_COVER? (boolean) + #DOC_COVER_TITLE_NUM Number of doc cover title items + #DOC_COVERS Print doc covers? (boolean) + #DOC_COVERS_OFF Don't print DOC_COVERs (boolean) + #DOCCOVER_RULE_WEIGHT Doctype underline weight on DOC_COVER + #DOCCOVER_RULE_WEIGHT_ADJ DOCCOVER_RULE_WEIGHT/2 + #DOCCOVER_UNDERLINE Underline doctype on DOC_COVER? (boolean) + #DOCCOVER_UNDERLINE_WEIGHT Doctype underline weight on DOC_COVER + #DOCCOVER_UNDERLINE_WEIGHT_ADJ DOCCOVER_UNDERLINE_WEIGHT/2 + #DOCCOVERS_COUNT Include DOC_COVER in pagination scheme? (boolean) + #DOC_HEADER Whether to print a doc header (boolean) + #DOC_LEAD_ADJ Incrementing value (in units) added to + #DOC_LEAD to fill page to #B_MARGIN + #DOC_LEAD Leading used in body + #DOC_L_LENGTH Global L_LENGTH + #DOC_L_MARGIN Global L_MARGIN + #DOC_LR_MARGIN_TMP In HEADER, if RECTO_VERSO=1, temporarily + holds DOC_L_MARGIN during page margin switch + #DOC_PT_SIZE Point size used for body text + #DOC_R_MARGIN Global R_MARGIN + #DOC_TYPE 1=default, 2=chapter, 3=named, 4=letter + #DOCHEADER_ADVANCE Distance from top-of-page to baseline of + docheader + #DOCHEADER_COLOR Colorize docheader? (boolean) + #DOCHEADER_DEPTH Depth of docheader + #DOCHEADER_LEAD Lead of doc header + (#DOC_LEAD + #DOCHEADER_LEAD_ADJ) + #DOC_LEAD_ADJUST_OFF Don't adjust DOC_LEAD (boolean) + #DOCS Always 1 after START + #DOCTITLE_NUM Number of doctitle items + #DOCTYPE_COLOR Colorize doctype? (boolean) + #DOCTYPE_RULE_WEIGHT Doctype underline weight + #DOCTYPE_RULE_WEIGHT_ADJ DOCTYPE_RULE_WEIGHT/2 + #DOCTYPE_UNDERLINE Underline doctype? (boolean) + #DOCTYPE_UNDERLINE_WEIGHT Weight of doctype underline + #DOCTYPE_UNDERLINE_WEIGHT_ADJ DOCTYPE_UNDERLINE_WEIGHT/2 + #DOING_COVER Tells PRINT_AUTHORS that it's printing + the authors for a cover or doc cover + #DONE_ONCE Keeps track of how many times footnotes + have been collected inside the same diversion + #DONT_RULE_ME Rule this (apparent) first footnote? (boolean) + #DIVER_LN_OFF Turn linenumbering off in (block)quotes? + (boolean) + #DRAFT_WITH_PAGENUM Are we attaching draft/revision info to page + number? (boolean) + #EM_ADJUST Amount to raise \(em at END + #EN_ALLOWS_HEADERS Put page headers on endnotes pages? (boolean) + #EN_ALLOWS_HEADERS_ALL Put page headers on all endnotes pages? + (boolean) + #EN_BQ_AUTOLEAD Register created by EN_BLOCKQUOTE_AUTOLEAD + #EN_BQ_LEAD Leading of blockquotes on endnotes pages + #EN_FIGURE_SPACE Width of \0, for use with formatting endnotes + #EN_FIRST_PAGE Tells PRINT_PAGE_NUMBER about endnotes + first page number + #EN_FIRST_PN Page number that appears on page 1 of + endnotes pages. + #EN_HDRFTR_CENTER Should we print centre string of + headers/footers on endnotes pages? (boolean) + #EN_LEAD Lead of endnotes + #EN_LN_BRACKETS Are we using brackets for line-numbered + endnotes (boolean) + #EN_LN_SEP Are we using a separator for line-numbered + endnotes (boolean) + #EN_MARK \n[ln] when \*[EN-MARK] is called + #EN_MARK_2 \n[ln] when ENDNOTE is called + #EN_MARKER_STYLE 1=NUMBER; 2=LINE + #EN_NO_COLS Do not set endnotes in columns? (boolean) + #EN_NO_FIRST_PN Put pagenumber on 1st page of endnotes? + (boolean) + #EN_NUMBER Number of current endnote + #EN_NUMBER_PLACEHOLDERS Number of placeholders to 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) + #FN_AUTOLEAD Autolead value of footnotes + #FN_BL_INDENT Left indent of INDENT BOTH in footnotes + #FN_BR_INDENT Right indent of INDENT BOTH in footnotes + #FN_COUNT Which fn marker to print; also to + tell mom to reserve space for and print + the rule above footnotes + #FN_COUNT_AT_FOOTER The FN_COUNT after FOOTNOTES has been + output in FOOTER + #FN_COUNT_FOR_COLS Holds a separate footnote count for columns + (so they don't reset to 0 1 until page break) + #FN_DEFER Defer footnote to next page/column? (boolean) + If 0, don't defer. + #FN_DEFER_SPACE Whether to deposit space before + footnote 1 because there's a deferred + footnote on the page + #FN_DEPTH Depth of footnote diversion(s) + #FN_FOR_EPI Signals to epigraph that a footnote is being + processed + #FN_GAP When there are footnotes on a page, the + difference between where FOOTER will be + sprung and the next valid baseline. + Used in VFP_CHECK. + #FN_LEAD Lead in footnotes after FN_AUTOLEAD is + applied + #FN_L_INDENT Left indent of INDENT LEFT in footnotes + #FN_LINES Number of lines in fn; used to calculate + fn depth + #FN_LN_BRACKETS Are footnote linenumber brackets being used? + (boolean) + #FN_LN_SEP Is a footnote linenumber separator being used? + (boolean) + #FN_MARK \n[ln] when \*[FN-MARK] is called + #FN_MARK_2 \n[nl] when FOOTNOTE is called + #FN_MARKER_STYLE 1=STAR; 2=NUMBER + #FN_MARKERS Print footnote markers? (boolean) + #FN_NUMBER The footnote number attached to running text + (and fns) when numbers instead of + star/dagger is being used for footnootes + numbers + #FN_OVERFLOW_DEPTH Depth of leftover from footnote processing + #FN_OVERFLOW_TRAP_POS The register that sets the position of + trap FN_OVERFLOW_TRAP. + #FN_R_INDENT Right indent of INDENT RIGHT in footnotes + #FN_REF Put REFs in footnotes? (boolean) + #FN_RULE Print fn rule? (boolean) + #FN_RULE_ADJ # of points to raise footnote separator from + its baseline + #FN_RULE_LENGTH Length of footnote separator rule + #FN_RULE_WEIGHT Weight of the footnote separator rule + #FN_RULE_WEIGHT_ADJ FN_RULE_WEIGHT/2 + #FN_SPACE Post footnote space + #FN_WAS_DEFERED Tells HEADER about a deferred footnote + #FOOTER_DIFF In TRAPS, the difference between the + original #B_MARGIN and #VISUAL_B_MARGIN + #FOOTER_GAP Amount of space between end of text and + page # + #FOOTER_MARGIN Amount of space between page # and bottom + of page + #FOOTER_POS Position of footer trap (required for + collecting footnotes inside a diversion) + #FOOTER_RULE Print footer rule? (boolean) + #FOOTER_RULE_GAP Gap between footer and separator rule above + #FOOTER_RULE_WEIGHT Weight of footer rule + #FOOTER_RULE_WEIGHT_ADJ #FOOTER_RULE_WEIGHT/2 + #FOOTERS_ON Are we using footers? (boolean) + #FOOTERS_WERE_ON Were footers on? - used in FINIS and BLANKPAGE + (boolean) + #FOOTNOTE_COLOR Colorize footnotes? (boolean) + #FROM_BIB_STRING Tells UNDERSCORE it's underscoring $BIB_STRING + #FROM_COVER Tells UNDERSCORE it's underscoring on a cover + #FROM_DOC_COVER Tells UNDERSCORE it's underscoring on a doccover + #FROM_DOCTYPE Tells UNDERSCORE it's underscoring the doctype + #FROM_EN_STRING Tells UNDERSCORE it's underscoring $EN_STRING + #FROM_EN_TITLE Tells UNDERSCORE it's underscoring $EN_TITLE + #FROM_HEAD Tells UNDERSCORE it's underscoring a head + #FROM_DIVERT_FN Signals to FOOTNOTE, when run from + within DIVERT_FN_LEFTOVER, to set + #SPACE_REMAINING to the total area + allowable for running text + #FROM_FOOTER In col to col footnote processing, tells + FOOTNOTE that FOOTNOTES was output from + FOOTER. + #FROM_HEADER In col to col footnote processing, tells + FOOTNOTE that FOOTNOTES was output from + HEADER. + #FULLSPACE_QUOTES Should we fullspace quotes? (boolean) + #GET_DC_HEIGHT Used in routine to get the correct point size for + dropcaps + #GET_DEPTH Signals to FOOTNOTE that it should + measure the depth of current footnotes + plus the most recently added one, except + where the footnote is to be deferred to + the next page or column + #GUTTER Width of gutter between columns + #HDRFTR_BOTH Are we setting both headers and footers? (boolean) + #HDRFTR_CENTER_CAPS CENTER part of header/footer in caps? + (boolean; default=off) + #HDRFTR_CENTER_COLOR Colorize header/footer center? (boolean) + #HDRFTR_COLOR Colorize headers/footers? (boolean) + #HDRFTR_CTR_PAD_LEFT Amount of hdrftr CENTER padding on the left + #HDRFTR_CTR_PAD_RIGHT Amount of hdrftr CENTER padding on the right + #HDRFTR_CTR_PAD_TMP Temp storage of left hdrftr CENTER padding + (for recto/verso switch) + #HDRFTR_HEIGHT Cap height of $HDRFTR_RECTO/$HDRFTR_VERSO + strings + #HDRFTR_LEFT_CAPS Left part of header/footer in caps? + (boolean; default=off) + #HDRFTR_LEFT_COLOR Colorize header/footer left? (boolean) + #HDRFTR_PT_SIZE Initial point size of headers/footers + #HDRFTR_RECTO_CAPS Header/footer recto caps? (boolean) + #HDRFTR_RIGHT_CAPS Right part of header/footer in caps? + (boolean; default=on) + #HDRFTR_RIGHT_COLOR Colorize header/footer right? (boolean) + #HDRFTR_RULE Print head/footer rule? (boolean) + #HDRFTR_RULE_COLOR Colorize header/footer rule? (boolean) + #HDRFTR_RULE_GAP Space between header/footer and + header/footer rule + #HDRFTR_RULE_WEIGHT Weight of header/footer rule + #HDRFTR_RULE_WEIGHT_ADJ HDRFTR_RULE_WEIGHT/2 + #HDRFTR_TMP_CAPS_SWITCH Temporarily holds HDRFTR_LEFT_CAPS value if + #SWITCH_HDRFTR=1 + #HDRFTR_VERSO_CAPS Header/footer verso caps? (boolean) + #HEAD 1=main/section head 2=subhead + #HEAD_CAPS Print section titles in caps? (boolean) + #HEAD_COLOR Colorize heads? (boolean) + #HEADER_GAP Distance from header to running text + #HEAD_NUM Head number + #HEAD_SPACE 2 line spaces before heads? (boolean) + #HEAD_UNDERLINE Underline heads? (boolean) + #HEAD_UNDERLINE_WEIGHT Head underline weight + #HEAD_UNDERLINE_WEIGHT_ADJ HEAD_UNDERLINE_WEIGHT/2 + #HEADER_MARGIN Distance from top of page to header + #HEADER_RULE Print header rule? (boolean) + #HEADER_RULE_GAP Gap between header and header rule + #HEADER_RULE_WEIGHT Header rule weight + #HEADER_RULE_WEIGHT_ADJ HEADER_RULE_WEIGHT/2 + #HEADERS_ON Headers on? (boolean) + #HEADER_STATE Saves header state in COLLATE for use in + START after COLLATE + #HEADERS_WERE_ON Were headers on? - used in BLANKPAGE (boolean) + #HF_OFF Has HEADERS_AND_FOOTERS been turned off? (boolean) + #HORIZ_MARK Horizontal + #HOW_MANY Number of blank pages to output + #IGNORE Should we ignore this macro? Set to 1 in + TYPEWRITE. + #IN_BIB_LIST Tells ITEM we're doing a bibliography in + list style + #INDENT_FIRST_PARAS Indent first paras? (boolean) + #INDENT_FIRSTS Tells footnotes to leave INDENT_FIRST_PARAS + alone if it's on for running text. + #ITALIC_MEANS_ITALIC For TYPEWRITE. (boolean) + #ITEM Counter for removing _1, _2, _3... strings + in TITLE, CHAPTER_TITLE, etc. + #L_LENGTH_FOR_EPI Stores line length at top of doc for use + with EPIGRAPH when columns are on + #L_MARGIN_DIFF Difference between DOC_L_MARGIN and + L_MARGIN + #LEFT_CAP_HEIGHT Cap height of left string in headers/footers + #VALID_BASELINE Calculates vert. position of next valid + baseline in SHIM + #LETTER_STYLE 1=BUSINESS 2=PERSONAL + #LINEBREAK Did we have a linebreak? (boolean) + #LINEBREAK_COLOR Colorize linebreak? (boolean) + #LINENUMBER_COLOR Colorize linenumbers? (boolean) + #LINENUMBERS Holds various states of line-numbering when + line numbering is enabled + #LINES_PER_PAGE # of lines (at DOC_LEAD) that fit on + page after #B_MARGIN is set + #LN Are line numbers on? (boolean) + MN-active Are we doing a margin note? (boolean) + MN-curr Current margin note + MN-div-<n>-depth Depth of margin note <n> + MN-hy Hyphenation flag of margin notes + #MNinit Have margin notes been initialized? (boolean) + #MNinit_DEFERRED Did we have to defer a margin note? (boolean) + MN-last-pos Baseline of previous margin note + MN-lead-adj Difference between the current DOC_LEAD and the + leading used in margin notes + MN-left Number of current left margin note + MN-left-start Horizontal start position of left margin note + MN-left-width Width of left margin note + MN-right Number of current right margin note + MN-right-start Horizontal start position of right margin note + MN-right-width Width of right margin note + MN-sep Gutter between margin notes and running text + MN-shifted Did we have to shift a margin note down? + (boolean) + MN-size Point size of margin notes + MN-spacing Leading of margin notes + #MISC_<n> Used to print "next" misc lines in DO_COVER + #MISC_COVER_NUM Number of cover misc items + #MISC_DOCCOVER_NUM Number od doc cover misc items + #MISC_NUM Number of MISC items + #MISCS =#MISC_NUM in DO_COVER + #MN_OVERFLOW_LEFT If 1, left margin note text overflows + #MN_OVERFLOW_RIGHT If 1, right margin note text overflows + #n%_AT_PAGENUM_SET Page # from n% when PAGENUMBER invoked + #NEEDS_SPACE Instruct FOOTNOTE, when called by + PROCESS_FN_IN_DIVER, that if the footnote + had to be deferred, the VFP must be + raised by 1v (set in DIVER_FN_2_PRE) + #NEITHER Should we print no covers? (boolean) + #NEXT_AUTHOR Supplies correct digit to AUTHOR_<n> + when printing authors in doc header + #NEXT_LN Next linenumber when \n[ln] has to be stored + because linenumbering suspended + #NEXT_MISC Incrementing counter for misc lines in + DO_COVER + #NEXT_SUBTITLE Incrementing register used to print subtitles + #no-repeat-MN-left Don't repeat left margin note (boolean) + #no-repeat-MN-right Don't repeat right margin note (boolean) + #NO_BACK_UP Instructs FN_OVERFLOW_TRAP not to + subtract 1 line of footnote lead from + FN_OVERFLOW in a PREV_FN_DEFERRED + situation. + #NO_BREAK Set to 1 in COLLATE if last line of + text before COLLATE falls at the bottom + of the page; instructs NEWPAGE to use + 'br instead of .br + #NO_COLUMNS Don't print document in columns (boolean) + #NO_FN_MARKER Don't print footnote markers (boolean) + #NO_SHIM Should SHIM shim? (boolean) + #NO_SPACE When para spacing is active, instructs + PP not to add space after a quote or blockquote + #NO_TRAP_RESET Should we reset page traps? (boolean) + #NOT_YET_ADJUSTED Line on which a footnote was called has not yet + been adjusted by groff (boolean) + #NUM_AUTHORS # of authors mod 2 to test if odd or even + # of authors + #NUM_MISCS Number of args passed to MISC + #NUM_MISCS_COVER Number of args passed to MISC COVER + #NUM_MISCS_DOCCOVER Number of args passed to MISC DOC_COVER + #NUMBER_HEAD Are heads numbered? (boolean) + #NUMBER_PH Are paraheads numbered? (boolean) + #NUMBER_SH Are subheads numbered? (boolean) + #NUM_COLS Number of columns per page + #NUMBERED If set to 1, lets PARAHEAD know that + main- and subhead numbers have already been + prefixed to the parahead string + #NUM_FIELDS Incrementing register used to match + #TOTAL_FIELDS + #OK_PROCESS_LEAD Initial processing of TOC and endnote + leading is deferred until OK_PROCESS_LEAD=1 + #ORIGINAL_B_MARGIN The value for #B_MARGIN as set by the + macro B_MARGIN + #ORIG_DOC_LEAD DOC_LEAD before endnotes, bibliographies, tocs + #ORIG_L_LENGTH \\n[.l] before starting LISTs + #ORIGINAL_DOC_LEAD The lead for PRINT_STYLE 1 as set in + PRINTSTYLE; required so that PRINT_STYLE 1 + footnotes have an unadjusted lead of + 12 points + #OVERFLOW Signals to FOOTNOTE that some of the + footnote text won't fit on the page + #OVERFLOW_LEFT Does left margin note overflow? (boolean) + #OVERFLOW_RIGHT Does right margin note overflow? (boolean) + #P Page number for margin notes + #PAD_LIST_DIGITS<n> Pad LIST digits for LIST <n>? (boolean) + #PAGE_NUM_ADJ What to add to n% to get #PAGENUMBER + #PAGE_NUM_H_POS 1=left 2=CENTER 3=right; default=2 + #PAGE_NUM_COLOR Colorize pagenumbers? (boolean) + #PAGE_NUM_HYPHENS Print hyphens surrounding page numbers? + (boolean) + #PAGE_NUM_HYPHENS_SET Did user set (or unset) hyphens around page + numbers? (boolean) + #PAGE_NUM_POS_SET Did user set page number position? (boolean) + #PAGE_NUM_SET Test if PAGE_1_NUM was used to set 1st page + number + #PAGE_NUM_V_POS 1=top 2=bottom; default=2 + #PAGE_NUMS Print page numbers? (boolean) + #PAGE_POS Exact position on page during a diversion + (required for collecting footnotes inside + a diversion) + #PAGE_TOP \n[nl] after HEADER completes itself + #PAGENUM_STYLE_SET Did we set pagenumber style? (boolean) + #PAGENUMBER The page number + #PAGES Number of blank pages to output + #PAGINATE Are we paginating? (boolean) + #PAGINATE_TOC Is toc pagination on? (boolean) + #PAGINATE_WAS_ON Keeps track of pagination state while + outputting blank pages + #PAGINATION_STATE Saves pagination state in COLLATE for use in + START after a COLLATE + #PAGINATION_WAS_ON Was pagination on? - used in FINIS (boolean) + #PH_COLOR Colorize paraheads? (boolean) + #PH_INDENT Size of parahead indent + #PH_NUM Parahead number + #PP 0 at first para; auto-increments + #PP_AT_PAGE_BREAK # of last (incl. partial) para on page + #PP_INDENT How much to indent paras + #PP_SPACE Put space before paras? (boolean) + #PP_SPACE_SUSPEND Suspend para spacing for blockquotes and + epigraphs + #PP_STYLE_PREV In footnotes, stores PP style in effect + prior to invoking FOOTNOTE + #PP_STYLE Regular para=1; quote or epi para=2 + #PRE_COLLATE Set to 1 in COLLATE; prevents FAMILY + from clobbering a user-set DOC_FAMILY + #PREFIX_CH_NUM Prefix the chapter number to numbered + heads, subheads and/or paraheads? (boolean) + #PREV_FN_DEFERRED Was previous footnote deferred? (boolean) + #PRINT_PAGENUM_ON_PAGE_1 Should we print the page number on first + page of doc when footers are on? (boolean) + #PRINT_STYLE Typewrite=1, typeset=2 + #PT_SIZE_IN_UNITS Stored value of \n[.ps] from last time + PT_SIZE was called + #Q_AUTOLEAD Register created by QUOTE_AUTOLEAD + #Q_DEPTH Depth of quote + #Q_FITS Does this quote fit on one page/column? + (boolean) + #Q_LEAD Leading of quotes + #Q_LEAD_DIFF Difference between leading of running text + and the leading used in quotes/blockquotes + #Q_LEAD_REAL Leading of quotes and blockquotes saved at the + ends of their respective diversions + #Q_L_LENGTH Line length of quotes + #Q_OFFSET Page offset for quotes + #Q_OFFSET_VALUE Factor by which to multiply PP_INDENT to + offset quotes + #Q_PARTIAL_DEPTH The amount of a quote/blockquote that fits at + the bottom of a page when a quote/blockquote + spans pages + #Q_PP In PP, stores para # in QUOTE. Removed in + ENDQUOTE. + #Q_SPACE_ADJ The flexible amount of whitespace to add before + and after a quote/blockquote + #Q_TOP Vertical place on page that a quote starts + #QUOTE 1=PQUOTE, 2=BQUOTE + #QUOTE_COLOR Colorize quotes (poetic)? (boolean) + #QUOTE_LN Linenumber quotes? (boolean) + #RECTO_VERSO Switch HEADER_LEFT and HEADER_RIGHT on + alternate pages? (boolean) + ref*suppress-period Suppress period at end of ref field? (boolean) + ref*type Kind of reference we're building + #REF Was REF called? (boolean) + #REF_HY Hyphenate REFs? (boolean) + #REF_WARNING Have we issued a ref warning? (boolean) + #REPEAT Number of times to repeat linebreak + character + #RERUN_TRAPS Should we invoke TRAPS? (boolean) + #RESERVED_SPACE Just enough room to put 1 more line of + footnotes on the page + #RESET_EN_PP Holds value of register #EN_PP_INDENT + #RESET_EN_PP_INDENT Holds value of register #EN_PP_INDENT + #RESET_FN_COUNTERS 1 = "moved" footnote collected in a diversion + 2 = "deferred" fn collected in a diversion + #RESET_FN_NUMBER Should fn# start at 1 on every page? + (boolean) + #RESET_L_LENGTH Stores current line length when necessary + #RESET_PARA_SPACE Holds current value of boolean register + #PP_SPACE + #RESET_PP_INDENT Stores value of PP_INDENT when needed + #RESET_QUOTE_SPACING Stores value of boolean register + #FULLSPACE_QUOTES (used in endnotes) + #RESTORE_ADJ_DOC_LEAD Stores value of #ADJ_DOC_LEAD whenever needed + #RESTORE_B_MARGIN Stores #B_MARGIN whenever needed + #RESTORE_DOC_LEAD Stores value of current doc lead (used in + endnotes) + #RESTORE_HY Restore hyphenation after .][? (boolean) + #RESTORE_INDENT Store \n[.i] whenever needed + #RESTORE_L_LENGTH Stores \n[.l] whenever needed + #RESTORE_LN_NUM Should we restore line numbering? (boolean) + #RESTORE_OFFSET Page offset at moment footer trap is sprung; + not currently used + #RESTORE_TOC_PN_PADDING Saves #TOC_PN_PADDING in TOC prior to + processing $FIRST_DOC_TITLE + #RESTORE_UNDERLINE Instructs CODE OFF to restore underlining of + italics (TYPEWRITE) if underlining was + formerly on + #RIGHT_CAP_HEIGHT Cap height of right string in + headers/footers + #RULED Tells FOOTNOTE if a rule (or space has been + put above the first footnote on the page + #RUNON_FN_IN_DIVER If #LN=1, if we're in a (block)quote, instructs + FOOTNOTE to unformat diversion RUNON_FN_IN_DIVER + #RUNON_FOOTNOTES If #LN=1, instructs FOOTNOTE to unformat + diversion RUNON_FOOTNOTES + #RUN_ON Are we using run-on footnotes? (boolean) + #SAVED_DIVER_FN_COUNT In the case of a footnote inside a + diversion that should be treated as a + "normal" footnote, FOOTNOTE needs to + distinguish between a "normal" deferred + footnote (always the 1st footnote on the + page) and one that only looks as if + it should be deferred, when, in fact, + it's an overflow; this register lets + FOOTNOTE know whether the diversion + footnote is, in fact, the first on the + page. + #SAVED_DOC_LEAD Stored value of #DOC_LEAD (used in DEFAULTS after + a COLLATE) + #SAVED_FN_COUNT #FN_COUNT+1 prior to +#FN_COUNT; used + in FOOTNOTES while gathering fns inside + diversions + #SAVED_FN_COUNT_FOR_COLS #FN_COUNT_FOR_COLS+1 prior to + +#FN_COUNT_FOR_COLS; used in FOOTNOTES + while gathering fns inside diversions + #SAVED_FN_DEPTH_1 Footnote depth prior to adding footnote + diversion depth to FN_DEPTH; used when + footnote text will overflow + #SAVED_FN_DEPTH_2 Footnote depth after to adding footnote + diversion depth to FN_DEPTH; used when + footnote text will overflow + #SAVED_FN_NUMBER Stores current FN_NUMBER whenever needed + #SAVED_FOOTER_POS Position of FOOTER in DO_QUOTE (hack) + #SAVED_LEAD In FOOTER and DO_FOOTER, stores the + lead in effect prior to outputting + FOOTNOTES or performing either + PROCESS_FN_LEFTOVER or + PROCESS_FN_IN_DIVERSION; both the + diversion FOOTNOTES and the two macros + have, for PRINT_STYLE 2, an AUTOLEAD + call, which requires that an LS be + performed with the #SAVED_LEAD in + order to remove register #AUTO_LEAD or + #AUTO_LEAD_FACTOR. + #SAVED_UNDERSCORE_WEIGHT Stores underscore weight whenever needed + #SAVED_UNDERSCORE_WEIGHT_ADJ SAVED_UNDERSCORE_WEIGHT/2 + #SAVED_VFP Store variable footer position whenever needed + #SAVED_WEIGHT Stores weight given to RULE_WEIGHT whenever needed + #SAVED_WEIGHT_ADJ SAVED_UNDERSCORE_WEIGHT/2 + #SEP_TYPE Set to 1 if LIST separator is ( or [ or { + #SH_COLOR Colorize subheads? (boolean) + #SH_LEAD_ADJUST #DOC_LEAD/8 (TYPESET) or /2 (TYPEWRITE) + (used for subhead spacing) + #SH_NUM Subhead number + #SHIM Amount of lead required to advance to + next valid baseline + #SILENT_BQUOTE_LN "Silently" linenumber blockquotes? (boolean) + #SILENT_QUOTE_LN "Silently" linenumber quotes? (boolean) + #SINGLE_SPACE Is TYPEWRITE in single space mode? (boolean) + #SKIP_FOOTER If 1, instructs DO_FOOTER to do nothing + if B_MARGIN falls below FOOTER_MARGIN + #SLANT_MEANS_SLANT For TYPEWRITE. (boolean) + #SLANT_WAS_ON Keeps track of SLANT when it needs to go off + for a while + #SPACE_REMAINING Space remaining to footer trap; used to + decide whether or not to defer a footnote + #SPACE_TO_FOOTER Distance to FOOTER trap; used to calculate + available space when FOOTNOTE is called inside + a diversion + #SR_ADJ_FACTOR An adjustment factor that compensates + for the fact that #SPACE_REMAINING + sometimes reports a fractionally larger + space than is actually available for + footnote text. + #START If 1, signals completion of START + #START_FOR_FOOTERS Toggle set in START; signals to + PRINT_HDRFTR that START has been invoked, + allowing PRINT_HDRFTR to decide whether or + not to print a footer on page 1 + #START_FOR_MNinit If 1, defer processing MN_INIT until #START + #STORED_PP_INDENT Temporarily holds value of #PP_INDENT + #SUBTITLE_COLOR Colorize subtitle? (boolean) + #SUBTITLE_COVER_NUM Incrementing register used to define strings + $SUBTITLE_COVER_<n> + #SUBTITLE_DOCCOVER_NUM Incrementing register used to define strings + $SUBTITLE_DOCCOVER_<n> + #SUBTITLE_NUM Incrementing register used to define strings + $SUBTITLE_<n> + #SUBTITLES Holds number of subtitle items + #SUITE Current page number (for letters) + #SUP_PT_SIZE Point size of superscript + #SUSPEND_PAGINATION Suspend pagination prior to endnotes? + #SWITCH_HDRFTR Switch HDRFTR_LEFT and HDRFTR_RIGHT? + (boolean) + #T_MARGIN_LEAD_ADJ \n[.v]-12000; ensures critically accurate + placement of first lines on pages when + doc processing is not being used and + a T_MARGIN has been set + #TAB_OFFSET# "#" at the end is from $CURRENT_TAB + #TERMINATE Has TERMINATE been called? (boolean) + #TITLE_COLOR Colorize title? (boolean) + #TITLE_NUM Number of title items + #TOC_AUTHORS Whether to append author(s) to toc doc + title entries (boolean) + #TOC_ENTRY_PN Current page number when a toc entry is + collected + #TOC_FIRST_PAGE If 1, tells PRINT_PAGE_NUMBER that this + is the first page of the toc + #TOC_LEAD Leading of toc pages + #TOC_PN_PADDING Max. # of placeholders for toc entries + page numbers + #TOC_PS Point size of toc pages + #TOC_RV_SWITCH Switch L/R margins of toc pages + #TOC_HEAD_INDENT Indent of toc head entries + #TOC_HEAD_SIZE_CHANGE ps in/decrease of toc head entries + #TOC_PH_INDENT Indent of toc parahead entries + #TOC_PH_SIZE_CHANGE ps in/decrease of toc parahead entries + #TOC_SH_INDENT Indent of toc subhead entries + #TOC_SH_SIZE_CHANGE ps in/decrease of toc subhead entries + #TOC_TITLE_INDENT Indent of toc doc title entries + #TOC_TITLE_SIZE_CHANGE ps in/decrease of toc doc title entries + #TOTAL_FIELDS Total number of letter header fields + #TRAP \n[.t]-1 (used in DO_QUOTE) + #UNDERLINE_ITALIC For TYPEWRITE. (boolean) + #UNDERLINE_ON Was UNDERLINE called? (boolean) + #UNDERLINE_QUOTES Was UNDERLINE_QUOTES called? (boolean) + #UNDERLINE_QUOTE Underline pquotes? (boolean) + #UNDERLINE_SLANT For TYPEWRITE. (boolean) + #UNDERLINE_WAS_ON In HEADER to re-enable running text + UNDERLINE (boolean) + #USER_DEF_HDRFTR_CENTER Has user defined hdrftr center? (boolean) + #USER_DEF_HDRFTR_LEFT Has user defined hdrftr left? (boolean) + #USER_DEF_HDRFTR_RIGHT Has user defined hdrftr right? (boolean) + #USER_DEF_HEADER_CENTER User defined CENTER title? (boolean); + used in COPYSTYLE + #USER_DEF_HEADER_LEFT User defined CENTER title? (boolean); + used in COPYSTYLE + #USER_DEF_HEADER_RIGHT User defined CENTER title? (boolean) + used in COPYSTYLE + #USERDEF_HDRFTR User defined single string recto/verso + header/footer? (boolean) + #USERDEF_HDRFTR_RECTO_QUAD 1=left, 2=CENTER, 3=right + #USERDEF_HDRFTR_VERSO_QUAD 1=left, 2=CENTER, 3=right + #VARIABLE_FOOTER_POS Wandering trap position for processing + footnotes and footers; pos depends on number of + footnotes + #VISUAL_B_MARGIN Set in TRAPS, what \n[nl] would report + on the last line of running text before + FOOTER is sprung. + #VFP_DIFF #FN_DEPTH minus #SAVED_FN_DEPTH; the + number of footnote lines that will fit + on the page when there will be over, and + therefore the amount by which to raise + the VFP for footnotes with overflow after + the 1st footnote. + y Vertical position stored with mk in hdrftrs. + ++++STRINGS+++ + + $1ST_LETTER First letter of first arg to LIST + $ADJUST_BIB_LEAD 2nd arg to BIBLIOGRAPHY_LEAD; if not blank + adjust bib leading + $ADJUST_EN_LEAD 2nd arg to ENDNOTE_LEAD; if not blank adjust + endnote leading + $ADJUST_TOC_LEAD 2nd arg to TOC_LEAD; if not blank adjust + toc leading + $ATTRIBUTE_COLOR Attribution string color + $ATTRIBUTE_STRING Attribution string in doc header + $ATTRIBUTE_STRING_COVER Attribution string on cover + $ATTRIBUTE_STRING_DOCCOVER Attribution string on doc cover + $AUTHOR_<n> Document author(s) + $AUTHOR The author, or the first argument + passed to .AUTHOR ($AUTHOR_1) + $AUTHOR_COLOR Author color + $AUTHOR_COVER_<n> Author(s) on cover + $AUTHOR_DOCCOVER_<n> Author(s) on doc cover + $AUTHOR_FAM Family to use for author in doc header + $AUTHOR_FT Font to use for author in doc header + $AUTHOR_SIZE_CHANGE ps in/decrease of author in doc header + $AUTHOR_PT_SIZE Absolute ps of authors + $AUTHORS Comma-separated concatenated + string of all args passed to .AUTHOR + $BIB_FAM Bibliography page family + $BIB_FT Bibliography page font + $BIB_LEAD Base leading for bibliographies + $BIB_LIST_SEPARATOR Separator between enumerator and text + when outputting bibliographies in + LIST style + $BIB_LIST_PREFIX Prefix before enumerator when outputting + bibliographies in LIST style + $BIB_PN_STYLE Format of bibliography page numbers + $BIB_QUAD + $BIB_SPACE Post entry space for bibliographies + $BIB_STRING Bibliography title string + $BIB_STRING_FAM Bib title family + $BIB_STRING_FT Bib title font + $BIB_STRING_QUAD Bib title quad + $BIB_STRING_RULE_GAP Distance between the underscores when + BIB_STRING (bib first-page header) is + double-underlined + $BIB_STRING_SIZE_CHANGE Bib title size (+ or -) + $BIB_STRING_UNDERLINE_GAP Distance between BIB_STRING text and (first) + underline rule + $BQ_LN_GUTTER Gutter between line numbers and bquotes in + bquotes + $BQUOTE_COLOR Blockquote color + $BQUOTE_FAM Family to use for blockquotes + $BQUOTE_FT Font to use for blockquotes + $BQUOTE_QUAD Quad value for blockquotes + $BQUOTE_SIZE_CHANGE ps in/decrease of blockquotes + $BX_COLOR Box color + $BX_DEPTH Box depth + $BX_INDENT Box left margin starting position + $BX_WEIGHT Box rule weight + $BX_WIDTH Box width + $CENTER_TITLE What to put in the middle of header + title + $CH_NUM Chapter number (as a string) + $CHAPTER The chapter number + $CHAPTER_STRING What to print whenever the word + "chapter" is required + $CHAPTER_TITLE Concatenated args passed to CHAPTER_TITLE + $CHAPTER_TITLE_<n> Chapter title items + $CHAPTER_TITLE_FAM Family of chapter title + $CHAPTER_TITLE_FT Font of chapter title + $CHAPTER_TITLE_SIZE_CHANGE ps in/decrease of chapter title + $CHAPTER_TITLE_PT_SIZE Absolute ps of chapter title + $CHAPTER_TITLE_COLOR Color of chapter title + $CL_COLOR Circle (ellipse) color + $CL_DEPTH Circle (ellipse) depth + $CL_INDENT Circle (ellipse) left margin starting + position + $CL_WEIGHT Circle (ellipse) rule weight + $CL_WIDTH Circle (ellipse) width + $CLOSE_INDENT Argument passed to CLOSING_INDENT + $CODE_FAM Family to use with CODE + $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 + $FIRST_DOC_TITLE 1st doc's title captured in COLLATE + FN_MARK Inline, gets #FN_MARK ( \n[ln] ) + $FN_CLOSE_BRACKET Close bracket for line-number identified + footnotes + $FN_FAM Family used in footnotes + $FN_FT Font used in footnotes + $FN_LINENUMBER String to print before footnotes when + line-numbering enabled for footnotes + $FN_LN_SEP Separator after line-number identified + footnotes + $FN_OPEN_BRACKET Open bracket for line-number identified + footnotes + $FN_QUAD Quad used in footnotes + $FN_SIZE_CHANGE ps in/decrease of footnotes + $FOOTNOTE_COLOR Footnote color + $FTR_RECTO_QUAD Quad direction of footer recto + $FTR_RECTO_STRING String for footer recto + $FTR_VERSO_QUAD Quad direction of footer verso + $FTR_VERSO_STRING String for footer verso + $HDR_RECTO_QUAD Quad of header recto + $HDR_RECTO_STRING String for header recto + $HDR_VERSO_QUAD Quad of header verso + $HDR_VERSO_STRING String for header verso + +**Note: "header", in the descriptions below, means either headers or footers + $HDRFTR_CENTER What to put in CENTER part of headers; + default doctype + $HDRFTR_CENTER_COLOR Color of CENTER part of headers + $HDRFTR_CENTER_FAM Family of CENTER part of headers + $HDRFTR_CENTER_FT Font of centre part of headers + $HDRFTR_CENTER_NEW HDRFTR_CENTER after the start of TOC; + defined in HDRFTR_CENTER if + HDRFTR_CENTER is called as + FOOTER_CENTER + $HDRFTR_CENTER_OLD HDRFTR_CENTER just prior to start of + TOC; defined in HDRFTR_CENTER if + HDRFTR_CENTER is called as + FOOTER_CENTER + $HDRFTR_CENTER_SIZE_CHANGE ps in/decrease of centre title in + headers + $HDRFTR_COLOR Color of headers/footers + $HDRFTR_FAM Family to use in headers + $HDRFTR_LEFT_COLOR Color of LEFT part of headers + $HDRFTR_LEFT_FAM Family of left part of headers + $HDRFTR_LEFT_FT Font of left part of headers + $HDRFTR_LEFT_SIZE_CHANGE ps in/decrease of author in headers + $HDRFTR_LEFT What to put in left part of headers; + default author + $HDRFTR_RIGHT_COLOR Color of RIGHT part of headers + $HDRFTR_RIGHT_FAM Family of right part of headers + $HDRFTR_RIGHT_FT Font of right part of headers + $HDRFTR_RIGHT_SIZE_CHANGE ps in/decrease of right part of + headers + $HDRFTR_RIGHT What to put in right part of headers; + default title + $HDRFTR_RULE_COLOR Color of header rule + $HDRFTR_SIZE_CHANGE ps in/decrease of headers + $HDRFTR_TMP_SIZE_CHANGE_SWITCH Temporarily holds + HDRFTR_LEFT_SIZE_CHANGE if + #SWITCH_HDRFTRS=1 + $HDRFTR_TMP_SWITCH Temporarily holds HDRFTR_LEFT if + #SWITCH_HDRFTRS=1 + $HDRFTR_TMP_COLOR_SWITCH Temporarily holds HDRFTR_LEFT_COLOR if + #SWITCH_HDRFTRS=1 + $HEAD_COLOR Head color + $HEAD_FAM Family to use for section titles + $HEAD_FT Font to use for section titles + $HEAD_QUAD Quad value of section titles + $HEAD_SIZE_CHANGE ps in/decrease of section titles + $HEAD_UNDERLINE_GAP Distance between a head and the underline + $HYPHEN Vertically adjusted hyphen used around page + numbers + $LHS Holds digits on the left side of the decimal + in weight arg passed to RULE_WEIGHT + $LINEBREAK_CHAR Character that marks line breaks + $LINEBREAK_CHAR_V_ADJ +|- amount by which to raise/lower + linebreak character + $LAST_CHAR Temporary string used to discover whether + user has remembered to put a digit after + ROMAN or roman in arg to LIST + $LINEBREAK_COLOR Linebreak color + $LIST_ARG_1 The first arg to LIST (minus digits if + ROMAN or roman + $LN_COLOR Linenumber color + $LN_FAMILY Linenumber family + $LN_FONT Linenumber font + $LN_GUTTER Gutter to leave between line numbers + and text + $LN_INC 2nd arg to NUMBER_LINES as a string + $LN_NUM 1st arg to NUMBER_LINES as a string + $LN_SIZE_CHANGE ps in/decrease of linenumbers + $MISC_<n> 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 + $RESTORE_SS_VAR Saves \*[$SS_VAR] for use with ref*build + #REVISION The revision number (string valued) + $REVISION_STRING What to print whenever the word + "revision" is required + $RHS Holds digits on the right side of the decimal + in weight arg passed to RULE_WEIGHT + $RL_COLOR Rule color (DRH/DRV) + $RL_DEPTH Rule depth (DRH/DRV) + $RL_INDENT Left start position of rule (DRH/DRV) + $RL_LENGTH Rule length (DRH/DRV) + $RL_WEIGHT Rule weight (DRH/DRV) + $SAVED_COPYRIGHT Temporarily holds string in $COPYRIGHT + $SAVED_RULE_GAP Temporarily holds string in $RULE_GAP + $SAVED_PP_FT $PP_FT in effect at start of + .COLLATE; tested for and removed + in .PP + $SH_FAM Family to use in subheads + $SH_FT Font to use in subheads + $SH_SIZE_CHANGE ps in/decrease of subheads + $SH_COLOR Subhead color + $SIG_SPACE Arg passed to macro, SIGNATURE_SPACE + $SUBTITLE Concatenated args passed to SUBTITLE + $SUBTITLE_<n> Subtitle items for doc header + $SUBTITLE_COLOR Color of subtitle + $SUBTITLE_COVER_<n> Subtitle items for cover + $SUBTITLE_DOCCOVER_<n> Subtitle items for doc cover + $SUBTITLE_FAM Family to use for subtitle in doc + header + $SUBTITLE_FT Font to use for subtitle in doc header + $SUBTITLE_SIZE_CHANGE ps in/decrease of subtitle + $SUBTITLE_PT_SIZE Absolute ps of subtitle + $SUITE The #SUITE number register + $TITLE Concatenated args pass to TITLE + $TITLE_<n> Title items + $TITLE_COLOR Color of title + $TITLE_FAM Family to use for title in doc header + $TITLE_FT Font to use for title in doc header + $TITLE_PT_SIZE Absolute point size of title in docheader + $TITLE_SIZE_CHANGE ps in/decrease of title in doc header + $TOC_AUTHORS What to print after toc doc title entry + if #TOC_AUTHORS=1 + $TOC_FAM Family to use on toc pages + $TOC_HEAD_FAM Family of toc head entries + $TOC_HEAD_FT Font of toc head entries + $TOC_HEAD_ITEM A head as collected for TOC_ENTRIES + $TOC_HEADER_FAM Family to use for "Contents" + $TOC_HEADER_FT Font to use for "Contents" + $TOC_HEADER_QUAD Quad direction of "Contents" + $TOC_HEADER_SIZE ps in/decrease of "Contents"**** + $TOC_HEADER_STRING Header string of first toc page + $TOC_LEAD Leading of toc pages + $TOC_PH_ITEM Toc parahead entry + $TOC_PN Sets up toc leaders + entry pn + (typeset) + $TOC_PN_FAM Family for toc entries page numbers + $TOC_PN_FT Font for toc entries page numbers + $TOC_PN_SIZE_CHANGE ps in/decrease of toc entries page + numbers + $TOC_PN_STYLE Page-numbering style of toc pages + $TOC_PN_TYPEWRITE Sets up toc leaders + entry pn + (typewrite) + $TOC_PH_FAM Family of toc parahead entries + $TOC_PH_FT Font of toc parahead entries + $TOC_PARAHEAD_ITEM A parahead collected for TOC_ENTRIES + $TOC_SH_FAM Family of toc subhead entries + $TOC_SH_FT Font of toc subhead entries + $TOC_SH_ITEM A subhead collected for TOC_ENTRIES + $TOC_TITLE_FAM Family of toc doc title entries + $TOC_TITLE_FT Font of toc doc title entries + $TOC_TITLE_ITEM Toc document title item + $USER_SET_TITLE_ITEM User defined toc doc title entry as + set by TOC_TITLE_ENTRY + $UR_PAGINATION_STYLE Pagination style prior to endnotes + $USERDEF_HDRFTR_RECTO User defined header/footer recto string + $USERDEF_HDRFTR_VERSO User defined header/footer verso string + ++++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 + BREAK_BLOCKQUOTE BREAK_QUOTE + BREAK_CITATION BREAK_QUOTE + BREAK_CITE BREAK_QUOTE + CITATION BLOCKQUOTE + CITE BLOCKQUOTE + COL_BREAK COL_NEXT + DOC_FAM DOC_FAMILY + DOC_LLENGTH DOC_LINE_LENGTH + DOC_L_LENGTH DOC_LINE_LENGTH + DOC_L_MARGIN DOC_LEFT_MARGIN + DOC_LMARGIN DOC_LEFT_MARGIN + DOC_LS DOC_LEAD + DOC_PS DOC_PT_SIZE + DOC_R_MARGIN DOC_RIGHT_MARGIN + DOC_RMARGIN DOC_RIGHT_MARGIN + ENDNOTE_STRING_UNDERSCORE ENDNOTE_STRING_UNDERLINE + ENDNOTE_TITLE_UNDERSCORE ENDNOTE_TITLE_UNDERLINE + FOOTER_CENTER_CAPS HDRFTR_CENTER_CAPS + FOOTER_CENTER HDRFTR_CENTER + FOOTER_CENTRE_CAPS HDRFTR_CENTER_CAPS + FOOTER_CENTRE HDRFTR_CENTER + FOOTER_LEFT_CAPS HDRFTR_LEFT_CAPS + FOOTER_LEFT HDRFTR_LEFT + FOOTER_PLAIN HDRFTR_PLAIN + FOOTER_RECTO HDRFTR_RECTO + FOOTER_RIGHT_CAPS HDRFTR_RIGHT_CAPS + FOOTER_RIGHT HDRFTR_RIGHT + FOOTER_RULE_GAP HDRFTR_RULE_GAP + FOOTER_RULE HDRFTR_RULE + FOOTER_VERSO HDRFTR_VERSO + HDRFTR_RULE_INTERNAL HDRFTR_RULE + HEADER_CENTER_CAPS HDRFTR_CENTER_CAPS + HEADER_CENTER HDRFTR_CENTER + HEADER_CENTRE_CAPS HDRFTR_CENTER_CAPS + HEADER_CENTRE HDRFTR_CENTER + HEADER_LEFT_CAPS HDRFTR_LEFT_CAPS + HEADER_LEFT HDRFTR_LEFT + HEADER_PLAIN HDRFTR_PLAIN + HEADER_RECTO HDRFTR_RECTO + HEADER_RIGHT_CAPS HDRFTR_RIGHT_CAPS + HEADER_RIGHT HDRFTR_RIGHT + HEADER_RULE_GAP HDRFTR_RULE_GAP + HEADER_RULE HDRFTR_RULE + HEADER_VERSO HDRFTR_VERSO + PAGENUM PAGENUMBER + PAGINATION PAGINATE + PP_FT PP_FONT + PRINT_FOOTNOTE_RULE FOOTNOTE_RULE + SWITCH_FOOTERS SWITCH_HDRFTR + SWITCH_HEADERS SWITCH_HDRFTR + TOC_LS TOC_LEAD + TOC_PS TOC_PT_SIZE + ++++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 + + +

+ + + + + + + +

+ +

+ + + + diff --git a/contrib/mom/momdoc/stylesheet.css b/contrib/mom/momdoc/stylesheet.css new file mode 100644 index 00000000..3a0b6f1c --- /dev/null +++ b/contrib/mom/momdoc/stylesheet.css @@ -0,0 +1,648 @@ +/* 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 ; } + +.version /* version number for top of toc.html */ +{ + font-size: 90% ; + text-align: center ; +} + +.page /* Page setup: page color, size and border */ +{ + width: 760px ; + 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 ; +} + +/* Heads */ + +h1.docs +{ + font-family: arial,sans-serif ; + font-size: 175% ; + text-align: center ; + color: #002b56 ; + background-color: #e2f1ff ; + outline: solid 1px #99cccc ; + padding: 6px ; +} +h2.docs +{ + margin-bottom: -.25em ; + font-size: 120% ; + 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 +{ + margin-bottom: -.5em ; + color: #000056 ; +} +h4.doc-param-macros +{ + margin-top: -.5em ; +} +h4.arg-list +{ + margin-top: -.5em ; +} +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 ; + width: 736px ; + max-width: 736px ; + border: solid 1px #302419 ; + padding-top: 5px ; + padding-bottom: 3px ; + padding-left: 12px ; + padding-right: 12px ; + background-color: #ffffff ; + white-space: nowrap ; + overflow: auto ; +} +.box-code +{ + display: block ; + width: 679px ; + max-width: 679px ; + 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: 100% ; + 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: 100% ; + 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: 50% ; + margin-left: -6px ; +} +.mini-toc-col-2 +{ + float: left ; + width: 50% ; + clear: right ; +} + +/* 3-column mini-toc column defs */ +.col-1-definitions +{ + float: left ; + width: 32% ; + height: 53em ; + padding-bottom: 9px; + background-color: #e2deb5 ; + margin-right: 2% ; +} +.col-2-definitions +{ + float: left ; + width: 32% ; + height: 53em ; + padding-bottom: 9px; + background-color: #e2deb5 ; + margin-right: 2% ; +} +.col-3-definitions +{ + float: left ; + width: 32% ; + height: 53em ; + padding-bottom: 9px; + background-color: #e2deb5 ; + 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 ; + 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-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: 100% ; +} +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: #fafdff ; + 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 ; +} diff --git a/contrib/mom/momdoc/tables-of-contents.html b/contrib/mom/momdoc/tables-of-contents.html new file mode 100644 index 00000000..b27bc22c --- /dev/null +++ b/contrib/mom/momdoc/tables-of-contents.html @@ -0,0 +1,747 @@ + + + + + + + + Mom -- Document processing, tables of contents + + + + + + + +

+ + + + + + + +

Next: Bibliographies and references

+ +

Tables of contents

+ +

Introduction to tables of contents +
- Tables of contents behaviour
- Using psselect to put the table of contents where you want it
Instruct mom to output a table of contents
Control macros for tables of contents +
- Table of contents control macros and defaults

+ +

Introduction to tables of contents

+ +

+Want a table of contents for your document? Easy. Just enter +
+ + .TOC + +as the very last macro of your document file. Mom will have picked +up all document titles (in +collated +documents), all heads, subheads, and paragraph heads, as well as +any endnotes pages that have been output, and assigned them the +appropriate page number (and page numbering style). Talk about a +no-brainer! +

+ +

+That said, tables of contents 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. Mom is all about +simplicity and flexibility. +

+ +

Tables of contents 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. By default, each type of entry (e.g. a head +or a subhead) is set in a different font as well. If any of +heads, subheads or paragraph heads are numbered in the body of the +document, they are also numbered in the table of contents. Head, +subhead and paragraph head numbering in the table of contents is +not concatenated, as it is in the body of the document, +because it's visually redundant in a table of contents. +

+ +

+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 type of entry (i.e. title, head, +subhead, paragraph head). Furthermore, the page numbering style +can be changed, as can the amount of visual space reserved for page +reference numbers. +

+ +

Using `psselect` to put the table of contents where you want it

+ +

+Mom always outputs the table of contents at the end of a document. +While this is desirable for some language conventions—French, +for example—it is not desirable for others. +

+ +

+If you’d like your tables of contents near the start of +your document, you have two options: re-arrange the pages by hand +(okay for one or two hard copies of the document), or use the +psselect programme provided by the psutils suite +of tools (which you may have to install as a package from your +distribution if it is not already on your system). +

+ +

+The procedure for using psselect to put the table of +contents near the beginning of the document begins by you +determining how many pages it contains. You can +do this by previewing the document with the PostScript 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 re-arranged. 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 + +

+ + + + +

Instruct mom to output a table of contents

+ +

+Macro: TOC +

+ +

+If you want a table of contents, just place .TOC at the +very end of your document. Mom takes care of the rest. +

+ +

Control macros for tables of contents

+ +

+ERRATUM: In versions of mom prior to +1.3-e_3, the documentation incorrectly stated that table of contents +control macros could go anywhere in a mom file prior to invoking +.TOC. +

+ +

+In fact, table of contents control macros must come before +.START. +

+ +

Table of contents control macros and defaults

+ +

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
Table of contents page numbering +
- PAGINATE_TOC – turn table of contents pagination on or off
- TOC_PAGENUM_STYLE – table of contents page numbering style
Changing the table of contents header (title), string and style +
- Changing the header (title) string +
  - Table of contents header (title) string control macros and defaults
Changing the style of table of contents entries and page number references +
Additional table of contents control macros +

+ +

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 +(title) 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. Table of contents 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. Changing the table of contents header (title) string and style

+ +

+The table of contents header string is the title that appears at to 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" + +

+ +

Table of contents header string (title) control macros and defaults

+ +

+ +.TOC_HEADER_FAMILY default = prevailing doc family +.TOC_HEADER_FONT default = bold +.TOC_HEADER_SIZE default = +4 +.TOC_HEADER_QUAD default = left + +

+ +

4. Changing the style of table of contents entries and page number references

+ +

+“Entries” refers to titles in +collated +documents +(TITLE) +, heads +(HEAD), +subheads +(SUBHEAD), +and paragraph heads +(PARAHEAD) +as they appear in the table of contents. Their style is managed by +the usual +control macros, +which take the form TOC_<ELEMENT>_<SPEC> +(e.g. TOC_HEAD_FAMILY or TOC_SUBHEAD_INDENT). +

+ +

+“Page number references” means the page numbers associated with +entries. They take the form TOC_PN_<SPEC>. +

+ +

+The following is a list of the control macros for table of contents +entries, along with their defaults. +

+ +

+Note: +The table of contents _INDENT +macros set an absolute indent, relative to nothing, and therefore +require an appended +unit of measure. +

+ + + +.TOC_TITLE_FAMILY default = prevailing doc family +.TOC_TITLE_FONT default = bold italic +.TOC_TITLE_SIZE default = +0 +.TOC_TITLE_INDENT default = 0 for TYPESET and TYPEWRITE + + +.TOC_HEAD_FAMILY default = prevailing doc family +.TOC_HEAD_FONT default = bold +.TOC_HEAD_SIZE default = +.5 +.TOC_HEAD_INDENT default = 18p for TYPESET; 2m for TYPEWRITE + + +.TOC_SUBHEAD_FAMILY default = prevailing doc family +.TOC_SUBHEAD_FONT default = roman +.TOC_SUBHEAD_SIZE default = +0 +.TOC_SUBHEAD_INDENT default = 30p for TYPESET; 4m for TYPEWRITE + + +.TOC_PARAHEAD_FAMILY default = prevailing doc family +.TOC_PARAHEAD_FONT default = italic +.TOC_PARAHEAD_SIZE default = +0 +.TOC_PARAHEAD_INDENT default = 42p for TYPESET; 6m for TYPEWRITE + +.TOC_PN_FAMILY default = prevailing doc family +.TOC_PN_FONT default = roman +.TOC_PN_SIZE default = +0 + +

+ +

5. Additional table of contents control macros

+ +

+The following four macros allow you to +

instruct mom to append author(s) to TITLE entries
alter the wording of TITLE entries
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: 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 +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. +

+ +

+ + + + + + + + +

Next: Bibliographies and references

+ +

+ + + + + diff --git a/contrib/mom/momdoc/toc.html b/contrib/mom/momdoc/toc.html new file mode 100644 index 00000000..ef0b03cb --- /dev/null +++ b/contrib/mom/momdoc/toc.html @@ -0,0 +1,393 @@ + + + + + + + + Mom, version 1.5-e -- Table of Contents + + + + + + + +

+ +

+ mom, version 1.5-d +

+ +

+ The table of contents has grown quite large. To ease navigation, + click on any link in the + Quick Table of Contents + to go to the corresponding entry in the the + Full Table of Contents. +

+ +

+ Alternatively, if you've been using mom for a while, you might + prefer the + Quick Reference Guide. +

+ +

+ + + +

Quick Table of Contents

+ +

INTRODUCTORY STUFF

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
Preliminary document setup
Behaviour of the typesetting macros during document processing
The document element tags – heads, paragraphs, subheads, footnotes, etc.
Inserting images into a document
Page headers and footers
Pagination
Recto/verso printing and collating
Cover pages
Tables of contents
Bibliographies and references
Writing letters +
Quick reference guide
Appendices
Reserved words (macros, strings, registers)

+ +

+ + + +

Full Table of Contents

+ +

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 Paper and 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 +
- 5.2.1 Important note on leading/spacing and bottom margins +
  - 5.2.1.1 The SHIM macro – to get document leading back on track
5.3 PRELIMINARY DOCUMENT SETUP +
- 5.3.1 Tutorial – setting up a mom document
- 5.3.2 The reference macros – meta-information 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.3 The docstyle macros – general appearance; what kind of document you're creating, and how you want it to look overall +
  - 5.3.3.1 DOCTYPE – the kind of document
  - 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 Establishing type and formatting parameters before START +
  - 5.3.5.1 Use of the typesetting macros before START +
    - – 5.3.5.1.1 Including (sourcing) style sheets and files
    - – 5.3.5.1.2 Initializing colours
  - 5.3.5.2 DOC_LEAD_ADJUST – adjust document + leading + to fill pages +
    - – 5.3.5.2.1 SHIM – macro to get document leading back on track
  - 5.3.5.3 Managing the document header
  - 5.3.5.4 COLUMNS – setting documents in columns
- 5.3.6 Changing basic type and formatting parameters after START +
  - 5.3.6.1 Behaviour of the typesetting macros during document processing
  - 5.3.6.2 Post-START global style change macros +
    - – Macro list
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 Main heads
- 5.4.5 Subheads
- 5.4.6 Paragraph heads
- 5.4.7 Linebreaks – author linebreaks (section breaks)
- 5.4.8 Quotes – line for line poetic quotes or unformatted, verbatim text (e.g. blocks of code)
- 5.4.9 Blockquotes – cited material
- 5.4.10 Code – inserting code snippets
- 5.4.11 Lists – nested lists
- 5.4.12 Line numbering
- 5.4.13 Footnotes
- 5.4.14 Endnotes
- 5.4.15 Margin notes
- 5.4.16 Document termination string – FINIS
5.5 INSERTING IMAGES
5.6 PAGE HEADERS AND FOOTERS +
5.7 PAGINATION +
5.8 RECTO/VERSO PRINTING, COLLATING +
- 5.8.1 Introduction to recto/verso printing +
  - 5.8.1.1 Macro list
- 5.8.2 Introduction to collating +
  - 5.8.2.1 The COLLATE macro
5.9 COVER PAGES
5.10 TABLES OF CONTENTS +
5.11 BIBLIOGRAPHIES AND REFERENCES
5.12 WRITING LETTERS +

6. QUICK REFERENCE GUIDE

7. APPENDICES

7.1 Notes on the documentation
7.2 Adding PostScript fonts to groff +
- 7.2.1 How to create a PostScript font for use with groff
7.3 Some reflections on mom
7.5 List of reserved words + – complete list of macros, registers, strings, aliases and diversions
7.5 Contact the author

+ +

+ + + + + diff --git a/contrib/mom/momdoc/typesetting.html b/contrib/mom/momdoc/typesetting.html new file mode 100644 index 00000000..39acb714 --- /dev/null +++ b/contrib/mom/momdoc/typesetting.html @@ -0,0 +1,4924 @@ + + + + + + + + Mom -- Typesetting Macros + + + + + + + +

+ + + + + + + +

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, +heads, 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. Groff has defaults for these, +but I recommend setting them at the top of your files anyway unless +you’re using mom’s +document processing macros +and are content with her defaults. +

+ +

+The +PAPER +macro provides a shortcut for setting the page to the correct +dimensions for a number of 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

+ +

+Mom’s macros for setting up the desired size of printer sheets +tell mom and groff about the page dimensions, but not the driver +responsible for generating the final PostScript file. You must take +care of this yourself. +

+ +

+If you routinely print documents on the same size paper (you +probably do), the easiest way to make sure the PostScript driver +knows about your papersize is to edit the file +
+ + <path to groff>/font/devps/DESC + +In it, you will see a line that reads: + + papersize <papersize> + +Change <papersize> to the name of your papersize +(e.g. a4, letter, legal, etc.; a full list of valid named papersizes +that can be used in DESC is found in man papersize). If +your routine papersize is non-standard (i.e. doesn’t have a +“name”) you can give the dimensions for your papersize, +separated by a comma. The dimensions must have a +unit of measure +appended. Valid units of measure for papersize are +inches (i), +centimeters (c), +picas (P) and +points (p). +For example, to set up a routine papersize of 8 inches by 10 inches, +the line would look like this: +
+ + papersize 8i,10i + +Having set up your routine papersize, if you occasionally need to +print on sheets that do not conform to its dimensions, you must, in +addition to setting the page dimensions in your mom file, invoke +groff on the command line with the -P-p<papersize> +option. +

+ +

+For example, suppose your routine papersize is “letter”, +and you need to print something on a legal-sized sheet. After +telling mom about the legal-size sheet (with either +PAGELENGTH +and +PAGEWIDTH +or +PAPER, +or +PAGE) +in your mom file, when you invoke groff to process the file, the +command would look like this: +
+ + groff -mom -P-plegal + +

+ +

+Consult man groff, man grops and man +groff-font for additional information concerning papersizes, +as well as information on printing in “landscape” +orientation. +

+ +

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

+ +

+PAPER provides a convenient way to set the page 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 + +Please read the +Important note on page dimensions and papersize +for information on ensuring groff respects your PAPER size. +

+ + + +

Left margin

+ +

+Macro: L_MARGIN <left margin> +

+• Requires a unit of measure +

+ +

+L_MARGIN establishes the distance from the left edge of the printer +sheet at which you want your type to start. It may be used any +time, and remains in effect until you enter a new value. +

+ +

+Left indents +and +tabs +are calculated from the value you pass to L_MARGIN, hence it’s +always a good idea to invoke it before starting any serious +typesetting. A unit of measure is required. Decimal fractions are +allowed. Therefore, to set the left margin at 3 picas (1/2 inch), +you’d enter either +
+ + .L_MARGIN 3P + +or + + .L_MARGIN .5i + +If you use the macros +PAGE, +PAGEWIDTH +or +PAPER +without invoking L_MARGIN (either before or afterwards), mom +automatically sets L_MARGIN to 1 inch. +

+ +

+Note: L_MARGIN behaves in a special way +when you’re using the +document processing macros. +See +Typesetting macros 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. Obviously, it can’t make the calculation if +it 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 +START. +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 invoke .PAGE with a top margin +argument, any macros you invoke after .PAGE will almost +certainly move the +baseline +of the first line of text down by one linespace. To compensate, do +
+ + .RLD 1v + +immediately before entering any text, or, if it’s feasible, +make PAGE the last macro you invoke prior to entering text. +

+ +

+Please read the +Important note on page dimensions and papersize +for information on ensuring groff respects your PAGE dimensions and +margins. +

+ + + +

Start a new page

+ +

+Macro: NEWPAGE +

+ +

+Whenever you want to start a new page, use NEWPAGE, by itself with +no argument. Mom will finish up processing the current page and move +you to the top of a new one (subject to the top margin set with +T_MARGIN). +

+ +

+Experts: +Prior to version 1.1.9, NEWPAGE was simply an alias of +.bp. As of 1.1.9, NEWPAGE, is its own mom macro. While +the new macro should be backwardly compatible with documents created +using pre-1.1.9 moms, I suggest that from this version onward, if +you were in the habit of using .bp whenever you wanted to +break to a new page, you now begin to use NEWPAGE instead. +

+ +

+ + + +

Basic typesetting parameters

+ +

+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 number of PostScript families, each +identified by a 1-, 2-or 3-letter mnemonic. The standard families +are: +
+ + A = Avant Garde + BM = Bookman + H = Helvetica + HN = Helvetica Narrow + N = New Century Schoolbook + P = Palatino + T = Times Roman + ZCM = Zapf Chancery + +The argument you pass to FAMILY is the identifier at left, above. +For example, if you want Helvetica, enter +
+ + .FAMILY H + +

+ +

+Note: The font macro +(FT) +lets you specify both the type family and the desired font with +a single macro. While this saves a few keystrokes, I recommend +using FAMILY for family, and FT for font, except where doing +so is genuinely inconvenient. ZCM, for example, +only exists in one style: Italic (I). Therefore, +.FT ZCMI makes more sense than setting the family to +ZCM, then setting the font to I. +

+ +

+Additional note: As of mom, +version 1.1.9-a, if you are running a version of groff lower than +1.19.2, you must follow all FAMILY requests with a FT request, +otherwise mom will set all type up to the next FT request in the +fallback font. +

+ +

+If you are running a version of groff greater than or +equal to 1.19.2, when you invoke the FAMILY macro, mom +“remembers” the font style (Roman, Italic, etc) +currently in use (if the font style exists in the new family) and +will continue to use the same font style in the new family. For +example: +
+ + .FAMILY BM \" Bookman family + .FT I \" Medium Italic + <some text> \" Bookman Medium Italic + .FAMILY H \" Helvetica family + <more text> \" Helvetica Medium Italic + +However, if the font style does not exist in the new family, mom +will set all subsequent type in the +fallback font +(by default, Courier Medium Roman) until she encounters a +.FT +request that’s valid for the family. For example, assuming +you don’t have the font “Medium Condensed Roman” +(mom extension “CD”) in the Helvetica family: +
+ + .FAMILY UN \" Univers family + .FT CD \" Medium Condensed + <some text> \" Univers Medium Condensed + .FAMILY H \" Helvetica family + <more text> \" Courier Medium Roman! + +In the above example, you must follow +.FAMILY H with a FT request +that’s valid for Helvetica. +

+ +

+Please see the Appendices, +Adding PostScript fonts to groff, +for information on adding fonts and families to groff, as well as +to see a list of the extensions mom provides to groff’s basic +R, I, B, BI styles. +

+ +

+Experts: If you add other PostScript +families to groff’s /font/devps directory, I recommend +following the groff standard for naming families and fonts. For +example, if you add the Garamond family, name the font files +
+ + GARAMONDR + GARAMONDI + GARAMONDB + GARAMONDBI + +GARAMOND then becomes a valid family name you can pass to FAMILY. +(You could, of course, shorten GARAMOND to just G, or GD.) R, +I, B, and BI after GARAMOND are the roman, +italic, bold and bold-italic fonts respectively. +

+ + + +

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

+ +

+(As of mom, version 1.1.9-a, the range of arguments that can be +passed to FT has been considerably extended, allowing access to a +greater variety of font +weights +and +shapes. +Please see the +NOTE, +below.) +

+ +

+How mom reacts to an invalid argument to FT depends on which version +of groff you’re using. If your groff version is greater than +or equal to 1.19.2, mom will issue a warning and, depending on how +you’ve set up the +fallback font, +either continue processing using the fallback font, or abort +(allowing you to correct the problem). If your groff version is +less than 1.19.2, mom will silently continue processing, using +either the fallback font or the font that was in effect prior to the +invalid FT call. +

+ +

+FT will also accept, as an argument, a full family+font name. For +example, +
+ + .FT HB + +will set subsequent type in Helvetica Bold. However, I strongly +recommend keeping family and font separate except where doing so is +genuinely inconvenient. +

+ +

+For inline control of fonts, see +Inline Escapes, font control. +

+ +

+Note: mom, versions 1.1.9-a and higher, +considerably extends the range of arguments you can pass to FT, +making it more convenient to add and access fonts of differing +weights +and +shapes +within the same family. Have a look +here +for a list of the weight/style arguments mom +allows. +

+ +

+Be aware, though, that you must have the fonts, correctly installed +and named, in order to use the arguments. (See +How to create a PostScript font for use with groff +for how to add fonts to groff.) Please also read the +ADDITIONAL NOTE +found in the description of the FAMILY macro. +

+ + + +

Fallback font

+ +

+Macro: FALLBACK_FONT <fallback font> [ ABORT | WARN ] +

+ +

+In the event that you pass an invalid argument to +.FAMILY +(i.e. a non-existent family), mom, by default, uses the fallback +font, Courier Medium Roman (CR), in order to continue processing +your file. +

+ +

+If you’d prefer another fallback font, pass FALLBACK_FONT the +full family+font name of the font you’d like. For example, if +you’d rather the fallback font were Times Roman Medium Roman, +
+ + .FALLBACK_FONT TR + +would do the trick. +

+ +

+Additionally, if your version of groff accepts accepts ”.if +F” and ”.if S” (see +above), +mom issues a warning whenever a font style set with +FT +does not exist, either because you haven’t registered the +style (see +here +for instructions on registering styles), or because the font style +does not exist in the current family set with +FAMILY. +By default, mom then aborts, which allows you to correct the +problem. +

+ +

+If you’d prefer that mom not abort on non-existent fonts, +but rather continue processing using a fallback font, you can pass +FALLBACK_FONT the argument WARN, either by itself, or in +conjunction with your chosen fallback font. +

+ +

+Some examples of invoking FALLBACK_FONT: +

+ +

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

+ +

+You can prepend a plus or a minus sign to the argument to PT_SIZE, +in which case the point size will be changed by + or - the original +value. For example, if the point size is 12, and you want 14, you +can do +
+ + .PT_SIZE +2 + +then later reset it to 12 with + + .PT_SIZE -2 + +The size of type can also be changed inline. See +Inline Escapes, changing point size. +

+ +

+Note: It is unfortunate that the +pic 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 +

+ +

+Without the FACTOR argument, AUTOLEAD calculates the +linespace for you by adding its argument to the current point size +of type. All subsequent +PT_SIZE +requests automatically update the linespacing by the autolead amount. +

+ +

+Used in this way, AUTOLEAD does not require a unit of measure; +points is assumed. However, you may use an alternate unit of +measure by appending it to the argument. The argument may be a +decimal fraction (e.g. .5 or 2.75). +

+ +

+As an example, if your current point size of type is 12, entering +
+ + .AUTOLEAD 2 + +changes the linespace to 14 points, regardless any linespacing +already in effect. From here on, every change to the size of type +(with PT_SIZE, not +inline) +changes the linespace as well. If you decrease the type size to 9 +points, the leading decreases to 11 points. If you increase the +type size to 16 points, the leading increases to 18 points. +

+ +

+Automatic updating of the linespacing continues until you enter a +“manual” line space value with +LS. +

+ +

+If you give AUTOLEAD the optional FACTOR argument, AUTOLEAD +calculates the line space as a factor of the +numeric argument +you gave AUTOLEAD. For example, if your point size is 12, +
+ + .AUTOLEAD 1.125 FACTOR + +sets the leading at 13.5 points. If you change the point size to +14, the leading automatically changes to 15.75 (14 x 1.125). +

+ +

+Note: There’s no need to prepend a +plus sign +(+) +to AUTOLEAD’s argument, although you may do so if you wish. +

+ + + +

Line length

+ +

+Macro: LL <line length> +

+• Requires a unit of measure +

+ +

+LL (Line Length) takes one argument: the distance from the left +margin of the page to the maximum allowable point on the right at +which groff should place type. The line length, in other words, as +the macro suggests. +

+ +

+LL requires a unit of measure. Therefore, to set the line length to +39 picas, you would enter +
+ + .LL 39P + +As with other macros that require a unit of measure, the argument to +LL may be fractional. For example, +
+ + .LL 4.5i + +sets the line length to 4-1/2 inches. +

+ +

+Additionally, you may express a new line length relative to the +current line length by prepending a plus or minus sign to the +argument. Thus, if you wanted to increase the line length by 3 +points, you could +do +
+ + .LL +3p + +This is especially handy when you want to “hang” +punctuation outside the right margin since you can pass +groff’s +\w +escape as the argument to LL, like this: +
+ + .LL +\w'.'u + +The above example increases the current line length by the width of +a period. Notice that you must append the +unit of measure, +u, to the escape since LL requires a unit of measure. +

+ +

+Note: The right margin macro, +(R_MARGIN), +can also be used to set line length. +

+ +

+ + + +

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. + +See + +NOTES, + +below. +

+ +

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

+ +

+The mnemonic “EL” is borrowed from old Compugraphic +typesetting systems, where it stood for +"End Line." +Conceptually, EL is equivalent to the notion of a carriage return +with no linefeed. +

+ +

+EL’s function is simple: it breaks a line without advancing +on the page. As an example of where you might use it, imagine that +you’re working from marked-up copy. The markup indicates 24 +points of space between two given lines, but the prevailing line +spacing is 12.5 points. You may find it more convenient to break +the first line with EL and instruct mom to advance 24 points to the +next line instead of calculating the lead that needs to be added to +12.5 to get 24. To demonstrate: +
+ + .LEFT + .LS 12.5 + A line of text.\c + .EL + .ALD 24p + The next line of text. + +may be more intuitive than +
+ + .LEFT + .LS 12.5 + A line of text. + .ALD 11.5p + The next line of text. + +The first example has the further advantage that should you wish to +change the prevailing line space but keep the 24 points lead, you +don’t have to recalculate the extra space. +

+ +

+ALD in the above examples stands for +“Advance +LeaD” +(another mnemonic borrowed from Compugraphic), which is covered in +the section +Vertical movements. +

+ +

Notes

+ +

+In versions of mom prior to 1.1.9, EL did not always work as +advertised on the last +output line +of pages that contained a footer trap (e.g. one set with +B_MARGIN +or in documents formatted using the +document processing macros). +

+ +

+EL has been re-written so that this should no longer be the case. +However, in order for it to work in the +nofill +modes +(LEFT, +RIGHT +or +CENTER), +you must always “join” .EL to +the line before it using the +\c +inline escape, +like this: +
+ + .LEFT + A line I don’t want to advance\c + .EL + +Conversely, in +fill modes +(QUAD LEFT, +QUAD RIGHT, +QUAD CENTER +or +JUSTIFY), +the \c must not be used. +

+ +

+If EL is used after most macros or groff +primitives +(see the exception, below), you don’t have to worry about +this, regardless of the fill mode. Just type +.EL +

+ +

+Experts: EL is unrelated to +groff’s .el. If you find the similarity confusing, +you may want to alias EL as something else (but don’t use EOL; +mom uses it internally.) +

+ + + +

Break lines and add space between

+ +

+Macro: SPACE <space to add between lines> +

+Alias: SP +

+ +

+SPACE breaks a line, just like +BR, +then adds space after the line. With no argument, it adds an extra +line space of a value equal to the current +leading. +If you pass it a numeric argument without supplying a +unit of measure, +it advances that number of extra line spaces. For example: +
+ + .SPACE + +breaks the line then adds an extra linespace, whereas +
+ + .SPACE 2 + +breaks the line and adds two extra linespaces. +

+ +

+If you supply a unit of measure, SPACE breaks the line then advances +one linespace (at the current +leading) +PLUS the specified amount of extra space given to SPACE, as in +
+ + .SPACE 6p + +which breaks the line and advances one full linespace plus six +points. +

+ +

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

+ + + +

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 type size. Knowing how it’s +calculated is unimportant. What matters is having a sense of how +the value passed to WS affects the look of your type. Generally, +in/decreasing the word space by a value of 1 or 2 produces a +difference that in many cases is scarcely visible; in/decreasing by +a value of 5 or so produces a subtle but noticeable difference; and +in/decreasing by a value greater than 10 is always apparent. You +should preview your work to assess the effect of WS. +

+ +

+WS takes as its argument a number (decimal fractions are allowed) +preceded by a plus or minus sign. Therefore, to decrease the word +space slightly, you might enter
+ + .WS -4 + +To increase it by a noticeable amount, you might enter +
+ + .WS +12 + +You can reset the word spacing to its previous value by switching +the plus or minus sign, like this: +
+ + .WS +4 + A line of text + .WS -4 + +The .WS -4 undoes the effect of +.WS +4. You can also reset WS to its groff default +by entering +
+ + .WS DEFAULT + +This can be particularly useful if you’ve been playing around +with plus and minus values, and can’t remember by how much you +have to in/decrease the word space to get it back to normal. +

+ + + +

Sentence space

+ +

+Macro: SS <+sentence space> | 0 | DEFAULT +

+ +

+SS (Sentence Space) tells groff how to treat double spaces it +encounters between sentences in +input lines. +If you use SS, input sentences with two spaces after them and +input sentences that fall at the end of input lines all receive a +normal word space plus an additional amount of space whose size is +determined by the + value passed as an argument to SS. Thus, +
+ + .SS +2 + +means that input sentences with two spaces after them receive a +normal word space PLUS the +2 value passed to SS. +

+ +

+Like +WS, +increasing the sentence space by a value of 1 or 2 produces a +difference that in many cases is scarcely visible; increasing by a +value of 5 or so produces a subtle but noticeable difference (i.e. +the space between double-spaced input sentences will be slightly but +visibly greater than the space between words); and increasing by a +value greater than 10 is always apparent. You should preview your +work to assess the effect of SS. +

+ +

+There’s an additional argument you can pass SS: the number +zero (without the + sign). It’s the argument you’ll +use most often. Typeset copy should never have two spaces between +sentences, and the "zero" argument tells groff to give the extra +spaces no space at all (effectively removing them). Therefore, if +you double-space your sentences (as you should when writing in a +text editor), get in the habit of putting +
+ + .SS 0 + +at the top of your files. +

+ +

+If you do use SS for something other than ensuring that you +don’t get unwanted sentence spaces in output copy, you can set +or reset the sentence space to the groff default (the same width +as a word space, i.e. double-spaced input sentences will appear +double-spaced on output as well) with +
+ + .SS DEFAULT + +If you’re using the +document processing macros +and your +PRINTSTYLE +is TYPEWRITE, .SS DEFAULT is the +default, because you do want double spaces between sentences in copy +that imitates the look of a typewritten document. +

+ +

+IMPORTANT: SS with an argument other +than 0 (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 + +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 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: In versions prior to +1.1.9-a, RW affected all +fonts +in the +family +current at the time it was invoked. As of 1.1.9-a, this behaviour +has been changed. RW affects only the font current at the time +it’s invoked, and remains in effect for that font every time +the font is called, hence must be reset to zero to cancel its effect +(.RW 0) on that font. +

+ + + +

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: In versions prior to +1.1.9-a, EW affected all +fonts +in the +family +current at the time it was invoked. As of 1.1.9-a, this behaviour +has been changed. EW affects only the font current at the time +it’s invoked, and remains in effect for that font every time +the font is called, hence must be reset to zero to cancel its effect +(.EW 0) on that font. +

+ + + +

Break before line kerning

+ +

+Macro: BR_AT_LINE_KERN toggle +

+ +

+By default, in +fill +modes (i.e. +QUAD +L, R, C, J or +JUSTIFY) +mom does not break +input lines +when you invoke +RW +or +EW. +If you’d like her to break input lines prior to RW or EW, +invoke .BR_AT_INPUT_LINE without any argument. To +disable the breaks, invoke .BR_AT_INPUT_LINE with any +argument (OFF, QUIT, Q, X...), like this +
+ + .BR_AT_LINE_KERN OFF + +or + + .BR_AT_LINE_KERN X + +With QUAD L, R or C, mom simply breaks the line. With QUAD J (or +just JUSTIFY, which is the same thing), she breaks and +force justifies +the line prior to .EW or .RW. +

+ + + +

Automatic kerning

+ +

+Macro: KERN toggle +

+ +

+By itself (i.e. with no argument), KERN turns automatic pairwise +kerning +on. With any argument (e.g. OFF, Q, X), pairwise kerning is turned +off. +

+ +

+Kerning of individual character pairs can be controlled with the +inline escapes +\*[BU <n>] and +\*[FU <n>]. See +Inline Escapes, kerning. +

+ + + +

Automatic ligature generation

+ +

+Macro: LIGATURES toggle +

+Alias: LIG +

+ +

+Provided your current font has +ligatures, +LIGATURES, by itself, turns on automatic generation of ligatures. +When automatic ligature generation is on, simply typing the letters +of a ligature combination will produce the correct ligature upon +output. For example, if you type the word “finally”, +the fi combination will be output as an fi ligature. Generally +speaking, ligatures are A Good Thing, hence mom has them on by +default. +

+ +

+LIGATURES with any argument turns automatic ligature generation off. +

+ +

+Note: Not all fonts support ligatures. +

+ +

+ + + +

Type modifications (pseudo font styles)

+ +

+It sometimes happens that a PostScript +family +doesn’t contain all the fonts you need. You might, for +example, be missing an italic font, or a bold font. Or you might +not be able to get your hands on a condensed family. That’s +where these macros and inline escapes come in. With them, you +can fake the fonts you’re missing. A word of caution, +though: “faked” fonts are just that—faked. You +should only use them as a last resort, and then only sparingly. A +word or two or a line or two in a faked font will pass unnoticed; +large patches of type in a faked font look typographically cheap. +

+ +

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

+ + + +

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 type. +\*[SLANTX] turns the feature off. Both are +inline escapes, +therefore they should not appear as separate lines, but rather be +embedded in text lines, like this: +
+ + Not \*[SLANT]everything\*[SLANTX] is as it seems. + +Alternatively, if you wanted the whole line pseudo-italicized, +you’d do +
+ + \*[SLANT]Not everything is as it seems.\*[SLANTX] + +Once \*[SLANT] is invoked, it remains in effect until +turned off. +

+ +

+Note: If you’re using the +document processing macros +with +PRINTSTYLE TYPEWRITE, +mom underlines pseudo-italics by default. To change this behaviour, +use the special macro +SLANT_MEANS_SLANT. +

+ + + +

Set amount of emboldening

+ +

+Macro: SETBOLDER <amount of emboldening, in machine units> | RESET +

+ +

+Emboldening of type is accomplished by printing characters twice; +the second printing is slightly offset from the first, effectively +“thickening” the character. SETBOLDER lets you set the +number of +machine units +for the offset. Mom’s default is 700 units, which produces an +acceptable approximation of a bold font. If you want another +value—say, 500 units—you’d set it by entering +
+ + .SETBOLDER 500 + +If you change the emboldening offset and later want to set it back +to the mom default, do +
+ + .SETBOLDER RESET + +

+ +

+Note: By itself, SETBOLDER will not start +emboldening type; it merely tells mom what you want the emboldening +offset to be. To start emboldening, use the +inline escape +\*[BOLDER]. +

+ + + +

Emboldening on/off

+ +

+Inline: \*[BOLDER] +
+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 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 reinvoke +\*[COND] afterwards. Equally, \*[COND] must +be turned off before changing the condense percentage with +.CONDENSE. +

+ +

+Note: If you’re using the +document processing macros +with +PRINTSTYLE TYPEWRITE, +mom ignores \*[COND] requests. +

+ + + +

Set percentage for pseudo-extended type

+ +

+Macro: EXTEND <pseudo-extend percentage> +

+ +

+Pseudo-extending of type is accomplished by increasing the width of +characters at a given point size without increasing their height, +effectively widening them so they look like extended type. EXTEND +tells mom what percentage of the normal character width you want the +characters to be extended. +

+ +

+Mom has no default value for EXTEND, therefore you must set it +before using the +inline escape +\*[EXT]. +120% of the normal character width is a good value, and you’d +set it like this: +
+ + .EXTEND 120 + +

+ +

+Note: By itself, EXTEND will not start +pseudo-extending type; it merely tells mom what percentage of the +normal character width you want characters to be extended. To start +pseudo-extending, use the +inline escape +\*[EXT]. +

+ +

+Additional note: Make sure that +pseudo-extending is off (with +\*[EXTX]) +before before making any changes to the pseudo-extend percentage +with EXTEND. +

+ + + +

Pseudo-extending on/off

+ +

+Inline: \*[EXT] +
+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 reinvoke \*[EXT] +afterwards. Equally, \*[EXT] must be turned off before +changing the extend percentage with +EXTEND. +

+Note: If you’re using the +document processing macros +with +PRINTSTYLE TYPEWRITE, +mom ignores \*[EXT] requests. +

+ +

+ + + +

Vertical 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

+ + + +

Advance Lead (move downward)

+ +

+Macro: ALD <distance to move downward> +

+• Requires a unit of measure +

+ +

+ALD takes one argument: the distance to move downward on the page +relative to the current vertical position. +

+ +

+Used by itself, or preceded by +BR, +ALD will advance by one line space plus the distance you specify. +Preceded by +EL, +it will advance by exactly the distance you specify. +

+ +

+ALD requires a unit of measure. Decimal fractions are allowed, and +values may be combined. Therefore, to move down on the page by 1/4 +of an inch, you could enter either +
+ + .ALD .25i + +or +
+ + .ALD 1P+6p + +As the mnemonic +(Advance LeaD) +suggests, you’ll most often use ALD with +points +of lead. +

+ +

+Note: if you want to use ALD at the top +of a page (i.e. to advance to the starting position of type on a +page), combine the value you want with -1v (minus one +line space), like this: +
+ + .ALD 1i-1v + +At the top of a page, this will advance one inch from the top edge +of the paper. Without the -1v, the same command would advance one +inch from the top of the page plus the distance of one line space. +

+ + + +

Reverse Lead (move upward)

+ +

+Macro: RLD <distance to move upward> +

+• Requires a unit of measure +

+ +

+RLD takes one argument: the distance to move upward on the page +relative to the current vertical position. +

+ +

+Used by itself, or preceded by +BR, +RLD will advance by one line space, then reverse by the distance you +specify. Preceded by +EL, +it will reverse by exactly the distance you specify. +

+ +

+RLD requires a unit of measure. Decimal fractions are allowed, and +values may be combined. Therefore, to move up on the page by 1/4 of +an inch, you could enter either +
+ + .RLD .25i + +or + + .RLD 1P+6p + +As the mnemonic +(Reverse LeaD) +suggests, you’ll most often use RLD with +points +of lead. +

+ +

+ + + +

Tabs

+ +

+Mom provides two different kinds of tab setup: typesetting tabs +and string tabs. Neither one has anything to do with the tab key +on your keyboard, and both are utterly divorced from groff’s +notion of tabs. I recommend reading this section carefully in order +to understand how mom handles tabs. +

+ +

+Note: see the section +Typesetting macros during document processing +for re-assuring information on the use of tabs during +document processing. +

+ +

Typesetting tabs

+ +

+Typesetting tabs are defined by both an indent from the left margin +and a line length. This is quite different from typewriter-style +tab stops (the groff norm) that only define the left indent. In +conjunction with the +multi-column macros, +typesetting tabs significantly facilitate tabular and columnar work. +

+ +

+Typesetting tabs are created with the +TAB_SET +macro. TAB_SET identifies the tab (by number), establishes its left +indent and line length, and optionally sets a quad direction and +fill mode. After tabs have been created with TAB_SET, they can be +called at any time with the +TAB +macro. +

+ +

Quickie tutorial on typesetting tabs

+ +

+Say you want to set up three tabs to produce an employee evaluation +that looks something like this: +

+ +

+ +CRITERION EVALUATION COMMENTS + +Service Good Many clients specifically request + support from Joe by name. + +Punctuality Satisfactory Tends to arrive after 8:00am, but + often works through lunch hour. + +Team spirit Needs work Persistently gives higher priority + to helping clients than respecting + organizational hierarchy. + +

+ +

+You want the first tab, CRITERION, +

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

+ +

+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 +.TN +EVALUATION +.TN +COMMENTS +.SP +.TAB 1 +Service +.TN +Good +.TN +Many clients specifically request support from Joe by name. +.SP +.TAB 1 +Punctuality +.TN +Satisfactory +.TN +Tends to arrive after 8:00am, but often works through lunch hour. +.SP +.TAB 1 +Team spirit +.TN +Needs work +.TN +Persistently gives higher priority to helping clients +than respecting organizational hierarchy. +.TQ + +

+ +

+Try setting this up and processing it it with +
+ + groff -mom <filename> > <filename>.ps + +then previewing the .ps 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] + (ForWarD 12 points): +
+ + \*[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 +and +.TN +just like typesetting tabs (see +typesetting tabs tutorial). +

+ +

+Here’s the complete setup and entry for the sample employee +evaluation form utilizing string tabs. +

+ +

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 +.TN +EVALUATION +.TN +COMMENTS +.SP +.TAB 1 +Service +.TN +Good +.TN +Many clients specifically request support from Joe by name. +.SP +.TAB 1 +Punctuality +.TN +Satisfactory +.TN +Tends to arrive after 8:00am, but often works through lunch hour. +.SP +.TAB 1 +Team spirit +.TN +Needs work +.TN +Persistently gives higher priority to helping clients +than respecting organizational hierarchy. +.TQ + +

+ +

+Try setting this up and processing it with +
+ + groff -mom <filename> > <filename>.ps + +and previewing the .ps 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 a 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), like this: +
+ + .TAB 1 + A line of text in tab 1. + .TN + A line of text in tab 2. + +which produces +
+ + A line of text in tab 1. A line of text in tab 2. + +If the text in your tabs runs to several lines, and you want the +first lines of each tab to align, you must use the +multi-column macros. +

+ +

+Additional note: Any indents +in effect prior to calling a tab are automatically turned off by +TAB. If you were happily zipping down the page with a left indent +of 2 picas turned on, and you call a tab whose indent from the left +margin is 6 picas, your new distance from the left margin will be 6 +picas, not 6 picas plus the 2 pica indent. +

+ + + +

Tab Next

+ +

+Macro: TN +

+In tabs that aren’t given the QUAD +argument when they’re set up with +TAB_SET +or +ST, +you must terminate the line preceding .TN +with the \c inline escape. See the +ADDITIONAL NOTE. +If you find remembering whether to put in the +\c bothersome, you may prefer to use the +inline escape +alternative to +.TN, +\*[TB+], +which works consistently regardless of the fill mode. +

+ +

+TN moves over to the next tab in numeric sequence (tab n+1) without +advancing on the page. See the +NOTE +in the description of the TAB macro for an example of how TN works. +

+ +

+Note: You must put text in the +input line +immediately after TN. “Stacking” of TN’s is not +allowed. In other words, you cannot do +
+ + .TAB 1 + Some text + .TN + Some more text + .TN + .TN + Yet more text + +The above example, assuming tabs numbered from 1 to 4, should be entered +
+ + .TAB 1 + Some text + .TN + Some more text + .TAB 4 + Yet more text + +Additional note: +In versions of mom prior to 1.1.9, TN did not always work as +advertised on the last +output line +of pages that contained a footer trap (e.g. one set with +B_MARGIN +or in documents formatted using the +document processing macros). +

+ +

+TN has been re-written so that this should no longer be the case. +However, in order for it to work in tabs that have not been given a +QUAD argument (see +TAB_SET +and +ST) +you must always “join” .TN to +the line before it using the +\c +inline escape, +as in the following example: +
+ + .TAB_SET 1 0 1P L + .TAB_SET 2 1P 20P L + .TAB 1 + 1.\c + .TN + The first rule of survival is “make and keep good friends.” + +When output, the example will look like this: +
+ + 1. The first rule of survival is “make and keep good friends.” + +

+ +

+Conversely, if you did give a QUAD argument +to TAB_SET or ST, the +\c must not be used. +

+ + + +

Tab Quit

+ +

+Macro: TQ +

+ +

+TQ takes you out of whatever tab you were in, advances 1 linespace, +and restores the left margin, line length, quad direction and +fill mode +that were in effect prior to invoking any tabs. +

+ +

+ + + +

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

+ +

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. Personally, I don’t +use them much, except for cutarounds and multi-level lists à la +html, at which they excel. +

+ +

+Note: see the section +Typesetting macros 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 indents by its last active value. See the +brief 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 indents by its last active value. See the +brief 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 [ <left measure> <right measure> ] +

+• The optional arguments require a unit of measure +

+ +

+IB allows you to set or invoke a left and a right indent at the same +time. +

+ +

+At its first invocation, you must supply a measure for both indents; +at subsequent invocations when you wish to supply a measure, both +must be given again. As with IL and IR, the measures are added to +the values previously passed to the macro. Hence, if you wish to +change just one of the values, you must give an argument of zero to +the other. +

+ +

+A word of advice: If you need to manipulate left and right +indents separately, use a combination of IL and IR instead of IB. +You’ll save yourself a lot of grief. +

+ +

+A minus sign may be prepended to the arguments to subtract from +their current values. The +\w +inline escape +may be used to specify text-dependent measures, in which case no +unit of measure is required. For example, +
+ + .IB \w’margarine’ \w'jello' + +left indents text by the width of the word “margarine” +and right indents by the width of “jello”. +

+ +

+Like IL and IR, IB with no argument indents by its last active +values. See the +brief explanation of how mom handles indents +for more details. +

+ +

+Note: Calling a tab (with +.TAB <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. +

+ +

Recipe: Numbered lists using hanging indents

+ +

+Note: mom has macros for setting lists (see +Nested lists). +This recipe exists to demonstrate the use of hanging indents only. +

+ +

+Consider the following example: +
+ + .PAGE 8.5i 11i 1i 1i 1i 1i + .FAMILY T + .FT R + .PT_SIZE 12 + .LS 14 + .JUSTIFY + .KERN + .SS 0 + .IL \w'\0\0.' \"Indent left by 2 figure spaces and a period + .HI \w'\0\0.' \"Hang first line back by 2 figure spaces and a period + 1.\0The most important point to be considered is whether the + answer to the meaning of Life, the Universe, and Everything + really is 42. We have no-one’s word on the subject except + Mr. Adams’. + .HI + 2.\0If the answer to the meaning of Life, the Universe, + and Everything is indeed 42, what impact does this have on + the politics of representation? 42 is, after all not a + prime number. Are we to infer that prime numbers don’t + deserve equal rights and equal access in the universe? + .HI + 3.\0If 42 is deemed non-exclusionary, how do we present it + as the answer and, at the same time, forestall debate on its + exclusionary implications? + +First, we invoke a left indent with a measure equal to the width of +2 +figures spaces +plus a period (using the +\w +inline escape). At this point, the left indent is active; text +afterwards would normally be indented. However, we invoke a +hanging indent of exactly the same width, which hangs the first +line (and first line only!) to the left of the indent by the +same distance (in this case, that means “out to the left +margin”). Because we begin the first line with a number, +a period, and a figure space, the actual text (“The most +important point...”) starts at exactly the same spot as the +indented lines that follow. +

+ +

+Notice that subsequent invocations of .HI without a +measure produce exactly the same effect. +

+ +

+Paste the example above into a file and preview it with groff +-mom -X <filename> to see hanging indents in action. +

+ +

+IMPORTANT: Unlike IL, IR and IB, +measures given to HI are NOT additive. Each time you pass a measure +to HI, the measure is treated literally. +

+ + + +

Quitting indents

+ +

+Macro: IQ [ CLEAR ] (quit any/all indents — see IMPORTANT NOTE) +

+
+ +Macro: ILX [ CLEAR ] (exit Indent Left) +
+ +Macro: IRX [ CLEAR ] (exit Indent Right) +
+ +Macro: IBX [ CLEAR ] (exit Indent Both) + +

+IMPORTANT NOTE: Formerly, the macro +for quitting all indents was IX. This usage is now deprecated, in +favour of IQ. IX will continue to behave as before, but mom will +issue a warning to stderr indicating that you should update your +documents. +

+ +

+As a consequence of this change, ILX, IRX and IBX may now also be +invoked as ILQ, IRQ and IBQ. Both forms are acceptable. +

+ +

+Without an argument, the macros to quit indents merely restore your +original margins and line length. The measures stored in the indent +macros themselves are saved so you can call them again without +having to supply a measure. +

+ +

+If you pass these macros the optional argument CLEAR, +they not only restore your original left margin and line length, but +also clear any values associated with a particular indent style. +The next time you need an indent of the same style, you have to +supply a measure again. +

+ +

+.IQ CLEAR, as you’d suspect, +quits and clears the values for all indent styles at once. +

+ +

+ + + + + + + + +

Next: Goodies

+ +

+ + + + diff --git a/contrib/mom/momdoc/using.html b/contrib/mom/momdoc/using.html new file mode 100644 index 00000000..02a3bc1d --- /dev/null +++ b/contrib/mom/momdoc/using.html @@ -0,0 +1,304 @@ + + + + + + + + Using mom + + + + + + + +

+ + + + + + + +

Next: The typesetting macros

+ +

Using mom

+ +

Introduction
How to input mom’s macros
How to preview documents
Saving documents
Printing documents

+ +

Introduction

+ +

+As explained in the section +What is mom?, +mom can be used in two ways: for straight typesetting or +for document processing. The difference between the two +is that in straight typesetting, every macro is a literal +typesetting instruction that determines precisely how text +following it will look. Document processing, on the other +hand, uses markup tags (e.g. .PP for +paragraphs, .HEAD for heads, +.FOOTNOTE for footnotes, etc.) that make a +lot of typesetting decisions automatically. +

+ +

+You tell mom that you want to use the document processing macros +with the +START +macro, explained below. After START, +mom determines the appearance of text following the markup tags +automatically, although you, the user, can easily change how mom +interprets the tags. This gives you nearly complete control +over document design. In addition, the typesetting macros, in +combination with document processing, let you meet all sorts of +typesetting needs that just can’t be covered by “one +macro fits all“ markup tags. +

+ +

How to input mom’s macros

+ +

+Regardless of which way you use mom, the following apply: +

+ +

+ 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. + +
+ All mom’s macros begin with a period (dot) 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. All + arguments to a macro must appear on the same line as the + macro. +
+ 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 that the term is used in this manual, must be + surrounded by double-quotes + ("<text of string>"). Multiple + string arguments are separated from each other by spaces (each + argument surrounded by double-quotes, of course). +
+ If a string argument, as entered in your text editor, becomes + uncomfortably long (i.e. runs longer than the visible portion of + your screen or window), you may break it into two or more lines + by placing the backslash character (\) + at the ends of lines to break them up, like this: + + .SUBTITLE "An In-Depth Consideration of the \ + Implications of Forty-Two as the Meaning of Life, \ + The Universe, and Everything" + +

+ +

+Tip: +It’s important that formatted documents be easy to +read/interpret when you’re looking at them in a text editor. +One way to achieve this is to group macros that serve a similar +purpose together, and separate them from other groups of macros +with a blank comment line. In groff, that’s done with +\# on a line by itself. Consider the +following, which is a template for starting the chapter of a book. +
+ + .TITLE "My Pulitzer Novel" + .AUTHOR "Joe Blow" + .CHAPTER 1 + \# + .DOCTYPE CHAPTER + .PRINTSTYLE TYPESET + \# + .FAM P + .PT_SIZE 10 + .LS 12 + \# + .START + +

+ +

How to preview documents

+ +

+Other than printing out hard copy, there are two well-established +methods for previewing your work. Both assume you have a working +X server. +

+ +

+Groff itself comes with a quick and dirty previewer called +gxditview. Invoke it with: +
+ + groff -X -mom filename + +It’s not particularly pretty, doesn’t have many +navigation options, requires a lot of work if you want to use +other than the “standard“ groff PostScript fonts, +and occasionally has difficulty accurately reproducing some of +mom’s macro effects +(smartquotes +and +leaders +come to mind). What it does have going for it is that it’s +fast and doesn’t gobble up system resources. +

+ +

+A surer way to preview documents is with gv (ghostview). This +involves processing documents with groff and directing the default +PostScript output to a file, like this: +
+ + groff -mom filename > filename.ps + +You can then then open the ps file in gv. +

+ +

+Tip: +I’ve set up my editor (vi[m]) to do seamless, automatic +previewing. Whenever I’m working on a document that +needs previewing/checking, I fire up gv with the “Watch +File“ option turned on. The first time I want to look at +the file, I tell vim (via a keymapping) to process it with groff +and send it to a temporary file: +
+ + groff -mom <filename> > <filename>.ps + +I then open the file inside gv. Ever after, when I want to look at +any changes I make, I simply tell vim to work its magic again. +The Watch File option in gv registers that the PostScript file has +changed, and automatically loads the new version. Voilà!—instant +previewing. +

+ +

Saving documents

+ +

+By default, groff dumps its PostScript output to stdout (your +terminal screen) so you have to say where you want it to go if you +want to save it to a file. The most straightforward way to do +this is: +
+ + groff -mom <filename> > <filename>.ps + +which drops the output in a PostScript file. Alternatively, you +might prefer to save it as a pdf file, in which case you'd do: +
+ + groff -mom <filename> | ps2pdf - <filename>.pdf + +

+ +

Printing documents

+ +

+You can process and print documents from the command line without +saving them to .ps or .pdf files first. Here are two common ways +to do it: + + + groff -mom -l <filename> + groff -mom <filename> | lpr + +

+ +

+In the first, the -l option tells groff +to send the output to your printer. In the second, you’re +doing the same thing, except you’re telling groff to +pipe the output to your printer spooler. Basically, +they’re the same thing. The advantage to the second is that +you can pass additional options to lpr, for example to send +the output to a particular printer, like this: +
+ + groff -mom <filename> | lpr -P <printer_name> + +

+ +

+ + + + + + + + +