diff options
| author | PTPi <PTPi> | 2010-08-18 22:45:35 +0000 |
|---|---|---|
| committer | PTPi <PTPi> | 2010-08-18 22:45:35 +0000 |
| commit | f4bd055926124c14d7556c113721c0fb2dc18b0f (patch) | |
| tree | b41a62640b3c4ec9d67c7d471acd4c3cc5df102a | |
| parent | 3ba71bae1806d1b02f7d0d0e49d53523bb501c70 (diff) | |
| download | groff-f4bd055926124c14d7556c113721c0fb2dc18b0f.tar.gz | |
Complete overhaul of documentation; added new files.
22 files changed, 32416 insertions, 0 deletions
diff --git a/contrib/mom/momdoc/appendices.html b/contrib/mom/momdoc/appendices.html new file mode 100644 index 00000000..a28c4247 --- /dev/null +++ b/contrib/mom/momdoc/appendices.html @@ -0,0 +1,819 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- +This file is part of groff, the GNU roff type-setting system. + +Copyright (C) 2004, 2005, 2006, 2009, 2010 Free Software Foundation, Inc. +Written by Peter Schaffter. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with the +Invariant Sections being this comment section, with no Front-Cover +Texts, and with no Back-Cover Texts. + +A copy of the Free Documentation License is included as a file called +FDL in the main directory of the groff source package. +--> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"> + +<head> + <meta http-equiv="content-type" content="text/html;charset=utf-8"/> + <title>Mom -- Appendices</title> + <link rel="stylesheet" type="text/css" href="stylesheet.css" /> +</head> + +<body style="background-color: #f5faff;"> + +<!-- ==================================================================== --> + +<div id="top" class="page"> + +<!-- Navigation links --> +<table style="width: 100%;"> +<tr> + <td><a href="toc.html">Back to Table of Contents</a></td> + <td style="text-align: right;"><a href="reserved.html#top">Next: Reserved words</a></td> +</tr> +</table> + +<h1 id="appendices" class="docs">Appendices</h1> + +<div style="width: 54%; margin: auto;"> +<ul class="no-enumerator"> + <li><a href="#moredoc">Notes on the documentation</a></li> + <li><a href="#fonts">Adding PostScript fonts to groff</a> + <ul style="margin-left: -.5em;"> + <li><a href="#howto">How to create a PostScript font for use with groff</a></li> + </ul></li> + <li><a href="#codenotes">Some reflections on mom</a></li> + <li><a href="#contact">Contact the author</a></li> +</ul> +</div> + +<div class="rule-medium"><hr/></div> + +<h2 id="moredoc" class="docs">Notes on the documentation</h2> + +<p> +Some mom users are sure to ask: “Why is the documentation in +html? If mom’s so great, why not pdfs to show her off? And +if groff’s so great, why not write a man page?” +</p> + +<p> +Valid questions, to be sure, and mom has answers. (Okay—I +have answers, but I speak for mom.) +</p> + +<p> +The documentation is in html because I still find it the best tool +for navigating lengthy manuals. Html, with its anchors and links, +came into being precisely so people could do something they’d +never been able to with the printed word: instantly track down +internal and external references in a document. +</p> + +<p> +It’s essential that people reading mom’s documentation +never have difficulty finding precisely the macro they need for a +particular task. Equally, when reading up on a macro, they should +never be presented with terms or other macro names for which they +cannot instantly find accurate explanations. Short of having +written the documentation in TeX for the info browser (and TeX bloat +is one of the reasons I prefer to typeset with groff), I can think +of no better way to achieve the kind of truly useful documentation I +wanted than html. +</p> + +<div class="rule-medium"><hr/></div> + +<!-- ===================================================================== --> + +<h2 id="fonts" class="docs">Adding PostScript fonts to groff</h2> + +<div class="box-tip"> +<p class="tip"> +Robert Valiant has set up a web page containing information, +instructions and strategies for adding PostScript and TrueType fonts +to groff for use with mom. The page is directed at Debian GNU/Linux +users, but knowledgable users of other GNU/Linux distributions +should have no difficulty adapting it to their needs. The site is +located at +<br/> +<span class="pre-in-pp" style="display:block; margin-bottom: -1em;"> + <a href="http://russia.shaps.hawaii.edu/software/software.html">http://russia.shaps.hawaii.edu/software/software.html</a> +</span> +</p> +</div> + +<div id="small-note" class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +The term <kbd><prefix></kbd> in this section refers +to the directory in which groff is installed, typically +something like <kbd>/usr/share/groff/<version></kbd> +(for distro-specific, pre-compiled groff packages) or +<kbd>/usr/local/share/groff/<version></kbd> (if you’ve +built groff from source). +</p> +</div> + +<p> +Groff comes with a small library of PostScript +<a href="definitions.html#family">families</a> +(see the +<a href="typesetting.html#family">FAMILY</a> +macro for a list). The families have four +<a href="definitions.html#font">fonts</a> +associated with them. These fonts are a combination of +<a href="definitions.html#weight">weight</a> +and +<a href="definitions.html#shape">shape</a>: +<br/> +<span class="pre-in-pp"> + R (Roman, usually Medium weight), + I (Italic, usually Medium weight), + B (Bold, usually Roman shape) and + BI (Bold Italic) +</span> +If you work with mom a lot, you’ll find, sooner or later, that these +families and their associated fonts aren’t sufficient. You’ll +want to supplement them, either with more fonts for the families +already provided—<i>Damn! I need Helvetica Bold Condensed +Italic!</i>—or with entire new families. +</p> + +<p> +Without going into the gory details (yet), while it’s true +that adding fonts to groff is a relatively straightforward process, +extending existing families or adding new ones requires some +planning. +</p> + +<p> +The traditional approach to extending groff families has been to +create new families for non-default weights and shapes (e.g. Light, +which is a weight; Condensed, which is a shape), then to associate +them with groff’s predefined <b>R, I, B</b> and <b>BI</b> font +styles. An example of this can be seen in the groff PostScript +font library itself (<prefix>/font/devps/): there’s one +“family” for Helvetica (<b>HR</b>, <b>HI</b>, <b>HB</b>, +<b>HBI</b>) and another for Helvetica Narrow (<b>HNR</b>, +<b>HNI</b>, <b>HNB</b>, <b>HNBI</b>). +</p> + +<p> +The difficulty with this approach is that typographers tend to +think of families as referring to the entire set of font weights +and shapes associated with a particular family name. For example, +when a typesetter says “the Helvetica family”, s/he is +including the +<a href="definitions.html#weight">weights</a> +Helvetica Thin, Helvetic Light, Helvetica Regular, Helvetica Bold, +Helvetica Heavy, etc, and all their associated +<a href="definitions.html#shape">shapes</a> +(Roman, Italic, Condensed, Narrow, Extended, Outline, etc). +</p> + +<p> +Thus, intuitively, when a typesetter gives mom a +<kbd>.FAM(ILY) H</kbd> directive, s/he reasonably expects that +any subsequent <kbd>.FT</kbd> directive will access the desired font +from the Helvetica family—without the need to state explicitly +both family and font to <kbd>.FT</kbd>, as it is explained one can +do in the +<a href="typesetting.html#family">FAMILY</a> +and +<a href="typesetting.html#font">FT</a> +sections of these documents. +</p> + +<p> +If one had, say, the fonts, Helvetica Light Roman and Helvetica +Light Italic as well as Helvetica Light Condensed Roman and +Helvetica Light Condensed Italic, the established groff approach +would require two “partial” families: HLR/HLI and +HLCDR/HLCDI. Accessing these family/font combos routinely +throughout a document would then require changing family +(with <kbd>.FAM(ILY)</kbd>) and selecting the desired font +(with <kbd>.FT R</kbd> or <kbd>.FT I</kbd>), or +passing <kbd>.FT</kbd> the lengthy family+fontname (.e.g. +<kbd>.FT HLCDI</kbd>). +</p> + +<p> +Fortunately, groff provides a mechanism whereby it’s possible +to extend the basic <b>R</b>, <b>I</b>, <b>B</b> and <b>BI</b> fonts +(“styles” in groff-speak) so that one can, in fact, +create extensive type families, and access all the fonts in them +with <kbd>.ft</kbd> (groff) or <kbd>.FT</kbd> (mom). +</p> + +<p> +Mom uses this mechanism to offer, in addition to groff’s +default PostScript font styles, the following: +</p> + +<div class="examples-container" style="padding-bottom: 1em;"> +<div id="style-extensions" style="width: 53%; float: left;"> +<span class="pre"> +L = Light Roman +LI = Light Italic +LCD = Light Condensed Roman +LCDI = Light Condensed Italic +LEX = Light Extended Roman +LEXI = Light Extended Italic +CD = Medium/Book Condensed Roman +CDI = Medium/Book Condensed Italic +EX = Medium/Book Extended Roman +EXI = Medium/Book Extended Italic +DB = DemiBold Roman +DBI = DemiBold Italic +BCD = Bold Condensed Roman +BCDI = Bold Condensed Italic +BEX = Bold Extended Roman +</span> +</div> +<span class="pre"> +BEXI = Bold Extended Italic +HV = Heavy Roman +HVI = Heavy Italic +HVCD = Heavy Condensed Roman +HVCDI = Heavy Condensed Italic +HVEX = Heavy Extended Roman +HVEXI = Heavy Extended Italic +BL = Black Roman +BLI = Black Italic +BLCD = Black Condensed Roman +BLCDI = Black Condensed Italic +BLEX = Black Extended Roman +BLEXI = Black Extended Italic +UBL = Ultra-Black Roman +UBLI = Ultra-Black Italic +</span> +</div> + +<p style="clear: both;"> +Thus, with mom, if you’ve installed, say, some extra +Helvetica fonts and named them according to the convention +<kbd><F><S></kbd> (where <kbd><F></kbd> means +family and <kbd><S></kbd> means font style), once having +entered +<br/> +<span class="pre-in-pp" style="margin-bottom: -1em;"> + .FAMILY H +</span> +or +<span class="pre-in-pp" style="margin-top: -.5em;"> + .FAM H +</span> +you can access any of those Helvetica fonts simply by passing the +correct argument to +<a href="typesetting.html#font">FT</a>. +from the list, above. +</p> + +<p> +For example, if you were working in Medium Roman +(<kbd>.FT R</kbd>) and you needed Medium Condensed Italic for a +while (assuming it’s installed), you’d just type +<br/> +<span class="pre-in-pp"> + .FT CDI +</span> +to access the Medium Condensed Italic font from the Helvetica +family. +</p> + +<p> +Mom’s list of font styles doesn’t pretend to be +exhaustive, but rather tries to cover the basic weight/shape +combinations likely to be found in any reasonably complete type +family. +</p> + +<p> +The actual extension names are arbitrary and can be used in a +flexible manner. For example, if you create a family that has a +DemiBold font (<b>DB</b>) but no Bold font (<b>B</b>), you might +find it more convenient to give the DemiBold font the extension +“<b>B</b>”. Equally, if the family has an ExtraBold +font, you might find it more convenient to use the extension +“<b>HV</b>” (Heavy). +</p> + +<p id="register-style"> +However, you may, at needs, want to add to mom’s list of font +styles. You can do this by editing the file, om.tmac (typical +location: <kbd><prefix>tmac/om.tmac</kbd>). Near the top, +you’ll see lines of the form +<br/> +<span class="pre-in-pp"> + .sty \n[.fp] L \" Light Roman + .sty \n[.fp] LI \" Light Italic + .sty \n[.fp] LCD \" Light Condensed Roman +</span> +Simply add your new font style by imitating what you see, above, +and plugging in your new font style (having, of course, first +created the font, correctly named, in groff’s PostScript font +directory; see +<a href="#howto">How to create a PostScript font for use with groff</a>). +</p> + +<p> +For example, if you already have some fonts from the Univers family +installed and have called the family <b>UN</b>, you might decide at +some point to add the Bold Outline font (<b>UNBO</b>). In which +case, you’d add +<br/> +<span class="pre-in-pp"> + .sty \n[.fp] BO \" Bold Outline +</span> +to the <kbd>.sty \n[.fp] <font style></kbd> list +in om.tmac. +</p> + +<div class="box-important"> +<p class="tip"> +<span class="important">Important:</span> +Be careful that any styles you add do not conflict with +<i>family</i> names that already exist. “<b>C</b>”, +for example, conflicts with the Courier family (<b>CR</b>, +<b>CI</b>, <b>CB</b>, <b>CI</b>). Were you to create a font +style “<b>C</b>”, thinking that <kbd>.FT C</kbd> +would give you access to font style once you’d given a +<kbd>.FAM(ILY)</kbd> directive, you’d get a nasty surprise: +your type would come out in Courier Roman! +</p> +</div> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +Mom’s font extensions are not “user-space” +controllable via a macro. If you’ve been using groff for +a long time, and have already rolled your own solution to adding +PostScript families, fonts, weights, shapes, etc. to groff, you may +find that mom’s font extensions conflict with your own scheme. +Should that be the case, comment out the <kbd>.sty \n[.fp] <font +style></kbd> lines found near the top of the <kbd>om.tmac</kbd> +file. +</p> +</div> + +<div class="rule-medium"><hr/></div> + +<h2 id="howto" class="docs">How to create a PostScript font for use with groff</h2> + +<p> +These instructions aren’t meant to cover all possibilities, merely +to present one way of making PostScript families/fonts available to +groff and mom. +</p> + +<p> +GNU/Linux distributions being what they are, directory locations may +differ and the presence of some executables can’t be guaranteed. +I run a Debian system. The instructions reflect that. Users of +other distros will have to interpret them according to the way their +distro operates. +</p> + +<h3 class="docs appendices">1. What you need before you start</h3> + +<ul style="margin-top: 1em; margin-left: -.5em;"> + <li>groff, version 1.18 or higher<br/> + (Debian package: groff) + </li> + <li>a full installation of ghostscript and associated tools<br/> + (suggested Debian package: ghostscript-x) + </li> + <li>a library of PostScript fonts<br/> + (suggest Debian packages: gsfonts, gsfonts-x11, gsfonts-other) + </li> + <li>a utility for converting TrueType fonts to Type1 fonts<br/> + (Debian package: ttf2pt1) + </li> + <li>a font manager<br/> + (Debian packages: defoma, psfontmgr) + </li> + <li>perl<br/> + (Debian package: perl) + </li> +</ul> + +<p style="margin-top: -.5em;"> +A reasonably complete installation of any major GNU/Linux distro +should already have these on your system, except perhaps for the +utility to convert TrueType fonts to Type1 fonts (<b>ttf2pt2</b>). +</p> + +<h3 class="docs appendices">2. Initial preparation (you only need do this once)</h3> + +<ol style="margin-left: -.5em;"> + <li>If you don’t already have one, create a directory in + your home directory to hold new fonts. Any directory name + will do. I use <kbd>~/Fonts</kbd>, with subdirectories for + <kbd>Type1</kbd>, <kbd>TrueType</kbd> and <kbd>Groff</kbd> + fonts. Thus, + <br/> + <span class="pre-in-pp"> + ~/Fonts/Type1 + ~/Fonts/TrueType + ~/Fonts/Groff + </span> + </li> + <li id="site-font" style="margin-top: -2em;">Locate the groff + directory, <kbd>site-font</kbd>. The exact location is + difficult to predict, owing to differences between distros and + whether you’re using a pre-packaged groff or have built + it from source. Some typical locations are: + <br/> + <span class="pre-in-pp" style="margin-bottom: -2em;"> + /usr/share/groff + /usr/local/share/groff + /etc/groff + </span> + If you can’t find the site-font directory, locate + groff’s <kbd>site-tmac</kbd> directory, and, as + root, create site-font in the same directory as the + one that holds site-tmac. E.g., if you find site-tmac + in <kbd>/usr/share/groff</kbd>, create site-font in + <kbd>/usr/share/groff</kbd>. + </li> + <li style="margin-top: .5em;">Locate the file + <kbd><prefix>/font/devps/generate/textmap</kbd> and + symlink it to the name <kbd>textmap</kbd> in the directory + that contains your personal collection of PostScript fonts. + (See the + <a href="#small-note">note</a>, + above, for the meaning of <kbd><prefix></kbd>). On my + system, at the time of writing, <kbd><prefix></kbd> + is + <br/> + <span class="pre-in-pp" style="margin-bottom: -2em;"> + /usr/local/share/groff/1.20.1/ + </span> + therefore, I symlink it in <kbd>~/Fonts/Type1/</kbd> with + <br/> + <span class="pre-in-pp"> + ln -s /usr/local/share/groff/1.20.1/font/devps/generate/textmap textmap + </span> + </li> + <li style="margin-top: -2em;">Locate the file + <kbd><prefix>/font/devps/text.enc</kbd> and + symlink it to the name <kbd>text.enc</kbd> in your personal + font directory. On my system, in <kbd>~/Fonts/Type1/</kbd> + <br/> + <span class="pre-in-pp"> + ln -s /usr/local/share/groff/1.19.2/font/devps/text.enc text.enc + </span> + </li> + <li style="margin-top: -2em;">Make sure you know which + directory holds your PostScript fonts. You’ll need the + information later. On a Debian box, a typical location is + <kbd>/usr/share/fonts/type1/gsfonts</kbd> + </li> +</ol> + +<h3 class="docs appendices">3. Font creation/installation</h3> + +<ol style="margin-left: -.5em/"> + <li>Acquire the font as either Type1 (.pfb) or TrueType (.ttf).</li> + <li style="margin-top: .5em;">Place the font in your personal font directory; for me, + that’s + <br/> + <span class="pre-in-pp" style="margin-bottom: -2.5em;"> + ~/Fonts/Type1 + </span> + or + <br/> + <span class="pre-in-pp" style="margin-top: -.5em; margin-bottom: -2em;"> + ~/Fonts/TrueType + </span> + </li> + <li>In your personal font directory, run one of the following. + <ul style="margin-left: -1.5em;"> + <li style="margin-top: .5em;">for <b>Type1 fonts</b>: + <br/> + <span class="pre-in-pp" style="margin-bottom: -2em;"> + getafm fontfilename.pfb | gsnd - > fontfilename.afm + </span> + <i>(This generates something called + an .afm (Adobe Font Metrics) file from the .pfb file, which is required to + create PostScript fonts for groff.)</i> + </li> + <li style="margin-top: .5em;">for <b>TrueType fonts</b>: + <br/> + <span class="pre-in-pp" style="margin-bottom: -2em;"> + ttf2pt1 \-b fontfilename.ttf + </span> + <i>(For TrueType fonts, this generates a PostScript .pfb file + as well as an .afm file.)</i> + </li> + </ul></li> + <li style="margin-top: .5em;">Still in your personal font directory, run + <br/> + <span class="pre-in-pp" style="margin-bottom: -2em;"> + afmtodit -e text.enc fontfilename.afm textmap <GROFF_FONTNAME> + </span> + <p id="groff-font-name" style="margin-top: .25em;"> + Q: <i>How do I choose a</i> <kbd>GROFF_FONTNAME</kbd><i>?</i> + </p> + + <p> + A: Start by considering the + <a href="definitions.html#family">family</a> + to which the font belongs. If you’re adding to a family + that already exists in groff’s + <kbd><prefix>/font/devps</kbd> directory, that will be + the first part of the font name. (See + <a href="typesetting.html#family">here</a> + for a list of families already installed, along with their + groff names.) Add to that name the appropriate weight/style + extension, listed + <a href="#style-extensions">here</a>. + </p> + + <p> + For example, if you’re adding Helvetica Light Roman, + your <kbd>GROFF_FONTNAME</kbd> would be <kbd>HL</kbd>. + If you’re adding Helvetica Light Italic, your + <kbd>GROFF_FONTNAME</kbd> would be <kbd>HLI</kbd>. + </p> + + <p> + If you’re adding a font not already in groff’s + PostScript families, first choose a meaningful name for the + <a href="definitions.html#family">family</a> + to which the font belongs. The name can be anything you like. + If, for example, the family is Garamond, you could choose + <kbd>GARAMOND</kbd>, <kbd>GARA</kbd>, <kbd>GD</kbd>, or even + just plain G as the family name. Then tack on the appropriate + style/weight extension. Thus, if you were installing Garamond + Bold Condensed Italic and had chosen <kbd>GD</kbd> as the + family name for Garamond, your <kbd>GROFF_FONTNAME</kbd> would + be <kbd>GDBCDI</kbd>. + </p> + + <p> + In mom, you can then access the Garamond family with + <kbd>.FAM GD</kbd>, and the Bold Condensed Italic font wth + <kbd>.FT BCDI</kbd>. + </p> + + <div class="box-tip"> + <p class="tip"> + <span class="note">Note:</span> + The family name need not be in upper case, and there’s + no limit to the length of the name. “Garamond”, + for example, could be the name you give the Garamond + family. In fact, you might find it preferable, since a) you + wouldn’t have to remember how you’d named the + family, and b) should you be scanning your + <a href="#site-font">site-font directory</a>, + something like GaramondBCDI will be more meaningful than, + say, GDBCDI. + </p> + </div> + </li> + <li>Copy or move <kbd>GROFF_FONTNAME</kbd> to your + <a href="#site-font">site-font directory</a>, + or change to the site-font directory and make a symlink to + <kbd>GROFF_FONTNAME</kbd> in your personal directory. + </li> + <li style="margin-top: .5em;">Copy or move the .pfb file to the directory that + holds your PostScript fonts, or change to that directory and + make a symlink to the .pfb file in your personal directory. + </li> +</ol> + +<p> +Written out in full, adding fonts looks like a lot of work. It +isn’t. Basically, it’s just: +</p> +<ul style="margin-top: -.5em;"> + <li>generate an .afm (and .pfb if the font is TrueType)</li> + <li>create the groff font</li> + <li>put the groff font in<kbd> <prefix>/font/devps</kbd></li> + <li>put the .pfb file (the actual font) with your other PostScript fonts</li> +</ul> + +<p> +After you’ve done it a couple of times, it all makes sense +and is really quite easy. Not to mention that once you understand +the process, you can write a bash script to automate the process. +Here’s an example, which you can adapt to your own needs. +The script, for installing TrueType fonts, requires an argument (the +.ttf filename), then prompts for a family directory name (e.g. +AmericanTypewriter or Futura) and a name to give the groff font +(see +<a href="#groff-font-name">here</a> +for suggestions concerning groff font naming.) The script assumes a +<kbd>~/Font</kbd> directory with subdirectories <kbd>Type1</kbd>, +<kbd>TrueType</kbd> and <kbd>Groff</kbd>. +</p> + +<div class="examples" style="margin-bottom: 0px;">Code:</div> +<div class="box-code" style="width: 726px; max-width: 726px; height: 400px; overflow: auto;"> +<span class="pre" style="color: #302419;"> +#!/bin/sh +# +# Converts .ttf file to .pfb and generates .afm +# Moves the .afm and .pfb to $HOME/Fonts/Type1 +# Generates a groff font from the .afm file and installs it +# in $HOME/Fonts/Groff +# Symlinks the groff font to groff's site-font/devps directory +# Symlinks the .afm and .pfb to /usr/share/fonts/type1/gsfonts +# + +FONT=`basename $1 .ttf` +FONTDIR="$HOME/Fonts/TrueType" +T1_FONTDIR="$HOME/Fonts/Type1" +GS_FONTDIR="/usr/share/fonts/type1/gsfonts" +GROFF_SITE_FONTDIR="/usr/local/share/groff/site-font/devps" +GROFF_FONTS="$HOME/Fonts/Groff" +TEXTMAP="$T1_FONTDIR/textmap" +TEXTENC="$T1_FONTDIR/text.enc" + +echo -n "Family directory name: " +read FAMILYDIR + +if [ ! -d "$T1_FONTDIR/$FAMILYDIR" ] ; then + echo "Creating $FAMILYDIR in $T1_FONTDIR" + mkdir $T1_FONTDIR/$FAMILYDIR +fi + +echo -n "Groff name for this font: " +read FONTNAME + +echo "Creating .pfb and .afm files from $FONT.ttf" +(ttf2pt1 \-b $FONT.ttf) + +echo "Moving .afm and .pfb file to $T1_FONTDIR/$FAMILYDIR.." +mv $FONT.afm $T1_FONTDIR/$FAMILYDIR +mv $FONT.pfb $T1_FONTDIR/$FAMILYDIR + +echo "Changing to $T1_FONTDIR/$FAMILYDIR.." +cd $T1_FONTDIR/$FAMILYDIR + +echo "Creating $FONTNAME.." +afmtodit -e $TEXTENC $T1_FONTDIR/$FAMILYDIR/$FONT.afm $TEXTMAP $FONTNAME +mv -i $FONTNAME $GROFF_FONTS +echo "Linking $FONTNAME in $GROFF_SITE_FONTDIR.." +sudo ln -s $GROFF_FONTS/$FONTNAME $GROFF_SITE_FONTDIR/$FONTNAME + +echo "Linking $FONT.pfb and $FONT.afm in $GS_FONTDIR.." +cd $GS_FONTDIR +sudo ln -s $T1_FONTDIR/$FAMILYDIR/$FONT.afm $FONT.afm +sudo ln -s $T1_FONTDIR/$FAMILYDIR/$FONT.pfb $FONT.pfb + +echo "Font installation complete" + +exit 0 +</span> +</div> + +<div class="rule-medium" style="margin-top: 2em;"><hr/></div> + +<!-- ===================================================================== --> + +<h2 id="codenotes" class="docs">Some reflections on mom</h2> + +<p> +If, as Eric Raymond asserts, open source begins with a programmer +scratching a personal itch, then mom can truly be called open +source. +</p> + +<p> +Mom had her origins in a library of groff routines I wrote over +the years to handle various aspects of typesetting and document +processing that weren’t adequately covered by ms, me, mm, and +friends. Typically, I’d use the library to cobble together +macro sets for new challenges as they came my way. +</p> + +<p> +As a writer living in a perpetual state of penury, all the computers +I’ve ever owned have been hand-me-downs—several +generations out-of-date and resource challenged. Disk space has +always been an issue, as has processor speed and available RAM. One +of the reasons I run GNU/Linux rather than the offering from Redmond +is that it has helped enormously to get the most out of my poor +little boxes. +</p> + +<p> +In Linux-land (all Unix variants, in fact), the choice of +typesetting systems basically comes down to groff or TeX. Both are +wonderful—monumental achievements if you ask me—and both +have their own particular strengths. However, for people in my +financial position (and there are millions of us around the globe, +in both developed and developing countries), TeX and groff have one +big difference: size. TeX is huge. Even its most ardent supporters +agree it suffers from bloat, on top of being complex and unwieldy to +manage. Groff is tiny by comparison, occupying minimal disk space +and having only a small memory footprint while at the same time +being flexible and powerful, typographically speaking. Back in the +Jurassic Period, I ran it successfully on a 386 with 8 megs of RAM +and a 250 meg hard disk. +</p> + +<p> +However, groff has always had a liability: it’s incredibly geeky. +Owing to its very long history, it—and its “power users” +—seem to have remained stuck in a time warp. The canonical macro packages +still look as they did back in those decades when memory was exorbitantly +expensive and every byte mattered. +</p> + +<p> +For some time now, groff users and macro writers have had the option +to use “long” names for macros (i.e. longer than two +letters, the original limit), yet have mostly chosen not to. With +long names, it’s possible to create macro sets that are +humanly readable and easy to interpret, encouraging development and +evolution. What’s more, the macros themselves need not be +terse, intimidating, and easily forgotten 1- or 2-letter commands +inserted in the body of a document. They can be sensible and +helpful to everyone, groff newbies and old hands alike. +</p> + +<p> +Mom’s macro file, om.tmac, uses long names, aliases, and a +host of other groff goodies that have become part of the whole +groff picture under the unflagging guidance of groff’s +current maintainer, Werner Lemberg. The function of nearly +every macro, number register and string can be infered simply +from its name. The file is heavily commented. A consistent, if +idiosyncratic, indenting style is used as well, significantly +improving readability. Anyone wanting to futz around with +mom’s macros should be able to do so with a minimum of head +scratching. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Addendum:</span> +As of version 1.4-a, the main macro file, om.tmac, is now stripped +of comments when groff is built from sources. om.tmac in the sources +themselves still contains the comments, as do the tarballs posted on +mom’s homepage. +</p> +</div> + +<div class="rule-medium"><hr/></div> + +<!-- ===================================================================== --> + +<h2 id="contact" class="docs">Contact the author</h2> + +<p> +If you have any questions or comments about mom, +suggestions to make, criticisms to offer, or bugs to report, use the +groff mailing list at +<a href="mailto:groff@ffii.org">groff@ffii.org</a> +(subscription information available +<a href="http://ffii.org/mailman/listinfo/groff/">here</a>) +or contact me, Peter Schaffter, directly at of the following +address: +<br/> +<span class="pre-in-pp"> + peter@schaffter.ca +</span> +Please include the word “mom” or “groff” in the +Subject: line of any message sent to my personal address, or you +risk the wrath of my implacable spam filters. :) +</p> + +<p> +If you want to visit mom’s website, you’ll find a link +to it at +<br/> +<span class="pre-in-pp"> + http://www.schaffter.ca +</span> +The site contains links to some of my fiction, all of which was +typeset with mom and groff. +</p> + +<div class="rule-long"><hr/></div> + +<!-- Navigation links --> +<table style="width: 100%; margin-top: 12px;"> +<tr> + <td style="width: 33%;"><a href="toc.html">Back to Table of Contents</a></td> + <td style="width: 33%; text-align: center;"><a href="#top">Top</a></td> + <td style="width: 33%; text-align: right;"><a href="reserved.html">Next: Reserved words</a></td> +</tr> +</table> + +</div> + +<div class="bottom-spacer"><br/></div> + +</body> +</html> +<!-- vim: fileencoding=utf-8: nomodified: --> 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 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- +This file is part of groff, the GNU roff type-setting system. + +Copyright (C) 2004, 2005, 2006, 2009, 2010 Free Software Foundation, Inc. +Written by Peter Schaffter. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with the +Invariant Sections being this comment section, with no Front-Cover +Texts, and with no Back-Cover Texts. + +A copy of the Free Documentation License is included as a file called +FDL in the main directory of the groff source package. +--> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"> + +<head> + <meta http-equiv="content-type" content="text/html;charset=utf-8"/> + <title>Mom -- Colour</title> + <link rel="stylesheet" type="text/css" href="stylesheet.css" /> +</head> + +<body style="background-color: #f5faff;"> + +<!-- ==================================================================== --> + +<div id="top" class="page"> + +<!-- Navigation links --> +<table style="width: 100%;"> +<tr> + <td><a href="toc.html">Back to Table of Contents</a></td> + <td style="text-align: right;"><a href="graphical.html#top">Next: Graphical objects</a></td> +</tr> +</table> + +<h1 class="docs">Coloured text</h1> + +<div style="text-align: center;"> +<a href="#index-color">List of color macros</a> +</div> + +<div class="rule-medium"><hr/></div> + +<h2 class="docs">Introduction</h2> + +<p> +Mom’s support for coloured text is straightforward. You begin +by telling mom about the colours you want with +<kbd><a href="#newcolor">NEWCOLOR</a></kbd> +or +<kbd><a href="#xcolor">XCOLOR</a></kbd>. +Afterward, any time you want text to be coloured, you either colour +it with an +<a href="definitions.html#inlines">inline escape</a> +that contains the colour name (e.g. <kbd>\*[red]</kbd> +or <kbd>\*[blue]</kbd>) or invoke the macro, +<kbd><a href="#color">COLOR</a></kbd>, +with the name of the colour you want. +</p> + +<p id="color-example"> +For example, say you want to have the name “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 +<kbd><a href="#newcolor">NEWCOLOR</a></kbd> +and +<kbd><a href="#xcolor">XCOLOR</a></kbd> +for a full explanation of the difference between the two. +</p> + +<p> +If you use XCOLOR, you'd enter this: +<br/> +<span class="pre-in-pp"> + .XCOLOR yellow +</span> +If you use NEWCOLOR, you might enter: +<br/> +<span class="pre-in-pp"> + .NEWCOLOR yellow RGB #FFFF00 +</span> +</p> + +<p id="color-example2" style="margin-top: -1em;"> +After “defining” (or “initializing”) the +colour “yellow”, you'd colourize the name, Jack, either +with an inline escape +<br/> +<span class="pre-in-pp"> + All work and no play makes \*[yellow]Jack\*[black] a dull boy. +</span> +or with the +<kbd><a href="#color">COLOR</a></kbd> +macro +<br/> +<span class="pre-in-pp"> + All work and no play makes + .COLOR yellow + Jack + .COLOR black + a dull boy. +</span> +Notice, in both examples, that a) you have to set the colour back +to black after “Jack”, and b) you don’t have to +define or intialize the colour, black. Mom predefines it for you. +</p> + +<p> +For information on using colour during +<a href="docprocessing.html#intro-macros-docprocessing">document processing</a>, +see +<a href="docprocessing.html#color">Colour support in document processing</a>. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +Mom’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 <kbd>\D</kbd> +<a href="definitions.html#inlines">inline escapes</a>, +although you may give a colour as one of the arguments to +mom’s “box” and “circle” macros, +<a href="graphical.html#dbx">DBX</a> +and +<a href="graphical.html#dcl">DCL</a> +when the first argument to these macros is <kbd>SOLID</kbd>. +</p> +</div> + +<div class="box-tip"> +<p class="tip"> +<span class="experts">Experts:</span> +If you’re accustomed to using groff’s +<kbd>.defcolor</kbd> to define colours, and groff’s inline +<kbd>\m[<colorname>]</kbd> to call them, you may continue to +do so without confusing mom. +</p> +</div> + +<div class="macro-list-container"> +<h3 id="index-color" class="macro-list">Coloured text macros</h3> + +<ul class="macro-list"> + <li><a href="#newcolor">NEWCOLOR</a></li> + <li><a href="#xcolor">XCOLOR</a></li> + <li><a href="#color">COLOR</a></li> + <li><a href="#color-inline">\*[<colorname>]</a> (inline escape)</li> +</ul> +</div> + +<div class="rule-medium" style="margin-bottom: 1.5em;"><hr/></div> + +<!-- -NEWCOLOR- --> + +<div class="macro-id-overline"> +<h3 id="newcolor" class="macro-id">Creating (initializing) a colour with NEWCOLOR</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>NEWCOLOR</b> <kbd class="macro-args"><colour name> [<colour scheme>] <colour components></kbd> +</div> + +<p> +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 <kbd>.NEWCOLOR</kbd> (or +<kbd><a href="#xcolor">.XCOLOR</a></kbd>), +mom doesn’t have a clue what you mean when you reference a +colour (with +<a href="#color">COLOR</a> +or +<a href="#color-inline"><kbd>\*[<color name>]</kbd></a>). +</p> + +<p> +The first argument to 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. +</p> + +<p> +The second argument, which is entirely optional, is the +“colour scheme” you want mom to use when mixing the +colour. Valid arguments are +<br/> +<span class="pre-in-pp"> + RBG (3 components: red green blue) + CYM (3 components: cyan yellow magenta) + CMYK (4 components: cyan magenta yellow black) + GRAY (1 component) +</span> +If you omit the second argument, mom assumes you +want RGB. +</p> + +<p> +The final argument is the components of your colour. This can be +hexadecimal string starting with a pound sign (<kbd>#</kbd>) (for +colour values in the 0-255 range) or two pound signs (<kbd>##</kbd>) +(for colour values in the 0-65535 range), or it can be a series of +decimal digits, separated by spaces, one digit per component, with +the argument enclosed in double quotes. (If this is all gibberish +to you, see +<a href="#color-tip">Tips for newbies</a>.) +</p> + +<p> +Thus, to tell mom about a colour named “YELLOW”, you +could enter one of the following: +<br/> +<span class="pre-in-pp"> + .NEWCOLOR YELLOW #FFFF00 \"or ##FFFFFFFF0000 or "1 1 0" + .NEWCOLOR YELLOW RGB #FFFF00 \"or ##FFFFFFFF0000 or "1 1 0" + .NEWCOLOR YELLOW CYM #00FF00 \"or ##0000FFFF0000 or "0 1 0" + .NEWCOLOR YELLOW CYMK #00FF0000 \"or ##0000FFFF00000000 or "1 1 0" +</span> +After you've told mom about a colour, you can then get her to set +text in that colour either with the +<a href="definitions.html#inlines">inline escape</a>, +<a href="#color-inline"><kbd>\*[<colorname>]</kbd></a>, +or the macro, +<a href="#color">COLOR</a>. +(See the +<a href="#color-example">example</a>, +above.) +</p> + +<div class="box-tip"> +<p class="tip-top"> +<span class="note">Note:</span> +The colorname you give to NEWCOLOR may be used with groff’s +<kbd>\m[<colorname>]</kbd> inline escape (the <kbd>\m</kbd> +escape is used to set text and rule colours). Thus, assuming +a colorname “blueblack” set with NEWCOLOR, +<kbd>\*[blueblack]</kbd> and <kbd>\m[blueblack]</kbd> are +equivalent. Furthermore, the colorname can be given as an argument +to <b>groff</b>’s +<a href="definitions.html#primitives">primitive</a> +request, <kbd>.gcolor</kbd> (which does the same thing as +<kbd>\m[<colorname>]</kbd>). +</p> + +<p class="tip-bottom"> +Equally, the colorname may be used with +<kbd>\M[<colorname>]</kbd> and <kbd>.fcolor</kbd>, which set +the “fill” colour for solid graphical objects. +</p> +</div> + +<div class="box-tip"> +<p id="color-tip" class="tip-top"> +<span class="tip">Tips for newbies:</span> +Colour manipulation can be tremendously confusing if you don’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”. +</p> + +<p class="tip-bottom"> +Alternatively, you can use mom’s simpler +<kbd><a href="#xcolor">XCOLOR</a></kbd> +macro to initialize one of the 256 pre-defined X colours by +supplying the name of the color as an argument. +</p> +</div> + +<!-- -XCOLOR- --> + +<div class="macro-id-overline"> +<h3 id="xcolor" class="macro-id">Initializing a colour with XCOLOR</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>XCOLOR</b> <kbd class="macro-args"><X colorname> [<alias>]</kbd> +</div> + +<p class="requires"> +<kbd style="font-style: normal"><X colorname></kbd> <i>must be all one word, all lower case.</i> +<br/> +(See +<a href="#xcolor-names" style="font-style: normal;">Finding X color names</a> +for how to get a list of valid colour names.) +</p> + +<p> +XCOLOR is similar to NEWCOLOR in that it tells mom to initialize a +colour, but it’s easier to use. All you have to do is pass +it, as an argument, the valid name of one of the 256 pre-defined +X colours. The name must be all one word, and, breaking with mom +policy, it must be entered in lower case. +</p> + +<p> +For example, if you want to intialize the X colour, coral, all you +have to do is enter +<br/> +<span class="pre-in-pp"> + .XCOLOR coral +</span> +Afterwards +<br/> +<span class="pre-in-pp"> + .COLOR coral +</span> + +will colourize subsequent text coral until you instruct mom to +return to black, or some other pre-defined, initialized colour. +(The +<a href="definitions.html#inlines">inline escape</a> +<kbd>\*[coral]</kbd> will equally colourize text coral after you've +initialized the colour with XCOLOR.) +</p> + +<p> +The downside of XCOLOR is that you can’t create custom +colours. This restriction, however, is mitigated by the fact that +for many users, 256 colours is more than enough to play around with. +</p> + +<p> +While some X colours have fanciful names (peachpuff, papayawhip, +thistle, snow), many are self-explanatory and self-descriptive +in ordinary colour terms. “blue” is pure (rgb) +blue, “green” is pure (rgb) green, and so on. +Furthermore, for many X colors, there exist four variants, each +representing increasingly darker shades of the same colour. +For example, “blue1” is a relatively bright blue; +“blue2”, “blue3” and “blue4” are +increasingly darker shades. For that reason, you may find XCOLOR is +a better choice than NEWCOLOR when it comes to initializing common +colors. +</p> + +<p> +The whimsical nature of X colour names sometimes makes for names +that are long to type in, e.g. “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 +<br/> +<span class="pre-in-pp"> + .XCOLOR mediumspringgreen mygreen +</span> +or +<span class="pre-in-pp"> + .XCOLOR mediumspringgreen MYGREEN +</span> +so that whenever you want text mediumspringgreen-ed, you +can use either <kbd>.COLOR mygreen</kbd> (or +<kbd>.COLOR MYGREEN</kbd>) or the inline escape +<kbd>\*[mygreen]</kbd> (or <kbd>\*[MYGREEN]</kbd>.) +</p> + +<h3 id="xcolor-names" class="docs">Finding X color names</h3> + +<p> +There are two ways of finding the names of the pre-defined X +colours. One is to consult the file, rgb.txt, included with all +X11 installations. The location of the file on a Debian GNU/Linux +distribution is typically /etc/X11/rgb.txt. Other distributions and +other X installations may have the file in another location. The +file lists the colour names, but doesn’t show you what the +colours actually look like. +</p> + +<p> +A better way to get the colour names, as well as to see what the +colours look like, is to fire up a colour chooser (like xcolorsel) +that both lists the colour names and shows a swatch of the colour +as well. +</p> + +<p> +Whichever method you use to find X color names, remember that the +names, passed as arguments to XCOLOR, must be all one word, all in +lower case. +</p> + +<div class="box-tip"> +<p class="tip-top"> +<span class="note">Note:</span> +Both the colorname and the alias you give to XCOLOR may be +used with groff’s <kbd>\m[<colorname>]</kbd> +inline escape (the <kbd>\m</kbd> escape is used to set +text and rule colours). Thus, assuming an X-colorname +“mediumspringgreen” set with XCOLOR, and an alias, +“mygreen”, <kbd>\*[mediumspringgreen]</kbd>, +<kbd>\m[mediumspringgreen]</kbd>, <kbd>\*[mygreen]</kbd> and +<kbd>\m[mygreen]</kbd> are all equivalent. Furthermore, both the +colorname and the alias can be given as an argument to groff’s +<a href="definitions.html#primitives">primitive</a> +request, <kbd>.gcolor</kbd> (which does the same thing as +<kbd>\m[<colorname>]</kbd>). +</p> + +<p class="tip-bottom"> +The colorname initialized with XCOLOR <i>but not the +alias</i> may also be used with groff’s inline escape, +<kbd>\M[<colorname>]</kbd>, and the corresponding primitive, +<kbd>.fcolor</kbd>, both of which set the “fill” colour +for solid graphical objects. If you need a colour initialized with +XCOLOR for <kbd>\M</kbd> or <kbd>.fcolor</kbd>, you MUST give the +full colorname; the alias won’t work. +</p> +</div> + +<!-- -COLOR- --> + +<div class="macro-id-overline"> +<h3 id="color" class="macro-id">Invoking a color</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>COLOR</b> <kbd class="macro-args"><colorname></kbd> +</div> + +<p id="color-inline" class="requires" style="font-style: normal;"> +Inline: <kbd>\*[<colorname>]</kbd> +</p> + +<p> +Once you've told mom about a colour (via +<a href="#newcolor">NEWCOLOR</a> +or +<a href="#xcolor">XCOLOR</a>, +you use either the macro, COLOR, or the +<a href="definitions.html#inlines">inline escape</a>, +<kbd>\*[<colorname>]</kbd>, to cause mom to +set subsequent text in that colour. See the +<a href="#color-example2">example</a>, +above, which shows both in action. +</p> + +<div class="box-tip"> +<p class="tip-top"> +<span class="note">Note:</span> +You can use the <kbd>\*[<colorname>]</kbd> inline escape in +any +<a href="docprocessing.html#top">document processing</a> +macro that takes a +<a href="definitions.html#stringargument">string argument</a>. +However, you must remember to reset the colour at the end of the +argument (typically with <kbd>\*[black]</kbd>) unless you want all +subsequent invocations of that particular macro to be colourized. +</p> + +<p> +Furthermore, if you use <kbd>\*[<colorname>]</kbd> in the +string argument passed to +<a href="docelement.html#head">HEAD</a>, +<a href="docelement.html#subhead">SUBHEAD</a> +or +<a href="docelement.html#parahead">PARAHEAD</a>, +and you've requested that any of these types of heads be numbered, +the numbers themselves will not be coloured, only the text you +passed the macro. If you wish the numbers to be colourized as well, +you must explicitly tell mom that you wish all of the head(s), +subhead(s) or parahead(s), including the numbers, colourized by +invoking the appropriate +<a href="docelement.html#docelement-control">control macro</a>. +</p> + +<p class="tip-bottom"> +For colorizing underscored text, see +<a href="goodies.html#underscore-color">Colorizing underscored text</a> +in the notes at the end of +<a href="goodies.html#underscore">UNDERSCORE</a>. +</p> +</div> + +<div class="rule-long"><hr/></div> + +<!-- Navigation links --> +<table style="width: 100%; margin-top: 12px;"> +<tr> + <td style="width: 33%;"><a href="toc.html">Back to Table of Contents</a></td> + <td style="width: 33%; text-align: center;"><a href="#top">Top</a></td> + <td style="width: 33%; text-align: right;"><a href="graphical.html#top">Next: Graphical objects</a></td> +</tr> +</table> + +</div> + +<div class="bottom-spacer"><br/></div> + +</body> +</html> +<!-- vim: fileencoding=utf-8: nomodified: --> 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 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- +This file is part of groff, the GNU roff type-setting system. + +Copyright (C) 2004, 2005, 2006, 2009, 2010 Free Software Foundation, Inc. +Written by Peter Schaffter. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with the +Invariant Sections being this comment section, with no Front-Cover +Texts, and with no Back-Cover Texts. + +A copy of the Free Documentation License is included as a file called +FDL in the main directory of the groff source package. +--> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"> + +<head> + <meta http-equiv="content-type" content="text/html;charset=utf-8"/> + <title>Mom -- Document processing, creating cover pages</title> + <link rel="stylesheet" type="text/css" href="stylesheet.css" /> +</head> + +<body style="background-color: #f5faff;"> + +<!-- ==================================================================== --> + +<div id="top" class="page"> + +<!-- Navigation links --> +<table style="width: 100%;"> +<tr> + <td><a href="toc.html">Back to Table of Contents</a></td> + <td style="text-align: right;"><a href="tables-of-contents.html#top">Next: Tables of contents</a></td> +</tr> +</table> + +<h1 class="docs">Creating cover pages</h1> + +<div style="width: 63%; margin: auto;"> +<ul class="no-enumerator"> + <li><a href="#cover-intro">Introduction to cover pages</a> + <ul style="margin-left: -.5em; list-style-type: disc;"> + <li><a href="#important-note">Important note</a></li> + <li><a href="#desc">Description of cover pages</a></li> + <li><a href="#pagination">Headers/footers/pagination and cover pages</a></li> + <li><a href="#design">Designing your own cover pages</a></li> + </ul></li> + <li><a href="#index-covers">Cover and document cover macros</a> + <ul style="margin-left: -.5em; list-style-type: disc;"> + <li><a href="#cover">COVER / DOC_COVER</a> + <ul style="margin-left: -.5em; list-style-type: circle;"> + <li><a href="#required-arg">The required argument</a></li> + <li><a href="#chapter">How the CHAPTER argument and friends work</a></li> + <li><a href="#optional-args">The optional arguments</a></li> + <li><a href="#doctype">What the DOCTYPE argument means</a></li> + <li><a href="#blankpage">What the BLANKPAGE argument means</a></li> + </ul></li> + </ul></li> + <li><a href="#on-off">Enabling/disabling automatic generation of cover pages</a></li> + <li><a href="#cover-control">Control macros for covers and doc covers</a></li> +</ul> +</div> + +<div class="rule-medium"><hr/></div> + +<h2 id="cover-intro" class="docs">Introduction to cover pages</h2> + +<p> +Though identical in treatment, mom provides two kinds of cover +pages: section cover pages (which I shall refer to simply as +cover pages) and document cover pages (”doc +covers”). +</p> + +<p> +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. +</p> + +<p> +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”. +</p> + +<p> +In non-collated documents (say, an essay) you can use either a cover +or doc cover to generate the cover sheet. +</p> + +<p> +In addition, nothing prevents you from generating both a doc cover +and a cover for every document in a collated document. Or you can +selectively disable the automatic generation of either doc covers or +covers in a collated document on-the-fly. +</p> + +<div id="important-note" class="box-important"> +<p class="tip"> +<span class="important">Important note:</span> +Automatic generation of covers or doc covers after the first one(s) +only takes place if you are working with collated documents. Mom +provides no mechanism for saying ”print a section cover +here even though I'm still working on the same (non-collated) +document.” +</p> +</div> + +<h3 id="desc" class="docs">Description of cover pages</h3> + +<p> +By default, mom typesets covers and doc covers identically to +<a href="definitions.html#docheader">docheaders</a> +(see +<a href="docprocessing.html#docheader-control">How to change the look of docheaders</a> +for a description of what a docheader looks like). The only +differences are +</p> +<ul style="margin-top: -.5em; margin-bottom: -.5em;"> + <li>the position on the page where the information is output</li> + <li>the (optional) addition of copyright and miscellaneous information</li> + <li>there’s no running text underneath</li> +</ul> + +<p> +You tell mom what you want to appear on cover pages through the +arguments you pass to +<a href="#cover">COVER</a> +and/or +<a href="#cover">DOC_COVER</a>. +Provided you have already given mom the appropriate reference macros +(e.g. +<a href="docprocessing.html#title">TITLE</a> +or +<a href="docprocessing.html#author">AUTHOR</a>), +she will output covers and doc covers identically to how she +would output docheaders containing the same information. +</p> + +<p> +By default, mom starts covers and doc covers one-third of the way +down the page. This can be changed through the use of the control +macros COVER_ADVANCE / DOC_COVER_ADVANCE. +</p> + +<p> +If you request copyright information (and have already given mom the +reference macro, +<a href="docprocessing.html#copyright">COPYRIGHT</a>), +she sets it, by default, in a smaller +<a href="definitions.html#ps">point size</a> +in the bottom right hand corner of the cover or doc cover. The +position, as well as all of the standard typesetting parameters, can be +altered via control macros. +</p> + +<p> +Similarly, if you request miscellaneous information (and have +already given mom the reference macro, +<a href="docprocessing.html#misc">MISC</a>), +she sets it, by default, in a smaller point size in the bottom left +hand corner of the cover or doc cover. As with the copyright, the +position and type specs can be altered via control macros. +</p> + +<h3 id="pagination" class="docs">Headers/footers/pagination and cover pages</h3> + +<p> +Mom does not set any +<a href="definitions.html#header">headers</a> +or +<a href="definitions.html#footer">footers</a> +on cover pages. Neither does she set any page numbers. From +the point of view of pagination, covers and doc covers are by +default considered ”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. +</p> + +<h3 id="design" class="docs">Designing your own cover pages</h3> + +<p> +Finally, if you want to design your own cover page(s), you can +always typeset them (using the +<a href="typesetting.html#macros-typesetting">typesetting macros</a>), +invoke +<a href="typesetting.html#newpage"><kbd>.NEWPAGE</kbd></a>, +set up your document (see +<a href="docprocessing.html#docprocessing-tut">Tutorial – Setting up a mom document</a>), +and lastly invoke +<a href="docprocessing.html#start"><kbd>.START</kbd></a>. +The cover page, and any typesetting commands on it, will have no +effect on mom’s processing of the document after you invoke +<kbd><a href="docprocessing.html#START">.START</a></kbd>. +</p> + +<div class="macro-list-container"> +<h3 id="index-covers" class="macro-list">Cover and document cover macros</h3> +<ul class="macro-list"> + <li><a href="#cover">COVER and DOC_COVER</a> + <ul style="margin-left: -.5em; list-style-type: disc;"> + <li><a href="#required-and-optional-args">Required and optional arguments</a></li> + </ul></li> + <li><a href="#on-off">Enabling/disabling automatic generation of cover pages</a> + <ul style="margin-left: -.5em; list-style-type: disc;"> + <li><a href="#covers">COVERS</a></li> + <li><a href="#doc-covers">DOC_COVERS</a></li> + </ul></li> + <li><a href="#cover-control">Control macros for covers and doc covers</a></li> +</ul> +</div> + +<!-- -COVER- --> + +<div class="macro-id-overline"> +<h3 id="cover" class="macro-id">COVER and DOC_COVER</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>COVER</b> <kbd class="macro-args">(see required and optional arguments, below)</kbd> +</div> + +<div id="doc-cover" class="box-macro-args" style="margin-top: 1em;"> +Macro: <b>DOC_COVER</b> <kbd class="macro-args">(see required and optional arguments, below)</kbd> +</div> + +<div id="required-and-optional-args" style="margin-top: 1em; padding-bottom: 3px; white-space: nowrap; overflow: auto;"> +<b><a href="#required-arg">Required argument:</a></b> <kbd class="macro-args">TITLE | DOCTITLE | COVERTITLE | CHAPTER | CHAPTER_TITLE | CHAPTER+TITLE</kbd> +</div> + +<div style="margin-top: .5em; padding-bottom: 3px; white-space: nowrap; overflow: auto;"> +<b><a href="#optional-args">Optional arguments:</a></b> <kbd class="macro-args">[ SUBTITLE AUTHOR DOCTYPE COPYRIGHT MISC BLANKPAGE ]</kbd> +</div> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +These macros should be placed in the +“style-sheet” section of your document setup (see +<a href="docprocessing.html#docprocessing-tut">Tutorial – Setting up a mom document</a>), +i.e. after PRINTSTYLE (and/or DOCTYPE and/or COPYSTYLE), but before START. +</p> +</div> + +<p style="margin-top: -.25em;"> +COVER and DOC_COVER behave identically. The reason mom provides +two macros for cover page generation is so that you can have two +different kinds of covers with different information on each. +</p> + +<p> +Imagine, for a moment, you’ve written a document comprised of +three sections. When you +<a href="rectoverso.html#collate">COLLATE</a> +the document for output, you could use DOC_COVER to generate a cover +page that contained the name of the entire document, your (the +author’s) name, and perhaps the copyright date. Subsequently, +you could use COVER, after each <kbd>.COLLATE</kbd> but before each +<kbd><a href="docprocessing.html#start">.START</a></kbd>, +to generate a cover page (or cover ”sheet”, if you +prefer) containing just the name of the section. +</p> + +<h4 id="required-arg" class="docs" style="margin-top: -.5em;">The required argument</h4> + +<p> +Both COVER and DOC_COVER, whenever invoked, require a first +argument, as listed above. This first argument will become the +first bit of information mom prints on the cover or doc cover (i.e. +the title). +</p> + +<p> +In order for the information to appear, you must, of course, have +given mom the appropriate +<a href="docprocessing.html#reference-macros">reference macro</a>. +A list of first arguments with their equivalent reference macros follows. +</p> + +<dl style="margin-top: -.5em;"> + <dt class="no-italic"><kbd>TITLE</kbd></dt> + <dd> + – means the argument you gave to <a href="docprocessing.html#title">TITLE</a> + </dd> + <dt class="no-italic"><kbd>DOCTITLE</kbd></dt> + <dd> + – means the argument you gave to <a href="docprocessing.html#doc-title">DOCTITLE</a> + </dd> + <dt class="no-italic"><kbd>COVERTITLE</kbd></dt> + <dd> + – means the argument you gave to <a href="docprocessing.html#covertitle">COVERTITLE</a> + or + <a href="docprocessing.html#doc-covertitle">DOC_COVERTITLE</a> + </dd> + <dt class="no-italic"><kbd>CHAPTER, CHAPTER_TITLE, CHAPTER+TITLE</kbd></dt> + <dd> + – see below, <i>How the CHAPTER argument and friends work</i> + </dd> +</dl> + +<h5 id="chapter" class="docs" style="margin-top: -.5em; text-transform: none;">How the CHAPTER argument and friends work</h5> + +<p> +<span style="display: block; margin-bottom: -1.25em; font-weight: bold;">• CHAPTER</span> +<br/> +The <kbd>CHAPTER</kbd> argument will print the +<a href="docprocessing.html#chapter-string">CHAPTER_STRING</a> +concatenated with the chapter number you gave to +<a href="docprocessing.html#chapter">CHAPTER</a>. +For example, assuming a vanilla setup for your chapter: +<br/> +<span class="pre-in-pp" style="color: #64614a;"> + .CHAPTER 1 + .CHAPTER_TITLE "The Bonny Blue Yonder" + <span style="color: #941614;">.COVER CHAPTER</span> \"(or <span style="color: #941614;">.DOC_COVER CHAPTER</span>) +</span> +will print (and only print) +<br/> +<span class="pre-in-pp"> + Chapter 1 +</span> +</p> + +<p style="margin-top: -1em;"> +<span style="display: block; margin-bottom: -1.25em; font-weight: bold;">• CHAPTER_TITLE</span> +<br/> +The <kbd>CHAPTER_TITLE</kbd> argument will print the chapter title +you gave to +<a href="docprocessing.html#chapter-title">CHAPTER_TITLE</a>. +For example, assuming a vanilla setup for your chapter: +<br/> +<span class="pre-in-pp" style="color: #64614a;"> + .CHAPTER 1 + .CHAPTER_TITLE "The Bonny Blue Yonder" + <span style="color: #941614;">.COVER CHAPTER_TITLE</span> \"(or <span style="color: #941614;">.DOC_COVER CHAPTER_TITLE</span>) +</span> +will print (and only print) +<br/> +<span class="pre-in-pp"> + The Bonny Blue Yonder +</span> +</p> + +<p style="margin-top: -1em;"> +<span style="display: block; margin-bottom: -1.25em; font-weight: bold;">• CHAPTER+TITLE</span> +<br/> +The <kbd>CHAPTER+TITLE</kbd> argument will print both the +concatenated chapter string+number and the chapter title. For +example, assuming a vanilla setup for your chapter: +<br/> +<span class="pre-in-pp" style="color: #64614a;"> + .CHAPTER 1 + .CHAPTER_TITLE "The Bonny Blue Yonder" + <span style="color: #941614;">.COVER CHAPTER+TITLE</span> \"(or <span style="color: #941614;">.DOC_COVER CHAPTER+TITLE</span>) +</span> +will print +<br/> +<span class="pre-in-pp"> + Chapter 1 + The Bonny Blue Yonder +</span> +</p> + +<h4 id="optional-args" class="docs" style="margin-top: -1em;">The optional arguments</h4> + +<p> +The remainder of the arguments to COVER and +DOC_COVER are optional. They refer specifically to +the information you gave the +<a href="docprocessing.html#reference-macros">reference macros</a> +bearing the same name as the arguments. +</p> + +<p> +You may enter as many or as few as you would like to see on your +cover or doc cover. The only hitch is—pay attention, +class—they must be entered in the order given above. +For example, if you want <kbd>TITLE</kbd>, <kbd>AUTHOR</kbd>, +<kbd>COPYRIGHT</kbd> and <kbd>MISC</kbd> +<br/> +<span class="pre-in-pp"> + .COVER TITLE AUTHOR COPYRIGHT MISC +</span> + +is correct, while +<br/> +<span class="pre-in-pp"> + .COVER TITLE AUTHOR MISC COPYRIGHT +</span> + +is not. +</p> + +<h5 id="doctype" class="docs" style="text-transform: none; margin-top: -.5em;">What the DOCTYPE argument means</h5> + +<p> +When you pass COVER or DOC_COVER +the argument, <kbd>DOCTYPE</kbd>, it refers to the argument you gave +to +<a href="docprocessing.html#doctype">DOCTYPE</a> <kbd>NAMED</kbd>. +For example, if, in your +<a href="docprocessing.html#docstyle-macros">docstyle macros</a> +you gave a +<br/> +<span class="pre-in-pp"> + .DOCTYPE NAMED "Abstract" +</span> +the argument, <kbd>DOCTYPE</kbd>, given to the COVER or DOC_COVER +macros, would mean that you wanted the word, Abstract, to appear on +the cover or doc cover underneath the title and/or author(s), just +as it would in the +<a href="docprocessing.html#docheader">docheader</a>. +</p> + +<h5 id="blankpage" class="docs" style="text-transform: none; margin-top: -.5em;">What the BLANKPAGE argument means</h5> + +<p> +If the final argument to DOC_COVER or COVER is <kbd>BLANKPAGE</kbd>, +mom will insert a blank page after the doc cover or cover. This is +particularly useful if you intend to print your document two-sided, +since, in two-sided printing, there may be instances where you do +not want text on the reverse side of cover or title pages. +</p> + +<p> +If you enable DOC_COVERS_COUNT_PAGES and/or COVERS_COUNT_PAGES, the +blank page will be taken into account in the pagination scheme, +though no page number appears on it. Otherwise, blank pages are +invisible to mom's pagination. +</p> + +<!-- -ENABLING/DISABLING- --> + +<div class="macro-id-overline"> +<h3 id="on-off" class="macro-id">Enabling/disabling automatic generation of cover pages</h3> +</div> + +<div id="covers" class="box-macro-args"> +Macro: <b>COVERS</b> <kbd class="macro-args"><toggle></kbd> +</div> + +<div id="doc-covers" class="box-macro-args" style="margin-top: 1em;"> +Macro: <b>DOC_COVERS</b> <kbd class="macro-args"><toggle></kbd> +</div> + +<p> +By default, if you give mom a +<a href="#cover">COVER</a> +or +<a href="#doc-cover">DOC_COVER</a> +directive, she will print the cover or doc cover. In a document +that contains sections, articles or chapters formerly treated as +”one-off’s” but now being +<a href="rectoverso.html#collate-intro">collated</a>, +such behaviour may not be desirable. +</p> + +<p> +Mom lets you selectively enable or disable the generation of covers +and/or doc covers with the toggle macros, COVERS and DOC_COVERS. +Because they’re toggle macros, simply invoking them by +themselves enables automatic cover or doc cover generation, while +invoking them with any argument at all (<kbd>OFF, QUIT, X</kbd>, +etc) disables cover or doc cover generation. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +You must place these macros prior to any instance of +<a href="docprocessing.html#start">START</a>. +Since they’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 <kbd>OFF, NO, X</kbd>, etc. argument), +is immediately after the first invocation of START. By doing so, +you ensure they meet the requirement of preceding all subsequent +instances of START. +</p> +</div> + +<div class="rule-short"><hr/></div> + +<h2 id="cover-control" class="macro-group">Control macros for covers and doc covers</h2> + +<p> +The default typographic appearance of the items on a cover or doc +cover is identical to that of the items in a +<a href="definitions.html#docheader">docheader</a>. +(See +<a href="docprocessing.html#docheader-desc">Docheader description</a> +for a description of the defaults.) +</p> + +<p> +<a href="docprocessing.html#copyright">COPYRIGHT</a> +and +<a href="docprocessing.html#misc">MISC</a>, +which do not appear in docheaders, have the following default +characteristics: +</p> +<ul style="margin-top: -.5em; margin-bottom: -.5em;"> + <li>the COPYRIGHT line is set in the bottom right hand corner + of the page, 2 + <a href="definitions.html#ps">point sizes</a> + smaller than the size of + <a href="definitions.html#running">running text</a> + </li> + <li>MISC lines are set in the bottom left hand + corner of the page, in the same family, font and point size + as the copyright line. + </li> +</ul> + +<p> +The defaults for the entirety of covers and doc covers, and all the +elements thereon, can be changed with control macros whose defaults +and arguments are identical to the corresponding control macros +governing docheaders. The only difference is the name by which you +invoke them. +</p> + +<p> +A complete list of cover and doc cover control macros follows. +Please refer to +<a href="docprocessing.html#index-docheader-control">docheader control</a> +in order to get the defaults and any special instructions for usage. +</p> + +<h3 id="index-cover-control" class="docs" style="margin-bottom: .25em;">Cover / doc cover control macros and defaults</h3> + +<div class="defaults-container" style="padding-bottom: 8px;"> + +<span class="pre defaults"> +COVER_ADVANCE DOC_COVER_ADVANCE -+ +COVER_FAMILY DOC_COVER_FAMILY | like +COVER_LEAD DOC_COVER_LEAD | DOCHEADER_<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 +</span> +</div> + +<p style="margin-top: -2em;"> +<b>Note:</b> +<br/> +COVER_COUNTS_PAGES and DOC_COVER_COUNTS_PAGES are toggle macros, +hence invoking them by themselves means that mom will consider +covers and doc covers in the pagination scheme; invoking them with +any argument (<kbd>OFF, NO, X</kbd>, etc.) means they are ignored. +The default is to ignore them. +</p> + +<div class="rule-long"><hr/></div> + +<!-- Navigation links --> +<table style="width: 100%; margin-top: 12px;"> +<tr> + <td style="width: 33%;"><a href="toc.html">Back to Table of Contents</a></td> + <td style="width: 33%; text-align: center;"><a href="#top">Top</a></td> + <td style="width: 33%; text-align: right;"><a href="tables-of-contents.html">Next: Tables of contents</a></td> +</tr> +</table> + +</div> + +<div class="bottom-spacer"><br/></div> + +</body> +</html> +<!-- vim: fileencoding=utf-8: nomodified: --> 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 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- +This file is part of groff, the GNU roff type-setting system. + +Copyright (C) 2004, 2005, 2006, 2009, 2010 Free Software Foundation, Inc. +Written by Peter Schaffter. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with the +Invariant Sections being this comment section, with no Front-Cover +Texts, and with no Back-Cover Texts. + +A copy of the Free Documentation License is included as a file called +FDL in the main directory of the groff source package. +--> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"> + +<head> + <meta http-equiv="content-type" content="text/html;charset=utf-8"/> + <title>Mom -- Definitions and Terms</title> + <link rel="stylesheet" type="text/css" href="stylesheet.css" /> +</head> + +<body style="background-color: #f5faff;"> + +<!-- ==================================================================== --> + +<div id="top" class="page"> + +<!-- Navigation links --> +<table style="width: 100%;"> + <tr> + <td><a href="toc.html">Back to Table of Contents</a></td> + <td style="text-align: right;"><a href="using.html#top">Next: Using mom</a></td> + </tr> + </table> + +<h1 id="terms" class="docs">Definitions of terms used in this manual</h1> + +<p> +I use a number of typesetting-specific and groff-specific terms +throughout this documentation, as well as a few terms that apply +to mom herself. To make life easier, I’ll explain +them here. Refer back to this section should you encounter a word +or concept you’re not familiar with. +</p> + +<div class="rule-short" style="margin-top: 18px; margin-bottom: 28px;"><hr/></div> + +<div class="col-1-definitions"> + <table class="definitions"> + <tr><th class="definitions">Typesetting terms</th></tr> + <tr> + <td> + <a href="#ascender">Ascender</a><br/> + <a href="#baseline">Baseline</a><br/> + <a href="#ballotbox">Ballot box</a><br/> + <a href="#bullet">Bullet</a><br/> + <a href="#capheight">Cap-height</a><br/> + <a href="#descender">Descender</a><br/> + <a href="#discretionaryhyphen">Discretionary hyphen</a><br/> + <a href="#dropcap">Drop cap</a><br/> + <a href="#em">Em/en</a><br/> + <a href="#family">Family</a><br/> + <a href="#figurespace">Figure space/Digit space</a><br/> + <a href="#fixedwidthfont">Fixed width font</a><br/> + <a href="#fixedwidthspace">Fixed width space</a><br/> + <a href="#font">Font</a><br/> + <a href="#force">Force justify</a><br/> + <a href="#just">Justify/justification</a><br/> + <a href="#gutter">Gutter</a><br/> + <a href="#kern">Kerning</a><br/> + <a href="#kernunit">Kern Units</a><br/> + <a href="#leading">Lead/leading</a><br/> + <a href="#leader">Leaders</a><br/> + <a href="#ligatures">Ligature</a><br/> + <a href="#picaspoints">Picas/Points</a><br/> + <a href="#ps">Point Size</a><br/> + <a href="#quad">Quad</a><br/> + <a href="#rag">Rag</a><br/> + <a href="#shape">Shape</a><br/> + <a href="#solid">Solid/set solid</a><br/> + <a href="#trackkerning">Track kerning/Line kerning</a><br/> + <a href="#unbreakablespace">Unbreakable space</a><br/> + <a href="#weight">Weight</a><br/> + <a href="#wordspace">Word space</a><br/> + <a href="#xheight">x-height</a><br/> + </td> + </tr> + </table> +</div> + +<div class="col-2-definitions"> + <table class="definitions"> + <tr><th class="definitions">Groff terms</th></tr> + <tr> + <td> + <a href="#alias">Alias</a><br/> + <a href="#arguments">Arguments</a><br/> + <a href="#commentlines">Comment lines</a><br/> + <a href="#controllines">Control Lines</a><br/> + <a href="#filled">Filled lines</a><br/> + <a href="#inlines">Inline escapes</a><br/> + <a href="#inputline">Input line</a><br/> + <a href="#macros">Macros</a><br/> + <a href="#units">Machine units</a><br/> + <a href="#numericargument">Numeric argument</a><br/> + <a href="#outputline">Output line</a><br/> + <a href="#primitives">Primitives</a><br/> + <a href="#stringargument">String Argument</a><br/> + <a href="#unitofmeasure">Unit of measure</a><br/> + <a href="#zerowidthcharacter">Zero-width character</a><br/> + </td> + </tr> + </table> +</div> + +<div class="col-3-definitions"> + <table class="definitions"> + <tr><th class="definitions">Mom terms</th></tr> + <tr> + <td> + <a href="#blockquote">Blockquote</a><br/> + <a href="#controlmacro">Control macro</a><br/> + <a href="#docheader">Docheader</a><br/> + <a href="#epigraph">Epigraph</a><br/> + <a href="#footer">Footer</a><br/> + <a href="#head">Head</a><br/> + <a href="#header">Header</a><br/> + <a href="#linebreak">Linebreak</a><br/> + <a href="#parahead">Paragraph head</a><br/> + <a href="#quote">Quote</a><br/> + <a href="#running">Running text</a><br/> + <a href="#subhead">Subhead</a><br/> + <a href="#toggle">Toggle</a><br/> + </td> + </tr> + </table> +</div> + +<h3 id="typesetting-terms" class="docs">Typesetting terms</h3> +<dl> + <dt id="ascender">Ascender</dt> + <dd> + The portion of a letter that extends above the bowl. For + example, the letters a, c, and e have no ascenders. The letters + b, d, and h do. + </dd> + + <dt id="baseline">Baseline</dt> + <dd> + The imaginary line on which the bottoms of capital letters and + the bowls of lower case letters rest. + </dd> + + <dt id="ballotbox">Ballot box</dt> + <dd> + An unfilled square, usually + <a href="#capheight">cap-height</a> + in size, typically placed beside items in a checklist. + </dd> + + <dt id="bullet">Bullet</dt> + <dd> + A small, filled circle typically found beside items or points in + a list. + </dd> + + <dt id="capheight">Cap-height</dt> + <dd> + The height of the tallest capital letter in a given + <a href="#font">font</a> + at the current + <a href="#ps">point size</a>. + </dd> + + <dt id="descender">Descender</dt> + <dd> + The portion of a letter that extends beneath the + <a href="#baseline">baseline</a> + (j, q, y are letters with descenders). + </dd> + + <dt id="discretionaryhyphen">Discretionary hyphen</dt> + <dd> + A symbol inserted between two syllables of a word that indicates + to a typesetting program the valid hyphenation points in the + word. Normally, if hyphenation is turned on, groff knows where + to hyphenate words. However, hyphenation being what it is + (in English, at any rate), groff doesn’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 + + <span class="pre" style="margin-bottom: -2em;"> + \% (backslash followed by a percent) + </span> + </dd> + + <dt id="dropcap">Drop cap</dt> + <dd> + A large, usually upper-case letter that introduces the first + paragraph of a document or section thereof. The top of the + drop cap usually lines up with the top of the first line of the + paragraph, and typically “drops” several lines lower. + Text adjacent to the drop cap is indented to the right of the + letter until the bottom of the drop cap is reached, at which + point text reverts to the left margin. + </dd> + + <dt id="em">Em/en</dt> + <dd> + An em is a relative measurement equal to the width of the + letter M at a given + <a href="#ps">point size</a> + in a given + <a href="#font">font</a>. + Since most Ms are designed square, an em is usually (but + sometimes erroneously) considered to be the same size as the + current point size (i.e. if the point size of the type is 12, + one em equals 12 points). An en is equal to the width of a + letter N (historically 2/3 of an em, although groff treats an en + as 1/2 of an em). Typically, ems and ens are used to measure + indents, or to define the length of dashes (long hyphens). + </dd> + + <dt id="family">Family</dt> + <dd> + The collective name by which a collection of + <a href="#font">fonts</a> + are known, e.g. Helvetica, Times Roman, Garamond. + </dd> + + <dt id="figurespace">Figure space/Digit space</dt> + <dd> + A + <a href="#fixedwidthspace">fixed width space</a> + that has the width of one digit. Used for aligning numerals in, + say, columns or numbered lists. In groff, the figure space is + entered with + + <span class="pre" style="margin-bottom: -2em;"> + \0 (backslash followed by a zero) + </span> + </dd> + + <dt id="fixedwidthfont">Fixed width font</dt> + <dd> + A family or font in which every character occupies exactly the + same amount of vertical space on the line. Courier is the + best-known, if not the most elegant, fixed-width font. + </dd> + + <dt id="fixedwidthspace">Fixed width space</dt> + <dd> + Equal to + <a href="#wordspace">word space</a>, + but does not expand or contract when text is + <a href="#just">justified</a>. + In groff, fixed width space is entered with + + <span class="pre" style="margin-bottom: -2em;"> + \<space> (backslash followed by hitting the spacebar) + </span> + </dd> + + <dt id="font">Font</dt> + <dd> + The specific + <a href="#weight">weight</a> + and + <a href="#shape">shape</a> + of type within a + <a href="#family">family</a>, + e.g. light, medium, bold (which are weights), and roman, italic, + condensed (which are shapes). By default, groff knows of four + fonts within its default set of families: R (medium roman), I + (medium italic), B (bold roman) and BI (bold italic). + Mom considerably extends this very basic list. + </dd> + + <dt id="force">Force justify</dt> + <dd> + Sometimes, in + <a href="#just">justified</a> + text, a line needs to be broken short of the right margin. + Force justifying means telling a typesetting program (like + groff) that you want the line broken early AND that you want the + line’s word spacing stretched to force the line flush with the + right margin. + </dd> + + <dt id="gutter">Gutter</dt> + <dd> + The vertical whitespace separating columns of type. + </dd> + + <dt id="just">Justify/justification</dt> + <dd> + Lines of type are justified when they’re flush at both the left + and right margins. Justification is the act of making both + margins flush. Some people use the terms "left justified" and + "right justified" to mean type where only the left (or right) + margins align. I don’t. See + <a href="#quad">quad</a>. + </dd> + + <dt id="kern">Kerning</dt> + <dd> + Moving pairs of letters closer together to remove excess + whitespace between them. In the days before phototypesetting, + type was set from small, rectangular blocks of wood or metal, + each block having exactly one letter. Because the edge of + each block determined the edge of each letter, certain letter + combinations (TA, for example) didn’t fit together well and had + to be mortised by hand to bring them visually closer. Modern + typesetting systems usually take care of kerning automatically, + but they’re far from perfect. Professional typesetters still + devote a lot of time to fitting letters and punctuation together + properly. + </dd> + + <dt id="kernunit">Kern Units</dt> + <dd> + A relative distance equal to 1/36 of the current + <a href="#ps">point size</a>. + Used between individual letters + for + <a href="#kern">kerning</a>. + Different typesetting systems use different values (1/54 is + popular), and sometimes call kern units by a different name. + </dd> + + <dt id="leading">Lead/leading</dt> + <dd> + The distance from the + <a href="#baseline">baseline</a> + of one line of type to the line of type immediately beneath + it. Pronounced "ledding." Also called line spacing. Usually + measured in + <a href="#picaspoints">points</a>. + + <p> + <em>In case you’re interested...</em> In previous centuries, + lines of type were separated by thin strips of—you guessed + it—lead. Lines of type that had no lead between them were said + to be “set solid.” Once you began separating them with + strips of lead, they were said to be “leaded”, and the + spacing was expressed in terms of the number of + <a href="#picaspoints">points</a> + of lead. For this reason, “leading” and “line + spacing” aren’t, historically speaking, synonymous. + If type was set 10 on 12, for example, the leading was 2 + points, not 12. Nowadays, however, the two terms are used + interchangeably to mean the distance from baseline to baseline. + </p> + + </dd> + + <dt id="leader">Leaders</dt> + <dd> + Single characters used to fill lines, usually to their end. So + called because they “lead” the eye from one element + of the page to another. For example, in the following (brief) + Table of Contents, the periods (dots) are leaders. + + <span class="pre" style="margin-bottom: -2em;"> + Foreword............... 2 + Chapter 1.............. 5 + Chapter 2.............. 38 + Chapter 3.............. 60 + </span> + </dd> + + <dt id="ligatures">Ligature</dt> + <dd> + Ligatures are letters joined together to form a single + character. The commonest are fi, fl, ff, ffi and ffl. Others + are ae and oe. Occasionally, one sees an st ligature, but this + is archaic and quite rare. + </dd> + + <dt id="picaspoints">Picas/Points</dt> + <dd> + There are twelve points in a pica, and six picas in an inch + (hence 72 points to the inch). In the same way that gem-dealers + have always used their own system of measurement for weight + (carats), typographers have always used their own system of + measurement for type. + </dd> + + <dt id="ps">Point Size</dt> + <dd> + The nominal size of type, measured in + <a href="#picaspoints">points</a> + from the bottom of the longest + <a href="#descender">descender</a> + to the top of the highest + <a href="#ascender">ascender</a>. + In reality, type is always fractionally smaller than its point + size. + </dd> + + <dt id="quad">Quad</dt> + <dd> + When only one margin of type is flush, lines of type are quadded + in the direction of the flush margin. Therefore, quad left + means the left margin is flush, the right isn’t. Quad right + means the right margin is flush, the left isn’t. Quad centre + means neither the left nor the right margin is flush; rather, + lines of type are quadded on both sides so that type appears + centred on the page. + </dd> + + <dt id="rag">Rag</dt> + <dd> + Describes a margin that isn’t flush. Rag right means the right + margin isn’t flush. Rag left means the left margin isn’t flush. + The expression "flush left/rag right" is sometimes used to + describe type that is + <a href="#quad">quadded</a> + left. + </dd> + + <dt id="shape">Shape</dt> + <dd> + The degree of slant and/or the width of characters. + (Technically speaking, this is not a proper typesetting term; + however, it may help clarify some concepts presented in these + documents.) + + <p> + Some typical shapes are: + </p> + + <ul style="margin-top: -.5em; margin-bottom: -.5em"> + <li>“Roman”, which has no slant, and has letterforms of + average width</li> + <li>“Italic”, which is slanted, and has letterforms + of average width</li> + <li>“Condensed”, which has no slant, but has + letterforms narrower than the average represented by Roman</li> + <li>“Condensed Italic”, which is slanted, with letterforms narrower + than average</li> + </ul> + + <p> + The term + <a href="#font">font</a>, + as it is used in these documents, refers to a combination of + <a href="#weight">weight</a> + and shape. + </p> + + </dd> + + <dt id="solid">Solid/set solid</dt> + <dd> + When no + <a href="#leading">lead</a> + is added between lines of type (i.e. the + <a href="#ps">point size</a> + and linespacing are the same), the lines are said to be “set + solid.” + </dd> + + <dt id="trackkerning">Track kerning/Line kerning</dt> + <dd> + Sometimes, it’s advantageous to increase or decrease the amount + of space between every letter in a line by an equal (usually + small) amount, in order to fit more (or fewer) characters on the + line. The correct term is letter spacing, but track kerning and + line kerning (and sometimes, just "kerning") have come to mean + the same thing. + </dd> + + <dt id="unbreakablespace">Unbreakable space</dt> + <dd> + Equal to + <a href="#wordspace">word space</a>, + however words separated by an unbreakable space will always be + kept together on the same line. Expands and contracts like word + space. Useful for proper names, which one should, whenever + possible, avoid splitting onto two lines. In groff, unbreakable + space is entered with + + <span class="pre" style="margin-bottom: -2em;"> + \~ (backslash followed by a tilde) + </span> + </dd> + + <dt id="weight">Weight</dt> + <dd> + The thickness of the strokes of letterforms. Medium and Book + have average thicknesses and are the weights used for most + of the text in books, magazines, newspapers, etc. Light has + strokes slightly thinner than Medium or Book, but is still + acceptable for most text. Semibold, Bold, Heavy and Black all + have strokes of increasing thickness, making them suitable for + heads, subheads, headlines and the like. + </dd> + + <dt id="wordspace">Word space</dt> + <dd> + The amount of whitespace between words. When text is + <a href="#just">justified</a>, + word space expands or contracts to make the margins flush. + </dd> + + <dt id="xheight">x-height</dt> + <dd> + The height of a lower case letter x in a given font at a given + point size. Generally used to mean the average height of the + bowl of lower case letters. + </dd> +</dl> + +<h3 id="groff-terms" class="docs">Groff terms</h3> + +<dl> + <dt id="alias">Alias</dt> + <dd> + A + <a href="#macros">macro</a> + invoked by a name different from its “official” + name. For example, the official name of the macro to change + <a href="#family">family</a> + is <kbd>FAMILY</kbd>. Its alias is <kbd>FAM</kbd>. + Aliases may be created for any macro (via the + <a href="goodies.html#alias"><kbd>ALIAS</kbd></a> + macro) provided the alias uses a name not already taken by the + mom macros or one of the groff + <a href="#primitives">primitives</a>. + For a complete list of words or names you must not use, see the + <a href="reserved.html#reserved">list of reserved words</a>. + </dd> + + <dt id="arguments">Arguments</dt> + <dd> + Parameters or information needed by a + <a href="#macros">macro</a> + to do its job. For example, in the macro + + <span class="pre" style="margin-bottom: -2em;"> + .PT_SIZE 12 + </span> + + <kbd>12</kbd> is the argument. In the macro + + <span class="pre" style="margin-bottom: -2em;"> + .QUAD LEFT + </span> + + <kbd>LEFT</kbd> is the argument. Arguments are separated from + macros by spaces. Some macros require several arguments; each + is separated by a space. + </dd> + + <dt id="commentlines">Comment Lines</dt> + <dd> + <a href="#inputline">Input lines</a> + introduced with the comment character + + <span class="pre" style="margin-bottom: -2em;"> + \# (backslash followed by the pound sign) + </span> + + When processing output, groff silently ignores everything on a + line that begins with the comment character. + </dd> + + <dt id="controllines">Control Lines</dt> + <dd> + Instructions to groff that appear on a line by themselves, which + means that “control lines” are either + <a href="#macros">macros</a> + or groff + <a href="#primitives">primitives</a>. + Control lines begin with a period or, occasionally, an apostrophe. + </dd> + + <dt id="filled">Filled lines/fill mode</dt> + <dd> + Automatic + <a href="#just">justification</a> + or + <a href="#quad">quadding</a>. + In fill mode, the ends of lines as they appear in your text + editor are ignored. Instead, words from adjoining + <a href="#inputline">input lines</a> + are added one at a time to the output line until no more words + fit. Then, depending whether text is to be + <a href="#just">justified</a> + or + <a href="#quad">quadded</a> + (left, right, or centre), and depending on whether automatic + hyphenation is turned on, groff attempts to hyphenate the last + word, or, barring that, spreads and breaks the line (when + justification is turned on) or breaks and quads the line (when + quadding is turned on). + + <p> + Nofill mode (non-filled text) means that groff respects the ends + of lines exactly as they appear in your text editor. + </p> + + </dd> + + <dt id="inlines">Inline escapes</dt> + <dd> + Instructions issued to groff that appear as part of an + <a href="#inputline">input line</a> + (as opposed to + <a href="#macros">macros</a>, + which must appear on a line by themselves). Inline escapes are + always introduced by the backslash character. For example, + + <span class="pre" style="margin-bottom: -2em;"> + A line of text with the word T\*[BU 2]oronto in it + </span> + + contains the inline escape <kbd>\*[BU 2]</kbd> (which means + “move the letter ‘o’ 2 + <a href="#kernunit">kern units</a> + closer to the letter ‘T’”). + + <p style="margin-bottom: -2em;"> + Mom’s inline escapes always take the form + <kbd>\*[<ESCAPE>]</kbd>, where <kbd>ESCAPE</kbd> is + composed of capital letters, sometimes followed immediately by a + digit, sometimes followed by a space and a + <a href="#numericargument">numeric argument</a>. + 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 + + <span class="pre" style="margin-bottom: -2em;"> + \*[FP6] or \*[FWD 6p] + </span> + + while the groff escape for the same thing is + + <span class="pre" style="margin-bottom: -2em;"> + \h’6p’ + </span> + </p> + + </dd> + + <dt id="inputline" style="margin-top: -1em;">Input line</dt> + <dd> + A line of text as it appears in your text editor. + </dd> + + <dt id="macros">Macros</dt> + <dd> + Instructions embedded in a document that determine how groff + processes the text for output. mom’s macros + always begin with a period, on a line by themselves, and must + be typed in capital letters. Typically, macros contain complex + commands issued to groff—behind the scenes—via + groff + <a href="#primitives">primitives</a>. + </dd> + + <dt id="units">Machine units</dt> + <dd> + A machine unit is 1/1000 of a + <a href="#picaspoints">point</a> + when the groff device is ps. (“ps” means + “PostScript”—the default device for + which groff prepares output, and the device for which + mom was specifically designed.) + </dd> + + <dt id="numericargument">Numeric argument</dt> + <dd> + An + <a href="#arguments">argument</a> + that has the form of a digit. Numeric arguments can be built + out of arithmetic expressions using +, -, *, and / for plus, + minus, times, and divided-by respectively. If a numeric + argument requires a + <a href="#unitofmeasure">unit of measure</a>, + a unit of measure must be appended to <em>every</em> digit in + the argument. For example: + + <span class="pre" style="margin-bottom: -2em;"> + .ALD 1i-1v + </span> + + <div class="box-important" style="margin-right: 2.5em;"> + <p class="tip"> + <span class="important">IMPORTANT:</span> groff does not + respect the order of operations, but rather evaluates + arithmetic expressions from left to right. Parentheses must + be used to circumvent this peculiarity. Not to worry, though. + The likelihood of more than just the occasional plus or minus + sign when using mom’s macros is slim. + </p> + </div> + </dd> + + <dt id="outputline">Output line</dt> + <dd> + A line of text as it appears in output copy. + </dd> + + <dt id="primitives">Primitives</dt> + <dd> + The lowercase instructions, introduced with a period, that groff + uses as its native command language, and out of which macros + are built. The majority of groff’s primitive requests are two + letters long. + </dd> + + <dt id="stringargument">String Argument</dt> + <dd> + Technically, any + <a href="#arguments">argument</a> + that is not numeric. In this documentation, string argument + means an argument that requires the user to input text. For + example, in the + <a href="#macros">macro</a> + + <span class="pre" style="margin-bottom: -2em;"> + .TITLE "My Pulitzer Novel" + </span> + + <kbd>"My Pulitzer Novel"</kbd> is a string argument. + + <p> + Because string arguments must be enclosed by double-quotes, you + can’t use double-quotes as part of the string argument. If you + need double-quotes to be part of a string argument, use the + <a href="#inlines">inline escapes</a> + <kbd>\(lq</kbd> and <kbd>\(rq</kbd> (leftquote and + rightquote respectively) in place of the double-quote character + (<kbd>"</kbd>). + </p> + + </dd> + + <dt id="unitofmeasure">Unit of measure</dt> + <dd> + The single letter after a + <a href="#numericargument">numeric argument</a> + that tells mom what measurement scale the + argument should use. Common valid units are: + + <span class="pre" style="margin-bottom: -2em;"> + i (inches) + p (points) + P (Picas) + c (centimetres) + m (ems) + n (ens) + u (machine units) + v (the current leading [line space]) + </span> + + <p style="margin-top: -1em;"> + Units of measure must come immediately after the numeric + argument (i.e. with no space between the argument and the unit + of measure), like this: + + <span class="pre" style="margin-bottom: -2em;"> + .ALD 2v + .LL 39P + .IL 1i + </span> + + The above example advances 2 line spaces and sets the line + length to 39 picas with a left indent of 1 inch. + </p> + + <div class="box-important" style="margin-right: 2.5em;"> + <p class="tip"> + <span class="important">IMPORTANT:</span> + Most mom macros that set the size or measure of something must + be given a unit of measure since most of the macros do not have + default units of measure. There are a couple of exceptions, + the most notable of which are <kbd>PT_SIZE</kbd> and + <kbd class="bold">LS</kbd>. Both use + <a href="#picaspoints">points</a> + as the default unit of measure, which means you don’t have to + append “p” to their argument. + </p> + </div> + + <p> + You can enter decimal values for any unit of measure. Different + units may be combined by adding them together (e.g. 1.5i+2m, + which gives a measure of 1-1/2 inches plus 2 ems). + </p> + + <div class="box-tip" style="margin-right: 2.5em;"> + <p class="tip"> + <span class="note">Note:</span> + a pica is composed of 12 points, therefore 12.5 picas is 12 + picas and 6 points, not 12 picas and 5 points. If you want 12 + picas and 5 points, you have to enter the measure as 12P+5p. + </p> + </div> + + </dd> + + <dt id="zerowidthcharacter">Zero-width character</dt> + <dd> + The + <a href="#inlines">inline escape</a> + that allows you to print a literal period, apostrophe and, if + <a href="#outputline">output lines</a> + are + <a href="#filled">filled</a>, + a space that falls at the beginning of an + <a href="#inputline">input line</a>. + It looks like this: + + <span class="pre" style="margin-bottom: -2em;"> + \& (backslash followed by an ampersand) + </span> + + Normally, groff interprets a period (or an apostrophe) at the + beginning of an input line as meaning that what follows is a + <a href="#controllines">control line</a>. + In fill modes, groff treats a space at the beginning of an input + line as meaning “start a new line and put a space at the + beginning of it.” If you want groff to interpret periods + and apostrophes at the beginning of input lines literally (i.e. + print them), or spaces at the beginning of input lines as just + garden variety word spaces, you must start the line with the + zero-width character. + </dd> +</dl> + +<h3 id="mom-terms" class="docs">Mom terms</h3> +<dl> + <dt id="blockquote">Blockquote</dt> + <dd> + Cited material other than + <a href="#quote">quotes</a>. + Typically set at a smaller point size than paragraph text, + indented from the left and right margins. Blockquotes are + <a href="#filled">filled</a>. + </dd> + + <dt id="controlmacro">Control macro</dt> + <dd> + Macros used in + <a href="docprocessing.html#docprocessing">document processing</a> + to control/alter the appearance of document elements (e.g. + heads, quotes, footnotes, + <a href="#header">headers</a>, + etc.). + </dd> + + <dt id="docheader">Document header/docheader</dt> + <dd> + Document information (title, subtitle, author, etc) output at + the top of page one. + </dd> + + <dt id="epigraph">Epigraph</dt> + <dd> + A short, usually cited passage that appears at the beginning of + a chapter, story, or other document. + </dd> + + <dt id="footer">Footer/page footer</dt> + <dd> + Document information (frequently author and title) output in + the bottom margin of pages <em>after</em> page one. Not to be + confused with footnotes, which are considered part of + <a href="#running">running text</a>. + </dd> + + <dt id="head">Head</dt> + <dd> + A title that introduces a major section of a document. + </dd> + + <dt id="header">Header/page header</dt> + <dd> + Document information (frequently author and title) output in the + top margin of pages <em>after</em> page one. + + <div class="box-tip" style="margin-right: 2.5em;"> + <p class="tip"> + <span class="note">Note:</span> In terms of content and style, + headers and + <a href="#footer">footers</a> + are the same; they differ only in their placement on the page. + In most places in this documentation, references to the content + or style of headers applies equally to footers. + </p> + </div> + + </dd> + + <dt id="linebreak">Linebreak/author linebreak</dt> + <dd> + A gap in the vertical flow of + <a href="#running">running text</a>, + frequently set off by typographic symbols such as asterisks or + daggers. Used to indicate a shift in the content of a document + (e.g. a scene change in a short story). Also commonly called a + scene break or a section break. + </dd> + + <dt id="parahead">Paragraph head</dt> + <dd> + A title joined to the body of a paragraph; hierarchically one + level beneath + <a href="#subhead">subheads</a>. + </dd> + + <dt id="quote">Quote</dt> + <dd> + A quote, to mom, is a line-for-line setting + of quoted material (e.g. poetry, song lyrics, or a snippet of + programming code). You don’t have to use + <a href="typesetting.html#br"><kbd>BR</kbd></a> + with quotes. + </dd> + + <dt id="running">Running text</dt> + <dd> + In a document formatted with mom, running + text means text that forms the body of the document, including + elements such as heads and subheads. + <a href="#docheader">Docheaders</a>, + <a href="#header">headers</a>, + <a href="#footer">footers</a> + and page numbers are not part of running text. + </dd> + + <dt id="subhead">Subhead</dt> + <dd> + A title used to introduce secondary sections of a document; + hierarchically one level beneath sections introduced by + <a href="#head">heads</a>. + </dd> + + <dt id="toggle">Toggle</dt> + <dd> + A macro or tag that, when invoked without an argument, begins + something or turns a feature on, and, when invoked with ANY + argument, ends something or turns a feature off. See + <a href="intro.html#toggle-example">Example 3</a> + of the section + <a href="intro.html#macro-args">How to read macro arguments</a>. + </dd> +</dl> + +<div class="rule-long"><hr/></div> + +<!-- Navigation links --> +<table style="width: 100%;"> + <tr> + <td style="width: 33%;"><a href="toc.html">Back to Table of Contents</a></td> + <td style="width: 33%; text-align: center;"><a href="#top">Top</a></td> + <td style="width: 33%; text-align: right;"><a href="using.html#top">Next: Using mom</a></td> +</tr> +</table> + +</div> + +<div class="bottom-spacer"><br/></div> + +</body> +</html> +<!-- vim: fileencoding=utf-8: nomodified:--> 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 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- +This file is part of groff, the GNU roff type-setting system. + +Copyright (C) 2004, 2005, 2006, 2009, 2010 Free Software Foundation, Inc. +Written by Peter Schaffter. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with the +Invariant Sections being this comment section, with no Front-Cover +Texts, and with no Back-Cover Texts. + +A copy of the Free Documentation License is included as a file called +FDL in the main directory of the groff source package. +--> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"> + +<head> + <meta http-equiv="content-type" content="text/html;charset=utf-8"/> + <title>Mom -- Document processing, element tags</title> + <link rel="stylesheet" type="text/css" href="stylesheet.css" /> +</head> + +<body style="background-color: #f5faff;"> + +<!-- ==================================================================== --> + +<div id="top" class="page"> + +<!-- Navigation links --> +<table style="width: 100%;"> +<tr> + <td><a href="toc.html">Back to Table of Contents</a></td> + <td style="text-align: right;"><a href="images.html#top">Next: Inserting images</a></td> +</tr> +</table> + +<h1 class="docs">The document element tags</h1> + +<div style="width: 386px; margin: auto;"> +<ul class="no-enumerator"> + <li><a href="#docelement-intro">Introduction to the document element tags</a></li> + <li><a href="#docelement-control">Control macros – changing the tag defaults</a> + <ul style="margin-left: -.5em; list-style-type: disc;"> + <li><a href="#control-macro-args">Arguments to the control macros</a> + <ul style="margin-left: -.5em; list-style-type: circle;"> + <li><a href="#family-and-font">family and font</a></li> + <li><a href="#point-size">point size</a></li> + <li><a href="#color">colour</a></li> + <li><a href="#quad">quad/justification</a></li> + <li><a href="#underline">underline style, rule weight</a></li> + </ul></li> + </ul></li> +</ul> +</div> + +<div class="rule-medium"><hr/></div> + +<h2 id="toc-doc-element" class="docs" style="text-align: center;">Document element tags table of contents</h2> + +<div id="docelement-mini-toc" style="font-size: 100%; line-height: 150%; margin-top: .5em;"> +<div class="mini-toc-col-1" style="margin-left: 0;"> +<h3 class="toc toc-docproc-header" style="margin-top: 1em;"><a class="header-link" href="#epigraph-intro">Epigraphs</a></h3> +<ul class="toc-docproc" style="margin-top: .5em;"> + <li><a href="#epigraph">EPIGRAPH</a></li> + <li><a href="#epigraph-control">Epigraph control</a></li> +</ul> +<h3 class="toc toc-docproc-header"><a class="header-link" href="#pp-intro">Paragraphs</a></h3> +<ul class="toc-docproc" style="margin-top: .5em;"> + <li><a href="#pp">PP</a></li> + <li><a href="#pp-control">Paragraph control</a></li> +</ul> +<h3 class="toc toc-docproc-header"><a class="header-link" href="#head-intro">Main heads</a></h3> +<ul class="toc-docproc" style="margin-top: .5em;"> + <li><a href="#head">HEAD</a></li> + <li><a href="#head-control">Head control</a></li> +</ul> +<h3 class="toc toc-docproc-header"><a class="header-link" href="#subhead-intro">Subheads</a></h3> +<ul class="toc-docproc" style="margin-top: .5em;"> + <li><a href="#subhead">SUBHEAD</a></li> + <li><a href="#subhead-control">Subhead control</a></li> +</ul> +<h3 class="toc toc-docproc-header"><a class="header-link" href="#parahead-intro">Paragraph heads</a></h3> +<ul class="toc-docproc" style="margin-top: .5em;"> + <li><a href="#parahead">PARAHEAD</a></li> + <li><a href="#parahead-control">Parahead control</a></li> +</ul> +<h3 class="toc toc-docproc-header"><a class="header-link" href="#linebreak-intro">Linebreaks (section breaks)</a></h3> +<ul class="toc-docproc" style="margin-top: .5em;"> + <li><a href="#linebreak">LINEBREAK</a></li> + <li><a href="#linebreak-control">Linebreak control</a></li> +</ul> +<h3 class="toc toc-docproc-header"><a class="header-link" href="#quote-intro">Quotes (line for line; poetry or code)</a></h3> +<ul class="toc-docproc" style="margin-top: .5em;"> + <li><a href="#quote">QUOTE</a></li> + <li><a href="#quote-control">Quote control</a></li> +</ul> +<h3 class="toc toc-docproc-header"><a class="header-link" href="#blockquote-intro">Blockquotes (cited material)</a></h3> +<ul class="toc-docproc" style="margin-top: .5em;"> + <li><a href="#blockquote">BLOCKQUOTE</a></li> + <li><a href="#blockquote-control">Blockquote control</a></li> +</ul> +</div> +<div class="mini-toc-col-2" style="margin-top: 1.5em;"> +<h3 class="toc toc-docproc-header"><a class="header-link" href="#code-intro">Inserting code snippets</a></h3> +<ul class="toc-docproc" style="margin-top: .5em;"> + <li><a href="#code">CODE</a></li> + <li><a href="#code-control">Code control</a></li> +</ul> +<h3 class="toc toc-docproc-header"><a class="header-link" href="#list-intro">Nested lists</a></h3> +<ul class="toc-docproc" style="margin-top: .5em;"> + <li><a href="#list">LIST</a></li> + <li><a href="#item">ITEM</a></li> + <li><a href="#list-control">List control</a></li> +</ul> +<h3 class="toc toc-docproc-header"><a class="header-link" href="#number-lines-intro">Line numbering</a></h3> +<ul class="toc-docproc" style="margin-top: .5em;"> + <li><a href="#number-lines">NUMBER_LINES</a></li> + <li><a href="#number-lines-control">Line numbering control</a></li> +</ul> +<h3 class="toc toc-docproc-header"><a class="header-link" href="#footnote-intro">Footnotes</a></h3> +<ul class="toc-docproc" style="margin-top: .5em;"> + <li><a href="#footnote">FOOTNOTE</a></li> + <li><a href="#footnote-control">Footnote control</a></li> +</ul> +<h3 class="toc toc-docproc-header"><a class="header-link" href="#endnote-intro">Endnotes</a></h3> +<ul class="toc-docproc" style="margin-top: .5em;"> + <li><a href="#endnote">ENDNOTE</a></li> + <li><a href="#endnote-control">Endnote control</a></li> +</ul> +<h3 class="toc toc-docproc-header"><a class="header-link" href="#margin-notes-intro">Margin notes</a></h3> +<ul class="toc-docproc" style="margin-top: .5em;"> + <li><a href="#mn-init">MN_INIT</a></li> + <li><a href="#mn">MN</a></li> + <li><a href="#margin-notes-control">Margin notes control</a></li> +</ul> +<h3 class="toc toc-docproc-header"><a class="header-link" href="#finis-intro">Document termination string</a></h3> +<ul class="toc-docproc" style="margin-top: .5em;"> + <li><a href="#finis">FINIS</a></li> + <li><a href="#finis-control">Finis control</a></li> +</ul> +</div> +</div> + +<div class="rule-medium" style="clear: both;"><hr/></div> + +<h2 id="docelement-intro" class="docs">Introduction to the document element tags</h2> + +<p> +Once you’ve completed the setup for a document (see +<a href="docprocessing.html#docprocessing-tut">Setting up a mom document</a>), +formatting it is a snap. Simply invoke the appropriate tag for +each document element as you need it. The tags are macros that +tell mom: “This is a paragraph; this is a subhead; this is a +footnote,” and so on. +</p> + +<p> +The list of tags is actually quite small—ideal for the users +mom brought herself into being for (see +<a href="intro.html#intro-intro">Who mom is meant for</a>). +However, the list of macros that control the appearance of the tags +upon output is extensive. Generally, for each tag, there are +<a href="definitions.html#controlmacro">control macros</a> +for the tag’s family, font and point size. Where appropriate, +there are macros to control leading, indents, quad and special +features as well. +</p> + +<p> +Mom has tasteful defaults for all the tags, hence you only use the +control macros when you want to change the way she does things. +This is usually done prior to +<a href="docprocessing.html#start">START</a>, +but can, in fact, be done at any time in the course of a document. +Any change to a tag’s style affects all subsequent invocations +of the tag. +</p> + +<h2 id="docelement-control" class="docs">Control macros – changing the tag defaults</h2> + +<p> +The control macros for document processing tags let you design the +look of all the parts of your documents—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. +</p> + +<p> +In addition, many tags have special macros to control features that +are pertinent to those tags alone. Have a look at the section +dealing with any particular tag to find out what macros control the +tag, and what mom’s defaults for the tag are. +</p> + +<p> +The control macros may be used at any time during the course of a +document (i.e. before or after +<a href="docprocessing.html#start">START</a>). +The changes you make alter all subsequent invocations of the +affected tag until you make another change, either by passing new +arguments to the tag’s control macro, or toggling a particular +feature of the tag on or off. +</p> + +<p> +And don’t forget: the +<a href="typesetting.html#macros-typesetting">typesetting macros</a> +can be used at any time, including inside +<a href="definitions.html#toggle">toggle</a> +tags (affecting only that particular invocation of the tag). +Equally, +<a href="definitions.html#inlines">inline escapes</a> +can be used in tags that take +<a href="definitions.html#stringargument">string arguments.</a> +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="tip">Tip:</span> +Get familiar with mom at her default settings before exploring the +control macros. Put her through her paces. See how she behaves. +Get to know what she feels like and how she looks, both in your +text editor and on the printed page. Then, if you don’t like +something, use this documentation to find the precise macro you need +to change it. There are tons of control macros. Reading up on them +and trying to remember them all might lead you to think that mom is +complex and unwieldy, which is not only untrue, but would offend her +mightily. +</p> +</div> + +<div class="box-important"> +<p class="tip-top"> +<span class="important">Important:</span> +The family, font, point size, colour and leading control macros have +no effect in +<a href="docprocessing.html#printstyle">PRINTSTYLE <kbd>TYPEWRITE</kbd></a>, +which sets everyTHING in Courier roman, 12/24 (i.e. 12-point type on +a linespace of 24 points). +</p> + +<p class="tip-bottom"> +Please also note that the defaults listed with the control macros +apply only to +<a href="docprocessing.html#printstyle">PRINTSTYLE <kbd>TYPESET</kbd></a> +unless a default for <kbd>TYPEWRITE</kbd> is also given. +</p> +</div> + +<h3 id="control-macro-args" class="docs">Arguments to the control macros</h3> + +<h4 id="family-and-font" class="docs" style="margin-top: 1em; margin-bottom: -.75em;">Family and font</h4> + +<p> +The arguments to the control macros that end in _FAMILY or _FONT are +the same as for +<a href="typesetting.html#family">FAMILY</a> +and +<a href="typesetting.html#font">FT</a>. +</p> + +<h4 id="point-size" class="docs" style="margin-top: -.5em; margin-bottom: -.75em;">Point size</h4> + +<p> +Control macros that end in _SIZE always take +the form <kbd>+<n></kbd> or <kbd>-<n></kbd> where +<n> is the number of +<a href="definitions.html#picaspoints">points</a> +larger (+) or smaller (-) than the point size of paragraphs +you want the document element to be. For example, to change +subheads to 1-1/2 points larger than the type in paragraphs, do +<br/> +<span class="pre-in-pp"> + .SUBHEAD_SIZE +1.5 +</span> +There’s no need for a +<a href="definitions.html#unitofmeasure">unit of measure</a> +with the _SIZE control macros; points is assumed. +</p> + +<h4 id="color" class="docs" style="margin-top: -.5em; margin-bottom: -.75em;">Colour</h4> + +<p> +Control macros that end in _COLOR take as their argument a colour +name pre-defined (or “initialized”) with +<a href="color.html#newcolor">NEWCOLOR</a> +or +<a href="color.html#xcolor">XCOLOR</a>. +For example, if you want your heads to be red, once you’ve defined +or initialized the color, red, +<br/> +<span class="pre-in-pp"> + .HEAD_COLOR red +</span> +will turn your heads red. +</p> + +<h4 id="lead" class="docs" style="margin-top: -.5em; margin-bottom: -.75em;">Lead/linespacing</h4> + +<p> +Control macros that end in _AUTOLEAD take the same argument as +<a href="typesetting.html#autolead">AUTOLEAD</a>, +<i>viz.</i> a digit that represents the number of points to add to +the tag’s point size to arrive at its +<a href="definitions.html#leading">leading</a>. +For example, to set footnotes +<a href="definitions.html#solid">solid</a>, do +<br/> +<span class="pre-in-pp"> + .FOOTNOTE_AUTOLEAD 0 +</span> +To set footnotes with a 1-point lead (i.e. with the line spacing +one point greater than the footnote’s point size), do +<br/> +<span class="pre-in-pp"> + .FOOTNOTE_AUTOLEAD 1 +</span> +</p> + +<div class="box-tip" style="margin-top: -1.25em;"> +<p class="tip"> +<span class="note">Note:</span> +_AUTOLEAD control macros do not have a <kbd>FACTOR</kbd> argument. +</p> +</div> + + +<h4 id="control-indents" class="docs" style="margin-top: -.75em; margin-bottom: -.75em;">Indents</h4> + +<p> +Except for +<a href="#para-indent">PARA_INDENT</a>, +the argument to control macros that end in _INDENT can take +either a single numeral (whole numbers only, no decimal fractions) +<i>without</i> a +<a href="definitions.html#unitofmeasure">unit of measure</a> +appended to it, or a digit (including decimal fractions) <i>with</i> +a unit of measure appended. +</p> + +<p> +A digit <i>without</i> a unit of measure appended represents by +how much you want your paragraph first-line indents (set with +PARA_INDENT) multiplied to achieve the correct indent for a +particular tag. For example, +<br/> +<span class="pre-in-pp"> + .PARA_INDENT 2m + .BLOCKQUOTE_INDENT 2 +</span> +means that blockquotes will be indented from the left margin by +twice the size of the paragraph indent, or 4 +<a href="definitions.html#em">ems</a>. +</p> + +<p> +A digit <i>with</i> a unit of measure appended defines an absolute +indent, relative to nothing. In the following, blockquotes will be +indented by 3 +<a href="definitions.html#picaspoints">picas</a> +and 6 +<a href="definitions.html#picaspoints">points</a>, +regardless of the paragraph indent. +<br/> +<span class="pre-in-pp"> + .PARA_INDENT 2m + .BLOCKQUOTE_INDENT 3P+6p +</span> +</p> + +<h4 id="quad" class="docs" style="margin-top: -1em; margin-bottom: -.75em;">Quad/justification style</h4> + +<p> +Control macros that end in _QUAD take the same arguments as +<a href="typesetting.html#quad">QUAD</a>. +</p> + +<h4 id="underline" class="docs" style="margin-bottom: -.75em;">Underline style, rule weight</h4> + +<p> +If mom gives the option to underline a document element, the weight +of the underline and its distance from the +<a href="definitions.html#baseline">baseline</a> +are controlled by macros that end in _UNDERLINE. +</p> + +<p> +Page elements that are separated from +<a href="definitions.html#running">running text</a> +by a rule (i.e. page headers, page footers and footnotes) are +controlled by macros that end in _RULE_WEIGHT. +</p> + +<p> +The weight argument to _UNDERLINE macros is the same as the argument +to +<a href="inlines.html#rule-weight">RULE_WEIGHT</a>, +as is the argument to _RULE_WEIGHT macros. +</p> + +<div class="rule-short"><hr/></div> + +<!-- ==================================================================== --> + +<h2 id="epigraph-intro" class="macro-group">Epigraphs</h2> + +<ul style="margin-left: -.5em;"> + <li><a href="#epigraph">Tag: EPIGRAPH</a></li> + <li><a href="#epigraph-control">Epigraph control macros and defaults</a></li> +</ul> + +<p> +<a href="definitions.html#epigraph">Epigraphs</a> +colour, flavour, or comment on the document they precede. +Typically, they are centred at the top of a document’s first page +(underneath the title) and set in a smaller point size than that of +paragraph text. +</p> + +<p> +By default, mom sets epigraphs centred and +<a href="definitions.html#filled">unfilled</a>; +this lets you input them on a line for line basis. This behaviour +can be changed to accomodate +<a href="definitions.html#filled">filled</a> +epigraph “blocks.” +</p> + +<!-- -EPIGRAPH- --> + +<div class="macro-id-overline"> +<h3 id="epigraph" class="macro-id">EPIGRAPH</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>EPIGRAPH</b> <kbd class="macro-args"><toggle> | [ BLOCK ]</kbd> +</div> + +<p> +EPIGRAPH is a toggle, used like this: +<br/> +<span class="pre-in-pp"> + .EPIGRAPH + <text of epigraph> + .EPIGRAPH OFF +</span> +<kbd>OFF</kbd>, above, could be anything—say, <kbd>Q</kbd> or +<kbd>X</kbd>—since any argument other than <kbd>BLOCK</kbd> +turns it off. +</p> + +<p> +If given the argument, <kbd>BLOCK</kbd>, EPIGRAPH sets epigraphs +<a href="definitions.html#filled">filled</a>, +justified or quadded in the same direction as paragraphs, indented +equally from both the left and right margins. +</p> + +<p> +If a block-style epigraph runs to more than one paragraph (unlikely, +but conceivable), you <i>must</i> introduce every +paragraph—including the first—with the +<a href="#pp">PP</a> +tag. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +EPIGRAPH should only be used at the top of a document (i.e. just +after +<a href="docprocessing.html#start">START</a>) +or after +<a href="#head-intro">heads</a>. +The latter is not especially recommended, but it does work. In all +other places where you want quotes or cited text, use +<a href="#quote">QUOTE</a> +or +<a href="#blockquote">BLOCKQUOTE</a>. +</p> +</div> + +<div class="defaults-container" style="padding-bottom: 8px;"> +<h3 id="epigraph-control" class="docs defaults" style="margin-top: -.25em;">EPIGRAPH control macros and defaults</h3> + +<p class="defaults"> +See +<a href="#control-macro-args">Arguments to the control macros</a>. +</p> + +<span class="pre defaults"> +.EPIGRAPH_FAMILY default = prevailing document family; default is Times Roman +.EPIGRAPH_FONT default = roman +.EPIGRAPH_SIZE default = -1.5 (points) +.EPIGRAPH_COLOR default = black +.EPIGRAPH_AUTOLEAD default = 2 points + +(The next two apply to “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. +</span> +</div> + +<div class="box-notes"> +<h3 id="epigraph-indent" class="docs notes" style="margin-bottom: -.75em;">Note on EPIGRAPH_INDENT</h3> + +<p style="margin-top: .5em;"> +Prior to version 1.4-b, mom allowed only the passing of an integer +to the macro, EPIGRAPH_INDENT. The integer represented the amount +by which to multiply the argument passed to +<a href="#para-indent">PARA_INDENT</a> +to arrive at an indent for block style epigraphs. +</p> + +<p> +As of version 1.4-b, you can now append a +<a href="definitions.html#unitofmeasure">unit of measure</a> +to the argument passed to EPIGRAPH_INDENT, thus setting an absolute +indent, relative to nothing. The old behaviour is still respected, +though; in other words, if you pass EPIGRAPH_INDENT an integer with +no unit of measure appended, the integer represents the amount by +which to multiply PARA_INDENT to arrive at an indent for block style +epigraphs. +</p> + +<p> +Please also note that if your PARA_INDENT is <kbd>0</kbd> (i.e. no +indenting of the first line of paragraphs), you <i>must</i> set an +EPIGRAPH_INDENT yourself, with a unit of measure appended to the +argument. Mom has no default for EPIGRAPH_INDENT if paragraph first +lines are not being indented. +</p> + +<p class="tip-bottom"> +The default value for EPIGRAPH_INDENT is <kbd>3</kbd> (for +<a href="docprocessing.html#printstyle">PRINTSTYLE TYPESET</a>) +and <kbd>2</kbd> (for +<a href="docprocessing.html#printstyle">PRINTSTYLE TYPEWRITE</a>). +</p> +</div> + +<div class="rule-short"><hr/></div> + +<!-- ==================================================================== --> + +<h2 id="pp-intro" class="macro-group">Paragraphs</h2> + +<ul style="margin-left: -.5em;"> + <li><a href="#pp">Tag: PP</a></li> + <li><a href="#pp-control">Paragraph control macros and defaults</a></li> +</ul> + +<p> +The paragraph macro is the one you use most often. Consequently, +it’s one of most powerful, yet simplest to use—just the +letters PP. No arguments, nothing. Just <kbd>.PP</kbd> on a line +by itself any time, in any document element, tells mom you want to +start a new paragraph. The spacing and indent appropriate to where +you are in your document are taken care of automatically. +</p> + +<p> +By default, mom does not indent the first paragraph of a document, +nor paragraphs that fall immediately after +<a href="#head-intro">heads</a> +or +<a href="#subhead-intro">subheads</a>. +The first paragraphs of blockquotes and block-style epigraphs are +also not indented. This behaviour can be changed with the control +macro +<kbd><a href="#para-indent-first">INDENT_FIRST_PARAS</a></kbd>. +</p> + +<p> +In contrast to some other macro sets, mom does not deposit a blank +line between paragraphs. If you want her to do so, use the control +macro PARA_SPACE. (I don’t recommend using this macro with +<a href="typesetting.html#printstyle">PRINTSTYLE TYPEWRITE</a>.) +</p> + +<p> +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. +</p> + +<div class="box-tip"> +<p class="tip-top"> +<span class="tip">Tip:</span> +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 <kbd>.PP</kbd>’s. The visual +interruption in the flow of text is a serious obstacle to creativity +and critiquing. +</p> + +<p> +I use the tab key on my keyboard to indent paragraphs by four spaces +when I'm writing, producing a text file that looks pretty much like +what you see on a printed page. When it comes time to format and +print the file, I run it through a sed script that (amongst other +things) converts the intial four spaces into <kbd>.PP</kbd> (plus a +new line) and pipes the output to groff for processing and printing. +</p> + +<p class="tip-bottom"> +Another solution would be to insert a blank line between paragraphs +of your text files. The blank lines can then be sedded out at +print time, as above (<kbd>.PP</kbd> plus a newline), or, more +conveniently, you could use the <kbd>.blm</kbd> +<a href="definitions.html#primitives">primitive</a> +(blank line macro) to tell groff (and mom) that blank lines should +be interpreted as PP’s. +<br/> +<span class="pre-in-pp"> + .blm PP +</span> +tells groff that blank lines are really the macro PP. +</p> +</div> + +<!-- -PP- --> + +<div class="macro-id-overline"> +<h3 id="pp" class="macro-id">PP</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>PP</b> +</div> +<p> +<kbd>.PP</kbd> (on a line by itself, of course) tells mom to start a +new paragraph. See +<a href="#pp-intro">above</a> +for more details. In addition to regular text paragraphs, you can +use PP in +<a href="#epigraph-intro">epigraphs</a>, +<a href="#blockquote-intro">blockquotes</a> +and +<a href="#footnote-intro">footnotes</a>. +</p> + +<div class="defaults-container" style="background-color: #ded4bd; border: none;"> +<h3 id="pp-control" class="docs defaults">PP control macros and defaults</h3> + +<p class="defaults"> +The PP macro being so important, and representing, as it were, the +basis of everything that goes on in a document, its control is +managed in a manner somewhat different from other document element +tags. +</p> +<ol style="margin-top: .5em; padding-bottom: .5em;"> + <li><a href="#pp-family">Family control</a></li> + <li><a href="#pp-font">Font control</a></li> + <li><a href="#pp-color">Paragraph colour</a></li> + <li><a href="#pp-leading">Leading/linespacing control</a></li> + <li><a href="#pp-just-quad">Justification/quad control</a></li> + <li><a href="#para-indent">First-line indent control</a></li> + <li><a href="#para-indent-first">Initial paragraphs indent control</a></li> + <li><a href="#pp-space">Paragraph spacing control</a></li> +</ol> +</div> + +<h4 id="pp-family" class="docs" style="margin-top: -1.5em;">1. Family control</h4> + +<p> +The paragraph +<a href="definitions.html#family">family</a> +is set with +<a href="typesetting.html#family">FAMILY</a> +prior to +<a href="docprocessing.html#start">START</a>, +or +<a href="docprocessing.html#doc-family">DOC_FAMILY</a> +afterwards. Please note that both globally affect the family of +every element in the document. +</p> + +<p> +If you wish to change the family for regular text paragraphs only, +invoke <kbd>.FAMILY</kbd> immediately after <kbd>.PP</kbd> in every +paragraph whose family you wish to differ from the prevailing +document family. +</p> + +<p> +Mom’s default paragraph (and document) family is Times Roman. +</p> + +<h4 id="pp-font" class="docs" style="margin-top: -.25em;">2. Font control</h4> + +<p> +To change the +<a href="definitions.html#font">font</a> +used in regular text paragraphs, use PP_FONT, which takes the same +argument as +<a href="typesetting.html#font">FT</a>. +PP_FONT may be used before or after +<a href="docprocessing.html#start">START</a>. +Only regular text paragraphs are affected; paragraphs in +<a href="#epigraph-intro">epigraphs</a>, +<a href="#blockquote-intro">blockquotes</a> +and +<a href="#footnote-intro">footnotes</a> +remain at their default setting (medium roman) unless you change +them with the appropriate control macros. +</p> + +<p> +Mom’s default paragraph font is medium roman. +</p> + +<h4 id="pp-color" class="docs" style="margin-top: -.25em;">3. Paragraph colour</h4> + +<p> +Mom has no special control macro for colourizing paragraphs. If you +wish a colourized paragraph, you must use the macro, +<a href="color.html#color">COLOR</a>, +or the +<a href="definitions.html#inline">inline escape</a>, +<a href="color.html#color-inline"><kbd>\*[<colorname>]</kbd></a>, +<i>after</i> <kbd>.PP</kbd>. The colour must be one pre-defined (or +“initialized”) with +<a href="color.html#newcolor">NEWCOLOR</a> +or +<a href="color.html#xcolor">XCOLOR</a>. +</p> + +<p> +Please note that unless you change the colour back to it’s +default (usually black) at the end of the paragraph, all subsequent +paragraphs will be set in the new colour, although most other +elements of your document will continue to be set in the default +colour (usually black). +</p> + +<p> +For example, assuming you have defined the colour, blue, +<br/> +<span class="pre-in-pp"> + .PP + .COLOR blue + <first paragraph> + .HEAD "Monty Python" + .SUBHEAD "The Origins of Spam" + .PP + <second paragraph> +</span> +the first paragraph will be blue, the head and subhead will be in +the document’s default colour (usually black), and the second +paragraph will be in blue. +</p> + +<p> +The one document element that is affected by changing the colour of +paragraphs is +<a href="#parahead">paraheads</a>, +since paraheads are attached directly to the body of paragraphs. +In other words, if you change the colour of a paragraph and do not +reset the paragraph colour back to its default, subsequent paraheads +will appear in the same colour as your paragraphs unless you have +explicitly told mom you want a pre-defined (or +“initialized”) color (usually black) for your paraheads. +</p> + +<p> +See the footnote to +<a href="#parahead-color">PARAHEAD_COLOR</a>. +</p> + +<h4 id="pp-leading" class="docs" style="margin-top: -.25em;">4. Leading</h4> + +<p> +The paragraph +<a href="definitions.html#leading">leading</a> +is set with +<a href="typesetting.html#leading">LS</a> +prior to +<a href="docprocessing.html#start">START</a>, +or +<a href="docprocessing.html#doc-lead">DOC_LEAD</a> +afterwards. Please note that either method globally affects the +leading and spacing of every document element (except +<a href="definitions.html#header">headers</a> +and +<a href="definitions.html#footer">footers</a>). +</p> + +<p> +If you wish to change the leading of regular text paragraphs only, +invoke <kbd>.LS</kbd> immediately after <kbd>.PP</kbd> in every +paragraph whose leading you wish to change. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Warning:</span> +It is extremely unwise to change a paragraph's leading with LS as +it will, in all cases, screw up mom’s ability to balance +the bottom margin of pages. Should you absolutely need to change +paragraph leading with LS, and subsequently want mom to get back on +the right leading track, use the +<a href="docprocessing.html#shim">SHIM</a> +macro. +</p> +</div> + +<p> +Mom’s default paragraph leading (document leading) +is 16 points, adjusted to fill the page. +</p> + +<h4 id="pp-just-quad" class="docs" style="margin-top: -.25em;">5. Justification/quad</h4> + +<p> +The justification/quad-direction of regular text paragraphs (i.e. +<a href="definitions.html#just">justified</a>, +or +<a href="definitions.html#filled">filled</a> +and +<a href="definitions.html#quad">quadded</a> +left/right/centre) is set with +<a href="typesetting.html#justify">JUSTIFY</a> +or +<a href="typesetting.html#quad">QUAD</a> +prior to +<a href="docprocessing.html#start">START</a>, +and with +<a href="docprocessing.html#doc-quad">DOC_QUAD</a> +afterwards. +</p> + +<p> +Please note that either method of setting the paragraph +justification/quad-direction also affects +<a href="#epigraph-intro">epigraphs</a> +and +<a href="#footnote-intro">footnotes</a>, +but not +<a href="#blockquote-intro">blockquotes</a> +(whose default is quad left unless you change it with +<a href="#blockquote">BLOCKQUOTE_QUAD</a>). +The justification/quad-direction of epigraphs and footnotes may be +changed with their own control macros. +</p> + +<p> +If you wish to change the justification/quad-direction of individual +paragraphs, invoke +<a href="typesetting.html#justify"><kbd>.JUSTIFY</kbd></a> +or +<a href="typesetting.html#quad"><kbd>.QUAD</kbd></a> +on the line immediately after <kbd>.PP</kbd>. Only the paragraph +in question gets justified or quadded differently; subsequent +paragraphs remain unaffected. +</p> + +<p> +Mom’s default justification/quad-direction for paragraphs +when the +<a href="docprocessing.html#printstyle">PRINTSTYLE</a> +is <kbd>TYPESET</kbd> is justified; for PRINTSTYLE +<kbd>TYPEWRITE</kbd>, the default is quad left. +</p> + +<h4 id="para-indent" class="docs" style="margin-top: -.25em;">6. First-line indent</h4> + +<p> +The first-line indent of paragraphs is controlled by PARA_INDENT, +which takes one argument: the size of the indent. PARA_INDENT may be +used before or after +<a href="docprocessing.html#start">START</a>. +A +<a href="definitions.html#unitofmeasure">unit of measure</a> +is required; fractional sizes are allowed. Thus, to set the +paragraph indent to 4-1/2 +<a href="definitions.html#em">ems</a>, do +<br/> +<span class="pre-in-pp"> + .PARA_INDENT 4.5m +</span> +In addition to establishing the basic first line-indent of +paragraphs, PARA_INDENT also affects +<a href="#epigraph-intro">epigraphs</a>, +<a href="#quote-intro">quotes</a> +and +<a href="#blockquote-intro">blockquotes</a>, +whose overall indenting from the left and (where applicable) +right margins is relative to PARA_INDENT if +the _INDENT control macro for these tags has +no +<a href="definitions.html#unitofmeasure">unit of measure</a> +appended to it. Furthermore, the first-line indent of paragraphs +within these document elements (as well as footnotes) is also +relative to PARA_INDENT (always 1/2 of PARA_INDENT), hence they are +also affected. +</p> + +<p> +Mom’s default PARA_INDENT is 2 ems for +<a href="docprocessing.html#printstyle">PRINTSTYLE</a> +<kbd>TYPESET</kbd> and 3 picas (1/2 inch) for +<a href="docprocessing.html#printstyle">PRINTSTYLE</a> +<kbd>TYPEWRITE</kbd>. +</p> + +<h4 id="para-indent-first" class="docs" style="margin-top: -.25em;">7. Indenting initial paragraphs</h4> + +<p> +By default, mom does not indent the first paragraph of a document, +nor the first paragraph after a head or subhead, nor the first +paragraphs of +<a href="#epigraph-intro">epigraphs</a>, +<a href="#blockquote-intro">blockquotes</a> +or +<a href="#footnote-intro">footnotes</a> +that run to more than one paragraph. +</p> + +<p> +If you wish to have first paragraphs indented, invoke the macro +<kbd>.INDENT_FIRST_PARAS</kbd> without an argument, either before or +after +<a href="docprocessing.html#start">START</a>. +INDENT_FIRST_PARAS is a toggle macro, therefore passing it any +argument (<b>OFF, QUIT, Q, X</b>...) cancels its effect, meaning +that first paragraphs will once again not be indented. +</p> + +<h4 id="pp-space" class="docs">8. Spacing paragraphs</h4> + +<p> +By default, mom does not insert a blank line between +paragraphs. If you would like her to do so, invoke the macro, +<kbd>.PARA_SPACE</kbd>, without an argument, either before or after +<a href="docprocessing.html#start">START</a>. +PARA_SPACE is a toggle macro, therefore passing it any argument +(<b>OFF, QUIT, Q, X</b>...) cancels its effect, meaning that +paragraphs will once again not be separated by a blank line. +</p> + +<div class="box-tip"> +<p class="tip-top"> +<span class="note">Note:</span> +If PARA_SPACE is on, mom spaces only those paragraphs that come +after an initial paragraph. Initial paragraphs are those that come +immediately after the +<a href="definitions.html#docheader">docheader</a>, +<a href="#epigraph-intro">epigraphs</a>, +<a href="#head-intro">heads</a>, +<a href="#subhead-intro">subheads</a> +and +<a href="#linebreak-intro">linebreaks</a>. +(The first paragraph after these document elements requires no +blank line to separate it from other paragraphs.) +</p> + +<p class="tip-bottom"> +Sometimes, you can be fairly deep into a document before using PP +for the first time, and when you do, because mom is still waiting +for that initial paragraph, she doesn’t space it with a blank +line, even though you expect her to. The simple workaround for this +is to invoke <kbd>.PP</kbd> twice (in succession) at the point you +expect the blank line to appear. +</p> +</div> + +<div class="rule-short"><hr/></div> + +<!-- ==================================================================== --> + +<h2 id="head-intro" class="macro-group">Main heads</h2> + +<ul style="margin-left: -.5em;"> + <li><a href="#head">Tag: HEAD</a></li> + <li><a href="#head-control">Head control macros and defaults</a></li> +</ul> + +<p> +Main heads—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 +<a href="#subhead-intro">subheads</a> +and +<a href="#parahead-intro">paraheads</a>. +</p> + +<p> +By default, heads are centred on the page, underlined, all in caps. +A double linespace precedes each head. In +<a href="docprocessing.html#printstyle">PRINTSTYLE <kbd>TYPESET</kbd></a>, +heads are bold, slightly larger than paragraph text. +</p> + +<p> +If these defaults don’t suit you, you can change them with the +head control macros. +</p> + +<!-- -HEAD- --> + +<div class="macro-id-overline"> +<h3 id="head" class="macro-id">HEAD</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>HEAD</b> <kbd class="macro-args">"<text of head>" [ "<2nd line>" [ "<3rd line>" ... ] ]</kbd> +</div> + +<p> +The argument to HEAD is the text of the head, surrounded by +double-quotes. If you need additional lines for a head, simply +surround each line with double-quotes. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +If a head falls near the bottom of an output page and mom is unable +to fit the head <i>plus at least one line of text underneath it</i>, +she will set the head at the top of the next page. +</p> + +<p class="tip-bottom"> +<span class="additional-note">Additional note:</span> +If an +<a href="definitions.html#inputline">input line</a> +in a head (i.e. one of the lines surrounded by double-quotes) has +to be broken by mom in order to fit the current line-length (say, +a narrow column measure), the head underline (underscore) will not +behave. You’ll recognize the problem as soon as you preview +your document. If you encounter a head that misbehaves with respect +to underlining, the solution is to supply each line <i>as you want +it</i> as a separate argument (surrounded by double-quotes) to the +HEAD macro. +</p> + +<p> +For example, if mom breaks +<br/> +<span class="pre-in-pp"> + .HEAD "This is a very, very, very long head" +</span> +into<br/> +<span class="pre-in-pp"> + This is a very, very, very + long head +</span> +you’ll see the misbehaving underscore and should change the +argument to HEAD to +<br/> +<span class="pre-in-pp"> + .HEAD "This is a very, very very" "long head" +</span> +</p> +</div> + +<div class="defaults-container" style="background-color: #ded4bd; border: none;"> +<h3 id="head-control" class="docs defaults">HEAD control macros and defaults</h3> + +<p class="defaults"> +There are, in addition to the usual family/font/size/quad control +macros, a number of macros to manage head numbering, spacing, +underlining, and so on. Check them out if you’re unhappy with +mom’s defaults. +</p> +<ol style="margin-top: .5em; padding-bottom: .5em;"> + <li><a href="#head-general">Family/font/size/colour/quad</a></li> + <li><a href="#head-caps">Capitalizing heads</a></li> + <li><a href="#head-space">Pre-head space</a></li> + <li><a href="#head-underline">Underscoring</a></li> + <li><a href="#number-heads">Numbering</a></li> + <li><a href="#reset-head-number">Reset head numbering</a></li> + <li><a href="#head-inlines">Vertical inline escapes inside heads</a></li> +</ol> +</div> + +<h4 id="head-general" class="docs" style="margin-top: -1.5em; margin-bottom: .5em;">1. Family/font/size/colour/quad</h4> + +<div class="defaults-container" style="padding-bottom: 8px;"> +<p class="defaults" style="padding-top: 6px;"> +See +<a href="#control-macro-args">Arguments to the control macros</a>. +</p> +<span class="pre defaults"> +.HEAD_FAMILY default = prevailing document family; default is Times Roman +.HEAD_FONT default = bold +.HEAD_SIZE default = +1 (point) +.HEAD_COLOR default = black +.HEAD_QUAD default = CENTER +</span> +</div> + +<h4 id="head-caps" class="docs" style="margin-top: -1.25em;">2. Capitalizing heads</h4> + +<p> +By default, mom sets heads in caps, regardless of the +<a href="definitions.html#stringargument">string(s)</a> +you give to +<a href="#head">HEAD</a>. +To change this behaviour, do +<br/> +<span class="pre-in-pp"> + .HEAD_CAPS OFF +</span> +HEAD_CAPS is a toggle macro, therefore you can use any argument you +like instead of <kbd>OFF</kbd> (<b>END, QUIT, Q, X</b>...). To turn +HEAD_CAPS back on, simply invoke it without an argument. +</p> + +<h4 id="head-space" class="docs" style="margin-top: -.25em;">3. Pre-head space</h4> + +<p> +By default, mom deposits 2 blank lines prior to every head. If +you’d prefer just a single blank line, do +<br/> +<span class="pre-in-pp"> + .HEAD_SPACE OFF +</span> +HEAD_SPACE is a toggle macro, therefore you can use any argument +you like instead of <kbd>OFF</kbd> (<kbd>END, QUIT, Q, X</kbd>...). +To restore the space before heads to 2 blank lines, invoke +<kbd>.HEAD_SPACE</kbd> without an argument. +</p> + +<h4 id="head-underline" class="docs" style="margin-top: -.25em;">4. Underscoring</h4> + +<p> +By default, mom underlines heads. To change this behaviour, do +<br/> +<span class="pre-in-pp"> + .HEAD_UNDERLINE OFF +</span> +HEAD_UNDERLINE can be used as a toggle macro, therefore you can +use any argument you like instead of <kbd>OFF</kbd> (<kbd>END, +QUIT, Q, X</kbd>...) to turn it off, or invoke it by itself to +turn head underlining on. +</p> + +<p> +In addition to toggling head underlining on or off, as of +version 1.5 of mom, you can use HEAD_UNDERLINE to set the weight +of the underline and its distance from the head, like this: +<br/> +<span class="pre-in-pp"> + .HEAD_UNDERLINE <weight> [<gap>] +</span> +The <kbd>weight</kbd> argument is in points, or fractions thereof, +and must not have the +<a href="definitions.html#unitofmeasure">unit of measure</a>, +<kbd>p</kbd>, appended. Like +<a href="inlines.html#rule-weight">RULE_WEIGHT</a>, +weights must be greater than 0 and less than 100. Mom’s +default for head underlines is 1/2 point. +</p> + +<p> +The <kbd>gap</kbd> argument determines the distance from the +baseline of the head to the upper edge of the underline. It can +be given using any unit of measure, and must have the unit of +measure appended to the argument. Mom’s default gap for head +underlines is 2 points. +</p> + +<p> +As an example, suppose you want your heads underlined with a +4-point rule separated from the head by 3 points. The way to +accomplish it is: +<br/> +<span class="pre-in-pp"> + .HEAD_UNDERLINE 4 3p +</span> +If you wanted the same thing, but were content with mom’s +default gap of 2 points, +<br/> +<span class="pre-in-pp"> + .HEAD_UNDERLINE 4 +</span> +would do the trick. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +If you supply a weight to HEAD_UNDERLINE, and optionally a gap, you +also turn the underlining of heads on; if this is not what you want, +you must turn head underlining off manually afterwards. +</p> +</div> + +<h4 id="number-heads" class="docs" style="margin-top: -.25em;">5. Numbering</h4> + +<p> +If you’d like your heads numbered, simply invoke +<span class="pre-in-pp"> + .NUMBER_HEADS +</span> +with no argument. Mom will number all subsequent heads automatically +(in ascending order, naturally). +</p> + +<p> +If, in addition to numbering heads, you also request that +<a href="#subhead-intro">subheads</a> +and/or +<a href="#parahead-intro">paraheads</a> +be numbered, the head number will be included in their numbers (each +number separated by a period [dot]). +</p> + +<p> +Should you wish to stop head numbering, invoke +<kbd>.NUMBER_HEADS</kbd> with any argument (<kbd>OFF, QUIT, END, +X</kbd>...). Head numbering will cease, and the head number will +not be included in the numbering of subheads and/or paraheads. +</p> + +<p> +See also +<a href="#prefix-chapter-number">Prefixing chapter numbers</a> +if you’d like chapter numbers prepended to the head numbers. +</p> + +<h4 id="reset-head-number" class="docs" style="margin-top: -.25em;">6. Reset head numbering</h4> + +<p> +Should you wish to reset the head number to “1”, +invoke +<span class="pre-in-pp"> + .RESET_HEAD_NUMBER +</span> +with no argument. If, for some reason, you want mom to use a head +number that is not the next in ascending order (i.e. the last head +number + 1), invoke <kbd>.RESET_HEAD_NUMBER</kbd> with the number +you want, e.g. +<br/> +<span class="pre-in-pp"> + .RESET_HEAD_NUMBER 6 +</span> +Your next head will be numbered “6” and subsequent heads will +be numbered in ascending order from “6”. +</p> + +<h4 id="head-inlines" class="docs" style="margin-top: -.25em;">7. Vertical inline escapes inside heads</h4> + +<p> +If you need to adjust the +<a href="definitions.html#baseline">baseline</a> +position of a head (e.g. the head falls at the top of a column and +you want its +<a href="definitions.html#ascender">ascenders</a> +to line up with the ascenders of +<a href="definitions.html#running">running text</a> +in other columns), you can embed a vertical motion +<a href="definitions.html#inlines">inline escape</a> +(either +<a href="inlines.html#inline-vertical-mom">mom</a>’s +or +<a href="inlines.html#inline-vertical-groff">groff</a>’s +in the string(s) you pass to HEAD. +</p> + +<p> +For example, +<br/> +<span class="pre-in-pp" style="margin-bottom: -1em;"> + .HEAD "\*[DOWN 3p]Text of head" +</span> +or +<span class="pre-in-pp" style="margin-top: -.5em;"> + .HEAD "\v'3p'Text of head" +</span> +will lower the baseline of the head by three points. Note that +there’s no need to reverse the sense of the inline escape. +</p> + +<p> +In the case of heads that run to more than one line, you must embed +the escape in the string for each line, like this: +<br/> +<span class="pre-in-pp" style="margin-bottom: -1em;"> + .HEAD "\*[DOWN 3p]First line" "\[DOWN 3p]Next line" +</span> +or +<span class="pre-in-pp" style="margin-top: -.5em;"> + .HEAD "\v'3p'First line" "\v'3p'Next line" +</span> +</p> + +<div class="rule-short"><hr/></div> + +<!-- ==================================================================== --> + +<h2 id="subhead-intro" class="macro-group">Subheads</h2> + +<ul style="margin-left: -.5em;"> + <li><a href="#subhead">Tag: SUBHEAD</a></li> + <li><a href="#subhead-control">Subhead control macros</a></li> +</ul> + +<p> +Subheads should be used any place you want titles to introduce +sections of a document below heads. If you wish, mom can +number subheads for you. Subhead numbers can also be included +hierarchically in numbered +<a href="#parahead-intro">paraheads</a>. +</p> + +<p> +By default, subheads are flush left. In +<a href="docprocessing.html#printstyle">PRINTSTYLE <kbd>TYPESET</kbd></a>, +they are set bold, slightly larger than paragraph text. In +<a href="docprocessing.html#printstyle">PRINTSTYLE <kbd>TYPEWRITE</kbd></a>, +they are underlined. A single linespace precedes them in both +printstyles, and a tiny space adjustment raises them slightly +above text that comes afterwards for greater clarity in document +structuring. +</p> + +<p> +If these defaults don’t suit you, you can change them with the +subhead control macros. +</p> + +<!-- -SUBHEAD- --> + +<div class="macro-id-overline"> +<h3 id="subhead" class="macro-id">SUBHEAD</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>SUBHEAD</b> <kbd class="macro-args">"<text of subhead>" [ "<2nd line>" [ "<3rd line>" ... ] ]</kbd> +</div> + +<p> +The argument to SUBHEAD is the text of the subhead, surrounded by +double-quotes. If you need additional lines for a subhead, simply +surround each line with double-quotes. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +If a subhead falls near the bottom of an output page and mom is +unable to fit the head <i>plus at least one line of text underneath +it</i>, she will set the subhead at the top of the next page. +</p> +</div> + +<div class="defaults-container" style="background-color: #ded4bd; border: none;"> +<h3 id="subhead-control" class="docs defaults">SUBHEAD control macros and defaults</h3> + +<p class="defaults"> +In addition to the usual family/font/size/quad control macros, there +are macros to manage subhead numbering. +</p> + +<ol style="margin-top: .5em; padding-bottom: .5em;"> + <li><a href="#subhead-general">Family/font/size/colour/quad</a></li> + <li><a href="#number-subheads">Numbering</a></li> + <li><a href="#reset-subhead-number">Reset subhead numbering</a></li> + <li><a href="#subhead-inlines">Vertical inline escapes inside subheads</a></li> +</ol> +</div> + +<h4 id="subhead-general" class="docs" style="margin-top: -1.5em; margin-bottom: .5em;">1. Family/font/size/quad</h4> + +<div class="defaults-container" style="padding-bottom: 8px;"> +<p class="defaults" style="padding-top: 6px;"> +See +<a href="#control-macro-args">Arguments to the control macros</a>. +</p> +<span class="pre defaults" style="padding-bottom: -1em;"> +.SUBHEAD_FAMILY default = prevailing document family; default is Times Roman +.SUBHEAD_FONT default = bold +.SUBHEAD_SIZE default = +.5 (point) +.SUBHEAD_COLOR default = black +.SUBHEAD_QUAD default = LEFT +</span> +</div> + +<h4 id="number-subheads" class="docs" style="margin-top: -1.25em;">2. Number subheads</h4> + +<p> +If you’d like your subheads numbered, simply invoke +<kbd>.NUMBER_SUBHEADS</kbd> with no argument. Mom +will number all subsequent subheads automatically (in ascending +order, naturally). +</p> + +<p> +If, in addition to numbering subheads, you also request that +<a href="#head-intro">heads</a> +be numbered, the head number will be included in the subhead number +(separated by a period [dot]). +</p> + +<p> +Should you wish to stop subhead numbering, invoke +<kbd>.NUMBER_SUBHEADS</kbd> with any argument (<kbd>OFF, QUIT, END, +X</kbd>...). Subhead numbering will cease, and the subhead number +will not be included in the numbering of paraheads. +</p> + +<p> +See also +<a href="#prefix-chapter-number">Prefixing chapter numbers</a> +if you’d like chapter numbers prepended to the subhead numbers. +</p> + +<h4 id="reset-subhead-number" class="docs" style="margin-top: -.25em;">3. Reset subhead numbering</h4> + +<p> +Should you wish to reset the subhead number to “1”, +invoke +<span class="pre-in-pp"> + .RESET_SUBHEAD_NUMBER +</span> +with no argument. If, for some reason, you want mom to use a +subhead number that is not the next in ascending order (i.e. the +last subhead number + 1), invoke <kbd>.RESET_SUBHEAD_NUMBER</kbd> +with the number you want, e.g. +<br/> +<span class="pre-in-pp"> + .RESET_SUBHEAD_NUMBER 4 +</span> + +Your next subhead will be numbered “4” and subsequent +subheads will be numbered in ascending order from “4”. +</p> + +<h4 id="subhead-inlines" class="docs" style="margin-top: -.25em;">4. Vertical inline escapes inside subheads</h4> + +<p> +See +<a href="#head-inlines">Vertical inline escapes inside heads</a>. +The information there applies equally to subheads. +</p> + +<div class="rule-short"><hr/></div> + +<!-- ==================================================================== --> + +<h2 id="parahead-intro" class="macro-group">Paragraph heads</h2> + +<ul style="margin-left: -.5em;"> + <li><a href="#parahead">Tag: PARAHEAD</a></li> + <li><a href="#parahead-control">Parahead control macros</a></li> +</ul> + +<p> +Paragraph heads (paraheads) should be used any place you want titles +to introduce paragraphs below heads or subheads. If you wish, mom +can number paraheads for you. +</p> + +<p> +By default, paraheads are joined to the body of a paragraph, +slightly indented (provided the paragraph is not a +“first” paragraph as defined in +<a href="#para-indent-first">Indenting initial paragraphs</a>) +and separated from the body of the paragraph by a small amount of +horizontal space. In +<a href="docprocessing.html#printstyle">PRINTSTYLE <kbd>TYPESET</kbd></a>, +they are set bold italic, slightly larger than paragraph text. In +<a href="docprocessing.html#printstyle">PRINTSTYLE <kbd>TYPEWRITE</kbd></a>, +they are underlined. +</p> + +<p> +If these defaults don’t suit you, you can change them with the +parahead control macros. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="tip">Tip:</span> +If you really need a heading level below subhead (a sub-subhead) +that isn’t joined to the body of a paragraph, you can trick +PARAHEAD into giving you one by creating a paragraph that contains +only a parahead, like this: +<br/> +<span class="pre-in-pp"> + .PP + .PARAHEAD "My Sub-Subhead" + .PP + <text> +</span> +</p> +</div> + +<!-- -PARAHEAD- --> + +<div class="macro-id-overline"> +<h3 id="parahead" class="macro-id">PARAHEAD</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>PARAHEAD</b> <kbd class="macro-args">"<text of parahead>"</kbd> +</div> + +<p> +PARAHEAD must come after +<a href="#pp">PP</a> +or it will not work. +</p> + +<p> +The argument is the text of the parahead, surrounded by +double-quotes. Because paraheads are joined to the body of a +paragraph, they accept only one argument (see +<a href="#head">HEAD</a> +and +<a href="#subhead">SUBHEAD</a>). +</p> + +<div class="defaults-container" style="background-color: #ded4bd; border: none;"> +<h3 id="parahead-control" class="docs defaults">PARAHEAD control macros and defaults</h3> + +<p class="defaults"> +In addition to the family/font/size/colour/indent control macros, +there are macros to manage parahead numbering. +</p> + +<ol style="margin-top: .5em; padding-bottom: .5em;"> + <li><a href="#parahead-general">Family/font/size/color</a></li> + <li><a href="#parahead-indent">Indent</a></li> + <li><a href="#parahead-space">Horizontal space</a></li> + <li><a href="#number-paraheads">Numbering</a></li> + <li><a href="#reset-parahead-number">Reset parahead numbering</a></li> +</ol> +</div> + +<h4 id="parahead-general" class="docs" style="margin-top: -1.5em; margin-bottom: .5em;">1. Family/font/size/colour</h4> + +<div class="defaults-container" style="padding-bottom: 8px;"> +<p class="defaults" style="padding-top: 6px;"> +See +<a href="#control-macro-args">Arguments to the control macros</a>. +</p> +<span class="pre defaults"> +.PARAHEAD_FAMILY default = prevailing document family; default is Times Roman +.PARAHEAD_FONT default = bold italic +.PARAHEAD_SIZE default = +.5 (point) +.PARAHEAD_COLOR default = black* + +*If you colourize paragraph text, paraheads will appear in the same + colour as the text unless you explicitly tell mom to colour them + otherwise by invoking .PARAHEAD_COLOR. If you do want paraheads + that are coloured the same as paragraph text, it’s generally a good + idea to invoke .PARAHEAD_COLOR anyway (with the same colour used + for paragraph text), just to let mom know. +</span> +</div> + +<h4 id="parahead-indent" class="docs" style="margin-top: -1.25em;">2. Indent</h4> + +<p> +Unlike other control macros that end in +<a href="#control-indents">_INDENT</a>, +the argument to the macro that controls indenting of paragraph +heads (PARAHEAD_INDENT) is not relative to the first-line indent of +normal paragraphs. In other words, it takes an absolute value, and +requires a +<a href="definitions.html#unitofmeasure">unit of measure</a>. +For example, to set the paragraph head indent to 2-1/2 picas, you +do: +<br/> +<span class="pre-in-pp"> + .PARAHEAD_INDENT 2.5P +</span> +</p> + +<p> +Mom’s default indent for paragraph heads is 1/2 the first-line +indent of normal paragraphs (both printstyles). However, as stated +above, if you choose to change the indent, you must give an absolute +value (unless you’re a groff expert and want to manipulate the +number register <kbd>\n[#PP_INDENT]u</kbd> arithmetically as the +argument to PARAHEAD_INDENT for an indent that’s relative to +PP_INDENT.) +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +Paragraph heads in “first paragraphs”, as defined in +<a href="#para-indent-first">Indenting initial paragraphs</a>, +are not indented unless you turn +<kbd><a href="#indent-first-paras">INDENT_FIRST_PARAS</a></kbd> +on. +</p> +</div> + +<h4 id="parahead-space" class="docs" style="margin-top: -.25em;">3. Horizontal space</h4> + +<p> +The default amount of horizontal space between a parahead and the +text that begins the body of a paragraph is 2/3 of an +<a href="definitions.html#em">em</a> +for +<a href="docprocessing.html#printstyle">PRINTSTYLE <kbd>TYPESET</kbd></a>) +and 1 +<a href="definitions.html#figurespace">figure space</a> +for +<a href="docprocessing.html#printstyle">PRINTSTYLE <kbd>TYPEWRITE</kbd></a>). +</p> + +<p> +The default for <kbd>TYPEWRITE</kbd> is fixed, but if the default +for <kbd>TYPESET</kbd> doesn’t suit you, you can change it +with the macro, PARAHEAD_SPACE. +</p> +<p> +PARAHEAD_SPACE takes just one argument: the amount of space you +want, with a +<a href="definitions.html#unitofmeasure">unit of measure</a> +appended. Thus, if you want the horizontal space between a parahead +and the start of paragraph text to be 6 +<a href="definitions.html#picaspoints">points</a>, +you’d do: +<br/> +<span class="pre-in-pp"> + .PARAHEAD_SPACE 6p +</span> +</p> + +<h4 id="number-paraheads" class="docs" style="margin-top: -1.25em;">4. Numbering</h4> + +<p> +If you’d like your paraheads numbered, simply invoke +<kbd>.NUMBER_PARAHEADS</kbd> with no argument. Mom +will number all subsequent paraheads automatically (in ascending +order, naturally). +</p> + +<p> +If, in addition to numbering paraheads, you also request that +<a href="#head-intro">heads</a> +and +<a href="#subhead-intro">subheads</a> +be numbered, the head and/or subhead number will be included in the +parahead number (separated by a period [dot]). +</p> + +<p> +Should you wish to stop parahead numbering, invoke +<kbd>.NUMBER_PARAHEADS</kbd> with any argument (<kbd>OFF, QUIT, END, +X</kbd>...). Parahead numbering will cease. +</p> + +<p> +See also +<a href="#prefix-chapter-number">Prefixing chapter numbers</a> +if you’d like chapter numbers prepended to the paragraph head +numbers. +</p> + +<h4 id="reset-parahead-number" class="docs" style="margin-top: -.25em;">5. Reset paragraph head numbering</h4> + +<p> +Should you wish to reset the parahead number to “1”, +invoke +<span class="pre-in-pp"> + .RESET_PARAHEAD_NUMBER +</span> +with no argument. If, for some reason, you want mom to use a +parahead number that is not the next in ascending order (i.e. the +last parahead number + 1), invoke <kbd>.RESET_PARAHEAD_NUMBER</kbd> +with the number you want, e.g. +<br/> +<span class="pre-in-pp"> + .RESET_PARAHEAD_NUMBER 7 +</span> +Your next parahead will be numbered “7” and subsequent +paraheads will be numbered in ascending order from “7”. +</p> + +<!-- -PREFIX_CHAPTER_NUMBER- --> + +<div class="examples-container" style="margin-bottom: 1.5em;"> +<div id="prefix-chapter-number" class="macro-id-overline" style="border-top: none;"> +<h3 class="macro-id" style="margin-top: 9px; text-transform: none; font-size: 105%;">Prefixing chapter numbers</h3> +</div> + +<div class="box-macro-args" style="width: 686px;"> +Macro: <b>PREFIX_CHAPTER_NUMBER</b> <kbd class="macro-args"><none> | <chapter number as digit> | <anything></kbd> +</div> + +<p> +If you’ve requested numbering of heads, subheads and/or paragraph +heads (with +<a href="#number-heads">NUMBER_HEADS</a>, +<a href="#number-subheads">NUMBER_SUBHEADS</a> +and/or +<a href="#number-paraheads">NUMBER_PARAHEADS</a>) +and you’d like mom, in addition, to prefix +a chapter number to the numbering scheme, you can do so with +PREFIX_CHAPTER_NUMBER. +</p> + +<p> +After you invoke <kbd>.PREFIX_CHAPTER_NUMBER</kbd>, mom will prepend +the current chapter number to all subsequent head elements (main +heads, subheads or paragraph heads) for which you have requested +numbering. Thus, assuming chapter number twelve (12): +<br/> +<span class="pre-in-pp"> + 1. FIRST MAIN HEAD + ------------------ + + 1.1. First Subhead Under Main Head +</span> +becomes +<br/> +<span class="pre-in-pp"> + 12.1. FIRST MAIN HEAD + --------------------- + + 12.1.1. First Subhead Under Main Head +</span> +</p> + +<p> +When you invoke <kbd>.PREFIX_CHAPTER_NUMBER</kbd> without an +argument, mom checks to see whether the argument +you passed to +<a href="docprocessing.html#chapter">CHAPTER</a> +is a digit. If it is, she immediately starts pre-pending the +current chapter number to numbered head elements. If it isn’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. +</p> + +<p> +In collated documents, mom automatically increments +the digit used by PREFIX_CHAPTER_NUMBER by one +(current chapter digit + 1) every time you invoke +<a href="rectoverso.html#collate"><kbd>.COLLATE</kbd></a>, +even if you’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 <i>must</i> must put +<br/> +<span class="pre-in-pp"> + .PREFIX_CHAPTER_NUMBER <chapter number> +</span> +somewhere after the invocation of COLLATE and +before the first numbered head element of each collated document). +</p> + +<p> +PREFIX_CHAPTER_NUMBER can be disabled by passing +it any argument other than a digit (e.g. <b>OFF, QUIT, END, +X</b>, etc), although, as noted above, mom +will keep, and—in the case of collated +documents—increment the chapter number, allowing you to turn +prefixing of +chapter numbers to numbered head elements off and on according to +your needs or whims. +</p> + +<p> +<span class="note">Note:</span> +Because PREFIX_CHAPTER_NUMBER takes an (optional) digit representing +the chapter number, it’s use need not be restricted to +<a href="docprocessing.html#doctype">DOCTYPE <kbd>CHAPTER</kbd></a>. +You can use it with any document type. Furthermore, even if +your doctype isn’t <kbd>CHAPTER</kbd>, you can identify +the document as a chapter <i>for the purposes of numbering head +elements</i> by invoking the macro, +<a href="docprocessing.html#chapter"><kbd>.CHAPTER</kbd></a>, +with a +<a href="definitions.html#numericargument">numeric argument</a> +in your document setup. +</p> +</div> + +<div class="rule-short"><hr/></div> + +<!-- ==================================================================== --> + +<h2 id="linebreak-intro" class="macro-group">Linebreaks (section breaks)</h2> + +<ul style="margin-left: -.5em;"> + <li><a href="#linebreak">Tag: LINEBREAK</a></li> + <li><a href="#linebreak-control">Linebreak control macros and defaults</a></li> +</ul> + +<p> +Linebreaks (“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. +</p> + +<!-- -LINEBREAK- --> + +<div class="macro-id-overline"> +<h3 id="linebreak" class="macro-id">LINEBREAK</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>LINEBREAK</b> +</div> +<p class="alias" style="margin-bottom: 0;"> +<i>Alias:</i> <b>SECTION</b> +</p> + +<p> +LINEBREAK takes no arguments. Simply invoke it (on a line by +itself, of course) whenever you want to insert an author linebreak. +</p> + +<div class="defaults-container" style="background-color: #ded4bd; border: none;"> +<h3 id="linebreak-control" class="docs defaults">LINEBREAK control macros and defaults</h3> + +<p class="defaults"> +By default, mom marks +<a href="definitions.html#linebreak">author linebreaks</a> +with three centred asterisks (stars) in the prevailing colour of the +document (by default, black). You can alter this with the control +macros +</p> +<ol style="margin-top: .5em; padding-bottom: .5em;"> + <li><a href="#linebreak-char">LINEBREAK_CHAR</a></li> + <li><a href="#linebreak-color">LINEBREAK_COLOR</a></li> +</ol> +</div> + +<h4 id="linebreak-char" class="docs" style="margin-top: -1.5em; margin-bottom: .5em;">1. Linebreak character</h4> +<div class="box-macro-args"> +Macro: <b>LINEBREAK_CHAR</b> <kbd class="macro-args">[ <character> ] [ <iterations> [ <vertical adjustment> ] ]</kbd> +</div> + +<p class="alias" style="margin-bottom: 0;"> +<i>Alias:</i> <b>SECTION_CHAR</b> +</p> +<p class="requires"> +• The third optional argument requires a +<a href="definitions.html#unitofmeasure">unit of measure</a>. +</p> + +<p> +LINEBREAK_CHAR determines what mom prints when LINEBREAK is invoked. +It takes 3 optional arguments: the character you want deposited at +the line break, the number of times you want the character repeated, +and a vertical adjustment factor. +</p> + +<p> +The first argument is any valid groff character (e.g. <kbd>*</kbd> +[an asterisk], <kbd>\(dg</kbd> [a dagger], <kbd>\f(ZD\N'141\fP</kbd> +[an arbitrary character from Zapf Dingbats], <kbd>\l'4P'</kbd> [a +4-pica long rule]). Mom sets the character centred on the current +line length. (See <kbd>man groff_char</kbd> for a list of all +valid groff characters.) +</p> + +<p> +The second argument is the number of times to repeat the character. +</p> + +<p> +The third argument is a +|-value by which to raise (+) or lower (-) +the character in order to make it appear visually centred between +sections of text. This lets you make vertical adjustments to +characters that don’t sit on the +<a href="definitions.html#baseline">baseline</a> +(such as asterisks). The argument must be preceded by a plus or +minus sign, and must include a unit of measure. +</p> + +<p> +If you enter LINEBREAK_CHAR with no arguments, sections of +text will be separated by two blank lines when you invoke +<kbd>.LINEBREAK</kbd>. +</p> + +<p> +Mom’s default for LINEBREAK_CHAR is +<br/> +<span class="pre-in-pp"> + .LINEBREAK_CHAR * 3 -3p +</span> +i.e. three asterisks, lowered 3 points from their normal vertical +position (for +<a href="docprocessing.html#printstyle">PRINTSTYLE <kbd>TYPESET</kbd></a>; +the vertical adjustment is -2 points for +<a href="docprocessing.html#printstyle">PRINTSTYLE <kbd>TYPEWRITE</kbd></a>). +</p> + +<h4 id="linebreak-color" class="docs" style="margin-top: -.25em; margin-bottom: .5em;">2. Linebreak colour</h4> + +<div class="box-macro-args"> +Macro: <b>LINEBREAK_COLOR</b> <kbd class="macro-args"><color name></kbd> +</div> +<p class="alias" style="margin-bottom: 0;"> +<i>Alias:</i> <b>SECTION_COLOR</b> +</p> + +<p> +To change the colour of the linebreak character(s), simply invoke +<kbd>.LINEBREAK_COLOR</kbd> with the name of a colour pre-defined +(or “initialized”) with +<a href="color.html#newcolor">NEWCOLOR</a> +or +<a href="color.html#xcolor">XCOLOR</a>. + +</p> + +<div class="rule-short"><hr/></div> + +<!-- ==================================================================== --> + +<h2 id="quote-intro" class="macro-group">Quotes (line for line, poetry or code)</h2> + +<ul style="margin-left: -.5em;"> + <li><a href="#quote">Tag: QUOTE</a></li> + <li><a href="#quote-control">Quote control macros and defaults</a></li> +</ul> + +<p> +<a href="definitions.html#quote">Quotes</a> +are always set in +<a href="definitions.html#filled">nofill mode</a>, +flush left. This permits entering quotes on a line for line basis +in your text editor and have them come out the same way on output +copy. (See +<a href="#blockquote-intro">Blockquotes</a> +for how quotes, in the present sense, differ from longer passages of +cited text.) +</p> + +<p> +Since mom originally came into being to serve the needs of creative +writers (i.e. novelists, short story writers, etc.—not +to cast aspersions on the creativity of mathematicians and +programmers), she sets quotes in italics +<a href="docprocessing.html#printstyle">(PRINTSTYLE <kbd>TYPESET</kbd>)</a> +or underlined +<a href="docprocessing.html#printstyle">(PRINTSTYLE <kbd>TYPEWRITE</kbd>)</a>, +indented from the left margin. Obviously, she’s thinking +“quotes from poetry or song lyrics”, but with the +<a href="#quote-control">QUOTE control macros</a> +you can change her defaults so QUOTE serves other needs, e.g. +entering verbatim snippets of programming code, command line +instructions, and so on. (See the +<a href="#code">CODE</a> +for a convenience macro to assist in including programming code +snippets in documents.) +</p> + +<h3 id="quote-spacing" class="docs">QUOTE spacing</h3> + +<p> +Besides indenting quotes, mom further sets them off from +<a href="definitions.html#running">running text</a> +with a small amount of vertical whitespace top and bottom. In +<a href="docprocessing.html#printstyle">PRINTSTYLE <kbd>TYPEWRITE</kbd></a>, +this is always one full linespace. In +<a href="docprocessing.html#printstyle">PRINTSTYLE <kbd>TYPESET</kbd></a>, +it’s 1/2 of the prevailing +<a href="definitions.html#leading">leading</a> +if the quote fits fully on the page (i.e. with running text above +and below it), otherwise it’s a full linespace either above +or below as is necessary to balance the page to the bottom margin. +This behaviour can be changed with the control macro +<a href="#always-fullspace-quotes">ALWAYS_FULLSPACE_QUOTES</a>. +</p> + +<div class="box-tip"> +<h2 id="quote-spacing-notes" class="docs" style="padding-top: 9px; font-size: 100%;">Further notes on quote spacing</h2> +<p class="cefaults"> +As of version 1.3 of mom, handling of the vertical whitespace around +quotes changed slightly from its original implementation. +</p> + +<p> +In versions of mom prior to 1.3, it was not possible to alter the +<a href="definitions.html#leading">leading</a> +of quotes and blockquotes (which was the same as the document +leading), ensuring that the vertical whitespace remained consistent, +as described above. +</p> + +<p> +As of version 1.3, it became possible to change the +leading of quotes and blockquotes with <kbd>.QUOTE_AUTOLEAD</kbd> and +<kbd>BLOCKQUOTE_AUTOLEAD</kbd>, with the following changes in +mom’s behaviour: +</p> + +<p> +If your quote (or blockquote) leading differs from the document +leading, mom attempts to observe the same rules for vertical +whitespace outlined above; however, she will also insert a small, +flexible amount of extra whitespace around the quotes to make sure +the whitespace is equal, top and bottom. Since she does this +on a quote by quote basis, rather than by figuring out how much +extra whitespace is needed to adjust <i>all</i> quotes on a page, +the spacing around multiple quotes on the same page will differ +slightly, although each will be balanced between lines of normal +<a href="definitions.html#running">running text</a>, +top and bottom. (The inability to scan an entire page and insert +equalized whitespace at marked places is a limitation of groff, +which, by and large, processes text on a line-per-line basis.) +</p> + +<p> +If you don’t want the behaviour described above (i.e. you +don’t want mom shimming [possibly irregularly linespaced] +quotes or blockquotes), issue the macro +<br/> +<span class="pre-in-pp"> + .NO_SHIM +</span> +prior to invoking <kbd>.QUOTE</kbd> or <kbd>.BLOCKQUOTE</kbd>. +</p> + +<p> +If you’ve disabled shimming of quotes and blockquotes with +<kbd>.NO_SHIM</kbd> and you want mom to return to her default +behaviour in this matter, invoke <kbd>.NO_SHIM OFF</kbd> (or +<kbd>QUIT, END, X</kbd>, etc). +</p> + +<p class="tip-bottom"> +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. +</p> +</div> + +<!-- -QUOTE- --> + +<div class="macro-id-overline"> +<h3 id="quote" class="macro-id">QUOTE</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>QUOTE</b> <kbd class="macro-args">toggle</kbd> +</div> + +<p> +QUOTE is a toggle macro. To begin a section +of quoted text, invoke it with no argument, then type in your +quote. When you’re finished, invoke <kbd>.QUOTE</kbd> with any +argument (e.g. <kbd>OFF, END, X, Q</kbd>...) to turn it off. Example: +<br/> +<span class="pre-in-pp"> + .QUOTE + Nymphomaniacal Jill + Used a dynamite stick for a thrill + They found her vagina + In North Carolina + And bits of her tits in Brazil. + .QUOTE END +</span> +</p> + +<div class="defaults-container" style="background-color: #ded4bd; border: none;"> +<h3 id="quote-control" class="docs defaults">QUOTE control macros and defaults</h3> + +<ol style="margin-top: .5em; padding-bottom: .5em;"> + <li><a href="#quote-general">Family/font/size/leading/colour/indent</a></li> + <li><a href="#always-fullspace-quotes">Spacing above and below quotes (typeset only)</a></li> + <li><a href="#underline-quotes">Underlining quotes (typewrite only)</a></li> + <li><a href="#break-quote">Manually break a footnoted quote that crosses pages/columns (deprecated)</a></li> +</ol> +</div> + +<h4 id="quote-general" class="docs" style="margin-top: -1.5em; margin-bottom: .5em;">1. Family/font/size/colour/indent</h4> + +<div class="defaults-container" style="padding-bottom: 8px;"> +<p class="defaults" style="padding-top: 6px;"> +See +<a href="#control-macro-args">Arguments to the control macros</a>. +</p> +<span class="pre defaults"> +.QUOTE_FAMILY default = prevailing document family; default is Times Roman +.QUOTE_FONT default = italic; underlined in TYPEWRITE +.QUOTE_SIZE default = +0 (i.e. same size as paragraph text) +.QUOTE_AUTOLEAD default = none; leading of quotes is the same as paragraphs +.QUOTE_COLOR default = black +.QUOTE_INDENT (see below, "Quote indent") +</span> +</div> + +<h4 id="quote-indent" class="docs" style="margin-top: -1.5em;">Quote indent</h4> + +<p> +Prior to version 1.4-b, mom allowed only the passing of an integer +to the macro, <kbd>.QUOTE_INDENT</kbd>. The integer represented the +amount by which to multiply the argument passed to +<kbd><a href="#para-indent">PARA_INDENT</a></kbd> +to arrive at an indent for quotes (and blockquotes). +</p> + +<p> +As of version 1.4-b, you can now append a +<a href="definitions.html#unitofmeasure">unit of measure</a> +to the argument passed to <kbd>.QUOTE_INDENT</kbd>, thus +setting an absolute indent, relative to nothing. The old +behaviour is still respected, though; in other words, if you +pass <kbd>.QUOTE_INDENT</kbd> an integer with no unit of measure +appended, the integer represents the amount by which to multiply +<kbd>.PARA_INDENT</kbd> to arrive at an indent for quotes (and +blockquotes). +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +If your PARA_INDENT is 0 (i.e. no indenting of the first line of +paragraphs), you <i>must</i> set a QUOTE_INDENT yourself, with a +unit of measure appended to the argument. Mom has no default for +QUOTE_INDENT if paragraph first lines are not being indented. +</p> +</div> + +<p> +The default value for QUOTE_INDENT is 3 (for +<a href="docprocessing.html#printstyle">PRINTSTYLE <kbd>TYPESET</kbd></a>) +and 2 (for +<a href="docprocessing.html#printstyle">PRINTSTYLE <kbd>TYPEWRITE</kbd></a>). +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +QUOTE_INDENT also sets the indent for +<a href="#blockquote">blockquotes</a>. +</p> +</div> + +<h4 id="always-fullspace-quotes" class="docs" style="margin-top: -.25em;">2. Spacing above and below quotes (typeset only)</h4> + +<p> +If you’d like mom always to put a full linespace above and +below quotes, invoke +<br/> +<span class="pre-in-pp"> + .ALWAYS_FULLSPACE_QUOTES +</span> +with no argument. If you wish to restore mom’s +default behaviour regarding the spacing of quotes (see +<a href="#quote-spacing">above</a>), +invoke the macro with any argument (<kbd>OFF, QUIT, END, X</kbd>...) +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +This macro also sets mom’s spacing policy for +<a href="#blockquote-intro">blockquotes</a>. +</p> +</div> + +<h4 id="underline-quotes" class="docs" style="margin-top: -.25em;">3. Underlining quotes (typewrite only)</h4> + +<p> +By default in +<a href="docprocessing.html#printstyle">PRINTSTYLE TYPEWRITE</a>, +mom underlines quotes. If you’d rather she didn’t, +invoke <kbd>.UNDERLINE_QUOTES</kbd> with any argument (<b>OFF, +QUIT, END, X</b>...) to disable the feature. Invoke it without +an argument to restore mom’s default underlining of +quotes. +</p> + +<p> +If you not only wish that mom not underline +quotes, but also that she set them in italic, you must follow each +instance of QUOTE with the typesetting macro +<a href="typesetting.html#font">FT I</a>. +Furthermore, since mom underlines all instances of +italics by default in <b>PRINTSTYLE TYPEWRITE</b>, you +must also make sure that ITALIC_MEANS_ITALIC is +enabled (see +<a href="docprocessing.html#typewrite-control">PRINTSTYLE TYPEWRITE control macros</a>). +</p> + +<h4 id="break-quote" class="docs">4. Manually break a footnoted quote that crosses pages/columns (deprecated)</h4> + +<div class="box-tip"> +<p class="tip"> +<i>As of version 1.1.9, the macro</i> BREAK_QUOTE <i>became obsolete +(or, at least, should have become obsolete.) It remains here for +backward compatibility with documents created prior to 1.1.9, and +just in case despite my efforts to make it obsolete you still +encounter the problem it’s supposed to fix. Should you find +yourself having to use</i> BREAK_QUOTE <i>while running</i> mom +1.1.9 <i>or higher, please notify me immediately.</i> +</p> +</div> + +<p style="margin-top: -.5em;"> +Exceptionally, a quote or blockquote containing a footnote may +cross a page or column. When this happens, the footnote marker may +not be correct for its position relative to other footnotes on the +page, and the footnote itself may appear on the wrong page or at the +bottom of the wrong column. When this happens, study your output to +determine the precise point at which the quote breaks (or at which +you want it to break), and add +<span class="pre-in-pp"> + .BREAK_QUOTE +</span> +on a line by itself afterwards. No other intervention is required, +and the footnote(s) will be marked correctly and appear on the +correct page. +</p> + +<p> +<kbd>.BREAK_QUOTE</kbd> may be used with both quotes and +blockquotes, and hence is aliased as <kbd>.BREAK_BLOCKQUOTE</kbd>, +<kbd>BREAK_CITATION</kbd> and <kbd>BREAK_CITE</kbd>. +</p> + +<div class="rule-short"><hr/></div> + +<!-- ==================================================================== --> + +<h2 id="blockquote-intro" class="macro-group">Blockquotes (cited material)</h2> + +<ul style="margin-left: -.5em;"> + <li><a href="#blockquote">Tag: BLOCKQUOTE</a></li> + <li><a href="#blockquote-control">BLOCKQUOTE control macros</a></li> +</ul> + +<p> +<a href="definitions.html#blockquote">Blockquotes</a> +are used to cite passages from another author’s work. So that +they stand out well from +<a href="definitions.html#running">running text</a>, +mom indents them from both the left and right margins and sets them +in a different point size +(<a href="docprocessing.html#printstyle">PRINTSTYLE TYPESET</a> +only). +<a href="definitions.html#outputline">Output lines</a> +are +<a href="definitions.html#filled">filled</a>, +and, by default, +<a href="definitions.html#quad">quadded</a> +left. +</p> + +<p> +Besides indenting blockquotes, mom further sets them off from +running text with a small amount of vertical whitespace top and +bottom. (See +<a href="#quote-spacing">above</a> +for a complete explanation of how this is managed, and how +to control it.) +</p> + +<!-- -BLOCKQUOTE- --> + +<div class="macro-id-overline"> +<h3 id="blockquote" class="macro-id">BLOCKQUOTE</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>BLOCKQUOTE</b> <kbd class="macro-args">toggle</kbd> +</div> + +<p class="alias" style="margin-bottom: 0;"> +<i>Aliases: </i> <b>CITE, CITATION</b> +</p> + +<p> +BLOCKQUOTE is a toggle macro. To begin a cited passage, invoke +the tag with no argument, then type in your blockquote. When +you’re finished, invoke <kbd>.BLOCKQUOTE</kbd> with any +argument (e.g. <kbd>OFF, END, X, Q</kbd>...) to turn it off. +Example: +<br/> +<span class="pre-in-pp"> + .BLOCKQUOTE + Redefining the role of the United States from enablers to keep + the peace to enablers to keep the peace from peacekeepers is + going to be an assignment. + .RIGHT + \[em]George W. Bush + .BLOCKQUOTE END +</span> +If the cited passage runs to more than one paragraph, you must +introduce each paragraph—including the first—with +<kbd><a href="#pp">.PP</a></kbd>. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +The aliases CITE and CITATION may be used in place of the BLOCKQUOTE +tag, as well as in any of the control macros that begin or end with +<kbd>BLOCKQUOTE_</kbd>. +</p> +</div> + +<div class="defaults-container" style="background-color: #ded4bd; border: none;"> +<h3 id="blockquote-control" class="docs defaults">BLOCKQUOTE control macros and defaults</h3> + +<ol style="margin-top: .5em; padding-bottom: .5em;"> + <li><a href="#blockquote-general">Family/font/size/leading/colour/quad/indent</a></li> + <li><a href="#bq-always-fullspace-quotes">Spacing above and below (typeset only)</a></li> + <li><a href="#break-quote">Manually break a footnoted blockquote that crosses pages/columns</a></li> +</ol> +</div> + +<h4 id="blockquote-general" class="docs" style="margin-top: -1.5em; margin-bottom: .5em;">1. Family/font/size/colour/quad/indent</h4> + +<div class="defaults-container" style="padding-bottom: 8px;"> +<p class="defaults" style="padding-top: 6px;"> +See +<a href="#control-macro-args">Arguments to the control macros</a>. +</p> +<span class="pre defaults"> +.BLOCKQUOTE_FAMILY default = prevailing document family; default is Times Roman +.BLOCKQUOTE_FONT default = roman +.BLOCKQUOTE_SIZE default = -1 (point) +.BLOCKQUOTE_AUTOLEAD default = none; leading of blockquotes is the same as paragraphs +.BLOCKQUOTE_COLOR default = black +.BLOCKQUOTE_QUAD default = left +.BLOCKQUOTE_INDENT (see below) +</span> +</div> + +<h4 id="blockquote-indent" class="docs" style="margin-top: -1.5em;">Blockquote indent</h4> + +<p> +Prior to version 1.4-b, mom allowed only the passing of an integer +to the macro, BLOCKQUOTE_INDENT. The integer represented the amount +by which to multiply the argument passed to +<kbd><a href="#para-indent">PARA_INDENT</a></kbd> +to arrive at an indent for blockquotes (and quotes). +</p> + +<p> +As of version 1.4-b, you can append a +<a href="definitions.html#unitofmeasure">unit of measure</a> +to the argument passed to <kbd>.BLOCKQUOTE_INDENT</kbd>, thus +setting an absolute indent, relative to nothing. The old +behaviour is still respected, though. In other words, if you pass +<kbd>.BLOCKQUOTE_INDENT</kbd> an integer with no unit of measure +appended, the integer represents the amount by which to multiply +<kbd>.PARA_INDENT</kbd> to arrive at an indent for blockquotes (and +quotes). +</p> + +<p> +The default value for <kbd>.BLOCKQUOTE_INDENT</kbd> is 3 (for +<a href="docprocessing.html#printstyle">PRINTSTYLE <kbd>TYPESET</kbd></a>) +and 2 (for PRINTSTYLE +<a href="docprocessing.html#printstyle">PRINTSTYLE <kbd>TYPEWRITE</kbd></a>). +</p> + +<div class="box-tip"> +<p class="tip-top"> +<span class="note">Note:</span> +If your PARA_INDENT is 0 (i.e. no indenting of the first line of +paragraphs), you must set a BLOCKQUOTE_INDENT yourself, with a +unit of measure appended to the argument. Mom has no default for +BLOCKQUOTE_INDENT if paragraph first lines are not being indented. +</p> + +<p class="tip-bottom"> +<span class="additional-note">Additional note:</span> +BLOCKQUOTE_INDENT also sets the indent for +<a href="#quote">QUOTES</a>. +</p> +</div> + +<h4 id="bq-always-fullspace-quotes" class="docs">2. Spacing above and below blockquotes (typeset only)</h4> + +<p> +If you’d like mom always to put a full linespace above and +below blockquotes, invoke +<br/> +<span class="pre-in-pp"> + .ALWAYS_FULLSPACE_QUOTES +</span> +with no argument. If you wish to restore mom’s default +behaviour regarding the spacing of blockquotes (see +<a href="#quote-spacing">above</a>), +invoke the macro with any argument (<b>OFF, QUIT, END, +X</b>...). +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +This macro also sets mom’s spacing policy for +<a href="#quote-intro">quotes</a>. +</p> +</div> + +<div class="rule-short"><hr/></div> + +<!-- ==================================================================== --> + +<h2 id="code-intro" class="macro-group">Inserting code snippets</h2> + +<ul style="margin-left: -.5em;"> + <li><a href="#code">Tag: CODE</a></li> + <li><a href="#code-control">CODE control macros and defaults</a></li> +</ul> + +<p> +CODE is a convenience macro that facilitates entering code snippets +into documents. Its use is not restricted to documents created +using mom’s document processing macros; it can be used for +“manually” typeset documents as well. +</p> + +<div class="macro-id-overline"> +<h3 id="code" class="macro-id">CODE</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>CODE</b> <kbd class="macro-args">[BR | BREAK | SPREAD] toggle</kbd> +</div> + +<p class="requires" style="font-style: normal"> +Inline escape: <b><kbd>\*[CODE]</kbd></b> +</p> + +<p> +When you invoke <kbd>.CODE</kbd> without an argument, or use the +<a href="definitions.html#inlines">inline escape</a>, +<kbd>\*[CODE]</kbd>, +mom changes the font to a +<a href="definitions.html#fixedwidthfont">fixed-width font</a> +(Courier, by default) and turns +<a href="goodies.html#smartquotes">SMARTQUOTES</a> +off. Additionally, if you invoke <kbd>.CODE</kbd> inside +<a href="#quote">QUOTE</a> +while in +<a href="docprocessing.html#printstyle">PRINTSTYLE <kbd>TYPEWRITE</kbd></a> +with the default underlining of quotes turned on, it disables the +underlining for the duration of CODE. +</p> + +<p> +Passing any argument other than <kbd>BR</kbd>, <kbd>BREAK</kbd> +or <kbd>SPREAD</kbd> to CODE (e.g. <kbd>OFF, QUIT, END, X,</kbd> +etc.) turns CODE off and returns the family, font, smartquotes +and (if applicable) underlining of quotes to their former state. +If you’ve used the inline escape, <kbd>\*[CODE]</kbd>, to +initiate a section of code, <kbd>\*[CODE OFF]</kbd> equally returns +things to their former state. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +If your code snippet includes the backslash character, which is +groff’s escape character, you will have to change the +escape character temporarily to something else with the macro, +<a href="goodies.html#esc-char">ESC_CHAR</a>. +Mom has no way of knowing what special characters you’re going +to use in code snippets, therefore she cannot automatically replace +the escape character with something else. +</p> +</div> + +<div class="box-important"> +<p class="tip-top"> +<span class="important">Important:</span> +<kbd>.CODE</kbd> does not cause a line break when +you’re in a +<a href="definitions.html#filled">fill mode</a> +(i.e. +<a href="typesetting.html#justify">JUSTIFY</a> +or +<a href="typesetting.html#quad">QUAD</a> +<kbd>LEFT, CENTER,</kbd> or <kbd>RIGHT</kbd>). +If you want CODE to deposit a break, invoke <kbd>.CODE</kbd> with +the argument <kbd>BR</kbd> (or <kbd>BREAK</kbd>). If, in addition +to having mom break the line before <kbd>.CODE</kbd>, you want her +to +<a href="definitions.html#force">force justify</a> +it as well, invoke <kbd>.CODE</kbd> with the argument, +<kbd>SPREAD</kbd>. If, in addition to breaking the line before CODE +you want a break afterwards, you must supply it manually with +<a href="typesetting.html#br">BR</a> +unless what follows immeidately is a macro that automatically causes +a break (e.g. +<a href="#pp">PP</a>). +</p> + +<p> +In all likelihood, if you want the situation described above (i.e. a +break before and after CODE), what you probably want is to use +<a href="quote">QUOTE</a> +in conjunction with CODE, like this: +<br/> +<span class="pre-in-pp"> + .QUOTE + .CODE + $ echo "Hello, world" | sed -e 's/Hello,/Goodbye, cruel' + .CODE OFF + .QUOTE OFF +</span> +QUOTE takes care of breaking both the text and the code, as well as +indenting the code and offsetting it from +<a href="definitions.html#running">running text</a> +with vertical whitespace. +</p> + +<p class="tip-bottom"> +<span class="note">Note:</span> +<kbd>BR</kbd>, <kbd>BREAK</kbd> and <kbd>SPREAD</kbd> have no +effect when used with the inline escape, <kbd>\*[CODE]</kbd>. The +assumption behind <kbd>\*[CODE]</kbd> is that you’re inserting +a bit of code into a line, not creating a distinct code block. +</p> +</div> + +<div class="defaults-container" style="background-color: #ded4bd; border: none;"> +<h3 id="code-control" class="docs defaults">CODE control macros and defaults</h3> + +<ol style="margin-top: .5em; padding-bottom: .5em;"> + <li><a href="#code-general">Family/Font/Color</a></li> + <li><a href="#code-size">Size</a></li> +</ol> +</div> + +<h4 id="code-general" class="docs" style="margin-top: -1.5em; margin-bottom: .5em;">1. Family/font/colour</h4> + +<div class="defaults-container" style="padding-bottom: 8px;"> +<p class="defaults" style="padding-top: 6px;"> +See +<a href="#control-macro-args">Arguments to the control macros</a>. +</p> +<span class="pre defaults"> +.CODE_FAMILY default = Courier +.CODE_FONT default = roman; see Note +.CODE_COLOR default = black + +Note: Unlike other control macros, CODE_FONT sets the code font for both +PRINTSTYLE TYPESET and PRINTSTYLE TYPEWRITE. +</span> +</div> + +<h4 id="code-size" class="docs" style="margin-top: -1.25em;">2. Size</h4> + +<p> +CODE_SIZE works a little differently from the other _SIZE macros +(see <a href="#control-macro-args">Arguments to the control +macros</a>). The argument you pass it is a percentage of the +prevailing document point size. It does not require a pre-pended +plus (<kbd>+</kbd>) or minus (<kbd>-</kbd>) sign, nor an appended +percent sign (<kbd>%</kbd>). Thus, is you want the point size of your CODE font to be +90% of the prevailing document point size, you enter: +<br/> +<span class="pre-in-pp"> + .CODE_SIZE 90 +</span> +Fixed-width fonts have notoriously whimsical +<a href="definitions.html#xheight">x-heights</a>, +meaning that they frequently look bigger (or, in some cases, +smaller) than the type surrounding them, even if they're technically +the same point size. CODE_SIZE lets you choose a percentage of the +prevailing point size for your fixed-width CODE font so it doesn't look +gangly or miniscule in relation to the type around it. All +invocations of <kbd>.CODE</kbd> or <kbd>\*[CODE]</kbd> will use this +size, so that if you decide to change the prevailing point size of your +document, the CODE font will be scaled proportionally. +</p> + +<div class="rule-short"><hr/></div> + +<!-- ==================================================================== --> + +<h2 id="list-intro" class="macro-group">Nested lists</h2> + +<ul style="margin-left: -.5em;"> + <li><a href="#list">Tag: LIST</a></li> + <li><a href="#item">Tag: ITEM</a></li> + <li><a href="#list-control">LIST control macros and defaults</a></li> +</ul> + +<p> +Lists are points or items of interest or importance that are +separated from +<a href="definitions.html#running">running text</a> +by enumerators. Some typical enumerators are +<a href="definitions.html#em">en-dashes</a>, +<a href="definitions.html#bullet">bullets</a>, +digits and letters. +</p> + +<p> +Setting lists with mom is easy. First, you initialize a list with +the LIST macro. Then, for every item in the list, you invoke +the macro, <kbd>.ITEM</kbd>, followed by the text of the item. +When a list is finished, you exit the list with +<kbd>.LIST OFF</kbd> (or <kbd>QUIT, END, BACK,</kbd> etc.) +</p> + +<p> +By default mom starts each list with the enumerator flush with the +left margin of running text that comes before it, like this: +<br/> +<span class="pre-in-pp"> + My daily schedule needs organizing. I can’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 +</span> +In other words, mom does not, by default, indent entire lists. +Indenting a list is controlled by the macro, +<a href="#shift-list">SHIFT_LIST</a>. +(This is a design decision; there are too many instances where a +default indent is not desirable.) Equally, mom does not add any +extra space above or below lists. +</p> + +<p> +Lists can be nested (as in the example above). In other words, +you can set lists within lists, each with an enumerator (and +possibly, indent) of your choosing. In nested lists, each +invocation of <kbd>.LIST OFF</kbd> (you may prefer to use +<kbd>.LIST BACK</kbd>) takes you back to the previous depth +(or level) of list, with that list’s enumerator and indent +intact. The final <kbd>.LIST OFF</kbd> exits lists completely +and returns you to the left margin of running text. +</p> + +<p> +Finally, lists can be used in documents created with either the +<a href="docprocessing.html#top">document processing macros</a> +or the +<a href="typesetting.html#top">typesetting macros</a>. +</p> + +<!-- -LIST- --> + +<div class="macro-id-overline"> +<h3 id="list" class="macro-id">LIST</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>LIST</b> <kbd class="macro-args">[ BULLET | DASH | DIGIT | ALPHA | alpha | ROMAN<n> | roman<n> | USER <string>] [ <separator> | <user-defined enumerator> ] [ <prefix> ] [ <off> ]</kbd> +</div> + +<p> +Invoked by itself (i.e. with no argument), LIST +initializes a list (with bullets as the default enumerator). +Afterwards, each block of input text preceded by +<kbd><a href="#item">.ITEM</a></kbd>, +on a line by itself, is treated as a list item. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +Every time you invoke <kbd>.LIST</kbd> to start a list (as opposed to +<a href="#list-exit">exiting one</a>), +you must supply an enumerator (and optionally, a separator) for the +list, unless you want mom’s default enumerator, which is a +bullet. Within nested lists, mom stores the enumerator, separator +and indent for any list you return <i>backwards</i> to (i.e. with +<kbd>.LIST OFF</kbd>), but does not store any information for lists +you move <i>forward</i> to. +</p> +</div> + +<p> +There are a lot of arguments (be sure to side-scroll through them +all, above), so I’ll discuss them one at a time here. +</p> +<h3 class="docs">The first argument – enumerator style</h3> + +<p> +The optional arguments <kbd>BULLET</kbd>, <kbd>DASH</kbd>, +<kbd>DIGIT</kbd> (for Arabic numerals), <kbd>ALPHA</kbd> (for +uppercase letters), <kbd>alpha</kbd> (for lowercase letters), +<kbd>ROMAN<n></kbd> (for uppercase roman numerals), +<kbd>roman<n></kbd> (for lowercase roman numerals) tell +<kbd>mom</kbd> what kind of enumerator to use for a given list. +</p> + +<p> +The arguments, <kbd>ROMAN<n></kbd> and +<kbd>roman<n></kbd>, are special. You must append to them +a digit (arabic, e.g. "1" or "9" or "17") saying how many items a +particular roman-numeralled 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. +</p> + +<p> +A roman-numeralled list containing, say, five items, would be set +up like this: +<br/> +<span class="pre-in-pp"> + .LIST roman5 producing i) Item 1. + .ITEM ii) Item 2. + Item 1. iii) Item 3. + .ITEM iv) Item 4. + Item 2. v) Item 5. + .ITEM + Item 3 + .ITEM + Item 4 + .ITEM + Item 5 +</span> +</p> + +<p> +The argument, <kbd>USER</kbd>, lets you make up your own enumerator, +and must be followed by a second argument: what you’d like the +enumerator to look like. +</p> + +<p> +For example, if you want a list enumerated +with <kbd>=></kbd>, +<br/> +<span class="pre-in-pp"> + .LIST USER => + .ITEM + A list item +</span> + +will produce +<br/> +<span class="pre-in-pp"> + => A list item +</span> +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +If the argument to <kbd>USER</kbd> contains spaces, you must enclose +the argument in double quotes. +</p> +</div> + +<h3 class="docs">The second argument – separator style</h3> + +<p> +If you choose <kbd>DIGIT</kbd>, <kbd>ALPHA</kbd>, <kbd>alpha</kbd>, +<kbd>ROMAN<n></kbd>, or <kbd>roman<n></kbd>, you may +enter the optional argument, <kbd>separator</kbd>, to say what kind +of separator you want after the enumerator. The separator can be +anything you like. The default for <kbd>DIGIT</kbd> is a period +(dot), like this: +<br/> +<span class="pre-in-pp"> + 1. A list item +</span> +The default separator for <kbd>ALPHA</kbd>, <kbd>alpha</kbd>, +<kbd>ROMAN<n></kbd> and <kbd>roman<n></kbd> is a right +parenthesis, like this: +<br/> +<span class="pre-in-pp"> + a) An alpha-ed list item + b) A second alpha-ed list item +</span> +If you’d prefer, say, digits with right-parenthesis separators +instead of the default period, you’d do +<br/> +<span class="pre-in-pp"> + .LIST DIGIT ) + .ITEM + A numbered list item +</span> +which would produce +<br/> +<span class="pre-in-pp"> + 1) A numbered list item +</span> +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +<kbd>BULLET</kbd>, <kbd>DASH</kbd> and <kbd>USER</kbd> do not take a +separator. +</p> +</div> + +<h3 class="docs">The third argument – prefix style</h3> + +<p> +Additionally, you may give a prefix (i.e. a character +that comes <i>before</i> the enumerator) when your +enumerator style for a particular list is <kbd>DIGIT</kbd>, +<kbd>ALPHA</kbd>, <kbd>alpha</kbd>, <kbd>ROMAN<n></kbd> or +<kbd>roman<n></kbd>. In the arguments to LIST, the prefix +comes <i>after</i> the separator, which is counter-intuitive, +so please be careful. +</p> + +<p> +A prefix can be anything you like. Most likely, you’ll want +some kind of open-bracket, such as a left parenthesis. If, for +example, you want a <kbd>DIGIT</kbd> list with the numbers enclosed +in parentheses, you’d enter +<br/> +<span class="pre-in-pp"> + .LIST DIGIT ) ( + .ITEM + The first item on the list. + .ITEM + The second item on the list. +</span> +which would produce +<br/> +<span class="pre-in-pp"> + (1) The first item on the list. + (2) The second item on the list. +</span> +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +<kbd>BULLET</kbd>, <kbd>DASH</kbd> and +<kbd>USER</kbd> do not take a prefix. +</p> +</div> + +<h3 class="docs">Exiting lists – LIST OFF/BACK or QUIT_LISTS</h3> + +<p> +Any single argument to <kbd>LIST</kbd> other than +<kbd>BULLET</kbd>, <kbd>DASH</kbd>, <kbd>DIGIT</kbd>, +<kbd>ALPHA</kbd>, <kbd>alpha</kbd>, <kbd>ROMAN<n></kbd>, +<kbd>roman<n></kbd> or <kbd>USER</kbd> (e.g. +<kbd>LIST OFF</kbd> or <kbd>LIST BACK</kbd>) takes you out +of the current list. +</p> + +<p> +If you are at the first list-level (or list-depth), mom returns you +to the left margin of running text. Any indents that were in effect +prior to setting the list are fully restored. +</p> + +<p> +If you are in a nested list, mom moves you back one list-level +(i.e. does not take you out of the list structure) and restores the +enumerator, separator and indent appropriate to that level. +</p> + +<p> +Each invocation of <kbd>.LIST</kbd> should thus be be matched by +a corresponding <kbd>.LIST OFF</kbd> in order to fully exit +lists. For example, +<br/> +<span class="pre-in-pp"> + Lorem ipsum dolor sit amet, consetetur sadipscing elitr, + sed diam nonumy eirmod tempor invidunt ut labore. + o List item in level 1 + o List item in level 1 + - List item in level 2 + - List item in level 2 + Lorem ipsum dolor sit amet, consetetur sadipscing elitr, + sed diam nonumy eirmod tempor invidunt ut labore. +</span> +is created like this: +<br/> +<span class="pre-in-pp"> + Lorem ipsum dolor sit amet, consetetur sadipscing elitr, + sed diam nonumy eirmod tempor invidunt ut labore. + .LIST BULLET + .ITEM + List item in level 1 + .ITEM + List item in level 1 + .LIST DASH + .ITEM + List item in level 2 + .ITEM + List item in level 2 + .LIST OFF \" Turn level 2 list off + .LIST OFF \" Turn level 1 list off + Lorem ipsum dolor sit amet, consetetur sadipscing elitr, + sed diam nonumy eirmod tempor invidunt ut labore. +</span> +</p> + +<p> +Alternatively, you may use the single-purpose macro, +<kbd>.QUIT_LISTS</kbd>, to get yourself out of a list structure. In +the example above, the two <kbd>.LIST OFF</kbd> lines could be +replaced with a single <kbd>.QUIT_LISTS</kbd>. +</p> + +<div class="macro-id-overline"> +<h3 id="item" class="macro-id">ITEM</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>ITEM</b> +</div> + +<p> +After you’ve initialized a list with +<a href="#list">LIST</a>, +precede each item you want in the list with <kbd>.ITEM</kbd>. Mom +takes care of everything else with respect to setting the item +appropriate to the list you’re in. +</p> + +<p> +In document processing, it is valid to have list items that contain +multiple paragraphs. Simply issue a +<kbd><a href="#pp">.PP</a></kbd> +request for each paragraph <i>following</i> the first item. +I.e., don’t do this: +<br/> +<span class="pre-in-pp"> + .ITEM + .PP + Some text... + .PP + A second paragraph of text +</span> +but rather +<br/> +<span class="pre-in-pp"> + .ITEM + Some text... + .PP + A second paragraph of text +</span> +</p> + +<div class="defaults-container" style="background-color: #ded4bd; border: none;"> +<h3 id="list-control" class="docs defaults">LIST control macros and defaults</h3> + +<ol style="margin-top: .5em; padding-bottom: .5em;"> + <li><a href="#shift-list">Indenting lists (SHIFT_LIST)</a></li> + <li><a href="#reset-list">Resetting an initialized list’s enumerator (RESET_LIST)</a></li> + <li><a href="#pad-list-digits">Padding digit enumerators (PAD_LIST_DIGITS)</a></li> +</ol> +</div> + +<h4 id="shift-list" class="docs" style="margin-top: -1.5em;">1. Indenting lists – SHIFT_LIST</h4> + +<p> +If you want a list to be indented to the right of running text, or +indented to the right of a current list, use the macro SHIFT_LIST +immediately after +<a href="#list">LIST</a>. +SHIFT_LIST takes just one argument: the amount by which you want the +list shifted to the right. The argument requires a +<a href="definitions.html#unitofmeasure">unit of measure</a>. +</p> + +<p> +SHIFT_LIST applies only to the list you just initialized with LIST. +It does not carry over from one invocation of LIST to the next. +However, the indent remains in effect when you return to a list +level in a nested list. +</p> + +<p> +For example, if you want a 2-level list, with each list indented to +the right by 18 +<a href="definitions.html#picaspoints">points</a>, +<br/> +<span class="pre-in-pp"> + Lorem ipsum dolor sit amet, consetetur sadipscing elitr, + sed diam nonumy eirmod tempor invidunt ut labore. + .LIST \" List 1 + .SHIFT_LIST 18p \" Indent 18 points right of running text + .ITEM + List 1 item + .ITEM + List 1 item + .LIST DASH \" List 2 + .SHIFT_LIST 18p \" Indent 18 points right of list 1 + .ITEM + List 2 item + .ITEM + List 2 item + .LIST OFF \" Move back to list 1 + .ITEM + List 1 item + .ITEM + List 1 item + .LIST OFF \" Exit lists + Lorem ipsum dolor sit amet, consetetur sadipscing elitr, + sed diam nonumy eirmod tempor invidunt ut labore. +</span> +produces (approximately) +<br/> +<span class="pre-in-pp"> + Lorem ipsum dolor sit amet, consetetur sadipscing elitr, + sed diam nonumy eirmod tempor invidunt ut labore. + o List 1 item + o List 1 item + - List 2 item + - List 2 item + o List 1 item + o List 1 item + Lorem ipsum dolor sit amet, consetetur sadipscing elitr, + sed diam nonumy eirmod tempor invidunt ut labore. +</span> +</p> + +<h4 id="reset-list" class="docs" style="margin-top: -.25em;">2. Resetting an initialized list’s enumerator – RESET_LIST</h4> + +<p> +In nested lists, if your choice of list enumerator for a given level +of list is <kbd>DIGIT</kbd>, <kbd>ALPHA</kbd>, <kbd>alpha</kbd>, +<kbd>ROMAN</kbd> or <kbd>roman</kbd>, you may sometimes want to +reset the list’s enumerator when you return to that list. +Consider the following: +<br/> +<span class="pre-in-pp"> + Things to do religiously each and every day: + 1. Take care of the dog + a) walk every day + b) brush once a week + - trim around the eyes every fourth brushing + - don’t forget to check nails + 2. Feed the cat + a) soft food on Mon., Wed. and Fri. + b) dry food on Tues., Thurs. and Sat. + c) canned tuna on Sunday +</span> +</p> + +<p> +Normally, within a nested list, when you return to an +incrementally-enumerated list, the enumerator continues incrementing +from where it left off. That means, in the example above, the +normal state of affairs for the alpha'ed list under +<br/> +<span class="pre-in-pp"> + 2. Feed the cat +</span> +would be d), e) and f). The solution, in such a case, is simply +to reset the enumerator—before <kbd>.ITEM</kbd>—with +the macro, <kbd>.RESET_LIST</kbd>. By default, with no argument, +<kbd>.RESET_LIST</kbd> resets the enumerator to 1, A, a, I or i +depending on the style of enumerator. You may, if you wish, pass +<kbd>.RESET_LIST</kbd> a +<a href="definitions.html#numericargument">numeric argument</a> +representing the starting enumerator for the reset (if different +from "1"), although I can’t at present think of a use for this +feature. +</p> + +<h4 id="pad-list-digits" class="docs" style="margin-top: -.25em;">3. Padding digit enumerators – PAD_LIST_DIGITS</h4> + +<h5 class="docs" style="margin-top: 1em;">Arabic digits</h5> + +<p style="margin-top: .5em;"> +When your choice of enumerators is DIGIT and the number of items +in the list exceeds nine (9), you have to make a design decision: +should mom leave room for the extra numeral in two-numeral digits to +the right or the left of the single-numeral digits? +</p> + +<p> +If you want the extra space to the right, invoke the macro, +<kbd>.PAD_LIST_DIGITS</kbd> (with no argument), after +<kbd>.LIST</kbd> and before <kbd>.ITEM</kbd>. This will produce +something like +<br/> +<span class="pre-in-pp"> + 8. List item + 9. List item + 10. List item +</span> +If you want the extra space to the left, invoke +<kbd>.PAD_LIST_DIGITS</kbd> with the single argument, +<kbd>LEFT</kbd>, which will produce +<br/> +<span class="pre-in-pp"> + 8. List item + 9. List item + 10. List item +</span> +</p> + +<p> +Of course, if the number of items in the list is less than ten +(10), there’s no need for PAD_LIST_DIGITS. +</p> + +<h5 class="docs" style="margin-top: -.5em;">Roman numerals</h5> + +<p style="margin-top: .5em;"> +By default, mom sets roman numerals in lists flush left. The +<kbd><n></kbd> argument appended to <kbd>ROMAN<n></kbd> +or <kbd>roman<n></kbd> allows her to calculate how much space +to put after each numeral in order to ensure that the text of items +lines up properly. +</p> + +<p> +If you’d like the roman numerals to line +up flush right (i.e. be padded "left"), simply +invoke <kbd>.PAD_LIST_DIGITS LEFT</kbd> after +<kbd>.LIST ROMAN<n></kbd> or +<kbd>.LIST roman<n></kbd> and before <kbd>.ITEM</kbd>. +</p> + +<div class="rule-short"><hr/></div> + +<!-- -LINE NUMBERING- --> + +<h2 id="number-lines-intro" class="macro-group">Line numbering – prepend numbers to output lines</h2> + +<ul style="margin-left: -.5em;"> + <li><a href="#number-lines">Macro: <b>NUMBER_LINES</b></a> + <ul style="margin-left: -.5em;"> + <li><a href="#ln-control">Line numbering control (off/suspend, resume)</a></li> + </ul></li> + <li><a href="#number-lines-control">Control macros and defaults</a> + <ul style="margin-left: -.5em;"> + <li><a href="#number-lines-control-quote">Line numbering control macros for quotes and blockquotes</a></li> + </ul></li> +</ul> + +<p style="margin-top: -.5em;"> +When you turn line-numbering on, mom, by default +</p> +<ul style="margin-top: -.5em;"> + <li>numbers every line of paragraph text; line-numbering is + suspended for all other document processing tags (like + docheaders, epigraphs, heads, subheads, etc.) and special + pages (covers, endotes, bibliographies, etc.); be aware, + though, that if you turn + <a href="definitions.html#docheader">docheaders</a> + off (with + <a href="docprocessing.html#docheader">DOCHEADER</a> OFF) + and create your own docheader, mom + <i>will</i> line-number your custom docheader + </li> + <li>doesn’t touch your line length; line numbers are hung + outside your current left margin (as set with + <a href="typesetting.html#l-margin">L_MARGIN</a>, + <a href="typesetting.html#page">PAGE</a> + or + <a href="docprocessing.html#doc-left-margin">DOC_LEFT_MARGIN</a>), + regardless of any indents that may be active + </li> + <li>separates line numbers from running text by two + <a href="definitions.html#figurespace">figure spaces</a>. + </li> +</ul> + +<p> +Line numbering may be enabled and disabled for +<kbd><a href="#quote">QUOTE</a></kbd> +and/or +<kbd><a href="#blockquote">BLOCKQUOTE</a></kbd> +in one of three styles. See +<a href="#number-lines-control-quote">Line numbering control macros for quotes and blockquotes</a>. +</p> + +<!-- -NUMBER_LINES- --> + +<div class="macro-id-overline"> +<h3 id="number-lines" class="macro-id">NUMBER_LINES</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>NUMBER_LINES</b> <kbd class="macro-args"><start number> [ <which lines to number> [ <gutter> ] ]</kbd> +</div> + +<div class="box-macro-args" style="margin-top: 1em;"> +Macro: <b>NUMBER_LINES</b> <kbd class="macro-args"><anything> | RESUME</kbd> +</div> + +<p> +NUMBER_LINES does what it says: prints line numbers, to the left of +<a href="definitions.html#outputline">output lines</a> +of paragraph text. One of the chief reasons for wanting numbered +lines is in order to identify footnotes or endnotes by line number +instead of by a marker in the text. (See +<a href="#footnote-linenumbers">FOOTNOTE_MARKER_STYLE LINE</a> +for instructions on line-numbered footnotes, and +<a href="#endnote-marker-style">ENDNOTE_MARKER_STYLE</a> +for instructions on line-numbered endnotes.) +</p> + +<p> +The first time you invoke +<a href="#number-lines">NUMBER_LINES</a> +you must, at a minimum, tell it what line number you want the +<i>next</i> +<a href="definitions.html#outputline">output line</a> +to have. The optional arguments which <kbd>lines to number</kbd> +and <kbd>gutter</kbd> allow you to state which lines should +be numbered (e.g. every five or every ten lines), and the gutter to +place between line numbers and +<a href="definitions.html#running">running text</a>. +</p> + +<p> +For example, if you want mom to number output lines using her defaults, +<span class="pre-in-pp"> + .NUMBER_LINES 1 +</span> +will prepend the number, 1, to the next output line and number all +subsequent output lines sequentially. +</p> + +<p> +If you want only every five lines numbered, pass mom the optional +<kbd>which lines to number</kbd> argument, like this: +<span class="pre-in-pp"> + .NUMBER_LINES 1 5 +</span> +</p> + +<div class="box-important"> +<p class="tip-top"> +<span class="important">GOTCHA!</span> +The argument to <kbd><which lines to number></kbd> instructs +mom to number only those lines that are multiples of the argument. +Hence, in the above example, line number <kbd>1</kbd> will +<i>not</i> be numbered, since <kbd>1</kbd> is not a multiple of +<kbd>5</kbd>. +</p> + +<p> +If you want line number <kbd>1</kbd> to be numbered, you have to +invoke <kbd>.NUMBER_LINES 1 1</kbd> before the first output line +you want numbered, then study your <i>output</i> copy and determine +where best to insert the following in your <i>input</i> input text: +<br/> +<span class="pre-in-pp"> + .NUMBER_LINES \n[ln] 5 +</span> +(The escape, <kbd>\n[ln]</kbd>, ensures that NUMBER_LINES +automatically supplies the correct value for the first argument, +<kbd><start number></kbd>.) +</p> + +<p class="tip-bottom"> +Following this recipe, line number <kbd>1</kbd> will be numbered; +subsequently, only line numbers that are multiples of 5 will be +numbered. A little experimentation may be required to determine the +best place for it in your input text. +</p> +</div> + +<p> +The optional argument, <kbd><gutter></kbd>, tells mom how much +space to put between the line numbers and the running text. +<kbd><gutter></kbd> does not require (or even accept) a +<a href="definitions.html#unitofmeasure">unit of measure</a>. +The argument you pass to it is the number of +<a href="definitions.html#figurespace">figure spaces</a> +you want between line numbers and running text. +Mom’s default gutter is two figure spaces. If +you’d like a wider gutter, say, four figures spaces, you’d do +<br/> +<span class="pre-in-pp"> + .NUMBER_LINES 1 1 4 + | + +-- Notice you *must* supply a value + for the 2nd argument in order to supply + a value for the 3rd. +</span> +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +When giving a value for <kbd><gutter></kbd>, you cannot skip +the <kbd><which lines to number></kbd> argument. Either fill +in the desired value, or use two double-quotes ( <kbd>""</kbd> ) to +have mom use the value formerly in effect. +</p> +</div> + +<h3 id="ln-control" class="docs" style="margin-top: -.5em;">Off/suspend, resume</h3> + +<p style="margin-top: .5em;"> +After initializing line numbering, you can suspend it, with the +option to resume, using +<br/> +<span class="pre-in-pp"> + .NUMBER_LINES OFF +</span> +(or <kbd>END, QUIT, X,</kbd> etc). +</p> + +<p>To resume line numbering: +<br/> +<span class="pre-in-pp"> + .NUMBER_LINES RESUME +</span> +When you resume, the line number will be the next in sequence +from where you left off. If that is not what you want—say +you want to reset the line number to <kbd>1</kbd>—re-invoke +<kbd>.NUMBER_LINES</kbd> with whatever arguments are needed for the +desired result. +</p> + +<div class="box-tip" style="margin-left: 6px;"> +<p class="tip"> +<span class="note">Additional notes:</span> +</p> +<ol style="margin-top: -1.25em; margin-left: -1.25em; padding-bottom: .5em;"> + <li>In document processing, you may invoke + <kbd>.NUMBER_LINES</kbd> either before or after + <kbd>.START</kbd>. Mom doesn’t care. + </li> + <li style="margin-top: .25em;">If you’re collating documents with + <a href="rectoverso.html#collate">COLLATE</a>, + you should re-invoke, at a minimum, + <kbd>.NUMBER_LINES 1</kbd> for each collated + document, in order to ensure that each begins with the + number, <kbd>1</kbd>, prepended to the first line. + </li> + <li style="margin-top: .25em;">Occasionally, you may want to + change the current gutter between line numbers and running + text without knowing what the next output line number should + be. Since NUMBER_LINES requires this number as its first + argument, in such instances, pass NUMBER_LINES as its first + argument the escape + <kbd>\n[ln]</kbd>. + <br/> + <span style="display: block; margin-top: .5em;">For example, if you were numbering every 5 lines with a + gutter of 2 (figure spaces) and you needed to change the + gutter to 4 (figures spaces), + <br/> + <span class="pre-in-pp" style="margin-bottom: -2em;"> + .NUMBER_LINES \n[ln] 5 4 + </span> + would do the trick. + </span> + </li> + <li style="margin-top: .25em;">If you’re using + <a href="#mn-intro">margin notes</a> + in a document, be sure to set the gutter for margin notes wide + enough to allow room for the line numbers. + </li> + <li style="margin-top: .25em;">Mom (groff, actually), only numbers + lines <i>to the left</i> of running text. For aesthetic + reason, therefore, the use of line numbering when setting a + document in columns is discouraged. However, should you wish + to number lines when setting in columns, make sure the + <a href="definitions.html#gutter">gutter(s)</a> + between columns is wide enough to leave room for the numbers. + </li> +</ol> +</div> + +<div class="defaults-container" style="background-color: #ded4bd; border: none;"> +<h3 id="number-lines-control" class="docs defaults">NUMBER_LINES control macros and defaults</h3> + +<ol style="margin-top: .5em; padding-bottom: .5em;"> + <li><a href="#number-lines-general">Family/font/size/colour</a></li> + <li><a href="#number-lines-control-quote">Line numbering control for quotes and blockquotes</a> + <ul style="margin-left: -.75em; list-style-type: disc;"> + <li><a href="#number-quote-lines">Number QUOTE lines</a></li> + <li><a href="#number-blockquote-lines">Number BLOCKQUOTE lines</a></li> + <li><a href="#number-lines-control-case">Numbering QUOTE and BLOCKQUOTE lines on a case by case basis</a></li> + </ul></li> +</ol> +</div> + +<h4 id="number-lines-general" class="docs" style="margin-top: -1.5em; margin-bottom: .5em;">1. Family/font/size/colour</h4> + +<div class="defaults-container" style="padding-bottom: 8px;"> +<p class="defaults" style="padding-top: 6px;"> +See +<a href="#control-macro-args">Arguments to the control macros</a>. +</p> +<span class="pre defaults"> +.LINENUMBER_FAMILY default = prevailing family or document family; default is Times Roman +.LINENUMBER_FONT default = prevailing font +.LINENUMBER_SIZE default = +0 +.LINENUMBER_COLOR default = black +</span> +</div> + +<h4 id="number-lines-control-quote" class="docs" style="margin-top: -1.75em;">2. Line numbering control macros for QUOTE and BLOCKQUOTE</h4> + +<h5 id="number-quote-lines" class="docs" style="margin-top: 1em;">Number QUOTE lines</h5> + +<p> +If you’d like mom to number lines of output text +in a +<a href="#quote">QUOTE</a> +as part of the same order and sequence as paragraph text, simply +invoke +<span class="pre-in-pp"> + .NUMBER_QUOTE_LINES +</span> +by itself. +</p> + +<p> +There is a catch with numbering quotes, though. Owing to groff’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 <kbd><gutter></kbd> argument. +</p> + +<p> +If you’d like to change the gutter for quotes line-numbered in +this way, invoke <kbd>.NUMBER_QUOTE_LINES</kbd> with a digit +representing the number of +<a href="definitions.html#figurespace">figure spaces</a> +you’d like between the line numbers and the quoted text, like this: +<br/> +<span class="pre-in-pp"> + .NUMBER_QUOTE_LINES 1 +</span> +With the above, line numbers in quotes (and only quotes) will have +a gutter of 1 figure space. +</p> + +<p> +If you’re using "line numbering style" for footnotes +(<a href="#footnote-marker-style">FOOTNOTE_MARKER_STYLE <kbd>LINE</kbd>)</a>, +you may not wish to have quotes <i>visibly</i> line-numbered, but +still want to embed footnotes inside quotes. In order to do that, +mom allows you to say +<span class="pre-in-pp"> + .NUMBER_QUOTE_LINES SILENT +</span> +When you invoke <kbd>.NUMBER_QUOTE_LINES SILENT</kbd>, +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 <i>suspending</i> +incrementing of line numbers during the output of quotes.) This +allows you to embed line-numbered footnotes inside quotes and have +the line number label in the footnote come out sensibly. +</p> + +<p> +Once having turned NUMBER_QUOTE_LINES on, you may disable it with +<span class="pre-in-pp"> + .NUMBER_QUOTE_LINES OFF +</span> +(or <kbd>QUIT, END, X,</kbd> etc). +</p> + +<h5 id="number-blockquote-lines" class="docs">Number BLOCKQUOTE lines</h5> + +<p> +If you’d like mom to number lines of output text +in a +<a href="#quote">BLOCKQUOTE</a> +as part of the same order and sequence as paragraph text, simply +invoke +<span class="pre-in-pp"> + .NUMBER_BLOCKQUOTE_LINES +</span> +by itself. +</p> + +<p> +There is a catch with numbering blockquotes, though. Owing to +groff’s restriction of accepting only the figure space as the +line number gutter’s unit of measure, it is not possible for line +numbers in blockquotes to hang outside a document’s overall left +margin and be reliably flush with the line numbers of paragraph +text. Conseqently, line numbers in blockquotes hang to the +left of the blockquote, separated from the blockquote by the +<kbd><gutter></kbd> argument. +</p> + +<p> +If you’d like to change the gutter for blockquotes line-numbered in +this way, invoke +<span class="pre-in-pp"> + .NUMBER_BLOCKQUOTE_LINES +</span> +with a digit representing the number of +<a href="definitions.html#figurespace">figure spaces</a> +you’d like between the line numbers and the blockquoted text, like +this: +<br/> +<span class="pre-in-pp"> + .NUMBER_BLOCKQUOTE_LINES 1 +</span> + +With the above, line numbers in blockquotes (and only blockquotes) +will have a gutter of 1 figure space. +</p> + +<p> +If you are using "line numbering style" for footnotes +(<a href="#footnote-marker-style">FOOTNOTE_MARKER_STYLE <kbd>LINE</kbd>)</a>, +you may not wish to have blockquotes <i>visibly</i> line-numbered, +but still want to embed footnotes inside blockquotes. In order to +do that, mom allows you to say +<span class="pre-in-pp"> + .NUMBER_BLOCKQUOTE_LINES SILENT +</span> +When you invoke <kbd>.NUMBER_BLOCKQUOTE_LINES SILENT</kbd>, +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 <i>suspending</i> +incrementing of line numbers during the output of blockquotes.) +This allows you to embed line-numbered footnotes inside blockquotes +and have the line number label in the footnote come out sensibly. +</p> + +<p> +Once having turned NUMBER_BLOCKQUOTE_LINES on, you may disable it +with +<span class="pre-in-pp"> + .NUMBER_BLOCKQUOTE_LINES OFF +</span> +(or <kbd>QUIT, END, X,</kbd> etc). +</p> + +<h4 id="number-lines-control-case" class="docs" style="margin-top: -.25em;">3. Numbering QUOTE and BLOCKQUOTE lines on a case by case basis</h4> + +<p> +Sometimes, you may want quotes or blockquotes to have a different +line numbering scheme from the one used in the rest of the document. +Or, you may want line numbering enabled only inside a particular +quote or blockquote. A common reason for this would be if you were +using the +<a href="#quote">QUOTE</a> +macro to insert lines of programming code into a document. +</p> + +<p> +To enable line numbering within quotes or blockquotes on a case by +case basis, simply invoke +<a href="#number-lines">NUMBER_LINES</a> +with the arguments you need immediately after entering +<kbd><a href="#quote">.QUOTE</a></kbd> +or +<kbd><a href="#blockquote">.BLOCKQUOTE</a></kbd>. +(<a href="number-quote-lines">NUMBER_QUOTE_LINES</a> +and/or +<a href="number-blockquote-lines">NUMBER_BLOCKQUOTE_LINES</a> +should be turned off if you’re doing this.) The quote +or blockquote will then be line-numbered according to your +specifications: the starting line number of the quote or blockquote +will be the one you give as a first argument to NUMBER_LINES; which +lines to number will be the value you pass to <kbd>which lines +to number</kbd> (defaults to <kbd>1</kbd>); line numbers will +hang to the left of the quote or blockquote, separated from the +quote or blockquote by <kbd>gutter</kbd> (defaults to <kbd>2</kbd>). +</p> + +<p> +As soon as QUOTE or BLOCKQUOTE is turned off, line numbering ceases, +not only with respect to subsequent paragraph text (if they are +not being line-numbered), but also for any subsequent invocation +of <kbd>.QUOTE</kbd> or <kbd>.BLOCKQUOTE</kbd>. In other words, +you must re-enable quote or blockquote line-numbering inside every +instance of QUOTE or BLOCKQUOTE when line-numbering either of them +on a case by case basis. +</p> + +<div class="rule-short"><hr/></div> + +<!-- ==================================================================== --> + +<h2 id="footnote-intro" class="macro-group">Footnotes</h2> + +<ul> + <li><a href="#footnote-behaviour">Footnote behaviour</a> + <ul style="margin-left: -.5em;"> + <li><a href="#fn-and-punct">Footnote markers and punctuation in the running text</a></li> + </ul></li> + <li><a href="#footnote">Tag: FOOTNOTE</a></li> + <li><a href="#footnote-control">Footnote control macros and defaults</a></li> +</ul> + +<p> +For something so complex behind the scenes, footnotes are easy to use. +You just type, for example, +<br/> +<span id="footnote-example" class="pre-in-pp"> + ...the doctrines of Identity as urged by Schelling\c + .FOOTNOTE + <footnote about who the hell is Schelling> + .FOOTNOTE OFF + were generally the points of discussion presenting the most + of beauty to the imaginative Morella. +</span> +and be done with it. +(Note the obligatory use of the <kbd>\c</kbd> +<a href="definitions.html#inlines">inline escape</a>, +required whenever your +<a href="#footnote-marker-style">FOOTNOTE_MARKER_STYLE</a> +is either <kbd>STAR</kbd> [star/dagger footnotes] or +<kbd>NUMBER</kbd> [superscript numbers].) +</p> + +<p> +After you invoke <kbd>.FOOTNOTE</kbd>, mom takes care of everything: +putting footnote markers in the body of the document, keeping track +of how many footnotes are on the page, identifying the footnotes +themselves appropriately, balancing them properly with the bottom +margin, deferring footnotes that don’t fit on the page... +Even if you’re using +<a href="docprocessing.html#columns">COLUMNS</a>, +mom knows what to do, and Does The Right Thing. +</p> + +<p> +Footnotes can be sly little beasts, though. If you’re writing +a document that’s footnote-heavy, you might want to read the +following. +</p> + +<h3 id="footnote-behaviour" class="docs">Footnote behaviour</h3> + +<p> +By default, mom marks footnotes with alternating stars (asterisks), +daggers, and double-daggers. The first footnote gets a star, the +second a dagger, the third a double-dagger, the fourth two stars, +the fifth two daggers, etc. If you prefer numbered footnotes, rest +assured mom is happy to oblige. +</p> + +<p> +A small amount of vertical whitespace and a short horizontal rule +separate footnotes from the document body. The amount of whitespace +varies slightly from page to page depending on the number of lines +in the footnotes. Mom tries for a nice balance between too little +whitespace and too much, but when push comes to shove, she’ll +usually opt for ample over cramped. The last lines of footnotes are +always flush with the document’s bottom margin. +</p> + +<p> +If mom sees that a portion of a footnote cannot be fit on its page, +she carries that portion over to the next page. If an entire +footnote can’t be fit on its page (i.e. FOOTNOTE has been +called too close to the bottom), she defers the footnote to the next +page, but sets it with the appropriate marker from the previous +page. +</p> + +<p> +When footnotes occur within cited text, for example a +<a href="#quote">QUOTE</a> +or a +<a href="#blockquote">BLOCKQUOTE</a>, +mom will usually opt for deferring the footnote over to the next +page if it allows her to complete the cited text on one page. +</p> + +<p> +In the unfortunate happenstance that a deferred footnote is the +only footnote on its page (i.e. it’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. +</p> + +<p> +In the circumstance where a deferred footnote is not the only one +on its page, and is consequently marked by something other than +a single star, there’s no confusion and 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). +</p> + +<p> +Very exceptionally, two footnotes may have to be deferred (e.g. one +occurs on the second to last line of a page, and another on the last +line). In such a circumstance, mom does not add +a blank after the second deferred footnote. If you’d like a blank +line separating both deferred footnotes from any footnotes proper to +the page the deferred ones were moved to, add the space manually by +putting a +<a href="typesetting.html#space"><kbd>.SPACE</kbd></a> +command at the end of the footnote text, before +<kbd>.FOOTNOTE OFF</kbd> (or <kbd>X, QUIT, EXIT</kbd>, etc). +</p> + +<p> +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. +</p> + +<p> +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 +<a href="#head">HEAD</a> +near the bottom of a page and the page has some footnotes on it, mom +may simply not have room to set any text under the head (normally, +she insists on having room for at least one line of text beneath +a head). In such an instance, mom will either set the head, with +nothing under it but footnotes, or transfer the head to the next +page. Either way, you’ll have a gaping hole at the bottom +of the page. It’s a sort of typographic Catch-22, and can +only be resolved by you, the writer or formatter of the document, +adjusting the type on the offending page so as to circumvent the +problem. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +Exceptionally, you may encounter problems +with footnotes inside quotes and blockquotes that cross a page or +column. See +<a href="#break-quote">BREAK_QUOTE</a> +for a solution. +</p> +</div> + +<h3 id="fn-and-punct" class="docs">Footnote markers and punctuation in the running text</h3> + +<ol style="margin-left: -1.25em;"> + <li><a href="#fn-and-punct-fill">“Fill” modes – JUSTIFY, or QUAD LEFT | CENTER | RIGHT</a></li> + <li><a href="#fn-and-punct-nofill">“No-fill” modes – LEFT, CENTER, RIGHT</a></li> +</ol> + +<h4 id="fn-and-punct-fill" class="docs">1. “Fill” modes – JUSTIFY, or QUAD LEFT | CENTER | RIGHT</h4> + +<p> +In +<a href="definitions.html#filled">fill</a> +modes, the correct way to enter the line after +<kbd>.FOOTNOTE OFF</kbd> is to input it as if it’s +literally a continuation of the input line you were entering before +you invoked <kbd>.FOOTNOTE</kbd>. Therefore, if necessary, the +input line may have to begin with space(s) or a punctuation mark, as +in the two following examples. +</p> + +<div id="examples-footnotes-1" class="examples-container" style="padding-bottom: 1em;"> +<div class="examples" style="margin-top: 0; margin-bottom: -.25em;">Example 1</div> +<span class="pre"> +A line of text,\c +.FOOTNOTE +A footnote line. +.FOOTNOTE OFF + broken up with a comma. +^ +(last line begins with a literal space) +</span> +</div> + +<div id="examples-footnotes-2" class="examples-container" style="margin-top: 1em; padding-bottom: 1em;"> +<div class="examples" style="margin-top: 0; margin-bottom: -.25em;">Example 2</div> +<span class="pre"> +A line of text\c +.FOOTNOTE +A footnote line. +.FOOTNOTE OFF +, broken up with a comma. +^ +(last line begins with a comma and a space) +</span> +</div> + +<p> +Example 1 produces, on output +<br/> +<span class="pre-in-pp"> + A line of text,* broken up with a comma. +</span> +Example 2 produces +<br/> +<span class="pre-in-pp"> + A line of text*, broken up with a comma. +</span> +Care must be taken, though, if the punctuation mark that begins the +line after <kbd>.FOOTNOTE OFF</kbd> is a period (dot). You +<b><i>must</i></b> begin such lines with <kbd>\&.</kbd>, like +this: +<br/> +<span class="pre-in-pp"> + ...end of sentence\c + .FOOTNOTE + A footnote line. + .FOOTNOTE OFF + \&. A new sentence... +</span> +If you omit the <kbd>\&.</kbd>, the line will vanish! +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +The document element tags, +<a href="#epigraph">EPIGRAPH</a> +and +<a href="#blockquote">BLOCKQUOTE</a>, +imply a fill mode, therefore these instructions also apply when you +insert a footnote into epigraphs or blockquotes. +</p> +</div> + +<h4 id="fn-and-punct-nofill" class="docs">2. “No-fill” modes – LEFT, CENTER, RIGHT</h4> + +<p> +In +<a href="definitions.html#filled">no-fill</a> +modes, you must decide a) whether text on the <i>input</i> line +after <kbd>.FOOTNOTE OFF</kbd> is to be joined to the +<i>output</i> line before <kbd>.FOOTNOTE</kbd> was invoked, or b) +whether you want the <i>output</i> text to begin on a new line. +</p> + +<p> +In the first instance, simply follow the instructions, +<a href="#fn-and-punct-fill">above</a>, +for fill modes. +</p> + +<p> +In the second instance, you must explicitly tell mom that +you want input text after <kbd>.FOOTNOTE OFF</kbd> to +begin on a new output line. This is accomplished by passing +<kbd>.FOOTNOTE OFF</kbd> (or <kbd>QUIT, END, X,</kbd> etc) an +additional argument: <kbd>BREAK</kbd> or <kbd>BR</kbd>. +</p> + +<p> +Study the two examples below to understand the difference. +</p> + +<div id="examples-footnotes-3" class="examples-container" style="padding-bottom: 1em;"> +<div class="examples" style="margin-top: 0; margin-bottom: -.25em;">Example 1</div> +<span class="pre"> +.LEFT +A line of text\c +.FOOTNOTE +A footnote line +.FOOTNOTE OFF +that carries on after the footnote. +</span> +</div> + +<div id="examples-footnotes-4" class="examples-container" style="margin-top: 1em; padding-bottom: 1em;"> +<div class="examples" style="margin-top: 0; margin-bottom: -.25em;">Example 2</div> +<span class="pre"> +.LEFT +A line of text\c +.FOOTNOTE +A footnote line +.FOOTNOTE OFF BREAK +that doesn’t carry on after the footnote. +</span> +</div> + +<p> +Example 1, on output, produces +<br/> +<span class="pre-in-pp"> + A line of text* that carries on after the footnote. +</span> +whereas Example 2 produces +<span class="pre-in-pp"> + A line of text* + that doesn’t carry on after the footnote. +</span> +The distinction becomes particularly important if you like to see +punctuation marks come <i>after</i> footnote markers. In no-fill +modes, that’s accomplished like this: +<br/> +<span class="pre-in-pp"> + .LEFT + A line of text\c + .FOOTNOTE + A footnote line + .FOOTNOTE OFF + , + broken up with a comma. +</span> +The output of the above looks like this: +<br/> +<span class="pre-in-pp"> + A line of text*, + broken up with a comma. +</span> +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +The document element tag, +<a href="#quote">QUOTE</a>, +implies a no-fill mode, therefore these instructions also apply when +you insert footnotes into quotes. +</p> +</div> + +<!-- -FOOTNOTE- --> + +<div class="macro-id-overline"> +<h3 id="footnote" class="macro-id">FOOTNOTE</h3> +</div> + +<div class="box-macro-args"> +Tag: FOOTNOTE <kbd class="macro-args"><toggle> [ BREAK | BR ] | INDENT LEFT | RIGHT | BOTH <indent value></kbd> +</div> + +<p class="requires"> +• <kbd><indent value></kbd> requires a <a href="definitions.html#unitofmeasure">unit of measure</a> +<br/> +See <span style="font-style: normal"><a href="#footnote-note">HYPER-IMPORTANT NOTE</a></span>. +</p> + +<p> +FOOTNOTE is a toggle macro, therefore invoking it on a line by +itself allows you to enter a footnote in the body of a document. +Invoking it with any argument other than INDENT (i.e. <kbd>OFF, +QUIT, END, X...</kbd>) tells mom you’re finished. +</p> + +<p> +Footnotes are the only element of +<a href="definitions.html#running">running text</a> +that are not affected by the typesetting +<a href="typesetting.html#indents">indent macros</a>. +In the unlikely event that you want a page’s footnotes to +line up with a running indent, invoke <kbd>.FOOTNOTE</kbd> with +the <kbd>INDENT</kbd> argument and pass it an indent direction and +indent value. <kbd>L, R,</kbd> and <kbd>B</kbd> may be used in place +of <kbd>LEFT, RIGHT,</kbd> and <kbd>BOTH</kbd>. FOOTNOTE must be +invoked with <kbd>INDENT</kbd> for every footnote you want indented; +mom does not save any footnote indent information from invocation to +invocation. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +If a footnote runs to more than one paragraph, do <i>not</i> begin +the footnote with the +<a href="#pp">PP</a> +tag. Use <kbd>.PP</kbd> only to introduce subsequent paragraphs. +</p> +</div> + +<div id="footnote-note" class="box-tip"> +<p class="tip-top"> +<span class="note">HYPER-IMPORTANT NOTE:</span> +The final word on the +<a href="definitions.html#inputline">input line</a> +that comes immediately before FOOTNOTE <i>must</i> terminate with a +<kbd><a href="typesetting.html#join">\c</a></kbd> +inline escape if your +<a href="#footnote-marker-style">FOOTNOTE_MARKER_STYLE</a> +is either <kbd>STAR</kbd> or <kbd>NUMBER</kbd>. See the +<a href="#footnote-example">footnote example</a> +above. +</p> + +<p> +Additionally, in +<a href="definitions.html#filled">fill</a> +modes +(<a href="typesetting.html#justify">JUSTIFY</a> +or +<a href="typesetting.html#quad">QUAD</a>), +the line <i>after</i> a <kbd>.FOOTNOTE OFF</kbd> should be +entered as if there were no interruption in the input text, i.e. +the line should begin with a literal space or punctuation mark (see +explanation and examples +<a href="#fn-and-punct">here</a>). +</p> + +<p> +In +<a href="definitions.html#filled">no-fill</a> +modes, the optional argument <kbd>BREAK</kbd> or <kbd>BR</kbd> may +be used after the<kbd>OFF</kbd> (or <kbd>QUIT, END, X,</kbd> etc.) +argument to instruct mom not to join the next input line to the +previous output. See +<a href="#fn-and-punct-nofill">here</a> +for a more complete explanation, with examples. +</p> + +<p class="tip-bottom"> +Do not use the <kbd>\c</kbd> inline escape if your +FOOTNOTE_MARKER_STYLE is <kbd>LINE</kbd>, or if you have disabled +footnote markers with +<kbd><a href="#footnote-markers">.FOOTNOTE_MARKERS OFF</a></kbd>. +In these instances, the line after <kbd>.FOOTNOTE OFF</kbd> +should be entered normally. +</p> +</div> + +<div class="defaults-container" style="background-color: #ded4bd; border: none;"> +<h3 id="footnote-control" class="docs defaults">FOOTNOTE control macros macros and defaults</h3> + +<ol style="margin-top: .5em; padding-bottom: .5em;"> + <li><a href="#footnote-general">Family/font/size/colour/lead/quad</a></li> + <li><a href="#footnote-markers">Footnote markers</a> – on or off</li> + <li><a href="#footnote-marker-style">Footnote marker style</a> – star+dagger or numbered</li> + <li><a href="#footnotes-by-linenumber">Footnotes by line number</a> + <ul style="margin-left: -.5em; list-style-type: disc;"> + <li><a href="#footnote-linenumber-brackets">FOOTNOTE_LINENUMBER_BRACKETS</a></li> + <li><a href="#footnote-linenumber-separator">FOOTNOTE_LINENUMBER_SEPARATOR</a></li> + <li><a href="#footnotes-run-on">FOOTNOTES_RUN_ON</a> – line-numbered footnotes only</li> + </ul></li> + <li><a href="#reset-footnote-number">Reset footnote number</a> – set footnote marker number to 1</li> + <li><a href="#footnote-space">Inter-footnote spacing</a></li> + <li><a href="#footnote-rule">Footnote rule</a> – on or off</li> + <li><a href="#footnote-rule-length">Footnote rule length</a> – length of footnote separator rule</li> + <li><a href="#footnote-rule-weight">Footnote rule weight</a> – weight of footnote separator rule</li> + <li><a href="#footnote-rule-adj">Adjust vertical position of footnote separator rule</a></li> +</ol> +</div> + +<h4 id="footnote-general" class="docs" style="margin-top: -1.5em; margin-bottom: .5em;">1. Family/font/size/colour/lead/quad</h4> + +<div class="defaults-container" style="padding-bottom: 8px;"> +<p class="defaults" style="padding-top: 6px;"> +See +<a href="#control-macro-args">Arguments to the control macros</a>. +</p> +<span class="pre defaults"> +.FOOTNOTE_FAMILY default = prevailing document family; default is Times Roman +.FOOTNOTE_FONT default = roman +.FOOTNOTE_SIZE default = -2 (points) +.FOOTNOTE_COLOR default = black +.FOOTNOTE_AUTOLEAD default = 2 points (typeset); single-spaced (typewrite) +.FOOTNOTE_QUAD default = same as paragraphs +</span> +</div> + +<h4 id="footnote-markers" class="docs" style="margin-top: -1.25em;">2. Footnote markers – FOOTNOTE_MARKERS</h4> + +<p> +If you don’t want footnote markers, in either the body of +the document or beside footnote entries themselves, toggle them +off with <kbd>.FOOTNOTE_MARKERS OFF</kbd> (or <kbd>END, QUIT, +X</kbd>...). This means, of course, that you’ll +have to roll your own. If you want them back on, invoke +<kbd>.FOOTNOTE_MARKERS</kbd> with no argument. Footnote markers are +on by default. +</p> + +<p> +If FOOTNOTE_MARKERS are disabled, do not use the <kbd>\c</kbd> +inline escape to terminate the line before <kbd>.FOOTNOTE</kbd>. +</p> + +<h4 id="footnote-marker-style" class="docs" style="margin-top: -.25em;">3. Footnote marker style – FOOTNOTE_MARKER_STYLE</h4> + +<p> +Mom gives you two choices of footnote marker style: star+dagger (see +<a href="#footnote-behaviour">footnote behaviour</a> +above), or numbered. +</p> + +<p> +<kbd>.FOOTNOTE_MARKER_STYLE STAR</kbd> gives you star+dagger (the +default). There is a limit of 10 footnotes per page with this +style. +</p> + +<p> +<kbd>.FOOTNOTE_MARKER_STYLE NUMBER</kbd> gives you superscript +numbers, both in the document body and in the footnote entries +themselves. By default, footnote numbers increase incrementally +(prev. footnote number + 1) throughout the whole document. You +can ask mom to start each page’s footnote numbers at 1 with +<kbd>.RESET_FOOTNOTE_NUMBER</kbd> +(<a href="#reset-footnote-number">see below</a>.) +</p> + +<h4 id="footnotes-by-linenumber" class="docs" style="margin-top: -.25em;">4. Footnotes by line number</h4> + +<p> +<kbd>.FOOTNOTE_MARKER_STYLE LINE</kbd> lets you have footnotes which +are identified by line number, rather than by a marker in the text. +(Note that +<a href="#number-lines">NUMBER_LINES</a> +must be enabled in order to use this marker style.) +</p> + +<p> +With FOOTNOTE_MARKER_STYLE <kbd>LINE</kbd>, mom will identify +footnotes either by single line numbers, or line ranges. If +what you want is a single line number, you need only invoke +<kbd>.FOOTNOTE</kbd>, <i>without terminating the text line before it +with</i> <kbd>\c</kbd>, at the appropriate place in running text. +</p> + +<p> +If you want a range of line numbers (e.g. [5-11] ), +insert, directly into the first line of the range you want, +the <a href="definitions.html#inlines">inline escape</a>, +<kbd>\*[FN-MARK]</kbd>. For the terminating line number of the +range, you need only invoke <kbd>.FOOTNOTE</kbd>, (again, without +attaching <kbd>\c</kbd> to the text line before it). Mom is smart +enough to figure out that where <kbd>.FOOTNOTE</kbd> was invoked +represents the terminating line number. Range-numbered footnotes +are always output on the page where <kbd>.FOOTNOTE</kbd> was +invoked, not the page where <kbd>\*[FN-MARK]</kbd> appears (subject, +of course, to the rules for footnotes that fall too close to the +bottom of a page, as outlined +<a href="#footnote-rules">here</a>). +</p> + +<h5 id="footnote-linenumber-brackets" class="docs" style="margin-top: -.25em;">Footnote line number brackets</h5> + +<p> +Mom, by default, puts footnote line numbers inside square +brackets. The style of the brackets may be changed with the macro, +FOOTNOTE_LINENUMBER_BRACKETS, which takes one of three possible +arguments: <kbd>PARENS</kbd> (round brackets), <kbd>SQUARE</kbd> +(the default) or <kbd>BRACES</kbd> (curly braces). If you prefer a +shortform, the arguments, <kbd>(</kbd>, <kbd>[</kbd> or <kbd>{</kbd> +may be used instead. +</p> + +<h5 id="footnote-linenumber-separator" class="docs" style="margin-top: -.25em;">FOOTNOTE_LINENUMBER_SEPARATOR</h5> + +<p> +If you don’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. +</p> + +<p> +The separator can be composed of any valid groff character, +or any combination of characters. +</p> + +<p> +<b>A word of caution:</b> when using a separator, mom doesn’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 +<br/> +<span class="pre-in-pp"> + .FOOTNOTE_LINENUMBER_SEPARATOR ": " +</span> +</p> + +<h5 id="footnotes-run-on" class="docs" style="margin-top: -.25em;">RUN-ON FOOTNOTES</h5> + +<p> +Finally, if your footnote marker style is <kbd>LINE</kbd>, you may +instruct mom to do "run-on style" footnotes. Run-on footnotes +do not treat footnotes as discrete entities, i.e. on a line by +themselves. Rather, each footnote is separated from the footnote +before it by a space, so that the footnotes on any given page +form a continuous block, like lines in a paragraph. The macro +to get mom to run footnotes on is <kbd>.FOOTNOTES_RUN_ON</kbd>. +Invoked by itself, it turns the feature on. Invoked with any +other argument (<kbd>OFF, NO</kbd>, etc.), it turns the feature off. It is +generally not a good idea to turn the feature on and off during the +course of a single document. If you do, mom will issue a warning +if there’s going to be a problem. However, it is always +perfectly safe to enable/disable the feature after +<a href="rectoverso.html#collate">COLLATE</a>. +</p> + +<p> +The usual reason for wanting run-on footnotes is that you’re +using them to hold many, short references. (See +<a href="refer.html#top">here</a> +for instructions on using the groff program, <kbd>refer</kbd>, to +set up references.) +</p> + +<h4 id="reset-footnote-number" class="docs" style="margin-top: -.25em;">5. Reset footnote number – RESET_FOOTNOTE_NUMBER</h4> + +<p> +<kbd>.RESET_FOOTNOTE_NUMBER</kbd>, by itself, resets footnote +numbering so that the next footnote you enter is numbered 1. +</p> + +<p> +<kbd>.RESET_FOOTNOTE_NUMBER PAGE</kbd> tells mom to start every +page’s footnote numbering at 1. +</p> + +<h4 id="footnote-space" class="docs" style="margin-top: -.25em;">6. Inter-footnote spacing – FOOTNOTE_SPACE</h4> + +<p> +If you’d like a little extra space between footnotes, you can +have mom put it in for you by invoking <kbd>.FOOTNOTE_SPACE</kbd> +with an argument representing the amount of extra space you’d +like. The argument to FOOTNOTE_SPACE requires a +<a href="definitions.html#unitofmeasure">unit of measure</a>. +</p> + +<p> +In the following example, footnotes will be separated from each +other by 3 +<a href="definitions.html#picaspoints">points</a>. +<br/> +<span class="pre-in-pp"> + .FOOTNOTE_SPACE 3p +</span> +</p> + +<h4 id="footnote-rule" class="docs" style="margin-top: -.25em;">7. Footnote rule – FOOTNOTE_RULE</h4> + +<p> +If you don’t want a footnote separator rule, toggle it off with +<kbd>.FOOTNOTE_RULE OFF</kbd> (or <kbd>END, QUIT, X</kbd>...). +Toggle it back on by invoking <kbd>.FOOTNOTE_RULE</kbd> with no +argument. The default is to print the rule. +</p> + +<h4 id="footnote-rule-length" class="docs" style="margin-top: -.25em;">8. Footnote rule length – FOOTNOTE_RULE_LENGTH</h4> + +<p> +If you want to change the length of the footnote separator rule, +invoke <kbd>.FOOTNOTE_RULE_LENGTH</kbd> with a length, like this, +<br/> +<span class="pre-in-pp"> + .FOOTNOTE_RULE_LENGTH 1i +</span> + +which sets the length to 1 inch. Note that a +<a href="definitions.html#unitofmeasure">unit of measure</a> +is required. The default is 4 +<a href="definitions.html#picaspoints">picas</a> +for both +<a href="docprocessing.html#printstyle">PRINTSTYLES</a>. +</p> + +<h4 id="footnote-rule-weight" class="docs" style="margin-top: -.25em;">9. Footnote rule weight – FOOTNOTE_RULE_WEIGHT</h4> + +<p> +If you want to change the weight (“thickness”) of the +footnote separator rule, invoke <kbd>.FOOTNOTE_RULE_WEIGHT</kbd> +with the desired weight. The weight is measured in +<a href="definitions.html#picaspoints">points</a>; +however, do not append the +<a href="definitions.html#unitofmeasure">unit of measure</a>, +<kbd>p</kbd>, to the argument. +</p> + +<p> +Mom’s default footnote rule weight is 1/2 point. If +you’d like a 1-point rule instead,<br/> +<span class="pre-in-pp"> + .FOOTNOTE_RULE_WEIGHT 1 +</span> +is how you’d get it. +</p> + +<h4 id="footnote-rule-adj" class="docs" style="margin-top: -.25em;">10. Adjust vertical position of footnote separator rule – FOOTNOTE_RULE_ADJ</h4> + +<p> +The footnote separator rule is a rule whose bottom edge falls +on the +<a href="definitions.html#baseline">baseline</a> +(at the footnote +<a href="definitions.html#leading">leading</a>) +one line above the first line of a page’s footnotes. By default, +mom raises the rule 3 +<a href="definitions.html#picaspoints">points</a> +from the baseline so that the separator and the footnotes don’t +look jammed together. If you’d prefer a different vertical +adjustment, invoke <kbd>.FOOTNOTE_RULE_ADJ</kbd> with the +amount you’d like. For example +<br/> +<span class="pre-in-pp"> + .FOOTNOTE_RULE_ADJ 4.25p +</span> +raises the rule by 4-1/4 points. Note that you can only raise +the rule, not lower it. A +<a href="definitions.html#unitofmeasure">unit of measure</a> +is required. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +If your document +<a href="definitions.html#leading">leading</a> +is 2 +<a href="definitions.html#picaspoints">points</a> +or less (e.g your +<a href="definitions.html#ps">point size</a> +is 10 and your linespacing is 10, 11, or 12), lowering mom’s +default footnote rule adjustment will almost certainly give you +nicer looking results than leaving the adjustment at the default. +Furthermore, you can invoke <kbd>.FOOTNOTE_RULE_ADJ</kbd> on any +page in which footnotes appear, or in any column, so that the +placement of the footnote rule can be changed on-the-fly, should you +wish. +</p> +</div> + +<div class="rule-short"><hr/></div> + +<!-- ==================================================================== --> + +<h2 id="endnote-intro" class="macro-group">Endnotes</h2> + +<ul style="margin-left: -.5em;"> + <li><a href="#endnote-behaviour">Endnotes behaviour</a> + <ul style="margin-left: -.5em;"> + <li><a href="#endnote-spacing">A note on endnotes spacing</a></li> + <li><a href="#endnote-columns">Endnotes and columnar documents</a></li> + </ul></li> + <li><a href="#endnote">Tag: ENDNOTE</a></li> + <li><a href="#endnotes">Macro: <b>ENDNOTES</b></a>—tell mom to output endnotes</li> + <li><a href="#endnote-control">ENDNOTES control macros and defaults</a></li> +</ul> + +<p> +Embedding endnotes into mom documents is accomplished the same way +as embedding +<a href="#footnote-intro">footnotes</a>. +The example below is identical to the one shown in the +<a href="#footnote-example">introduction to footnotes</a>, +except that <kbd>.FOOTNOTE</kbd> has been replaced with +<kbd>.ENDNOTE</kbd>. +</p> + +<div id="examples" class="examples-container" style="padding-bottom: 1em;"> +<div class="examples" style="margin-top: 0; margin-bottom: -.25em;">Example</div> +<span id="endnote-example" class="pre"> + ...the doctrines of Identity as urged by Schelling\c + .ENDNOTE + <endnote about who the hell is Schelling> + .ENDNOTE OFF + were generally the points of discussion presenting the most + of beauty to the imaginative Morella. +</span> +</div> + +<p> +As with footnotes, note the obligatory use of the <kbd>\c</kbd> +<a href="definitions.html#inlines">inline escape</a> +when your +<kbd><a href="#endnote-marker-style">ENDNOTE_MARKER_STYLE</a></kbd> +is <kbd>NUMBER</kbd> (which marks endnotes references in +<a href="definitions.html#running">running text</a> +with superscript numbers). When the marker style is +<kbd>LINE</kbd>, you must <i>not</i> use the <kbd>\c</kbd> +escape. +</p> + +<p> +Endnotes differ from footnotes in two ways (other than the fact that +endnotes come at the end of a document whereas footnotes appear in +the body of the document): +</p> + +<ol style="margin-top: -.5em;"> + <li>When your ENDNOTE_MARKER_STYLE is <kbd>NUMBER</kbd>, + endnotes are always numbered incrementally, starting at "1". + </li> + <li>Endnotes must be output explicitly; mom does not output + them for you. In + <a href="rectoverso.html#collate">collated</a> + documents, this allows you to choose whether you want the + endnotes to appear at the end of each chapter or article in a + document, or grouped together at the very end of the document. + </li> +</ol> + +<p> +Within endnotes, you may use the document element tags +<a href="#pp">PP</a>, +<a href="#quote">QUOTE</a> +and +<a href="#blockquote">BLOCKQUOTE</a>. +This provides the flexibility to create endnotes that run to several +paragraphs, as well as to embed cited text within endnotes. +</p> + +<p> +Should you wish to change the appearance of quotes or blockquotes +that appear within endnotes, you may do so with the +<a href="#quote-control">quote control macros</a> +or +<a href="#blockquote-control">blockquote control macros</a>. +However, you must make the changes <i>within</i> each endnote, +prior to invoking <kbd>.QUOTE</kbd> or <kbd>.BLOCKQUOTE</kbd>, +and undo them prior to terminating the endnote (i.e. before +<kbd>.ENDNOTE OFF</kbd>), otherwise the changes will affect +subsequent quotes and blockquotes that appear in the document body +as well. +</p> + +<h3 id="endnote-behaviour" class="docs">Endnotes behaviour</h3> + +<p> +When you output endnotes (with +<kbd><a href="#endnotes">.ENDNOTES</a></kbd>), +mom finishes processing the last page of your document, then breaks +to a new page for printing the endnotes. If the document type is +<kbd><a href="docprocessing.html#doctype">CHAPTER</a></kbd>, +the centre part of the +<a href="definitions.html#header">header</a> +(or footer), which, by default, contains a chapter number or title, +is removed. +</p> + +<p> +By default, mom starts the endnotes page with a bold, +centred, double-underscored head, “ENDNOTES”. +Underneath—flush left, bold, and underscored—she prints +the document title (or, in the case of chapters, the chapter +number or title). She then prints the endnotes. Each endnote is +identified by its appropriate number, in bold, right aligned to two +placeholders. The text of the endnotes themselves is indented to +the right of the numbers. +</p> + +<p> +If the endnotes are grouped together at the end of a collated +document, each section of the document that contains endnotes is +identified by its own unique title (or chapter number or title), +bold, flush left, and underscored. +</p> + +<p> +Of course, all the defaults, as well as the overall style of the +endnotes page, can be changed with the +<a href="#endnote-control">endnote control macros</a>. +The attentive will notice that endnotes have an awful lot of control +macros. This is because endnotes are like a mini-document unto +themselves, and therefore need not be bound by the style parameters +of the body of the document. +</p> + +<h3 id="endnote-spacing" class="docs">A note on endnotes spacing</h3> + +<p> +On the endnotes page(s), each new endnote is separated from the +previous endnote by a full line space. This can result in a bottom +margin that hangs, and is the one instance, other than the use of +<a href="#pp-space">PARA_SPACE</a>, +where mom allows unequal bottom alignment of pages. Should you wish +to correct this, by adding or subtracting small amounts of space +between endnotes that appear together on an endnotes page, make the +adjustment (with +<a href="typesetting.html#ald">ALD</a>, +<a href="typesetting.html#rld">RLD</a> +or +<a href="typesetting.html#space">SPACE</a>) +<i>at the end of each endnote</i> (i.e. just before invoking +<a href="#endnote"><kbd>.ENDNOTE OFF</kbd></a>) +rather than at the top. +</p> + +<h3 id="endnote-columns" class="docs">Endnotes and columnar documents</h3> + +<p> +If your document is set in columns (see +<a href="docprocessing.html#columns">COLUMNS</a>), +mom gives you the option to have endnotes appear in either +the column format or set to the full page width. See +<a href="#endnotes-no-columns">ENDNOTES_NO_COLUMNS</a>. +</p> + +<!-- -ENDNOTE- --> + +<div class="macro-id-overline"> +<h3 id="endnote" class="macro-id">ENDNOTE</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>ENDNOTE</b> <kbd class="macro-args"><toggle> [ BREAK | BR ]</kbd> +</div> +<p class="requires"> +See <span style="font-style: normal"><a href="#endnote-note">HYPER-IMPORTANT NOTE</a></span> +</p> + +<p> +ENDNOTE is a toggle macro, therefore invoking it on a line by itself +allows you to enter an endnote in the body of a document. Invoking +it with any other argument (i.e. <kbd>OFF, QUIT, END, X...</kbd> +tells mom that you’ve finished the endnote. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +If an endnote runs to more than one paragraph, do <i>not</i> begin +the endnote with the +<a href="#pp">PP</a> +tag. Use PP only to introduce subsequent paragraphs. +</p> +</div> + +<div id="endnote-note" class="box-tip"> +<p class="tip-top"> +<span class="note">HYPER-IMPORTANT NOTE:</span> +If your +<a href="#endnote-marker-style">ENDNOTE_MARKER_STYLE</a> +is <kbd>NUMBER</kbd> (mom’s default), the final word on the +<a href="definitions.html#inputline">input line</a> +that comes immediately before <kbd>.ENDNOTE</kbd> MUST terminate +with a +<a href="typesetting.html#join"><kbd>\c</kbd></a> +inline escape. See the +<a href="#endnote-example">endnote example</a> +above. +</p> + +<p> +Additionally, in +<a href="definitions.html#filled">fill</a> +modes +(<a href="typesetting.html#justify">JUSTIFY</a> +or +<a href="typesetting.html#quad">QUAD</a>, +the line <i>after</i> <kbd>.ENDNOTE OFF</kbd> should be +entered as if there were no interruption in the input text, i.e. +the line should begin with a literal space or punctuation mark (see +explanation and examples for footnotes, which apply equally to +endnotes, +<a href="#fn-and-punct">here</a>). +</p> + +<p> +In +<a href="definitions.html#filled">no-fill</a> +modes, the optional argument <kbd>BREAK</kbd> or <kbd>BR</kbd> may +be used after the <kbd>OFF</kbd> (or <b>QUIT, END, X,</b> etc.) +argument to instruct mom not to join the next input line to the +previous output. See +<a href="#fn-and-punct-nofill">here</a> +for a more complete explanation. The examples are for +<kbd>.FOOTNOTE</kbd>, but apply equally to <kbd>.ENDNOTE</kbd>. +</p> + +<p class="tip-bottom"> +If your ENDNOTE_MARKER_STYLE is LINE, do not use the <kbd>\c</kbd> +escape, and enter the line after <kbd>.ENDNOTE OFF</kbd> normally. +</p> +</div> + +<!-- -ENDNOTES- --> + +<div class="macro-id-overline"> +<h3 id="endnotes" class="macro-id">ENDNOTES</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>ENDNOTES</b> +</div> + +<p> +Unlike footnotes, which mom automatically outputs at the bottom +of pages, endnotes must be explicitly output by you, the +user. ENDNOTES, by itself (i.e. without any argument), is the macro +to do this. +</p> + +<p> +Typically, you’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. +</p> + +<p> +Should you wish to output the endnotes for each section of a +collated document at the ends of the sections (instead of at the +very end of the document), simply invoke <kbd>.ENDNOTES</kbd> +immediately prior to +<a href="rectoverso.html#collate">COLLATE</a>. +Mom will print the endnotes, identified and numbered appropriately, +on a separate page prior to starting the next section of the +document. Each subsequent invocation of <kbd>.ENDNOTES</kbd> +outputs only those endnotes that mom collected after the previous +invocation. +</p> + +<div class="defaults-container" style="background-color: #ded4bd; border: none;"> +<h3 id="endnote-control" class="docs defaults">ENDNOTES control macros and defaults</h3> + +<div class="box-important" style="width: 700px; margin: auto; background-color: #ded4bd;"> +<p class="tip-top" style="color: #000056;"> +<span class="important">Important:</span> +Endnotes control macros must always be invoked prior to the first +instance of +<a href="#endnote"><kbd>.ENDNOTE</kbd></a>. +</p> + +<p style="color: #000056; margin-top: -.5em;"> +When you embed endnotes in the body of a document, mom collects +<i>and processes</i> them for later outputting (when you invoke +<a href="#endnotes"><kbd>.ENDNOTES</kbd></a>). +By the time you do invoke <kbd +style="color: #000056;">.ENDNOTES</kbd>, it’s much too late to +change your mind about how you want them to look. +</p> + +<p class="tip-bottom" style="color: #000056; margin-top: -.5em;"> +My advice? If you’re planning to change the default +appearance of endnotes pages, set them up prior to +<a href="docprocessing.html#start">START</a>. +</p> +</div> + +<ol style="margin-top: .5em; padding-bottom: .5em;"> + <li><a href="#endnotes-general"><b>General endnotes style control</b></a> + <ul style="margin-left: -.5em;"> + <li><a href="#endnote-style">Base family/font/quad</a></li> + <li><a href="#endnote-pt-size">Base point size</a></li> + <li><a href="#endnote-lead">Leading</a></li> + <li><a href="#singlespace-endnotes">Singlespace endnotes (TYPEWRITE only)</a></li> + <li><a href="#endnote-para-indent">Paragraph indenting</a></li> + <li><a href="#endnote-para-space">Paragraph spacing</a></li> + <li><a href="#endnotes-no-columns">Turning off column mode during endnotes output</a></li> + </ul></li> + <li><a href="#endnotes-pagination"><b>Pagination of endnotes</b></a> + <ul style="margin-left: -.5em;"> + <li><a href="#endnotes-pagenum-style">Page numbering style</a></li> + <li><a href="#endnotes-first-pagenumber">Setting the first page number of endnotes</a></li> + <li><a href="#endnotes-no-first-pagenum">Omitting a page number on the first page of endnotes</a></li> + <li><a href="#suspend-pagination">Suspending pagination during endnotes output</a></li> + </ul></li> + <li><a href="#endnotes-header-control"><b>Header/footer control</b></a> + <ul style="margin-left: -.5em;"> + <li><a href="#endnotes-modify-hdrftr">Modifying what goes in the endnotes header/footer</a></li> + <li><a href="#endnotes-hdrftr-center">Header/footer centre string when doctype is CHAPTER</a></li> + <li><a href="#endnotes-allows-headers">Allow headers on endnotes pages</a></li> + </ul></li> + <li><a href="#endnotes-main-title"><b>Endnotes' first-page title control</b></a> + <ul style="margin-left: -.5em;"> + <li><a href="#endnote-string">Title string</a></li> + <li><a href="#endnote-string-control">Title string control macros and defaults</a></li> + <li><a href="#endnote-string-placement">Title string placement</a></li> + <li><a href="#endnote-string-underline">Title string underscoring</a></li> + <li><a href="#endnote-string-caps">Title string capitalization</a></li> + </ul></li> + <li><a href="#endnotes-doc-title"><b>Endnotes document-identification string control</b></a> + <ul style="margin-left: -.5em;"> + <li><a href="#endnote-title">Document-identification string(s)</a></li> + <li><a href="#endnote-title-control">Document-identification string control macros and defaults</a></li> + <li><a href="#endnote-title-underscore">Document-identification string underscoring</a></li> + </ul></li> + <li><a href="#endnotes-numbering"><b>Endnotes referencing style</b></a> + <ul style="margin-left: -.5em;"> + <li><a href="#endnote-marker-style">Endnote marker style</a> – by numbers in the text, or by line number + <ul style="margin-left: -.5em;"> + <li><a href="#endnote-linenumber-gap">Spacing between line-numbered endnotes and the endnote text</a></li> + <li><a href="#endnote-linenumber-brackets">Brackets around endnote line numbers</a></li> + <li><a href="#endnote-linenumber-separator">Separator after endnote line numbers instead of brackets</a></li> + </ul></li> + <li><a href="#endnote-number-control">Endnote numbering control macros and defaults</a></li> + <li><a href="#endnote-number-alignment">Endnote numbering alignment</a></li> + </ul></li> +</ol> +</div> + +<h4 id="endnotes-general" class="docs" style="margin-top: -1.5em; margin-bottom: .5em;">1. General endnotes page style control</h4> + +<h5 id="endnote-style" class="docs" style="margin-top: 0; margin-bottom: .5em; margin-left: .5em;">• Base family/font/quad</h5> + +<div class="defaults-container" style="padding-bottom: 8px;"> +<p class="defaults" style="padding-top: 6px;"> +See +<a href="#control-macro-args">Arguments to the control macros</a>. +</p> +<span class="pre defaults"> +.ENDNOTE_FAMILY default = prevailing document family; default is Times Roman +.ENDNOTE_FONT default = roman +.ENDNOTE_QUAD* default = justified + +*Note: ENDNOTE_QUAD must be set to either L (LEFT) or J (JUSTIFIED); + R (RIGHT) and C (CENTER) will not work. +</span> +</div> + +<!-- -ENDNOTE_PT_SIZE- --> + +<h5 id="endnote-pt-size" class="docs" style="margin-top: -1.5em; margin-bottom: .5em; margin-left: .5em;">• Base point size</h5> + +<div class="box-macro-args"> +Macro: <b>ENDNOTE_PT_SIZE</b> <kbd class="macro-args"><base type size of endnotes></kbd> +</div> + +<p> +Unlike most other control macros that deal with size of document +elements, ENDNOTE_PT_SIZE takes as its argument an absolute value, +relative to nothing. Therefore, the argument represents the size of +endnote type in +<a href="definitions.html#picaspoints">points</a>, +unless you append an alternative +<a href="definitions.html#unitofmeasure">unit of measure</a>. +For example, +<br/> +<span class="pre-in-pp"> + .ENDNOTE_PT_SIZE 12 +</span> +sets the base point size of type on the endnotes page to 12 +points, whereas +<br/> +<span class="pre-in-pp"> + .ENDNOTE_PT_SIZE .6i +</span> +sets the base point size of type on the endnotes page to 1/6 of an +inch. +</p> + +<p> +The type size set with ENDNOTE_PT_SIZE is the size of type used for +the text of the endnotes, and forms the basis from which the point +size of other endnote page elements is calculated. +</p> + +<p> +The default for +<a href="docprocessing.html#printstyle">PRINTSTYLE <kbd>TYPESET</kbd></a> +is 12.5 points (the same default size used in the body of the +document). +</p> + +<!-- -ENDNOTE_LEAD- --> + +<h5 id="endnote-lead" class="docs" style="margin-top: -.5em; margin-bottom: .5em; margin-left: .5em;">• Leading</h5> + +<div class="box-macro-args"> +Macro: <b>ENDNOTE_LEAD</b> <kbd class="macro-args"><base leading of endnotes> [ ADJUST ] </kbd> +</div> + +<p class="requires"> +• Does not require a <a href="definitions.html#unitofmeasure">unit of measure</a>; points is assumed +</p> + +<p> +Unlike most other control macros that deal with leading of document +elements, ENDNOTE_LEAD takes as its argument an absolute value, +relative to nothing. Therefore, the argument represents the +<a href="definitions.html#leading">leading</a> +of endnotes in +<a href="definitions.html#picaspoints">points</a> +unless you append an alternative +<a href="definitions.html#unitofmeasure">unit of measure</a>. +For example, +<br/> +<span class="pre-in-pp"> + .ENDNOTE_LEAD 14 +</span> +sets the base leading of type on the endnotes page to 14 +points, whereas +<br/> +<span class="pre-in-pp"> + .ENDNOTE_LEAD .5i +</span> +sets the base leading of type on the endnotes page to 1/2 inch. +</p> + +<p> +If you want the leading of endnotes adjusted to fill the page, pass +ENDNOTE_LEAD the optional argument +<kbd>ADJUST</kbd>. (See +<a href="docprocessing.html#doc-lead-adjust">DOC_LEAD_ADJUST</a> +for an explanation of leading adjustment.) +</p> + +<p> +The default for +<a href="docprocessing.html#printstyle">PRINTSTYLE <kbd>TYPESET</kbd></a> +is 14 points, adjusted. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +Even if you give mom a <kbd>.DOC_LEAD_ADJUST OFF</kbd> command, she +will still, by default, adjust endnote leading. You <i>must</i> +enter <kbd>.ENDNOTE_LEAD <lead></kbd> with no +<kbd>ADJUST</kbd> argument to disable this default behaviour. +</p> +</div> + +<!-- -SINGLESPACE_ENDNOTES- --> + +<h5 id="singlespace-endnotes" class="docs" style="margin-top: -.5em; margin-bottom: .5em; margin-left: .5em;">• Singlespace endnotes (TYPEWRITE only)</h5> + +<div class="box-macro-args"> +Macro: <b>SINGLESPACE_ENDNOTES</b> <kbd class="macro-args"><toggle></kbd> +</div> + +<p> +If your +<a href="docprocessing.html#printstyle">PRINTSTYLE</a> +is <kbd>TYPEWRITE</kbd> and you use TYPEWRITE’s default +double-spacing, endnotes are double-spaced. If your document is +single-spaced, endnotes are single-spaced. +</p> + +<p> +If, for some reason, you’d prefer that endnotes be +single-spaced in an otherwise double-spaced document (including +double-spaced +<a href="rectoverso.html#collate">collated</a> +documents), invoke +<br/> +<span class="pre-in-pp"> + .SINGLESPACE_ENDNOTES +</span> +with no argument. And if, god help you, you want to change endnote +single-spacing back to double-spacing for different spacing of +endnotes output at the ends of separate documents in a collated +document, invoke <kbd>.SINGLESPACE_ENDNOTES</kbd> with any argument +(<kbd>OFF, QUIT, Q, X</kbd>...). +</p> + +<!-- -ENDNOTE_PARA_INDENT- --> + +<h5 id="endnote-para-indent" class="docs" style="margin-top: 0; margin-bottom: .5em; margin-left: .5em;">• Paragraph indenting</h5> + +<div class="box-macro-args"> +Macro: <b>ENDNOTE_PARA_INDENT</b> <kbd class="macro-args"><amount to indent first line of paragraphs in endnotes></kbd> +</div> + +<p class="requires"> +• Requires a <a href="definitions.html#unitofmeasure">unit of measure</a> +</p> + +<p> +ENDNOTE_PARA_INDENT works exactly the same way as +<a href="#para-indent">PARA_INDENT</a>, +except that the indent given is the amount by which to indent the +first lines of endnote paragraphs, not document body paragraphs. +</p> + +<p> +The default is 1.5 +<a href="definitions.html#em">ems</a> +for +<a href="docprocessing.html#printstyle">PRINTSTYLE <kbd>TYPESET</kbd></a>; +1/2 inch for +<a href="docprocessing.html#printstyle">PRINTSTYLE <kbd>TYPEWRITE</kbd></a>. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +The first line of the first paragraph of endnotes (the one attached +immediately to the identifying endnote number) is never indented. +Only subsequent paragraphs are affected by ENDNOTE_PARA_INDENT. +</p> +</div> + +<!-- -ENDNOTE_PARA_SPACE- --> + +<h5 id="endnote-para-space" class="docs" style="margin-top: -.5em; margin-bottom: .5em; margin-left: .5em;">• Paragraph spacing</h5> + +<div class="box-macro-args"> +Macro: <b>ENDNOTE_PARA_SPACE</b> <kbd class="macro-args"><toggle></kbd> +</div> + +<p> +ENDNOTE_PARA_SPACE works exactly the same way as +<a href="#pp-space">PARA_SPACE</a>, +except that it inserts a blank line between endnote paragraphs, not +document body paragraphs. +</p> + +<p> +The default is not to insert a blank line between paragraphs in +endnotes. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +Each endnote itself is always separated from any previous endnote +by a line space. ENDNOTE_PARA_SPACE refers only to paragraphs that +appear within each discrete endnote. +</p> +</div> + +<!-- -ENDNOTES_NO_COLUMNS- --> + +<h5 id="endnotes-no-columns" class="docs" style="margin-top: -.5em; margin-bottom: .5em; margin-left: .5em;">• Turning off column mode during endnotes output</h5> + +<div class="box-macro-args"> +Macro: <b>ENDNOTES_NO_COLUMNS</b> <kbd class="macro-args"><toggle></kbd> +</div> + +<p> +By default, if your document is set in +<a href="docprocessing.html#columns">columns</a>, +mom sets the endnotes in columns, too. However, if your document +is set in columns and you’d like the endnotes not to be, +just invoke <kbd>.ENDNOTES_NO_COLUMNS</kbd> with no argument. +The endnotes pages will be set to the full page measure of your +document. +</p> + +<p> +If you output endnotes at the end of each document in a +<a href="rectoverso.html#collate">collated</a> +document set in columns, column mode will automatically be +reinstated for each document, even with ENDNOTES_NO_COLUMNS turned +on. In such circumstances, you must re-enable ENDNOTES_NO_COLUMNS +for each separate collated document. +</p> + +<h4 id="endnotes-pagination" class="docs" style="margin-bottom: .5em;">2. Pagination of endnotes</h4> + +<!-- -ENDNOTES_PAGENUM_STYLE- --> + +<h5 id="endnotes-pagenum-style" class="docs" style="margin-top: 0; margin-bottom: .5em; margin-left: .5em;">• Page numbering style</h5> + +<div class="box-macro-args"> +Macro: <b>ENDNOTES_PAGENUM_STYLE</b> <kbd class="macro-args">DIGIT | ROMAN | roman | ALPHA | alpha</kbd> +</div> + +<p> +Use this macro to set the page numbering style of endnotes pages. +The arguments are identical to those for +<a href="headfootpage.html#pagenum-style">PAGENUM_STYLE</a>. +The default is <kbd>digit</kbd>. You may want to change it to, say, +<kbd>alpha</kbd>, which you would do with +<br/> +<span class="pre-in-pp"> + .ENDNOTES_PAGENUM_STYLE alpha +</span> +</p> + +<!-- -ENDNOTES_FIRST_PAGENUMBER- --> + +<h5 id="endnotes-first-pagenumber" class="docs" style="margin-top: -.5em; margin-bottom: .5em; margin-left: .5em;">• Setting the first page number of endnotes</h5> + +<div class="box-macro-args"> +Macro: <b>ENDNOTES_FIRST_PAGENUMBER</b> <kbd class="macro-args"><page # that appears on page 1 of endnotes></kbd> +</div> + +<p> +Use this macro with caution. If all endnotes for several +<a href="rectoverso.html#collate">collated</a> +documents are to be output at once, i.e. not at the end of each +separate doc, ENDNOTES_FIRST_PAGENUMBER tells mom what page number +to put on the first page of the endnotes. +</p> + +<p> +However, if you set ENDNOTES_FIRST_PAGENUMBER in collated documents +in which the endnotes are output after each section (chapter, +article, etc), you have to reset every section’s first page +number after +<a href="rectoverso.html#collate">COLLATE</a> +and before +<a href="docprocessing.html#start">START</a> +with +<a href="headfootpage.html#pagenumber">PAGENUMBER</a>. +</p> + +<!-- -ENDNOTES_NO_FIRST_PAGENUN- --> + +<h5 id="endnotes-no-first-pagenum" class="docs" style="margin-top: -.25em; margin-bottom: .5em; margin-left: .5em;">• Omitting a page number on the first page of endnotes</h5> + +<div class="box-macro-args"> +Macro: <b>ENDNOTES_NO_FIRST_PAGENUM</b> <kbd class="macro-args"><toggle></kbd> +</div> + +<p> +This macro is for use only if +<a href="headfootpage.html#footers">FOOTERS</a> +are on. It tells +<a href="#endnotes">ENDNOTES</a> +not to print a page number on the first endnotes page. Mom’s +default is to print the page number. +</p> + +<!-- -SUSPEND_PAGINATION- --> + +<h5 id="suspend-pagination" class="docs" style="margin-top: -.5em; margin-bottom: .5em; margin-left: .5em;">• Suspending pagination during endnotes output</h5> + +<div class="box-macro-args" style="margin-bottom: 1em;"> +Macro: <b>SUSPEND_PAGINATION</b> +</div> + +<div class="box-macro-args"> +Macro: <b>RESTORE_PAGINATION</b> +</div> + +<p> +SUSPEND_PAGINATION doesn’t take an argument. Invoked +immediately prior to +<a href="#endnotes">ENDNOTES</a>, +it turns off endnotes pages pagination. Mom continues, however to +increment page numbers silently. +</p> + +<p> +To restore normal document pagination after endnotes, invoke +<kbd>.RESTORE_PAGINATION</kbd> (again, with no argument) immediately +after <kbd>.ENDNOTES</kbd>. +</p> + +<h4 id="endnotes-header-control" class="docs" style="margin-bottom: .5em;">3. Header/footer control</h4> + +<h5 id="endnotes-modify-hdrftr" class="docs" style="margin-top: 0; margin-bottom: -.75em; margin-left: .5em;">• Modifying what goes in the endnotes header/footer</h5> + +<p> +If you wish to modify what appears in the header/footer that appears +on endnotes page(s), make the changes before you invoke +<a href="#endnotes"><kbd>.ENDNOTES</kbd></a>, +not afterwards. +</p> + +<p> +Except in the case of +<a href="docprocessing.html#doctype">DOCTYPE <kbd>CHAPTER</kbd></a>, +mom prints the same header or footer used throughout the document +on the endnotes page(s). Chapters get treated differently in that, +by default, mom does not print the header/footer centre string +(normally the chapter number or chapter title.) In most cases, this +is what you want. However, should you not want mom to remove +the centre string from the endnotes page(s) headers/footers, invoke +<kbd><a href="#endnotes-hdrftr-center">.ENDNOTES_HEADER_CENTER</a></kbd> +with no argument. +</p> + +<p> +An important change you may want to make is to put the word +“Endnotes” in the header/footer centre position. To do +so, invoke +<br/> +<span class="pre-in-pp" style="margin-bottom: -1em;"> + .HEADER_CENTER "Endnotes" +</span> +or +<span class="pre-in-pp" style="margin-top: -.5em;"> + .FOOTER_CENTER "Endnotes" +</span> +prior to invoking <kbd>.ENDNOTES</kbd>. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +If your +<a href="docprocessing.html#doctype">DOCTYPE</a> +is <kbd>CHAPTER</kbd>, you must also invoke +<a href="#endnotes-hdrftr-center">ENDNOTES_HEADER_CENTER</a> +for the ENDNOTES_HEADER_CENTER to appear. +</p> +</div> + +<h5 id="endnotes-hdrftr-center" class="docs" style="margin-top: 0; margin-bottom: .5em; margin-left: .5em;">• Header/footer centre string when doctype is CHAPTER</h5> + +<div class="box-macro-args"> +Macro: <b>ENDNOTES_HEADER_CENTER</b> <kbd class="macro-args">toggle</kbd> +</div> + +<p> +If your +<a href="docprocessing.html#doctype">DOCTYPE</a> +is <kbd>CHAPTER</kbd> and you want mom to include a centre +string in the headers/footers that appear on endnotes +pages, invoke <kbd>.ENDNOTES_HEADER_CENTER</kbd> (or +<kbd>.ENDNOTES_FOOTER_CENTER</kbd>) with no argument. Mom’s +default is not to print the centre string. +</p> + +<p> +If, for some reason, having enabled the header/footer centre string +on endnotes pages, you wish to disable it, invoke the same macro +with any argument (<kbd>OFF, QUIT, Q, X</kbd>...). +</p> + +<h5 id="endnotes-allows-headers" class="docs" style="margin-top: -.5em; margin-bottom: .5em; margin-left: .5em;">• Allow headers on endnotes pages</h5> + +<div class="box-macro-args"> +Macro: <b>ENDNOTES_ALLOWS_HEADERS</b> <kbd class="macro-args"><none> | ALL</kbd> +</div> + +<p> +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 +<br/> +<span class="pre-in-pp"> + .ENDNOTES_ALLOWS_HEADERS OFF +</span> +If you want headers on every page including the first, do +<br/> +<span class="pre-in-pp"> + .ENDNOTES_ALLOWS_HEADERS ALL +</span> +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +If FOOTERS are on, mom prints footers on every endnotes page. +This is a style convention. In mom, there is no such beast as +ENDNOTES_ALLOWS_FOOTERS OFF. +</p> +</div> + +<h4 id="endnotes-main-title" class="docs">4. Endnotes' first-page title control</h4> + +<!-- -ENDNOTE_STRING- --> + +<h5 id="endnote-string" class="docs" style="margin-top: 1em; margin-bottom: .5em; margin-left: .5em;">• Title string</h5> + +<div class="box-macro-args"> +Macro: <b>ENDNOTE_STRING</b> <kbd class="macro-args">"<head to print at the top of endnotes>"</kbd> +</div> + +<p> +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 <kbd>.ENDNOTE_STRING</kbd> with the +endnotes-page head you want, surrounded by double-quotes. If you +don’t want a head at the top of the first endnotes-page, +invoke <kbd>.ENDNOTE_STRING</kbd> with a blank argument (either two +double-quotes side by side—<kbd>""</kbd>—or no +argument at all). +</p> + +<!-- -ENDNOTE_STRING_CONTROL- --> + +<h5 id="endnote-string-control" class="docs" style="margin-top: -.5em; margin-bottom: .5em; margin-left: .5em;">• Title control macros and defaults</h5> + +<div class="defaults-container" style="padding-bottom: 8px;"> +<p class="defaults" style="padding-top: 6px;"> +See +<a href="#control-macro-args">Arguments to the control macros</a>. +</p> +<span class="pre defaults"> +.ENDNOTE_STRING_FAMILY default = prevailing document family; default is Times Roman +.ENDNOTE_STRING_FONT default = bold +.ENDNOTE_STRING_SIZE* default = +1 +.ENDNOTE_STRING_QUAD default = centred + +*Relative to the size of the endnotes text (set with ENDNOTE_PT_SIZE) +</span> +</div> + +<!-- -ENDNOTE_STRING_ADVANCE- --> + +<h5 id="endnote-string-placement" class="docs" style="margin-top: -1em; margin-bottom: .5em; margin-left: .5em;">• Title string placement</h5> + +<div class="box-macro-args"> +Macro: <b>ENDNOTE_STRING_ADVANCE</b> <kbd class="macro-args"><distance from top of page></kbd> +</div> + +<p class="requires"> +• Argument requires a <a href="definitions.html#unitofmeasure">unit of measusure</a> +</p> + +<p> +By default, mom places the title (the docheader, as it were) of +endnotes pages (typically "ENDNOTES") on the same +<a href="definitions.html#baseline">baseline</a> +that is used for the start of +<a href="definitions.html#running">running text</a>. +If you’d prefer another location, higher or lower on the page +(thereby also raising or lowering the starting position of the +endnotes themselves), invoke <kbd>.ENDNOTE_STRING_ADVANCE</kbd> with +an argument stating the distance from the top edge of the page at +which you’d like the title placed. +</p> + +<p> +The argument requires a unit of measure, so if you’d like the title +to appear 1-1/2 inches from the top edge of the page, you’d tell +mom about it like this: +<br/> +<span class="pre-in-pp"> + .ENDNOTE_STRING_ADVANCE 1.5i +</span> +</p> + +<!-- -ENDNOTE_STRING_UNDERLINE- --> + +<h5 id="endnote-string-underline" class="docs" style="margin-top: -1em; margin-bottom: .5em; margin-left: .5em;">• Title string underscoring</h5> + +<div class="box-macro-args"> +Macro: <b>ENDNOTE_STRING_UNDERSCORE</b> <kbd class="macro-args">[DOUBLE] [<underscore weight> [<underscore gap> [<distance between double rules]]] | <none> | <anything></kbd> +</div> + +<p class="alias" style="margin-bottom: 0;"> +<i>Alias:</i> <b>ENDNOTE_STRING_UNDERLINE</b> +</p> + +<p class="requires"> +• The argument +<span style="font-style: normal"><kbd><underscore weight></kbd></span> +must not have the +<a href="definitions.html#unitofmeasure">unit of measure</a>, +<span style="font-style: normal;"><kbd>p</kbd></span>, +appended to it; all other arguments require a unit of measure +</p> + +<p> +Invoked without an argument, <kbd>.ENDNOTE_STRING_UNDERSCORE</kbd> +will place a single rule underneath the endnotes page title. Invoked +with the argument, <kbd>DOUBLE</kbd>, ENDNOTE_STRING_UNDERSCORE will +double-underscore the title. Invoked with any other non-numeric +argument, (e.g. <kbd>OFF, NO, X</kbd>, etc.) the macro disables +underscoring of the title. +</p> + +<p> +In addition, you can use ENDNOTE_STRING_UNDERSCORE to control the +weight of the underscore rule(s), the gap between the title and the +underscore, and, in the case of double-underscores, the distance +between the two rules. +</p> + +<p> +Some examples: +<br/> +<span class="pre-in-pp"> + .ENDNOTE_STRING_UNDERSCORE 1 + - turn underscoring on; set the rule weight to 1 point + + .ENDNOTE_STRING_UNDERSCORE 1 3p + - turn underscoring on; set the rule weight to 1 point; set + the gap between the title and the underscore to 3 points + + .ENDNOTE_STRING_UNDERSCORE DOUBLE .75 3p + - turn double-underscoring on; set the rule weight to 3/4 of + a point; set the gap between the title and the upper + underscore to 3 points; leave the gap between the upper + and the lower underunderscore at the default + + .ENDNOTE_STRING_UNDERSCORE DOUBLE 1.5 1.5p 1.5p + - turn double-underscoring on; set the rule weight to 1-1/2 + points; set the gap between the title and the upper + underscore to 1-1/2 points; set the gap between the upper + and the lower underscore to 1-1/2 points +</span> +Note, from the above, that in all instances, underscoring (single +or double) is enabled whenever ENDNOTE_STRING_UNDERSCORE is used in +this way. +</p> + +<p> +Mom’s default is to double-underscore the title with 1/2-point +rules placed 2 points apart and 2 points below the baseline of the +title. +</p> + +<!-- -ENDNOTE_STRING_CAPS- --> + +<h5 id="endnote-string-caps" class="docs" style="margin-top: -.5em; margin-bottom: .5em; margin-left: .5em;">• Title string capitalization</h5> + +<div class="box-macro-args"> +Macro: <b>ENDNOTE_STRING_CAPS</b> <kbd class="macro-args">toggle</kbd> +</div> + +<p> +Invoked by itself, <kbd>.ENDNOTE_STRING_CAPS</kbd> will +automatically capitalize the endnotes-page title. Invoked with any +other argument, the macro disables automatic capitalization of the +title. +</p> + +<p> +If you’re generating a table of contents, you may want the +endnotes pages title to be in caps, but the toc entry in caps/lower +case. If the argument to +<kbd><a href="#endnote-string">ENDNOTE_STRING</a></kbd> +is in caps/lower case and ENDNOTE_STRING_CAPS is on, this is exactly +what will happen. +</p> + +<p> +Mom’s default is to capitalize the endnotes pages title string. +</p> + +<!-- -ENDNOTE_TITLE- --> + +<h4 id="endnotes-doc-title" class="docs" style="margin-top: -.25em;">5. Endnotes document-identification title control</h4> + +<h5 id="endnote-title" class="docs" style="margin-top: 1em; margin-bottom: .5em; margin-left: .5em;">• Document-identification title string(s)</h5> + +<div class="box-macro-args"> +Macro: <b>ENDNOTE_TITLE</b> <kbd class="macro-args">"<title to identify a document in endnotes>"</kbd> +</div> + +<p> +By default, mom identifies the document(s) to which endnotes belong +by the document title(s) given to the +<a href="docprocessing.html#title">TITLE</a> +macro. If you’d like her to identify the document(s) another +way, simply invoke <kbd>.ENDNOTE_TITLE</kbd> prior to +<a href="docprocessing.html#start">START</a> +with the identifying title you want, surrounded by double-quotes. +</p> + +<p> +If you don’t want any identifying title, invoke +<kbd>.ENDNOTE_TITLE</kbd> with a blank argument, either two +double-quotes side by side (<kbd>""</kbd>) or no argument +at all. This is particularly useful if you have a single (i.e. +non-collated) document and find having the document’s title +included in the endnotes redundant. +</p> + +<!-- -ENDNOTE_TITLE_CONTROL- --> + +<h5 id="endnote-title-control" class="docs" style="margin-top: .75em; margin-bottom: .5em; margin-left: .5em;">• Document-identification string control macros and defaults</h5> + +<div class="defaults-container" style="padding-bottom: 8px;"> +<p class="defaults" style="padding-top: 6px;"> +See +<a href="#control-macro-args">Arguments to the control macros</a>. +</p> +<span class="pre defaults"> +.ENDNOTE_TITLE_FAMILY default = prevailing document family; default is Times Roman +.ENDNOTE_TITLE_FONT default = bold +.ENDNOTE_TITLE_SIZE* default = 0 +.ENDNOTE_TITLE_QUAD default = left + +*Relative to the size of the endnotes text (set with ENDNOTE_PT_SIZE) +</span> +</div> + +<!-- -ENDNOTE_TITLE_UNDERLINE- --> + +<h5 id="endnote-title-underscore" class="docs" style="margin-top: -1.25em; margin-bottom: .5em; margin-left: .5em;">• Endnotes document-identification underscoring</h5> + +<div class="box-macro-args"> +Macro: <b>ENDNOTE_TITLE_UNDERSCORE</b> <kbd class="macro-args">[DOUBLE] [<underline weight> [<underline gap> [<distance between double rules]]] | <none> | <anything></kbd> +</div> + +<p class="alias" style="margin-bottom: 0;"> +<i>Alias:</i> <b>ENDNOTE_TITLE_UNDERLINE</b> +</p> + +<p class="requires"> +• The argument +<span style="font-style: normal"><kbd><underscore weight></kbd></span> +must not have the +<a href="definitions.html#unitofmeasure">unit of measure</a>, +<span style="font-style: normal;"><kbd>p</kbd></span>, +appended to it; all other arguments require a unit of measure +</p> + +<p> +Invoked without an argument, <kbd>.ENDNOTE_TITLE_UNDERSCORE</kbd> +will place a single rule underneath the document identification +string. Invoked with the argument <kbd>DOUBLE</kbd>, +ENDNOTE_TITLE_UNDERSCORE will double-underscore the string. Invoked +with any other non-numeric argument, (e.g. <kbd>OFF, NO, X</kbd>, +etc.) the macro disables underscoring of the string. +</p> + +<p> +In addition, you can use ENDNOTE_TITLE_UNDERSCORE to control the +weight of the underscore rule(s), the gap between the title and the +underscore, and, in the case of double-underscores, the distance +between the two rules. +</p> + +<p> +Some examples: +<br/> +<span class="pre-in-pp"> + .ENDNOTE_TITLE_UNDERSCORE 1 + - turn underscoring on; set the rule weight to 1 point + + .ENDNOTE_TITLE_UNDERSCORE 1 3p + - turn underscoring on; set the rule weight to 1 point; set + the gap between the string and the underscore to 3 points + + .ENDNOTE_TITLE_UNDERSCORE DOUBLE .75 3p + - turn double-underscoring on; set the rule weight to 3 points + + .ENDNOTE_TITLE_UNDERSCORE DOUBLE 1.5 1.5p 1.5p + - turn double-underscoring on; set the rule weight to 1-1/2 + points; set the gap between the string and the upper + underscore to 1-1/2 points; set the gap between the upper + and the lower underscore to 1-1/2 points +</span> +</p> + +<p> +Note, from the above, that in all instances, underscoring (single or +double) is enabled whenever ENDNOTE_TITLE_UNDERSCORE is used in this +way. +</p> + +<p> +Mom’s default is to single-underscore the string with a +1/2-point rule placed 2 points below its baseline. +</p> + +<!-- -ENDNOTE_NUMBERING- --> + +<h4 id="endnotes-numbering" class="docs" style="margin-top: -.25em;">6. Endnotes referencing style</h4> + +<h5 id="endnote-marker-style" class="docs" style="margin-top: 1em; margin-bottom: .5em; margin-left: .5em;">• Endnote marker style</h5> + +<div class="box-macro-args"> +Macro: <b>ENDNOTE_MARKER_STYLE</b> <kbd class="macro-args">LINE | NUMBER</kbd> +</div> + +<p> +By default, mom places superscript numbers in +<a href="definitions.html#running">running text</a> +to identify endnotes. However, if you have +<a href="#number-lines">linenumbering</a> +turned on, you may instruct mom not to put superscript numbers in +the running text, but rather to reference endnotes by line number. +The command to do this is +<br/> +<span class="pre-in-pp"> + .ENDNOTE_MARKER_STYLE LINE +</span> +With ENDNOTE_MARKER_STYLE <kbd>LINE</kbd>, mom will identify +endnotes either by single line numbers or by line ranges. If +what you want is a single line number, you need only invoke +<kbd>.ENDNOTE</kbd>, <i>without terminating the text line before +it with</i> <kbd>\c</kbd>, at the appropriate place in running +text. +</p> + +<p> +(Should you wish to revert to mom’s default behaviour of +placing a superscript number in the text to identify an endnote, +you can invoke <kbd>.ENDNOTE_MARKER_STYLE</kbd> with the argument, +<kbd>NUMBER</kbd>. It is not advisable to switch marker styles +within a single document, for aesthetic reasons, but there is +nothing to prevent you from doing so.) +</p> + +<p id="en-mark"> +If you want a range of line numbers (e.g. [5-11] ), +insert, directly into the first line of the range you want, +the <a href="definitions.html#inlines">inline escape</a>, +<kbd>\*[EN-MARK]</kbd>. For the terminating line number of the +range, you need only invoke <kbd>.ENDNOTE</kbd>, (again, without +attaching <kbd>\c</kbd> to the text line before it). Mom is smart +enough to figure out that where <kbd>.ENDNOTE</kbd> is invoked +represents the terminating line number. +</p> + +<h5 id="endnote-linenumber-gap" class="docs" style="margin-top: -.5em; margin-bottom: .5em; margin-left: .5em;">• Spacing between line-numbered endnotes and the endnote text</h5> + +<div class="box-macro-args"> +Macro: <b>ENDNOTE_LINENUMBER_GAP</b> <kbd class="macro-args"><size of gap></kbd> +</div> + +<p class="requires"> +• Requires a <a href="definitions.html#unitofmeasure">unit of measure</a> +</p> + +<p> +Given the impossibility of knowing, in advance, the string length +of all the line numbers or ranges of line numbers that will be used +in endnotes (the string length of “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: +<br/> +<span class="pre-in-pp"> + [1-2] Notwithstanding, Frye later asserts that Christianity + is "a ghost with the chains of a foul historical record of + cruelty clanking behind it." +</span> +You can change the size of the gap with the macro, +ENDNOTE_LINENUMBER_GAP, which takes as its single argument the size +of the gap. The argument requires a +<a href="definitions.html#unitofmeasure">unit of measure</a>. +So, for example, to change the gap to 2 +<a href="definitions.html#picaspoints">picas</a>, +you’d do +<br/> +<span class="pre-in-pp"> + .ENDNOTE_LINENUMBER_GAP 2P +</span> +The default gap for both +<a href="docprocessing.html#printstyle">PRINTSTYLE TYPESET</a> +and +<a href="docprocessing.html#printstyle">PRINTSTYLE TYPEWRITE</a> +is 1.5 +<a href="definitions.html#em">ems</a>. +</p> + +<h5 id="endnote-linenumber-brackets" class="docs" style="margin-top: -.5em; margin-bottom: .5em; margin-left: .5em;">• Brackets around endnote line numbers</h5> + +<div class="box-macro-args"> +Macro: <b>ENDNOTE_LINENUMBER_BRACKETS</b> <kbd class="macro-args">PARENS | SQUARE | BRACES | ( | [ | {</kbd> +</div> + +<p> +By default, mom puts endnote line numbers inside square brackets. +The style of the brackets may be changed with the macro, +ENDNOTE_LINENUMBER_BRACKETS, which takes one of three possible +arguments: <kbd>PARENS</kbd> (“round” brackets), +<kbd>SQUARE</kbd> (the default) or <kbd>BRACES</kbd> (curly braces). +If you prefer a shortform, the arguments, <kbd>(</kbd>, <kbd>[</kbd> +or <kbd>{</kbd> may be used instead. +</p> + +<h5 id="endnote-linenumber-separator" class="docs" style="margin-top: -.5em; margin-bottom: .5em; margin-left: .5em;">• Separator after endnote line numbers instead of brackets</h5> + +<div class="box-macro-args"> +Macro: <b>ENDNOTE_LINENUMBER_SEPARATOR</b> <kbd class="macro-args"><character></kbd> +</div> + +<p> +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. +</p> + +<p> +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 +<br/> +<span class="pre-in-pp"> + .ENDNOTE_LINENUMBER_SEPARATOR : +</span> +</p> + +<h5 id="endnote-number-control" class="docs" style="margin-top: -1em; margin-bottom: .5em; margin-left: .5em;">• Endnote numbering style control</h5> + +<div class="defaults-container" style="padding-bottom: 8px;"> +<p class="defaults" style="padding-top: 6px;"> +See +<a href="#control-macro-args">Arguments to the control macros</a>. +</p> + +<p class="defaults"> +Please note that the control macros for endnote numbering affect only +the numbers that appear on the endnotes pages themselves, not the +endnote numbers that appear in the body of the document(s). +</p> +<span class="pre defaults"> +.ENDNOTE_NUMBER_FAMILY default = prevailing document family; default is Times Roman +.ENDNOTE_NUMBER_FONT default = bold +.ENDNOTE_NUMBER_SIZE* default = 0 + +*Relative to the size of the endnotes text (set with ENDNOTE_PT_SIZE) +</span> +</div> + +<h5 id="endnote-number-alignment" class="docs" style="margin-top: -1.25em; margin-bottom: -.5em; margin-left: .5em;">• Endnote numbering alignment</h5> + +<p style="margin-top: .75em;"> +By default, mom hangs the numbers on endnotes pages, aligned right +to two placeholders, producing this: +<br/> +<span id="endnote-numbering-alignment-example" class="pre-in-pp"> + 9. Lorem ipsum dolor sit amet, consetetur sadipscing elitr, + sed diam nonumy eirmod tempor invidunt ut labore et + dolore magna aliquyam erat, sed diam voluptua. + + 10. Lorem ipsum dolor sit amet, consetetur sadipscing elitr, + sed diam nonumy eirmod tempor invidunt ut labore et + dolore magna aliquyam erat, sed diam voluptua. +</span> +The macros to alter this behaviour are +</p> +<ul style="margin-top: -.5em; margin-left: -.5em;"> + <li><a href="#endnote-numbers-align-right">ENDNOTE_NUMBERS_ALIGN_RIGHT</a></li> + <li><a href="#endnote-numbers-align-left">ENDNOTE_NUMBERS_ALIGN_LEFT</a></li> +</ul> + +<!-- -ENDNOTE_NUMBERS_ALIGN_RIGHT- --> + +<div id="endnote-numbers-align-right" class="box-macro-args"> +Macro: <b>ENDNOTE_NUMBERS_ALIGN_RIGHT</b> <kbd class="macro-args"><number of placeholders></kbd> +</div> + +<p> +ENDNOTE_NUMBERS_ALIGN_RIGHT takes one (non-optional) argument: the +number of placeholders to reserve for right alignment of endnote +numbers. +</p> + +<p> +For example, if you have fewer than ten endnotes, you might want to do +<br/> +<span class="pre-in-pp"> + .ENDNOTE_NUMBERS_ALIGN_RIGHT 1 +</span> +which would ensure that the endnote numbers hang, but are all flush +with the page’s left margin. If, god help you, you have over a hundred +endnotes, you’d want to do +<br/> +<span class="pre-in-pp"> + .ENDNOTE_NUMBERS_ALIGN_RIGHT 3 +</span> +to ensure that the numbers hang and are properly right-aligned. +</p> + +<!-- -ENDNOTE_NUMBERS_ALIGN_LEFT- --> + +<div id="endnote-numbers-align-left" class="box-macro-args"> +Macro: <b>ENDNOTE_NUMBERS_ALIGN_LEFT</b> +</div> + +<p> +If you don’t want the endnote numbers to hang and right-align, +invoke <kbd>.ENDNOTE_NUMBERS_ALIGN_LEFT</kbd>, which doesn’t +require any argument. This disables hanging and right-alignment of +endnote numbers, so that the example +<a href="#endnote-numbering-alignment-example">above</a> +comes out like this: +<br/> +<span class="pre-in-pp"> + 9. Lorem ipsum dolor sit amet, consetetur sadipscing elitr, + sed diam nonumy eirmod tempor invidunt ut labore et + dolore magna aliquyam erat, sed diam voluptua. + + 10. Lorem ipsum dolor sit amet, consetetur sadipscing elitr, + sed diam nonumy eirmod tempor invidunt ut labore et + dolore magna aliquyam erat, sed diam voluptua. +</span> +</p> + +<div class="rule-short"><hr/></div> + +<!-- ==================================================================== --> + +<h2 id="margin-notes-intro" class="macro-group">Margin notes</h2> + +<ul style="margin-left: -.5em;"> + <li><a href="#margin-notes-behaviour">Margin notes behaviour</a> + <ul style="margin-left: -.5em;"> + <li><a href="#margin-notes-vertical">Adjusting the vertical position of margin notes</a></li> + </ul></li> + <li><a href="#mn-init">Macro: <b>MN_INIT</b></a>—initialize margin notes</li> + <li><a href="#mn">Tag: MN</a></li> +</ul> + +<p> +Margin notes are short annotations that appear in either the left +or right margin of a document. Sometimes they comment on the text. +Sometimes they assist in following the “flow” of a +document by summarizing the subject of a portion of text. Sometimes +they’re comments to yourself in a draft copy. +</p> + +<p> +The margin notes macros and routines in om.tmac (mom) are +“mommified” versions of the margin notes macros and +routines written by Werner Lemberg and patched by Gaius Mulley. +</p> + +<h3 id="margin-notes-behaviour" class="docs">Margin notes behaviour</h3> + +<p> +First things first: before you enter your first margin note, you +must “initialize” margin notes with +<a href="#mn-init">MN_INIT</a>. +MN_INIT sets up the style parameters for margin notes, including +things like +<a href="definitions.html#font">font</a>, +<a href="definitions.html#family">family</a> +and +<a href="definitions.html#leading">leading</a>. +</p> + +<p> +After initializing margin notes, you create margin notes with the +<a href="#mn">MN</a> +macro. Based on the argument you pass MN, your margin note will go +in either the left or the right margin. +</p> + +<p> +Margin notes are tricky from a typographic standpoint with respect +to vertical placement. Since the leading of margin notes may differ +from that of +<a href="definitions.html#running">running text</a>, +it’s impossible for mom to guess whether to align +the first lines of margin notes with a document +<a href="definitions.html#baseline">baseline</a>, +whether to align the last lines of margin notes with a document +baseline, or whether to center them, vertically, so that neither +first nor last line aligns with anything! +</p> + +<p> +Given this difficulty, mom always aligns the first line of any +margin note with a document baseline. If you want a different +behaviour, you must adjust the position(s) of margin notes yourself, +on a note by note basis. (See +<a href="#margin-notes-vertical">Adjusting the vertical position of margin notes</a>.) +</p> + +<p> +Generally speaking, mom tries to place margin notes at the point +where you invoke +<a href="#mn">MN</a>. +However, in the event that a margin note runs deep, she may not be +able to place a subsequent margin note exactly where you want. In +such an instance, mom will “shift” the margin note down +on the page, placing it one (margin note) linespace beneath the +previous margin note (plus whatever vertical space is required to +get the first line to line up with a baseline of running text). A +warning will be issued, letting you know this has happened, and +where. +</p> + +<p> +Sometimes, if a margin note has to be shifted down, there simply +isn’t enough room to start the margin note on the page on +which <kbd>.MN</kbd> is invoked. In that case, mom ignores the +margin note entirely and issues a warning, letting you know what +she’s done, and where. </p> + +<p> +In the event that a margin note, sucessfully begun on a page, runs +past your bottom margin (or the last line before footnotes begin), +the margin note will “flow” onto the next page. If +it is a “left” margin note, it will continue in the +left margin. If it is a “right” margin note, it will +continue in the right margin. +</p> + +<p> +If your document is being set in two columns, 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. +</p> + +<h3 id="margin-notes-vertical" class="docs">Adjusting the vertical position of margin notes</h3> + +<p> +When the +<a href="definitions.html#term-leading">leading</a> +of margin notes differs from the leading used throughout a document, +you may want to adjust the vertical position of individual margin +notes. This is most often going to be the case with margin notes +that end near the bottom of the page, where you want the last line +of the margin note to line up with the last line of text on the +page. +</p> + +<p> +Adjustments to the vertical position of margin notes must be done +inside the margin note (i.e. after <kbd>.MN</kbd>), at the top, +before entering text. The commands to use are +<kbd>\!<a href="typesetting.html#ald">.ALD</a></kbd> +(to lower the margin note) and +<kbd>\!<a href="typesetting.html#rld">.RLD</a></kbd> +(to raise it). + +The <kbd>\!</kbd> <i>must</i> precede the macros, or they +won’t have any effect. +</p> + +<!-- -MN_INIT- --> + +<div class="macro-id-overline"> +<h3 id="mn-init" class="macro-id">MN_INIT</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>MN_INIT</b> <kbd class="macro-args"><arguments (see list)></kbd> +</div> + +<h4 style="margin-top: .75em; margin-left: .5em; font-style: normal; font-weight: bold: font-size: 105%; color: #6f614a;">Argument list:</h4> + +<span class="pre" style="margin-top: -1.5em; margin-left: .5em;"> +[ RAGGED | SYMMETRIC ] +<left-width> +<right-width> +<gutter> +<family+font> +<point-size> +<lead> +<colour> +<hyphenation-flags> +</span> + +<p style="margin-top: 1.25em;"> +Before you enter your first margin note, you must initialize +<i>all</i> the parameters associated with margin notes with MN_INIT. +If you forget to do so, mom will issue a warning and abort. +</p> + +<p> +The argument list is quite long; an explanation of each argument +follows. Any argument whose value you want to be the default must +be entered as <kbd>""</kbd> (i.e. two double-quotes with +no space between them). Defaults for each argument are given in the +explanations below. +</p> + +<h4 class="docs arg-list">Argument 1: <kbd style="color: #302419;">[ RAGGED | SYMMETRIC ]</kbd></h4> + +<p> +If the first argument is <kbd>RAGGED</kbd>, both left and +right margin notes will be flush left. If the first argument +is <kbd>SYMMETRIC</kbd> left margin notes will be set flush +<i>right</i>, and right margin notes will be set flush +<i>left</i>. The effect is something like this: +<br/> +<span class="pre-in-pp"> + A left This is a meaningless batch A right + margin note of text whose sole purpose is margin note + with just to demonstrate how the sym- with just + a few words metric argument to MN sets left a few words + in it. and right margin notes. in it. +</span> +</p> + +<p> +If the argument is omitted, or given as <kbd>""</kbd>, +both left and right margin notes will be set justified. (Justified +is usually not a good idea, since the narrow measure of margin notes +makes pleasing justification a near impossibility.) +</p> + +<h4 class="docs arg-list">Argument 2: <kbd style="color: #302419;"><left-width></kbd></h4> + +<p> +The width of left margin notes. A +<a href="definitions.html#unitofmeasure">unit of measure</a> +must be appended directly onto the argument. The default is to set +left margin notes right out to the edge of the page, which is almost +certainly not what you want, so you should give a value for this +argument if using left margin notes. +</p> + +<h4 class="docs arg-list">Argument 3: <kbd style="color: #302419;"><right-width></kbd></h4> + +<p> +The width of right margin notes. A +<a href="definitions.html#unitofmeasure">unit of measure</a> +must be appended directly onto the argument. The default is to +set right margin notes right out to the edge of the page, which is +almost certainly not what you want, so you should give a value for +this argument if using right margin notes. +</p> + +<h4 class="docs arg-list">Argument 4: <kbd style="color: #302419;"><gutter></kbd></h4> + +<p> +The +<a href="definitions.html#gutter">gutter</a> +between margin notes and +<a href="definitions.html#running">running text</a>. +A +<a href="definitions.html#unitofmeasure">unit of measure</a> +must be appended directly onto the argument. The gutter applies to +both left and right margin notes. The default is 1 +<a href="definitions.html#em">em</a>. +</p> + +<h4 class="docs arg-list">Argument 5: <kbd style="color: #302419;"><font></kbd></h4> + +<p> +The family+font for margin notes. Yes, that’s right: the +family <i>plus</i> font combo. For example, if you want Times +Roman Medium, the argument must be TR. If you want Palatino +Medium Italic, the argument must be PI. The default is the same +family+font combo used for a document’s paragraph text. +</p> + +<h4 class="docs arg-list">Argument 6: <kbd style="color: #302419;"><point size></kbd></h4> + +<p> +The point size of type for margin notes. There is no need to append a +<a href="definitions.html#unitofmeasure">unit of measure</a> +to the argument; +<a href="definitions.html#picaspoints">points</a> +is assumed (although there’s nothing preventing you from +appending an alternative unit of measure directly to the argument). +The default is for margin notes to use the same point size of type +as is used in document paragraphs. +</p> + +<h4 class="docs arg-list">Argument 7: <kbd style="color: #302419;"><lead></kbd></h4> + +<p> +The +<a href="definitions.html#leading">leading</a> +of margin notes. <kbd><lead></kbd> uses +<a href="definitions.html#picaspoints">points</a> +as its unit of measure, so don’t tack a unit of measure onto +the end of the argument. The default lead is the same leading +as is used for paragraph text (i.e. the document’s base +leading). If you want the default, you may, for convenience +and clarity, give the word, <kbd>DOC</kbd>, to this argument, +instead of <kbd>""</kbd> (two double-quotes). Like the +double-quotes, it indicates that the leading should be the same as +the document’s base leading. +</p> + +<h4 class="docs arg-list">Argument 8: <kbd style="color: #302419;"><colour></kbd></h4> + +<p> +The colour of margin notes. The colour must be pre-initialized +with +<a href="color.html#newcolor">NEWCOLOR</a> +or +<a href="color.html#xcolor">XCOLOR</a>. +The default is black. +</p> + +<h4 class="docs arg-list">Argument 9: <kbd style="color: #302419;"><hyphenation-flags></kbd></h4> + +<p> +A number telling groff how you want margin notes +hyphenated. +<br/> +<span class="pre-in-pp"> + 1 = hyphenate without restrictions + 2 = do not hyphenate the last word on the page + 4 = do not hyphenate the last two characters of a word + 8 = do not hyphenate the first two characters of a word +</span> +The values can be added together, so, for example, if you want +neither the first two nor the last two characters of words +hyphenated, the hyphenation-flag would be 12. The default value is +14 (i.e. 2+4+8). +</p> + +<!-- -MN- --> + +<div class="macro-id-overline"> +<h3 id="mn" class="macro-id">MN</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>MN</b> <kbd class="macro-args">LEFT | RIGHT</kbd> +</div> + +<p> +Once you’ve initialized margin notes with +<kbd><a href="#mn-init">.MN_INIT</a></kbd>, +you can enter margin notes any time you like with <kbd>.MN</kbd>. +An argument of <kbd>LEFT</kbd> will set a left margin note. An +argument of <kbd>RIGHT</kbd> will set a right margin note. +</p> + +<p> +Any argument, such as <kbd>OFF</kbd> (or <kbd>QUIT, END, X</kbd>, +etc) exits the current margin note. +</p> + +<div class="rule-short"><hr/></div> + +<!-- ==================================================================== --> + +<!-- -FINIS- --> + +<h2 id="finis-intro" class="macro-group">Document termination string</h2> + +<ul style="margin-left: -.5em;"> + <li><a href="#finis">Tag: FINIS</a></li> + <li>FINIS control macros + <ul style="margin-left: -1.25em;"> + <li><a href="#finis-string">Changing the FINIS string</a></li> + <li><a href="#finis-string-caps">Automatic capitalization of the FINIS string</a></li> + <li><a href="#finis-color">Changing the FINIS color</a></li> + </ul></li> +</ul> + +<p> +The use of FINIS is optional. If you invoke it (at the end of a +document before +<kbd><a href="#toc">.TOC</a></kbd> +or +<kbd><a href="#endnotes">.ENDNOTES</a></kbd>), +mom deposits the word, <b>END</b>, centred after a blank line, +beneath the last line of the document. <b>END</b> is enclosed +between +<a href="definitions.html#em">em-dashes</a>, +like this: +<br/> +<span class="pre-in-pp"> + ...and they all lived happily ever after. + — END — +</span> +</p> + +<p> +If you’re writing in a language other than English, you can +change what mom prints for END with the control macro, +<a href="#finis-string">FINIS_STRING</a>. +</p> + +<div class="macro-id-overline"> +<h3 id="finis" class="macro-id">FINIS</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>FINIS</b> +</div> + +<p> +The use of FINIS is optional, but if you use it, it should be the +last macro you invoke in a document (before +<kbd><a href="#endnotes">.ENDNOTES</a></kbd> +or +<kbd><a href="#toc">.TOC</a></kbd>). +See +<a href="#finis-intro">above</a> +for a description of how FINIS behaves. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +If you don’t use FINIS, and you don’t want +<a href="definitions.html#footer">footers</a> +(if they’re on) or a page number at the bottom of the last +page of a document, you have to turn them off manually, as the last +two lines of your document file, like this: +<br/> +<span class="pre-in-pp"> + .FOOTERS OFF + .PAGINATE OFF +</span> +</p> +</div> + +<!-- -FINIS STRING- --> + +<h3 id="finis-string" class="docs">Changing the FINIS string</h3> + +<p> +By default, FINIS prints the word, END, between +<a href="definitions.html#em">em-dashes</a>. +If you’d like mom to print something else between the dashes, +use the FINIS_STRING macro (anywhere in the document prior to +FINIS). +</p> + +<p> +For example, if your document’s in French, you’d do +<br/> +<span class="pre-in-pp"> + .FINIS_STRING "FIN" +</span> +Double-quotes must enclose the macro’s argument. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +If you pass FINIS_STRING a blank string, i.e. +<br/> +<span class="pre-in-pp"> + .FINIS_STRING "" +</span> +mom will still print the em-dashes when you invoke +<kbd>.FINIS</kbd>. This, in effect, produces a short, centred +horizontal rule that terminates the document. (In +<a href="docprocessing.html#printstyle">PRINTSTYLE <kbd>TYPEWRITE</kbd></a>, +it’s a short, dashed line composed of four hyphens.) +</p> +</div> + +<!-- -FINIS STRING CAPS- --> + +<h3 id="finis-string-caps" class="docs">Automatic capitalization of the FINIS string</h3> + +<p> +By default, mom sets the string you pass to FINIS all-caps. +If you’d prefer that she not do so, but rather respect +the FINIS string exactly as you enter it, invoke the macro, +<kbd>.FINIS_STRING_CAPS</kbd> with the <kbd>OFF</kbd> argument, like +this: +<br/> +<span class="pre-in-pp"> + .FINIS_STRING_CAPS OFF +</span> +<kbd>OFF</kbd>, above, could be anything, e.g. <kbd>NO</kbd> or +<kbd>X</kbd>. +</p> + +<!-- -FINIS COLOR- --> + +<h3 id="finis-color" class="docs">Changing the FINIS colour</h3> + +<p> +Invoking the control macro, <kbd>.FINIS_COLOR</kbd>, with a +pre-defined (or “initalized”) color changes the colour +of both the FINIS string and the em-dashes that surround it. If you +use the +<a href="definitions.html#inline">inline escape</a>, +<a href="color.html#color-inline"><kbd>\*[<colorname>]</kbd></a>, +in the argument passed to FINIS, only the text will be in the +new colour; the em-dashes will be in the default document colour +(usually black). +</p> + +<div class="rule-long"><hr/></div> + +<!-- Navigation links --> +<table style="width: 100%; margin-top: 12px;"> +<tr> + <td style="width: 33%;"><a href="toc.html">Back to Table of Contents</a></td> + <td style="width: 33%; text-align: center;"><a href="#top">Top</a></td> + <td style="width: 33%; text-align: right;"><a href="images.html#top">Next: Inserting images</a></td> +</tr> +</table> + +</div> + +<div class="bottom-spacer"><br/></div> + +</body> +</html> +<!-- vim: fileencoding=utf-8: nomodified: --> 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 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- +This file is part of groff, the GNU roff type-setting system. + +Copyright (C) 2004, 2005, 2010, 2009, 2010 Free Software Foundation, Inc. +Written by Peter Schaffter. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with the +Invariant Sections being this comment section, with no Front-Cover +Texts, and with no Back-Cover Texts. + +A copy of the Free Documentation License is included as a file called +FDL in the main directory of the groff source package. +--> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"> + +<head> + <meta http-equiv="content-type" content="text/html;charset=utf-8"/> + <title>Mom -- Document Processing, Introduction and Setup</title> + <link rel="stylesheet" type="text/css" href="stylesheet.css" /> +</head> + +<body style="background-color: #f5faff;"> + +<!-- ==================================================================== --> + +<div id="top" class="page"> + +<!-- Navigation links --> +<table style="width: 100%;"> +<tr> + <td><a href="toc.html">Back to Table of Contents</a></td> + <td style="text-align: right;"><a href="docelement.html#top">Next: The document element tags</a></td> +</tr> +</table> + +<h1 class="docs">Document processing with mom</h1> + +<div style="text-align: center;"> +<ul class="no-enumerator" style="margin-left: -2.5em;"> + <li><a href="#defaults">Document defaults</a></li> + <li><a href="#leading-note">Important note on leading/spacing and bottom margins</a></li> + <li><a href="#shim">The SHIM macro</a></li> +</ul> +</div> + +<div class="rule-medium"><hr/></div> + +<h2 id="toc-doc-processing" class="docs" style="text-align: center;">Table of contents</h2> + +<div id="docprocessing-mini-toc" style="font-size: 90%; line-height: 150%; margin-top: .5em;"> +<div class="mini-toc-col-1" style="margin-left: 0;"> +<h3 class="toc toc-docproc-header" style="margin-top: 1em;"><a class="header-link" href="#docprocessing-intro">Introduction</a></h3> +<h3 class="toc toc-docproc-header" style="margin-top: .5em;"><a class="header-link" href="#setup">Document setup</a></h3> +<ul class="toc-docproc" style="margin-top: .5em;"> + <li><a href="#docprocessing-tut"><b>Tutorial – Setting up a mom document</b></a></li> + <li><a href="#reference-macros"><b>The reference macros</b></a> + <ul class="toc-docproc"> + <li><a href="#title">TITLE</a></li> + <li><a href="#doc-title">DOCTITLE</a></li> + <li><a href="#subtitle">SUBTITLE</a></li> + <li><a href="#author">AUTHOR</a></li> + <li><a href="#chapter">CHAPTER</a></li> + <li><a href="#chapter-title">CHAPTER_TITLE</a></li> + <li><a href="#draft">DRAFT</a></li> + <li><a href="#revision">REVISION</a></li> + <li><a href="#copyright">COPYRIGHT</a></li> + <li><a href="#misc">MISC</a></li> + <li><a href="#covertitle">COVERTITLE</a></li> + <li><a href="#doc-covertitle">DOC_COVERTITLE</a></li> + </ul></li> + <li><a href="#docstyle-macros"><b>The docstyle macros</b></a> + <ul class="toc-docproc"> + <li><a href="#doctype">DOCTYPE</a></li> + <li><a href="#printstyle">PRINTSTYLE</a></li> + <li><a href="#copystyle">COPYSTYLE</a></li> + </ul></li> +</ul> +<h3 class="toc toc-docproc-header"><a class="header-link" href="#start-macro">Initiate document processing</a></h3> +<ul class="toc-docproc" style="margin-top: .5em;"> + <li><a href="#start"><b>The START macro</b></a></li> +</ul> +<h3 class="toc toc-docproc-header"><a class="header-link" href="#style-before-start">Establishing type and formatting<br/><span style="display: block; margin-top: -.3em;">parameters before START</span></a></h3> +<ul class="toc-docproc" style="margin-top: .5em;"> + <li><a href="#type-before-start"><b>Behaviour of the typesetting macros before START</b></a> + <ul class="toc-docproc"> + <li><a href="docprocessing.html#include">Including (sourcing) style sheets and files</a></li> + <li><a href="#color">Initializing colours</a></li> + </ul></li> +</ul> +</div> +<div class="mini-toc-col-2" style="margin-top: -.5em;"> +<br/> +<ul class="toc-docproc" style="margin-top: .5em;"> + <li><a href="#doc-lead-adjust"><b>Adjust linespacing to fill pages</b></a> + <ul class="toc-docproc"> + <li><a href="#doc-lead-adjust">DOC_LEAD_ADJUST</a></li> + <li><a href="#shim">SHIM</a> – the macro to get document leading back on track</li> + </ul></li> + <li><a href="#docheader"><b>Managing the document header</b></a> + <ul class="toc-docproc"> + <li><a href="#docheader">DOCHEADER</a></li> + <li><a href="#docheader-control">Docheader control</a> + <ul class="toc-docproc"> + <li><a href="#docheader-desc">Docheader description</a></li> + <li><a href="#index-docheader-control">Macro list</a></li> + </ul></li> + </ul></li> + <li><a href="#columns-intro"><b>Setting documents in columns</b></a> + <ul class="toc-docproc"> + <li><a href="#columns">COLUMNS</a></li> + <li><a href="#breaking-columns">Breaking columns manually</a> + <ul class="toc-docproc"> + <li><a href="#col-next">COL_NEXT</a></li> + <li><a href="#col-break">COL_BREAK</a></li> + </ul></li> + </ul></li> +</ul> +<h3 class="toc toc-docproc-header"><a class="header-link" href="#style-after-start">Changing basic type and formatting<br/><span style="display: block; margin-top: -.3em;">parameters after START</span></a></h3> +<ul class="toc-docproc" style="margin-top: .5em;"> + <li><a href="#behaviour"><b>Behaviour of the typesetting macros during document processing</b></a></li> + <li><a href="docprocessing.html#index-doc-param"><b>Post-START global style change macros</b></a> + <ul class="toc-docproc"> + <li><a href="#doc-left-margin">DOC_LEFT_MARGIN</a></li> + <li><a href="#doc-right-margin">DOC_RIGHT_MARGIN</a></li> + <li><a href="#doc-line-length">DOC_LINE_LENGTH</a></li> + <li><a href="#doc-family">DOC_FAMILY</a></li> + <li><a href="#doc-pt-size">DOC_PT_SIZE</a></li> + <li><a href="#doc-lead">DOC_LEAD</a></li> + <li><a href="#doc-lead-adjust">DOC_LEAD_ADJUST</a></li> + <li><a href="#doc-quad">DOC_QUAD</a></li> + </ul></li> +</ul> +</div> +</div> + +<div class="rule-medium" style="clear: both;"><hr/></div> + +<!-- ==================================================================== --> + +<h2 id="docprocessing-intro" class="docs">Introduction to document processing</h2> + +<p> +Document processing with mom uses markup tags to identify document elements +such as heads, paragraphs, and so on. The tags are, of course, +macros, but with sensible, readable names that make them easy +to grasp and easy to remember. (And don’t forget: if you +don’t like the “official” name of a tag — +too long, cumbersome to type in, not “intuitive” enough +— you can change it with the +<a href="goodies.html#alias">ALIAS</a> +macro.) +</p> + +<p> +In addition to the tags themselves, mom has an extensive array of +macros that control how they look and behave. +</p> + +<p> +Setting up a mom doc is a simple, four-part procedure. You +begin by entering information about the document itself (title, +subtitle, author, etc.). Next, you tell mom what kind of document +you’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 +<kbd><a href="#start">START</a></kbd> +macro. Voilà! You’re ready to write. +</p> + +<!-- ==================================================================== --> + +<h2 id="defaults" class="docs">Document defaults</h2> + +<p> +As is to be expected, mom has defaults for everything. If you want +to know a particular default, read about it in the description of +the pertinent tag. +</p> + +<p> +I fear the following may not be adequately covered in the +documentation, so just in case: +</p> +<ul style="margin-top: -.5em; margin-bottom: .5em;"> + <li>the paper size is 8.5x11 inches</li> + <li>the left and right margins are 1-inch</li> + <li>the top and bottom margins for document text are plus/minus + visually 1-inch + </li> + <li>pages are numbered; the number appears centred, at the + bottom, surrounded by hyphens ( e.g. -6- ) + </li> + <li>the first page of a document begins with a + <a href="definitions.html#docheader">document header</a> + </li> + <li>subsequent pages have + <a href="definitions.html#header">page headers</a> + with a rule underneath + </li> +</ul> + +<!-- ==================================================================== --> + +<h2 id="leading-note" class="docs">Important note on leading/spacing and bottom margins</h2> + +<p> +Mom takes evenly-aligned bottom margins in +<a href="definitions.html#running">running text</a> +very seriously. Only under a very few (exceptional) circumstances +will she allow a bottom margin to “hang” (i.e. to fall +short). +</p> + +<p> +In order to ensure even bottom margins, mom uses the +“base” document +<a href="definitions.html#leading">leading</a> +in effect <i>at the start of running text on each page</i> (i.e. +the leading used in paragraphs) to calculate the spacing of every +document element. Prior to invoking +<a href="#start">START</a>, +this is set with the +<a href="typesetting.html#macros-typesetting">typesetting macro</a> +<a href="typesetting.html#leading">LS</a>, +afterwards with the document +<a href="definitions.html#controlmacro">control macro</a> +<a href="#doc-lead">DOC_LEAD</a>. +</p> + +<p> +Because mom relies so heavily on the base document +leading, any change to the leading or spacing on a page will almost +certainly have undesirable consequences on that page’s bottom margin +unless the change is fully compensated for elsewhere on the page. +</p> + +<p> +In other words, if you add a few points of space somewhere on a page, +you must subtract the same number of points somewhere else on that +same page, and vice versa. +</p> + +<p> +If it’s a question of adding or subtracting full +line spaces between or within document elements, you +can do so by using the “<kbd>v</kbd>” <a +href="definitions.html#unitofmeasure">unit of measure</a> with +whatever spacing macro you choose — +<a href="typesetting.html#ald">ALD</a>, +<a href="typesetting.html#rld">RLD</a>, +<a href="typesetting.html#space">SPACE</a> +— and mom won’t object. “<kbd>v</kbd>” means +“the current leading”, so she isn’t confused by it. And +since “<kbd>v</kbd>” accepts decimal fractions, you can add/subtract +half linespaces and quarter linespaces with “<kbd>v</kbd>” as well, +<i>provided you compensate for the fractional linespace somewhere +else on the page</i>. +</p> + +<p> +If all this seems like too much work, mom provides a special macro +to get you out of trouble if you’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. +</p> + +<!-- -SHIM- --> + +<div class="macro-id-overline"> +<h3 id="shim" class="macro-id">SHIM</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>SHIM</b> +</div> + +<p> +SHIM doesn’t take any argument. Use it whenever you’ve played +around with the +<a href="definitions.html#leading">leading</a> +or spacing on a page and you need to get mom’s document +leading back on track. +</p> + +<p> +For example, say you want to insert a picture into a document with +the special groff macro, PSPIC (see <kbd>man groff-tmac</kbd> for +usage). +</p> + +<p> +Pictures aren’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. +</p> + +<p> +The solution is to insert SHIM after the picture, +like this: +<br/> +<span class="pre-in-pp"> + <some lines of text> + .PSPIC <full path to picture> + .SHIM + <more lines of text> +</span> +</p> + +<p> +SHIM instructs mom to insert as much or a little space after the +picture as is needed to ensure that the baseline of the next +<a href="definitions.html#outputline">output line</a> +falls where mom would have put it had you not disrupted the normal +flow of output lines with the picture. +</p> + +<p> +And say, on previewing the above example, you find that the picture +doesn’t centre nicely between the lines of text, you can +always do +<br/> +<span class="pre-in-pp"> + <some lines of text> + .RLD 3p + .PSPIC <full path to picture> + .SHIM + <more lines of text> +</span> +to raise the picture slightly (reverse lead 3 points; see +<a href="typesetting.html#rld">RLD</a>), +and still have SHIM ensure that text underneath falls exactly where +it’s supposed to. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +For information on disabling the automatic shimming of quotes and +blockquotes during document processing, see +<a href="docelement.html#no-shim">here</a>. +</p> +</div> + +<div class="rule-short"><hr/></div> + +<!-- ==================================================================== --> + +<h2 id="setup" class="docs" style="margin-bottom: .5em;">Preliminary document setup</h2> + +<div class="examples-container" style="margin-bottom: 1.5em;"> +<h3 id="docprocessing-tut" class="docs">Tutorial – Setting up a mom document</h3> + +<p style="margin-top: 1em;"> +There are four parts to setting up a mom doc (three, actually, +with one optional). Before we proceed, though, be reassured that +something as simple as +<br/> +<span class="pre-in-pp"> + .TITLE "By the Shores of Lake Attica" + .AUTHOR "Rosemary Winspeare" + .PRINTSTYLE TYPESET + .START +</span> +produces a beautifully typeset 8.5x11 document, with a +<a href="definitions.html#docheader">docheader</a> +at the top of page 1, +<a href="definitions.html#header">page headers</a> +with the title and author on subsequent pages, and page numbers at +the bottom of each page. In the course of the document, heads, +subheads, citations, quotes, epigraphs, and so on, all come out +looking neat, trim, and professional. +</p> + +<p> +For the purposes of this tutorial, we’re going to set up +a short story—<i>My Pulitzer Winner</i>—by Joe Blow. +Thankfully, we don’t have to look at story itself, just the +setup. Joe wants the document +</p> +<ul style="margin-top: -.5em; margin-bottom: -.5em;"> + <li>to be draft 7, revision 39;</li> + <li>to use the “default” style of document formatting:</li> + <li>to print as draft-style output (instead of “final” copy output);</li> + <li>to be typeset, in Helvetica, 12 on 14, + <a href="definitions.html#rag">rag-right</a>; + </li> + <li>to have <a href="definitions.html#footer">footers</a> + instead of + <a href="definitions.html#header">headers</a>; + </li> + <li>to use a single asterisk for + <a href="definitions.html#linebreak">author linebreaks</a>. + </li> +</ul> + +<p> +Joe Blow has no taste in typography. His draft won’t look +pretty, but this is, after all, a tutorial; we’re after +examples, not beauty. +</p> + +<h4 class="docs" style="margin-top: -.5em;">Step 1</h4> + +<p style="margin-bottom: -.5em;"> +The first step in setting up any document is giving mom some +reference information. The reference macros are: +</p> +<div style="width: 50%; float: left;"> +<ul> + <li>TITLE</li> + <li>DOCTITLE</li> + <li>COVERTITLE</li> + <li>DOC_COVERTITLE</li> + <li>SUBTITLE</li> + <li>AUTHOR</li> + <li>CHAPTER – the chapter number</li> +</ul> +</div> +<div> +<ul> + <li>DRAFT – the draft number</li> + <li>REVISION – the revision number</li> + <li>COPYRIGHT – only used on cover pages</li> + <li>MISC – only used on cover pages</li> + <li>COVER_TITLE – only on cover pages; only if needed</li> + <li>DOC_COVER_TITLE – only on document cover pages; only if needed</li> +</ul> +</div> + +<p style="margin-top: -.5em; clear: both;"> +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 +<a href="definitions.html#arguments">arguments</a> +from the macros by any number of spaces. The following are what +you’d need to start Joe Blow’s story. +<br/> +<span class="pre-in-pp"> + .TITLE "My Pulitzer Winner" + .AUTHOR "Joe Blow" + .DRAFT 7 + .REVISION 39 +</span> +</p> + +<h4 class="docs" style="margin-top: -1.5em;">Step 2</h4> + +<p> +Once you’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: +</p> +<ul style="margin-top: -.5em; margin-bottom: -.5em;"> + <li>DOCTYPE—the type of document (default, chapter, user-defined, letter)</li> + <li>PRINTSTYLE—typeset or typewritten</li> + <li>COPYSTYLE —draft or final copy</li> +</ul> + +<p> +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> +</p> + +<p> +Adding to what we already have, the next bit of setup for Joe +Blow’s story looks like this: +<br/> +<span class="pre-in-pp"> + .TITLE "My Pulitzer Winner" + .AUTHOR "Joe Blow" + .DRAFT 7 + .REVISION 39 + \# + .DOCTYPE DEFAULT \"Superfluous; mom uses DOCTYPE DEFAULT by default + .PRINTSTYLE TYPESET + .COPYSTYLE DRAFT +</span> +Notice the use of the +<a href="definitions.html#commentlines">comment line</a> +( <kbd>\#</kbd> ), a handy way to keep groups of macros visually +separated for easy reading in a text editor. +</p> + +<h4 class="docs" style="margin-top: -.5em; margin-bottom: -.5em;">Step 3</h4> + +<p> +This step—completely optional—is where you, the +user, take charge. Mom has defaults for <i>everything</i>, but +who’s ever satisfied with defaults? Use any of the +<a href="typesetting.html#macros-typesetting">typesetting macros</a> +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 +<a href="#printstyle">PRINTSTYLE</a> +directive <i>before</i> making any such changes. +</p> + +<p> +Joe Blow wants his story printed in Helvetica, 12 on 14, rag right, +with +<a href="definitions.html#footer">page footers</a> +instead of +<a href="definitions.html#header">page headers</a> +and a single asterisk for the +<a href="definitions.html#linebreak">linebreak</a> +character. None of these requirements conforms to mom’s +defaults for the chosen PRINTSTYLE (TYPESET), so we change them +here. The setup for Joe Blow’s story now looks like this: +<br/> +<span class="pre-in-pp"> + .TITLE "My Pulitzer Winner" + .AUTHOR "Joe Blow" + .DRAFT 7 + .REVISION 39 + \# + .DOCTYPE DEFAULT + .PRINTSTYLE TYPESET + .COPYSTYLE DRAFT + \# + .FAMILY H + .PT_SIZE 12 + .LS 14 + .QUAD LEFT \"i.e. rag right + .FOOTERS + .LINEBREAK_CHAR * +</span> +</p> + +<h4 class="docs" style="margin-top: -1.5em; margin-bottom: -.5em;">Step 4</h4> + +<p> +The final step in setting up a document is telling mom to start +document processing. It’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). +</p> + +<p> +Here’s the complete setup for <i>My Pulitzer Winner</i>: +<br/> +<span class="pre-in-pp"> + .TITLE "My Pulitzer Winner" + .AUTHOR "Joe Blow" + .DRAFT 7 + .REVISION 39 + \# + .DOCTYPE DEFAULT + .PRINTSTYLE TYPESET + .COPYSTYLE DRAFT + \# + .FAMILY H + .PT_SIZE 12 + .LS 14 + .QUAD LEFT \"i.e. rag right + .FOOTERS + .LINEBREAK_CHAR * + \# + .START +</span> +As pointed out earlier, Joe Blow is no typographer. Given that all he +needs is a printed draft of his work, a simpler setup would have been: +<br/> +<span class="pre-in-pp"> + .TITLE "My Pulitzer Winner" + .AUTHOR "Joe Blow" + .DRAFT 7 + .REVISION 39 + \# + .PRINTSTYLE TYPEWRITE + .COPYSTYLE DRAFT + \# + .START +</span> +<kbd>.PRINTSTYLE TYPEWRITE</kbd>, above, means that Joe’s +work will come out “typewritten, double-spaced”, +making the blue-pencilling he (or someone else) is sure to do much +easier (which is why many publishers and agents still insist on +typewritten, double-spaced copy). +</p> + +<p> +When J. Blow stops re-writing and decides to print off a final, +typeset copy of his work for the world to see, he need only make two +changes to the (simplified) setup: +<br/> +<span class="pre-in-pp"> + .TITLE "My Pulitzer Winner" + .AUTHOR "Joe Blow" + .DRAFT 7 + .REVISION 39 + \# + .PRINTSTYLE TYPESET \"first change + .COPYSTYLE FINAL \"second change + \# + .START +</span> +In the above, <kbd>.DRAFT 7, .REVISION 39,</kbd> and +<kbd>.COPYSTYLE FINAL</kbd> are actually superfluous. The draft +and revision numbers aren’t used when COPYSTYLE is FINAL, +and <b>COPYSTYLE FINAL</b> is mom’s default unless you tell +her otherwise. +</p> + +<p> +BUT... to judge from the number of drafts already, +J. Blow may very well decide his “final” version still +isn’t up to snuff. Hence, he might as well leave in the +superfluous macros. That way, when draft 7, rev. 62 becomes draft +8, rev. 1, he’ll be ready to tackle his Pulitzer winner again. +</p> +</div> + +<div class="rule-short"><hr/></div> + +<!-- ======================================================================== --> + +<h2 id="reference-macros" class="macro-group">The reference macros</h2> + +<p> +The reference macros give mom the meta-information she needs to +generate +<a href="definitions.html#docheader">docheaders</a>, +<a href="definitions.html#header">page headers</a>, +and +<a href="cover.html#cover-top">covers</a>. +They must go at the top of any file that uses mom’s document +processing macros. +</p> + +<div class="macro-list-container"> +<h3 id="index-reference" class="macro-list">Reference macros</h3> + +<ul class="macro-list"> + <li><a href="#title">TITLE</a> – title of a story, article, etc</li> + <li><a href="#doc-title">DOCTITLE</a> – title of a book, or any collated document</li> + <li><a href="#subtitle">SUBTITLE</a></li> + <li><a href="#author">AUTHOR</a></li> + <li><a href="#chapter">CHAPTER</a> – the chapter number + <ul> + <li class="sublist"><a href="#chapter-string">CHAPTER_STRING</a> – “Chapter”, “CHAPTER”, “Chapître”, etc</li> + </ul></li> + <li><a href="#chapter-title">CHAPTER_TITLE</a></li> + <li><a href="#draft">DRAFT</a> + <ul> + <li class="sublist"><a href="#draft-string">DRAFT_STRING</a> – “Draft”, “DRAFT”, “Jet”, etc</li> + </ul></li> + <li><a href="#revision">REVISION</a> + <ul> + <li class="sublist"><a href="#revision-string">REVISION_STRING</a> – “Revision”, “Rev.”, “Révision”, etc</li> + </ul></li> + <li><a href="#copyright">COPYRIGHT</a></li> + <li><a href="#misc">MISC</a></li> + <li><a href="#covertitle">COVERTITLE</a> – frontispiece, title page, etc</li> + <li><a href="#doc-covertitle">DOC_COVERTITLE</a> – book cover, collated document cover, etc</li> +</ul> +</div> + +<!-- -TITLE- --> + +<div class="macro-id-overline"> +<h3 id="title" class="macro-id">TITLE</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>TITLE</b> <kbd>"<title string>" ["<2nd line>" ["<3rd line>" ... ] ]</kbd> +</div> +<p class="requires"> +• Arguments must be enclosed in double-quotes +</p> + +<p> +The title string can be caps or caps/lower-case; it’s up to you. In +<a href="#printstyle">PRINTSTYLE TYPESET</a>, +the title will appear in the +<a href="definitions.html#docheader">docheader</a> +exactly as you typed it. However, mom converts the title to all +caps in +<a href="definitions.html#header">page headers</a> +unless you turn that feature off (see +<a href="headfootpage.html#_caps">HEADER_<POSITION>_CAPS</a>). +In +<a href="#printstyle">PRINTSTYLE TYPEWRITE</a>, +the title always gets converted to caps. +</p> + +<p> +TITLE accepts multiple arguments, each surrounded by double-quotes. +Each argument is printed on a separate line, permitting you to +create multi-line titles in your docheaders. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +If your <kbd><a href="#doctype">DOCTYPE</a></kbd> is CHAPTER, TITLE +should be the title of the opus, not “CHAPTER whatever”. +</p> +</div> + +<!-- -DOCTITLE- --> + +<div class="macro-id-overline"> +<h3 id="doc-title" class="macro-id">DOCUMENT TITLE</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>DOCTITLE</b> <kbd class="macro-args">"<overall document title>" ["<2nd line>" ["<3rd line>" ... ] ]</kbd> +</div> +<p class="requires"> +• Arguments must be enclosed in double-quotes +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +This macro should be used only if your <a +href="#doctype">DOCTYPE</a> is <kbd>DEFAULT</kbd> (which is +mom’s default). If your DOCTYPE is CHAPTER, use +<a href="#title">TITLE</a> +to set the overall document title for cover pages, document cover +pages, and page headers or footers. +</p> +</div> + +<p style="margin-top: -.5em;"> +When you’re creating a single document, say, an essay or a +short story, you have no need of this macro. +<a href="#title">TITLE</a> +takes care of all your title needs. +</p> + +<p> +However if you’re +<a href="rectoverso.html#collate">collating</a> +a bunch of documents together, say, to print out a report containing +many articles with different titles, or a book of short stories with +different authors, you need DOCTITLE. +</p> + +<p> +DOCTITLE tells mom the title of the complete document (as opposed to +the title of each article or entitled section). +</p> + +<p> +The doctitle string can be caps or caps/lower-case; it’s up to +you. In +<a href="#printstyle">PRINTSTYLE TYPESET</a>, +by default, the doctitle appears in the rightmost position of +<a href="definitions.html#header">page headers</a>, +all in caps unless you turn that feature off (see +<a href="headfootpage.html#_caps">HEADER_<POSITION>_CAPS</a>). +In +<a href="#printstyle">PRINTSTYLE TYPEWRITE</a>, +the doctitle always gets converted to caps. +</p> + +<p> +DOCTITLE accepts multiple arguments, each surrounded +by double-quotes. Each argument is printed on a separate line, +permitting you to create multi-line document titles for use on +<a href="cover.html#cover">Covers</a> +and/or +<a href="cover.html#doc-cover">Doc covers</a>. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +If your +<a href="#doctype">DOCTYPE</a> +is CHAPTER, you don’t need DOCTITLE. TITLE takes care of +everything. +</p> +</div> + +<!-- -SUBTITLE- --> + +<div class="macro-id-overline"> +<h3 id="subtitle" class="macro-id">SUBTITLE</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>SUBTITLE</b> <kbd class="macro-args">[COVER | DOC_COVER] "<subtitle>" ["<2nd line>" ["<3rd line>" ... ] ]</kbd> +</div> +<p class="requires"> +• String arguments must be enclosed in double-quotes +</p> + +<p> +The subtitle string can be caps or caps/lower-case. I recommend +caps/lower case. +</p> + +<p> +SUBTITLE accepts multiple arguments, each surrounded +by double-quotes. Each argument is printed on a separate line, +permitting you to create multi-line subtitles. +</p> + +<p> +If the optional argument, <kbd>COVER</kbd> or <kbd>DOC_COVER</kbd>, +is given to SUBTITLE, the remaining string +arguments represent the subtitle that will appear on cover or +document cover pages (see the +<a href="cover.html#cover-intro">Introduction to cover pages</a> +for a description of the difference between “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: +<br/> +<span class="pre-in-pp"> + .SUBTITLE "The Docheader Subtitle" + .SUBTITLE DOC_COVER "The Document Cover Subtitle" + .SUBTITLE COVER "The Cover Subtitle" +</span> +The first invocation of <kbd>.SUBTITLE</kbd> establishes the +subtitle that appears in the docheader at the top of the first page +of a document. The second invocation establishes the subtitle that +appears on the document cover; the third establishes the subtitle +that appears on the cover (“title”) page. +</p> + +<p> +If you don’t require differing subtitles for doc cover and cover +pages, <kbd>.SUBTITLE</kbd>, without the optional first argument, is +sufficient, provided you give the word, <kbd>SUBTITLE</kbd>, as an +argument to the macro +<a href="cover.html#doc-cover">DOC_COVER</a> +or +<a href="cover.html#cover">COVER</a> +</p> + +<!-- -AUTHOR- --> + +<div class="macro-id-overline"> +<h3 id="author" class="macro-id">AUTHOR</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>AUTHOR</b> <kbd class="macro-args">[COVER | DOC_COVER] "<author>" [ "<author2>" ["<author3>" ... ] ]</kbd> +</div> + +<p class="alias" style="margin-bottom: 0;"> +<i>Alias:</i> <b>EDITOR</b> +</p> +<p class="requires"> +• String arguments must be enclosed in double-quotes +</p> + +<p> +Each author string can hold as many names as you like, e.g. +<br/> +<span class="pre-in-pp" style="margin-bottom: -1em;"> + .AUTHOR "Joe Blow" +</span> +or +<br/> +<span class="pre-in-pp" style="margin-top: -.5em;"> + .AUTHOR "Joe Blow, Jane Doe" "John Hancock" +</span> +Mom prints each string that’s enclosed in double-quotes on a +separate line in the +<a href="definitions.html#docheader">docheader</a>, +however only the first string appears in +<a href="definitions.html#header">page headers</a>. +If you want mom to put something else in the author part of page +headers (say, just the last names of a document’s two +authors), redefine the appropriate part of the header (see +<a href="headfootpage.html#header-control">header/footer control</a>). +</p> + +<p> +The strings can be caps or caps/lower-case. I recommend caps/lower +case. +</p> + +<p> +If the optional argument, <kbd>COVER</kbd> or <kbd>DOC_COVER</kbd>, +is given to AUTHOR, the remaining string arguments represent the +author(s) that will appear on cover or document cover pages (see the +<a href="cover.html#cover-intro">Introduction to cover pages</a> +for a description of the difference between “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: +<br/> +<span class="pre-in-pp"> + .AUTHOR "Joe Blow" + .EDITOR DOC_COVER "John Smith" "and" "Jane Doe" \" EDITOR is an alias for AUTHOR + .AUTHOR COVER "Joe Blow" "(assisted by Jane Doe)" +</span> +The first invocation of <kbd>.AUTHOR</kbd> establishes the author +that appears in the docheader at the top of the first page of +a document and in subsequent page headers/footers. The second +invocation establishes the authors (editors, in this instance) that +appear on the document cover; the third establishes the author(s) +that appear(s) on the cover (“title”) page. +</p> + +<p> +If you don’t require differing authors for doc cover and cover +pages, <kbd>.AUTHOR</kbd>, without the optional first argument, is +sufficient, provided you give the word, <kbd>AUTHOR</kbd> as an +argument to the macro +<a href="cover.html#doc-cover">DOC_COVER</a> +or +<a href="cover.html#cover">COVER</a> +</p> + +<!-- -CHAPTER- --> + +<div class="macro-id-overline"> +<h3 id="chapter" class="macro-id">CHAPTER</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>CHAPTER</b> <kbd class="macro-args"><chapter number></kbd> +</div> + +<p> +The chapter number can be in any form you like—a digit, a roman +numeral, a word. If you choose +<a href="#doctype">DOCTYPE CHAPTER</a>, +mom prints whatever argument you pass CHAPTER beside the word, +“Chapter”, as a single line +<a href="definitions.html#docheader">docheader</a>. +She also puts the same thing in the middle of +<a href="definitions.html#header">page headers</a>. +</p> + +<p> +Please note that if your argument to CHAPTER runs to more than one +word, you must enclose the argument in double-quotes. +</p> + +<p> +If you’re not using DOCTYPE CHAPTER, the macro can +be used to identify any document as a chapter <i>for the purpose of +prepending a chapter number to numbered head elements</i>, provided +you pass it a +<a href="definitions.html#numericargument">numeric argument</a>. +See +<a href="docelement.html#prefix-chapter-number">PREFIX_CHAPTER_NUMBER</a>. +</p> + +<!-- -CHAPTER_STRING- --> + +<h3 id="chapter-string" class="docs">Chapter string</h3> + +<p> +If you’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: +<br/> +<span class="pre"> + .CHAPTER_STRING "Chapître" +</span> +</p> + +<p> +You can also use CHAPTER_STRING if you want +“CHAPTER” (all caps) instead of “Chapter” +(caps/lowercase) in the doc- and page-headers. +</p> + +<!-- -CHAPTER_TITLE- --> + +<div class="macro-id-overline"> +<h3 id="chapter-title" class="macro-id">CHAPTER_TITLE</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>CHAPTER_TITLE</b> <kbd class="macro-args">"<chapter title>" ["<2nd line>" ["<3rd line>" ... ] ]</kbd> +</div> +<p class="requires"> +• Arguments must be enclosed in double-quotes +</p> + +<p> +If, either in addition to or instead of “Chapter +<n>” appearing at the top of chapters, you want your +chapter to have a title, use CHAPTER_TITLE, with your title enclosed +in double-quotes, like this: +<br/> +<span class="pre"> + .CHAPTER_TITLE "The DMCA Nazis" +</span> +</p> + +<p> +CHAPTER_TITLE accepts multiple arguments, each surrounded by +double-quotes. Each argument is printed on a separate line, +permitting you to create multi-line chapter titles in your +docheaders. +</p> + +<p> +If you’ve used +<a href="#chapter">CHAPTER</a> +to give the chapter a number, both “Chapter <n>” +and the chapter title will appear at the top of the chapter, like +this: +<br/> +<span class="pre-in-pp"> + Chapter 1 + The DMCA Nazis +</span> +In such a case, by default, only the chapter’s title will appear in +the +<a href="definitions.html#header">page headers</a>, +not “Chapter <n>”. +</p> + +<p> +If you omit CHAPTER when setting up your reference macros, only the +title will appear, both at the top of page one and in subsequent +page headers. +</p> + +<p> +The style of the chapter title can be altered by +<a href="docelement.html#docelement-control">control macros</a>, +e.g. CHAPTER_TITLE_FAMILY, CHAPTER_TITLE_FONT, etc. The default +family, font and point size are Times Roman, Bold Italic, 4 points +larger than +<a href="definitions.html#running">running text</a>. +</p> + +<!-- -DRAFT- --> + +<div class="macro-id-overline"> +<h3 id="draft" class="macro-id">DRAFT</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>DRAFT</b> <kbd class="macro-args"><draft number></kbd> +</div> + +<p> +DRAFT only gets used with +<a href="#copystyle">COPYSTYLE DRAFT</a>. +If the COPYSTYLE is FINAL (the default), mom ignores DRAFT. DRAFT +accepts both alphabetic and numeric arguments, hence it’s +possible to do either +<br/> +<span class="pre"> + .DRAFT 2 + or + .DRAFT Two +</span> +</p> + +<p> +Mom prints the argument to <kbd>.DRAFT</kbd> (i.e. the draft number) +beside the word “Draft” in the middle part of +<a href="definitions.html#header">page headers</a>. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">A small word of caution:</span> +If your argument to <kbd>.DRAFT</kbd> is more than one word long, +you must enclose the argument in double-quotes. +</p> +</div> + +<p> +You may, if you wish, invoke <kbd>.DRAFT</kbd> without an +argument, in which case, no draft number will be printed beside +“Draft” in headers or footers. +</p> + +<!-- -DRAFT_STRING- --> + +<h3 id="draft-string" class="docs">The draft string</h3> + +<p> +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: +<br/> +<span class="pre"> + .DRAFT_STRING "Jet" +</span> +</p> + +<p> +Equally, DRAFT_STRING can be used to roll your own solution to +something other than the word “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 +<br/> +<span class="pre"> + .DRAFT alpha-three + .DRAFT_STRING "Trial run" +</span> +</p> + +<p> +If you wanted only “Trial run” to appear, entering +<kbd>.DRAFT</kbd> without an argument as well as +<kbd>.DRAFT_STRING "Trial run"</kbd> is how you’d do it. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +If you define both a blank <kbd>.DRAFT</kbd> and a blank +<kbd>.DRAFT_STRING</kbd>, mom skips the draft field in headers +entirely. If this is what you want, this is also the only way +to do it. Simply omitting invocations of <kbd>.DRAFT</kbd> and +<kbd>.DRAFT_STRING</kbd> will result in mom using her default, which +is to print “Draft <number>”. +</p> +</div> + +<!-- -REVISION- --> + +<div class="macro-id-overline"> +<h3 id="revision" class="macro-id">REVISION</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>REVISION</b> <kbd class="macro-args"><revision number></kbd> +</div> + +<p> +REVISION only gets used with +<a href="#copystyle">COPYSTYLE DRAFT</a>. +If the COPYSTYLE is FINAL (the default), mom ignores the REVISION +macro. REVISION accepts both alphabetic and numeric arguments, hence +it’s possible to do either +<br/> +<span class="pre" style="margin-bottom: -1em;"> + .REVISION 2 +</span> +or +<span class="pre" style="margin-top: -.5em;"> + .REVISION Two +</span> +</p> + +<p> +Mom prints the revision number beside the shortform +“Rev.” in the middle part of +<a href="definitions.html#header">page headers</a>. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">A small word of caution:</span> +If your argument to <kbd>.REVISION</kbd> is more than one word long, +you must enclose the argument in double-quotes. +</p> +</div> + +<p> +You may, if you wish, invoke <kbd>.REVISION</kbd> without an +argument, in which case, no revision number will be printed beside +"Rev." in headers or footers. +</p> + +<!-- -REVISION_STRING- --> + +<h3 id="revision-string" class="docs">The revision string</h3> + +<p> +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: +<br/> +<span class="pre"> + .REVISION_STRING "Rév." +</span> +</p> + +<p> +Additionally, you may sometimes want to make use of mom’s +<a href="#copystyle">COPYSTYLE DRAFT</a> +but not actually require any draft information. For example, +you might like mom to indicate only the revision number of +your document. The way to do that is to define an empty +<kbd>.DRAFT</kbd> and <kbd>.DRAFT_STRING</kbd> in addition to +<kbd>.REVISION</kbd>, like this: +<br/> +<span class="pre"> + .DRAFT + .DRAFT_STRING + .REVISION 2 +</span> +</p> + +<p> +Equally, if you want to roll your own solution to what revision +information appears in headers, you could do something like this: +<br/> +<span class="pre"> + .DRAFT + .DRAFT_STRING + .REVISION "two-twenty-two" + .REVISION_STRING "Revision" +</span> +</p> + +<p> +The above, naturally, has no draft information. If you want to roll +your own <kbd>.DRAFT</kbd> and/or <kbd>.DRAFT_STRING</kbd> as well, +simply supply arguments to either or both. +</p> + +<!-- -COPYRIGHT- --> + +<div class="macro-id-overline"> +<h3 id="copyright" class="macro-id">COPYRIGHT</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>COPYRIGHT</b> <kbd class="macro-args">[COVER | DOC_COVER] "<copyright info>"</kbd> +</div> + +<p class="requires"> +• Argument must be enclosed in double-quotes +</p> + +<p> +The argument passed to COPYRIGHT is only used on cover or doc cover +pages, and then only if the argument COPYRIGHT is passed to +<a href="cover.html#cover">COVER</a> +or +<a href="cover.html#doc-cover">DOC_COVER</a>. +Do not include the copyright symbol in the argument passed to +COPYRIGHT; mom puts it in for you. +</p> + +<p> +If the optional argument, <kbd>COVER</kbd> or <kbd>DOC_COVER</kbd>, +is given to COPYRIGHT, the string argument represents the copyright +information that will appear on cover or document cover pages (see +the +<a href="cover.html#cover-intro">Introduction to cover pages</a> +for a description of the difference between “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: +<br/> +<span class="pre-in-pp"> + .COPYRIGHT DOC_COVER "2010 John Smith and Jane Doe" + .COPYRIGHT COVER "2008 Joe Blow" +</span> +The first invocation of <kbd>.COPYRIGHT</kbd> establishes the +copyright information that appears on the document cover; the second +establishes the copyright information that appears on the cover +(“title”) page. +</p> + +<p> +If you don’t require differing copyright information for +doc cover and cover pages, <kbd>.COPYRIGHT</kbd>, without the +optional first argument, is sufficient, provided you give the word, +<kbd>COPYRIGHT</kbd>, as an argument to the macro +<a href="cover.html#doc-cover">DOC_COVER</a> +or +<a href="cover.html#cover">COVER</a> +</p> + +<!-- -MISC- --> + +<div class="macro-id-overline"> +<h3 id="misc" class="macro-id">MISC</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>MISC</b> <kbd class="macro-args">[COVER | DOC_COVER] "<argument 1>" ["<argument 2>" "<argument 3>" ...]</kbd> +</div> + +<p class="requires"> +• String arguments must be enclosed in double-quotes +</p> + +<p> +The argument(s) passed to MISC are only used on cover or doc cover +pages, and then only if the argument <kbd>MISC</kbd> is passed to +<a href="cover.html#cover">COVER</a> +or +<a href="cover.html#doc-cover">DOC_COVER</a>. +MISC can contain any information you like. Each argument appears on +a separate line at the bottom of the cover or doc cover page. +</p> + +<p> +For example, if you’re submitting an essay where the prof has +requested that you include the course number, his name and the date, +you could do +<br/> +<span class="pre-in-pp"> + .MISC "Music History 101" "Professor Hasbeen" "Dec. 24, 2010" +</span> +and the information would appear on the essay’s cover page. +</p> + +<p> +If the optional argument, <kbd>COVER</kbd> or <kbd>DOC_COVER</kbd>, +is given to MISC, the string arguments represent the miscellaneous +information that will appear on cover or document cover pages (see +the +<a href="cover.html#cover-intro">Introduction to cover pages</a> +for a description of the difference between “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: +<br/> +<span class="pre"> + .MISC DOC_COVER "Music History 101" "Professor Hasbeen" + .MISC COVER "Spring Term Paper" +</span> +</p> + +<p> +The first invocation of <kbd>.MISC</kbd> establishes the +miscellaneous information that appears on the document cover; the +second establishes the miscellaneous information that appears on the +cover (“title”) page. +</p> + +<p> +If you don’t require differing miscellaneous information +for doc cover and cover pages, <kbd>.MISC</kbd>, without the +optional first argument, is sufficient, provided you give the word +“MISC” as an argument to the macro +<a href="cover.html#doc-cover">DOC_COVER</a> +or +<a href="cover.html#cover">COVER</a> +</p> + +<!-- -COVER_TITLE- --> + +<div class="macro-id-overline"> +<h3 class="macro-id">COVERTITLE & DOC_COVERTITLE</h3> +</div> + +<div id="covertitle" class="box-macro-args"> +Macro: <b>COVERTITLE</b> <kbd class="macro-args">"<user defined cover page title>" ["<2nd line>" ["<3rd line>" ... ] ]</kbd> +</div> +<p class="requires"> +• Arguments must be enclosed in double-quotes +</p> + +<div id="doc-covertitle" class="box-macro-args"> +Macro: <b>DOC_COVERTITLE</b> <kbd class="macro-args">"<user defined document cover page title>" ["<2nd line>" ["<3rd line>" ... ] ]</kbd> +</div> +<p class="requires"> +• Arguments must be enclosed in double-quotes +</p> + +<p> +The arguments passed to COVERTITLE or DOC_COVERTITLE are only +used on cover or doc cover pages, and then only if the argument +COVERTITLE is passed to +<a href="cover.html#cover">COVER</a> +or +<a href="cover.html#doc-cover">DOC_COVER</a>. +</p> + +<p> +The only time you require a COVERTITLE or DOC_COVERTITLE is when +none of the required first arguments to COVER or DOC_COVER fits +your needs for the title you want to appear on cover (or doc cover) +pages. +</p> + +<p> +COVERTITLE and DOC_COVERTITLE accept multiple arguments, each +surrounded by double-quotes. Each argument is printed on a separate +line, permitting you to create multi-line titles on your cover +and/or doc cover pages. +</p> + +<div class="rule-short"><hr/></div> + +<!-- ======================================================================== --> + +<h2 id="docstyle-macros" class="macro-group">The docstyle macros</h2> + +<p> +The docstyle macros tell mom what type of document you’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. +</p> + +<div class="macro-list-container"> +<h3 id="index-docstyle" class="macro-list">Docstyle macros</h3> +<ul class="macro-list"> + <li><a href="#doctype">DOCTYPE</a> + <ul class="sublist"> + <li><a href="#doctype-underline">DOCTYPE_UNDERLINE</a> – control DOCTYPE <kbd>NAMED</kbd> underlining</li> + </ul></li> + <li><a href="#printstyle">PRINTSTYLE</a> – non-optional macro required for document processing + <ul class="sublist" style="line-height: 140%;"> + <li><a href="#typeset-defaults">Defaults for PRINTSTYLE TYPESET</a></li> + <li><a href="#typewrite-defaults">Defaults for PRINTSTYLE TYPEWRITE</a> + <ul class="sublist sub"> + <li><a href="#typewrite-control">PRINTSTYLE TYPEWRITE control macros</a> – underlining</li> + </ul></li> + </ul></li> + <li><a href="#copystyle">COPYSTYLE</a></li> +</ul> +</div> + +<!-- -DOCTYPE- --> + +<div class="macro-id-overline"> +<h3 id="doctype" class="macro-id">DOCTYPE</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>DOCTYPE</b> <kbd class="macro-args">DEFAULT | CHAPTER | NAMED "<name>" | LETTER</kbd> +</div> + +<p> +The arguments <kbd>DEFAULT,</kbd> <kbd>CHAPTER</kbd> and +<kbd>NAMED</kbd> tell mom what to put in the +<a href="definitions.html#docheader">docheader</a> +and +<a href="definitions.html#header">page headers</a>. +<kbd>LETTER</kbd> tells her that you want to write a letter. +</p> + +<p> +Mom’s default DOCTYPE is <kbd>DEFAULT</kbd>. If that’s +what you want, you don’t have to give a DOCTYPE command. +</p> + +<p> +<kbd>DEFAULT</kbd> prints a +<a href="definitions.html#docheader">docheader</a> +containing the title, subtitle and author information given to the +<a href="#reference-macros">reference macros</a>, +and page headers with the author and title. (See +<a href="headfootpage.html#header-style">Default specs for headers</a> +for how mom outputs each part of the page header.) +</p> + +<p> +<kbd>CHAPTER</kbd> prints “Chapter <n>” in place +of a +<a href="definitions.html#docheader">docheader</a> +(<n> is what you gave to the +<a href="#reference-macros">reference macro</a>, +<kbd><a href="#chapter">CHAPTER</a></kbd>). +If you give the chapter a title with +<a href="#chapter-title">CHAPTER TITLE</a>, +mom prints “Chapter <n>” and the +title underneath. If you omit the +<a href="#chapter">CHAPTER</a> +reference macro but supply a +<a href="#chapter-title">CHAPTER_TITLE</a>, +mom prints only the chapter title. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +For backward compatibility with pre-1.1.5 versions of mom, you can +also supply a chapter title by omitting the CHAPTER reference macro +and supplying a chapter title with +<a href="#chapter-string">CHAPTER_STRING</a>.) +</p> +</div> + +<p> +The page headers in DOCTYPE <kbd>CHAPTER</kbd> contain the author, +the title of the book (which you gave with +<a href="#title">TITLE</a>), +and “Chapter <n>” (or the chapter title). See +<a href="headfootpage.html#header-style">Default Specs for Headers</a> +for mom’s default type parameters for each part of +the page header. +</p> + +<p> +<kbd>NAMED</kbd> takes an additional argument: a name for this +particular kind of document (e.g. outline, synopsis, abstract, +memorandum), enclosed in double-quotes. <kbd>NAMED</kbd> is +identical to <kbd>DEFAULT</kbd> except that mom prints the argument +to <kbd>NAMED</kbd> beneath the +<a href="definitions.html#docheader">docheader</a>, +as well as in page headers. +(See +<a href="headfootpage.html#header-style">Default specs for headers</a> +for how mom outputs each part of the page header.) +</p> + +<p> +Additionally, if you wish the name of this particular kind of +document to be coloured, you can pass DOCTYPE <kbd>NAMED</kbd> a +third (optional) argument: the name of a colour pre-defined (or +“initialized”) with +<a href="color.html#newcolor">NEWCOLOR</a> +or +<a href="color.html#xcolor">XCOLOR</a>. +For example, if you have a doctype named “Warning”, +and you’d like “Warning” to be in red, assuming you’ve +pre-defined (or “initialized”) the color, red, this is +what the DOCTYPE entry would look like: +<br/> +<span class="pre"> + .DOCTYPE NAMED "Warning" red +</span> +</p> + +<div class="box-tip" style="margin-top: 1.5em;"> +<h3 id="doctype-underline" class="docs control">How to control DOCTYPE NAMED underlining</h3> + +<p style="tip"> +By default, the string passed to DOCTYPE <kbd>NAMED</kbd> is +underlined in the docheader, and on document-cover pages and cover +(“title”) pages. (See the +<a href="cover.html#intro">Introduction to covers</a> +for the difference between “doc cover” and +“cover” pages.) +</p> + +<p> +Formerly, this underlining was carved in stone. As of version 1.5 +of mom, you can use the macro DOCTYPE_UNDERLINE to set the weight of +the underline and its distance from where the doctype-name appears +in the docheader (doc covers and covers handle underlining of the +doctype-name differently; see +<a href="cover.html#cover-underline">COVER_UNDERLINE</a>), +or simply toggle doctype underlining on or off. Mom’s default +is to underline the doctype-name. +</p> + +<p> +The order of arguments is <kbd>weight</kbd>, optionally followed by +<kbd>gap</kbd>, where “gap” is the distance from the +<a href="definitions.html#baseline">baseline</a> +of the doctype-name to the underline. +</p> + +<p> +The <kbd>weight</kbd> argument is given in points, or fractions +thereof, and must not have the +<a href="definitions.html#unitofmeasure">unit of measure</a>, +<kbd>p</kbd>, appended. Like +<a href="inlines.html#rule-weight">RULE_WEIGHT</a>, +weights must be greater than 0 and less than 100. Mom’s +default for DOCTYPE <kbd>NAMED</kbd> underlining is 1/2 point. +</p> + +<p> +The <kbd>gap</kbd> argument can be given using any unit of measure, +and must have the unit of measure appended to the argument. +The distance of the gap is measured from the baseline of the +DOCTYPE <kbd>NAMED</kbd> name to the upper edge of the underline. +Mom’s default gap for named-doctype underlining is 2 points. +</p> + +<p> +As an example, supposed you want the doctype-name underlined in the +docheader with a 2-point rule separated from the head by 3 points. +The way to accomplish it is: +<br/> +<span class="pre-in-pp"> + .DOCTYPE_UNDERLINE 2 3p +</span> +If you wanted the same thing, but were content with mom’s +default gap of 2 points, +<br/> +<span class="pre-in-pp"> + .DOCTYPE_UNDERLINE 4 +</span> +would do the trick. +</p> + +<p> +If you merely want to toggle the underlining of +the doctype-name in docheaders on or off, invoke +<kbd>.DOCTYPE_UNDERLINE</kbd> by itself to turn the underlining on, +or <kbd>.DOCTYPE_UNDERLINE OFF</kbd> (or NO, X, etc.) +</p> + +<p class="tip-bottom"> +Please note that if you supply a weight to DOCTYPE_UNDERLINE, and +optionally a gap, you also turn the underlining of the doctype-name +in docheaders on; if this is not what you want, you must turn the +underlining off manually afterwards. +</p> +</div> + +<p> +<kbd>LETTER</kbd> tells mom you’re writing a letter. See the +section +<a href="letters.html#letters">Writing Letters</a> +for instructions on using mom to format letters. +</p> + +<!-- -PRINTSTYLE- --> + +<div class="macro-id-overline"> +<h3 id="printstyle" class="macro-id">PRINTSTYLE</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>PRINTSTYLE</b> <kbd class="macro-args">TYPESET | TYPEWRITE [ SINGLESPACE ]</kbd> +</div> + +<p class="requires"> +• Required for document processing +<br/> +Must come before any changes to default document style +</p> + +<p> +PRINTSTYLE tells mom whether to typeset a document, or to print it +out “typewritten, doubled-spaced”. +</p> + +<div class="box-important"> +<p class="tip-top"> +<span class="important">Important:</span> +<b>This macro may not be omitted.</b> In order for document +processing to take place, mom requires a PRINTSTYLE. If you +don’t give one, mom will warn you on stderr and print a single +page with a nasty message. +</p> + +<p class="tip-bottom"> +Furthermore, PRINTSTYLE must come before any changes to mom’s +default typestyle parameters. (This applies primarily to, but is by +no means restricted to, PRINTSTYLE <kbd>TYPESET</kbd>.) PRINTSTYLE +sets up complete templates that include default papersize, margins, +family, fonts, point sizes, and so on. Therefore, changes to any +aspect of document style must come afterwards. +</p> +</div> + +<p> +<kbd>TYPESET</kbd>, as the argument implies, typesets +documents (by default in Times Roman; see +<a href="#typeset-defaults">TYPESET defaults</a>). +You have full access to all the +<a href="typesetting.html#macros-typesetting">typesetting macros</a> +as well as the +<a href="definitions.html#style-control">style control macros</a> +of document processing. +</p> + +<p> +As mentioned above, PRINTSTYLE <kbd>TYPESET</kbd> must come before +any changes to mom’s default typographic settings. For +example, +<br/> +<span class="pre-in-pp"> + .PAPER A4 + .LS 14 + .PRINTSTYLE TYPESET +</span> +will not changes mom’s default paper size to A4, +nor her default document leading 14 points, whereas +<br/> +<span class="pre-in-pp"> + .PRINTSTYLE TYPESET + .PAPER A4 + .LS 14 +</span> +will. +</p> + +<p> +With <kbd>TYPEWRITE</kbd>, mom does her best to reproduce the look +and feel of typewritten, double-spaced copy (see +<a href="#typewrite-defaults">TYPEWRITE defaults</a>). +<a href="docelement.html#docelement-control">Control macros</a> +and +<a href="typesetting.html#intro-macros-typesetting">typesetting macros</a> +that alter family, font, point size, and +<a href="definitions.html#leading">leading</a> +are (mostly) ignored. An important exception is +<a href="headfootpage.html#hdrftr-global-size">HEADER_SIZE</a> +(and, by extension, FOOTER_SIZE), which allows you to reduce the +point size of headers/footers should they become too crowded. Most +of mom’s inlines affecting the appearance of type are also +ignored +(<kbd><a href="inlines.html#inline-size-mom">\*S[<size>]</a></kbd> +is an exception; there may be a few others). +</p> + +<p> +In short, <kbd>TYPEWRITE</kbd> never produces effects +other than those available on a typewriter. Don’t be fooled +by how brainless this sounds; mom is remarkably sophisticated when +it comes to conveying the typographic sense of a document within the +confines of <kbd>TYPEWRITE</kbd>. +</p> + +<p> +The primary uses of <kbd>TYPEWRITE</kbd> are: outputting hard +copy drafts of your work (for editing) and producing documents +for submission to publishers and agents who (wisely) insist on +typewritten, double-spaced copy. To get a nicely typeset version of +work that’s in the submission phase of its life (say, to show +fellow writers for critiquing), simply change <kbd>TYPEWRITE</kbd> +to <kbd>TYPESET</kbd> and print out a copy. +</p> + +<p> +If, for some reason, you would prefer the output of +<kbd>TYPEWRITE</kbd> single-spaced, pass PRINTSTYLE +<kbd>TYPEWRITE</kbd> the optional argument, <kbd>SINGLESPACE</kbd>. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +If you absolutely must have a leading other than typewriter double- +or singlespaced, the only way to get it is with the +<a href="#doc-lead">DOC_LEAD</a> +macro, and then only if DOC_LEAD is set <i>before</i> you invoke the +<a href="#start">START</a> +macro. +</p> +</div> + +<div class="defaults-container"> +<h3 id="typeset-defaults" class="docs defaults" style="margin-top: 0;">PRINTSTYLE TYPESET defaults</h3> +<span class="pre defaults"> + Family = Times Roman + Point size = 12.5 + Paragraph leading = 16 points, adjusted + Fill mode = justified + Hyphenation = enabled + max. lines = 2 + margin = 36 points + interword adjustment = 1 point + Kerning = enabled + Ligatures = enabled + Smartquotes = enabled + Word space = groff default + Sentence space = 0 +</span> +</div> + +<div class="defaults-container"> +<h3 id="typewrite-defaults" class="docs defaults" style="margin-top: 0;">PRINTSTYLE TYPEWRITE defaults</h3> +<span class="pre defaults"> + Family = Courier + Italics = underlined + Point size = 12 + Paragraph leading = 24 points, adjusted; 12 points for SINGLESPACE + Fill mode = left + Hyphenation = disabled + Kerning = disabled + Ligatures = disabled + Smartquotes = disabled + Word space = groff default + Sentence space = groff default + Columns = ignored +</span> +</div> + +<div class="box-tip" style="margin-top: 1.5em;"> +<h3 id="typewrite-control" class="docs control">PRINTSTYLE TYPEWRITE control macros (underlining)</h3> + +<p> +In PRINTSTYLE <kbd>TYPEWRITE</kbd>, mom, by default, underlines +anything that looks like italics. This includes the +<a href="typesetting.html#slant-inline"><kbd>\*[SLANT]</kbd></a> +<a href="definitions.html#inlines">inline escape</a> +for pseudo-italics. +</p> + +<p> +If you’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 +<br/> +<span class="pre-in-pp"> + .ITALIC_MEANS_ITALIC +</span> +and +<span class="pre-in-pp"> + .SLANT_MEANS_SLANT +</span> +Neither requires an argument. +</p> + +<p> +Although it’s unlikely, should you wish to reverse +the sense of these macros in the midst of a document, +<kbd>.UNDERLINE_ITALIC</kbd> and <kbd>.UNDERLINE_SLANT</kbd> restore +underlining of italics and pseudo-italics. +</p> + +<p> +Additionally, by default, mom underlines +<a href="definitions.html#quotes">quotes</a> +(but not +<a href="definitions.html#blockquotes">blockquotes</a>) +in PRINTSTYLE <kbd>TYPEWRITE</kbd>. If you don’t like this +behaviour, turn it off with +<br/> +<span class="pre"> + .UNDERLINE_QUOTES OFF +</span> +</p> + +<p> +To turn underlining of quotes back on, use UNDERLINE_QUOTES without +an argument. +</p> + +<p class="tip-bottom"> +While most of the +<a href="docelement.html#docelement-control">control macros</a> +have no effect on <b>PRINTSTYLE TYPEWRITE</b>, there +is an important exception: +<a href="headfootpage.html#hdrftr-global-size">HEADER_SIZE</a> +(and by extension, FOOTER_SIZE). This is +particularly useful for reducing the point size of +headers/footers should they become crowded (quite likely to +happen if the title of your document is long and your +<kbd><a href="#copystyle">COPYSTYLE</a></kbd> +is DRAFT). +</p> +</div> + +<!-- -COPYSTYLE- --> + +<div class="macro-id-overline"> +<h3 id="copystyle" class="macro-id">COPYSTYLE</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>COPYSTYLE</b> <kbd class="macro-args">DRAFT | FINAL</kbd> +</div> + +<p> +Mom’s default COPYSTYLE is <kbd>FINAL</kbd>, so you +don’t have to use this macro unless you want to. +</p> + +<p> +COPYSTYLE <kbd>DRAFT</kbd> exhibits the following behaviour: +</p> +<ol style="margin-top: -.5em;"> + <li>Documents start on page 1, whether or not you + request a different starting page number with + <a href="headfootpage.html#pagenumber">PAGENUMBER</a>. + </li> + <li>Page numbers are set in lower case roman numerals.</li> + <li>The draft number supplied by + <a href="#draft">DRAFT</a> + and a revision number, if supplied with + <a href="#revision">REVISION</a> + (see + <a href="#reference-macros">reference macros</a>), + appear in the centre part of + <a href="definitions.html#header">page headers</a> + (or footers, depending on which you’ve selected) along with + any other information that normally appears there. + </li> +</ol> + +<div class="box-important"> +<p class="tip"> +<span class="important">Important:</span> +If you define your own centre part for page headers with +<a href="headfootpage.html#hdrftr-center">HEADER_CENTER</a>, +no draft and/or revision number will appear there. If you want +draft and revision information in this circumstance, use +<a href="headfootpage.html#draft-with-pagenumber">DRAFT_WITH_PAGENUMBER</a>. +</p> +</div> + +<p> +COPYSTYLE <kbd>FINAL</kbd> differs from <kbd>DRAFT</kbd> in that: +</p> +<ol style="margin-top: -.5em;"> + <li>It respects the starting page number you give the document.</li> + <li>Page numbers are set in normal (Arabic) digits.</li> + <li>No draft or revision number appears in the page headers.</li> +</ol> + +<div class="box-tip"> +<p id="copystyle-note" class="tip"> +<span class="note">Note:</span> +The centre part of page headers can get crowded, especially with +<a href="docprocessing.html#doctype">DOCTYPE <kbd>CHAPTER</kbd></a> +and +<a href="docprocessing.html#doctype">DOCTYPE <kbd>NAMED</kbd></a>, +when the COPYSTYLE is <kbd>DRAFT</kbd>. Three mechanisms are +available to overcome this problem. One is to reduce the overall +size of headers (with +<a href="headfootpage.html#hdrftr-global-size">HEADER_SIZE</a>). +Another, which only works with +<a href="docprocessing.html#printstyle">PRINTSTYLE <kbd>TYPESET</kbd></a>, +is to reduce the size of the header’s centre part only (with +<a href="headfootpage.html#_size">HEADER_CENTER_SIZE</a>). +And finally, you can elect to have the draft/revision information +attached to page numbers instead of having it appear in the centre +of page headers (see +<a href="headfootpage.html#draft-with-pagenumber">DRAFT_WITH_PAGENUMBER</a>). +</p> +</div> + +<div class="rule-short"><hr/></div> + +<!-- ======================================================================== --> + +<h2 id="start-macro" class="macro-group">Initiate document processing</h2> + +<p> +In order to use mom’s document element macros (tags), you have +to tell her you want them. The macro to do this is +<a href="#start">START</a>. +</p> + +<p> +START collects the information you gave mom in the setup section at +the top of your file (see +<a href="#docprocessing-tut">Tutorial – Setting up a mom document</a>), +merges it with her defaults, sets up headers and page numbering, +and prepares mom to process your document using the document +element tags. No document processing takes place until you invoke +<kbd>.START</kbd>. +</p> + +<!-- -START- --> + +<div class="macro-id-overline"> +<h3 id="start" class="macro-id">START</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>START</b> +</div> +<p class="requires"> +• Required for document processing +</p> + +<p> +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 +<a href="typesetting.html#macros-typesetting">typesetting macros</a>), +don’t use START. +</p> + +<p> +At a barest minimum before START, you must enter a +<a href="#printstyle">PRINTSTYLE</a> +command. +</p> + +<div class="rule-short"><hr/></div> + +<!-- ======================================================================== --> + +<h2 id="style-before-start" class="macro-group">Establishing type and formatting parameters before START</h2> + +<p> +In the third (optional) part of setting up a document (see +<a href="#docprocessing-tut">Tutorial – Setting up a mom document</a>), +you can use the +<a href="typesetting.html">typesetting macros</a> +to change mom’s document-wide defaults for margins, +line length, family, base point size, +<a href="definitions.html#leading">leading</a>, +and justification style. +</p> + +<p> +Two additional style concerns have to be addressed here (i.e. in +macros before +<a href="#start">START</a>): +changes to the +<a href="definitions.html#docheader">docheader</a>, +and whether you want you want the document’s nominal leading +adjusted to fill pages fully to the bottom margin. +</p> + +<div class="macro-list-container" style="margin-top: 2em;"> +<h3 id="index-style-before-start" class="macro-list">Type & formatting parameters before START</h3> +<ul class="macro-list"> + <li><a href="#type-before-start">Behaviour of the typesetting macros before START</a> + <ul class="sublist" style="line-height: 120%; margin-bottom: .25em;"> + <li><a href="#meanings">List of meanings</a></li> + <li><a href="#lrc-note">Special note on LEFT, RIGHT and CENTER</a></li> + <li><a href="#include">Including (sourcing) style sheets and files</a></li> + <li><a href="#color">Initializing colors</a></li> + </ul></li> + <li><a href="#doc-lead-adjust">DOC_LEAD_ADJUST</a> – adjust linespacing to fill pages and align bottom margins</li> + <li><a href="#docheader">DOCHEADER</a> + <ul class="sublist" style="line-height: 120%;"> + <li><a href="#docheader-control">Docheader control</a></li> + </ul></li> + <li><a href="#columns">COLUMNS</a> + <ul class="sublist" style="line-height: 120%;"> + <li><a href="#col-next">COL_NEXT</a></li> + <li><a href="#col-break">COL_BREAK</a></li> + </ul></li> +</ul> +</div> + +<h3 id="type-before-start" class="docs">Behaviour of the typesetting macros before START</h3> + +<p> +From time to time (or maybe frequently), you’ll want the +overall look of a document to differ from mom’s defaults. +Perhaps you’d like her to use a different +<a href="definitions.html#family">family</a>, +or a different overall +<a href="definitions.html#leading">leading</a>, +or have different left and/or right page margins. +</p> + +<p> +To accomplish such alterations, use the appropriate +<a href="typesetting.html#macros-typesetting">typesetting macros</a> +(listed below) after +<a href="#printstyle">PRINTSTYLE</a> +and before +<a href="#start">START</a>. +</p> + +<p> +More than one user has, quite understandably, not fully grasped the +significance of the preceding sentence. The part they’ve missed is +<i>after</i> PRINTSTYLE. +</p> + +<p> +Changes to any aspect of the default look and/or formatting of a mom +document must come after PRINTSTYLE. For example, it might seem +natural to set up page margins at the very top of a document with +<br/> +<span class="pre-in-pp"> + .L_MARGIN 1i + .R_MARGIN 1.5i +</span> +However, when you invoke <kbd>.PRINTSTYLE</kbd>, those margins +will be overridden. The correct place to set margins—and +all other changes to the look of a document—is <i>after</i> +PRINTSTYLE. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +Don’t use the macros listed in +<a href="#doc-param-macros">Changing document-wide typesetting parameters after START</a> +prior to START; they are exclusively for use +afterwards. +</p> +</div> + +<div id="meanings" class="defaults-container"> +<h3 class="docs defaults" style="margin-top: 0;">Meanings</h3> +<p style="margin-left: 9px; margin-top: -.25em;"> +When used before START, the +<a href="typesetting.html#macros-typesetting">typesetting macros</a>, +below have the following meanings: +<br/> +<span class="pre"> + L_MARGIN Left margin of pages, including headers/footers + R_MARGIN Right margin of pages, including headers/footers + T_MARGIN The point at which running text (i.e. not + headers/footers or page numbers) starts on each + page + B_MARGIN* The point at which running text (i.e. not + (see note) headers/footers or page numbers) ends on each page + + PAGE If you use PAGE, its final four arguments have the + same meaning as L_ R_ T_ and B_MARGIN (above). + + LL The line length for everything on the page; + equivalent to setting the right margin with + R_MARGIN + FAMILY The family of all type in the document + PT_SIZE The point size of type in paragraphs; mom uses + this to calculate automatic point size changes + (e.g. for heads, footnotes, quotes, headers, etc) + LS/AUTOLEAD** The leading used in paragraphs; all leading and + spacing of running text is calculated from this + + QUAD/JUSTIFY Affects paragraphs only + LEFT*** No effect + RIGHT*** No effect + CENTER*** No effect + +------ + *See <a href="headfootpage.html#footer-margin">FOOTER MARGIN AND BOTTOM MARGIN</a> for an important warning + **See <kbd><a href="#doc-lead-adjust">DOC_LEAD_ADJUST</a></kbd> +***See <a href="#lrc-note">Special note</a> +</span> +</p> +</div> + +<p> +Other macros that deal with type style, or refinements thereof +(<b>KERN, LIGATURES, HY, WS, SS,</b> etc.), behave normally. +It is not recommended that you set up tabs or indents prior to +START. +</p> + +<p> +If you want to change any of the basic parameters (above) +<i>after</i> START and have them affect a document globally (as if +you’d entered them <i>before</i> START), you must use the macros +listed in +<a href="#doc-param-macros">Changing document-wide style parameters after START</a>. +</p> + +<h4 id="lrc-note" class="docs">Special note on LEFT, RIGHT and CENTER prior to START</h4> + +<p> +In a word, these three macros have no effect on document processing +when invoked prior to START. +</p> + +<p> +All mom’s document element tags (PP, HEAD, BLOCKQUOTE, +FOOTNOTE, etc.) except +<a href="docelement.html#quote">QUOTE</a> +set a +<a href="definitions.html#filled">fill mode</a> +as soon as they’re invoked. If you wish to turn fill mode off +for the duration of any tag (with +<a href="typesetting.html#lrc">LEFT, RIGHT or CENTER</a>) +you must do so immediately after invoking the tag. Furthermore, +the change affects <i>only</i> the current invocation of the tag. +Subsequent invocations of the same tag for which you want the same +change require that you invoke <kbd>.LEFT</kbd>, <kbd>.RIGHT</kbd> +or <kbd> CENTER</kbd> immediately after every invocation of the tag. +</p> + +<!-- -INCLUDE- --> + +<h4 id="include" class="docs">Including (sourcing) style sheets and files</h4> + +<p> +If you routinely make the same changes to mom’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 +<a href="#printstyle">PRINTSTYLE</a> +and before +<a href="#start">START</a>. +</p> + +<p> +Say, for example, in a particular kind of document, you always +want main heads set in Helvetica Bold Italic, flush left, +with no underscore. You’d create a file, let’s call it +<kbd>head-template</kbd>, in which you’d place the pertinent HEAD +control macros. +<br/> +<span class="pre-in-pp"> + .HEAD_FAMILY H + .HEAD_FONT BI + .HEAD_QUAD L + .HEAD_UNDERLINE OFF +</span> +Then, in the preliminary document set-up section of your main file, +you’d include the style sheet, or template, like this: +<br/> +<span class="pre-in-pp"> + .TITLE "Sample Document + .AUTHOR "Joe Blow + .PRINTSTYLE TYPESET + \# + .INCLUDE head-template + \# + .START +</span> + +The blank comment lines ( <kbd>\#</kbd> ) aren’t required, but +they do make your file(s) easier to read. +</p> + +<p> +If the file to be included is in the same directory as the file +you’re working, you simply enter the filename after +<kbd>.INCLUDE</kbd>. If the file’s in another directory, you must +provide a full path name to it. For example, if you’re working in +a directory called <kbd>/home/joe/stories</kbd> and your +style-sheet is in <kbd>/home/joe/style-sheets</kbd>, the above +example would have to look like this: +<br/> +<span class="pre-in-pp"> + .TITLE "Sample Document + .AUTHOR "Joe Blow + .PRINTSTYLE TYPESET + \# + .INCLUDE /home/joe/style-sheets/head-template + \# + .START +</span> +</p> + +<p> +INCLUDE is not restricted to style sheets or templates. You can +include any file at any point into a document, provided the file +contains only text and valid groff or mom formatting commands. +Neither is INCLUDE restricted to use with mom’s document +processing macros. You can use it in plain typeset documents as +well. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="experts">Experts:</span> +INCLUDE is an alias for the groff request, <kbd>.so</kbd>. Mix 'n' +match with impunity. +</p> +</div> + +<!-- -COLOUR- --> + +<h4 id="color" class="docs">Initializing colours</h4> + +<p> +Although it doesn’t really matter where you define/initialize +colours for use in document processing (see +<a href="color.html#newcolor">NEWCOLOR</a> +and +<a href="color.html#xcolor">XCOLOR</a> +in the section +<a href="color.html#color-intro">Coloured text</a>), +I recommend doing so before you begin document processing with +<kbd><a href="#start">START</a></kbd>. +</p> + +<p> +The macro, +<a href="color.html#color">COLOR</a>, +and the +<a href="definitions.html#inlines">inline escape</a>, +<a href="color.html#color-inline"><kbd>\[<colorname>]</kbd></a>, +can be used at any time during document processing for occasional +colour effects. However, consistent and reliable colourizing of +various document elements (the docheader, heads, linebreaks, +footnotes, pagenumbers, and so on) must be managed through the use +of the +<a href="docelement.html#docelement-control">document element control macros</a>. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +If you plan to have mom generate a +<a href="docelement.html#toc">table of contents</a>, +do not embed colour +<a href="definitions.html#inlines">inline escapes</a> +(<a href="color.html#color-inline"><kbd>\[<colorname>]</kbd></a>) +in the +<a href="definitions.html#stringargument">string arguments</a> +given to any of the +<a href="docprocessing.html#reference-macros">reference macros</a>, +nor in the string arguments given to +<a href="docelement.html#head">HEAD</a>, +<a href="docelement.html#subhead">SUBHEAD</a> +or +<a href="docelement.html#parahead">PARAHEAD</a>. +Use, rather, the +<a href="definitions.html#controlmacro">control macros</a> +mom provides to automatically colourize these +elements. +</p> +</div> + +<!-- -DOC LEAD ADJUST- --> + +<div class="macro-id-overline"> +<h3 id="doc-lead-adjust" class="macro-id">Adjust linespacing to fill pages and align bottom margins</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>DOC_LEAD_ADJUST</b> <kbd class="macro-args">toggle</kbd> +</div> + +<p class="requires"> +• Must come after +<a href="typesetting.html#ls"><span class="normal">LS</span></a> +or +<a href="typesetting.html.#autoloead"><span class="normal">AUTOLEAD</span></a> +and before +<a href="#start"><span class="normal">START</span></a> +</p> + +<p> +DOC_LEAD_ADJUST is a special macro to adjust document +<a href="definitions.html#leading">leading</a> +so that bottom margins fall precisely where you expect. +</p> + +<p> +When you invoke <kbd>.DOC_LEAD_ADJUST</kbd>, mom takes the number +of lines that fit on the page at your requested leading, then +incrementally adds +<a href="definitions.html#units">machine units</a> +to the leading until the maximum number of lines at the new leading +that fit on the page coincides perfectly with the bottom margin of +<a href="definitions.html#running">running text</a>. +</p> + +<p> +In most instances, the difference between the requested lead and +the adjusted lead is unnoticeable, and since in almost all cases +adjusted leading is what you want, it’s mom’s default +and you don't have to invoke it explicitly. +</p> + +<p> +However, should you not want adjusted document leading, you must +turn it off manually, like this: +<br/> +<span class="pre"> + .DOC_LEAD_ADJUST OFF +</span> +</p> + +<p> +If you set the document leading prior to START with +<a href="typesetting.html#leading">LS</a> +or +<a href="typesetting.html#autolead">AUTOLEAD</a>, +DOC_LEAD_ADJUST <kbd>OFF</kbd> must come afterwards, like +this: +<br/> +<span class="pre-in-pp"> + .LS 12 + .DOC_LEAD_ADJUST OFF +</span> +In this scenario, the maximum number of lines that fit on a page at +a +<a href="definitions.html#leading">leading</a> +of 12 +<a href="definitions.html#picaspoints">points</a> +determine where mom ends a page. The effect will be that last lines +usually fall (slightly) short of the “official” bottom +margin. +</p> + +<p> +In +<a href="docprocessing.html#printstyle">PRINTSTYLE</a> <kbd>TYPEWRITE</kbd>, +the leading is always adjusted and can’t be turned off. +</p> + +<div class="box-tip"> +<p class="tip-top"> +<span class="note">Note:</span> +DOC_LEAD_ADJUST, if used, must be invoked after +<a href="typesetting.html#leading">LS</a> +or +<a href="typesetting.html#autolead">AUTOLEAD</a> +and before +<a href="#start">START</a>. +</p> + +<p class="tip-bottom"> +<span class="additional-note">Additional note:</span> +Even if you disable DOC_LEAD_ADJUST, mom will still adjust the +leading of endnotes pages and toc pages. See +<a href="docelement.html#endnote-lead">ENDNOTE_LEAD</a> +and +<a href="docelement.html#toc-lead">TOC_LEAD</a> +for an explanation of how to disable this default behaviour. +</p> +</div> + +<!-- -DOCHEADER- --> + +<div class="macro-id-overline"> +<h3 id="docheader" class="macro-id">Managing the docheader</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>DOCHEADER</b> <kbd class="macro-args"><toggle> [ distance to advance from top of page ]</kbd> +</div> + +<p class="requires"> +• Must come before +<a href="#start"><span class="normal">START</span></a>; <kbd><span class="normal">distance</span></kbd> requires a <a href="definitions.html#unitofmeasure">unit of measure</a> +</p> + +<p> +By default, mom prints a +<a href="definitions.html#docheader">docheader</a> +on the first page of any document (see +<a href="#docheader-desc">below</a> +for a description of the docheader). If you don’t want a docheader, +turn it off with +<br/> +<span class="pre-in-pp"> + .DOCHEADER OFF +</span> +DOCHEADER is a toggle macro, so the argument doesn’t +have to be OFF; it can be anything you like. +</p> + +<p> +If you turn the docheader off, mom, by default, starts +the running text of your document on the same top +<a href="definitions.html#baseline">baseline</a> +as all subsequent pages. If you’d like her to start at a different +vertical position, give her the distance you’d like as a second +argument. +<br/> +<span class="pre-in-pp"> + .DOCHEADER OFF 1.5i +</span> +This starts the document 1.5 inches from the top of the page PLUS +whatever spacing adjustment mom has to make in order to ensure that +the first baseline of running text falls on a “valid” +baseline (i.e. one that ensures that the bottom margin of the first +page falls where it should). The distance is measured from the top +edge of the paper to the +<a href="definitions.html#baseline">baseline</a> +of the first line of type. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="tip">Tip:</span> +Since no document processing happens until you invoke +<a href="#start"><kbd>.START</kbd></a>—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 +<kbd>.DOCHEADER OFF</kbd> with its optional distance +argument to ensure that the body of your document starts where +you want. You can even insert a PostScript image file (see <a +href="docelement.html#pspic">PSPIC)</a>. +</p> +</div> + +<!-- DOCHEADER CONTROL --> + +<h3 id="docheader-control" class="docs">Docheader control: How to change the look of docheaders</h3> + +<p> +In +<a href="#printstyle">PRINTSTYLE <kbd>TYPEWRITE</kbd></a>, +the look of docheaders is carved in stone. In +<a href="#printstyle">PRINTSTYLE <kbd>TYPESET</kbd></a>, +however, you can make a lot of changes. Macros that alter +docheaders must come before +<a href="#start">START</a>. +</p> + +<h4 id="docheader-desc" class="docs">Docheader description</h4> + +<p> +A typeset docheader has the following characteristics: +</p> +<div class="box-code" style="margin-left: 24px;"> +<span class="pre" style="color: #302419;"> + TITLE bold, 3.5 points larger than running text (not necessarily caps) + Subtitle medium, same size as running text + by medium italic, same size as running text + Author(s) medium italic, same size as running text + +(Document type) bold italic, underscored, 3 points larger than running text + +</span> +</div> + +<p> +Or, if the +<a href="#doctype">DOCTYPE</a> +is <kbd>CHAPTER</kbd>, +</p> +<div class="box-code" style="margin-left: 24px;"> +<span class="pre" style="color: #302419;"> + Chapter <n> bold, 4 points larger than running text +Chapter Title bold italic, 4 points larger than running text + +</span> +</div> + +<p> +The +<a href="definitions.html#family">family</a> +is the prevailing family of the whole document. Title, subtitle, +author and document type are what you supply with the +<a href="#reference-macros">reference macros</a>. +Any you leave out will not appear; mom will compensate: + +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +If your DOCTYPE is <kbd>CHAPTER</kbd> and you have both “Chapter +<n>” and a “Chapter Title” (as above), mom +inserts a small amount of whitespace between them, equal to +one-quarter of the <a href="definitions.html#leading">leading</a> in +effect. If this doesn’t suit you, you can alter the space by +including the +<a href="definitions.html#inlines">inline escapes</a>, +<a href="inlines.html#up"><kbd>\*[UP]</kbd></a> +or +<a href="inlines.html#down"><kbd>\*[DOWN]</kbd></a>, +in the argument you pass to +<a href="#chapter-title">CHAPTER_TITLE</a>, +like this: +<br/> +<span class="pre-in-pp" style="margin-bottom: -1em;"> + .CHAPTER_TITLE "\*[DOWN 2p]Why Not Patent Calculus?" +</span> +or +<span class="pre-in-pp" style="margin-top: -.5em;"> + .CHAPTER_TITLE "\*[UP 2p]Why Not Patent Calculus?" +</span> +</p> +</div> + +<div class="macro-list-container"> +<h3 id="index-docheader-control" class="macro-list">Docheader control</h3> +<ol class="macro-list"> + <li><a href="#change-start">Change the starting position of the docheader</a></li> + <li><a href="#docheader-quad">Change quad direction the entire docheader</a></li> + <li><a href="#docheader-family">Change the family of the entire docheader</a></li> + <li><a href="#change-family">Change the family of individual docheader elements</a></li> + <li><a href="#change-font">Change the font of individual docheader elements</a></li> + <li><a href="#change-size">Adjust the size of docheader elements</a></li> + <li><a href="#adjust-leading">Adjust the docheader leading</a></li> + <li><a href="#docheader-color">Change the colour of the entire docheader</a></li> + <li><a href="#change-color">Change the colour of the individual docheader elements</a></li> + <li><a href="#change-attribute">Change the attribution string (“by”)</a></li> +</ol> +</div> + +<h4 id="change-start" class="docs">1. Change the starting position of the docheader</h4> + +<p> +By default, a docheader starts on the same +<a href="definitions.html#baseline">baseline</a> +as +<a href="definitions.html#running">running text</a>. +If you’d like it to start somewhere else, use the macro, +DOCHEADER_ADVANCE, and give it the distance you want (measured from +the top edge of the paper to the first baseline of the docheader), +like this: +<br/> +<span class="pre-in-pp"> + .DOCHEADER_ADVANCE 4P +</span> +A +<a href="definitions.html#unitofmeasure">unit of measure</a> +is required. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +If +<a href="headfootpage.html#headers">HEADERS</a> +are <kbd>OFF</kbd>, mom’s normal top margin for +<a href="definitions.html#running">running text</a> +(7.5 +<a href="definitions.html#picaspoints">picas</a>) +changes to 6 picas (visually approx. 1 inch). Since the first +baseline of the docheader falls on the same baseline as the first +line of running text (on pages after page 1), you might find the +docheaders a bit high when headers are off. Use DOCHEADER_ADVANCE +to place them where you want. +</p> +</div> + +<h4 id="docheader-quad" class="docs">2. Change the quad direction of the docheader</h4> + +<p> +By default, mom centers the docheader. If you’d prefer to +have your docheaders set flush left or right, or need to restore +the default centering, invoke <kbd>.DOCHEADER_QUAD</kbd> with the +quad direction you want, either <kbd>LEFT</kbd> (or <kbd>L</kbd>), +<kbd>RIGHT</kbd> (or <kbd>R</kbd>) or <kbd>CENTER</kbd> (or +<kbd>C</kbd>). +</p> + +<h4 id="docheader-family" class="docs">3. Change the family of the entire docheader</h4> + +<p> +By default, mom sets the docheader in the same +family used for +<a href="definitions.html#running">running text</a>. +If you’d prefer to have your docheaders set in a different +family, invoke <kbd>.DOCHEADER_FAMILY</kbd> with the family you +want. The argument to DOCHEADER_FAMILY is the same as for +<a href="typesetting.html#family">FAMILY</a>. +</p> + +<p> +For example, mom’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, +<br/> +<span class="pre-in-pp"> + .DOCHEADER_FAMILY H +</span> +is how you’d do it. +</p> + +<p> +Please note that if you use DOCHEADER_FAMILY, you can still alter +the family of individual parts of the docheader with the macros +listed +<a href="#change-family">here</a>. +</p> + +<h4 id="change-family" class="docs">4. Change the family of individual docheader elements</h4> + +<p> +The following macros let you change the +<a href="definitions.html#family">family</a> +of each docheader element separately: +</p> +<ul style="list-style-type: none; margin: -.5em;"> + <li>Macro: <b>TITLE_FAMILY</b> <kbd class="macro-args"><family></kbd></li> + <li>Macro: <b>CHAPTER_TITLE_FAMILY</b> <kbd class="macro-args"><family></kbd></li> + <li>Macro: <b>SUBTITLE_FAMILY</b> <kbd class="macro-args"><family></kbd></li> + <li>Macro: <b>AUTHOR_FAMILY</b> <kbd class="macro-args"><family></kbd></li> + <li>Macro: <b>DOCTYPE_FAMILY</b> <kbd class="macro-args"><family></kbd> + (if <a href="#doctype">DOCTYPE</a> is <kbd>NAMED</kbd>) + </li> +</ul> + +<p> +Simply pass the appropriate macro the family you want, just as you +would with +<a href="typesetting.html#family">FAMILY</a>. +</p> + +<h4 id="change-font" class="docs">5. Change the font of individual docheader elements</h4> + +<p> +The following macros let you change the +<a href="definitions.html#font">font</a> +of each docheader element separately: +</p> +<ul style="list-style-type: none; margin: -.5em;"> + <li>Macro: <b>TITLE_FONT</b> <kbd class="macro-args">R | B | I | BI</kbd></li> + <li>Macro: <b>CHAPTER_TITLE_FONT</b> <kbd class="macro-args">R | B | I | BI</kbd></li> + <li>Macro: <b>SUBTITLE_FONT</b> <kbd class="macro-args">R | B | I | BI</kbd></li> + <li>Macro: <b>AUTHOR_FONT</b> <kbd class="macro-args">R | B | I | BI</kbd></li> + <li>Macro: <b>DOCTYPE_FONT</b> <kbd class="macro-args">R | B | I | BI</kbd> + (if <a href="#doctype">DOCTYPE</a> is <kbd>NAMED</kbd>) + </li> +</ul> + +<p> +Simply pass the appropriate macro the font you want. <kbd>R, B, +I</kbd> and <kbd>BI</kbd> have the same meaning as they do for +<a href="typesetting.html#font">FT</a>. +</p> + +<h4 id="change-size" class="docs">6. Adjust the size of individual docheader elements</h4> + +<p> +The following macros let you adjust the point size of each docheader +element separately. +</p> + +<p> +Mom calculates the point size of docheader elements from the point +size of paragraphs in running text, so you must prepend a + or - +sign to the argument. Points is assumed as the +<a href="definitions.html#unitofmeasure">unit of measure</a>, +so there’s no need to append a unit to the argument. +Fractional point sizes are allowed. +</p> + +<ul style="list-style-type: none; margin: -.5em;"> + <li>Macro: <b>TITLE_SIZE</b> <kbd class="macro-args"><+/-points></kbd> + <br/> + default = +3.5 (+4 if docheader title is "Chapter <n>") + </li> + <li>Macro: <b>.CHAPTER_TITLE_SIZE</b> <kbd class="macro-args"><+/-points></kbd> + <br/> + default = +4 + </li> + <li>Macro: <b>.SUBTITLE_SIZE</b> <kbd class="macro-args"><+/-points></kbd> + <br/> + default = +0 + </li> + <li>Macro: <b>.AUTHOR_SIZE</b> <kbd class="macro-args"><+/-points></kbd> + <br/> + default = +0 + </li> + <li>Macro: <b>.DOCTYPE_SIZE</b> <kbd class="macro-args"><+/-points></kbd> + (if <a href="#doctype">DOCTYPE</a> is <kbd>NAMED</kbd>) + <br/> + default = +3 + </li> +</ul> + +<p> +Simply pass the appropriate macro the size adjustment you want. +</p> + +<h4 id="adjust-leading" class="docs">7. Adjust the docheader leading</h4> + +<p> +The +<a href="definitions.html#leading">leading</a> +of docheaders is the same as running text. If you’d like your +docheaders to have a different leading, say, 2 points more than the +lead of running text, use: +<br/> +<span class="pre-in-pp"> + .DOCHEADER_LEAD +2 +</span> +Since the leading of docheaders is calculated from the lead of running +text, a + or - sign is required before the argument (how much to add +or subtract from the lead of running text). No +<a href="definitions.html#unitofmeasure">unit of measure</a> +is required; points is assumed. +</p> + +<h4 id="docheader-color" class="docs">8. Change the colour of the entire docheader</h4> + +<p> +If you want to colourize the entire docheader: +<br/> +<span class="pre-in-pp"> + .DOCHEADER_COLOR <kbd class="macro-args"><color name></kbd> +</span> +You must pre-define (or “initialize”) the colour with +<a href="color.html#newcolor">NEWCOLOR</a> +or +<a href="color.html#xcolor">XCOLOR</a>. +</p> + + +<h4 id="change-color" class="docs">9. Change the colour of the docheader elements individually</h4> + +<p> +The following macros let you change the colour of each +docheader element separately. You must pre-define (or +“initialize”) the colour with +<a href="color.html#newcolor">NEWCOLOR</a> +or +<a href="color.html#xcolor">XCOLOR</a>. +</p> +<ul style="list-style-type: none; margin: -.5em;"> + <li>Macro: <b>TITLE_COLOR</b> <kbd class="macro-args"><colorname></kbd></li> + <li>Macro: <b>CHAPTER_TITLE_COLOR</b> <kbd class="macro-args"><colorname></kbd> + <ul style="list-style-type: disc; margin-left: -.5em;"> + <li>Note: <b>CHAPTER_TITLE_COLOR</b> is needed only if you supply both a + <a href="#chapter">CHAPTER</a> + reference macro and a + <a href="#chapter-title">CHAPTER_TITLE</a> + macro. Otherwise, TITLE_COLOR takes care of colorizing the + chapter header. + </li> + </ul></li> + <li>Macro: <b>SUBTITLE_COLOR</b> <kbd class="macro-args"><colorname></kbd></li> + <li>Macro: <b>ATTRIBUTE_COLOR</b> <kbd class="macro-args"><colorname></kbd> + (the “by” string preceding author[s] name[s]) + </li> + <li>Macro: <b>AUTHOR_COLOR</b> <kbd class="macro-args"><colorname></kbd></li> + <li>Macro: <b>DOCTYPE_COLOR</b> <kbd class="macro-args"> <colorname></kbd> + (if <a href="#doctype">DOCTYPE</a> is <kbd>NAMED</kbd>) + </li> +</ul> + +<p> +It is not recommended that you embed colour (with the +<a href="definitions.html#inlines">inline escape</a>, +<a href="color.html#color-inline"><kbd>\*[<colorname>]</kbd></a>) +in the strings passed to TITLE, CHAPTER_TITLE, SUBTITLE, AUTHOR or +the name you give DOCTYPE <kbd>NAMED</kbd>. The strings passed to +these macros are used to generate page +<a href="definitions.html#header">headers</a> +and +<a href="definitions.html#footer">footers</a>, +with the result that an embedded colour will cause the string to be +colourized in headers and/or footers as well. (If you want headers +or footers colourized, or parts thereof, use the header/footer +control macros.) +</p> + +<h4 id="change-attribute" class="docs">10. Change the attribution string (“by”)</h4> + +<p> +If you’re not writing in English, you can change what mom +prints where “by” appears in docheaders. For example, +<br/> +<span class="pre-in-pp"> + .ATTRIBUTE_STRING "par" +</span> +changes “by” to “par”. ATTRIBUTE_STRING +can also be used, for example, to make the attribution read +"Edited by". +</p> + +<p> +If you don’t want an attribution string at all, simply pass +ATTRIBUTE_STRING an empty argument, like this: +<br/> +<span class="pre-in-pp"> + .ATTRIBUTE_STRING "" +</span> +Mom will deposit a blank line where the attribution string normally +appears. +</p> + +<p> +If the optional argument, <kbd>COVER</kbd> or <kbd>DOC_COVER</kbd>, +is given to ATTRIBUTE_STRING, the string argument represents the +attribution string that will appear on cover or document cover pages +(see the +<a href="cover.html#cover-intro">Introduction to cover pages</a> +for a description of the difference between “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: +<br/> +<span class="pre-in-pp"> + .ATTRIBUTE_STRING "" + .ATTRIBUTE_STRING DOC_COVER "Edited by" + .ATTRIBUTE_STRING COVER "by" +</span> +The first invocation of <kbd>.ATTRIBUTE_STRING</kbd> establishes a +blank attribution string that will be incorporated in the first-page +docheader. The second will print “Edited by” on the +document cover; the third will print “by” on the cover +(“title”) page. +</p> + +<p> +If you don’t require differing attribute strings for +doc cover pages, cover pages, or the first-page docheader, +<kbd>.ATTRIBUTE_STRING</kbd>, without either of the optional first +arguments, is sufficient. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +The type specs for the attribution line in docheaders are the +same as for the author line. Although it’s highly unlikely +you’ll want the attribution line in a different family, font, +or point size, you can make such changes using +<a href="definitions.html#inlines">inline escapes</a> +in the argument to ATTRIBUTE_STRING. For example, +<br/> +<span class="pre-in-pp"> + .ATTRIBUTE_STRING "\f[HBI]\*[SIZE -2p] by \*[SIZE +2p]\*[PREV]" +</span> +would set “by” in Helvetica bold italic, 2 points +smaller than normal. +</p> +</div> + +<div class="rule-short"><hr/></div> + +<!-- -COLUMNS- --> + +<h2 id="columns-intro" class="docs">Setting documents in columns</h2> + +<p> +Setting documents in columns is easy with mom. All you have to do +is is say how many columns you want and how much space you want +between them (the +<a href="definitions.html#gutter">gutters</a>). +That’s it. Mom takes care of everything else, from soup to +nuts. +</p> + +<h3 class="docs">Some words of advice</h3> + +<p> +If you want your type to achieve a pleasing +<a href="definitions.html#just">justification</a> +or +<a href="definitions.html#rag">rag</a> +in columns, reduce the point size of type (and probably the +<a href="definitions.html#leading">leading</a> +as well). Mom’s default document point size is 12.5, which +works well across her default 39 +<a href="definitions.html#picaspoints">pica</a> +full page line length, but with even just two columns on a page, the +default point size is awkward to work with. +</p> + +<p> +Furthermore, you’ll absolutely need to reduce the indents for +<a href="docelement.html#epigraph-control">epigraphs</a>, +<a href="docelement.html#quote-general">quotes</a>, +and +<a href="docelement.html#blockquote-general">blockquotes</a> +(and probably the +<a href="docelement.html#para-indent">paragraph first-line indent</a> +as well). +</p> + +<!-- -COLUMN- --> + +<div class="macro-id-overline"> +<h3 id="columns" class="macro-id">COLUMNS</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>COLUMNS</b> <kbd class="macro-args"><number of columns> <width of gutters></kbd> +</div> + +<p class="requires"> +• Should be the last macro before START +<br/> + +<i>The second argument requires a <a href="definitions.html#unitofmeasure">unit of measure</a></i> +</p> + +<p> +COLUMNS takes two arguments: the number of columns you want on +document pages, and the width of the +<a href="definitions.html#gutter">gutter</a> +between them. For example, to set up a page with two columns +separated by an 18 point gutter, you’d do +<br/> +<span class="pre-in-pp"> + .COLUMNS 2 18p +</span> +Nothing to it, really. However, as noted above, COLUMNS should +always be the last document setup macro prior to +<a href="#start">START</a>. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +Mom ignores columns completely +when the +<a href="#printstyle">PRINTSTYLE</a> +is <kbd>TYPEWRITE</kbd>. The notion of typewriter-style +output in columns is just too ghastly for her to bear. +</p> +</div> + +<h3 class="docs">Using tabs when COLUMNS are enabled</h3> + +<p> +Mom’s tabs (both +<a href="typesetting.html#typesetting-tabs">typesetting tabs</a> +and +<a href="typesetting.html#string-tabs">string tabs</a>) +behave as you’d expect during document processing, even +when COLUMNS are enabled. Tab structures set up during document +processing carry over from page to page and column to column. +</p> + +<!-- -BREAKING COLUMNS- --> + +<h3 id="breaking-columns" class="docs">Breaking columns manually</h3> + +<p> +Mom takes care of breaking columns when they reach the bottom +margin of a page. However, there may be times you want to break +the columns yourself. There are two macros for breaking columns +manually: COL_NEXT and COL_BREAK. +</p> + +<div id="col-next" class="box-macro-args"> +Macro: <b>COL_NEXT</b> +</div> + +<p> +<kbd>.COL_NEXT</kbd> breaks the line just before it, +<a href="definitions.html#quad">quads</a> +it left (assuming the type is justified or quad left), and moves over +to the top of the next column. If the column happens to be the last +(rightmost) one on the page, mom starts a new page +at the "column 1" position. This is the macro to use when +you want to start a new column after the end of a paragraph. +</p> + +<div id="col-break" class="box-macro-args"> +Macro: <b>COL_BREAK</b> +</div> + +<p> +<kbd>.COL_BREAK</kbd> is almost the same as <kbd>.COL_NEXT</kbd>, +except that instead of breaking and quadding the line preceding it, +mom breaks and spreads it (see +<a href="typesetting.html#spread">SPREAD</a>). +Use this macro whenever you need to start a new column in the middle +of a paragraph. +</p> + +<div class="box-important"> +<p class="tip"> +<span class="important">Warning:</span> +If you need COL_BREAK in the middle of a blockquote or (god help +you) an epigraph, you must do the following in order for COL_BREAK +to work: +<br/> +<span class="pre-in-pp"> + .SPREAD + \!.COL_BREAK +</span> +</p> +</div> + +<div class="rule-short"><hr/></div> + +<!-- ======================================================================== --> + +<!-- *** --> + + +<h2 id="style-after-start" class="macro-group">Changing basic type and formatting parameters after START</h2> + +<ul id="changing-basic-type"> + <li><a href="#behaviour">Behaviour of the typesetting macros during document processing</a> + <ul style="margin-left: -.5em;"> + <li><a href="#behaviour-specific">Effect of specific typesetting macros</a></li> + </ul></li> + <li><a href="#tb-margins">Top and bottom margins in document processing</a></li> + <li><a href="#space">Inserting space at the top of a new page</a> + <ul style="margin-left: -.5em;"> + <li><a href="#add-space">ADD_SPACE</a></li> + </ul></li> +</ul> + +<div class="rule-medium"><hr/></div> + +<h3 id="behaviour" class="docs">Behaviour of the typesetting macros during document processing</h3> + +<p> +During document processing, most of the +<a href="typesetting.html#macros-typesetting">typesetting macros</a> +affect type in the document globally. For example, if you turn +kerning off, pairwise kerning is disabled not only in paragraphs, +but also in headers, footers, quotes, and so on. +</p> + +<p> +Typesetting macros that alter margins and line lengths affect +<a href="definitions.html#running">running text</a> +globally (or at least try to), but leave headers/footers and +footnotes alone. (To indent footnotes, see the full explanation of +the +<a href="docelement.html#footnote">FOOTNOTE</a> +macro.) +</p> + +<p> +Mom’s tabs (both +<a href="typesetting.html#typesetting-tabs">typesetting tabs</a> +and +<a href="typesetting.html#string-tabs">string tabs</a>) +behave as expected in running text during document processing. Tab +structures that do not exceed the line length of running text are +preserved sensibly from page to page, and, if +<a href="docprocessing.html#columns">COLUMNS</a> +are enabled, from column to column. +</p> + +<p> +Some typesetting macros, however, when used during document +processing, behave in special ways. These are the macros that deal +with the basic parameters of type style: horizontal and vertical +margins, line length, +<a href="definitions.html#family">family</a>, +<a href="definitions.html#font">font</a>, +<a href="definitions.html#ps">point size</a>, +<a href="definitions.html#leading">leading</a>, +and +<a href="definitions.html#quad">quad</a>. +</p> + +<p> +Mom assumes that any changes to these parameters stem from a +temporary need to set type in a style different from that provided +by mom’s +<a href="docelement.html#index-docelement">document element tags</a>. +In other words, you need to do a bit of creative typesetting in the +middle of a document. +</p> + +<p> +The following lists those typesetting macros whose behaviour during +document processing requires some explanation. +(Please refer to +<a href="#tb-margins">Top and bottom margins in document processing</a> +for information on how mom interprets +<a href="typesetting.html#t-margin">T_MARGIN</a> +and +<a href="typesetting.html#b-margin">B_MARGIN</a> +in document processing. Additionally, see +<a href="#add-space">ADD_SPACE</a> +if you encounter the problem of trying to get mom to put space at +the tops of pages after the first.) +</p> +<div id="behaviour-specific" class="box-code" style="margin-left: 24px;"> +<span class="pre" style="color: #302419;"> + MACRO EFFECT DURING DOCUMENT PROCESSING + ----- --------------------------------- + + L_MARGIN •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. +</span> +</div> + +<h3 id="tb-margins" class="docs" style="margin-top: 1.5em;">Top and bottom margins in document processing</h3> + +<p> +Normally, mom establishes the top and bottom +margins of +<a href="definitions.html#running">running text</a> +in documents from the values of <b>HEADER_MARGIN + +HEADER_GAP</b> and <b>FOOTER_MARGIN + FOOTER_GAP</b> +respectively. However, if you invoke +<a href="typesetting.html#t-margin">T_MARGIN</a> +or +<a href="typesetting.html#b-margin">B_MARGIN</a> +either before or after +<a href="docelement.html#start">START</a>, +they set the top and bottom margins of running text irrespective of +HEADER_GAP and FOOTER_GAP. +</p> + +<p> +Put another way, in document processing, T_MARGIN +and B_MARGIN set the top and bottom margins of +running text, but have no effect on the placement of +<a href="definitions.html#header">headers</a>, +<a href="definitions.html#footer">footers</a>, +or page numbers. +</p> + +<!-- ==================================================================== --> + +<h3 id="space" class="docs">Inserting space at the top of a new page</h3> + +<p> +Occasionally, you may want to insert space before the start of +<a href="definitions.html#running">running text</a> +on pages after the first. +</p> + +<p> +You might have tried using +<a href="typesetting.html#ald">ALD</a> +or +<a href="typesetting.html#space">SPACE</a> +and found it did nothing. This is because mom normally inhibits +any extra space before the start of running text on pages after the +first. +</p> + +<p> +If you need the space, you must use the macro, ADD_SPACE, in +conjuction with +<a href="typesetting.html#newpage">NEWPAGE</a>. +</p> + +<!-- -ADD_SPACE- --> + +<div class="macro-id-overline"> +<h3 id="add-space" class= "macro-id">ADD_SPACE</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>ADD_SPACE</b> <kbd class="macro-args"><amount of space></kbd> +</div> + +<p class="requires"> +• Requires a <a href="definitions.html#unitofmeasure">unit of measure</a> +</p> + +<p> +ADD_SPACE takes as its single argument the distance +you want mom to advance from the normal +baseline position at the top of any page after the first +(i.e. the one on which the docheader is normally printed). A +<a href="definitions.html#unitofmeasure">unit of measure</a> is +required. +</p> + +<p> +For example, say you wanted to insert 2 inches of space before the +start of +<a href="definitions.html#running">running text</a> +on a page other than the first. You’d accomplish it with +<br/> +<span class="pre-in-pp"> + .NEWPAGE + .ADD_SPACE 2i +</span> +which would terminate your current page, break to a new page, print +the header (assuming headers are on) and insert 2 inches of space +before the start of running text. +</p> + +<p> +Since adding space in this way is almost sure to disrupt mom’s +ability to guarantee perfectly flush bottom margins, I highly +recommend using the +<a href="docprocessing.html#shim">SHIM</a> +macro immediately after ADD_SPACE. +</p> + +<!-- *** --> +<h2 id="intro-doc-param" class="macro-group">Changing basic type and formatting parameters after START</h2> + +<p> +In the normal course of things, you establish the basic type +parameters of a document prior to invoking +<a href="#start">START</a>, +using the +<a href="typesetting.html#macros-typesetting">typesetting macros</a> +(<b>L_MARGIN, FAMILY, PT_SIZE, LS,</b> etc). After +START, you <i>must</i> use the following macros to make +global changes to the basic type parameters of a document. +</p> + +<div class="macro-list-container"> +<h3 id="index-doc-param" class="macro-list">Post-START global style change macros</h3> +<ul class="macro-list"> + <li><a href="#doc-left-margin">DOC_LEFT_MARGIN</a></li> + <li><a href="#doc-right-margin">DOC_RIGHT_MARGIN</a></li> + <li><a href="#doc-line-length">DOC_LINE_LENGTH</a></li> + <li><a href="#doc-family">DOC_FAMILY</a></li> + <li><a href="#doc-pt-size">DOC_PT_SIZE</a></li> + <li><a href="#doc-lead">DOC_LEAD</a></li> + <li><a href="#doc-lead-adjust">DOC_LEAD_ADJUST</a></li> + <li><a href="#doc-quad">DOC_QUAD</a></li> +</ul> +</div> + +<!-- -DOC_LEFT_MARGIN --> + +<div class="macro-id-overline"> +<h3 id="doc-left-margin" class="macro-id">DOC_LEFT_MARGIN</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>DOC_LEFT_MARGIN</b> <kbd class="macro-args"><left margin></kbd> +</div> + +<p class="requires"> +• Requires a <a href="definitions.html#unitofmeasure">unit of measure</a> +</p> + +<h4 class="docs doc-param-macros">Arguments and behaviour</h4> + +<ul class="doc-param-macros"> + <li>the argument is the same as for + <a href="typesetting.html#l-margin">L_MARGIN</a> + </li> + <li>changes all left margins to the new value</li> + <li>the line length remains the same (i.e. the right margin + shifts when you change the left margin) + </li> +</ul> + +<!-- -DOC_RIGHT_MARGIN --> + +<div class="macro-id-overline"> +<h3 id="doc-right-margin" class="macro-id">DOC_RIGHT_MARGIN</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>DOC_RIGHT_MARGIN</b> <kbd class="macro-args"><right margin></kbd> +</div> + +<p class="requires"> +• Requires a <a href="definitions.html#unitofmeasure">unit of measure</a> +</p> + +<h4 class="docs doc-param-macros">Arguments and behaviour</h4> + +<ul class="doc-param-macros"> + <li>the argument is the same as for + <a href="typesetting.html#r-margin">R_MARGIN</a> + </li> + <li>changes all right margins, including + <a href="definitions.html#docheader">docheaders</a>, + headers (or footers) and page numbering to the new value; + for changing the right margin of + <a href="definitions.html#running">running text</a> + only, use + <a href="typesetting.html#r-margin">R_MARGIN</a> + (see + <a href="#behaviour">typesetting macros during + document processing</a>, + entry for R_MARGIN) + </li> + <li>all mom commands that include a right indent calculate + the indent from the new value + </li> +</ul> + +<!-- -DOC_RIGHT_MARGIN --> + +<div class="macro-id-overline"> +<h3 id="doc-line-length" class="macro-id">DOC_LINE_LENGTH</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>DOC_LINE_LENGTH</b> <kbd class="macro-args"><length></kbd> +</div> + +<p class="requires"> +• Requires a <a href="definitions.html#unitofmeasure">unit of measure</a> +</p> + +<h4 class="docs doc-param-macros">Arguments and behaviour</h4> + +<ul class="doc-param-macros"> + <li>the argument is the same as for + <a href="typesetting.html#linelength">LL</a> + </li> + <li>exactly equivalent to changing the right margin with + DOC_RIGHT_MARGIN (see + <a href="#doc-right-margin">above</a>); + for changing the line length of + <a href="definitions.html#running">running text</a> + only, use + <a href="typesetting.html#linelength">LL</a> + (see + <a href="#behaviour">typesetting macros during document processing</a>, + entry for LL) + </li> +</ul> + +<!-- -DOC_FAMILY- --> + +<div class="macro-id-overline"> +<h3 id="doc-family" class="macro-id">DOC_FAMILY</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>DOC_FAMILY</b> <kbd class="macro-args"><family></kbd> +</div> + +<h4 class="docs doc-param-macros" style="margin-top: 1em;">Arguments and behaviour</h4> + +<ul class="doc-param-macros"> + <li>the argument is the same as for + <a href="typesetting.html#family">FAMILY</a> + </li> + <li>globally changes the type family for + <ul> + <li style="margin-left: -.5em;">the <a href="definitions.html#docheader">docheader</a></li> + <li style="margin-left: -.5em;">all <a href="docelement.html#index-docelement">document element tags</a>, including footnotes</li> + <li style="margin-left: -.5em;"><a href="definitions.html#header">headers and/or footers</a></li> + <li style="margin-left: -.5em;"><a href="docelement.html#number-lines-intro">line numbering</a></li> + <li style="margin-left: -.5em;"><a href="headfootpage.html#pagination">page numbering</a></li> + </ul></li> + <li>does <i>not</i> change the family of + <ul> + <li><a href="cover.html#doc-cover">document cover pages</a></li> + <li><a href="cover.html#cover">cover pages</a></li> + <li><a href="docelement.html#endnote-intro">endnotes pages</a></li> + <li><a href="docelement.html#toc-intro">table of contents</a></li> + </ul></li> + <li>any page elements (e.g. headers page numbers, footnotes) whose + families you wish to remain at their old values must be + reset with the appropriate + <a href="docelement.html#docelement-control">control macros</a> + </li> +</ul> + +<!-- -DOC_PT_SIZE- --> + +<div class="macro-id-overline"> +<h3 id="doc-pt-size" class="macro-id">DOC_PT_SIZE</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>DOC_PT_SIZE</b> <kbd class="macro-args"><point size></kbd> +</div> + +<p class="requires"> +• Does not require a <a href="definitions.html#unitofmeasure">unit of measure</a>; points is assumed +</p> + +<h4 class="docs doc-param-macros">Arguments and behaviour</h4> + +<ul class="doc-param-macros"> + <li>the argument is the same as for + <a href="typesetting.html#ps">PT_SIZE</a>, + and refers to the point size of type in paragraphs + </li> + <li>all automatic point size changes (heads, quotes, + footnotes, headers, etc.) are affected by the new size; + anything you do not want affected must be reset to + its former value (see the Control Macros section of + the pertinent document element for instructions on + how to do this) + </li> +</ul> + +<!-- -DOC_LEAD- --> + +<div class="macro-id-overline"> +<h3 id="doc-lead" class="macro-id">DOC_LEAD</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>DOC_LEAD</b> <kbd class="macro-args"><points> [ ADJUST ]</kbd> +</div> + +<p class="requires"> +• Does not require a <a href="definitions.html#unitofmeasure">unit of measure</a>; points is assumed +</p> + +<h4 class="docs doc-param-macros">Arguments and behaviour</h4> + +<ul class="doc-param-macros"> + <li>the argument is the same as for + <a href="typesetting.html#leading">LS</a>, + and refers to the + <a href="definitions.html#lead">leading</a> + of paragraphs + </li> + <li>because paragraphs will have a new leading, the leading and + spacing of most running text is influenced by the new value + </li> + <li>epigraphs and footnotes remain unaffected; + if you wish to change their leading, use + <a href="docelement.html#epigraph-autolead">EPIGRAPH_AUTOLEAD</a> + and + <a href="docelement.html#footnote-autolead">FOOTNOTE_AUTOLEAD</a>. + </li> + <li>the optional argument <kbd>ADJUST</kbd> performs + leading adjustment as explained in + <a href="#doc-lead-adjust">DOC_LEAD_ADJUST</a> + </li> +</ul> + +<div class="box-important"> +<p class="tip"> +<span class="important">Important:</span> +Do not use DOC_LEAD in the middle of a page! It should always and +only be invoked immediately prior to a new page, like this: +<br/> +<span class="pre-in-pp"> + .DOC_LEAD <new value> + .NEWPAGE +</span> +</p> +</div> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +Even if you don’t pass DOC_LEAD the optional argument +<kbd>ADJUST</kbd>, mom will still adjust the leading of endnotes +pages and toc pages. See +<a href="docelement.html#endnote-lead">ENDNOTE_LEAD</a> +and +<a href="docelement.html#toc-lead">TOC_LEAD</a> +for an explanation of how to disable this default behaviour. +</p> +</div> + +<!-- -DOC_QUAD- --> + +<div class="macro-id-overline"> +<h3 id="doc-quad" class="macro-id">DOC_QUAD</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>DOC_QUAD</b> <kbd class="macro-args">L | R | C | J</kbd> +</div> + +<h4 class="docs doc-param-macros" style="margin-top: 1em;">Arguments and behaviour</h4> + +<ul class="doc-param-macros"> + <li>the arguments are the same as for + <a href="typesetting.html#quad">QUAD</a> + </li> + <li>affects paragraphs, epigraphs and footnotes; does not + affect blockquotes + </li> +</ul> + +<div class="rule-long"><hr/></div> + +<!-- Navigation links --> +<table style="width: 100%; margin-top: 12px;"> +<tr> + <td style="width: 33%;"><a href="toc.html">Back to Table of Contents</a></td> + <td style="width: 24%; text-align: center;"><a href="#top">Top</a></td> + <td style="width: 43%; text-align: right;"><a href="docelement.html#top">Next: The document element tags</a></td> +</tr> +</table> + +</div> + +<div class="bottom-spacer"><br/></div> + +</body> +</html> +<!-- vim: fileencoding=utf-8: nomodified: --> 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 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- +This file is part of groff, the GNU roff type-setting system. + +Copyright (C) 2004, 2005, 2006, 2009, 2010 Free Software Foundation, Inc. +Written by Peter Schaffter. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with the +Invariant Sections being this comment section, with no Front-Cover +Texts, and with no Back-Cover Texts. + +A copy of the Free Documentation License is included as a file called +FDL in the main directory of the groff source package. +--> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"> + +<head> + <meta http-equiv="content-type" content="text/html;charset=utf-8"/> + <title>Mom -- Goodies</title> + <link rel="stylesheet" type="text/css" href="stylesheet.css" /> +</head> + +<body style="background-color: #f5faff;"> + +<!-- ==================================================================== --> + +<div id="top" class="page"> + +<!-- Navigation links --> +<table style="width: 100%;"> +<tr> + <td><a href="toc.html">Back to Table of Contents</a></td> + <td style="text-align: right;"><a href="inlines.html#top">Next: Inline escapes</a></td> +</tr> +</table> + +<h1 id="goodies" class="docs">Goodies</h1> + +<p> +The macros in this section are a collection of useful (and sometimes +nearly indispensable) routines to simplify typesetting. +</p> + +<div id="goodies-macros-mini-toc" style="margin-top: -1em; font-size: 95%;"> +<div class="mini-toc-col-1"> +<ul class="no-enumerator"> +<li class="list-head-goodies"><a href="#alias">ALIAS</a> <span class="normal-smaller">– rename macros</span></li> +<li class="list-head-goodies"><a href="#silent">SILENT</a> <span class="normal-smaller">– “hide” input lines from output</span></li> +<li class="list-head-goodies"><a href="#trap">TRAP</a> <span class="normal-smaller">– suspend/re-invoke traps</span></li> +<li class="list-head-goodies"><a href="#smartquotes">SMARTQUOTES</a> <span class="normal-smaller">– convert typewriter doublequotes to proper doublequotes</span></li> +<li class="list-head-goodies"><a href="#caps">CAPS</a> <span class="normal-smaller">– convert to upper case</span></li> +<li class="list-head-goodies"><a href="#string">STRING</a> <span class="normal-smaller">– user-definable strings</span></li> +<li class="list-head-goodies"><a href="#esc-char">ESC_CHAR</a> <span class="normal-smaller">– change the escape character to something other than a backslash</span></li> +<li class="list-head-goodies"><a href="#sizespecs">SIZESPECS</a> <span class="normal-smaller">– get cap-height, x-height and descender depth of a font</span></li> +<li class="list-head-goodies no-anchor"><span style="font-size: 90%;">Underscoring/underlining</span> +<ul class="sublist"> + <li class="list-head-goodies text-color"><a href="#underscore">UNDERSCORE</a> <span class="normal-smaller">– single underscore</span> + <ul class="sublist sub"> + <li class="list-head-goodies text-color"><a href="#underscore-weight">Controlling the weight of underscores</a></li> + <li class="list-head-goodies text-color"><a href="#underscore-color">Colorizing underscores</a></li> + <li class="list-head-goodies text-color"><a href="#underscore-notes">Notes on underscoring</a></li> + </ul></li> + <li class="list-head-goodies text-color"><a href="#underscore2">UNDERSCORE2</a> <span class="normal-smaller">– double underscore</span></li> + <li class="list-head-goodies text-color"><a href="#underline">UNDERLINE</a> <span class="normal-smaller">– fixed-width fonts only</span> + <ul class="sublist sub"> + <li class="list-head-goodies text-color"><a href="#ul">\*[UL]</a> <span class="normal-sub-sub">– inline escape to underline; fixed-width fonts only</span></li> + </ul></li> +</ul></li> +<li class="list-head-goodies no-anchor"><span style="font-size: 90%;">Padding</span> +<ul class="sublist"> + <li class="list-head-goodies text-color"><a href="#pad">PAD</a> <span class="normal-smaller">– insert equalized space into lines</span> + <ul class="sublist sub"> + <li class="list-head-goodies text-color"><a href="#pad-marker">PAD_MARKER</a> <span class="normal-sub-sub">– change/set the marker used with PAD</span></li> + </ul></li> +</ul></li> +</ul> +</div> +<div class="mini-toc-col-2"> +<ul class="no-enumerator"> +<li class="list-head-goodies no-anchor"><span style="font-size: 90%;">Leaders</span> +<ul class="sublist"> + <li class="list-head-goodies text-color"><a href="#leader">\*[LEADER]</a> <span class="normal-smaller">– inline escape to add leaders to a line</span></li> + <li class="list-head-goodies text-color"><a href="#leader-character">LEADER_CHARACTER</a> <span class="normal-smaller">– change/set the leader character</span></li> +</ul></li> +<li class="list-head-goodies no-anchor"><span style="font-size: 90%;">Drop caps</span> +<ul class="sublist"> + <li class="list-head-goodies text-color"><a href="#dropcap">DROPCAP</a> <span class="normal-smaller">– set a drop cap</span></li> + <li class="list-head-goodies text-color" style="list-style-type: none;"><a href="#dropcap-support"><span class="normal-smaller" style="font-weight: bold;">Support macros for DROPCAP</span></a> + <ul class="sublist sub"> + <li class="list-head-goodies text-color"><a href="#dropcap-family">DROPCAP_FAMILY</a> <span class="normal-sub-sub">– change drop cap family</span></li> + <li class="list-head-goodies text-color"><a href="#dropcap-font">DROPCAP_FONT</a> <span class="normal-sub-sub">– change drop cap font</span></li> + <li class="list-head-goodies text-color"><a href="#dropcap-adjust">DROPCAP_ADJUST</a> <span class="normal-sub-sub">– alter size of drop cap</span></li> + <li class="list-head-goodies text-color"><a href="#dropcap-color">DROPCAP_COLOR</a> <span class="normal-sub-sub">– change colour of drop cap</span></li> + <li class="list-head-goodies text-color"><a href="#dropcap-gutter">DROPCAP_GUTTER</a> <span class="normal-sub-sub">– change space between drop cap and running text</span></li> + </ul></li> +</ul></li> +<li class="list-head-goodies text-color no-anchor"><span style="font-size: 90%;">Superscripts</span> +<ul class="sublist"> + <li class="list-head-goodies text-color"><a href="#sup">\*[SUP]</a> <span class="normal-smaller">– inline escape to set superscripts</span> + <ul class="sublist sub"> + <li class="list-head-goodies text-color"><a href="#sup-raise">SUPERSCRIPT_RAISE_AMOUNT</a> <span class="normal-sub-sub">(control superscript raise amount</span></li> + <li class="list-head-goodies text-color"><a href="#cond-or-ext-sup">\*[CONDSUP]</a> <span class="normal-sub-sub">– condensed superscripts</span></li> + <li class="list-head-goodies text-color"><a href="#cond-or-ext-sup">\*[EXTSUP]</a> <span class="normal-sub-sub">– extended superscripts</span></li> + </ul></li> +</ul></li> +</ul> +</div> +</div> + +<div class="rule-medium" style="padding-bottom: 1em;"><hr/></div> + +<!-- -ALIAS- --> + +<div class="macro-id-overline"> +<h3 id="alias" class="macro-id">Rename macros</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>ALIAS</b> <kbd class="macro-args"><new name> <old name></kbd> +</div> + +<p> +The ALIAS macro may well be your best friend. With it, you can +change the name of a macro to anything you like (provided the new +name is not already being used by mom; see the +<a href="reserved.html#reserved">list of reserved words</a>). +</p> + +<p> +Groff has always been a bit intimidating for new users because +its standard macro packages use very terse macro names. Mom +doesn’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. +</p> + +<p> +If you don’t like one of mom’s macro names, say, +PAGEWIDTH, change it, like this: +<br/> +<span class="pre-in-pp"> + .ALIAS PW PAGEWIDTH + | | + new--+ +--official + name name +</span> +The first argument to ALIAS is the new name you want for a macro. +The second is the “official” name by which the macro is +normally invoked. After ALIAS, either can be used. +</p> + +<p> +Note that in ALIAS, you do NOT include the period (dot) that +precedes the macro when it’s a +<a href="definitions.html#controllines">control line</a>. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="tip">Tip:</span> +A particularly good candidate for ALIAS is the macro, +<a href="typesetting.html#ps">PT_SIZE</a>. +A more natural name for it (at least to old-school phototypesetters) +would simply be PS, but PS conflicts with the <b>eqn</b> equation +preprocessor and thus mom uses the longer form. However, if +you’re not using <b>eqn</b>, you can happily rename PT_SIZE to +PS: +<br/> +<span class="pre-in-pp"> + .ALIAS PS PT_SIZE +</span> +</p> +</div> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +If you use ALIAS a lot, and always for the same things, consider +creating an aliases file of the form +<br/> +<span class="pre-in-pp"> + .ALIAS <new name> <old name> + .ALIAS <new name> <old name> + .ALIAS <new name> <old name> + ...etc +</span> +Put the file someplace convenient and source it (include it) at the +beginning of your documents with the +<a href="docprocessing.html#include">INCLUDE</a> +macro. Assuming that you've created an aliases file called +<b>mom-aliases</b> in your home directory under a directory called +<b>Mom</b>, you'd source it by placing +<br/> +<span class="pre-in-pp"> + .INCLUDE /home/<username>/Mom/mom-aliases +</span> +at the top of your documents. +</p> + +<p class="tip-bottom"> +If you share documents that make use of an alias file, remember that +other people don’t have the file. Paste the whole thing at +the top of your documents, please. +</p> +</div> + +<div class="box-tip"> +<p class="tip"> +<span class="experts">Experts:</span> +ALIAS is an alias of <kbd>.als</kbd>. You can use either, or mix +'n' match with impunity. +</p> +</div> + +<!-- -SILENT- --> +<div class="macro-id-overline"> +<h3 id="silent" class="macro-id">Hide input lines from output</h3> +</div> + +<div class="box-macro-args"> + Macro: <b>SILENT</b> <kbd class="macro-args">toggle</kbd> +</div> + +<p class="alias" style="margin-bottom: 0;"> +<i>Alias:</i> <b>COMMENT</b> +</p> + +<p> +Sometimes, you want to “hide” +<a href="definitions.html#inputline">input lines</a> +from final output. This is most likely to be the case when setting +up string tabs (see the +<a href="typesetting.html#string-tabs-tut">quickie tutorial on string tabs</a> +for an example), but there are other places where you might want +input lines to be invisible as well. Any place you don’t want +input lines to appear in the output, use the SILENT macro. +</p> + +<p> +SILENT is a toggle. Invoking it without an argument turns it on; +any argument turns it off. E.g., +<br/> +<span class="pre-in-pp"> + .SILENT + A line of text + .SILENT OFF +</span> +The line “A line of text” will not appear in the +output copy. +</p> + +<p> +SILENT is aliased as COMMENT. If you want to insert non-printing +comments into your documents, you may prefer this. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="tip">Tip:</span> +SILENT does not automatically break an +<a href="definitions.html#inputline">input line</a> +(see +<a href="typesetting.html#br">BR</a>) +when you’re in one of the +<a href="definitions.html#filled">fill modes</a> +(<a href="typesetting.html#justify">JUSTIFY</a> +or +<a href="typesetting.html#quad">QUAD L | R | C | J</a>). +The same applies to tabs +(<a href="typesetting.html#tab-set">typesetting</a> +or +<a href="typesetting.html#st">string</a>) +to which you've passed the J or QUAD argument. You must insert +<kbd>.BR</kbd> yourself, or risk a portion of your text +disappearing into a black hole. +</p> +</div> + +<!-- -TRAP- --> + +<div class="macro-id-overline"> +<h3 id="trap" class="macro-id">Suspend/re-invoke traps</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>TRAP</b> <kbd class="macro-args">toggle</kbd> +</div> + +<p> +Traps are vertical positions on the output page at which you or +mom have instructed groff to start doing something automatically. +Commonly, this is near the bottom of the page, where automatic +behind-the-scenes processing is needed in order for one page to +finish and another to start. +</p> + +<p> +Sometimes, traps get sprung when you don’t want them. If this +happens, surround just the offending macros and input lines with +<br/> +<span class="pre-in-pp"> + .TRAP OFF + ... + .TRAP +</span> +TRAP is a toggle, therefore any argument turns it off (i.e. suspends +the trap), and no argument turns it (back) on. +</p> + +<!-- -SMARTQUOTES- --> + +<div class="macro-id-overline"> +<h3 id="smartquotes" class="macro-id">Convert typewriter doublequotes to proper doublequotes</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>SMARTQUOTES</b> <kbd class="macro-args">[<off>] [ ,, | >> | << ]</kbd> +</div> + +<span style="margin-left: .5em">or</span> + +<div class="box-macro-args"> +Macro: <b>SMARTQUOTES</b> <kbd class="macro-args">DA | DE | ES | FR | IT | NL | NO | PT | SV</kbd> +</div> + +<p> +If you invoke SMARTQUOTES without an argument, mom converts all +instances of the inch-mark, (<kbd>"</kbd>), also called +a doublequote, into the appropriate instances of true Anglo-American +open-and close-doublequotes. (See +<a href="#sq-international">Internationalization</a> +for how to get SMARTQUOTES to behave correctly for non-English +quoting styles.) +</p> + +<p> +Typographically, there is a difference between the inch-mark and +quotation marks—a BIG difference. Sadly, typewriters and computer +keyboards supply only one: the inch-mark. While using inches for +doublequotes is, and always has been, acceptable in typewriter-style +copy, it has never been, and, God willing, never will be acceptable in +typeset copy. Failure to turn inches into quotes is the first thing +a professional typesetter notices in documents prepared by amateurs. +And you don’t want to look like an amateur, do you? +</p> + +<h3 id="sq-international" class="docs">Internationalization</h3> +<p> +If you invoke SMARTQUOTES with one of the optional arguments +(<kbd>,,</kbd> or <kbd>>></kbd> +or <kbd><<</kbd>) you can use +<kbd>"</kbd> (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. +</p> + +<p> +<kbd>,,</kbd> opens quotes with “lowered +doublequotes” and closes them with “raised +doublequotes”, as in this ascii approximation: +<br/> +<span class="pre-in-pp"> + ,,Hilfe !`` +</span> + +<kbd>>></kbd> opens quotes with guillemets +pointing to the right, and closes them with guillemets pointing to +the left, as in this ascii approximation: +<br/> +<span class="pre-in-pp"> + >>Zurück !<< +</span> +<kbd><<</kbd> opens quotes with guillemets +pointing to the left, and closes them with guillemets pointing to +the right, as in this ascii approximation: +<br/> +<span class="pre-in-pp"> + <<Mais monsieur! Je ne suis pas ce genre de fille!>> +</span> +Please note: the above arguments to SMARTQUOTES are literal +ASCII characters. <kbd>,,</kbd> is two commas; +<kbd><<</kbd> is two less-than signs; +<kbd>>></kbd> is two greater-than signs. +</p> + +<p> +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. +<br/> +<span class="pre-in-pp"> + .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>> +</span> +</p> + +<p> +Turn SMARTQUOTES off by passing it any argument not in the argument +list (e.g. OFF, QUIT, X, etc.) +</p> + +<p> +If you’re using the +<a href="docprocessing.html#docprocessing">document processing macros</a> +with +<a href="docprocessing.html#printstyle">PRINTSTYLE TYPESET</a>, +SMARTQUOTES is on by default (in the Anglo-American style); with +<a href="docprocessing.html#printstyle">PRINTSTYLE TYPEWRITE</a>, +it’s off by default (and should probably stay that way). +</p> + +<p> +Finally, if you’re fussy about the kerning of quote marks in +relation to the text they surround, or have special quoting needs, +you have to enter quote marks by hand using groff’s native +<a href="definitions.html#inlines">inline escapes</a> +for special characters (see <kbd>man groff-char</kbd> +for a complete list of special characters). Entering quote marks +this way allows you to use mom’s +<a href="inlines.html#inline-kerning-mom">inline kerning escapes</a> +to fine-tune the look of quotes. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +SMARTQUOTES does not work on single quotes, which most people +input with the apostrophe (found at the right-hand end of the +“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: +<br/> +<span class="pre-in-pp"> + "But she said, `I don’t want to!'" +</span> +</p> + +<p class="tip-bottom" style="margin-top: -1em;"> +<span class="additional-note">Additional note:</span> +Whether or not you have SMARTQUOTES turned on, get into the habit of +entering the foot-and inch-marks, when you need them, with the +<a href="definitions.html#inlines">inline escapes</a> +<kbd>\*[FOOT]</kbd> and +<kbd>\*[INCH]</kbd>, instead of +<kbd>'</kbd> and <kbd>"</kbd>. +</p> +</div> + +<!-- -CAPS- --> + +<div class="macro-id-overline"> +<h3 id="caps" class="macro-id">Convert to upper case</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>CAPS</b> <kbd class="macro-args">toggle</kbd> +</div> + +<p> +CAPS converts all lower case letters to upper case. +Primarily, it’s a support macro used by the +<a href="docprocessing.html#docprocessing">document processing macros</a>, +but you may find it helpful on occasion. CAPS is a toggle, therefore +no argument turns it on, any argument (OFF, QUIT, X, etc.) turns +it off. +<br/> +<span class="pre-in-pp"> + .CAPS + All work and no play makes Jack a dull boy. + .CAPS OFF +</span> + +produces, on output +<br/> +<span class="pre-in-pp"> + ALL WORK AND NO PLAY MAKES JACK A DULL BOY. +</span> +If you wish to capitalise a section of type inline, use the +<a href="definitions.html#inlines">inline escapes</a>, +<a href="inlines.html#uc-lc"><kbd>\*[UC]...\*[LC]</kbd></a> +like this: +<br/> +<span class="pre-in-pp"> + All work \*[UC]and\*[LC] no play makes Jack a dull boy. +</span> + +The above produces, on output +<br/> +<span class="pre-in-pp"> + All work AND no play makes Jack a dull boy. +</span> +</p> + +<!-- -STRING- --> + +<div class="macro-id-overline"> +<h3 id="string" class="macro-id">User-defined strings</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>STRING</b> <kbd class="macro-args"><name> <what you want in the string></kbd> +</div> + +<p> +You may find sometimes that you have to type out portions of text +repeatedly. If you'd like not to wear out your fingers, you can +define a string that, whenever you call it by name, outputs whatever +you put into it. +</p> + +<p> +For example, say you’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: +<br/> +<span class="pre-in-pp"> + .STRING mw the Montreal/Windsor corridor +</span> +Once a string is defined, you can call it any time with the +<a href="definitions.html#inlines">inline escape</a> +<kbd>\*[<stringname>]</kbd>. Using the example +string above +<br/> +<span class="pre-in-pp"> + The schedule for trains along \*[mw]: +</span> +produces, on output +<br/> +<span class="pre-in-pp"> + The schedule for trains along the Montreal/Windsor corridor: +</span> +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +Be very careful not to put any spaces at the ends of strings +you’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, <kbd +class="bold">\"</kbd>, immediately following any string definition +in order to avoid spaces you can’t see, like this +<br/> +<span class="pre-in-pp"> + .STRING mw the Montreal/Windsor corridor\" +</span> +</p> +</div> + +<div class="box-tip"> +<p class="tip"> +<span class="experts">Experts:</span> +STRING is an alias for +<b>ds</b>. You can use either, or mix 'n' match with impunity. +</p> +</div> + +<!-- -ESC_CHAR- --> + +<div class="macro-id-overline"> +<h3 id="esc-char" class="macro-id">Change the escape character</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>ESC_CHAR</b> <kbd class="macro-args"><new character> | <anything></kbd> +</div> + +<p> +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 (<kbd +class="bold">\\</kbd>), 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). +</p> + +<p> +ESC_CHAR with a single character argument changes the escape +character to whatever the argument is. ESC_CHAR with no argument +restores the escape character to the backslash. +</p> + + +<div class="box-tip"> +<p class="tip"> +<span class="experts">Experts:</span> +ESC_CHAR is an alias of <kbd>.ec</kbd>. Mix 'n' match +the two with impunity. +</p> +</div> + +<!-- -SIZESPECS- --> + +<div class="macro-id-overline"> +<h3 id="sizespecs" class="macro-id">Get cap-height, x-height and descender depth of a font</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>SIZESPECS</b> +</div> + +<p> +Whenever you need to get the +<a href="definitions.html#capheight">cap-height</a>, +<a href="definitions.html#xheight">x-height</a> +or +<a href="definitions.html#descender">descender</a> +depth of type at the current point size, invoke <kbd +class="bold">.SIZESPECS</kbd>, which takes no argument. +The dimensions are stored in the string registers +<b>\*[$CAP_HEIGHT]</b>, <b>\*[$X_HEIGHT]</b> and +<b>\*[$DESCENDER]</b>, respectively, in +<a href="definitions.html#units">machine units</a> +to which the +<a href="definitions.html#unitofmeasure">unit of measure</a>, +<b>u</b>, is already appended. +</p> + +<p> +Thus, if you wanted to advance 2 inches from your current position +on the page plus the cap-height of the current point size of type +<br/> +<span class="pre-in-pp"> + .PT_SIZE <n> + .SIZESPECS + .ALD 2i+\*[$CAP_HEIGHT] +</span> +would do the trick. +</p> + +<!-- -UNDERSCORE- --> + +<div class="macro-id-overline"> +<h3 id="underscore" class="macro-id">Single underscore</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>UNDERSCORE</b> <kbd class="macro-args">[ <distance below baseline> ] "<string>"</kbd> +</div> + +<p class="requires"> +• Optional argument requires a <a href="definitions.html#unitofmeasure">unit of measure</a> +</p> + +<p> +By default, UNDERSCORE places an underscore 2 points beneath the +required +<a href="definitions.html#stringargument">string argument</a>. +The string must be enclosed in double-quotes, like this: +<br/> +<span class="pre-in-pp"> + .UNDERSCORE "Unmonitored monopolies breed high prices and poor products." +</span> +If you wish to change the distance of the rule from the baseline, +use the optional argumen +<kbd><distance below baseline></kbd> +(with a unit of measure). +<br/> +<span class="pre-in-pp"> + .UNDERSCORE 3p "Unmonitored monopolies breed high prices and poor products." +</span> +The above places upper edge of the underscore 3 points below the +<a href="definitions.html#baseline">baseline</a>. +</p> + +<h3 id="underscore-weight" class="docs">Controlling the weight of underscores</h3> +<p> +The weight (thickness) of underscores may be controlled with the +macro, UNDERSCORE_WEIGHT. Thus, if you want underscores with a +weight of 1-1/2 points, you'd invoke: +<br/> +<span class="pre-in-pp"> + .UNDERSCORE_WEIGHT 1.5 +</span> +prior to invoking <kbd>.UNDERSCORE</kbd>. Every +subsequent instance of <kbd>.UNDERSCORE</kbd> will use +this weight. +</p> + +<p> +Mom’s default underscore weight is 1/2 point. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +UNDERSCORE_WEIGHT also sets the weight of +<a href="#UNDERSCORE2">double underscores.</a> +</p> +</div> + +<h3 id="underscore-color" class="docs">Colorizing underscored text</h3> +<p> +If you want underscored text to be in a different colour from the +text around it, use the +<a href="color.html#color">COLOR</a> +macro, rather than the +<a href="color.html#color-inline">inline escape for changing color</a>. +In other words, assuming your prevailing text color is black and +you want underscored text in red +<br/> +<span class="pre-in-pp"> + .COLOR red + .UNDERSCORE "text to underscore" + .COLOR black +</span> +rather than +<br/> +<span class="pre-in-pp"> + .UNDERSCORE "\*[red]text to underscore\*[black]" +</span> +The latter will render the text in red, and the underscore in black. +You can use this to create truly rainbow effects if you want, e.g. +text in red, underscore in blue, and prevailing type in black: +<br/> +<span class="pre-in-pp"> + .UNDERSCORE "\*[red]text to underscore\*[blue]" + .COLOR black +</span> +</p> + +<h3 id="underscore-notes" class="docs">Notes on underscoring</h3> +<p> +UNDERSCORE does not work across line breaks in output copy, which is +to say that you can’t underscore a multi-line passage simply +by putting the text of the whole thing in the string you pass to +UNDERSCORE. Each +<a href="definitions.html#outputline">output line</a> +or portion of an output line you want underscored must be plugged +separately into UNDERSCORE. Bear in mind, though, that underscoring +should at best be an occasional effect in typeset copy. If you want +to emphasize an entire passage, it’s much, much better to +change fonts (e.g. to italic or bold). +</p> + +<p> +You can easily and successfully underline entire passages in +simulated typewriter-style copy (i.e. if your font is a monospaced +one, like Courier, or you’re using the document processing +macro +<a href="#printstyle">PRINTSTYLE TYPEWRITE</a>), +with the +<a href="#underline">UNDERLINE</a> +macro. UNDERLINE is designed specifically for this purpose, but +works only with the monspaced fonts. +</p> + +<p> +Mom doesn’t always get the position and length of the +underscore precisely right in +<a href="definitions.html#just">justified</a> +copy, although she’s fine with all the other +<a href="definitions.html#filled">fill modes</a>, +as well as with the no-fill modes. The reason is that when text is +justified, the word spacing may expand to fill the line, but that +doesn’t happen until <i>after</i> 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 +(<kbd>\</kbd>) to each word space in the string passed +to UNDERSCORE. The word spacing of the underscored string may be +slightly smaller than the word space of the remainder of the line, +but in most cases, the difference isn’t visually noticeable. +</p> + +<p> +UNDERSCORE tends to confuse <b>gxditview</b>, even though the +output, when printed, looks fine. Generally, I recommend using +<b>gv</b> to preview files anyway. See the section on +<a href="using.html#using-previewing">previewing</a>. +</p> + +<!-- -UNDERSCORE2- --> + +<div class="macro-id-overline"> +<h3 id="underscore2" class="macro-id">Double underscore</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>UNDERSCORE2</b> <kbd class="macro-args">[ <distance below baseline> [ <distance between rules> ] ] "<string>"</kbd> +</div> + +<p class="requires"> +• Optional arguments require a <a href="definitions.html#unitofmeasure">unit of measure</a> +</p> + +<p> +By default, UNDERSCORE2 places a double underscore 2 points beneath +the required +<a href="definitions.html#stringargument">string argument</a>. +The string must be enclosed in double-quotes, like this: +<br/> +<span class="pre-in-pp"> + .UNDERSCORE2 "Unmonitored monopolies breed high prices and poor products." +</span> +The default distance between the two rules is 2 points, measured +from the bottom edge of the upper rule to the top edge of the lower +one. +</p> + +<p> +If you wish to change the distance of the double underscore from the +<a href="definitions.html#baseline">baseline</a>, +use the optional argument +<kbd><distance below baseline></kbd> +(with a unit of measure), e.g., +<br/> +<span class="pre-in-pp"> + .UNDERSCORE2 3p "Unmonitored monopolies breed high prices and poor products." +</span> +which places the upper edge of the first rule of the double +underscore 3 points below the baseline. +</p> + +<p> +If you wish to change the distance between the two rules as well, +use the second optional argument +<kbd><distance between rules></kbd> +(with a unit of measure). Be aware that you must give a value for +the first optional argument if you want to use the second. The +distance between the two rules is measured from the bottom edge of +the upper rule to the top edge of the lower one. +</p> + +<p> +The weight (thickness) of double underscores may be controlled with +the macro +<a href="#underscore-weight">UNDERSCORE_WEIGHT</a> +(q.v). +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +The same restrictions and caveats apply to UNDERSCORE2 as to +UNDERSCORE. See the +<a href="#underscore-notes">NOTES</a> +for UNDERSCORE. +</p> +</div> + +<!-- -UNDERLINE- --> + +<div class="macro-id-overline"> +<h3 id="underline" class="macro-id">Underline text — monospaced fonts only</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>UNDERLINE</b> <kbd class="macro-args">toggle</kbd> +</div> + +<p> +If your font is monospaced, like Courier, or you’re using the +document processing macro +<a href="#printstyle">PRINTSTYLE TYPEWRITE</a>, +UNDERLINE allows you to underline words and passages that, in +typeset copy, would be italicized. You invoke UNDERLINE as you do +with all toggle macros — by itself (i.e. with no argument) to +initiate underlining, and with any argument (OFF, QUIT, X, etc) to +turn underlining off. +</p> + +<p> +When on, UNDERLINE underlines letters, words and numbers, but not +punctuation or spaces. This makes for more readable copy than a +solid underline. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +Underlining may also be turned on and off +<a href="definitions.html#inlines">inline</a> +with the escapes +<kbd><a href="#ul">\*[UL]...\*[ULX]</a></kbd>. +</p> +</div> + +<!-- -UL- --> + +<div class="macro-id-overline"> +<h3 id="ul" class="macro-id">Inline escape for underlining — monospaced fonts only</h3> +</div> + +<div class="box-macro-args"> +Inline: <b>\*[UL]...\*[ULX]</b> +</div> + +<p> +If your font is a monospaced one, like Courier, or you’re +using the document processing macro +<a href="#printstyle">PRINTSTYLE TYPEWRITE</a>, +<kbd>\*[UL]...\*[ULX]</kbd> underlines words and +passages that, in typeset copy, would be italicized. +</p> + +<p> +<kbd>\*[UL]</kbd> underlines all letters, words and numbers +following it, but not punctuation or spaces. This makes for more +readable copy than a solid underline. When you no longer want +underlining, <kbd>\*[ULX]</kbd> turns underlining off. +</p> + +<p> +The macro +<kbd><a href="#underline">UNDERLINE</a></kbd> +and the inline escape <kbd>\*[UL]</kbd> are functionally +identical, hence +<br/> +<span class="pre-in-pp"> + .FAM C + .FT R + .PT_SIZE 12 + .LS 24 + .SS 0 + .QUAD LEFT + Which should I heed? + .UNDERLINE + Just do it + .UNDERLINE OFF + or + .UNDERLINE + just say no? + .UNDERLINE OFF +</span> +produces the same result as +<br/> +<span class="pre-in-pp"> + .FAM C + .FT R + .PT_SIZE 12 + .LS 24 + .SS 0 + .QUAD LEFT + Which should I heed? \*[UL]Just do it\*[ULX] or \*[UL]just say no?\*[ULX] +</span> +</p> + +<!-- -PAD- --> + +<div class="macro-id-overline"> +<h3 id="pad" class="macro-id">Insert space into lines</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>PAD</b> <kbd class="macro-args">"<string with pad markers inserted>" [ NOBREAK ]</kbd> +</div> + +<p> +With PAD, you can insert proportional amounts of whitespace into a +line. The optional <kbd id="nobreak" class="bold">NOBREAK</kbd> +argument tells mom not to advance on the page after the PAD macro +has been invoked. +</p> + +<p> +PAD calculates the difference between the length of text on the line +and the distance remaining to its end, then inserts the difference +(as whitespace) at the place(s) you specify. +</p> + +<p> +Take, for example, the following relatively common typesetting +situation, found at the bottom of legal agreements: +<br/> +<span class="pre"> + Date Signature | +</span> +</p> + +<p> +The person signing the agreement is supposed to fill in the date +as well as a signature. Space needs to be left for both, but the +exact amount is neither known, nor important. All that matters is +that there be a little space after Date, and rather more space after +Signature. (In the above, <kbd>|</kbd> represents the +end of the line at the prevailing line length.) +</p> + +<p> +The +<a href="goodies.html#pad-marker">pad marker</a> +(see below) is <kbd>#</kbd> (the pound or number sign +on your keyboard) and can be used multiple times in a line. With +that in mind, here’s how you'd input the Date/Signature line +(assuming a length of 30 picas): +<br/> +<span class="pre"> + .LL 30P + .PAD "Date#Signature###" +</span> +</p> + +<p> +When the line is output, the space remaining on the line, after +"Date" and "Signature" have been taken into +account, is split into four (because there are four # signs). One +quarter of the space is inserted between Date and Signature, the +remainder is inserted after Signature. +</p> + +<div class="examples-container"> +<h3 id="pad-example" class="docs notes">Example of PAD usage</h3> +<p style="margin-top: .5em;"> +One rarely wants merely to insert space in a line; one usually wants +to fill it with something, hence PAD is particularly useful in +conjunction with +<a href="typesetting.html#string-tabs">string tabs</a>. +The following uses the Date/Signature example, above, but adds +rules into the whitespace through the use of string tabs and +mom’s +<a href="definitions.html#inlines">inline escape</a> +<kbd><a href="inlines.html#inline-rule-mom">\*[RULE]</a></kbd>. +(Instead of <kbd>\*[RULE]</kbd>, groff’s line +drawing function, +<kbd><a href="inlines.html#inline-linedrawing-groff">\l'<distance>'</a></kbd> +could be used.) +<br/> +<span class="pre-in-pp"> + .LL 30P + .PAD "Date \*[ST1]#\*[ST1X] Signature \*[ST2]###\*[ST2X]" NOBREAK + .ST 1 J + .ST 2 J + .TAB 1 + \*[RULE] + .TN + \*[RULE] + .TQ +</span> +If you’re not a typesetter, and if you’re new to groff, +the example probably looks like gibberish. My apologies. However, +remember that typesetting is a craft, and without having studied the +craft, it takes a while to grasp its concepts. +</p> + +<p> +Basically, what the example does is: +</p> +<ol style="margin-top: -.5em; margin-bottom: -.5em;"> + <li>Pads the Date/Signature line with a shorter space for Date + (<kbd>#</kbd>) and a longer space for Signature + (<kbd>###</kbd>), encloses the padded space with string tabs + markers, and outputs the line without advancing on the page. + </li> + <li>Sets the quad for the two string tabs (in this instance, justified). + </li> + <li>Calls the first string tab and draws a rule to its full + length. + </li> + <li>Calls the second tab with + <a href="typesetting.html#tn">TN</a> + (which moves to tab 2 and stays on the same baseline) + then draws a rule to the full length of string tab 2. + </li> +</ol> + +<p> +Often, when setting up string tabs this way, you don’t want the +padded line to print immediately. To accomplish this, use +<kbd><a href="#silent">SILENT</a></kbd>. +See the +<a href="typesetting.html#string-tabs-tut">quickie tutorial on string tabs</a> +for an example. +</p> +</div> + +<div class="box-tip"> +<p class="tip-top"> +<span class="note">Note:</span> +Because the pound sign +(<kbd>#</kbd>) is used as the pad marker, you +can’t use it as a literal part of the pad string. If you need +the sign to appear in the text of a padded line, change the pad +marker with +<kbd><a href="#pad-marker">PAD_MARKER</a></kbd>. +Also, be aware that <kbd>#</kbd> as a pad marker +only applies within the PAD macro; at all other times it prints +literally, just as you'd expect. +</p> + +<p class="tip-bottom"> +Another important consideration when using PAD is that because the +string must be enclosed in double-quotes, you can’t use the +double-quote (<kbd>"</kbd>) as part of the string. The +way to circumvent this is to use the groff +<a href="definitions.html#inlines">inline escapes</a> +<kbd>\(lq</kbd> and <kbd>\(rq</kbd> +(leftquote and rightquote respectively) whenever double-quotes are +required in the string passed to PAD. +</p> +</div> + +<!-- -PAD_MARKER- --> + +<div class="macro-id-overline"> +<h3 id="pad-marker" class="macro-id">Change/set the marker used with PAD</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>PAD_MARKER</b> <kbd class="macro-args">"<character to use as the pad marker></kbd> +</div> + +<p> +If you need to change mom’s default pad marker (<kbd +class="bold">#</kbd>), either because you want a literal # in +the padded line, or simply because you want to use another character +instead, use PAD_MARKER, whose argument is the new pad marker +character you want. +<br/> +<span class="pre-in-pp"> + .PAD_MARKER @ +</span> +changes the pad marker to <kbd>@</kbd>. +</p> + +<p> +Once you've changed the pad marker, the new marker remains in effect +for every instance of +<a href="#pad">PAD</a> +until you change it again (say, back to the pound sign). +</p> + +<!-- -\*[LEADER]- --> + +<div class="macro-id-overline"> +<h3 id="leader" class="macro-id">Inline escape to add leaders to a line</h3> +</div> + +<div class="box-macro-args"> +Inline: <b>\*[LEADER]</b> +</div> + +<p> +Whenever you want to fill a line or tab with +<a href="definitions.html#leader">leaders</a>, +use the +<a href="definitions.html#inlines">inline escape</a> +<kbd>\*[LEADER]</kbd>. The remainder of the line or +tab will be filled with the leader character. Mom’s default +leader character is a period (dot), but you can change it to any +character you like with +<kbd><a href="#leader-character">LEADER_CHARACTER</a></kbd>. +</p> + +<div class="box-tip"> +<p class="tip-top"> +<span class="note">Note:</span> +<kbd>\*[LEADER]</kbd> fills lines or tabs right to +their end. You cannot insert leaders into a line or tab and have +text following the leader on the same line or in the same tab. +Should you wish to achieve such an effect typographically, create +tabs for each element of the line and fill them appropriately with +the text and leaders you need. +<a href="typesetting.html#string-tabs">String tabs</a> +are perfect for this. An example follows. +<br/> +<span class="pre"> + .LL 30P + .PAD "Date\*[ST1]#\*[ST1X]Signature\*[ST2]###\*[ST2X]" + .EL + .ST 1 J + .ST 2 J + .TAB 1 + \*[LEADER] + .TN + \*[LEADER] + .TQ +</span> +</p> + +<p class="tip-bottom"> +The PAD line sets the words Date and Signature, and marks string +tabs around the pad space inserted in the line. The string tabs are +then "set", called, and filled with leaders. The result +looks like this: +<br/> +<span class="pre" style="margin-bottom: -1em;"> + Date.............Signature..................................... +</span> +</p> +</div> + +<!-- -LEADER_CHARACTER- --> + +<div class="macro-id-overline"> +<h3 id="leader-character" class="macro-id">Change/set the leader character</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>LEADER_CHARACTER</b> <kbd class="macro-args"><character></kbd> +</div> + +<p> +LEADER_CHARACTER takes one argument: a single character you would +like to be used for +<a href="definitions.html#leader">leaders</a>. +(See +<kbd><a href="#leader">\*[LEADER]</a></kbd> +for an explanation of how to fill lines with leaders.) +</p> + +<p> +For example, to change the leader character from mom’s +default (a period) to the underscore character, enter +<br/> +<span class="pre-in-pp"> + .LEADER_CHARACTER _ +</span> +</p> + +<!-- -DROPCAP- --> + +<div class="macro-id-overline"> +<h3 id="dropcap" class="macro-id">Drop caps</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>DROPCAP</b> <kbd class="macro-args"><dropcap letter> <number of lines to drop> [ COND <percentage> | EXT <percentage> ]</kbd> +</div> + +<p> +The first two arguments to DROPCAP are the letter you want to be the +<a href="definitions.html#dropcap">drop cap</a> +and the number of lines you want it to drop. By default, mom uses +the current family and font for the drop cap. +</p> + +<p> +The optional argument (<kbd>COND</kbd> or <kbd>EXT</kbd>) indicates +that you want the drop cap condensed (narrower) or extended (wider). +If you use <kbd class="bold">COND</kbd> or <kbd>EXT</kbd>, you must +follow the argument with the percentage of the letter’s normal +width you want it condensed or extended. No percent sign +(<kbd>%</kbd>) is required. +</p> + +<p> +Mom will do her very best to get the drop cap to line up with the +first line of text indented beside it, then set the correct number +of indented lines, and restore your left margin when the number of +drop cap lines has been reached. +</p> + +<p> +Beginning a paragraph with a drop cap “T” looks like this: +<br/> +<span class="pre"> + .DROPCAP T 3 COND 90 + he thousand injuries of Fortunato I had borne as best I + could, but when he ventured upon insult, I vowed revenge. + You who so well know the nature of my soul will not suppose, + however, that I gave utterance to a threat... +</span> +</p> + +<p> +The drop cap, slightly condensed but in the current family and font, +will be three lines tall, with whatever text fills those three +lines indented to the right of the letter. The remainder of the +paragraph’s text will revert to the left margin. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +When using the +<a href="docprocessing.html#docprocessing">document processing macro</a> +<a href="docelement.html#pp">PP</a>, +DROPCAP only works +</p> +<ul style="margin-top: -1em; margin-bottom: 0;"> + <li>with initial paragraphs (i.e. at the start of the document, + or after + <a href="docelement.html#head">HEAD</a>),</li> + <li>when <kbd>.DROPCAP</kbd> comes immediately after <kbd>.PP</kbd>,</li> + <li>the + <a href="docprocessing.html#printstyle">PRINTSTYLE</a> + is TYPESET.</li> +</ul> +<p class="tip-bottom"> +If these conditions aren’t met, DROPCAP is silently ignored. +</p> +</div> + +<div class="box-important"> +<p class="tip"> +<span class="important">Warning:</span> +DROPCAP puts a bit of a strain on resource-challenged systems. If +you have such a system and use drop caps extensively in a document, +be prepared for a wait while mom does her thing. +</p> +</div> + +<h3 id="dropcap-support" class="docs control-macros-header">Support macros for DROPCAP</h3> +<p> +Drop caps are the bane of most typesetters’ existence. +It’s very difficult to get the size of the drop cap right +for the number of drop lines, especially if the drop cap is in a +different family from the prevailing family of running text. Not +only that, but there’s the gutter around the drop cap to take +into account, plus the fact that the letter may be too wide or too +narrow to look anything but odd or misplaced. +</p> + +<p> +Mom solves the last of these problems with the <kbd>COND</kbd> and +<kbd>EXT</kbd> arguments. The rest she solves with macros that +change the default behaviour of DROPCAP, namely +</p> +<ul class="no-enumerator" style="margin-top: -.5em; margin-left: -.5em;"> + <li><a href="#dropcap-family">DROPCAP_FAMILY</a></li> + <li><a href="#dropcap-font">DROPCAP_FONT</a></li> + <li><a href="#dropcap-color">DROPCAP_COLOR</a></li> + <li><a href="#dropcap-adjust">DROPCAP_ADJUST</a></li> + <li><a href="#dropcap-gutter">DROPCAP_GUTTER</a></li> +</ul> + +<p style="margin-top: -.5em;"> +These macros must, of course, come before you invoke DROPCAP. +</p> + +<h3 id="dropcap-family" class="control-macro">• DROPCAP_FAMILY</h3> +<p style="margin-left: .66em;"> +Set the drop cap family by giving DROPCAP_FAMILY the name of the +family you want, e.g. +<br/> +<span class="pre-in-pp"> + .DROPCAP_FAMILY H +</span> +which will set the family to Helvetica for the drop cap only. +</p> + +<h3 id="dropcap-font" class="control-macro">• DROPCAP_FONT</h3> +<p style="margin-left: .66em;"> +Set the drop cap font by giving DROPCAP_FONT the name of the font +you want, e.g. +<br/> +<span class="pre-in-pp"> + .DROPCAP_FONT I +</span> +which will set the font to italic for the drop cap only. +</p> + +<h3 id="dropcap-adjust" class="control-macro">• DROPCAP_ADJUST</h3> +<p style="margin-left: .66em;"> +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. +<br/> +<span class="pre-in-pp"> + .DROPCAP_ADJUST +1 +</span> +or +<br/> +<span class="pre"> + .DROPCAP_ADJUST -.75 +</span> +</p> + +<p style="margin-left: .66em;"> +DROPCAP_ADJUST only understands +<a href="definitions.html#picaspoints">points</a>, +therefore do not append any +<a href="definitions.html#unitofmeasure">unit of measure</a> +to the argument. And always be sure to prepend the plus or +minus sign, depending on whether you want the drop cap larger or +smaller. +</p> + +<h3 id="dropcap-color" class="control-macro">• DROPCAP_COLOR</h3> +<p style="margin-left: .66em;"> +If you'd like your drop cap colourized, simply invoke +<kbd>.DROPCAP_COLOR <color></kbd> with the name of a colour you've already +created (“initialized”) with +<a href="color.html#newcolor">NEWCOLOR</a> +or +<a href="color.html#xcolor">XCOLOR</a>. +Only the drop cap will be colourized; all other text will remain at +the current colour default (usually black). +</p> + +<h3 id="dropcap-gutter" class="control-macro">• DROPCAP_GUTTER</h3> +<p style="margin-left: .66em;"> +By default, mom puts three points of space between the drop cap +and the text indented beside it. If you want another value, use +DROPCAP_GUTTER (with a unit of measure), like this: +<br/> +<span class="pre-in-pp"> + .DROPCAP_GUTTER 6p +</span> +</p> + +<!-- -\*[SUP]- --> + +<div class="macro-id-overline"> +<h3 id="sup" class="macro-id">Superscript</h3> +</div> + +<div class="box-macro-args"> +Inlines: <kbd>\*[SUP]...\*[SUPX]</kbd> +</div> + +<p> +Superscripts are accomplished +<a href="definitions.html#inlines">inline</a>. +Whenever you need one, typically for numerals, all you need to do is +surround the superscript with the inlines above. <kbd>\*[SUP]</kbd> +begins superscripting; <kbd>\*[SUPX]</kbd> turns it off. +</p> + +<p id="cond-or-ext-sup"> +If your running type is +<a href="typesetting.html#cond-inline">pseudo-condensed</a> +or +<a href="typesetting.html#ext-inline">pseudo-extended</a> +and you want your superscripts to be equivalently pseudo-condensed +or -extended, use <kbd>\*[CONDSUP]...\*[CONDSUPX]</kbd> or +<kbd>\*[EXTSUP]...\*[EXTSUPX]</kbd>. +</p> + +<p> +The superscript inlines are primarily used by the +<a href="docprocessing.html#docprocessing">document processing macros</a> +for automatic generation of numbered footnotes. However, you may +find them useful for other purposes. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +Mom does a pretty fine job of making superscripts look good in any +font and at any size. If you’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. +</p> +</div> + +<h3 id="sup-raise" class="docs">SUPERSCRIPT RAISE AMOUNT</h3> +<p> +By default, mom raises superscripts 1/3 of an +<a href="definitions.html#ems">em</a> +above the baseline. If you’re not happy with this default, you can +change it by invoking SUPERSCRIPT_RAISE_AMOUNT with +the amount you want them raised. A +<a href="definitions.html#unitofmeasure">unit of measure</a> +must be appended directly to the amount. Thus, you want +superscripts raised by 3 +<a href="definitions.html#picaspoints">points</a> +instead of 1/3 em, you'd +do +<br/> +<span class="pre-in-pp"> + .SUPERSCRIPT_RAISE_AMOUNT 3p +</span> +and all subsequent superscripts would be raised by 3 points. +</p> + +<div class="rule-long"><hr/></div> + +<!-- Navigation links --> +<table style="width: 100%; margin-top: 12px;"> +<tr> + <td style="width: 33%;"><a href="toc.html">Back to Table of Contents</a></td> + <td style="width: 33%; text-align: center;"><a href="#top">Top</a></td> + <td style="width: 33%; text-align: right;"><a href="inlines.html#top">Next: Inline escapes</a></td> +</tr> +</table> + +</div> + +<div class="bottom-spacer"><br/></div> + +</body> +</html> +<!-- vim: fileencoding=utf-8: nomodified: --> 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 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- +This file is part of groff, the GNU roff type-setting system. + +Copyright (C) 2004, 2005, 2006, 2009, 2010 Free Software Foundation, Inc. +Written by Peter Schaffter. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with the +Invariant Sections being this comment section, with no Front-Cover +Texts, and with no Back-Cover Texts. + +A copy of the Free Documentation License is included as a file called +FDL in the main directory of the groff source package. +--> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"> + +<head> + <meta http-equiv="content-type" content="text/html;charset=utf-8"/> + <title>Mom -- Graphical Objects</title> + <link rel="stylesheet" type="text/css" href="stylesheet.css" /> +</head> + +<body style="background-color: #f5faff;"> + +<!-- ==================================================================== --> + +<div id="top" class="page"> + +<!-- Navigation links --> +<table style="width: 100%;"> +<tr> + <td><a href="toc.html">Back to Table of Contents</a></td> + <td style="text-align: right;"><a href="docprocessing.html#top">Next: Document processing</a></td> +</tr> +</table> + +<h1 class="docs">Graphical objects</h1> + +<div style="text-align: center;"> +<ul class="no-enumerator" style="margin-left: -2.5em;"> + <li><a href="#intro-graphical">Introduction to graphical objects</a></li> + <li><a href="#behaviour">Graphical objects behaviour</a></li> + <li><a href="#order">Order of arguments</a></li> + <li><a href="#index-graphical">Index of graphical objects macros</a></li> +</ul> +</div> + +<div class="rule-medium"><hr/></div> + +<h2 id="intro-graphical" class="docs">Introduction to graphical objects</h2> + +<p> +Groff has a number of +<a href="definitions.html#inlines">inline escapes</a> +for drawing rules, polygons, ellipses and splines. All begin with +<kbd>\D</kbd> (presumably for “Draw”) and are documented +in the groff info manual: +<br/> +<span class="pre-in-pp"> + info groff => Escape index => \D +</span> +The escapes allow you to draw just about any simple graphical object +you can think of, but owing to their syntax, they’re not always easy +to read, which can make tweaking them difficult. Additionally, +while they perform in a <i>consistent</i> manner, they don’t +always perform in an <i>expected</i> manner. +</p> + +<p> +Experience shows that the most common graphical elements typesetters +need are rules (horizontal and vertical), boxes, and circles (or +ellipses). For this reason, mom provides macros +to draw these objects in an easy-to-understand way; the results are +predictable, and mom’s syntax makes fixes or tweaks +painless. +</p> + +<p id="graphical-example"> +For example, if you want to draw a 2-inch square outline box at the left +margin using groff’s <kbd>\D</kbd> escapes, it looks like this: +<br/> +<span class="pre-in-pp"> + back up + by + weight + +-------+ + | | + \D't 500'\h'-500u'\D'p 2i 0 0 2i -2i 0 0 -2i' + | | | | + +-------+ +------------------------+ + set rule draw box, 1 line at a time + weight +</span> + +Obviously, this isn’t very efficient for something as simple as a +box. +</p> + +<p> +Here’s the same box, drawn with mom’s box drawing +macro, +<kbd><a href="#dbx">DBX</a></kbd>: +<br/> +<span class="pre-in-pp"> + left margin indent--+ +--box width + | | + .DBX .5 0 2i 2i + | | + rule weight--+ +--box depth + (in points) +</span> +</p> + +<p> +Mom’s graphical object macros allow—in fact, +require—giving the rule weight (“thickness”) for +the object (or saying that you want it filled), an indent from the +left margin where the object begins, the dimensions of the object, +and optionally a colour for the object. +</p> + +<p> +There are no defaults for the arguments to mom'a graphical object +macros, which means you must supply the arguments every time you +invoke them. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +As stated above, mom only provides macros for commonly-used +graphical objects (rules, boxes, circles). More complex objects +(polygons, non-straight lines, splines) must be drawn using +groff’s <kbd>\D</kbd> escapes. +</p> +</div> + +<h3 id="behaviour" class="docs">Graphical object behaviour</h3> + +<p> +Mom’s graphical object macros all behave in the following, +carved-in-stone ways: +</p> +<ol style="margin-top: -.5em; margin-bottom: -.5em;"> + <li>Objects are drawn from the + <a href="definitions.html#baseline">baseline</a> + down, including horizontal rules.</li> + <li>Objects begin precisely at the left indent supplied as + an argument to the macro.</li> + <li>Objects are drawn from left to right.</li> + <li>Enclosed objects (boxes, circles) are drawn from the + perimeter <i>inward</i>.</li> + <li>Objects return to their horizontal/vertical point of origin.</li> +</ol> + +<p> +The consistency means that once you've mastered the very simple +order of arguments that applies to invoking graphical object +macros, you can draw objects with full confidence that you know +exactly where they’re placed and how much room they +occupy. Furthermore, because all return to their point of origin, +you’ll know exactly where you are on the page. +</p> + +<h3 id="order" class="docs">Order of arguments</h3> + +<p> +The order of arguments to the graphical object macros is the same +for every macro: +</p> +<ul style="margin-top: -.5em; margin-bottom: -.5em;"> + <li>the <kbd><span style="text-decoration: underline">W</span></kbd>eight of the rule + <ul style="margin-left: -.75em;"> + <li>if the object is enclosed (i.e. is a box or circle), the + weight of the rule if you want the object outlined</li> + <li>the single word, <kbd>SOLID</kbd>, may be used in place + of the <b>weight</b> argument if you want the + object filled</li> + </ul></li> + <li>the <kbd><span style="text-decoration: underline">I</span></kbd>ndent from the current left margin at + which to begin the object</li> + <li>the <kbd><span style="text-decoration: underline">L</span></kbd>ength of the object, if applicable</li> + <li>the <kbd><span style="text-decoration: underline">D</span></kbd>epth of the object, if applicable</li> + <li>the <kbd><span style="text-decoration: underline">C</span></kbd>olour of the object (optional)</li> +</ul> + +<p> +A simple mnemonic for the order of arguments is “<b>WILD +C</b>ard”. 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, +<kbd><a href="#drh">DRH</a></kbd>, +with only the arguments (from the mnemonic) that apply: <b>W-I-L</b> (and +possibly <b>C</b>). +</p> + +<div class="macro-list-container"> +<h3 id="index-graphical" class="macro-list">Graphical objects macros</h3> + +<ul class="macro-list"> + <li><a href="#drh">DRH</a> + – horizontal rules</li> + <li><a href="#drv">DRV</a> + – vertical rules</li> + <li><a href="#dbx">DBX</a> + – box</li> + <li><a href="#dcl">DCL</a> + – circles or ellipses</li> +</ul> +</div> + +<!-- -DRH- --> + +<div class="macro-id-overline"> +<h3 id="drh" class="macro-id">Drawing horizontal rules</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>DRH</b> <kbd class="macro-args"><none> | <weight> <indent> <length> [<colour>]</kbd> +</div> + +<p class="requires"> +• The argument to <kbd class="normal"><weight></kbd> is in +<a href="definitions.html#picaspoints" class="normal">points</a>, +but do <span class="normal">NOT</span> append the +<a href="definitions.html#unitsofmeasure">unit of measure</a>, +<kbd class="normal">p</kbd>. +<br/> +• The arguments, <kbd class="normal"><indent></kbd> and +<kbd class="normal"><length></kbd>, require a unit of measure. +</p> + +<p> +If all you want is to draw a rule from your current left +margin to your current right margin (in other words, a "full +measure" rule), you may invoke <kbd>.DRH</kbd> without any +arguments. +</p> +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +DRH is the only graphical object macro that may be invoked +without arguments. The weight (“thickness”) of +the rule is determined by the argument you last gave the +macro, <a href="inlines.html#rule-weight">RULE_WEIGHT</a>. +DRH, used this way, is exactly equivalent to entering the +<a href="definitions.html#inlines">inline escape</a>, <a +href="inlines.html#inline-rule-mom"><kbd>\*[RULE]</kbd></a>. +</p> +</div> + +<p style="margin-top: -.5em;"> +To draw horizontal rules of a specified length, you must, at +a minimum, supply DRH with the arguments <kbd>weight,</kbd> +<kbd>indent</kbd> (measured from the current left margin) and +<kbd>length</kbd>. +</p> + +<p> +Optionally, you may give a <kbd>colour</kbd> argument. The colour +may be either one defined with +<a href="color.html#newcolor">NEWCOLOR</a>, +or a named X-colour inititialized with +<a href="color.html#xcolor">XCOLOR</a>, +or an X-colour alias (again, initialized with XCOLOR). +</p> + +<p> +Say, for example, you want to draw a 1-1/4 point horizontal rule +that starts 2 picas from the current left margin and runs for 3 +inches. To do so, you'd invoke <kbd>.DRH</kbd> like this: +<br/> +<span class="pre-in-pp"> + weight length + | | + .DRH 1.25 2P 3i + | + indent +</span> +(Note that the rule weight argument, which is expressed in points, +must NOT have the unit of measure <kbd>p</kbd> appended to it.) +</p> + +<p> +If, in addition, you want the rule blue: +<br/> +<span class="pre-in-pp"> + .DRH 1.25 2P 3i blue +</span> +</p> + +<h3 class="docs">How mom handles the positioning of horizontal rules</h3> + +<p> +Horizontal rules are drawn from left to right, and from the baseline +down. “From the baseline down” means that if you request +a rule with a weight of four points, the four points of rule fall +entirely below the baseline. +</p> + +<p> +Furthermore, after the rule is drawn, mom returns you to the current +left margin, at the same vertical position on the page as when DRH +was invoked. In other words, DRH causes no movement on the page, +either horizontal or vertical. +</p> + +<!-- -DRV- --> + +<div class="macro-id-overline"> +<h3 id="drv" class="macro-id">Drawing vertical rules</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>DRV</b> <kbd class="macro-args"><weight> <indent> <depth> [<colour>]</kbd> +</div> + +<p class="requires"> +• The argument to <kbd class="normal"><weight></kbd> is in +<a href="definitions.html#picaspoints" class="normal">points</a>, +but do <span class="normal">NOT</span> append the +<a href="definitions.html#unitsofmeasure">unit of measure</a>, +<kbd class="normal">p</kbd>. +<br/> +• The arguments, <kbd class="normal"><indent></kbd> and +<kbd class="normal"><depth></kbd>, require a unit of measure. +</p> + +<p> +To draw vertical rules of a specified length, you must, at +a minimum, supply DRV with the arguments <kbd>weight,</kbd> +<kbd>indent</kbd> (measured from the current left margin) and +<kbd>depth</kbd>. +</p> + +<p> +Optionally, you may give a <kbd>colour</kbd> argument. The colour +may be either one defined with +<a href="color.html#newcolor">NEWCOLOR</a>, +or a named X-colour inititialized with +<a href="color.html#xcolor">XCOLOR</a>, +or an X-colour alias (again, initialized with XCOLOR). +</p> + +<p> +Say, for example, you want to draw a 3/4-point vertical rule that +starts 19-1/2 picas from the current left margin and has a depth of +6 centimeters. To do so, you'd invoke <kbd>.DRV</kbd> like this: +<br/> +<span class="pre-in-pp"> + weight depth + | | + .DRV .75 19P+6p 6c + | + indent +</span> +(Note that the rule weight argument, which is expressed in points, +must NOT have the unit of measure <kbd>p</kbd> appended to it.) +</p> + +<p> +If, in addition, you want the rule red: +<br/> +<span class="pre-in-pp"> + .DRV .75 19P+6p 6c red +</span> +</p> + +<h3 class="docs">How mom handles the positioning of vertical rules</h3> + +<p> +Vertical rules are drawn from the baseline down, and from left to +right. "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. +</p> + +<p> +Furthermore, after the rule is drawn, mom returns you to the current +left margin, at the same vertical position on the page as when DRV +was invoked. In other words, DRV causes no movement on the page, +either horizontal or vertical. +</p> + +<!-- -DBX- --> + +<div class="macro-id-overline"> +<h3 id="dbx" class="macro-id">Drawing boxes</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>DBX</b> <kbd class="macro-args">< <weight> | SOLID > <indent> <length> <depth> [<colour>]</kbd> +</div> + +<p class="requires"> +• The argument to <kbd class="normal"><weight></kbd> is in +<a href="definitions.html#picaspoints" class="normal">points</a>, +but do <span class="normal">NOT</span> append the +<a href="definitions.html#unitsofmeasure">unit of measure</a>, +<kbd class="normal">p</kbd>. +<br/> +• The arguments, <kbd class="normal"><indent></kbd>, +<kbd class="normal"><length></kbd> and +<kbd class="normal"><depth></kbd>, require a unit of measure. +</p> + +<p> +To draw boxes of specified dimensions, you must, at a minimum, +supply DBX with the arguments <kbd>weight</kbd> or <kbd>SOLID</kbd>, +<kbd>indent</kbd> (measured from the current left margin), +<kbd>length</kbd> and <kbd>depth</kbd>. +</p> + +<p> +Optionally, you may give a <kbd>colour</kbd> argument. The colour +may be either one defined with +<a href="color.html#newcolor">NEWCOLOR</a>, +or a named X-colour inititialized with +<a href="color.html#xcolor">XCOLOR</a>, +or an X-colour alias (again, initialized with XCOLOR). +</p> + +<p> +Say, for example, you want to draw a 1/2 point outline box that +starts one inch from the current left margin and has the dimensions +12 picas x 6 picas. To do so, you'd invoke <kbd>.DBX</kbd> like this: +<br/> +<span class="pre-in-pp"> + indent depth + | | + .DBX .5 1i 12P 6P + | | + weight length +</span> +(Note that the box weight argument, which is expressed in points, +must NOT have the unit of measure <kbd>p</kbd> appended to it.) +</p> + +<p> +If you want the same box, but solid (“filled”) rather +than drawn as an outline: +<br/> +<span class="pre-in-pp"> + .DBX SOLID 1i 12P 6P +</span> +Additionally, if you want the box green: +<br/> +<span class="pre-in-pp"> + .DBX .5 1i 12P 6P green + or + .DBX SOLID 1i 12P 6P green +</span> +</p> + +<h3 class="docs">How mom handles the positioning of boxes</h3> + +<p> +Boxes are drawn from the baseline down, from left to right, and +from the perimeter <i>inward</i>. “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 +<i>within</i> the dimensions of the box. +</p> + +<p> +Furthermore, after the box is drawn, mom returns you to the current +left margin, at the same vertical position on the page as when DBX +was invoked. In other words, DBX causes no movement on the page, +either horizontal or vertical. +</p> + +<!-- -DCL- --> + +<div class="macro-id-overline"> +<h3 id="dcl" class="macro-id">Drawing circles (ellipses)</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>DCL</b> <kbd class="macro-args">< <weight> | SOLID > <indent> <length> <depth> [<colour>]</kbd> +</div> + +<p class="requires"> +• The argument to <kbd class="normal"><weight></kbd> is in +<a href="definitions.html#picaspoints" class="normal">points</a>, +but do <span class="normal">NOT</span> append the +<a href="definitions.html#unitsofmeasure">unit of measure</a>, +<kbd class="normal">p</kbd>. +<br/> +• The arguments, <kbd class="normal"><indent></kbd>, +<kbd class="normal">length</kbd> and +<kbd class="normal"><depth></kbd>, require a unit of measure. +</p> + +<p> +To draw circles of specified dimensions, you must, at a minimum, +supply DCL with the arguments <kbd>weight</kbd> or <kbd>SOLID</kbd>, +<kbd>indent</kbd> (measured from the current left margin), +<kbd>length</kbd> and <kbd>depth</kbd>. +</p> + +<p> +Optionally, you may give a <kbd>colour</kbd> argument. The colour +may be either one defined with +<a href="color.html#newcolor">NEWCOLOR</a>, +or a named X-colour inititialized with +<a href="color.html#xcolor">XCOLOR</a>, +or an X-colour alias (again, initialized with XCOLOR). +</p> + +<p> +Say, for example, you want to draw a 1/2 point outline circle +(ellipse, actually, in this case) that starts one inch from the +current left margin and has the dimensions 6 centimeters x 3 +centimeters. To do so, you'd invoke <kbd>.DCL</kbd> like this: +<br/> +<span class="pre-in-pp"> + indent depth + | | + .DCL .5 1i 6c 3c + | | + weight ength +</span> +(Note that the box weight argument, which is expressed in points, +must NOT have the unit of measure <kbd>p</kbd> appended to it.) +</p> + +<p> +If you want the same box, but solid (“filled”) rather +than drawn as an outline: +<br/> +<span class="pre-in-pp"> + .DCL SOLID 1i 6c 3c +</span> +Additionally, if you want the circle yellow: +<br/> +<span class="pre-in-pp"> + .DCL .5 1i 6c 3c yellow + or + .DCL SOLID 1i 6c 3c yellow +</span> +</p> + +<h3 class="docs">How mom handles the positioning of circles (ellipses)</h3> + +<p> +Circles (ellipses) are drawn from the baseline down, from left +to right, and from the perimeter <i>inward</i>. “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 <i>within</i> the dimensions of the +circle or ellipse. +</p> + +<p> +Furthermore, after the circle is drawn, mom returns you to the +current left margin, at the same vertical position on the page as +when DCL was invoked. In other words, DCL causes no movement on the +page, either horizontal or vertical. +</p> + +<div class="rule-long"><hr/></div> + +<!-- Navigation links --> +<table style="width: 100%; margin-top: 12px;"> +<tr> + <td style="width: 33%;"><a href="toc.html">Back to Table of Contents</a></td> + <td style="width: 33%; text-align: center;"><a href="#top">Top</a></td> + <td style="width: 33%; text-align: right;"><a href="docprocessing.html#top">Next: Document processing</a></td> +</tr> +</table> + +</div> + +<div class="bottom-spacer"><br/></div> + +</body> +</html> +<!-- vim: fileencoding=utf-8: nomodified: --> 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 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- +This file is part of groff, the GNU roff type-setting system. + +Copyright (C) 2004, 2005, 2006, 2009, 2010 Free Software Foundation, Inc. +Written by Peter Schaffter. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with the +Invariant Sections being this comment section, with no Front-Cover +Texts, and with no Back-Cover Texts. + +A copy of the Free Documentation License is included as a file called +FDL in the main directory of the groff source package. +--> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"> + +<head> + <meta http-equiv="content-type" content="text/html;charset=utf-8"/> + <title>Mom -- Document processing, page headers/footers and pagination</title> + <link rel="stylesheet" type="text/css" href="stylesheet.css" /> +</head> + +<body style="background-color: #f5faff;"> + +<!-- ==================================================================== --> + +<div id="top" class="page"> + +<!-- Navigation links --> +<table style="width: 100%;"> +<tr> + <td><a href="toc.html">Back to Table of Contents</a></td> + <td style="text-align: right;"><a href="rectoverso.html#top">Next: Recto/verso printing, collating</a></td> +</tr> +</table> + +<h1 class="docs">Page headers/footers, pagination</h1> + +<div style="text-align: center;"> +<ul class="no-enumerator" style="margin-left: -2.5em;"> + <li><a href="#headfootpage-intro">Introduction – VERY IMPORTANT; read me!</a></li> + <li> <a href="#pagination-note">An important note on pagination</a></li> + <li><a href="#description-general">General description of headers/footers</a></li> + <li><a href="#header-style">Default specs for headers/footers</a></li> + <li><a href="#vertical-spacing">Vertical placement and spacing of headers/footers</a></li> +</ul> +</div> + +<div class="rule-medium"><hr/></div> + +<h2 id="toc-doc-head-foot-page" class="docs" style="text-align: center;">Table of contents</h2> + +<h3 class="toc toc-docproc-header" style="margin-top: 1em;"><a class="header-link" href="#headfoot-management">Managing page headers and footers</a></h3> +<ul class="toc-docproc" style="margin-top: .5em;"> + <li><a href="#headers">HEADERS</a> – on or off</li> + <li><a href="#footers">FOOTERS</a> – on or off</li> + <li><a href="#footer-on-first-page">FOOTER_ON_FIRST_PAGE</a></li> +</ul> +<h3 class="toc toc-docproc-header"><a class="header-link" href="#headfoot-control">Control macros for headers/footers</a></h3> + <ul class="toc-docproc" style="margin-top: .5em;"> + <li><a href="#index-headfoot-control">Header/footer control macros and defaults</a> + <ul class="toc-docproc"> + <li><a href="#hdrftr-strings">Header/footer strings</a> + <ul class="toc-docproc"> + <li><a href="#reserved-strings">Using mom’s reserved strings in header/footer definitions</a> (TITLE, AUTHOR, etc.)</li> + </ul></li> + <li><a href="#hdrftr-style">Header/footer style</a> + <ul class="toc-docproc"> + <li><a href="#hdrftr-style-global">Global changes</a></li> + <li><a href="#hdrftr-style-part">Part-by-part changes</a></li> + </ul></li> + <li><a href="#hdrftr-vertical">Vertical placement and spacing of headers/footers</a> + <ul class="toc-docproc"> + <li><a href="#hdrftr-margin">HEADER_MARGIN / FOOTER_MARGIN</a> + <ul class="toc-docproc no-enumerator" style="margin-left: -2em;"> + <li>– <a href="#footer-margin">Important: FOOTER_MARGIN and bottom margins</a></li> + </ul></li> + </ul></li> + <li><a href="#hdrftr-separator">The header/footer separator rule</a> + <ul class="toc-docproc"> + <li><a href="#hdrftr-rule">HEADER_RULE</a> – on or off</li> + <li><a href="#hdrftr-rule-weight">HEADER_RULE_WEIGHT</a> – weight of the rule</li> + <li><a href="#hdrftr-rule-gap">HEADER_RULE_GAP</a> – distance of rule from header/footer</li> + <li><a href="#hdrftr-rule-color">HEADER_RULE_COLOR</a> – colour of the header/footer rule</li> + </ul></li> + </ul></li> +</ul> +<h3 class="toc toc-docproc-header"><a class="header-link" href="#userdef-hdrftr-rv">User-defined, single string recto/verso headers/footers</a></h3> +<ul class="toc-docproc" style="margin-top: .5em;"> + <li><a href="#hdrftr-recto">HEADER_RECTO, HEADER_VERSO</a> + <ul style="margin-left: -.5em"> + <li><a href="#userdef-hdrftr">User-defined, single string headers/footers (no recto/verso)</a></li> + <li><a href="#padding-hdrftr">Padding the header-recto/header-verso string</a></li> + </ul></li> +</ul> +<h3 class="toc toc-docproc-header"><a class="header-link" href="#headers-and-footers-intro">Headers and footers on the same page</a></h3> +<h3 class="toc toc-docproc-header" style="margin-top: .75em;"><a class="header-link" href="#pagination-intro">Pagination</a></h3> +<ul class="toc-docproc" style="margin-top: .5em;"> + <li><a href="#index-pagination">Pagination macros</a></li> + <li><a href="#index-pagination-control">Pagination control macros and defaults</a></li> +</ul> +<h3 class="toc toc-docproc-header"><a class="header-link" href="#blank-pages">Inserting blank pages into a document</a></h3> + +<div class="rule-medium" style="margin-top: 1.5em;"><hr/></div> + +<h2 id="headfootpage-intro" class="macro-group">Managing page headers and footers</h2> + +<div id="headerfooter" class="box-tip"> +<p class="tip-top"> +<span class="note">Note:</span> +Because headers and footers are virtually identical, this +documentation addresses itself only to headers. In all cases, +unless otherwise noted, descriptions of headers describe footers as +well. +</p> + +<p class="tip-bottom"> +Furthermore, any +<a href="definitions.html#controlmacro">control macro</a> +that begins with HEADER_ may be used to control footers, simply by +replacing HEADER_ with FOOTER_. +</p> +</div> + +<p style="margin-top: -.75em;"> +<a href="definitions.html#header">Headers</a> +and +<a href="definitions.html#footer">footers</a>, +as defined in the section +<a href="definitions.html#mom">Mom’s Document Processing Terms</a>, +are those parts of a document that contain information about the document +itself which appear in the margins either above or below +<a href="definitions.html#running">running text</a>. +They are, in all respects but two, identical. The differences are: +</p> +<ol style="margin-top: -.5em; margin-bottom: -.5em;"> + <li>headers appear in the margin <i>above</i> running text while + footers appear in the margin <i>beneath</i> running text; + </li> + <li>the (optional) rule that separates headers from running + text appears <i>below</i> the header while + the (optional) rule that separates footers from running + text appears <i>above</i> the footer. + </li> +</ol> + +<div id="pagination-note" class="box-tip" style="margin-top: 1.5em;"> +<p class="tip"> +<span class="note">Note:</span> +While the single page number that mom generates in either the top +or bottom margin above or below running text is technically a kind +of header/footer, mom and this documentation treat it as a separate +page element. +</p> +</div> + +<div id="author-note" class="box-tip"> +<p class="tip"> +<span class="note">Author's note:</span> +Left to their own devices (i.e. if you’re happy with the way +mom does things by default), headers are something you never have to +worry about. You can skip reading this section entirely. But if +you want to change them, be advised that headers have more macros to +control their appearance than any other document element. The text +of this documentation becomes correspondingly dense at this point. +</p> +</div> + +<h3 id="description-general" class="docs">General description of headers/footers</h3> + +<p> +Headers comprise three distinct parts: a left part, a centre part, +and a right part. Each part contains text (a “string”) +that identifies some aspect of the document as a whole. +</p> + +<p> +”The left part (“header-left) lines up with the +document’s left margin. The centre part (“header +centre“) is centred on the document’s line length. +”The right part (“header-right) lines up with the +document’s right margin. Not all parts need contain a string, +and if you don’t want headers at all, you can turn them off +completely. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note to groff experts:</span> +Although mom’s headers resemble the three-part titles +generated by <kbd>.tl</kbd>, they’re in no way related to it, +nor based upon it. <kbd>.tl</kbd> is not used at all in mom. +</p> +</div> + +<p> +Normally, mom fills headers with strings appropriate to the document +type selected with +<a href="docprocessing.html#doctype">DOCTYPE</a>. +You can, however, supply whatever strings you like—including +page numbers—to go in any part of headers. What’s more, +you can set the family, font, size, colour and capitalization style +(caps or caps/lower-case) for each header part individually. +</p> + +<p> +By default, mom prints a horizontal rule beneath headers to separate +them visually from running text. In the case of footers, the rule +is above. You can increase or decrease the space between the header +and the rule if you like (with +<kbd><a href="#hdrftr-rule-gap">HEADER_RULE_GAP</a></kbd>), +or remove it completely. +</p> + +<h3 id="header-style" class="docs">Default specs for headers/footers</h3> + +<p> +Mom makes small type adjustments to each part of the header (left, +centre, right) to achieve an aesthetically pleasing result. The +defaults are listed below. (The strings mom puts by default in each +part are explained in +<a href="docprocessing.html#doctype">DOCTYPE</a>.) +</p> + +<div class="defaults-container" style="padding-bottom: 8px;"> +<p class="defaults" style="padding-top: 6px; padding-bottom: 6px; text-align: center;"> +<i>Note:</i> Except for capitalization (all caps or caps/lower-case), +these defaults apply only to +<a href="docprocessing.html#printstyle">PRINTSTYLE <kbd>TYPESET</kbd></a>. +</p> +<span class="pre defaults"> +TYPE SPEC HEADER LEFT HEADER CENTER HEADER RIGHT +--------- ----------- ------------- ------------ +Family document default document default document default +Font roman italic roman +Colour (black) (black) (black) +All caps no no yes +Size* -.5 (points) -.5 (points) -2 (points) + (-2 if all caps) (-2 if all caps) (-.5 if not all caps) + +*Relative to the point size of type in paragraphs +</span> +</div> + +<p style="margin-top: -1.5em;"> +You can, of course, change any of the defaults using the appropriate +control macros. And should you wish to design headers from the +ground up, mom has a special macro, +<a href="#hdrftr-plain">HEADER_PLAIN</a>, +that removes all type adjustments to headers. The straightforward +type specs for paragraphs are used instead, providing a simple +reference point for any alterations you want to make to the family, +font, size and capitalization style of any header part. +</p> + +<h3 id="vertical-spacing" class="docs">Vertical placement and spacing of headers/footers</h3> + +<p> +As explained in the section, +<a href="docprocessing.html#behaviour">Typesetting macros during document processing</a>, +the top and bottom margins of a mom document are the vertical start +and end positions of +<a href="definitions.html#running">running text</a>, +not the vertical positions of headers or footers, which, by definition, +appear in the margins above (or below) running text. +</p> + +<p> +The vertical placement of headers is controlled by the macro +<a href="#hdrftr-margin">HEADER_MARGIN</a>, +which establishes the +<a href="definitions.html">baseline</a> +position of headers relative to the top edge of the page. The +header rule, whose position is relative to the header itself, is +controlled by a separate macro. +</p> + +<p> +FOOTER_MARGIN is the counterpart to HEADER_MARGIN, and establishes +the baseline position of footers relative to the bottom edge of the +page. +</p> + +<p> +The distance between headers and the start +of running text can be controlled with the macro, +<a href="#hdrftr-gap">HEADER_GAP</a> +(effectively making HEADER_MARGIN + HEADER_GAP the top margin of +running text unless you give mom a literal top margin (with +<a href="typesetting.html#t-margin">T_MARGIN</a>), +in which case she ignores HEADER_GAP and begins the running text at +whatever top margin you give. +</p> + +<p> +FOOTER_GAP and +<a href="typesetting.html#b-margin">B_MARGIN</a> +work similarly, except they determine where running text <i>ends</i> +on the page. (See +<a href="#footer-margin">Important – footer margin and bottom margins</a> +for a warning about possible conflicts between the footer margin and +the bottom margin.) +</p> + +<p> +Confused? Mom apologizes. It’s really quite simple. By +default, mom sets headers 4-1/2 +<a href="definitions.html#picaspoints">picas</a> +down from the top of the page and begins the running text 3 picas +(the HEADER_GAP) beneath that, which means the effective top margin +of the running text is 7-1/2 picas (visually approx. 1 inch). +However, if you give mom a literal top margin (with +<a href="typesetting.html#t-margin">T_MARGIN</a>), +she ignores the HEADER_GAP and starts the running text at whatever +top margin you give. +</p> + +<p> +Footers are treated similarly. Mom sets footers 3 picas up from the +bottom of the page, and interrupts the processing of running text 3 +picas (the FOOTER_GAP) above that (again, visually approx. 1 inch). +However, if you give mom a literal bottom margin (with +<a href="typesetting.html#b-margin">B_MARGIN</a>), +she ignores the FOOTER_GAP and interrupts the processing of running +text at whatever bottom margin you give. +</p> + +<p> +If mom is paginating your document (she does, by default, at the +bottom of each page), the vertical spacing and placement of page +numbers, whether at the top or the bottom of the page, is managed +exactly as if the page numbers were headers (or footers), and are +controlled by the same macros. See +<a href="#pagination">Pagination control</a>. +</p> + +<div class="rule-short"><hr/></div> + +<!-- ======================================================================== --> + +<h2 id="headfoot-management" class="macro-group">Managing headers/footers</h2> + +<p> +The following are the basic macros for turning +<a href="definitions.html#header">headers</a> +or +<a href="definitions.html#footer">footers</a> +on or off. They should be invoked prior to +<a href="docprocessing.html#start">START</a>. +</p> + +<p> +By default, mom prints page headers. If you turn +them off, she will begin the +<a href="definitions.html#running">running text</a> +on each page with a default top margin of 6 +<a href="definitions.html#picaspoints">picas</a> +unless you have requested a different top margin (with +<a href="typesetting.html#t-margin">T_MARGIN</a>) +prior to +<a href="docprocessing.html#start">START</a>. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +<a href="#headers">HEADERS</a> +and +<a href="#footers">FOOTERS</a> +are mutually exclusive. If headers are on, footers (but not +bottom-of-page numbering) are automatically turned off. Equally, +if footers are on, headers (but not top-of-page numbering) are +automatically turned off. Thus, if you’d prefer footers in a +document, you need only invoke +<kbd><a href="#footers">.FOOTERS</a></kbd>; +there’s no need to turn headers off first. +</p> +</div> + +<p> +If you need both headers and footers, there’s a special macro, +<a href="#headers-and-footers">HEADERS_AND_FOOTERS</a>, +that allows you to set it up. +</p> + +<div class="macro-list-container"> +<h3 id="index-hdrftr" class="macro-list">Header/footer macros</h3> +<ul class="macro-list"> + <li><a href="#headers">HEADERS</a> – on or off</li> + <li><a href="#footers">FOOTERS</a> – on or off</li> + <li><a href="#footer-on-first-page">FOOTER_ON_FIRST_PAGE</a></li> + <li><a href="#userdef-hdrftr-rv">User-defined, single string recto/verso headers/footers</a> + <ul> + <li><a href="#hdrftr-rectoverso">HEADER_RECTO, HEADER_VERSO</a> + <ul style="margin-left: -.5em;"> + <li><a href="#userdef-hdrftr">User-defined, single string headers/footers (no recto/verso)</a></li> + </ul></li> + <li><a href="#reserved-strings">Using mom’s reserved strings in header/footer definitions</a> + (title, author, etc.) + </li> + </ul></li> + <li><a href="#headers-and-footers-intro">HEADERS_AND_FOOTERS</a> – + putting both headers and footers on document pages + </li> + <li><a href="#headfoot-control">Header and footer control macros</a></li> +</ul> +</div> + +<!-- -HEADERS- --> + +<div class="macro-id-overline"> +<h3 class="macro-id">Headers</h3> +</div> + +<div id="headers" class="box-macro-args"> +Macro: <b>HEADERS</b> <kbd class="macro-args">toggle</kbd> +</div> + +<p> +<a href="definitions.html#header">Page headers</a> +are on by default. If you don’t want them, turn them off by +invoking <kbd>.HEADERS</kbd> with any argument (<b>OFF, QUIT, +END, X...</b>), e.g. +<br/> +<span class="pre-in-pp"> + .HEADERS OFF +</span> +</p> + +<p> +<b>NOTE:</b> HEADERS automatically +disables +<a href="definitions.html#footer">footers</a> +(you can’t have both), but not the page numbers that normally +appear at the bottom of the page. +</p> + +<p> +<b>ADDITIONAL NOTE:</b> If HEADERS +are OFF, mom’s normal top +margin for +<a href="definitions.html#running">running text</a> +(7.5 +<a href="definitions.html#picaspoints">picas</a>) +changes to 6 picas (visually approx. 1 inch). This does NOT apply +to the situation where footers have been explicitly turned on +(with +<kbd><a href="#footers">FOOTERS</a></kbd>). +Explicitly invoking footers moves page numbering to the +top of the page, where its placement and spacing are the same as +for headers. (I.e. the top margin of running text remains 7.5 +picas.) +</p> + +<!-- -FOOTERS- --> + +<div class="macro-id-overline"> +<h3 id="footers" class="macro-id">Footers</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>FOOTERS</b> <kbd class="macro-args">toggle</kbd> +</div> + +<p> +<a href="definitions.html#footer">Page footers</a> +are off by default. If you want them instead of +<a href="definitions.html#header">headers</a> +(you can’t have both), turn them on by invoking +<kbd>.FOOTERS</kbd> without an argument, e.g. +<br/> +<span class="pre-in-pp"> + .FOOTERS +</span> +</p> + +<p> +FOOTERS automatically disables headers, and +mom shifts the placement of page numbers from their +normal position at page bottom to the top of the page. +</p> + +<p> +<b>NOTE:</b> By default, when footers are on, +mom does not print a page number on the first +page of a document, nor on first pages after +<a href="rectoverso.html#collate">COLLATE</a>. +If you don’t want this behaviour, you can change it with +<kbd><a href="#pagenum-on-first-page">PAGENUM_ON_FIRST_PAGE</a></kbd>. +</p> + +<!-- -FOOTER_ON_FIRST_PAGE- --> + +<div class="macro-id-overline"> +<h3 id="footer-on-first-page" class="macro-id">Footer on first page</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>FOOTER_ON_FIRST_PAGE</b> <kbd class="macro-args">toggle</kbd> +</div> + +<p> +If you invoke +<a href="#footers"><kbd>.FOOTERS</kbd></a>, +mom, by default, does not print a footer on the +first page of the document. (The +<a href="definitions.html">docheader</a> +on page 1 makes it redundant.) However, should you wish a footer on +page 1, invoke <kbd>.FOOTER_ON_FIRST_PAGE</kbd> without any argument. +</p> + +<div class="rule-short"><hr/></div> + +<h2 id="headfoot-control" class="macro-group">Control macros for headers/footers</h2> + +<p> +Virtually every part of headers (and footers; see the note on how +<a href="#headerfooter">“headers” means “footers”</a> +in the +<a href="#headfootpage-intro">Introduction</a> +to headers/footers) can be designed to your own specifications. +</p> + +<div class="macro-list-container"> +<h3 id="index-headfoot-control" class="macro-list">Header/footer control macros and defaults</h3> + +<ol style="margin-top: -1.5em; padding-bottom: 6px;"> + <li><a href="#hdrftr-strings">Header/footer strings</a> + <ul style="margin-left: -.5em;"> + <li><a href="#hdrftr-left">HEADER_LEFT</a></li> + <li><a href="#hdrftr-centre">HEADER_CENTER</a> + <ul style="margin-left: -.5em;"> + <li><a href="#hdrftr-centre-pad">Padding the header-centre string</a></li> + </ul></li> + <li><a href="#hdrftr-right">HEADER_RIGHT</a></li> + <li><a href="#reserved-strings">Using mom’s reserved strings in header/footer definitions</a> + (e.g. <kbd>\E*[$TITLE]</kbd> when you want + <br/> + the title, <kbd>\E*[$AUTHOR]</kbd> when you want the author, etc.) + </li> + <li><a href="#page-number-symbol">Replacing header-left, centre or right with the page number</a></li> + <li><a href="#page-number-incl">Including the page number in header-left, centre or right</a></li> + </ul></li> + <li><a href="#hdrftr-style">Header/footer style</a> + <ul style="margin-left: -.5em;"> + <li><a href="#hdrftr-style-global">Global changes</a> + <ul style="margin-left: -.5em;"> + <li><a href="#hdrftr-global-family">HEADER_FAMILY</a> – family for entire header</li> + <li><a href="#hdrftr-global-size">HEADER_SIZE</a> – size for entire header</li> + <li><a href="#hdrftr-plain">HEADER_PLAIN</a> – disable default adjustments to header parts</li> + <li><a href="#hdrftr-color">HEADER_COLOR</a> – colourize the header</li> + </ul></li> + <li><a href="#hdrftr-style-part">Part-by-part changes</a> + <ul style="margin-left: -.5em;"> + <li><a href="#_family">_FAMILY</a> – left, centre or right family</li> + <li><a href="#_font">_FONT</a> – left, centre or right font</li> + <li><a href="#_size">_SIZE</a> – left, centre or right size</li> + <li><a href="#_caps">_CAPS</a> – left, centre or right all caps</li> + <li><a href="#_color">_COLOR</a> – left, centre or right colour</li> + </ul></li> + </ul></li> + <li><a href="#hdrftr-vertical">Header/footer vertical placement and spacing</a> + <ul style="margin-left: -.5em;"> + <li><a href="#hdrftr-margin">HEADER_MARGIN</a></li> + <li><a href="#hdrftr-gap">HEADER_GAP</a></li> + </ul></li> + <li><a href="#hdrftr-separator">Header/footer separator rule</a> + <ul style="margin-left: -.5em;"> + <li><a href="#hdrftr-rule">HEADER_RULE</a></li> + <li><a href="#hdrftr-rule-weight">HEADER_RULE_WEIGHT</a></li> + <li><a href="#hdrftr-rule-gap">HEADER_RULE_GAP</a></li> + <li><a href="#hdrftr-rule-color">HEADER_RULE_COLOR</a></li> + </ul></li> +</ol> +</div> + +<!-- -HDRFTR_STRINGS- --> + +<h4 id="hdrftr-strings" class="docs">1. Header/footer strings</h4> + +<div id="hdrftr-left" class="box-macro-args" style="margin-top: 1em;"> +”Macro: <b>HEADER_LEFT</b> <kbd class="macro-args">“<text of header-left> | #</kbd> +</div> + +<div id="hdrftr-centre" class="box-macro-args" style="margin-top: 1em;"> +”Macro: <b>HEADER_CENTER</b> <kbd class="macro-args">“<text of header-centre> | #</kbd> +</div> + +<div id="hdrftr-right" class="box-macro-args" style="margin-top: 1em;"> +”Macro: <b>HEADER_RIGHT</b> <kbd class="macro-args">“<text of header-right> | #</kbd> +</div> + +<p> +To change the text (the “string”) of the left, centre, +or right part of headers, invoke the appropriate macro, above, +with the string you want. For example, 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: +<br/> +<span class="pre-in-pp"> + .HEADER_LEFT "R. Stallman, E. Raymond" +</span> +</p> + +<p> +Because the arguments to HEADER_LEFT, _CENTER, +and _RIGHT are +<a href="definitions.html#stringargument">string arguments</a>, +they must be enclosed in double-quotes. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +Replace HEADER_, above, with FOOTER_ to change the strings in +footers. +</p> +</div> + +<h3 id="hdrftr-centre-pad" class="docs">Padding the header/footer centre string</h3> + +<div class="box-macro-args" style="margin-top: 1em;"> +Macro: <b>HEADER_CENTER_PAD</b> <kbd class="macro-args">LEFT | RIGHT <amount of space by which to pad centre string left or right></kbd> +</div> + +<p class="requires"> +• Requires a <a href="definitions.html#unitofmeasure">unit of measure</a> +</p> + +<p> +By default, mom centres the header-centre string on the line length +in effect for page headers. +</p> + +<p> +In some cases, notably when the header-left or header-right +strings are particularly long, the effect isn’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. +</p> + +<p> +For example, say your document is an outline for a novel called +<i>By the Shores of Lake Attica</i>. You’ve told mom you want +<br/> +<span class="pre-in-pp"> + .DOCTYPE NAMED "Outline" +</span> +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 +<br/> +<span class="pre-in-pp"> + .HEADER_CENTER_PAD RIGHT 3P +</span> +you can scoot the word "Outline" over three +<a href="definitions.html#picaspoints">picas</a> +<i>to the left</i> (because the padding is added onto the right of the +string) so that your head looks nicely spaced out. Invoking +<kbd>.HEADER_CENTER_PAD</kbd> with the <kbd>LEFT</kbd> argument puts +the padding on the left side of the string so that it scoots +right. +</p> + +<p> +Most reassuring of all is that if you use HEADER_CENTER_PAD +conjunction with +<a href="rectoverso.html#recto-verso">RECTO_VERSO</a>, +mom will pad the centre string appropriately left OR right, +depending on which page you’re on, without you having to tell +her to do so. +</p> + +<h3 id="reserved-strings" class="docs">Using mom’s reserved strings in header/footer definitions</h3> + +<p> +As pointed out in the +<a href="#author-note">Author’s note</a> +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. +</p> + +<p> +However, situations do arise where you need to manipulate what goes +in the header/footer strings, setting and resetting them as you go +along. +</p> + +<p> +A case where you might want to do this would be if you want to +output endnotes at the end of each document in a series of +<a href="rectoverso.html#collate">collated</a> +documents, and you want the word "Endnotes" to go in the header +centre position of the endnotes, but want, say, the +<a href="docprocessing.html#title">TITLE</a> +to go back into the centre position for the next output document. +</p> + +<p> +In scenarios like the above, mom has a number of reserved strings +you can plug into the HEADER_LEFT, _CENTER and _RIGHT macros. They +are: +<br/> +<span class="pre-in-pp"> + \E*[$TITLE] —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 +</span> +Returning to the scenario above, first, you’d define a centre +string for the endnotes page: +<br/> +<span class="pre-in-pp"> + .HEADER_CENTER "Endnotes" +</span> +Then, you’d output the endnotes: +<br/> +<span class="pre-in-pp"> + .ENDNOTES +</span> +Then, you’d prepare mom for the next document: +<br/> +<span class="pre-in-pp"> + .COLLATE + .TITLE "New Doc Title" + .AUTHOR "Josephine Blough" +</span> +Then, you’d redefine the header-centre string using the reserved +string <kbd>\*[$TITLE]</kbd>, like this: +<br/> +<span class="pre-in-pp"> + .HEADER_CENTER "\E*[$TITLE]" +</span> +And last, you’d do: +<br/> +<span class="pre-in-pp"> + .START +</span> +Voilà! Any argument you pass to +<a href="docprocessing.html#title">TITLE</a> +from here on in (say, for subsequent documents) is back in the +header-centre position. Here’s the whole routine again: +<br/> +<span class="pre-in-pp"> + .HEADER_CENTER "Endnotes" + .ENDNOTES + .COLLATE + .TITLE "New Doc Title" + .AUTHOR "Josephine Blough" + .HEADER_CENTER "\E*[$TITLE]" + .START +</span> +</p> + +<p> +If need be, you can concatenate the strings, as in the following +example. +<br/> +<span class="pre-in-pp"> + .HEADER_CENTER "\E*[$CHAPTER_STRING] \E*[$CHAPTER]" +</span> +which, assuming a <kbd>.CHAPTER_STRING</kbd> of +<kbd>"Chapter"</kbd> and a <kbd>.CHAPTER</kbd> of +<kbd>"2"</kbd>, would put “Chapter 2” in the +header-centre position. +</p> + +<h3 id="page-number-symbol" class="docs">Replacing header-left, -centre or -right with the page number</h3> + +<p> +If you would like to have the current page number appear in the +header-left, -centre, or -right position instead of a text string, +invoke the appropriate macro, above, with the single argument +<kbd>#</kbd> (the “number” or “pound” sign). +Do not surround the pound size with double-quotes, as you would +normally do if the argument to <kbd>.HEADER_CENTER</kbd> were a +string. For example, +<br/> +<span class="pre-in-pp"> + .HEADER_CENTER # +</span> +(notice, no double-quotes) will print the current page number in the +centre part of headers. +</p> + +<h3 id="page-number-incl" class="docs">Including the page number in header-left, -CENTER or -right</h3> + +<p> +If you would like to <i>include</i> the current page number in the +string you pass to HEADER_LEFT, _CENTER, or _RIGHT, (as +opposed to replacing the string with the page number), use the +special +<a href="definitions.html#inlines">inline escape</a> +<kbd>\*[PAGE#]</kbd> in the string argument. +</p> + +<p> +For example, say you have a document that’s ten pages long, +and you want header-right to say “page <whichever> of +10”, invoke <kbd>.HEADER_RIGHT</kbd> as follows: +<br/> +<span class="pre-in-pp"> + .HEADER_RIGHT "page \*[PAGE#] of 10" +</span> +The header-right of page two will read “page 2 of 10”, +the header-right of page three will read “page 3 of 10”, +and so on. +</p> + +<!-- -HDRFTR_STYLE- --> + +<h4 id="hdrftr-style" class="docs">2. Header/footer style</h4> + +<h5 id="hdrftr-style-global" class="docs" style="margin-top: 1em;">Global changes</h5> + +<p style="margin-top: .5em;"> +The following macros allow you to make changes that affect all parts +of the header at once. +</p> + +<div class="macro-list-container"> +<ul style="padding-top: 6px; padding-bottom: 6px; margin-left: -.5em;"> + <li><a href="#hdrftr-global-family">HEADER_FAMILY</a></li> + <li><a href="#hdrftr-global-size">HEADER_SIZE</a></li> + <li><a href="#hdrftr-plain">HEADER_PLAIN</a></li> + <li><a href="#hdrftr-color">HEADER_COLOR</a></li> +</ul> +</div> + +<div id="hdrftr-global-family" class="box-macro-args"> +Macro: <b>HEADER_FAMILY</b> <kbd class="macro-args"><family></kbd> +</div> + +<p> +By default, mom uses the default document family for headers. If +you would like her to use another +<a href="definitions.html#family">family</a> +in headers, invoke <kbd>.HEADER_FAMILY</kbd> with the identifier +for the family you want. The argument is the same as for the +typesetting macro +<a href="typesetting.html#family">FAMILY</a>. +</p> + +<p> +Replace HEADER_, above, with FOOTER_ to change the footer family. +</p> + +<div id="hdrftr-global-size" class="box-macro-args"> +Macro: <b>HEADER_SIZE</b> <kbd class="macro-args"><+|-number of points></kbd> +</div> +<p class="requires"> +• Argument is relative to the point size of type in paragraphs. +See +<span style="font-style: normal;"><a href="docelement.html#control-macro-args">Arguments to the control macros</a></span> +for an explanation of how control macros ending in +_SIZE work. +</p> + +<p> +By default, mom makes small adjustments to the size of each part +of a header to achieve an aesthetically pleasing result. If +you’d like her to continue to do so, but would like the +overall appearance of headers to be a little smaller or a little +larger, invoke <kbd>.HEADER_SIZE</kbd> with + or - the number of <a +href="definitions.html#picaspoints">points</a> (fractions allowed) +by which you want her to in/decrease the size of headers. For +example, +<br/> +<span class="pre-in-pp"> + .HEADER_SIZE +.75 +</span> +increases the size of every part of a header by 3/4 of a point while +respecting mom’s own little size changes. +</p> + +<p> +Replace HEADER_, above, with FOOTER_ to change the footer size. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +Normally, macros that control headers have no effect on +<a href="docprocessing.html#printstyle">PRINTSTYLE <kbd>TYPEWRITE</kbd></a>. +HEADER_SIZE is an exception. While all parts of a header in +PRINTSTYLE <kbd>TYPEWRITE</kbd> are always the same size, you +can use HEADER_SIZE with PRINTSTYLE <kbd>TYPEWRITE</kbd> to +reduce the header’s overall point size. You’ll most +likely require this when the +<a href="docprocessing.html#copystyle">COPYSTYLE</a> +is <kbd>DRAFT</kbd>, since portions of the header may overprint if, +say, the title of your document is very long. +</p> +</div> + +<div id="hdrftr-color" class="box-macro-args"> +Macro: <b>HEADER_COLOR</b> <kbd class="macro-args"><colorname></kbd> +</div> + +<p> +If you want your headers in a colour different from the document +default (usually black), invoke <kbd>.HEADER_COLOR</kbd> with the +name of a colour pre-defined (or “initialized”) with +<a href="color.html#newcolor">NEWCOLOR</a> +or +<a href="color.html#xcolor">XCOLOR</a>. +</p> + +<p> +HEADER_COLOR will set all the parts of the header +plus the header rule in the colour you give it as an argument. If +you wish finer control over colour in headers, you can use +<a href="#_color">HEADER_<POSITION>_COLOR</a> +to colourize each part of the header separately, as well as +<a href="#hdrftr-rule-color">HEADER_RULE_COLOR</a> +to change the colour of the header rule. +</p> + +<p> +Replace HEADER_, above, with FOOTER_ to colourize footers. +</p> + +<div class="box-macro-args"> +Macro: <b>HEADER_PLAIN</b> +</div> + +<p> +By default, mom makes adjustments to the font, size, and +capitalization style of each part of headers to achieve an +aesthetically pleasing look. Should you wish to design your own +headers from the ground up without worrying how changes to the +various elements of header style interact with mom’s defaults, +invoke <kbd>.HEADER_PLAIN</kbd> by itself, with no argument. Mom +will disable her default behaviour for headers, and reset all +elements of header style to the same family, font, point size and +colour as she uses in paragraphs. +</p> + +<p> +Replace HEADER_, above, with FOOTER_ to disable mom’s default +behaviour for the various elements of footer style. +</p> + +<h4 id="hdrftr-style-part" class="docs">3. Part by part changes</h4> + +<p> +When using the following control ”macros, replace +“<POSITION> by <b>LEFT, CENTER,</b> or RIGHT as +appropriate. +</p> + +<div class="macro-list-container"> +<ul style="padding-top: 6px; padding-bottom: 6px; margin-left: -.5em;"> + <li><a href="#_family">HEADER_<POSITION>_FAMILY</a></li> + <li><a href="#_font">HEADER_<POSITION>_FONT</a></li> + <li><a href="#_size">HEADER_<POSITION>_SIZE</a></li> + <li><a href="#_caps">HEADER_<POSITION>_CAPS</a></li> + <li><a href="#_color">HEADER_<POSITION>_COLOR</a></li> +</ul> +</div> + +<div id="_family" class="box-macro-args"> +Macro: <b>HEADER_<POSITION>_FAMILY</b> <kbd class="macro-args"><family></kbd> +</div> + +<p> +Use HEADER_<POSITION>_FAMILY to change the +<a href="definitions.html#family">family</a> +of any part of headers. See +<a href="docelement.html#control-macro-args">Arguments to the control macros</a> +for an explanation of how control macros ending in _FAMILY work. +</p> + +<p> +Replace HEADER_, above, with FOOTER_ to change a footer part’s family. +</p> + +<div id="_font" class="box-macro-args"> +Macro: <b>HEADER_<POSITION>_FONT</b> <kbd class="macro-args"><font></kbd> +</div> + +<p> +Use HEADER_<POSITION>_FONT to change the +<a href="definitions.html#font">font</a> +of any part of headers. See +<a href="docelement.html#control-macro-args">Arguments to the control macros</a> +for an explanation of how control macros ending in _FONT work. +</p> + +<p> +Replace HEADER_, above, with FOOTER_ to change a footer part’s font. +</p> + +<div id="_size" class="box-macro-args"> +Macro: <b>HEADER_<POSITION>_SIZE</b> <kbd class="macro-args"><+|-number of points></kbd> +</div> + +<p> +Use HEADER_<POSITION>_SIZE to change the size of any part of +headers (relative to the point size of type in paragraphs). See +<a href="docelement.html#control-macro-args">Arguments to the control macros</a> +for an explanation of how control macros ending in _SIZE work. +</p> + +<p> +Replace HEADER_, above, with FOOTER_ to change a footer part’s size. +</p> + +<div id="_caps" class="box-macro-args"> +Macro: <b>HEADER_<POSITION>_CAPS</b> <kbd class="macro-args">toggle</kbd> +</div> + +<p> +HEADER_<POSITION>_CAPS is a +<a href="definitions.html#toggle">toggle macro</a>. +If you want any part of headers to be set in all caps, regardless of +the capitalization of that part’s string as given to the +<a href="docprocessing.html#reference-macros">reference macros</a> +or as defined by you with the +<a href="#hdrftr-strings">header string control macros</a>, +simply invoke this macro (using the appropriate position) with no +argument. If you wish to turn capitalization off (say, for the +header-right string that mom capitalizes by default), invoke the +macro with any argument (e.g. <kbd>OFF, QUIT, END, X</kbd>...). +</p> + +<p> +Replace HEADER_, above, with FOOTER_ to change a footer part’s +capitalization style. +</p> + +<div id="_color" class="box-macro-args"> +Macro: <b>HEADER_<POSITION>_COLOR</b> <kbd class="macro-args"><colorname></kbd> +</div> + +<p> +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: +<br/> +<span class="pre-in-pp"> + .HEADER_RIGHT_COLOR red +</span> +The other parts of the header will be in the default header colour +(usually black, but that can be changed with +<a href="#hdrftr-color">HEADER_COLOR</a>). +</p> + +<p> +Remember that you have to define (or “initialize”) a +colour with +<a href="color.html#newcolor">NEWCOLOR</a> +or +<a href="color.html#xcolor">XCOLOR</a> +before you can use the colour. +</p> + +<p> +If you create a +<a href="#userdef-hdrftr-rv">user-defined header</a> +with +<a href="#hdrftr-rectoverso">HEADER_RECTO</a> +or +<a href="#hdrftr-rectoverso">HEADER_VERSO</a>, +and you want various elements within the header to be colourized, +embed the colours in the string passed to HEADER_RECTO or +HEADER_VERSO with the +<a href="color.html#color-inline"><kbd>\*[<colorname>]</kbd></a> +<a href="definitions.html#inlines">inline escape</a>. +</p> + +<p> +Replace HEADER_, above, with FOOTER_ to set the colours for the +various elements of footers. +</p> + +<!-- -HDRFTR_VERTICAL- --> + +<h4 id="hdrftr-vertical" class="docs">3. Header/footer vertical placement and spacing</h4> + +<p> +See +<a href="#vertical-spacing">Vertical placement and spacing of headers/footers</a> +for an explanation of how mom deals with +headers, footers, and top/bottom page margins. +</p> + +<div class="macro-list-container"> +<ul style="padding-top: 6px; padding-bottom: 6px; margin-left: -.5em;"> + <li><a href="#hdftr_margin">HEADER_MARGIN</a></li> + <li><a href="#hdftr_gap">HEADER_GAP</a></li> +</ul> +</div> + +<!-- -HDRFTR_MARGIN- --> + +<div id="hdrftr-margin" class="box-macro-args"> +Macro: <b>HEADER_MARGIN</b> <kbd class="macro-args"><distance to baseline of header></kbd> +</div> + +<p class="requires"> +• Requires a <a href="definitions.html#unitofmeasure">unit of measure</a> +</p> + +<p> +Use HEADER_MARGIN to set the distance from the top edge of the page to the +<a href="definitions.html#baseline">baseline</a> +of type in headers. A unit of measure is required, and decimal +fractions are allowed. +</p> + +<p> +Mom’s default header margin is 4-1/2 +<a href="definitions.html#picaspoints">picas</a>, +but if you want a different margin, say, 1/2-inch, do +<br/> +<span class="pre-in-pp"> + .HEADER_MARGIN .5i +</span> +If your document uses +<a href="definitions.html#footer">footers</a>, +replace HEADER_, above, with FOOTER_. The argument to FOOTER_MARGIN +is the distance from the bottom edge of the page to the baseline of +type in footers. Mom’s default footer margin is 3 +<a href="definitions.html#picaspoints">picas</a>. +</p> + +<h3 class="docs">Header/footer margins and page numbering</h3> + +<p> +Mom uses HEADER_MARGIN and FOOTER_MARGIN to establish the baseline +position of page numbers in addition to the baseline position of +headers and footers proper. +</p> + +<p> +By default, page numbers appear at the bottom of the page, therefore +if you want the default position (bottom), but want to change the +baseline placement, use FOOTER_MARGIN. Conversely, if page numbers +are at the top of the page, either because you turned +<a href="#footers">FOOTERS</a> +on or because you instructed mom to put them there with +<a href="#pagenum-pos">PAGENUM_POS</a>, +you’d use HEADER_MARGIN to change their baseline placement. +</p> + +<div id="footer-margin" class="box-important" style="padding-bottom: 15px;"> +<p class="tip-top"> +<span class="important" style="display: block; margin-bottom: -1em;">Important – FOOTER_MARGIN and bottom margins</span> +<br/> +Mom requires a footer margin (i.e. the distance from the bottom of +the page at which to place footers) for proper operation, hence she +sets one, even if you don’t. As stated above, her default +footer margin is 3-picas. +</p> + +<p> +If you use +<a href="typesetting.html#b-margin">B_MARGIN</a> +or +<a href="typesetting.html#page">PAGE</a>, +to set a bottom margin for your document (prior to +<a href="docprocessing.html#start">START</a>) +and the margin’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. +</p> + +<p> +If you see the warning even when footers and/or bottom-of-page page +numbering are disabled, set a nominal footer margin of 0 prior to +<a href="docprocessing.html#start">START</a>, +as in these examples. +</p> + +<div id="examples-footnotes-1" class="examples-container" style="padding-bottom: 1em;"> +<div class="examples" style="margin-top: 0; margin-bottom: -.25em;">Example 1</div> +<span class="pre"> + <reference macros, etc> + .PAGINATION OFF + .B_MARGIN .25i + .FOOTER_MARGIN O + .START +</span> +</div> + +<div id="examples-footnotes-2" class="examples-container" style="margin-top: 1em; padding-bottom: 1em;"> +<div class="examples" style="margin-top: 0;">Example 2</div> +<span class="pre"> + <reference macros, etc> + .HEADERS OFF + .PAGENUM_POS TOP RIGHT + .B_MARGIN .25i + .FOOTER_MARGIN O + .START +</span> +</div> +</div> + +<!-- -HDRFTR_GAP- --> + +<div id="hdrftr-gap" class="box-macro-args"> +Macro: <b>HEADER_GAP</b> <kbd class="macro-args"><distance from header to start of running text></kbd> +</div> + +<p class="requires"> +• Requires a <a href="definitions.html#unitofmeasure">unit of measure</a> +</p> + +<p> +Use HEADER_GAP to set the distance from the +<a href="definitions.html#baseline">baseline</a> +of type in headers to the start of +<a href="definitions.html#running">running text</a>. +A unit of measure is required, and decimal fractions are allowed. +</p> + +<p> +As explained in +<a href="#vertical-spacing">Vertical placement and spacing of headers/footers</a>, +HEADER_MARGIN + HEADER_GAP determine the default vertical starting +position of running text on the page unless you have given mom your +own top margin (with +<a href="typesetting.html#t-margin">T_MARGIN</a>). +If you give a top margin, mom ignores HEADER_GAP; running text +starts at your stated top margin. +</p> + +<p> +Mom’s default header gap is 3 +<a href="definitions.html#picaspoints">picas</a>, +but if you want a different gap, say, 2 centimetres, do +<br/> +<span class="pre-in-pp"> + .HEADER_GAP 2c +</span> +</p> + +<p> +If your document uses +<a href="definitions.html#footer">footers</a>, +replace HEADER_, above, with FOOTER_. The argument to FOOTER_GAP +is the distance from the baseline of type in footers to the last +baseline of running text on the page. +</p> + +<p> +As explained in +<a href="#vertical-spacing">Vertical placement and spacing of headers/footers</a>, +FOOTER_MARGIN + FOOTER_GAP determine the default vertical end +position of running text on the page unless you have given mom a +bottom margin (with +<a href="typesetting.html#b-margin">B_MARGIN</a>). +If you give a bottom margin, mom ignores FOOTER_GAP; running text +ends at your stated bottom margin, subject to the restriction outlined +<a href="#footer-margin">here</a>. +</p> + +<p> +Mom’s default footer gap is 3 +<a href="definitions.html#picaspoints">picas</a>. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +Mom uses HEADER_GAP and FOOTER_GAP to establish the start and end +baseline positions of running text with respect to both headers and +footers AND page numbers. If you wish to change the gap between the +last line of running text and a bottom page number, use FOOTER_GAP. +If page numbers are at the top of the page, change the gap between +the number and the first line of running text with HEADER_GAP. +</p> +</div> + +<!-- -HDRFTR_SEPARATOR- --> + +<h4 id="hdrftr-separator" class="docs">4. Header/footer separator rule</h4> + +<p> +The header/footer separator rule is a modest horizontal rule, +set slightly below the header (or above the footer), that runs +the length of the +<a href="definitions.html#header">header</a> +and helps separate it visually from +<a href="definitions.html#running">running text</a>. If +you don’t want the rule, you can turn it off. If you want it, +but at a different vertical position relative to the header (or +footer), you can alter its placement. +</p> + +<div class="macro-list-container"> +<ul style="padding-top: 6px; padding-bottom: 6px; margin-left: -.5em;"> + <li><a href="#hdrftr-rule">HEADER_RULE</a> – on or off</li> + <li><a href="#hdrftr-rule-weight">HEADER_RULE_WEIGHT</a> – weight of the rule</li> + <li><a href="#hdrftr-rule-gap">HEADER_RULE_GAP</a> – distance of rule from header</li> + <li><a href="#hdrftr-rule-color">HEADER_RULE_COLOR</a> – color of rule header</li> +</ul> +</div> + +<!-- -HDRFTR_RULE- --> + +<div id="hdrftr-rule" class="box-macro-args"> +Macro: <b>HEADER_RULE</b> <kbd class="macro-args">toggle</kbd> +</div> + +<p> +By default, mom prints a header separator rule underneath headers +(or above footers). If you don’t want the rule, turn it off by +invoking <kbd>.HEADER_RULE</kbd> with any argument (<kbd>OFF, QUIT, +END, X...</kbd>), e.g. +<br/> +<span class="pre-in-pp"> + .HEADER_RULE OFF +</span> +To turn the rule (back) on, invoke <kbd>.HEADER_RULE</kbd> +without any argument. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +Replace HEADER_, above, with FOOTER_ to enable/disable the printing +of the footer separator rule. (Most likely, if you’re using +<kbd><a href="#footers">FOOTERS</a></kbd>, +you’ll want it off.) +</p> +</div> + +<!-- -HDRFTR_RULE_WEIGHT- --> + +<div id="hdrftr-rule-weight" class="box-macro-args"> +Macro: <b>HEADER_RULE_WEIGHT</b> <kbd class="macro-args"><weight in points></kbd> +</div> + +<p class="requires"> +• Argument must <span class="normal">NOT</span> have a <a href="definitions.html#unitofmeasure">unit of measure</a> appended +</p> + +<p> +HEADER_RULE_WEIGHT controls the weight (“thickness”) of +the header rule. Like +<a href="inlines.html#rule-weight">RULE_WEIGHT</a>, +it takes a single argument: the weight of the header rule expressed +in +<a href="definitions.html#picaspoints">points</a> +but without the unit of measure, <kbd>p</kbd>, appended. The +argument to HEADER_RULE_WEIGHT must be greater than 0 and less than +100; decimal fractions are allowed. +</p> + +<p> +Say, for example, you want a really strong header separator rule. +<br/> +<span class="pre-in-pp"> + .HEADER_RULE_WEIGHT 4 +</span> +which sets the separator rule weight to 4 points, is how you’d do +it. +</p> + +<p> +Mom’s default header rule weight is 1/2 point. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +Replace HEADER_, above, with FOOTER_ to set the weight of the footer +separator rule. +</p> +</div> + +<!-- -HDRFTR_RULE_GAP- --> + +<div id="hdrftr-rule-gap" class="box-macro-args"> +Macro: <b>HEADER_RULE_GAP</b> <kbd class="macro-args"><distance of rule beneath header></kbd> +</div> + +<p class="requires"> +• Requires a <a href="definitions.html#unitofmeasure">unit of measure</a> +</p> + +<p> +HEADER_RULE_GAP is the distance from the +<a href="definitions.html#baseline">baseline</a> +of type in headers to the top edge of the rule underneath. (If +FOOTER_RULE_GAP, the gap is the distance from the top of the highest +<a href="definitions.html#ascender">ascender</a> +to the bottom edge of the rule.) A unit of measure is required, and +decimal fractions are allowed. Please note that HEADER_RULE_GAP has +no effect on +<a href="#hdrftr-gap">HEADER_GAP</a> +(i.e. HEADER_RULE_GAP is NOT added to HEADER_GAP when mom calculates +the space between headers and the start of +<a href="definitions.html#running">running text</a>). +</p> + +<p> +By default, the header rule gap is 4 +<a href="definitions.html#picaspoints">points</a>. +If you’d like to change it to, say, 1/4 +<a href="definitions.html#em">em</a>, do +<br/> +<span class="pre-in-pp"> + .HEADER_RULE_GAP .25m +</span> +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +Replace HEADER_, above, with FOOTER_ if you’re using +<a href="definitions.html#footer">footers</a> +and want to change the separator rule gap. In footers, the gap is +measured from the top of the tallest +<a href="definitions.html#ascender">ascender</a> +in the footer. +</p> + +<p class="tip-bottom"> +<span class="additional-note">Additional note:</span> +When using +<a href="#hdrftr-recto">FOOTER_RECTO</a> +and +<a href="#hdrftr-verso">FOOTER_VERSO</a>, +make sure that the default size for footers +(<a href="#footer-global-size">FOOTER_SIZE</a>) +is set to the largest size of type that will be used in the footer +or mom may not get the rule gap right. Inline changes to the size +of type in FOOTER_RECTO and FOOTER_VERSO should always be negative +(smaller) than the default. +</p> +</div> + +<!-- -HDRFTR_RULE_COLOR- --> + +<div id="hdrftr-rule-color" class="box-macro-args"> +Macro: <b>HEADER_RULE_COLOR</b> <kbd class="macro-args"><colorname></kbd> +</div> + +<p> +If you wish to change the colour of the header rule, invoke +<kbd>.HEADER_RULE_COLOR</kbd> with the name of a colour pre-defined +(or “initialized”) with +<a href="color.html#newcolor">NEWCOLOR</a> +or +<a href="color.html#xcolor">XCOLOR</a>. +</p> + +<p> +HEADER_RULE_COLOR overrides the colour set with +<a href="#hdrftr-color">HDRFTR_COLOR</a>, +so it’s possible to have the heads entirely in, say, blue (set +with HEADER_COLOR), and the header rule in, say, red. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +Replace HEADER_, above, with FOOTER_ to change the colour of the +footer rule. +</p> +</div> + +<div class="rule-short"><hr/></div> + +<!-- -USERDEF_HDRFTR- --> + +<h2 id="userdef-hdrftr-rv" class="macro-group">User-defined, single string recto/verso headers/footers</h2> + +<p> +Sometimes, you’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. +</p> + +<p> +Say, for example, you want recto page headers to contain a +document’s author, centred, and verso page headers to contain +the document’s title, also centred, like this: +<br/> +<span class="pre-in-pp"> + +------------------------+ +------------------------+ + | Author | | Title | + | | | | + | | | | + | | | | + | | | | + | | | | + | | | | + | | | | + | | | | + | | | | + | | | | + | | | | + | | | | + | | | | + +------------------------+ +------------------------+ +</span> +With mom’s standard 3-part headers, this isn’t possible, +even when +<a href="rectoverso.html#recto-verso">RECTO_VERSO</a> +is enabled. RECTO_VERSO switches the left and right parts of +headers on alternate pages, but the centre part remains unchanged. +</p> + +<p> +Any time you need distinctly different headers on alternate pages, +mom has macros that let you manually design and determine what goes +into headers on recto pages, and what goes into headers on verso +pages. The macros are +<a href="#hdrftr-recto">HEADER_RECTO</a> +and +<a href="#hdrftr-verso">HEADER_VERSO</a>. +Both allow you to state whether the header is flush left, centred, +or flush right, and both take a single +<a href="definitions.html#stringargument">string argument</a> +with which, by combining text and +<a href="definitions.html#inlines">inline escapes</a>, +you can make the headers come out just about any way you want. +Use of the <kbd>\*[PAGE#]</kbd> escape is permitted in the string +argument (see +<a href="#page-number-incl">Including the page number in header-left, -centre or -right</a>), +and, as an added bonus, mom provides a special mechanism whereby +it’s possible to +<a href="#padding-hdrftr">pad</a> +the string as well. The padding mechanism lets you create headers +that contain left, centre and right parts like mom's defaults but +entirely of your own design. +</p> + +<div class="macro-list-container"> +<ul style="padding-top: 6px; padding-bottom: 6px; margin-left: -.5em;"> + <li><a href="#hdrftr-recto">HEADER_RECTO</a></li> + <li><a href="#hdrftr-verso">HEADER_VERSO</a> + <ul style="margin-left: -.5em;"> + <li><a href="#userdef-hdrftr">User-defined single string headers/footers (no recto/verso)</a></li> + <li><a href="#padding-hdrftr">Padding the header-recto/header-verso string</a></li> + </ul></li> +</ul> +</div> + +<!-- -HDRFTR_RECTOVERSO- --> + +<div id="hdrftr-recto" class="box-macro-args"> +Macro: <b>HEADER_RECTO</b> <kbd class="macro-args">LEFT | CENTER | RIGHT [ CAPS ] "<header recto string>"</kbd> +</div> + +<div id="hdrftr-verso" class="box-macro-args" style="margin-top: 1em;"> +Macro: <b>HEADER_VERSO</b> <kbd class="macro-args">LEFT | CENTER | RIGHT [ CAPS ] "<header verso string>"</kbd> +</div> + +<div id="userdef-hdrftr" class="box-tip" style="margin-top: 1.5em; outline: 2px dashed #000089; margin-left: 3px; margin-right: 3px;"> +<p class="tip"> +<span class="tip" style="display: block; margin-bottom: -1.25em; color: #000056; font-size: 105%;">User-defined single string headers/footers (no recto/verso)</span> +<br/> +HEADER_RECTO may be used to create user-defined, single string +headers (or footers, with FOOTER_RECTO), even when recto/verso is +not enabled (with +<a href="rectoverso.html#recto-verso">RECTO_VERSO</a>). +In such cases, the header/footer you create is the one used on +every page, making HEADER_RECTO your “I need to design my own +headers from scratch” solution. +</p> +</div> + +<p> +HEADER_RECTO and HEADER_VERSO behave identically, hence all +references to HEADER_RECTO in this section also refer to +HEADER_VERSO. Furthermore, FOOTER_ can be used instead of HEADER_ +to set up recto/verso footers. +</p> + +<p> +The first argument to HEADER_RECTO is the direction in which you +want the header +<a href="definitions.html#quad">quadded</a>. +<kbd>L, C</kbd> and <kbd>R</kbd> may be used in place of <kbd>LEFT, +CENTER</kbd> and <kbd>RIGHT</kbd>. +</p> + +<p> +The second argument (optional) tells mom to capitalize the text of +the header. <b>Please note:</b> Do not use <kbd><a +href="inlines.html#uc-lc">\*[UC]...\*[LC]</a></kbd> inside the +string passed to HEADER_RECTO. +</p> + +<p> +The final argument is a string, surrounded by double-quotes, +containing what you want in the header. HEADER_RECTO disables +mom’s normal 3-part headers, therefore anything you want in +the headers must be entered by hand in the string, including colours +(via the +<a href="definitions.html#inlines">inline escape</a> +<a href="color.html#color-inline"><kbd>\*[<colorname>]</kbd></a>). +</p> + +<p> +By default, HEADER_RECTO is set at the same size, and in the same +family and font, as paragraph text. The control macros +<a href="#hdrftr-global-family">HEADER_FAMILY</a> +and +<a href="#hdrftr-global-size">HEADER_SIZE</a> +may be used to change the default family and size. Changes to the +font(s) within the string must be accomplished with the +<a href="definitions.html#inlines">inline escapes</a> +<kbd>\*[ROM], \*[IT], \*[BD], \*[BDI]</kbd> and +<kbd>\*[PREV]</kbd> (see +<a href="inlines.html#inline-fonts-mom">Changing fonts</a>). +Additional refinements to the style of the header-recto string, +including horizontal spacing and/or positioning, can also be made +with inline escapes. +</p> + +<p> +To include the current page number in the string, use the +<kbd>\*[PAGE#]</kbd> +<a href="definitions.html#inlines">inline escape</a>. +</p> + +<h3 id="padding-hdrftr" class="docs">Padding the header-recto/header-verso string</h3> + +<p> +You can “pad” the header-recto string, a convenience +you’ll appreciate in circumstances such as the following. +<br/> +<span class="pre-in-pp"> + VERSO RECTO + +------------------------+ +------------------------+ + | Author Page# | | Page# Title | + | | | | + | | | | + | | | | + | | | | + | | | | + | | | | + | | | | + | | | | + | | | | + | | | | + | | | | + | | | | + | | | | + +------------------------+ +------------------------+ +</span> +</p> + +<p> +There are two steps to padding the string argument passed to HEADER_RECTO +(if you’re unsure what padding is, see +<a href="goodies.html#pad">Insert space into lines</a>). +</p> +<ol style="margin-top: -.5em; margin-left: -.5em; margin-bottom: -.5em;"> + <li>Begin and end the string (inside the double-quotes) with the caret character (<kbd>^</kbd>).</li> + <li>Enter the pound sign (<kbd>#</kbd>) at any point in the string where you want an equalized amount of whitespace inserted.</li> +</ol> + +<p> +The situation depicted above is accomplished like this: +<br/> +<span class="pre-in-pp"> + .HEADER_RECTO LEFT "^\*[PAGE#]#\E*[$TITLE]^" + .HEADER_VERSO LEFT "^\E*[$AUTHOR]#\*[PAGE#]^" +</span> +Notice that the quad argument, <kbd>LEFT</kbd>, is used in both +cases. When padding a header, it doesn’t matter which +quad argument you use, although you must be sure to supply +one. Also note that mom does not interpret the <kbd>#</kbd> in +<kbd>\*[PAGE#]</kbd> as a padding marker (i.e. as a place to insert +whitespace). +</p> + +<div class="box-important"> +<p class="tip"> +<span class="important">Important:</span> +The +<a href="goodies.html#pad-marker">PAD_MARKER</a> +macro, which changes the default pad marker (<kbd>#</kbd>) used by +<a href="goodies.html#pad">PAD</a>, +has no effect on the pad marker used in the HEADER_RECTO string. If +you absolutely must have a literal pound sign in your HEADER_RECTO +string, use the escape sequence for the pound sign +( <kbd>\[sh]</kbd> ) where you want the pound sign to go. +</p> +</div> + +<!-- -HDRFTR_RECTOVERSO- --> + +<h2 id="headers-and-footers-intro" class="macro-group">Headers and footers on the same page</h2> + +<p> +Normally, mom prints either a header or a footer, but not both, depending on whether +<a href="docprocessing.html#header">HEADERS</a> +or +<a href="docprocessing.html#footer">FOOTERS</a> +is enabled. (Page numbering, whether in the top margin +or the bottom, is not considered a header or a footer.) +Should you need both headers and footers on the same page, the +single macro, HEADERS_AND_FOOTERS, is the way to set it up. +</p> + +<div id="headers-and-footers" class="box-macro-args"> +Macro: <b>HEADERS_AND_FOOTERS</b> <kbd class="macro-args">(see Invocation)</kbd> +</div> + +<p> +Invocation: +<br/> +<span class="pre-in-pp" style="margin-bottom: -1em;"> + .HEADERS_AND_FOOTERS \ + <L | C | R> "<header-recto string>" \ + <L | C | R> "<footer-recto string>" \ + <L | C | R> "<header-verso string>" \ + <L | C | R> "<header-verso string>" +</span> +or +<span class="pre-in-pp" style="margin-top: -.5em;"> + .HEADERS_AND_FOOTERS <anything> +</span> +</p> + +<p> +Unlike the macros, +<a href="#headers">HEADERS</a> +and +<a href="#footers">FOOTERS</a>, +which are +<a href="definitions.html#toggle">toggle</a> +macros, HEADERS_AND_FOOTERS requires that you supply the information +you want in the headers and footers yourself. Mom does no automatic +generation of things like the title and the author in headers and +footers when you’re using HEADERS_AND_FOOTERS. Furthermore, +style changes—family, font, pointsize, colour, capitalization, +etc —are entirely your responsibility and must be made with +<a href="definitions.html#inlines">inline escapes</a> +in the arguments passed to <kbd>“<recto +”header string>“</kbd>, <kbd><recto footer +string>“</kbd>, etc. By default, mom sets the headers and +footers created with HEADERS_AND_FOOTERS in the same family, font, +point size, capitalization style and colour as +<a href="definitions.html#running">running text</a>. +</p> + +<p> +The manner of entering what you want is identical to the way you +input +<a href="#userdef-hdrftr-rv">single string headers and footers</a>. +I suggest reading up on them, as well as looking at the entries, +<kbd><a href="#hdrftr-rectoverso">HEADER_RECTO</a></kbd> +and +<a href="#reserved-strings">Using mom’s reserved strings in header/footer definitions</a>. +</p> + +<p> +The same +<a href="#padding-hdrftr">padding mechanism</a> +used in HEADER_RECTO and HEADER_VERSO is available in the +<a href="definitions.html#stringargument">string arguments</a> +passed to HEADERS_AND_FOOTERS, allowing you to simulate two- and +three-part headers and footers. +</p> + +<p> +<kbd>L | C | R</kbd> in the arguments to HEADERS_AND_FOOTERS refers +to whether you want the specific header or footer set flush left, +centered, or flush right. (You can also use the longer forms, +<kbd>LEFT</kbd>, <kbd>CENTER</kbd> and <kbd>RIGHT</kbd>.) The +string you give afterwards is whatever text you want, including +mom’s +<a href="#reserved-strings">reserved strings</a>, +and whatever +<a href="definitions.html#inlines">inline escapes</a> +you need to change things like family and font, pointsize, colour, +etc. as you go along. +</p> + +<p> +Note the backslashes in the invocation, above. Every set of +arguments given this way to HEADERS_AND_FOOTERS <i>except the +last</i> requires a backslash after it. The use of backslashes +isn’t required if you want to put the entire argument list on +the same (very long!) line as the macro itself; I recommend sticking +to the style shown above to keep things manageable. +</p> + +<p> +If you want to disable having both headers and footers on the same +page, invoke <kbd>.HEADERS_AND_FOOTERS</kbd> with any argument +you want (e.g. <kbd>OFF, QUIT, END, X...</kbd>). Mom will restore +her default behaviour of setting automatically generated page +headers, with the page number, centered, at the bottom of the +page. If you would prefer footers instead of headers after turning +HEADERS_AND_FOOTERS off, invoke +<a href="#footers"><kbd>.FOOTERS</kbd></a> +afterwards. +</p> + +<h4 class="docs" style="margin-bottom: 1em;">Examples of HEADERS_AND_FOOTERS usage</h4> + +<div id="examples-userdef-hdrftr-1" class="examples-container" style="padding-bottom: 0;"> +<div class="examples" style="margin-top: 12px; margin-bottom: 0;">Example 1: Header and footer the same on every page</div> +<span class="pre"> +.HEADERS_AND_FOOTERS \ +-----------------------+ +C "\E*[$TITLE]" \ | Title | +L "^\E*[$AUTHOR]#\*[PAGE#]^" | | + | | + | | + | | + | | + | | + | | + | | + | | + | | + | | + | | + | Author Pg. # | + +-----------------------+ +</span> + +<p> +<kbd>\E*[$TITLE]</kbd> and <kbd>\E*[$AUTHOR]</kbd> will print the +strings you pass to +<a href="docprocessing.html#title">TITLE</a> +and +<a href="docprocessing.html#author">AUTHOR</a>; +<kbd>\*[PAGE#]</kbd> is how you include the page number in a header +or footer string. (For a list of special strings you can use in +headers and footers, see +<a href="#reserved-strings">here</a>.) +</p> + +<p> +You don’t have to use these special strings. You can type +in anything you like. I’ve only used them here to show that +they’re available. +</p> +</div> + +<div id="examples-userdef-hdrftr-2" class="examples-container" style="margin-top: 1em; padding-bottom: 18px;"> +<div class="examples" style="margin-top: 12px; margin-bottom: 0;">Example 2: Different headers and footers on recto/verso pages</div> +<span class="pre"> +.HEADERS_AND_FOOTERS \ +C "BOOK TITLE" \ +L "^\*[PAGE#]#\E*[$AUTHOR]^" \ +C "Story Title" \ +L "^\E*[$AUTHOR]#\*[PAGE#]^" + + +-----------------------+ +------------------------+ + | BOOK TITLE | | Story Title | + | | | | + | | | | + | | | | + | | | | + | | | | + | | | | + | | | | + | | | | + | | | | + | | | | + | | | | + | | | | + | Pg. # Author | | Author Pg.# | + +-----------------------+ +------------------------+ +</span> +</div> + +<div class="rule-short" style="margin-top: 1.25em;"><hr/></div> + +<!-- ==================================================================== --> + +<h2 id="pagination-intro" class="macro-group">Pagination</h2> + +<p> +By default, mom paginates documents. Page numbers +appear in the bottom margin of the page, centred between two hyphens. +As with all elements of mom’s document processing, +most aspects of pagination style can be altered to suit your taste +with control macros. +</p> + + +<div class="macro-list-container"> +<h3 id="index-pagination" class="macro-list">Pagination macros</h3> +<ul class="macro-list"> + <li><a href="#paginate">PAGINATE</a> – pagination on or off</li> + <li><a href="#pagenumber">PAGENUMBER</a> – user-defined (starting) page number</li> + <li><a href="#pagenum-style">PAGENUM_STYLE</a> – digits, roman numerals, etc</li> + <li><a href="#pagenum-on-first-page">PAGENUM_ON_FIRST_PAGE</a> – applies only when footers are enabled</li> + <li><a href="#draft-with-pagenumber">DRAFT_WITH_PAGENUMBER</a> – attach draft/revision information to page numbers</li> + <li><a href="#paginate-control">Pagination control macros and defaults</a></li> +</ul> +</div> + +<!-- -PAGINATE- --> + +<div id="paginate" class="box-macro-args"> +Macro: <b>PAGINATE</b> <kbd class="macro-args">toggle</kbd> +</div> + +<p class="alias" style="margin-bottom: 0;"> +<i>Alias:</i> <b>PAGINATION</b> +</p> + +<p> +By default, mom paginates documents (in the bottom margin). If +you’d prefer she not paginate, turn pagination off by invoking +<kbd>.PAGINATE</kbd> with any argument (<kbd>OFF, NO, QUIT, END, +X...</kbd>), e.g. +<br/> +<span class="pre-in-pp"> + .PAGINATE NO +</span> +To (re)start pagination, invoke <kbd>.PAGINATE</kbd> without any +argument. +</p> + +<!-- -PAGENUMBER- --> + +<div id="pagenumber" class="box-macro-args"> +Macro: <b>PAGENUMBER</b> <kbd class="macro-args"><number></kbd> +</div> + +<p> +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 <kbd>.PAGENUMBER</kbd> with the +number you want. +</p> + +<p> +PAGENUMBER need not be used only to give mom a "first page" number. +It can be used at any time to tell mom what number you want a page +to have. Subsequent page numbers will, of course, be incremented by +1 from that number. +</p> + +<!-- -PAGENUM_STYLE- --> + +<div id="pagenum-style" class="box-macro-args"> +Macro: <b>PAGENUM_STYLE</b> <kbd class="macro-args">DIGIT | ROMAN | roman | ALPHA | alpha</kbd> +</div> + +<p> +PAGENUM_STYLE lets you tell mom what kind of page numbering you +want. +<br/> +<span class="pre-in-pp"> + DIGIT Arabic digits (1, 2, 3...) + ROMAN upper case roman numerals (I, II, III...) + roman lower case roman numerals (i, ii, iii...) + ALPHA upper case letters (A, B, C...) + alpha lower case letters (a, b, c...) +</span> +</p> + +<!-- -PAGENUM_ON_FIRST_PAGE- --> + +<div id="pagenum-on-first-page" class="box-macro-args"> +Macro: <b>PAGENUM_ON_FIRST_PAGE</b> <kbd class="macro-args">toggle</kbd> +</div> + +<p> +This macro applies only if you’ve enabled +<a href="#footers">FOOTERS</a>. +If FOOTERS are on, mom automatically places page numbers at the tops +of pages except on the first page of a document (or on first pages +after +<a href="rectoverso.html#collate">COLLATE</a>). +If you’d like the page number to appear on “first” pages +when footers are on, invoke +<br/> +<span class="pre-in-pp"> + .PAGENUM_ON_FIRST_PAGE +</span> +with no argument. Any other argument turns the feature off +(<kbd>OFF, QUIT, END, X</kbd>, etc). +</p> + +<p> +As with most of the +<a href="definitions.html#controlmacro">control macros</a>, +PAGENUM_ON_FIRST_PAGE can be invoked at any time, meaning that if +you don’t want a page number on the very first page of a +document, but do want one on pages that appear after COLLATE, omit +it before the first +<a href="docprocessing.html#start">START</a> +of the document, then invoke it either just before or after your +first COLLATE. +</p> + +<!-- -DRAFT_WITH_PAGENUMBER- --> + +<div id="draft-with-pagenumber" class="box-macro-args"> +Macro: <b>DRAFT_WITH_PAGENUMBER</b> +</div> + +<p> +Sometimes, in +<a href="docprocessing.html#copystyle">COPYSTYLE <kbd>DRAFT</kbd></a>, +the CENTER part of page headers gets overcrowded because of +the draft and revision information that go there by default. +DRAFT_WITH_PAGENUMBER is one way to fix the problem. +</p> + +<p> +Invoked without an argument, <kbd>.DRAFT_WITH_PAGENUMBER</kbd> +removes draft/revision information from the page headers and +attaches it instead to the document’s page numbering, in the +form +<br/> +<span class="pre-in-pp"> + Draft #, Rev. # / <pagenumber> +</span> +If you have not supplied mom with a draft number (with +<a href="docprocessing.html#draft">DRAFT</a>) +DRAFT_WITH_PAGENUMBER will assume “Draft 1“, and will +print it before the page number. +</p> + +<p> +See the note in +<a href="docprocessing.html#copystyle-note">COPYSTYLE <kbd>DRAFT</kbd> +</a> +for other ways of dealing with crowded page headers when formatting +draft-style copy. +</p> + +<!-- -PAGINATE_CONTROL- --> + +<div class="macro-list-container"> +<h3 id="index-pagination-control" class="macro-list">Pagination control macros and defaults</h3> + +<ol style="margin-top: -1.5em; padding-bottom: 6px;"> + <li><a href="#paginate-general">Family/font/size/colour</a></li> + <li><a href="#pagenum-pos">Page number position (vertical and horizontal)</a></li> + <li><a href="#pagenum-hyphens">Enclose page numbers with hyphens (on or off)</a></li> +</ol> +</div> + +<h4 id="paginate-general" class="docs">1. Page number family/font/size/colour</h4> + +<div class="defaults-container" style="margin-top: 1em; padding-bottom: 8px;"> +<p class="defaults" style="padding-top: 6px;"> +See +<a href="docelement.html#control-macro-args">Arguments to the control macros</a>. +</p> +<span class="pre defaults"> +.PAGENUM_FAMILY default = prevailing document family; default is Times Roman +.PAGENUM_FONT default = roman +.PAGENUM_SIZE default = 0 (i.e. same size as paragraph text) +.PAGENUM_COLOR default = black +</span> +</div> + +<h4 id="pagenum-pos" class="docs" style="margin-top: -1em;">2. Page number position</h4> + +<div class="box-macro-args" style="margin-top: 1em;"> +Macro: <b>PAGENUM_POS</b> <kbd class="macro-args">TOP | BOTTOM LEFT | CENTER | RIGHT</kbd> +</div> + +<p> +Use PAGENUM_POS to change the default position of automatic page +numbering. PAGENUM_POS requires <i>two</i> arguments: a vertical +position (<kbd>TOP</kbd> or <kbd>BOTTOM</kbd>) and a horizontal +position (<kbd>LEFT</kbd> or <kbd>CENTER</kbd> or <kbd>RIGHT</kbd>). +</p> + +<p> +For example, if you turn both +<a href="definitions.html#header">headers</a> +and +<a href="definitions.html#footer">footers</a> +off (with <kbd>.HEADERS OFF</kbd> and +<kbd>.FOOTERS OFF</kbd>) and you want mom to number your pages +at the top right position, enter +<br/> +<span class="pre-in-pp"> + .PAGENUM_POS TOP RIGHT +</span> +</p> + +<h4 id="pagenum-hyphens" class="docs" style="margin-top: -1em;">3. Enclose page numbers with hyphens (on or off)</h4> + +<div class="box-macro-args" style="margin-top: 1em;"> +Macro: <b>PAGENUM_HYPHENS</b> <kbd class="macro-args">toggle</kbd> +</div> + +<p> +By default, mom encloses page numbers between hyphens. If you +don’t want this behaviour, invoke the macro PAGENUM_HYPHENS +with any argument (<kbd>OFF, QUIT, END, X</kbd>, etc), like this: +<br/> +<span class="pre-in-pp"> + .PAGENUM_HYPHENS OFF +</span> +If, for some reason, you want to turn page number hyphens back +on, invoke the macro without an argument. +</p> + +<!-- -BLANK_PAGE- --> + +<h2 id="blank-pages" class="macro-group">Inserting blank pages into a document</h2> + +<div class="box-macro-args"> +Macro: <b>BLANKPAGE</b> <kbd class="macro-args"><# of blank pages to insert> <NULL></kbd> +</div> + +<p> +This one does exactly what you’d expect—inserts a blank +page into the document. Unless you give the optional argument, +<kbd>NULL</kbd>, mom silently increments the page number of every +blank page and keeps track of +<a href="rectoverso.html#recto-verso">recto/verso</a> +stuff, but otherwise does nothing. It’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, <i>c'est pas +évident</i>. (Somewhere between <i>it isn’t easy, it +isn’t obvious</i> and <i>it isn’t fun</i>). +</p> + +<p> +The required argument to BLANK_PAGE is the number of blank pages to +insert. The argument is not optional, hence even if you only want +one blank page, you have to tell mom: +<br/> +<span class="pre-in-pp"> + .BLANKPAGE 1 +</span> +The optional argument, <kbd>NULL</kbd>, allows you to output the +specified number of pages without mom incrementing the page number +for each blank page. She will, however, continue to keep track +of which pages are recto/verso if recto/verso printing has been +enabled. +</p> + +<div class="rule-long"><hr/></div> + +<!-- Navigation links --> +<table style="width: 100%; margin-top: 12px;"> +<tr> + <td style="width: 33%;"><a href="toc.html">Back to Table of Contents</a></td> + <td style="width: 24%; text-align: center;"><a href="#top">Top</a></td> + <td style="width: 42%; text-align: right;"><a href="rectoverso.html">Next: Recto/verso printing, collating</a></td> +</tr> +</table> + +</div> + +<div class="bottom-spacer"><br/></div> + +</body> +</html> +<!-- vim: fileencoding=utf-8: nomodified: --> 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 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- +This file is part of groff, the GNU roff type-setting system. + +Copyright (C) 2004, 2005, 2006, 2009, 2010 Free Software Foundation, Inc. +Written by Peter Schaffter. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with the +Invariant Sections being this comment section, with no Front-Cover +Texts, and with no Back-Cover Texts. + +A copy of the Free Documentation License is included as a file called +FDL in the main directory of the groff source package. +--> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"> + +<head> + <meta http-equiv="content-type" content="text/html;charset=utf-8"/> + <title>Mom -- Inserting images into mom documents</title> + <link rel="stylesheet" type="text/css" href="stylesheet.css" /> +</head> + +<body style="background-color: #f5faff;"> + +<!-- ==================================================================== --> + +<div id="top" class="page"> + +<!-- Navigation links --> +<table style="width: 100%;"> +<tr> + <td><a href="toc.html">Back to Table of Contents</a></td> + <td style="text-align: right;"><a href="headfootpage.html#top">Next: Page headers/footers, pagination</a></td> +</tr> +</table> + +<h1 class="docs">Inserting images into a document</h1> + +<p> +You can insert images into a document by using the PSPIC +macro. PSPIC isn’t actually part of mom; it comes packaged +with groff itself. Images must be in PostScript format, either +straight .ps or .eps (Encapsulated PostScript). If you have the +ImageMagick suite of programmes installed on your system, a simple way +to convert most image formats to .eps is with <kbd>convert</kbd>, at +the command line, as in this jpg => eps example: +<br/> +<span class="pre-in-pp"> + convert <filename>.jpg <filename>.eps +</span> +There have been reports of trouble with PostScript level 2 images, +so don’t save your images in this format. +</p> + +<!-- -PSPIC- --> + +<div class="macro-id-overline"> +<h3 id="pspic" class= "macro-id">PSPIC</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>PSPIC</b> <kbd class="macro-args">[ -L | -R | -I <n> ] <file> [ width [ height ] ]</kbd> +</div> + +<p> +<kbd>man groff-tmac</kbd> contains the documentation for PSPIC, but +I’ll repeat it here with a few modifications for clarity. +</p> + +<div class="examples-container"> +<h3 id="groff-tmac" class="docs" style="margin-top: .5em;">From groff-tmac</h3> +<p style="margin-top: .5em; margin-bottom: .5em;"> +<kbd><file></kbd> is the name of the file containing the +image; <kbd>width</kbd> and <kbd>height</kbd> give the desired +width and height of the image as you wish it to appear within the +document. The width and height arguments may have +<a href="definitions.html#unitofmeasure">units of measure</a> +attached; the default unit of measure is +<kbd>i</kbd>. PSPIC will scale the graphic +uniformly in the x and y directions so that it is no more than +<kbd>width</kbd> wide and <kbd>height</kbd> high. By default, the +graphic will be horizontally centered. The <kbd>-L</kbd> and +<kbd>-R</kbd> options cause the graphic to be left-aligned and +right-aligned, respectively. The <kbd>-I</kbd> option causes +the graphic to be indented by <kbd><n></kbd>; the default unit of +measure is <kbd>m</kbd> +(<a href="definitions.html#em">ems</a>). +</p> +</div> + +<p> +Unless you’re a PostScript whiz and have futzed around with +bounding boxes and whatnot, it’s unlikely that your image will +occupy an easily predictable and precise amount of space on the +page. This is particularly significant when it comes to the amount +of vertical space occupied by the image. A certain amount of +manual tweaking of the vertical placement of the image will +probably be required, via the +<a href="typesetting.html#ald">ALD</a> +and +<a href="typesetting.html#rld">RLD</a> +macros. +</p> + +<p> +Additionally, images inserted into +<a href="definitions.html#running">running text</a> +will almost certainly disrupt the baseline placement of running +text. In order to get mom back on track after +invoking <kbd>.PSPIC</kbd>, I strongly recommend using the +<a href="docprocessing.html#shim">SHIM</a> +macro so that the bottom margin of running text falls where it +should. +</p> + +<div class="rule-long"><hr/></div> + +<!-- Navigation links --> +<table style="width: 100%; margin-top: 12px;"> +<tr> + <td style="width: 33%;"><a href="toc.html">Back to Table of Contents</a></td> + <td style="width: 20%; text-align: center;"><a href="#top">Top</a></td> + <td style="width: 46%; text-align: right;"><a href="headfootpage.html">Next: Page headers/footers, pagination</a></td> +</tr> +</table> + +</div> + +<div class="bottom-spacer"><br/></div> + +</body> +</html> +<!-- vim: fileencoding=utf-8: nomodified: --> 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 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- +This file is part of groff, the GNU roff type-setting system. + +Copyright (C) 2004, 2005, 2006, 2009, 2010 Free Software Foundation, Inc. +Written by Peter Schaffter. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with the +Invariant Sections being this comment section, with no Front-Cover +Texts, and with no Back-Cover Texts. + +A copy of the Free Documentation License is included as a file called +FDL in the main directory of the groff source package. +--> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"> +<head> + <meta http-equiv="content-type" content="text/html;charset=utf-8"/> + <title>Mom -- Inline escapes</title> + <link rel="stylesheet" type="text/css" href="stylesheet.css" /> +</head> + +<body style="background-color: #f5faff;"> + +<!-- ==================================================================== --> + +<div id="top" class="page"> + +<!-- Navigation links --> +<table style="width: 100%;"> +<tr> + <td><a href="toc.html">Back to Table of Contents</a></td> + <td style="text-align: right;"><a href="color.html#top">Next: Coloured text</a></td> +</tr> +</table> + +<h1 id="inline-escapes" class="docs">Inline escapes</h1> + +<div style="text-align: center;"> +<a href="#index-inlines">List of inline escapes</a> +</div> + +<div class="rule-medium"><hr/></div> + +<h2 id="intro-inlines" class="docs">Introduction</h2> +<p> +Inline escapes, as described in the +<a href="definitions.html#inlines">groff terms</a> +section of this manual, are typesetting commands that appear in text +<a href="definitions.html#inputline">input lines</a>, +as opposed to macros and other +<a href="definitions.html#controllines">control lines</a> +that must appear on lines by themselves. +</p> + +<p> +Aside from altering type parameters within a line, inlines also tell +groff about special characters—em-dashes, bullets, +<a href="definitions.html#figurespace">figure/digit-width spaces</a>, +and so on. It is beyond the scope of this manual to provide +a complete list of groff’s inline functions and special +characters. I recommend having a look at the +<a href="intro.html#canonical">canonical reference materials</a> +should you need more information than is contained herein. +</p> + +<p> +In groff, the escape character is the backslash (<kbd>\</kbd>). +Groff interprets everything following the backslash as instructions, +not literal text, until the escape sequence is complete. Should +you need the actual backslash character as part of a line of text, +simply enter it twice (<kbd>\\</kbd>). Groff understands that this +means "please print a backslash character." +</p> + +<p> +You can also use <kbd>\e</kbd> to print a literal backslash, or use +<a href="goodies.html#esc-char">ESC_CHAR</a> to change the escape +character to something other than the backslash, which lets you +use a single backslash as a literal backslash. +</p> + +<p> +Groff has a number of ways of recognizing what constitutes a +complete escape sequence. This is both a boon and a curse; some +escape sequences have no terminating delimiter and consequently +become difficult to distinguish from real input text. Others +require the use of an opening parenthesis with no corresponding +closing parenthesis. Still others need to be enclosed in square +brackets. +</p> + +<p> +Mom recognizes that certain escapes get used more often than others. +For these, she has a consistent input style that takes the form +<kbd>\*[...]</kbd>, which makes them stand out well from the text of +your documents. These escapes are the ones listed under +<a href="#inlines-mom">Mom’s personal inline escapes</a>. +</p> + +<p> +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 +<a href="intro.html#canonical">canonical reference materials</a> +pertaining to groff. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="tip">Helpful bit of information:</span> +Inline escapes can be used in +<a href="docprocessing.html#docprocessing">document processing macros</a> +that take +<a href="definitions.html#stringargument">string arguments</a>. +</p> +</div> + +<div class="macro-list-container"> +<h3 id="index-inlines" class="macro-list">List of inline escapes</h3> + +<ul class="macro-list"> +<li id="inlines-mom"><a href="#inlines-mom-top">Mom’s personal inline escapes</a> +<ul class="no-enumerator" style="margin-left: -1.5em;"> + <li><a href="#inline-fonts-mom">Changing fonts</a></li> + <li><a href="#inline-size-mom">Changing point size</a></li> + <li><a href="#uc-lc">Capitalise a section of type</a></li> + <li><a href="#inline-kerning-mom">Pairwise kerning</a></li> + <li><a href="#inline-horizontal-mom">Horizontal movement</a></li> + <li><a href="#inline-vertical-mom">Vertical movement</a></li> + <li><a href="#inline-b-mom">Terminate a line without advancing on the page</a></li> + <li><a href="#tb-plus-mom">Call the next sequential tab without advancing on the page</a></li> + <li><a href="#inline-rule-mom">Full measure rules</a> + <ul class="sublist" style="font-size: 100%;"> + <li><a href="#rule-weight">Macro to control the weight of rules</a></li> + </ul></li> +</ul></li> +<li id="inlines-groff"><a href="#inlines-groff-top">Commonly-used groff inline escapes</a> +<ul class="no-enumerator" style="margin-left: -1.5em;"> + <li><kbd>\f</kbd> <a href="#inline-fonts-groff">Font control</a></li> + <li><kbd>\h</kbd> <a href="#inline-horizontal-groff">Inline horizontal motions</a></li> + <li><kbd>\v</kbd> <a href="#inline-vertical-groff">Inline vertical motions</a></li> + <li><kbd>\w</kbd> <a href="#inline-stringwidth-groff">String width function</a></li> + <li><kbd>\l</kbd> <a href="#inline-linedrawing-groff">Horizontal line drawing function</a></li> + <li style="margin-left: 1.6em;"><a href="#inline-characters-groff">Special characters</a></li> +</ul></li> +</ul> +</div> + +<div class="rule-medium"><hr/></div> + +<!-- -INLINE_FONTS_MOM- --> + +<h2 id="inlines-mom-top" class="macro-group">Mom’s personal inline escapes</h2> + +<h3 id="inline-fonts-mom" class="docs">Changing fonts</h3> + +<p> +Mom provides five escapes for changing fonts inline: +<br/> +<span class="pre-in-pp"> + \*[ROM] Change to the medium roman font + \*[IT] Change to the medium italic font + \*[BD] Change to the bold roman font + \*[BDI] Change to the bold italic font + \*[PREV] Revert to the previous font (once only)* +</span> +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +<kbd>\*[PREV]</kbd> does not operate "stack style". It returns +to the previous font once only, and afterwards has no effect. In +other words, in the case of <kbd>\*[PREV]\*[PREV]</kbd>, only the +first <kbd>\*[PREV]</kbd> is respected; the second one is silently +ignored. +</p> +</div> + +<p> +These escapes are provided for merely for convenience, legibility, +and consistency when typesetting with mom. For more complete and +flexible inline font control, please see +<a href="#inline-fonts-groff">font control with <kbd>\f</kbd></a>. +</p> + +<div class="box-notes"> +<h3 id="inlines-docprocessing-fonts" class="docs notes">Notes concerning document processing</h3> +<p style="margin-top: .5em;"> +If you’re using the +<a href="docprocessing.html#docprocessing">document processing macros</a>, +inline font changes remain in effect only for the duration of the +current document element tag. +</p> + +<p class="tip-bottom"> +Additionally, if you’re designing your own +<a href="headfootpage.html#headfootpage-intro">HEADERS or FOOTERS</a> +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 +<a href="headfootpage.html#hdrftr-rectoverso">recto</a> +and/or +<a href="headfootpage.html#hdrftr-rectoverso">verso</a> +HEADERS or FOOTERS, or in the strings passed to +<a href="headfootpage.html#headers-and-footers">HEADERS_AND_FOOTERS</a>, +you must enter the inlines beginning with <kbd>\E*</kbd> +rather than just <kbd>\*</kbd>, e.g. <kbd>\E*[BD]</kbd>. +</p> +</div> + +<!-- -INLINE_SIZE_MOM- --> + +<h3 id="inline-size-mom" class="docs">Changing point size</h3> +<p> +Mom has two inline escapes for changing point size: +<br/> +<span class="pre-in-pp"> + \*[SIZE <size>] +</span> +and +<br/> +<span class="pre-in-pp"> + \*S[<size>] +</span> +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 +<br/> +<span class="pre-in-pp"> + \*[SIZE 12] +</span> +or +<br/> +<span class="pre-in-pp"> + \*S[12] +</span> +</p> + +<p> +The advantage of the first form is that it’s easy to remember, +and follows mom’s usual inline syntax. The advantage of the +second is that it’s more concise. +</p> + +<p> +Notice that in both cases, the new size does not require a +<a href="definitions.html#unitofmeasure">unit of measure</a>; +<a href="definitions.html#picaspoints">points</a> +is assumed. However, a unit of measure may be appended to the size +if that’s what you wish. Fractional sizes are, of course, +allowed. +</p> + +<p> +The size given to <kbd>\*[SIZE <size>]</kbd> or +<kbd>\*S[<size>]</kbd> may be expressed in plus or minus +terms, which can be very useful. In the following examples, the +word “mom” will be output 2 points larger than the point +size of the rest of the line. +<br/> +<span class="pre-in-pp"> + While she isn't perfect, \*S[+2]mom\*S[-2] isn't half bad. + While she isn't perfect, \*[SIZE +2]mom\*[SIZE -2] isn't half bad. +</span> +</p> + +<div class="box-notes"> +<h3 id="inline-docprocessing-ps" class="docs notes">NOTE CONCERNING DOCUMENT PROCESSING</h3> +<p style="margin-top: .5em;"> +If you’re using the +<a href="docprocessing.html#docprocessing">document processing macros</a> +and wish to design your own +<a href="headfootpage.html#headfootpage-intro">HEADERS or FOOTERS</a> +using mom’s inline escape for changing point size as part of +the left, centre and/or right strings, or in the strings for +<a href="headfootpage.html#hdrftr-rectoverso">recto</a> +and/or +<a href="headfootpage.html#hdrftr-rectoverso">verso</a> +HEADERS or FOOTERS, or in the strings passed to +<a href="headfootpage.html#headers-and-footers">HEADERS_AND_FOOTERS</a>, +you <i>must</i> use the form <kbd>\*S[<n>]</kbd> +and enter the inline beginning with <kbd>\E*</kbd>, like this: +<kbd>\E*S[<+|-><n>]</kbd>. +</p> + +<p class="tip-bottom"> +<span class="additional-note">Additional note:</span> +If you’re accustomed to groff’s usual way of handling +inline size requests <kbd>(\sN, \s±N, \s(NN, \s±(NN, \s[NNN], +\s±[NNN]),</kbd> feel free to continue with your old habits. Mom +doesn’t care. +</p> +</div> + +<!-- -CAPITALISATION- --> + +<h3 id="uc-lc" class="docs">Capitalise a section of type</h3> +<p> +If you need to capitalise a region of type inline, bracket the +region of type with the inline escapes, <kbd>\*[UC]</kbd> (Upper Case) +and <kbd>\*[LC]</kbd> (Lower Case), like this: +<br/> +<span class="pre-in-pp"> + All work \*[UC]and\*[LC] no play makes Jack a dull boy. +</span> +The above produces, on output +<br/> +<span class="pre-in-pp"> + All work AND no play makes Jack a dull boy. +</span> +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +<kbd>\*[UC]</kbd> and <kbd>\*[LC]</kbd> must not be used inside the +<a href="definitions.html#stringargument">string arguments</a> +passed to the +<a href="headfootpage.html#hdrftr-strings">HEADER_<POSITION></a> +macro. Instead, use the control macro +<a href="headfootpage.html#_caps">HEADER_<POSITION>_CAPS.</a> +For +<a href="headfootpage.html#hdrftr-rectoverso">HEADER_RECTO</a> +(or _VERSO) or +<a href="headfootpage.html#hdrftr-rectoverso">FOOTER_RECTO</a> +(or _VERSO), supply the <kbd>CAPS</kbd> option to the appropriate +macro. +</p> +</div> + +<!-- -INLINE_KERNING_MOM- --> + +<h3 id="inline-kerning-mom" class="docs">Pairwise kerning</h3> +<p> +Pairwise kerning means moving specific letter pairs closer +together or further apart (see +<a href="definitions.html#kern">Typesetting terms, kerning</a> +for more details). +</p> + +<p> +Mom permits inline pairwise kerning through the use of the inline +escapes +<br/> +<span class="pre-in-pp"> + \*[BU <n>] Closes the space between letters (Back Units). + \*[FU <n>] Opens the space between letters (Forward Units). +</span> +“<b><n></b>” is the number of +<a href="definitions.html#kernunit">kern units</a> +by which to close or open the space between letters. +</p> + +<p> +For example, +<br/> +<span class="pre-in-pp"> + THE HUMAN COST OF COMMODIF\*[FU 1]YING FRESH W\*[BU 4]A\*[BU 5]TER +</span> +moves the letter Y in “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. +</p> + +<p> +For backward compatibility, the forms +<br/> +<span class="pre-in-pp"> + \*[BU1]...\*[BU36] Move backward 1...36 <a href="definitions.html#kernunit">kern units</a> + \*[FU1]...\*[FU36] Move forward 1...36 <a href="definitions.html#kernunit">kern units</a> +</span> +also exist (i.e. with no space before the number of kern units desired, +up to a limit of 36). +</p> + +<div class="box-notes"> +<h3 id="inlines-docprocessing-kerning" class="docs notes">Notes concerning document processing</h3> +<p style="margin-top: .5em;"> +If you’re using the +<a href="docprocessing.html#docprocessing">document processing macros</a> +and wish to design your own +<a href="headfootpage.html#headfootpage-intro">HEADERS or FOOTERS</a> +using mom’s inline escapes for kerning as part of the left, +centre and/or right strings, or in the strings for +<a href="headfootpage.html#hdrftr-rectoverso">recto</a> +and/or +<a href="headfootpage.html#hdrftr-rectoverso">verso</a> +HEADERS or FOOTERS, or in the strings passed to +<a href="headfootpage.html#headers-and-footers">HEADERS_AND_FOOTERS</a>, +you <i>must</i> use the forms <kbd>\E*[BU<n>]</kbd> +and <kbd>\E*[FU<n>]</kbd> (i.e. with no space), and enter the +inline beginning with <kbd>\E*</kbd> rather than just <kbd>\*</kbd>, +e.g. <kbd>\E*[BU4]</kbd>. +</p> + +<p class="tip-bottom"> +<span class="additional-note">Additional note:</span> +Using the <kbd>BU</kbd> or <kbd>FU</kbd> escapes between characters +pairs that are already automatically kerned (see +<a href="typesetting.html#kern">KERN</a>) +disables the automatic +kerning and uses the value you give to BU or FU instead. +</p> +</div> + +<!-- -INLINE_HORIZONTAL_MOM- --> + +<h3 id="inline-horizontal-mom" class="docs">Horizontal inline movement</h3> +<p> +Sometimes, you may need to insert a specified amount amount of white +space into an +<a href="definitions.html#outputline">output line</a>, +or—occasionally—back up to a previous position on an +<a href="definitions.html#inputline">output</a> +line in order to create special typographic effects. +</p> + +<p> +Mom’s inline escapes for these horizontal movements are +<br/> +<span id="bck" class="pre-in-pp"> + \*[BCK <n unit>] Move backward inline the specified number of + <a href="definitions.html#unitofmeasure">units of measure</a>; decimal fractions are allowed. +</span> +and +<span id="fwd" class="pre-in-pp"> + \*[FWD <n unit>] Move forward inline the specified number of + <a href="definitions.html#unitofmeasure">units of measure</a>; decimal fractions are allowed. +</span> +</p> + +<p> +For example, +<br/> +<span class="pre-in-pp"> + 1.\*[FWD 12p]The Free Trade Play-Offs: WalMart 100, Mexico 0 +</span> +puts 12 points of space between <kbd>1.</kbd> and +<kbd>The</kbd>. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +For backward compatibility, the forms +<br/> +<span class="pre-in-pp"> + \*[BP.25]...\*[BP12.75] Move backward .25...12.75 points + \*[FP.25]...\*[FP12.75] Move forward .25...12.75 points +</span> +also exist (i.e. with no space before the digit and points being +the unit of measure, hence no unit of measure required). Both +accept quarter points, so it’s possible to do, for example, +<kbd>\*[FP.5]</kbd> or <kbd>\*[BP1.25]</kbd> up to a limit +of 12.75 points. +</p> +</div> + +<div class="box-notes"> +<h3 id="inlines-docprocessing-horizontal" class="docs notes">Note concerning document processing</h3> +<p style="margin-top: .5em; padding-bottom: .5em;"> +If you’re using the +<a href="docprocessing.html#docprocessing">document processing macros</a> +and wish to design your own +<a href="headfootpage.html#headfootpage-intro">HEADERS or FOOTERS</a> +using mom’s inline escapes for horizontal movements as part of +the left, centre and/or right strings, or in the strings for +<a href="headfootpage.html#hdrftr-rectoverso">recto</a> +and/or +<a href="headfootpage.html#hdrftr-rectoverso">verso</a> +HEADERS or FOOTERS, or in the strings passed to +<a href="headfootpage.html#headers-and-footers">HEADERS_AND_FOOTERS</a>, +you <i>must</i> use the forms <kbd>\E*[BP<n>]</kbd> +and <kbd>\E*[FP<n>]</kbd> (i.e. with no space), and enter the +inline beginning with <kbd>\E*</kbd> rather than just <kbd>\*</kbd>, +e.g. <kbd>\E*[BP.755]</kbd>. +</p> +</div> + +<!-- -INLINE_VERTICAL_MOM- --> + +<h3 id="inline-vertical-mom" class="docs">Vertical inline movement</h3> +<p> +If you need to move portions of type up or down on a line, mom +provides the following inline escapes: +<br/> +<span id="down" class="pre-in-pp"> + \*[DOWN <n unit>] Move down inline the specified number of + <a href="definitions.html#unitofmeasure">units of measure</a> + + <span id="up">\*[UP <n unit>] Move up inline the specified number of + <a href="definitions.html#unitofmeasure">units of measure</a></span> +</span> +For example, +<br/> +<span class="pre-in-pp"> + Tel: 905\*[UP 1p]-\*[DOWN 1p]4072 +</span> +moves the hyphen in the telephone number up by 1 point, then +moves back down by the same amount. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +<kbd>\*[UP]</kbd> and <kbd>\*[DOWN]</kbd> do not work in conjunction +with the inline escape, +<kbd><a href="#inline-rule-mom">\*[RULE]</a></kbd>. +</p> + +<p> +<span class="additional-note">Additional note:</span> +For backward compatibility, the following are also available: +<br/> +<span class="pre-in-pp"> + \*[ALD.25]...\*[ALD12.75] Advance lead .25...12.75 points (move downward) + \*[RLD.25]...\*[RLD12.75] Reverse lead .25...12.75 points (move upward) +</span> +</p> + +<p class="tip-bottom"> +Both <kbd>\*[ALD]</kbd> and <kbd>\*[RLD]</kbd> work in points, hence +you mustn’t use a unit of measure. +</p> +</div> + +<div class="box-notes"> +<h3 id="inline-docprocessing-vertical" class="docs notes">Note concerning document processing</h3> +<p style="margin-top: .5em; padding-bottom: .5em;"> +If you’re using the +<a href="docprocessing.html#docprocessing">document processing macros</a> +and wish to design your own +<a href="headfootpage.html#headfootpage-intro">HEADERS or FOOTERS</a> +using mom’s inline escapes for vertical movements as part of +the left, centre and/or right strings, or in the strings for +<a href="headfootpage.html#hdrftr-rectoverso">recto</a> +and/or +<a href="headfootpage.html#hdrftr-rectoverso">verso</a> +HEADERS or FOOTERS, or in the strings passed to +<a href="headfootpage.html#headers-and-footers">HEADERS_AND_FOOTERS</a>, +you <i>must</i> use the forms <kbd>\E*[ALD<n>]</kbd> +and <kbd>\E*[RLD<n>]</kbd> (i.e. with no space), and enter the +inline beginning with <kbd>\E*</kbd> rather than just <kbd>\*</kbd>, +e.g. <kbd>\E*[ALD.5]</kbd>. +</p> +</div> + +<!-- -INLINE_B_MOM- --> + +<h3 id="inline-b-mom" class="docs">Terminate a line without advancing on the page</h3> +<p> +Sometimes, you want mom to break a line but not advance on the page. +See +<a href="typesetting.html#el-example">here</a> +for an example of when you might want to do this. +</p> + +<p> +In versions of mom prior to 1.2-f, this was accomplished through the +use of the +<a href="typesetting.html#el">EL</a> +macro. As of 1.2-f, you can, if you prefer, accomplish the same +thing by using the inline escape, <kbd>\*[B]</kbd>. Simply attach +the escape to the end of any input line. Using the example given in +the document entry for EL, you'd use <kbd>\*[B]</kbd> like this: +<br/> +<span class="pre-in-pp"> + .LEFT + .LS 12.5 + A line of text.\*[B] + .ALD 24p + The next line of text. +</span> + +<kbd>\*[B]</kbd> works reliably regardless of the current +<a href="definitions.html#filled">fill mode</a>. +</p> + +<!-- -INLINE_TB+_MOM- --> + +<h3 id="tb-plus-mom" class="docs">Call the next sequential tab without advancing on the page</h3> +<p> +Sometimes, you want mom to move to the next tab in sequence (e.g. +from TAB 1 to TAB 2, or TAB 8 to TAB 9) without mom advancing on the +page. (See the NOTE +<a href="typesetting.html#note-tn">here</a> +if you’re not clear how mom manages tabs and linebreaks.) +</p> + +<p> +In versions of mom prior to 1.2-f, this was accomplished through the +use of +<a href="typesetting.html#tn">TN</a>. +As of 1.2-f, you can, if you prefer, accomplish the same thing by +using the inline escape, <kbd>\*[TB+]</kbd>. Simply attach the +escape to the end of any input line in a tab, like this: +<br/> +<span class="pre-in-pp"> + .TAB 1 + Some text\*[TB+] \" This line is in tab 1 + Some more text \" This line is in tab 2, on the same baseline as tab 1 +</span> + +<kbd>\*[TB+]</kbd> works reliably regardless of the current +<a href="definitions.html#filled">fill mode</a>. +</p> + +<!-- -INLINE_RULE_MOM- --> + +<h3 id="inline-rule-mom" class="docs">Full measure rules</h3> +<p> +I find I often need rules drawn to the full measure of the current line +or tab length. The official way to do this is <kbd>\l'\n[.lu]'</kbd>, +which is annoying to type, and doesn’t mean a whole heck of a lot if +you’re new to groff. The inline, <kbd>\*[RULE]</kbd>, is a simple +replacement for <kbd>\l'\n[.lu]'</kbd>. Use it whenever you need +a rule drawn to the full measure of the current line or tab length, for +example: +<br/> +<span class="pre-in-pp"> + .LL 6P + \*[RULE] +</span> + +The above draws a rule the full measure of the 6-pica line length. +For another way to draw full measure rules, see the macro, +<a href="graphical.html#drh">DRH</a>. +</p> + +<p> +<kbd>\*[RULE]</kbd> must appear on an +<a href="definitions.html#inputline">input line</a> +by itself, and always causes a break when entered after a normal +input line of text. It does not, however, deposit a break when used +immediately after a macro. +</p> + +<p> +The weight of the rule drawn with <kbd>\*[RULE]</kbd> is controlled +with the macro +<a href="#rule-weight">RULE_WEIGHT</a>. +Mom’s default is 1/2 point. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +<kbd>\*[RULE]</kbd> draws the rule to the full measure, hence it +cannot be used to fill the remainder of a partial line with a rule +in this way: +<br/> +<span class="pre-in-pp"> + Signature__________________________________________ +</span> +If you wish to accomplish this effect, you have to use +<kbd>\*[RULE]</kbd> in conjunction with the +<a href="goodies.html#pad">PAD</a> +macro and +<a href="typesetting.html#string-tabs">string tabs</a>. +(See the +<a href="goodies.html#pad-example">example</a> +provided with PAD.) +<a name="RULE_EXCEPTION"></a> +</p> + +<p> +Please also note that the inline escapes +<a href="#up"><kbd>\*[UP]</kbd></a> +and +<a href="#down"><kbd>\*[DOWN]</kbd></a> +cannot be used in conjunction with <kbd>\*[RULE]</kbd>. +</p> + +<p>This <i>doesn’t</i> work: +<br/> +<span class="pre-in-pp"> + \*[DOWN 2p]\*[RULE]\*[UP 2p] +</span> +whereas this does: +<br/> +<span class="pre-in-pp"> + .ALD 2p + \*[RULE] + .RLD 2p +</span> +</p> + +<p class="tip-bottom"> +See groff’s +<a href="#inline-linedrawing-groff">Horizontal line drawing function</a> +for more information on drawing horizontal rules. +</p> +</div> + +<!-- -RULE_WEIGHT- --> + +<div id="rule-weight" class="box-macro-args"> +Macro: <b>RULE_WEIGHT</b> <kbd><weight in points></kbd> +</div> + +<p class="requires"> +• Must <span class="normal">not</span> have a +<a href="definitions.html#unitofmeasure">unit of measure</a> +appended. +<br/> + Argument must be greater than 0 and less than 100; decimal +fractions are allowed. +</p> + +<p> +RULE_WEIGHT allows you to tell mom how heavy (in other words, how +“thick”) you want the rules drawn with the inline +escape, +<a href="#inline-rule-mom"><kbd>\*[RULE]</kbd></a>. +It takes a single argument: the weight of the rule in +<a href="definitions.html#picaspoints">points</a> +<i>but without the</i> +<a href="definitions.html#unitofmeasure">unit of measure</a> +<kbd>p</kbd> <i>attached</i>. Thus, to set the weight of rules +drawn with <kbd>\*[RULE]</kbd> to 1-1/4 points, you'd do +<br/> +<span class="pre-in-pp"> + .RULE_WEIGHT 1.25 +</span> +</p> + +<p> +RULE_WEIGHT also sets the weight of rules drawn +with +<a href="graphical.html#drh"><kbd>.DRH</kbd></a> +when DRH is not given any arguments. +</p> + +<div class="rule-medium"><hr/></div> + +<!-- -INLINE_FONT_GROFF- --> + +<h2 id="inlines-groff-top" class="macro-group">Commonly-used groff inline escapes</h2> + +<h3 id="inline-fonts-groff" class="docs">Font control (<kbd style="text-transform: none">\f</kbd>)</h3> + +<p> +Groff’s basic mechanism for inline font control is the escape +<kbd>\f[<font>]</kbd>. +<br/> +<span class="pre-in-pp"> + \f[R] Change to the medium roman font (equivalent to mom's \*[ROM]) + \f[I] Change to the medium italic font (equivalent to mom's \*[IT]) + \f[B] Change to the bold roman font (equivalent to mom's \*[BD]) + \f[BI] Change to the bold italic font (equivalent to mom's \*[BDI]) + \f[P] Revert to the previous font (equivalent to mom's \*[PREV]) +</span> +</p> + +<p> +<kbd>\f[<font>]</kbd> can be used with any valid +<a href="definitions.html#font">font style</a> +registered with groff. (See +<a href="appendices.html#style-extensions">here</a> +for a list of pre-registered font styles provided by mom). +</p> + +<p> +<kbd>\f[<font>]</kbd> can also take a complete valid +family+font name combo. This is especially useful should you +need to change both family and font inline. For example, if your +prevailing family and font are Times Roman and you want a few words +in Courier Bold Italic, you could do this: +<br/> +<span class="pre-in-pp"> + .FAM T + .FT R + The command \f[CBI]ls -l\f[P] gives a "long" directory listing. +</span> +The Unix command <kbd>ls -l</kbd> will appear in Courier Bold Italic +in a line that is otherwise in Times Roman. +</p> + +<!-- -INLINE_HORIZONTAL_GROFF- --> + +<h3 id="inline-horizontal-groff" class="docs">Inline horizontal motions (<kbd style="text-transform: none;">\h</kbd>)</h3> + +<p> +Whenever you need to move forward or backward on a line, use the +inline +<br/> +<span class="pre-in-pp"> + \h'<distance>' +</span> +In order to avoid unpleasant surprises, always append a +<a href="definitions.html#unitofmeasure">unit of measure</a> +to <kbd><distance></kbd>. For example, +<br/> +<span class="pre-in-pp"> + \h'1.25i' +</span> +moves you 1.25 inches to the right (forward) of the horizontal +position on the current +<a href="definitions.html#outputline">output line</a>. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +<kbd>\h'<distance>'</kbd> is exactly equivalent to +<a href="#fwd"><kbd>\*[FWD n<unit>]</kbd></a>. +</p> +</div> + +<p> +To move backwards by the same amount, do +<br/> +<span class="pre-in-pp"> + \h'-1.25i' +</span> +</p> + +<div class="box-tip"> +<p class="tip" style="margin-top: -1em;"> +<span class="note">Note:</span> +<kbd>\h'-<distance>'</kbd> is exactly equivalent to +<a href="#bck"><kbd>\*[BCK n<unit>]</kbd></a>. +</p> +</div> + +<!-- -INLINE_VERTICAL_GROFF- --> + +<h3 id="inline-vertical-groff" class="docs">Inline vertical motions (<kbd style="text-transform: none;">\v</kbd>)</h3> + +<p> +If you need to raise or lower type on a line (say, for sub- or +superscripts, or any other special effect), use +<br/> +<span class="pre-in-pp"> + \v'<distance>' +</span> +In order to avoid unpleasant surprises, always append a +<a href="definitions.html#unitofmeasure">unit of measure</a> +to <kbd><distance></kbd>. For example, +<br/> +<span class="pre-in-pp"> + \v'.6m' +</span> +moves you (approx.) 2/3 of an +<a href="definitions.html#em">em</a> +downward on the current +<a href="definitions.html#outputline">output line</a>. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +<kbd>\v'<distance>'</kbd> is exactly equivalent to +<a href="#down"><kbd>\*[DOWN n<unit>]</kbd></a>. +</p> +</div> + +<p style="margin-top: -.5em;"> +To move upward an equivalent amount, do +<br/> +<span class="pre-in-pp"> + \v'-.6m' +</span> +</p> + +<div class="box-tip" style="margin-top: -1em;"> +<p class="tip"> +<span class="note">Note:</span> +<kbd>\v'<-distance>'</kbd> is exactly equivalent to +<a href="#up"><kbd>\*[UP n<unit>]</kbd></a>. +</p> +</div> + +<div class="box-important"> +<p class="tip"> +<span class="important">Important:</span> +The vertical motion of <kbd>\v</kbd> affects ONLY type on the +current +<a href="definitions.html#outputline">output line</a>. +When groff breaks the output line, the effect of +<kbd>\v</kbd> is cancelled; the baseline of the next output line +is where it would be if you hadn’t used <kbd>\v</kbd>. +</p> +</div> + +<div class="box-tip"> +<p class="tip"> +<span class="tip">Tip:</span> +When using <kbd>\v</kbd> for occasional effects in a line, +don’t forget to reverse it when you've done what you want to +do. Otherwise, the remaining type will be set too high (if you +used <kbd>\v</kbd> with the minus sign) or too low (if you used +<kbd>\v</kbd> without the minus sign). +</p> +</div> + +<!-- -INLINE_STRINGWIDTH_GROFF- --> + +<h3 id="inline-stringwidth-groff" class="docs">String width function (<kbd style="text-transform: none;">\w</kbd>)</h3> + +<p> +In the context of mom, the string width inline +<kbd>\w'<string>'</kbd> primarily serves to let you establish the +horizontal measure of something (e.g. indents) based on the length +of a bit of text. For example, if you want a left indent the length +of the word “Examples:” plus a space, you can set it with +the <kbd>\w</kbd> inline escape: +<br/> +<span class="pre-in-pp"> + .IL "\w'Examples: '" +</span> +</p> + +<div class="box-tip" style="margin-top: -1em;"> +<p class="tip"> +<span class="note">Note:</span> +Whenever you pass <kbd>\w'string'</kbd> +to a macro that normally requires a +<a href="definitions.html#unitofmeasure">unit of measure</a>, +<i>do NOT add a unit of measure to the</i> +<kbd>\w'string'</kbd> <i>argument.</i> +</p> + +<p class="tip-bottom"> +Furthermore, if the string is composed of several words separated +by spaces, you MUST surround the whole escape with double quotes, +as in the example above. +</p> +</div> + +<!-- -INLINE_LINEDRAWING_GROFF- --> + +<h3 id="inline-linedrawing-groff" class="docs">Horizontal line drawing function (<kbd style="text-transform: none;">\l</kbd>)</h3> + +<p> +The <kbd>\l'distance'</kbd> inline allows you to draw a horizontal +rule of the specified distance. You must supply a +<a href="definitions.html#unitofmeasure">unit of measure</a>. +Therefore, to set a 3-pica rule into a line of text, you'd do +<br/> +<span class="pre-in-pp"> + A line of text with a superfluous \l'3P' 3-pica rule in it. +</span> +<kbd>\l'3P'</kbd>, above, not only draws the rule, but advances 3 +picas horizontally as well, just as you'd expect. +</p> + +<p> +For an easy way of drawing rules to the full measure of the current +line or tab length, see +<a href="#inline-rule-mom">Full measure rules</a>. +</p> + +<p> +The weight (thickness) of rules varies according to the point +size in effect when you invoke <kbd>\l</kbd>, but you can’t fix +the weight with any real precision. A point size of 12 produces +a tastefully moderate rule weight of between one-half and one +point (depending on your printer). +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +Besides <kbd>\l</kbd>, <b>groff</b> provides a number of more +sophisticated “drawing” escapes. It is well beyond +the scope of this documentation to demonstrate their usage; see +<br/> +<span class="pre-in-pp"> + info groff => Escape index => \D +</span> +for directions concerning their use. The drawing escapes can be a +bit unwieldy, so mom provides “user-friendly” macros for +the +<a href="graphical.html#top">graphical objects</a> +most commonly enountered in typesetting: horizontal and vertical +rules, boxes, and circles (ellipses). +</p> + +<p class="tip-bottom"> +Additionally, groff comes with two “preprocessors” that +let you create ruled tables and vector diagrams (line drawings): +<b>tbl</b> and <b>pic</b>. The documentation for <b>tbl</b> can be +downloaded from +<br/> + <a style="display: inline-block; margin-left: 2em; margin-top: .5em; margin-bottom: .5em" href="http://cm.bell-labs.com/cm/cs/doc/76/tbl.ps.gz">http://cm.bell-labs.com/cm/cs/doc/76/tbl.ps.gz</a> +<br/> +and <b>pic</b> from +<br/> + <a style="display: inline-block; margin-left: 2em; margin-top: .5em; margin-bottom: .5em" href="http://www.kohala.com/start/troff/gpic.raymond.ps">http://www.kohala.com/start/troff/gpic.raymond.ps</a> +<br/> +Both are powerful tools, but they can be nasty to learn—at +first, anyway. You may prefer to use a vector drawing program +to create diagrams and tables; inserting the results into a +document is easy enough with <kbd>.PSPIC</kbd> (consult +<kbd>man groff-tmac</kbd> for information on this indispensable and +easy-to-use macro). +</p> +</div> + +<!-- -INLINE_CHARACTERS_GROFF- --> + +<h3 id="inline-characters-groff" class="docs">Special characters and symbols</h3> +<p> +Here follows a short list of commonly-used special characters +available via inline escapes. If you’re not sure of the +meaning of some of these characters, consult the +<a href="definitions.html#top">Definitions of Terms</a>. +</p> + +<p> +For a complete list of special characters and glyphs (i.e. just +about anything you'd ever want to appear on the printed page, +including mathematical symbols, accented characters, unusual +ligatures and letters unique to various European languages), consult +<kbd>man groff-char</kbd>. +</p> + +<span class="pre"> + CHARACTER ESCAPE SEQUENCE + --------- --------------- + Comment line \# or .\" + Fixed-width space \<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 +</span> +<br/> + +<div class="rule-long"><hr/></div> + +<!-- Navigation links --> +<table style="width: 100%; margin-top: 12px;"> +<tr> + <td style="width: 33%;"><a href="toc.html">Back to Table of Contents</a></td> + <td style="width: 33%; text-align: center;"><a href="#top">Top</a></td> + <td style="width: 33%; text-align: right;"><a href="color.html#top">Next: Coloured text</a></td> +</tr> +</table> + +</div> + +<div class="bottom-spacer"><br/></div> + +</body> +</html> +<!-- vim: fileencoding=utf-8: nomodified: --> 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 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- +This file is part of groff, the GNU roff type-setting system. + +Copyright (C) 2004, 2005, 2006, 2009, 2010 Free Software Foundation, Inc. +Written by Peter Schaffter. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with the +Invariant Sections being this comment section, with no Front-Cover +Texts, and with no Back-Cover Texts. + +A copy of the Free Documentation License is included as a file called +FDL in the main directory of the groff source package. +--> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"> + +<head> + <meta http-equiv="content-type" content="text/html;charset=utf-8"/> + <title>What is mom?</title> + <link rel="stylesheet" type="text/css" href="stylesheet.css" /> +</head> + +<body style="background-color: #f5faff;"> + +<!-- ==================================================================== --> + +<div id="top" class="page"> + +<!-- Navigation links --> +<table style="width: 100%;"> + <tr> + <td><a href="toc.html">Back to Table of Contents</a></td> + <td style="text-align: right;"><a href="definitions.html#top">Next: Definitions</a></td> + </tr> + </table> + +<h1 id="intro" class="docs">What is mom?</h1> + +<div style="text-align: center;"> +<ul class="no-enumerator" style="margin-left: -2.5em;"> + <li ><a href="#intro-intro">Who is mom meant for?</a></li> + <li ><a href="#intro-typesetting">Typesetting with mom</a></li> + <li ><a href="#intro-docprocessing">Document processing with mom</a></li> + <li ><a href="#intro-philosophy">Mom’s philosophy</a></li> + <li ><a href="#intro-documentation">A note on mom’s documentation</a></li> + <li ><a href="#canonical">Canonical reference materials</a></li> + <li ><a href="#macro-args">How to read macro arguments</a></li> +</ul> +</div> + +<div class="rule-short" style="margin-top: 18px;"><hr/></div> + +<h2 id="intro-intro" class="docs">Who is mom meant for?</h2> + +<p> +Mom (“my own macros”, “my other macros”, +“maximum overdrive macros”...) is a macro set for +groff, designed to format documents for PostScript output. +She’s aimed at three kinds of users: +</p> + +<ol style="margin-top: -.5em; margin-bottom: -.5em;"> + <li>Typesetters who suspect groff might be “the right + tool for the job” but who are + frustrated/intimidated by groff’s terse, geeky, + not-always-typographically-intuitive + <a href="definitions.html#primitives">primitives</a>; + </li> + <li>Non-scientific writers (novelists, short story writers, + journalists, students) who just want their work to + look good; + </li> + <li>Newbies to computer typesetting, document processing or + groff who need a well-documented macro set to help them get + started. + </li> +</ol> + +<p> +As might be inferred from the above, mom is two macro packages in +one: a set of typesetting macros, and a set of document formatting +macros. The typesetting macros govern the physical aspects +of page layout and provide sane, comprehensible control over +typographic refinements. The document formatting macros let you +focus on a document’s content and logical structure without +worrying about typesetting or page layout at all. +</p> + +<p> +Because mom provides both typesetting and document formatting +macros, it’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 +<a href="definitions.html#primitives">primitives</a> +in order to accomplish what you want; the typesetting macros take +care of that. +</p> + +<h2 id="intro-typesetting" class="docs">Typesetting with mom</h2> + +<p> +Mom’s typesetting macros control the basic parameters +of type: margins, line length, type family, font, point size, +linespacing, and so on. In addition, they allow you to move +around on the page horizontally and vertically, and to set up +tabs, indents, and columns. Finally, they let you adjust such +typographic details as justification style, letter spacing, word +spacing, hyphenation, and kerning. +</p> + +<p> +In terms of typographic control, these macros resemble +the commands used on dedicated typesetting computers like +Compugraphics and Linotronics. Most of them simply give access +to groff’s typesetting primitives in a way that’s +consistent and easy to use. A few of them (tabs and indents, +for example) handle fundamental typesetting requirements in ways +radically different from groff primitives. +</p> + +<p> +With 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 +<kbd><a href="docprocessing.html#start">START</a></kbd> +macro; see below), every macro is a literal command that remains +in effect until you modify it or turn it off. This means that if +you want to create flyers, surveys, tabulated forms, curricula +vitae and so on, you may do so in the good old-fashioned way: one +step at a time with complete control over every element on the +page. +</p> + +<p> +Years of reading various mailing lists dealing with computer +typesetting (groff, TeX, and friends) have convinced me that no +program can ever replace the human eye and human input when it +comes to high quality typesetting. As of this writing, a thread +on the subject of “micro typography” in groff has been +going on for nearly a month. The reason for the lengthy thread +is obvious; words and punctuation on the printed page are too +variable, too fluid, to be rendered flawlessly by any algorithm, +no matter how clever. (For whatever it’s worth, a similar +problem exists with engraving musical scores by computer.) +</p> + +<p> +Mom does not try to solve the problems posed by things like +hanging punctuation, left-margin adjustments for upper case +letters like T and W, and so on. She merely tries to provide +tools that allow knowledgeable typesetters to come up with +solutions to these problems in ways that are easier and more +intuitive than manipulating groff at the +<a href="definitions.html#primitives">primitive</a> +level. As a professional typesetter of more than two decades, and +a writer, I have encountered few situations that cannot be handled +by mom’s typesetting macros. +</p> + +<p> +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 +<a href="definitions.html#just">justifying</a> +lines. At present, only word spacing is adjusted, requiring what +I consider an unnecessary amount of user intervention whenever +letter spacing is required. +</p> + +<h2 id="intro-docprocessing" class="docs">Document processing with mom</h2> + +<p> +Mom’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. +</p> + +<p> +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— +<a href="docprocessing.html#printstyle"><kbd>PRINTSTYLE TYPEWRITE</kbd></a>— +that changes typeset documents into ones that would make your +high-school typing teacher proud. Footnotes, endnotes, tables of +contents, multiple columns, nested lists, recto/verso printing and +user designable headers and footers are also part of the fun. +</p> + +<h2 id="intro-philosophy" class="docs">Mom’s philosophy</h2> + +<p> +Formatting documents should be easy, from soup to nuts. Writers +need to focus on what they’re writing, not on how it looks. +From the moment you fire up an editor to the moment you add +"FINIS" to your opus, nothing should interfere with the flow of +your words. The commands needed to format your work should be +easy to remember, comprehensible, and stand out well from the +text. There shouldn’t be too much clutter. Your documents +should be as readable inside a text editor as they are on the +printed page. +</p> + +<p> +Unfortunately, in computerland, “easy,” +“comprehensible,” and “readable” often +mean “you’re stuck with what you get.” No +document formatting system can give you exactly what you want all +the time, every time. Documents, it seems, always need to be +tweaked, either to satisfy a typographic whim or to clarify some +aspect of their content. +</p> + +<p> +Groff has traditionally solved the problem of formatting vs. +tweaking by requiring users of the common macro packages (mm, ms, +me and their offspring) to resort to groff +<a href="definitions.html#primitives">primitives</a> +and +<a href="definitions.html#inlines">inline escapes</a> +for their special typesetting needs. Not to put too fine a +point on it, groff primitives tend toward the abstruse, and most +inline escapes are about as readable in-line as an encrypted +password. This does not make for happy-camper writers, who either +find themselves stuck with a document formatting style they +don’t really like, or are forced to learn groff from the +ground up—a daunting task, to say the least. +</p> + +<p> +Mom aims to make creating documents a simple matter, but with +no corresponding loss of user control. The document processing +macros provide an excellent set of defaults, but if something is +not to your liking, you can change it. And in combination with +the typesetting macros, you have all the tools you need to massage +passages and tweak pages until they look utterly professional. +</p> + +<p> +One rarely hears the term “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. +</p> + +<p> +Mom does not try to be all things to all people. In contrast to +the normal groff philosophy, she does not try to produce output +that looks good no matter where it’s displayed. She’s +designed for printed output, although with +<a href="docprocessing.html#printstyle"><kbd>PRINTSTYLE TYPEWRITE</kbd></a> +she produces acceptable terminal copy. She makes no attempt to be +compatible with older versions of troff. +</p> + +<p> +One special feature in mom’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. +</p> + +<h2 id="intro-documentation" class="docs">A note on mom’s documentation</h2> + +<p> +Writing documentation is tough, no doubt about it. One is never +quite sure of the user’s level of expertise. Is s/he new +to the application, new to its underlying protocols and programs, +new to the operating system, new to computers? At some point, one +has to decide whom the documentation is for. Making the wrong +decision can mean the difference between a program that gets used +and a program that gets tossed. +</p> + +<p> +Mom’s documentation assumes users know their way around +their own operating system (basic file management, how to invoke +commands, how to use a text editor, etc). I use GNU/Linux, +and while the documentation may exhibit a GNU/Linux bias, mom +and groff can, in fact, be used on a variety of other popular +operating systems, including the one from Redmond, Virginia, USA. +</p> + +<p> +The documentation further assumes they at least know what groff +is, even if they don’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. +</p> + +<h2 id="canonical" class="docs">Canonical reference materials</h2> + +<p> +The canonical reference materials for groff are +<strong>cstr54</strong> (a downloadable PostScript copy of which +is available +<a href="http://www.kohala.com/start/troff/">here</a>) +and the <strong>troff</strong> and <strong>groff_diff</strong> +manpages. Another excellent source of information (maybe the best) +is the groff info pages, available by typing +<kbd>info groff</kbd> +at the command line (assuming you have the TeXinfo standalone +browser installed on your system, which is standard for most +GNU/Linux distributions). And for inputting special characters, +see <kbd>man groff_char</kbd>. +</p> + +<p style="margin-top: 24px;"> +I’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. +<i>Mea culpa.</i> +</p> + +<div class="box-tip"> +<p class="tip-top" style="padding-bottom: 9px;"> +<b>Note:</b> 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. +</p> +</div> + +<div class="box-tip"> +<p class="tip-top" style="padding-bottom: 9px; text-indent: 0px;"> +<strong>Addendum:</strong> As of version 1.4-a, the main macro +file, om.tmac, is now stripped of comments when groff is built +from sources. om.tmac in the sources themselves still contains +the comments, as do the tarballs posted on mom’s homepage. +</p> +</div> + +<div class="rule-short" style="padding-top: 6px; padding-bottom: 3px;"><hr/></div> + +<h2 id="macro-args" class="docs">How to read macro arguments</h2> + +<p> +The concise descriptions of macros in this documentation typically +look like this: +</p> + +<div class="box-macro-args"> +Macro: <b>MACRO_NAME</b> <kbd class="macro-args">arguments</kbd> +</div> + +<p> +<kbd>arguments</kbd> lists the macro’s +arguments using conventions that should be familiar to anyone who +has ever read a manpage. Briefly: +</p> + +<ol> + <li>Macro arguments are separated from each other by spaces.</li> + <li>If an argument is surrounded by chevrons + (<kbd>< ></kbd>), it’s a description + of the argument, not the argument itself. + </li> + <li>If an argument begins with or is surrounded by double-quotes, the + double quotes MUST be included in the argument. + </li> + <li>If the user has a choice between several arguments, each of the + choices is separated by the pipe character + (<kbd>|</kbd>), which means “or.” + </li> + <li>Arguments that are optional are surrounded by square brackets.</li> + <li><kbd><off></kbd> in an argument list means that any + argument other than those in the argument list turns the + macro off. + </li> +</ol> + +<h3 id="toggle-macro" class="docs">Toggle macros</h3> + +<p> +Some macros don’t require an argument. They simply start +something. When you need to turn them off, the same macro with +<em>any</em> argument will do the trick. That’s right: +<em>any</em> argument (in caps, lowercase or a mixture +thereof). This permits choosing whatever works for you: +<kbd>OFF, end, Quit, Q, X</kbd>... Hell, it +could even be <kbd>I_love_mom</kbd>. +</p> + +<p> +Since these macros toggle things on and off, the argument list +simply reads <kbd>toggle</kbd>. +</p> + +<div id="examples" class="examples-container"> +<h2 class="docs" style="margin-top: .5em;">Examples</h2> + +<div class="examples">Example 1: An argument requiring double-quotes</div> + +<div class="box-macro-args" style="max-width: 684px;"> +Macro: <b>TITLE</b> <kbd class="macro-args">"<title of document>"</kbd> +</div> + +<p> +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: +<br/> +<span class="pre-in-pp"> + .TITLE "My Pulitzer Novel" +</span> +</p> + +<div class="examples" style="margin-top: -1em;">Example 2: A macro with required and optional arguments</div> + +<div class="box-macro-args" style="width: 684px;"> +Macro: <b>TAB_SET</b> <kbd class="macro-args"><tab number> <indent> <length> [ L | R | C | J [ QUAD ] ] </kbd> +</div> + +<p> +The first required argument is a number that identifies the tab +(say, "3"). The second required argument is an indent from the +left margin (say, 6 picas). The third required argument is the +length of the tab (say, 3 picas). Therefore, at a minimum, when +using this macro, you would enter: +<br/> +<span class="pre-in-pp"> + .TAB_SET 3 6P 3P +</span> +The remaining two arguments are optional. The first is a +single letter, either <kbd>L, R, C</kbd> or +<kbd>J</kbd>. The second, which is itself +optional after <kbd>L, R, C</kbd> or +<kbd>J</kbd>, is the word <kbd>QUAD</kbd>. +Therefore, depending on what additional information you wish to +pass to the macro, you could enter: +<br/> +<span class="pre-in-pp"> + .TAB_SET 3 6P 3P L +</span> +or +<br/> +<span class="pre-in-pp"> + .TAB_SET 3 6P 3P L QUAD +</span> +</p> + +<div id="toggle-example" class="examples" style="margin-top: -1em;">Example 3: A sample toggle macro:</div> + +<div class="box-macro-args" style="max-width: 684px;"> +Macro: <b>QUOTE</b> <kbd class="macro-args">toggle</kbd> +</div> + +<p> +<kbd>QUOTE</kbd> begins a section of quoted text +in a document and doesn’t require an argument. When the +quote’s finished, you have to tell mom it’s done. +<span class="pre"> + .QUOTE + So runs my dream, but what am I? + An infant crying in the night + An infant crying for the light + And with no language but a cry. + .QUOTE OFF +</span> +</p> + +<p> + Alternatively, you could have turned the quote off with + <kbd>END</kbd>, or <kbd>X</kbd>, or something else. + </p> +</div> + +<!-- Navigation links --> +<table style="width: 100%; margin-top: 12px;"> +<tr> + <td style="width: 33%;"><a href="toc.html">Back to Table of Contents</a></td> + <td style="width: 33%; text-align: center;"><a href="#top">Top</a></td> + <td style="width: 33%; text-align: right;"><a href="definitions.html#top">Next: Definitions</a></td> +</tr> +</table> + +</div> + +<div class="bottom-spacer"><br/></div> + +</body> +</html> +<!-- vim: fileencoding=utf-8: nomodified: --> 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 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- +This file is part of groff, the GNU roff type-setting system. + +Copyright (C) 2004, 2005, 2006, 2009, 2010 Free Software Foundation, Inc. +Written by Peter Schaffter. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with the +Invariant Sections being this comment section, with no Front-Cover +Texts, and with no Back-Cover Texts. + +A copy of the Free Documentation License is included as a file called +FDL in the main directory of the groff source package. +--> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"> + +<head> + <meta http-equiv="content-type" content="text/html;charset=utf-8"/> + <title>Mom -- Writing letters</title> + <link rel="stylesheet" type="text/css" href="stylesheet.css" /> +</head> + +<body style="background-color: #f5faff;"> + +<!-- ==================================================================== --> + +<div id="top" class="page"> + +<!-- Navigation links --> +<table style="width: 100%;"> +<tr> + <td><a href="toc.html">Back to Table of Contents</a></td> + <td style="text-align: right;"><a href="macrolist.html#top">Next: Quick reference guide</a></td> +</tr> +</table> + +<h1 class="docs">Writing letters</h1> + +<h2 id="letters-intro" class="docs">Introduction</h2> + +<p> +Mom’s simple but effective letter-writing macros are a subset +of the +<a href="docprocessing.html#docprocessing">document processing macros</a>, +designed to ease the creation of correspondence. +</p> + +<p> +Because the letter macros are a subset of the document processing +macros, you can use +<a href="definitions.html#controlmacro">control macros</a> +to design correspondence to your own specifications. However, +mom makes no pretence of providing complete design flexibility in +the matter of letters, which are, after all, simple communicative +documents whose only real style requirements are that they be neat +and professional-looking. +</p> + +<div class="examples-container" style="margin-top: 1.5em; margin-bottom: 1.5em;"> +<h3 id="tutorial" class="docs">Tutorial – writing letters</h3> + +<p> +Mom letters begin, like all mom-processed documents, with +<a href="docprocessing.html#reference-macros">reference macros</a> +(in this case, +<a href="docprocessing.html#author">AUTHOR</a>), +a +<a href="docprocessing.html#doctype">DOCTYPE</a> +(LETTER, obviously), the essential +<a href="docprocessing.html#printstyle">PRINTSTYLE</a> +macro, and +<a href="docprocessing.html#start">START</a>, +like this: +<br/> +<span class="pre-in-pp"> + .AUTHOR "Yannick P. Guique" + .DOCTYPE LETTER + .PRINTSTYLE TYPESET + .START +</span> +PRINTSTYLE, above, could also be <kbd>TYPEWRITE</kbd>. Mom has no +objection to creating letters that look like they were typed on an +Underwood by a shapely secretary with 1940s gams. +</p> + +<p> +After the START macro, you enter headers pertinent to your letter: +the date, the addressee (in business correspondence, typically both +name and address), the addresser (that’s you; in business +correspondence, typically both name and address), and a greeting +(in full, e.g. “Dear Mr. Smith,” or “Dear +Mr. Smith:”). +</p> + +<p> +The macros for entering the headers are simple (they’re not even +<a href="definitions.html#toggle">toggles</a>): +<br/> +<span class="pre-in-pp"> + .DATE + .TO + .FROM + .GREETING +</span> +You may enter them in any order you like, except for GREETING, which +must come last. Mom ignores any headers you omit and spaces the +letter’s opening according to what you do include. See +<a href="#letters-defaults">Default for letters</a> +to find out how mom formats the headers. +</p> + +<p> +(In pre 1.1.7-a releases of mom, the order of entering headers was +fixed at the above. This has been changed, although if you do +follow the above order, mom will continue to behave exactly as she +did in pre 1.1.7-a.) +</p> + +<p> +Once you’ve filled in what you need to get a letter started, +simply type the letter, introducing each and every paragraph, +including the first, with the +<a href="docelement.html#pp">PP</a> +macro. +</p> + +<p> +At the end of the letter, should you wish a closing (“Yours +truly,” “Sincerely,” “Hugs and +kisses”), invoke the macro, <kbd>.CLOSING</kbd>, on a line +by itself, and follow it with the text of the closing. <b>N.B.</b> +Don’t put your name here; mom supplies it automatically from +<a href="docprocessing.html#author">AUTHOR</a>), +with enough space to leave room for your signature. If you omit the +closing, mom simply adds your name (from AUTHOR), again with enough +space for your signature. +</p> + +<p> +Assuming our tutorial letter is for business correspondence, +here’s what the complete letter looks like. +<br/> +<span class="pre-in-pp"> + .AUTHOR "Yannick P. Guique" + .DOCTYPE LETTER + .PRINTSTYLE TYPESET + .START + .DATE + August 25, 2010 + .TO + GUILLAUME BARRIÈRES + Minidoux Corporation + 5000 Pannes Drive + Redmond, Virginia + .FROM + Y.P. GUIQUE + 022 Umask Road + St-Sauveur-en-dehors-de-la-mappe, Québec + .GREETING + Dear Mr. Barrières, + .PP + It has come to my attention that you have once again been + lobbying the US government to prohibit the use of open source + software by endeavouring to outlaw so-called "warranty + free" applications. + .PP + I feel it is my duty to inform you that the success of your + operating system relies heavily on open source programs and + protocols, notably TCP/IP. + .PP + Therefore, in the interests of your corporation’s fiscal health, + I strongly advise that you withdraw support for any US + legislation that would cripple or render illegal open source + development. + .CLOSING + Sincerely, +</span> +This produces a letter with headers that follow the North American +standard for business correspondence. If you’d prefer another style +of correspondence, for example, British, you’d set up the same +letter like this: +<br/> +<span class="pre-in-pp"> + .AUTHOR "Yannick P. Guique" + .DOCTYPE LETTER + .PRINTSTYLE TYPESET + .START + .FROM + .RIGHT + Y.P. GUIQUE + 022 Umask Road + St-Sauveur-en-dehors-de-la-mappe, Québec + .TO + GUILLAUME BARRIÈRES + Minidoux Corporation + 5000 Pannes Drive + Redmond, Virginia + .DATE + .RIGHT + August 25, 2004 + .GREETING + Dear Mr. Barrières, +</span> +Notice the use of <kbd>.RIGHT</kbd> after <kbd>.FROM</kbd> and +<kbd>.DATE</kbd> in this example, used to change the default quad +for these macros. +</p> +</div> + +<h2 id="letters-defaults" class="docs">Mom’s default letter style</h2> + +<p> +In letters, if the order of header macros is +</p> +<ol style="margin-top: -.5em;"> + <li><kbd>.DATE</kbd></li> + <li><kbd>.TO</kbd> (the addressee)</li> + <li><kbd>.FROM</kbd> (the addresser)</li> + <li><kbd>.GREETING</kbd> (“Dear Whoever,” “To Whom It May Concern,” etc.)</li> +</ol> +<p style="margin-top: -.5em;"> +mom sets +</p> +<ul style="margin-top: -.5em;"> + <li>the date flush right, page right, at the top of page one, + with a gap of two linespaces underneath + </li> + <li>the addressee (<kbd>.TO</kbd>) in a block flush left, page + left, with a gap of one linespace underneath + </li> + <li>the addresser (<kbd>.FROM</kbd>) in a block flush left, page + left, with a gap of one linespace underneath + </li> + <li>the greeting flush left, with a gap of one linespace + underneath + </li> +</ul> +<p style="margin-top: -.5em;"> +which is the standard for North American business correspondence. +</p> + +<p> +If you switch the order of <kbd>.DATE</kbd>, <kbd>.TO</kbd> and/or +<kbd>.FROM</kbd>, mom sets all the headers +flush left, with a gap of one linespace underneath each. (The +default left quad of any header can be changed by invoking the +<kbd>.RIGHT</kbd> macro, on a line by itself, immediately before +inputting the text of the header.) +</p> + +<p> +Following the headers, mom sets +</p> +<ul style="margin-top: -.5em;"> + <li>the body of the letter justified</li> + <li>in multi-page letters: + <ul style="margin-left: -.5em;"> + <li>a footer indicating there’s a next page (of the form <kbd>.../#</kbd>)</li> + <li>the page number at the top of every page after page one</li> + </ul></li> + <li>the closing/signature lines flush left, indented halfway across the page</li> +</ul> + +<p> +Other important style defaults are listed below, and may be changed +via the +<a href="typesetting.html#top">typesetting macros</a> +or the document processing +<a href="definitions.html#controlmacro">control macros</a> +prior to +<a href="docprocessing.html#start">START</a>. +Assume that any style parameter not listed below is the same as for +any document processed with +<a href="docprocessing.html#typeset-defaults">PRINTSTYLE <kbd>TYPESET</kbd></a> +or +<a href="docprocessing.html#typewrite-defaults">PRINTSTYLE <kbd>TYPEWRITE</kbd></a>. +</p> + +<div class="defaults-container" style="padding-bottom: 8px;"> +<span class="pre defaults"> + PARAMETER PRINTSTYLE TYPESET PRINTSTYLE TYPEWRITE + + Paper size 8.5 x 11 inches 8.5 x 11 inches + Left/right margins 1.125 inches 1.125 inches + Header margin 3.5 picas 3.5 picas + (for page numbers) + Header gap 3 picas 3 picas + (for page numbers) + Family Times Roman Courier + Font roman roman + Point size 12 12 + Line space 13.5 12 (i.e. singlespaced) + Paragraph indent 3 ems 3 picas + Spaced paragraphs yes no + Footers* yes yes + Footer margin 3 picas 3 picas + Footer gap 3 picas 3 picas + Page numbers top, centred top, centred + + *Footers contain a "next page" number of the form .../# +</span> +</div> + +<div class="rule-medium"><hr/></div> + + +<div class="macro-list-container"> +<h3 id="index-letters-macros" class="macro-list">The letter macros</h3> +<p style="margin-left: 9px; margin-top: -1.5em;"> +All letter macros must come after +<a href="docprocessing.html#start">START</a>, +except NO_SUITE, which must come after +<a href="docprocessin.html#start">PRINTSTYLE</a> +and before +<a href="docprocessing.html#start">START</a>. +</p> + +<ul class="macro-list" style="margin-top: -.75em;"> + <li><a href="#date">DATE</a></li> + <li><a href="#to">TO</a></li> + <li><a href="#from">FROM</a></li> + <li><a href="#greeting">GREETING</a></li> + <li><a href="#closing">CLOSING</a> + <ul style="margin-left: -.5em;"> + <li><a href="#closing-indent">CLOSING_INDENT</a></li> + <li><a href="#signature-indent">SIGNATURE_INDENT</a></li> + </ul></li> + <li><a href="#no-suite">NO_SUITE</a> – turn the “next page” footer off</li> +</ul> +</div> + +<!-- -DATE- --> + +<div id="date" class="box-macro-args"> +Macro: <b>DATE</b> +</div> + +<p> +Invoke <kbd>.DATE</kbd> on a line by itself, with the date +underneath, like this: +<br/> +<span class="pre-in-pp"> + .DATE + October 31, 2012 +</span> +If you wish to change the default quad direction for the date, +enter <kbd>.LEFT</kbd> or <kbd>.RIGHT</kbd>, on a line by itself, +immediately after <kbd>.DATE</kbd>. +</p> + +<p> +If you wish to insert additional space between the date and any +letter header that comes after it, do so after inputting the date, +not at the top of the next header macro, like this: +<br/> +<span class="pre-in-pp"> + .DATE + October 31, 2012 + .SPACE \"Or, more simply, .SP +</span> +If you wish to remove the default space, +<br/> +<span class="pre-in-pp"> + .SPACE -1v \"Or, more simply, .SP -1v +</span> +will do the trick. +</p> + +<!-- -TO- --> + +<div id="to" class="box-macro-args"> +Macro: <b>TO</b> +</div> + +<p> +Invoke <kbd>.TO</kbd> on a line by itself, with the name and address +of the addressee underneath, like this: +<br/> +<span class="pre-in-pp"> + .TO + JOHN SMITH + 10 Roberts Crescent + Bramladesh, Ont. +</span> +If you wish to change the default quad direction for the address, +enter <kbd>.LEFT</kbd> or <kbd>.RIGHT</kbd>, on a line by itself, +immediately after <kbd>.TO</kbd>. +</p> + +<p> +If you wish to insert additional space between the address and +any letter header that comes after it, do so after inputting the +address, not at the top of the next header macro, like this: +<br/> +<span class="pre-in-pp"> + .TO + JOHN SMITH + 10 Roberts Crescent + Bramladesh, Ont. + .SPACE \"Or, more simply, .SP +</span> +If you wish to remove the default space, +<br/> +<span class="pre-in-pp"> + .SPACE -1v \"Or, more simply, .SP -1v +</span> +will do the trick. +</p> + +<!-- -FROM- --> + +<div id="from" class="box-macro-args"> +Macro: <b>FROM</b> +</div> + +<p> +Invoke <kbd>.FROM</kbd> on a line by itself, with the name and +address of the addresser underneath, like this: +<br/> +<span class="pre-in-pp"> + .FROM + JOE BLOW + 15 Brunette Road + Ste-Vieille-Andouille, Québec +</span> +If you wish to change the default quad direction for the address, +enter <kbd>.LEFT</kbd> or <kbd>.RIGHT</kbd>, on a line by itself, +immediately after <kbd>.FROM</kbd>. +</p> + +<p> +If you wish to insert additional space between the address and +any letter header that comes after it, do so after inputting the +address, not at the top of the next header macro, like this: +<br/> +<span class="pre-in-pp"> + .FROM + JOE BLOW + 15 Brunette Road + Ste-Vieille-Andouille, Québec + .SPACE \"Or, more simply, .SP +</span> +If you wish to remove the default space, +<br/> +<span class="pre-in-pp"> + .SPACE -1v \"Or, more simply, .SP -1v +</span> +will do the trick. +</p> + +<!-- -GREETING- --> + +<div id="greeting" class="box-macro-args"> +Macro: <b>GREETING</b> +</div> + +<p> +Invoke <kbd>.GREETING</kbd> on a line by itself, with the full +salutation you want for the letter underneath, like this: +<br/> +<span class="pre-in-pp"> + .GREETING + Dear Mr. Smith, +</span> +</p> + +<!-- -CLOSING- --> + +<div id="closing" class="box-macro-args"> +Macro: <b>CLOSING</b> +</div> + +<p> +Invoke <kbd>.CLOSING</kbd> on a line by itself after the body of +the letter, with the closing you’d like (e.g. “Yours +truly,”) underneath, like this: +<br/> +<span class="pre-in-pp"> + .CLOSING + Yours truly, +</span> +</p> + +<div class="box-tip" style="background-color: #E3D2B1;"> +<p class="tip"> +<span class="tip" style="display: inline-block; padding-bottom: .5em; color: #000056;">CLOSING control macros and defaults</span> +<br/> +Two macros control the behaviour of <kbd>.CLOSING</kbd>: +</p> +<ul style="margin-top: -1.25em;"> + <li>CLOSING_INDENT</li> + <li>SIGNATURE_SPACE</li> +</ul> + +<p id="closing-indent" style="margin-top: -.25em;"> +The first, CLOSING_INDENT, indicates the distance from the left +margin you’d like to have your closing indented. It takes a +single +<a href="definitions.html#numericargument">numeric argument</a> +and must have a +<a href="definitions.html#unitofmeasure">unit of measure</a> +appended to it, unless you want an indent of 0 (zero). Mom’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 +<a href="definitions.html#picaspoints">picas</a>, +you’d do it like this: +<br/> +<span class="pre-in-pp"> + .CLOSING_INDENT 6P +</span> +Or, if you wanted to have no indent at all: +<br/> +<span class="pre-in-pp"> + .CLOSING_INDENT 0 +</span> +</p> + +<p id="signature-space" style="margin-top: -1.25em;"> +The second, SIGNATURE_SPACE, controls how much room to leave for the +signature. It takes a single +<a href="definitions.html#numericargument">numeric argument</a> +and must have a +<a href="definitions.html#unitofmeasure">unit of measure</a> +appended to it. Mom’s default is 3 line spaces, but if you +wanted to change that to, say, 2 line spaces, you’d do: +<br/> +<span class="pre-in-pp"> + .SIGNATURE_SPACE 2v +</span> +</p> +</div> + +<!-- -NO_SUITE- --> + +<div class="box-macro-args" style="margin-top: 2em;"> +Macro: <b>NO_SUITE</b> +</div> + +<p> +If you don’t want mom to print a “next page” +number at the bottom of multi-page letters, invoke +<kbd>.NO_SUITE</kbd>, on a line by itself, prior to +<a href="docprocessing.html#start">START</a>. +</p> + +<div class="rule-long"><hr/></div> + +<!-- Navigation links --> +<table style="width: 100%; margin-top: 12px;"> +<tr> + <td style="width: 33%;"><a href="toc.html">Back to Table of Contents</a></td> + <td style="width: 33%; text-align: center;"><a href="#top">Top</a></td> + <td style="width: 33%; text-align: right;"><a href="macrolist.html">Next: Quick reference guide</a></td> +</tr> +</table> + +</div> + +<div class="bottom-spacer"><br/></div> + +</body> +</html> +<!-- vim: fileencoding=utf-8: nomodified: --> 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 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- +This file is part of groff, the GNU roff type-setting system. + +Copyright (C) 2004, 2005, 2006, 2009, 2010 Free Software Foundation, Inc. +Written by Peter Schaffter. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with the +Invariant Sections being this comment section, with no Front-Cover +Texts, and with no Back-Cover Texts. + +A copy of the Free Documentation License is included as a file called +FDL in the main directory of the groff source package. +--> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"> + +<head> + <meta http-equiv="content-type" content="text/html;charset=utf-8"/> + <title>Mom -- Quick reference guide</title> + <link rel="stylesheet" type="text/css" href="stylesheet.css" /> +</head> + +<body style="background-color: #f5faff;"> + +<!-- ==================================================================== --> + +<div id="top" class="page"> + +<!-- Navigation links --> +<table style="width: 100%;"> +<tr> + <td><a href="toc.html">Back to Table of Contents</a></td> + <td style="text-align: right;"><a href="appendices.html#top">Next: Appendices</a></td> +</tr> +</table> + +<h1 class="docs">Quick reference guide</h1> + +<p> +Once you know your way around mom, you may find this guide +preferable to using the Table of Contents. It lists mom’s +major user-space macros. The links point to references found +elsewhere in the documentation. +</p> + + +<div class="macro-list-container" style="padding-left: 9px; padding-right: 9px; padding-bottom: 1px;"> +<h2 class="docs" style="text-align: center; padding-top: 15px;">Index to the quick reference guide</h2> +<div style="width: 50%; float: left; margin-right: 9px;"> +<h3 class="docs" style="margin-top: 1.25em;">TYPESETTING MACROS</h3> +<ul style="margin-top: .5em; margin-left: 0; padding-left: 0; list-style-type: none;"> + <li><a href="#qr-1">Paper size, margins, line length</a></li> + <li><a href="#qr-2">Family, font, point size</a></li> + <li><a href="#qr-3">Font modifications</a></li> + <li><a href="#qr-4">Linespacing (leading)</a></li> + <li><a href="#qr-5">Justification, quad, breaking lines</a></li> + <li><a href="#qr-6">Hyphenation</a></li> + <li><a href="#qr-7">Word and sentence spacing</a></li> + <li><a href="#qr-8">Kerning, ligatures, smartquotes</a></li> + <li><a href="#qr-9">Horizontal/vertical motions, columns</a></li> + <li><a href="#qr-10">Indents</a></li> + <li><a href="#qr-11">Tabs</a></li> + <li><a href="#qr-12">Underscoring, underlining</a></li> + <li><a href="#qr-13">Superscipts</a></li> + <li><a href="#qr-14">Nested lists</a></li> + <li><a href="#qr-15">Colour</a></li> + <li><a href="#qr-16">Dropcaps</a></li> + <li><a href="#qr-17">Utilities</a></li> + <li><a href="#qr-18">Graphical Objects</a></li> +</ul> +<h3 class="docs" style="margin-top: -.5em;">DOCUMENT PROCESSING MACROS</h3> +<ul style="margin-top: .5em; margin-left: 0; padding-left: 0; list-style-type: none;"> + <li><a href="#qr-19">Reference macros</a></li> + <li><a href="#qr-20">General document formatting directives</a></li> + <li><a href="#qr-21">Line numbering</a></li> + <li><a href="#qr-22">Set documents in columns</a></li> + <li><a href="#qr-23">TYPEWRITE control macros</a></li> + <li><a href="#qr-24">Initiate document processing</a></li> +</ul> +</div> +<ul style="margin-top: 1.75em; margin-left: 0; padding-left: 0; list-style-type: none;"> + <li><a href="#qr-25">Epigraphs</a></li> + <li><a href="#qr-26">Main heads</a></li> + <li><a href="#qr-27">Subheads</a></li> + <li><a href="#qr-28">Paragraph heads</a></li> + <li><a href="#qr-19">Reference macros</a></li> + <li><a href="#qr-29">Paragraphs</a></li> + <li><a href="#qr-30">Quotes (line for line quotes)</a> </li> + <li><a href="#qr-31">Blockquotes (cited passages of text)</a></li> + <li><a href="#qr-32">Code snippets (inserting bits of programming code)</a></li> + <li><a href="#qr-33">Author linebreaks (section breaks)</a></li> + <li><a href="#qr-34">Document termination string</a></li> + <li><a href="#qr-35">Footnotes</a></li> + <li><a href="#qr-36">Endnotes</a></li> + <li><a href="#qr-37">Margin notes</a></li> + <li><a href="#qr-38">Bibliographic references</a></li> + <li><a href="#qr-39">Tables of contents</a></li> + <li><a href="#qr-40">Letter (correspondence) macros</a></li> + <li><a href="#qr-41">Changing global print style parameters after<br/><span style="margin-left: 1.25em;">START</span></a></li> + <li><a href="#qr-42">Managing a document’s first-page header<br/><span style="margin-left: 1.25em;">(the “docheader”)</span></a></li> + <li><a href="#qr-43">Managing page headers and footers</a></li> + <li><a href="#qr-44">Recto/verso page headers and footers</a></li> + <li><a href="#qr-45">Pagination</a></li> + <li><a href="#qr-46">Document and section cover (title) pages</a></li> + <li><a href="#qr-47">Utilities</a></li> +</ul> +</div> + +<h2 class="docs">Quick reference guide</h2> + +<div style="display: inline-block; margin-top: 1em; margin-bottom: .5em; border-bottom: 2px solid #302419;"><kbd>TYPESETTING MACROS</kbd></div> + +<table class="quick-ref"> +<tr> +<th id="qr-1" class="quick-ref" colspan="2" >+++ Paper size, margins, line length</th> +</tr> +<tr> +<td><a href="typesetting.html#paper">PAPER</a></td><td>-- set common paper sizes (letter, A4, etc)</td> +</tr> +<tr> +<td><a href="typesetting.html#pagewidth">PAGEWIDTH</a></td><td>-- set a custom page width</td> +</tr> +<tr> +<td><a href="typesetting.html#pagelength">PAGELENGTH</a></td><td>-- set a custom page length</td> +</tr> +<tr> +<td><a href="typesetting.html#page">PAGE</a></td><td>-- set explicit page dimensions and margins</td> +</tr> +<tr> +<td><a href="typesetting.html#t-margin">T_MARGIN</a></td><td>-- set a top margin</td> +</tr> +<tr> +<td><a href="typesetting.html#b-margin">B_MARGIN</a></td><td>-- set a bottom margin</td> +</tr> +<tr> +<td><a href="typesetting.html#l-margin">L_MARGIN</a></td><td>-- set a left margin (page offset)</td> +</tr> +<tr> +<td><a href="typesetting.html#r-margin">R_MARGIN</a></td><td>-- set a right margin</td> +</tr> +<tr> +<td><a href="typesetting.html#linelength">LL</a></td><td>-- set a line length</td> +</tr> +</table> + +<table class="quick-ref"> +<tr><th id="qr-2" class="quick-ref" colspan="2">+++ Family, font, point size</th></tr> +<tr> +<td><a href="typesetting.html#family">FAMILY</a></td><td>-- set the family of type</td> +</tr> +<tr> +<td><a href="typesetting.html#font">FT</a></td><td>-- set the font style (roman, italic, etc)</td> +</tr> +<tr> +<td><a href="typesetting.html#fallback-font">FALLBACK_FONT</a></td><td>-- establish a fallback font (for missing fonts)</td> +</tr> +<tr> +<td><a href="typesetting.html#ps">PT_SIZE</a></td><td>-- set the point size</td> +</tr> +<tr> +<td><a href="inlines.html#inline-size-mom">\*[SIZE n]</a></td><td>-- change the point size inline</td> +</tr> +</table> + +<table class="quick-ref"> +<tr> +<th id="qr-3" class="quick-ref" colspan="2" >+++ Font modifications</th> +</tr> +<tr><td style="padding-left: 0;">Pseudo italic</td></tr> +<tr> +<td><a href="typesetting.html#setslant">SETSLANT</a></td><td>-- set the degree of slant</td> +</tr> +<tr> +<td><a href="typesetting.html#slant-inline">\*[SLANT]</a></td><td>-- invoke pseudo italic inline</td> +</tr> +<tr> +<td><a href="typesetting.html#slant-inline">\*[SLANTX]</a></td><td>-- off pseudo italic inline</td> +</tr> +<tr><td style="padding-left: 0;">Pseudo bold</td></tr> +<tr> +<td><a href="typesetting.html#setbolder">SETBOLDER</a></td><td>-- set the amount of emboldening</td> +</tr> +<tr> +<td><a href="typesetting.html#bolder-inline">\*[BOLDER]</a></td><td>-- invoke pseudo bold inline</td> +</tr> +<tr> +<td><a href="typesetting.html#bolder-inline">\*[BOLDERX]</a></td><td>-- off pseudo bold inline</td> +</tr> +<tr><td style="padding-left: 0;">Pseudo condensed</td></tr> +<tr> +<td><a href="typesetting.html#condense">CONDENSE</a></td><td>-- set the amount to pseudo condense</td> +</tr> +<tr> +<td><a href="typesetting.html#cond-inline">\*[COND]</a></td><td>-- invoke pseudo condensing inline</td> +</tr> +<tr> +<td><a href="typesetting.html#cond-inline">\*[CONDX]</a></td><td>-- off pseudo condensing inlines</td> +</tr> +<tr><td style="padding-left: 0;">Pseudo extended</td></tr> +<tr> +<td><a href="typesetting.html#extend">EXTEND</a></td><td>-- set the amount to pseudo extend</td> +</tr> +<tr> +<td><a href="typesetting.html#ext-inline">\*[EXT]</a></td><td>-- invoke pseudo extending inline</td> +</tr> +<tr> +<td><a href="typesetting.html#ext-inline">\*[EXTX]</a></td><td>-- off pseudo condensing inlinee</td> +</tr> +</table> + +<table class="quick-ref"> +<tr> +<th id="qr-4" class="quick-ref" colspan="2" >+++ Linespacing (leading)</th> +</tr> +<tr> +<td><a href="typesetting.html#leading">LS</a></td><td>-- set the linespacing (leading)</td> +</tr> +<tr> +<td><a href="typesetting.html#autolead">AUTOLEAD</a></td><td>-- set the linespacing relative to the point size</td> +</tr> +</table> + +<table class="quick-ref"> +<tr> +<th id="qr-5" class="quick-ref" colspan="2" >+++ Justification, quad direction, line-by-line setting, breaking lines</th> +</tr> +<tr> +<td><a href="typesetting.html#justify">JUSTIFY</a></td><td>-- justify text to both margins</td> +</tr> +<tr> +<td><a href="typesetting.html#quad">QUAD</a></td><td>-- "justify" text left, centre, or right</td> +</tr> +<tr> +<td><a href="typesetting.html#lrc">LEFT</a></td><td>-- set line-by-line quad left</td> +</tr> +<tr> +<td><a href="typesetting.html#lrc">CENTER</a></td><td>-- set line-by-line quad centre</td> +</tr> +<tr> +<td><a href="typesetting.html#lrc">RIGHT</a></td><td>-- set line-by-line quad right</td> +</tr> +<tr> +<td><a href="typesetting.html#br">BR</a></td><td>-- break a justified line</td> +</tr> +<tr> +<td><a href="typesetting.html#spread">SPREAD</a></td><td>-- force justify a line</td> +</tr> +<tr> +<td><a href="typesetting.html#el">EL</a></td><td>-- break a line without advancing on the page</td> +</tr> +</table> + +<table class="quick-ref"> +<tr> +<th id="qr-6" class="quick-ref" colspan="2" >+++ Hyphenation</th> +</tr> +<tr> +<td><a href="typesetting.html#hy">HY</a></td><td>-- automatic hyphenation on or off</td> +</tr> +<tr> +<td><a href="typesetting.html#hy-set">HY_SET</a></td><td>-- set automatic hyphenation parameters</td> +</tr> +</table> + +<table class="quick-ref"> +<tr> +<th id="qr-7" class="quick-ref" colspan="2" >+++ Word and sentence spacing</th> +</tr> +<tr> +<td><a href="typesetting.html#ws">WS</a></td><td>-- set the minimum word space size</td> +</tr> +<tr> +<td><a href="typesetting.html#ss">SS</a></td><td>-- set the sentence space size</td> +</tr> +</table> + +<table class="quick-ref"> +<tr> +<th id="qr-8" class="quick-ref" colspan="2" >+++ Kerning, ligatures, smartquotes</th> +</tr> +<tr> +<td><a href="typesetting.html#kern">KERN</a></td><td>-- automatic character pair kerning on or off</td> +</tr> +<tr> +<td><a href="inlines.html#inline-kerning-mom">\*[BU n]</a></td><td>-- move characters pairs closer together inline</td> +</tr> +<tr> +<td><a href="inlines.html#inline-kerning-mom">\*[FU n]</a></td><td>-- move character pairs further apart inline</td> +</tr> +<tr> +<td><a href="typesetting.html#rw">RW</a></td><td>-- uniformly reduce space between characters (tighten)</td> +</tr> +<tr> +<td><a href="typesetting.html#ew">EW</a></td><td>-- uniformly increase space between characters (loosen)</td> +</tr> +<tr> +<td><a href="typesetting.html#br-at-line-kern">BR_AT_LINE_KERN</a></td><td>-- break previous line every time RW or EW is invoked</td> +</tr> +<tr> +<td><a href="typesetting.html#ligatures">LIGATURES</a></td><td>-- automatic generation of ligatures on or off</td> +</tr> +<tr> +<td><a href="goodies.html#smartquotes">SMARTQUOTES</a></td><td>-- smartquoting on or off</td> +</tr> +</table> + +<table class="quick-ref"> +<tr> +<th id="qr-9" class="quick-ref" colspan="2" >+++ Horizontal and vertical movements, columnar setting</th> +</tr> +<tr> +<td><a href="typesetting.html#ald">ALD</a></td><td>-- move downards on the page</td> +</tr> +<tr> +<td><a href="typesetting.html#rld">RLD</a></td><td>-- move upwards on the page</td> +</tr> +<tr> +<td><a href="typesetting.html#space">SPACE</a></td><td>-- insert space between lines on a page</td> +</tr> +<tr> +<td><a href="inlines.html#down">\*[DOWN n]</a></td><td>-- temporarily move downwards in a line</td> +</tr> +<tr> +<td><a href="inlines.html#up">\*[UP n]</a></td><td>-- temporarily move upwards in a line</td> +</tr> +<tr> +<td><a href="inlines.html#fwd">\*[FWD n]</a></td><td>-- move forward in a line</td> +</tr> +<tr> +<td><a href="inlines.html#bck">\*[BCK n]</a></td><td>-- move backwards in a line</td> +</tr> +<tr> +<td><a href="typesetting.html#mco">MCO</a></td><td>-- multiple columns on</td> +</tr> +<tr> +<td><a href="typesetting.html#mcr">MCR</a></td><td>-- recto vertical position of column start</td> +</tr> +<tr> +<td><a href="typesetting.html#mcx">MCX</a></td><td>-- multiple columns off, advance past longest column</td> +</tr> +</table> + +<table class="quick-ref"> +<tr> +<th id="qr-10" class="quick-ref" colspan="2" >+++ Indents</th> +</tr> +<tr> +<td><a href="typesetting.html#il">IL</a></td><td>-- set and turn on a left indent</td> +</tr> +<tr> +<td><a href="typesetting.html#ir">IR</a></td><td>-- set and turn on a right indent</td> +</tr> +<tr> +<td><a href="typesetting.html#ib">IB</a></td><td>-- set and turn on indents both left and right</td> +</tr> +<tr> +<td><a href="typesetting.html#iq">IQ</a></td><td>-- quit (exit) all indents</td> +</tr> +<tr> +<td><a href="typesetting.html#ti">TI</a></td><td>-- set and turn on a temporary (one line) indent</td> +</tr> +<tr> +<td><a href="typesetting.html#hi">HI</a></td><td>-- set and turn on a hanging indent</td> +</tr> +<tr> +<td><a href="typesetting.html#iq">ILX</a></td><td>-- left indents off</td> +</tr> +<tr> +<td><a href="typesetting.html#iq">IRX</a></td><td>-- right indents off</td> +</tr> +<tr> +<td><a href="typesetting.html#iq">IBX</a></td><td>-- both left and right indents off</td> +</tr> +</table> + +<table class="quick-ref"> +<tr> +<th id="qr-11" class="quick-ref" colspan="2" >+++ Tabs</th> +</tr> +<tr> +<td><a href="typesetting.html#tab-set">TAB_SET</a></td><td>-- set up a typesetting tab</td> +</tr> +<tr> +<td><a href="typesetting.html#tab">TAB <n></a></td><td>-- call tab <n></td> +</tr> +<tr> +<td><a href="typesetting.html#tq">TQ</a></td><td>-- quit (exit) tabs</td> +</tr> +<tr> +<td><a href="typesetting.html#inline-st">\*[STn]...\*[STnX]</a></td><td>-- string tabs (mark tab positions inline)</td> +</tr> +<tr> +<td><a href="typesetting.html#tn">TN</a></td><td>-- move to tab <n+1> without advancing on the page</td> +</tr> +<tr> +<td><a href="typesetting.html#st">ST</a></td><td>-- set quad/fill for string tabs</td> +</tr> +</table> + +<table class="quick-ref"> +<tr> +<th id="qr-12" class="quick-ref" colspan="2" >+++ Underscoring, underlining</th> +</tr> +<tr> +<td><a href="goodies.html#underscore">UNDERSCORE</a></td><td>-- underscore</td> +</tr> +<tr> +<td><a href="goodies.html#UNDERSCORE2">UNDERSCORE2</a></td><td>-- double underscore</td> +</tr> +<tr> +<td><a href="goodies.html#underline">UNDERLINE</a></td><td>-- underline (fixed width fonts only)</td> +</tr> +<tr> +<td><a href="goodies.html#ul">\*[UL]...\*[ULX]</a></td><td>-- invoke underling inline (fixed width fonts only)</td> +</tr> +</table> + +<table class="quick-ref"> +<tr> +<th id="qr-13" class="quick-ref" colspan="2" >+++ Superscipts</th> +</tr> +<tr> +<td><a href="goodies.html#sup">\*[SUP]...\*[SUPX]</a></td><td>-- superscript (inline)</td> +</tr> +<tr> +<td><a href="goodies.html#sup">\*[CONDSUP]...\*[CONDSUPX]</a></td><td>-- pseudo-condensed superscript (inline)</td> +</tr> +<tr> +<td><a href="goodies.html#sup">\*[EXTSUP]...\*[EXTSUPX]</a></td><td>-- pseudo extended supercript (inline)</td> +</tr> +<tr> +<td><a href="goodies.html#sup-raise">SUPERSCRIPT_RAISE_AMOUNT</a></td><td>-- vertical offset of superscripts</td> +</tr> +</table> + +<table class="quick-ref"> +<tr> +<th id="qr-14" class="quick-ref" colspan="2" >+++ Nested lists</th> +</tr> +<tr> +<td><a href="docelement.html#list">LIST</a></td><td>-- begin a list</td> +</tr> +<tr> +<td><a href="docelement.html#item">ITEM</a></td><td>-- begin an item in a list</td> +</tr> +<tr> +<td><a href="docelement.html#shift-list">SHIFT_LIST</a></td><td>-- change the indent of a list</td> +</tr> +<tr> +<td><a href="docelement.html#reset-list">RESET_LIST</a></td><td>-- clear and reset a list’s enumerator</td> +</tr> +<tr> +<td><a href="docelement.html#pad-list-digits">PAD_LIST_DIGITS</a></td><td>-- space to leave for digits in a digit-enumerated list</td> +</tr> +</table> + +<table class="quick-ref"> +<tr> +<th id="qr-15" class="quick-ref" colspan="2" >+++ Colour</th> +</tr> +<tr> +<td><a href="color.html#newcolor">NEWCOLOR</a></td><td>-- initialize (define) a colour</td> +</tr> +<tr> +<td><a href="color.html#color">COLOR</a></td><td>-- begin using an initialized colour</td> +</tr> +<tr> +<td><a href="color.htmlxcolor">XCOLOR</a></td><td>-- initialize a "named" X colour</td> +</tr> +<tr> +<td><a href="color.html#color-inline">\*[<colorname>]</a></td><td>-- begin using an initialized colour inline</td> +</tr> +</table> + +<table class="quick-ref"> +<tr> +<th id="qr-16" class="quick-ref" colspan="2" >+++ Dropcaps</th> +</tr> +<tr> +<td><a href="goodies.html#dropcap">DROPCAP</a></td><td>-- set a dropcap</td> +</tr> +<tr> +<td><a href="goodies.html#dropcap-family">DROPCAP_FAMILY</a></td><td>-- set a dropcap’s family</td> +</tr> +<tr> +<td><a href="goodies.html#dropcap-font">DROPCAP_FONT</a></td><td>-- set a dropcap’s font style</td> +</tr> +<tr> +<td><a href="goodies.html#dropcap-color">DROPCAP_COLOR</a></td><td>-- set a dropcap’s colour</td> +</tr> +<tr> +<td><a href="goodies.html#dropcap-adjust">DROPCAP_ADJUST</a></td><td>-- adjust size of a dropcap</td> +</tr> +<tr> +<td><a href="goodies.html#dropcap-gutter">DROPCAP_GUTTER</a></td><td>-- adjust space between a dropcap and regular text</td> +</tr> +</table> + +<table class="quick-ref"> +<tr> +<th id="qr-17" class="quick-ref" colspan="2" >+++ Utilities</th> +</tr> +<tr> +<td><a href="goodies.html#alias">ALIAS</a></td><td>-- give a macro a new name</td> +</tr> +<tr> +<td><a href="goodies.html#caps">CAPS</a></td><td>-- set type all caps</td> +</tr> +<tr> +<td><a href="goodies.html#silent">COMMENT</a></td><td>-- silently embed comments in a document</td> +</tr> +<tr> +<td><a href="goodies.html#esc-char">ESC_CHAR</a></td><td>-- change the default escape character</td> +</tr> +<tr> +<td><a href="goodies.html#leader">\*[LEADER]</a></td><td>-- insert leaders at the end of a line</td> +</tr> +<tr> +<td><a href="goodies.html#leader-character">LEADER_CHARACTER</a></td><td>-- change the character used for leaders</td> +</tr> +<tr> +<td><a href="typesetting.html#newpage">NEWPAGE</a></td><td>-- break to a new page</td> +</tr> +<tr> +<td><a href="goodies.html#pad">PAD</a></td><td>-- insert equalized regions of whitespace into a line</td> +</tr> +<tr> +<td><a href="goodies.html#pad-marker">PAD_MARKER</a></td><td>-- change the pad marker</td> +</tr> +<tr> +<td><a href="inlines.html#inline-rule-mom">\*[RULE]</a></td><td>-- draw a full measure rule</td> +</tr> +<tr> +<td><a href="goodies.html#sizespecs">SIZESPECS</a></td><td>-- get font's cap-height, x-height and descender depth</td> +</tr> +<tr> +<td><a href="goodies.html#silent">SILENT</a></td><td>-- output processing off or on</td> +</tr> +<tr> +<td><a href="goodies.html#trap">TRAP</a></td><td>-- enable or disable page position traps</td> +</tr> +</table> + +<table class="quick-ref"> +<tr> +<th id="qr-18" class="quick-ref" colspan="2" >+++ Graphical objects</th> +</tr> +<tr> +<td><a href="graphical.html#drh">DRH</a></td><td>-- draw a horizontal rule</td> +</tr> +<tr> +<td><a href="graphical.html#drv">DRV</a></td><td>-- draw a vertical rule</td> +</tr> +<tr> +<td><a href="graphical.html#dbx">DBX</a></td><td>-- draw a box</td> +</tr> +<tr> +<td><a href="graphical.html#dcl">DCL</a></td><td>-- draw a circle (ellipse)</td> +</tr> +<tr> +<td><a href="inlines.html#rule-weight">RULE_WEIGHT</a></td><td>-- set weight of rules drawn with \*[RULE]</td> +</tr> +<tr> +<td><a href="docelement.html#pspic">PSPIC</a></td><td>-- insert a PostScript image</td> +</tr> +</table> + +<div style="display: inline-block; margin-top: 1em; margin-bottom: .5em; border-bottom: 2px solid #302419;"><kbd>DOCUMENT PROCESSING MACROS</kbd></div> + +<table class="quick-ref"> +<tr> +<th id="qr-19" class="quick-ref" colspan="2" >+++ Reference macros</th> +</tr> +<tr> +<td><a href="docprocessing.html#title">TITLE</a></td><td>-- document title</td> +</tr> +<tr> +<td><a href="docprocessing.html#doctitle">DOCTITLE</a></td><td>-- overall document title (if different from TITLE)</td> +</tr> +<tr> +<td><a href="docelement.html#endnote-title">ENDNOTE_TITLE</a></td><td>-- document/chapter identification string for endnotes</td> +</tr> +<tr> +<td><a href="docprocessing.html#chapter">CHAPTER</a></td><td>-- chapter number</td> +</tr> +<tr> +<td><a href="docprocessing.html#chapter">CHAPTER_TITLE</a></td><td>-- chapter title</td> +</tr> +<tr> +<td><a href="docprocessing.html#draft-string">CHAPTER_STRING</a></td><td>-- what to use in place of “Chapter”</td> +</tr> +<tr> +<td><a href="docprocessing.html#subtitle">SUBTITLE</a></td><td>-- document subtitle</td> +</tr> +<tr> +<td><a href="docprocessing.html#author">AUTHOR</a></td><td>-- document author(s)</td> +</tr> +<tr> +<td><a href="docprocessing.html#covertitle">DOC_COVERTITLE</a></td><td>-- document title cover</td> +</tr> +<tr> +<td><a href="docprocessing.html#covertitle">COVERTITLE</a></td><td>-- section cover title</td> +</tr> +<tr> +<td><a href="docprocessing.html#covertitle">COPYRIGHT</a></td><td>-- copyright</td> +</tr> +<tr> +<td><a href="docprocessing.html#covertitle">MISC</a></td><td>-- miscellaneous cover information</td> +</tr> +<tr> +<td><a href="docprocessing.html#draft">DRAFT</a></td><td>-- document’s draft number</td> +</tr> +<tr> +<td><a href="docprocessing.html#draft-string">DRAFT_STRING</a></td><td>-- what to use in place of “Draft”</td> +</tr> +<tr> +<td><a href="docprocessing.html#revision">REVISION</a></td><td>-- document’s revision number</td> +</tr> +<tr> +<td><a href="docprocessing.html#revision-string">REVISION_STRING</a></td><td>-- what to use in place of “Revision”</td> +</tr> +</table> + +<table class="quick-ref"> +<tr> +<th id="qr-20" class="quick-ref" colspan="2" >+++ General document formatting directives</th> +</tr> +<tr> +<td><a href="docprocessing.html#doctype">DOCTYPE</a></td><td>-- general document type</td> +</tr> +<tr> +<td><a href="docprocessing.html#copystyle">COPYSTYLE</a></td><td>-- draft or final copy</td> +</tr> +<tr> +<td><a href="docprocessing.html#printstyle">PRINTSTYLE</a></td><td>-- typeset or “typewritten”</td> +</tr> +</table> + +<table class="quick-ref"> +<tr> +<th id="qr-21" class="quick-ref" colspan="2" >+++ Line numbering</th> +</tr> +<tr> +<td><a href="docelement.html#number-lines">NUMBER_LINES</a></td><td>-- automatic line numbering on or off</td> +</tr> +<tr> +<td><a href="docelement.html#number-lines-control">Control macros</a></td> +</tr> +<tr> +<td><a href="docelement.html#number-quote-lines"> NUMBER_QUOTE_LINES</a></td><td>-- numbering of QUOTE lines on or off</td> +</tr> +<tr> +<td><a href="docelement.html#number-blockquote-lines"> NUMBER_BLOCKQUOTE_LINES</a></td><td>-- numbering of BLOCKQUOTE lines on or off</td> +</tr> +</table> + +<table class="quick-ref"> +<tr> +<th id="qr-22" class="quick-ref" colspan="2" >+++ Set documents in columns</th> +</tr> +<tr> +<td><a href="docprocessing.html#columns">COLUMNS</a></td> +</tr> +<tr> +<td><a href="docprocessing.html#col-next">COL_NEXT</a></td> +</tr> +<tr> +<td><a href="docprocessing.html#col-break">COL_BREAK</a></td> +</tr> +</table> + +<table class="quick-ref"> +<tr> +<th id="qr-23" class="quick-ref" colspan="2" >+++ TYPEWRITE control macros</th> +</tr> +<tr> +<td><a href="docprocessing.html#typewrite-control">UNDERLINE_ITALIC</a></td><td>-- underlining of italics on</td> +</tr> +<tr> +<td><a href="docprocessing.html#underline-quotes">UNDERLINE_QUOTES</a></td><td>-- underlining of QUOTEs on or off</td> +</tr> +<tr> +<td><a href="docprocessing.html#typewrite-control">ITALIC_MEANS_ITALIC</a></td><td>-- use real italics (not underlining)</td> +</tr> +<tr> +<td><a href="docprocessing.html#typewrite-control">UNDERLINE_SLANT</a></td><td>-- underlining of pseudo-italics on</td> +</tr> +<tr> +<td><a href="docprocessing.html#typewrite-control">SLANT_MEANS_SLANT</a></td><td>-- use pseudo italics (not underlining)</td> +</tr> +</table> + +<table class="quick-ref"> +<tr> +<th id="qr-24" class="quick-ref" colspan="2" >+++ Initiate document processing</th> +</tr> +<tr> +<td><a href="docprocessing.html#start">START</a></td><td>-- begin document processing</td> +</tr> +</table> + +<table class="quick-ref"> +<tr> +<th id="qr-25" class="quick-ref" colspan="2" >+++ Epigraphs</th> +</tr> +<tr> +<td><a href="docelement.html#epigraph">EPIGRAPH</a></td><td>-- set an epigraph underneath the docheader</td> +</tr> +<tr> +<td><a href="docelement.html#epigraph-control">Control macros</a></td><td>-- change default style of epigraphs</td> +</tr> +</table> + +<table class="quick-ref"> +<tr> +<th id="qr-26" class="quick-ref" colspan="2" >+++ Main heads</th> +</tr> +<tr> +<td><a href="docelement.html#head">HEAD</a></td><td>-- set a main head</td> +</tr> +<tr> +<td><a href="docelement.html#head-general">Control macros</a></td><td>-- change default style of heads</td> +</tr> +<tr> +<td><a href="docelement.html#head-space"> HEAD_SPACE</a></td><td>-- control vertical space around heads</td> +</tr> +<tr> +<td><a href="docelement.html#number-heads"> NUMBER_HEADS</a></td><td>-- number heads</td> +</tr> +<tr> +<td><a href="docelement.html#prefix-chapter-number"> PREFIX_CHAPTER_NUMBER</a></td><td>-- prefix chapter number to head numbers</td> +</tr> +<tr> +<td><a href="docelement.html#reset-head-number"> RESET_HEAD_NUMBER</a></td><td>-- reset head number to "1"</td> +</tr> +</table> + +<table class="quick-ref"> +<tr> +<th id="qr-27" class="quick-ref" colspan="2" >+++ Subheads</th> +</tr> +<tr> +<td><a href="docelement.html#subhead">SUBHEAD</a></td><td>-- set a subhead</td> +</tr> +<tr> +<td><a href="docelement.html#subhead-general">Control macros</a></td><td>-- change default style of subheads</td> +</tr> +<tr> +<td><a href="docelement.html#number-subheads"> NUMBER_SUBHEADS</a></td><td>-- number subheads</td> +</tr> +<tr> +<td><a href="docelement.html#prefix-chapter-number"> PREFIX_CHAPTER_NUMBER</a></td><td>-- prefix chapter number to subhead numbers</td> +</tr> +<tr> +<td><a href="docelement.html#reset-subhead-number"> RESET_SUBHEAD_NUMBER</a></td><td>-- reset subhead number to "1"</td> +</tr> +</table> + +<table class="quick-ref"> +<tr> +<th id="qr-28" class="quick-ref" colspan="2" >+++ Paragraph heads</th> +</tr> +<tr> +<td><a href="docelement.html#parahead">PARAHEAD</a></td><td>-- set a paragraph head</td> +</tr> +<tr> +<td><a href="docelement.html#parahead-general">Control macros</a></td><td>-- change default style of paraheads</td> +</tr> +<tr> +<td><a href="docelement.html#number-paraheads"> NUMBER_PARAHEADS</a></td><td>-- number paraheads</td> +</tr> +<tr> +<td><a href="docelement.html#prefix-chapter-number"> PREFIX_CHAPTER_NUMBER</a></td><td>-- prefix chapter number to parahead numbers</td> +</tr> +<tr> +<td><a href="docelement.html#reset-parahead-number"> RESET_PARAHEAD_NUMBER</a></td><td>-- reset parahead number to "1"</td> +</tr> +</table> + +<table class="quick-ref"> +<tr> +<th id="qr-29" class="quick-ref" colspan="2" >+++ Paragraphs</th> +</tr> +<tr> +<td><a href="docelement.html#pp">PP</a></td><td>-- set a paragraph</td> +</tr> +<tr> +<td><a href="docelement.html#pp-control">Control macros</a></td><td>-- managing paragraph style concerns</td> +</tr> +<tr> +<td><a href="docelement.html#pp-font"> PP_FONT</a></td><td>-- globally change font of regular paragraphs</td> +</tr> +<tr> +<td><a href="docelement.html#para-indent"> PARA_INDENT</a></td><td>-- set the paragraph first-line indent</td> +</tr> +<tr> +<td><a href="docelement.html#indent-first-paras"> INDENT_FIRST_PARAS</a></td><td>-- indenting of paragraph first-lines on or off</td> +</tr> +<tr> +<td><a href="docelement.html#pp-space"> PARA_SPACE</a></td><td>-- linespace between paragraphs on or off</td> +</tr> +</table> + +<table class="quick-ref"> +<tr> +<th id="qr-30" class="quick-ref" colspan="2" >+++ Quotes (line for line verbatim quotes)</th> +</tr> +<tr> +<td><a href="docelement.html#quote">QUOTE</a></td><td>-- set quoted text line for line </td> +</tr> +<tr> +<td><a href="docelement.html#quote-general">Control macros</a></td><td>-- change default style of quotes</td> +</tr> +<tr> +<td><a href="docelement.html#always-fullspace-quotes"> ALWAYS_FULLSPACE_QUOTES</a></td><td>-- control vertical space around quotes</td> +</tr> +<tr> +<td><a href="docelement.html#break-quote"> BREAK_QUOTE</a></td><td>-- deprecated</td> +</tr> +</table> + +<table class="quick-ref"> +<tr> +<th id="qr-31" class="quick-ref" colspan="2" >+++ Blockquotes (cited passages of text)</th> +</tr> +<tr> +<td><a href="docelement.html#blockquote">BLOCKQUOTE</a></td><td>-- set longer passages of cited text</td> +</tr> +<tr> +<td><a href="docelement.html#blockquote-general">Control macros</a></td><td>-- change default style of blockquotes</td> +</tr> +<tr> +<td><a href="docelement.html#always-fullspace-quotes"> ALWAYS_FULLSPACE_BLOCKQUOTES</a></td><td>-- control vertical space around quotes</td> +</tr> +<tr> +<td><a href="docelement.html#break-quote"> BREAK_BLOCKQUOTE</a></td><td>-- deprecated</td> +</tr> +</table> + +<table class="quick-ref"> +<tr> +<th id="qr-32" class="quick-ref" colspan="2" >+++ Code snippets</th> +</tr> +<tr> +<td><a href="docelement.html#code">CODE</a></td><td>-- set a code snippet</td> +</tr> +<tr> +<td><a href="docelement.html#code-control">Control macros</a></td><td>-- change default style of code snippets</td> +</tr> +<tr> +<td><a href="docelement.html#code-general"> General</a></td><td>-- family, font, and colour</td> +</tr> +<tr> +<td><a href="docelement.html#code-size"> CODE_SIZE</a></td><td>-- code size as a percentage of prevailing text</td> +</tr> +</table> + +<table class="quick-ref"> +<tr> +<th id="qr-33" class="quick-ref" colspan="2" >+++ Author linebreaks (section breaks)</th> +</tr> +<tr> +<td><a href="docelement.html#linebreak">LINEBREAK</a></td><td>-- insert an author linebreak (section break)</td> +</tr> +<tr> +<td><a href="docelement.html#linebreak-control">Control macros</a></td><td>-- change default style of linebreaks</td> +</tr> +<tr> +<td><a href="docelement.html#linebreak-char"> LINEBREAK_CHAR</a></td><td>-- character to use for author linebreaks</td> +</tr> +<tr> +<td><a href="docelement.html#linebreak-color"> LINEBREAK_COLOR</a></td><td>-- colour of author linebreak character</td> +</tr> +</table> + +<table class="quick-ref"> +<tr> +<th id="qr-34" class="quick-ref" colspan="2" >+++ Document termination string</th> +</tr> +<tr> +<td><a href="docelement.html#finis">FINIS</a></td><td>-- insert a document termination string (e.g. --END--)</td> +</tr> +<tr> +<td><a href="docelement.html#finis-control">Control macros</a></td><td>-- change default style finis string</td> +</tr> +<tr> +<td><a href="docelement.html#finis-string"> FINIS_STRING</a></td><td>-- set the document termination string</td> +</tr> +<tr> +<td><a href="docelement.html#finis-color"> FINIS_COLOR</a></td><td>-- set the document termination string colour</td> +</tr> +</table> + +<table class="quick-ref"> +<tr> +<th id="qr-35" class="quick-ref" colspan="2" >+++ Footnotes</th> +</tr> +<tr> +<td><a href="docelement.html#footnote">FOOTNOTE</a></td><td>-- set a footnote</td> +</tr> +<tr> +<td><a href="docelement.html#footnote-general">Control macros</a></td><td>-- change default style of footnotes</td> +</tr> +<tr> +<td><a href="docelement.html#footnote-markers"> FOOTNOTE_MARKERS</a></td><td>-- footnote markers on or off</td> +</tr> +<tr> +<td><a href="docelement.html#footnote-marker-style"> FOOTNOTE_MARKER_STYLE</a></td><td>-- type of footnote marker to use</td> +</tr> +<tr> +<td><a href="docelement.html#reset-footnote-number"> RESET_FOOTNOTE_NUMBER</a></td><td>-- reset footnote numbering</td> +</tr> +<tr> +<td><a href="docelement.html#footnote-rule"> FOOTNOTE_RULE</a></td><td>-- footnote separator rule on or off</td> +</tr> +<tr> +<td><a href="docelement.html#footnote-rule-adj"> FOOTNOTE_RULE_ADJ</a></td><td>-- adjust vertical position of footnote rule</td> +</tr> +<tr> +<td><a href="docelement.html#footnote-rule-length"> FOOTNOTE_RULE_LENGTH</a></td><td>-- adjust length of footnote rule</td> +</tr> +<tr> +<td style="vertical-align: top;"><a href="docelement.html#footnotes-run-on"> FOOTNOTES_RUN_ON</a></td> + <td>-- instruct footnotes to be continuous (i.e. not to<br /> + begin on a new line; only for use with footnotes<br /> + identified by document line number)</td> +</tr> +</table> + +<table class="quick-ref"> +<tr> +<th id="qr-36" class="quick-ref" colspan="2" >+++ Endnotes</th> +</tr> +<tr> +<td><a href="docelement.html#endnote">ENDNOTE</a></td><td>-- set an endnote</td> +</tr> +<tr> +<td style="vertical-align: top;"><a href="docelement.html#EN-mark">\*[EN-MARK]</a></td> + <td>-- mark initial line of a range of line numbers<br /> + (for use with line numbered endnotes)</td> +</tr> +<tr> +<td><a href="docelement.html#endnotes">ENDNOTES</a></td><td>-- output endnotes</td> +</tr> +<tr> +<td><a href="docelement.html#endnote-control">Control macros</a></td><td>-- change just about anything to do with endnotes</td> +</tr> +</table> + +<table class="quick-ref" style="margin-top: -.5em; margin-left: 1em;"> +<tr> +<td><a href="docelement.html#endnotes-general">General style control</a></td> +</tr> +<tr> +<td><a href="docelement.html#endnotes-pagination">Pagination</a></td> +</tr> +<tr> +<td><a href="docelement.html#endnotes-header-control">Header/footer control</a></td> +</tr> +<tr> +<td><a href="docelement.html#endnotes-main-title">Title control</a></td> +</tr> +<tr> +<td><a href="docelement.html#endnotes-main-title">Document/section identification control</a></td> +</tr> +<tr> +<td><a href="docelement.html#endnotes-numbering">Identification style</a></td> +</tr> +</table> + +<table class="quick-ref"> +<tr> +<th id="qr-37" class="quick-ref" colspan="2" >+++ Margin notes</th> +</tr> +<tr> +<td><a href="docelement.html#mn-init">MN_INIT</a></td><td>-- initialize margin notes</td> +</tr> +<tr> +<td><a href="docelement.html#mn">MN</a></td><td>-- set a margin note</td> +</tr> +</table> + +<table class="quick-ref"> +<tr> +<th id="qr-38" class="quick-ref" colspan="2" >+++ Bibliographic references</th> +</tr> +<tr> +<td><a href="refer.html#ref">REF</a></td><td>-- begin a reference</td> +</tr> +<tr> +<td><a href="refer.html#footnote-refs">FOOTNOTE_REFS</a></td><td>-- place references in footnotes</td> +</tr> +<tr> +<td><a href="refer.html#endnote-refs">ENDNOTE_REFS</a></td><td>-- place references in endnotes</td> +</tr> +<tr> +<td><a href="refer.html#bracket-refs">REF( / REF)</a></td><td>-- put parentheses around embedded references</td> +</tr> +<tr> +<td><a href="refer.html#bracket-refs">REF[ / REF]</a></td><td>-- put square brackets around embedded references</td> +</tr> +<tr> +<td><a href="refer.html#bracket-refs">REF{ / REF}</a></td><td>-- put curly braces around mbedded references</td> +</tr> +<tr> +<td><a href="refer.html#bibliography">BIBLIOGRAPHY</a></td><td>-- output a bibliography</td> +</tr> +<tr> +<td><a href="refer.html#biblio-control">Control macros</a></td><td>-- change just about anything to do with bibliographies</td> +</tr> +</table> + +<table class="quick-ref" style="margin-top: -.5em; margin-left: 1em;"> +<tr> +<td><a href="refer.html#bibliography-type">BIBLIOGRAPHY_TYPE</a> -- "plain" or enumerated list</td> +</tr> +<tr> +<td><a href="refer.html#biblio-general">General style control</a></td> +</tr> +<tr> +<td><a href="refer.html#biblio-header-control">Header/footer control</a></td> +</tr> +<tr> +<td><a href="refer.html#biblio-main-title">Main head control</a></td> +</tr> +</table> + +<table class="quick-ref"> +<tr> +<th id="qr-39" class="quick-ref" colspan="2" >+++ Tables of contents</th> +</tr> +<tr> +<td><a href="docelement.html#toc">TOC</a></td><td>-- output a table of contents</td> +</tr> +<tr> +<td><a href="docelement.html#toc-control">Control macros</a></td><td>-- change just about anything to do with tables of contents</td> +</tr> +</table> + +<table class="quick-ref" style="margin-top: -.5em; margin-left: 1em;"> +<tr> +<td><a href="docelement.html#toc-general">General style control</a></td> +</tr> +<tr> +<td><a href="docelement.html#toc-pagenumbering">Page numbering</a></td> +</tr> +<tr> +<td><a href="docelement.html#toc-header">Title control</a></td> +</tr> +<tr> +<td><a href="docelement.html#toc-style">Changing the style of the different table of contents entry types</a></td> +</tr> +<tr> +<td><a href="docelement.html#toc-additional">Additional table of contents control macros</a></td> +</tr> +</table> + +<table class="quick-ref"> +<tr> +<th id="qr-40" class="quick-ref" colspan="2" >+++ Letter (correspondence) macros</th> +</tr> +<tr> +<td><a href="letters.html#date">DATE</a></td><td>-- letter’s date</td> +</tr> +<tr> +<td><a href="letters.html#from">FROM</a></td><td>-- letter’s addresser</td> +</tr> +<tr> +<td><a href="letters.html#to">TO</a></td><td>-- letter’s addressee</td> +</tr> +<tr> +<td><a href="letters.html#greeting">GREETING</a></td><td>-- letter’s salutation</td> +</tr> +<tr> +<td><a href="letters.html#closing">CLOSING</a></td><td>-- letter’s closing salutation</td> +</tr> +<tr> +<td><a href="letters.html#closing-indent">CLOSING_INDENT</a></td><td>-- indentation of the closing salutation</td> +</tr> +<tr> +<td><a href="letters.html#signature-space">SIGNATURE_SPACE</a></td><td>-- room to leave for the signature</td> +</tr> +<tr> +<td><a href="letters.html#no-suite">NO_SUITE</a></td><td>-- printing of "next page number" off or on</td> +</tr> +</table> + +<table class="quick-ref"> +<tr> +<th id="qr-41" class="quick-ref" colspan="2" >+++ Changing global print style parameters after START</th> +</tr> +<tr> +<td><a href="docprocessing.html#doc-left-margin">DOC_LEFT_MARGIN</a></td><td>-- left margin of everything on the page</td> +</tr> +<tr> +<td><a href="docprocessing.html#doc-right-margin">DOC_RIGHT_MARGIN</a></td><td>-- right margin of everything on the page</td> +</tr> +<tr> +<td><a href="docprocessing.html#doc-line-length">DOC_LINE_LENGTH</a></td><td>-- document’s base line length</td> +</tr> +<tr> +<td><a href="docprocessing.html#doc-family">DOC_FAMILY</a></td><td>-- document’s base family</td> +</tr> +<tr> +<td><a href="docprocessing.html#doc-pt-size">DOC_PT_SIZE</a></td><td>-- document’s base point size</td> +</tr> +<tr> +<td><a href="docprocessing.html#doc-lead">DOC_LEAD</a></td><td>-- document’s base lead</td> +</tr> +<tr> +<td><a href="docprocessing.html#doc-quad">DOC_QUAD</a></td><td>-- document’s base quad directions</td> +</tr> +</table> + +<table class="quick-ref"> +<tr> +<th id="qr-42" class="quick-ref" colspan="2" >+++ Managing a document’s first-page header</th> +</tr> +<tr> +<td><a href="docprocessing.html#docheader">DOCHEADER</a></td><td>-- document first-page header on or off</td> +</tr> +<tr> +<td><a href="docprocessing.html#docheader-control-index">Control macros</a></td><td>-- change default style of docheader elements</td> +</tr> +</table> + +<table class="quick-ref"> +<tr> +<th id="qr-43" class="quick-ref" colspan="2" >+++ Managing page headers and footers</th> +</tr> +<tr> +<td><a href="headfootpage.html#headers">HEADERS</a></td><td>-- page headers on or off</td> +</tr> +<tr> +<td><a href="headfootpage.html#footers">FOOTERS</a></td><td>-- page footers on or off</td> +</tr> +<tr> +<td style="vertical-align: top;"><a href="headfootpage.html#headers-and-footers">HEADERS_AND_FOOTERS</a></td><td>-- enable generation of both headers and footers</td> +</tr> +<tr> +<td><a href="headfootpage.html#index-reference">Control macros</a></td> +</tr> +</table> + +<table class="quick-ref" style="margin-top: -.5em; margin-left: 1em;"> +<tr> +<td><a href="headfootpage.html#strings">Strings</a></td><td>-- left-right-center strings</td> +</tr> +<tr> +<td><a href="headfootpage.html#style">Style</a></td><td>-- change style defaults for headers and/or footers</td> +</tr> +<tr> +<td><a href="headfootpage.html#global">Global</a></td><td>-- global style changes</td> +</tr> +<tr> +<td><a href="headfootpage.html#part-by-part">Part-by-part</a></td><td>-- part-by-part style changes</td> +</tr> +<tr> +<td><a href="headfootpage.html#vertical">Vertical placement</a></td><td>-- adjust postion of headers and/or footers</td> +</tr> +<tr> +<td><a href="headfootpage.html#separator-rule">Separator rule</a></td><td>-- manage the header/footer separator rule</td> +</tr> +</table> + +<table class="quick-ref"> +<tr> +<th id="qr-44" class="quick-ref" colspan="2" >+++ Recto/verso page headers and footers</th> +</tr> +<tr> +<td><a href="rectoverso.html#recto-verso">RECTO_VERSO</a></td><td>-- recto/verso headers and/or footers on or off</td> +</tr> +<tr> +<td><a href="rectoverso.html#switch-hdrftr">SWITCH_HEADERS</a></td><td>-- switch recto or verso header</td> +</tr> +<tr> +<td><a href="rectoverso.html#switch-hdrftr">SWITCH_FOOTERS</a></td><td>-- switch recto or verso footer</td> +</tr> +<tr> +<td><a href="headfootpage.html#hdrftr-rectoverso">HEADER_RECTO</a></td><td>-- string that constitutes a recto header</td> +</tr> +<tr> +<td><a href="headfootpage.html#hdrftr-rectoverso">HEADER_VERSO</a></td><td>-- string that constitutes a verso header</td> +</tr> +<tr> +<td><a href="headfootpage.html#hdrftr-rectoverso">FOOTER_RECTO</a></td><td>-- string that constitutes a recto footer</td> +</tr> +<tr> +<td><a href="headfootpage.html#hdrftr-rectoverso">FOOTER_VERSO</a></td><td>-- string that constitutes a recto footer</td> +</tr> +</table> + +<table class="quick-ref"> +<tr> +<th id="qr-45" class="quick-ref" colspan="2" >+++ Pagination</th> +</tr> +<tr> +<td><a href="headfootpage.html#paginate">PAGINATE</a></td><td>-- pagination on or off</td> +</tr> +<tr> +<td><a href="headfootpage.html#paginate-control">Control macros</a></td><td>-- change default style for pagination</td> +</tr> +<tr> +<td><a href="headfootpage.html#pagenumber"> PAGENUMBER</a></td><td>-- user-defined (starting) page number</td> +</tr> +<tr> +<td><a href="headfootpage.html#pagenum-style"> PAGENUM_STYLE</a></td><td>-- digits, roman numerals, etc</td> +</tr> +<tr> +<td><a href="headfootpage.html#pagenum-on-first-page"> PAGENUM_ON_FIRST_PAGE</a></td><td>-- when footers are enabled</td> +</tr> +<tr> +<td style="vertical-align: top;"><a href="headfootpage.html#draft-with-pagenumber"> DRAFT_WITH_PAGENUMBER</a></td><td>-- attach draft/revision information to page<br /> + numbers</td> +</tr> +</table> + +<table class="quick-ref"> +<tr> +<th id="qr-46" class="quick-ref" colspan="2" >+++ Document and section cover (title) pages</th> +</tr> +<tr> +<td><a href="cover.html#cover">COVER</a></td><td>-- information to include in a section cover</td> +</tr> +<tr> +<td><a href="cover.html#cover">DOC_COVER</a></td><td>-- information to include in a document cover</td> +</tr> +<tr> +<td><a href="cover.html#on-off">COVERS</a></td><td>-- printing of section covers on or off</td> +</tr> +<tr> +<td><a href="cover.html#on-off">DOC_COVERS</a></td><td>-- printing of document covers on or off</td> +</tr> +<tr> +<td><a href="cover.html#cover-control-index">Control macros</a></td><td>-- change style defaults for covers</td> +</tr> +</table> + +<table class="quick-ref"> +<tr> +<th id="qr-47" class="quick-ref" colspan="2" >+++ Utilities</th> +</tr> +<tr> +<td><a href="docprocessing.html#add-space">ADD_SPACE</a></td><td>-- add space to the top of a page</td> +</tr> +<tr> +<td><a href="docelement.html#blank-page">BLANKPAGE</a></td><td>-- output one or more blank pages</td> +</tr> +<tr> +<td><a href="docprocessing.html#doc-lead-adjust">DOC_LEAD_ADJUST</a></td><td>-- adjust document linespacing (lead) to fill pages</td> +</tr> +<tr> +<td><a href="rectoverso.html#collate">COLLATE</a></td><td>-- join documents or chapters of a document together</td> +</tr> +<tr> +<td><a href="docprocessing.html#shim">SHIM</a></td><td>-- move vertical position to next valid baseline</td> +</tr> +</table> + +<div class="rule-long"><hr/></div> + +<!-- Navigation links --> +<table style="width: 100%; margin-top: 12px;"> +<tr> + <td style="width: 33%;"><a href="toc.html">Back to Table of Contents</a></td> + <td style="width: 33%; text-align: center;"><a href="#top">Top</a></td> + <td style="width: 33%; text-align: right;"><a href="appendices.html">Next: Appendices</a></td> +</tr> +</table> + +</div> + +<div class="bottom-spacer"><br/></div> + +</body> +</html> +<!-- vim: fileencoding=utf-8: nomodified: --> 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 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- +This file is part of groff, the GNU roff type-setting system. + +Copyright (C) 2004, 2005, 2006, 2009, 2010 Free Software Foundation, Inc. +Written by Peter Schaffter. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with the +Invariant Sections being this comment section, with no Front-Cover +Texts, and with no Back-Cover Texts. + +A copy of the Free Documentation License is included as a file called +FDL in the main directory of the groff source package. +--> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"> + +<head> + <meta http-equiv="content-type" content="text/html;charset=utf-8"/> + <title>Mom -- Recto/verso printing, collating</title> + <link rel="stylesheet" type="text/css" href="stylesheet.css" /> +</head> + +<body style="background-color: #f5faff;"> + +<!-- ==================================================================== --> + +<div id="top" class="page"> + +<!-- Navigation links --> +<table style="width: 100%;"> +<tr> + <td><a href="toc.html">Back to Table of Contents</a></td> + <td style="text-align: right;"><a href="cover.html#top">Next: Cover pages</a></td> +</tr> +</table> + +<h1 class="docs">Recto/verso printing, collating</h1> + +<div style="width: 37%; margin: auto;"> +<ul class="no-enumerator" style="margin-left: -1em;"> + <li><a href="#rectoverso-intro">Introduction to recto/verso printing</a> + <ul style="margin-left: -.5em; list-style-type: disc;"> + <li><a href="#rectoverso-list">Macro list</a></li> + </ul></li> + <li><a href="#collate-intro">Introduction to collating</a> + <ul style="margin-left: -.5em; list-style-type: disc;"> + <li><a href="#collate">The COLLATE macro</a></li> + </ul></li> +</ul> +</div> + +<div class="rule-medium"><hr/></div> + +<h2 id="rectoverso-intro" class="docs">Introduction to recto/verso printing</h2> + +<p> +Recto/verso printing allows you to set up a mom document in such +a way that it can be printed on both sides of a printer sheet and +subsequently bound. +</p> + +<p> +With recto/verso, mom automatically takes control of the following +aspects of alternating page layout: +</p> +<ul style="margin-top: -.5em; margin-left: -.5em; margin-bottom: -.5em;"> + <li>switching left and right margins (if they’re not equal)</li> + <li>switching the left and right parts of the default 3-part + <a href="definitions.html#header">headers</a> + or + <a href="definitions.html#footer">footers</a> + (see the + <a href="headfootpage.html#description-general">General description of headers</a>) + </li> + <li>switching + <a href="headfootpage.html#hdrftr-rectoverso">HEADER_RECTO</a> + and + <a href="headfootpage.html#hdrftr-rectoverso">HEADER_VERSO</a> + if user-defined, single string recto/verso headers + or footers are used in place of the default 3-part + headers or footers + </li> + <li>switching the page number position (if page numbers are not centred)</li> +</ul> + +<p> +It is beyond the scope of this documentation to cover the different +ways in which you can make your printer print on both sides of +a sheet. A simple but effective method for those of us with +“dumb” printers is to open the document (after +it’s been processed into PostScript by groff—see +<a href="using.html#using-invoking">How to invoke groff with mom</a>) +in <b>gv</b> (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 <b>gv</b> print the “even pages“. If you +prefer to work from the command line, check out the man pages for +<kbd>pstops</kbd> and <kbd>psbook</kbd>. There are other programs +out there as well to help with two-sided printing. +</p> + +<div class="macro-list-container"> +<h3 id="rectoverso-list" class="macro-list">Recto/verso macros</h3> +<ul class="macro-list"> + <li><a href="#recto-verso">RECTO_VERSO</a></li> + <li><a href="#switch-hdrftr">SWITCH_HEADERS (also FOOTERS)</a> + – switch starting position of the header parts (left and right) + </li> +</ul> +</div> + +<!-- -RECTO_VERSO- --> + +<div id="recto-verso" class="box-macro-args"> +Macro: <b>RECTO_VERSO</b> +</div> + +<p> +If you want mom to set up alternating pages for recto/verso +printing, simply invoke RECTO_VERSO, with no argument, anywhere in +your document (most likely before +<a href="docprocessing.html#start">START</a>). +</p> + +<div class="box-tip"> +<p class="tip-top"> +<span class="note">Note:</span> +Recto/verso always switches the left and right parts of +<a href="definitions.html#header">headers</a> +or +<a href="definitions.html#footer">footers</a> +on odd/even pages. However, it only switches the left and right +margins if the margins aren’t equal. Consequently, it is +your responsibility to set the appropriate differing left and right +margins with +<a href="typesetting.html#l-margin">L_MARGIN</a> +and +<a href="typesetting.html#r-margin">R_MARGIN</a> +(prior to +<a href="docprocessing.html#start">START</a>) +or with +<a href="docprocessing.html#doc-left-margin">DOC_LEFT_MARGIN</a> +and +<a href="docprocessing.html#doc-right-margin">DOC_RIGHT_MARGIN</a> +(before or after START). +</p> + +<p class="tip-bottom"> +Equally, recto/verso only switches the page number position if page +numbers aren’t centred, which means you have to set the page +number position with +<a href="headfootpage.html#pagenum-pos">PAGENUM_POS</a> +(before or after START). +</p> +</div> + +<!-- -SWITCH_HDRFTR- --> + +<div id="switch-hdrftr" class="box-macro-args" style="margin-top: 1em;"> +Macro: <b>SWITCH_HEADERS</b> +</div> + +<p> +SWITCH_HEADERS switches the location of the header left string +(by default, the author) and the header right string (by default, +the document title). If you don’t like mom’s default +placement of author and title, use SWITCH_HEADERS to reverse it. +</p> + +<p> +SWITCH_HEADERS can also be useful in conjunction with +<a href="#recto-verso">RECTO_VERSO</a>. +The assumption of RECTO_VERSO is that the first page of a document +(i.e. recto/odd) represents the norm for header-left and header-right, +meaning that the second (and all subsequent verso/even) pages of the +document will reverse the order of header-left and header-right. +</p> + +<p> +If mom’s behaviour in this matter is not what you want, simply +invoke SWITCH_HEADERS on the first page of your recto/verso document +to reverse her default treatment of header parts. The remainder of +your document (with respect to headers) will come out as you want. +</p> + +<div class="rule-medium"><hr/></div> + +<!-- ===================================================================== --> + +<h2 id="collate-intro" class="docs">Introduction to collating</h2> + +<p> +Many people wisely keep chapters of a long work in separate +files, previewing or printing them as needed during the draft +phase. However, when it comes to the final version, mom requires +a single, collated file in order to keep track of page numbering +and recto/verso administration, generating tables of contents and +endnotes, ensuring that +<a href="definitions.html#docheader">docheaders</a> +get printed correctly, and a host of other details. +</p> + +<p> +The COLLATE macro, which can be used with any +<a href="docprocessing.html#doctype">DOCTYPE</a> +except <kbd>LETTER</kbd>, lets you glue mom-formatted text files +together. You need only concatenate chapters into a single file +(most likely with the <kbd>cat</kbd> command), put <kbd>.COLLATE</kbd> at the end of each +concatenated chapter, follow it with the +<a href="docprocessing.html#reference-macros">reference macros</a> +needed for the new chapter, e.g. +<a href="docprocessing.html#chapter">CHAPTER</a> +or +<a href="docprocessing.html#chapter-string">CHAPTER_STRING</a>, +make any pertinent style changes to the upcoming chapter (unlikely, +but possible), and re-invoke the +<a href="docprocessing.html#start">START</a> +macro. (Most likely, the reference macros and <kbd>.START</kbd> are +already there.) Each chapter will begin on a fresh page and behave +as expected. +</p> + +<p> +Even if you always work with monolithic, multi-chapter files, every +chapter and its associated reference macros plus <kbd>.START</kbd> +still needs to be preceded by a <kbd>.COLLATE</kbd> command. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +COLLATE assumes you are collating documents/files with similar +type-style parameters hence there’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. +</p> +</div> + +<div class="box-tip"> +<p id="caution" class="tip"> +<b>Two words of caution:</b> +</p> +<ol style="margin-top: -1.25em; margin-left: -1.25em; padding-bottom: .5em;"> + <li>Do not collate documents of differing + PRINTSTYLES (i.e. don’t try to + collate a <kbd>TYPESET</kbd> document and <kbd>TYPEWRITE</kbd> + document). + </li> + <li>Use <kbd>.DOC_FAMILY</kbd> instead of + <kbd>.FAMILY</kbd> if, for some reason, you want to + change the family of all the document elements after + <kbd>.COLLATE</kbd>. <kbd>.FAMILY</kbd>, by itself, will + change the family of paragraph text only. + </li> +</ol> +</div> + +<!-- -COLLATE- --> + +<div class="macro-id-overline"> +<h3 id="collate" class="macro-id">collate</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>COLLATE</b> +</div> + +<p> +The most basic (and most likely) collating situation looks like +this: +<br/> +<span class="pre-in-pp"> + .COLLATE + .CHAPTER 17 + .START +</span> +</p> + +<p> +A slightly more complex version of the same thing, for chapters +that require their own titles, looks like this: +<br/> +<span class="pre-in-pp"> + .COLLATE + .CHAPTER_TITLE "Geek Fatigue: Symptoms and Causes" + .START +</span> +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="tip">Tip:</span> +If the last +<a href="definitions.html#outputline">output line</a> +of a document before COLLATE falls too close to the bottom margin +for running text, mom may output a blank page with only a header +or footer between collated documents. In order to avoid this, I +recommend always preceding COLLATE with +<kbd><a href="typesetting.html#el">.EL</a></kbd>, +like this +<br/> +<span class="pre-in-pp"> + .EL + .COLLATE +</span> +</p> +</div> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +See the +<a href="#caution">two words of caution</a>, +above. +</p> +</div> + +<div class="rule-long"><hr/></div> + +<!-- Navigation links --> +<table style="width: 100%; margin-top: 12px;"> +<tr> + <td style="width: 33%;"><a href="toc.html">Back to Table of Contents</a></td> + <td style="width: 33%; text-align: center;"><a href="#top">Top</a></td> + <td style="width: 33%; text-align: right;"><a href="cover.html">Next: Cover pages</a></td> +</tr> +</table> + +</div> + +<div class="bottom-spacer"><br/></div> + +</body> +</html> +<!-- vim: fileencoding=utf-8: nomodified: --> 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 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- +This file is part of groff, the GNU roff type-setting system. + +Copyright (C) 2004, 2005, 2006, 2009, 2010 Free Software Foundation, Inc. +Written by Peter Schaffter. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with the +Invariant Sections being this comment section, with no Front-Cover +Texts, and with no Back-Cover Texts. + +A copy of the Free Documentation License is included as a file called +FDL in the main directory of the groff source package. +--> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"> + +<head> + <meta http-equiv="content-type" content="text/html;charset=utf-8"/> + <title>Mom -- Document processing, bibliographies and references</title> + <link rel="stylesheet" type="text/css" href="stylesheet.css" /> +</head> + +<body style="background-color: #f5faff;"> + +<!-- ==================================================================== --> + +<div id="top" class="page"> + +<!-- Navigation links --> +<table style="width: 100%;"> +<tr> + <td><a href="toc.html">Back to Table of Contents</a></td> + <td style="text-align: right;"><a href="letters.html#top">Next: Writing letters</a></td> +</tr> +</table> + +<h1 class="docs">Bibliographies and references</h1> + +<div style="width: 53%; margin: auto;"> +<ul class="no-enumerator"> + <li><a href="#intro-ref">Introduction to bibliographies and references</a></li> + <li><a href="#tutorial-ref">Tutorial – using mom with <kbd>refer</kbd></a> + <ul style="margin-left: -.5em; list-style-type: disc;"> + <li><a href="#db-ref">Creating a <kbd>refer</kbd> database</a></li> + <li><a href="#rcommands-ref">Required <kbd>refer</kbd> commands</a></li> + <li><a href="#accessing-ref">Accessing references in your documents</a></li> + <li><a href="#where-ref">Telling mom where to put references</a></li> + <li><a href="#biblio-ref">Creating bibliography pages</a></li> + <li><a href="#invoking-ref">Invoking groff with mom and <kbd>refer</kbd></a></li> + </ul></li> + <li><a href="#index-ref">Bibliography and reference macros</a> + <ul style="margin-left: -.5em; list-style-type: disc;"> + <li><a href="#biblio-control">Bibliography control macros and defaults</a></li> + </ul></li> +</ul> +</div> + +<div class="rule-medium"><hr/></div> + +<h2 id="intro-ref" class="docs">Introduction to bibliographies and references</h2> + +<p> +Mom provides the ability to automatically format and generate +bibliography pages, as well as footnote or endnote references, or +references embedded in the text. She accomplishes this by working +in conjunction with a special groff program called +<kbd>refer</kbd>. +</p> + +<p> +<kbd>refer</kbd> is, in groff-speak, a pre-processor, which is to +say that it scans your files, looking for very specific control +lines (i.e. lines that begin with a dot, the same way macros do). +If <kbd>refer</kbd> doesn't find them, it can’t do it’s +job and neither can mom. The scanning is done before any other +document processing. +</p> + +<p> +<kbd>refer</kbd> is a program that’s been around for a +long time. It’s powerful and has many, many features. +Unfortunately, the manpage (<kbd>man refer</kbd>), 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.) +</p> + +<p> +In order to get mom users up and running with <kbd>refer</kbd>, +this section of mom’s documentation focuses exclusively, in a +recipe-like manner, on what you need to know to use <kbd>refer</kbd> +satisfactorily in conjunction with mom. The information and +instructions are not to be taken as a manual or tutorial on full +<kbd>refer</kbd> usage. Much has been left out, on purpose. +</p> + +<p> +If you’re already a <kbd>refer</kbd> user, the information +herein will be useful for adapting your current <kbd>refer</kbd> +usage to mom’s way of doing things. If you’ve never +used <kbd>refer</kbd>, the information is essential, and, in many +cases, may be all you need. +</p> + +<p> +(For the benefit of old groff-hands: <kbd>refer</kbd> +support in mom is heavily based on the +<kbd>refer</kbd> module of the “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.) +</p> + +<p> +<kbd>refer</kbd> requires first that you create a +bibliographic database. From the information contained in the +database, mom formats and generates bibliographies +and references in MLA (Modern Language Association) style. MLA +style is clean, contemporary and flexible, and is widely used in the +humanities, where the range of material that has to be referenced +can run from simple books to live interviews and film. +</p> + +<p> +Once you have created your database, you instruct <kbd>refer</kbd> +(and mom) to access entries in it by supplying keywords associated +with the entries. Depending on what you’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. +</p> + +<p> +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 +<br/> +<span class="pre-in-pp"> + http://www.aresearchguide.com/12biblio.html +</span> +or any other website or reference book on MLA style. +</p> + +<div class="rule-short"><hr/></div> + +<div class="examples-container" style="margin-top: 1.5em; margin-bottom: 1.5em;"> +<h3 id="tutorial-ref" class="docs">Tutorial – Using <kbd style="font-style: normal; text-transform: none;">refer</kbd> with mom</h3> +<ol style="margin-top: 1em; margin-left: -1em; margin-bottom: -.5em;"> + <li><a href="#db-ref">Creating a <kbd>refer</kbd> database</a> + <ul style="margin-left: -.5em"> + <li><a href="#example-refer-database">Example <kbd>refer</kbd> database</a></li> + <li><a href="#field-identifiers">Meanings of the field identifiers (<kbd>%A</kbd>, <kbd>%T</kbd>, etc.)</a></li> + </ul></li> + <li><a href="#rcommands-ref">Required <kbd>refer</kbd> commands</a> + <ul style="margin-left: -.5em"> + <li><a href="#refer-block1">Required <kbd>refer</kbd> block (embedded references)</a></li> + <li><a href="#refer-block2">Required <kbd>refer</kbd> block (bibliographies)</a></li> + </ul></li> + <li><a href="#accessing-ref">Accessing references in your documents</a></li> + <li><a href="#where-ref">Telling mom where to put references</a></li> + <li><a href="#biblio-ref">Creating bibliography pages</a></li> + <li><a href="#invoking-ref">Invoking groff with mom and <kbd>refer</kbd></a></li> +</ol> + +<h4 id="db-ref" class="docs">1. Creating a refer database</h4> + +<p> +The first step in using <kbd>refer</kbd> with mom is setting +up your bibliographic database. The database is a text file +containing entries for each reference you want to access from your +mom files. The file is <i>not</i> a “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. +</p> + +<p> +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. <kbd>%A</kbd> or <kbd>%T</kbd>. The letter identifies +what part of a bibliographic entry the field refers to: Author, +Title, Publisher, Date, etc. After the field identifier comes +a single space, followed by the information appropriate to +field. No punctuation should go at the ends of fields; mom adds +what’s correct automatically. Do note, however, that +author(s) (<kbd>%A</kbd>) requires that you enter the author +information exactly as you wish it to come out (minus the period), +including the comma after the first author’s last name. +</p> + +<p> +Here’s an example database containing two records so you can +visualize what the above paragraph says. +</p> + +<div id="example-refer-database" class="examples" style="margin-top: -.5em;">Example <kbd>refer</kbd> database</div> +<div class="examples-container" style="padding-bottom: 1em;"> +<span class="pre"> +%A Schweitzer, Albert +%A C.M. Widor +%T J.S. Bach +%l Ernest Newman +%V Vol 2 +%C London +%I Adam and Charles Black +%D 1923 +%O 2 vols +%K bach vol 2 + +%A Schaffter, Peter +%T The Schumann Proof +%C Toronto +%I RendezVous Press +%D 2004 +%K schumann schaffter +</span> +</div> + +<p> +The order in which you enter fields doesn’t matter. mom +and <kbd>refer</kbd> will re-arrange them in the correct order +for you. The meaning of the letters follows. There are, with +<kbd>refer</kbd>, quite a few—all uppercase — which +have, over time, come to be standard. Mom respects these. However, +she adds to the list (mostly using lowercase letters). +</p> + +<div id="field-identifiers" class="examples" style="margin-top: -.5em;">Meanings of the field identifiers</div> +<div class="examples-container" style="padding-bottom: 1em;"> +<span class="pre"> +%A Author – 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 +</span> +</div> + +<div id="ref-disc-hy" class="box-tip"> +<p class="tip-top"> +<span class="tip">Tip:</span> +If you have automatic hyphenation enabled in your document (you +probably do), mom will hyphenate your references. This can be a +problem because references typically contain several proper names, +which shouldn’t be hyphenated. The solution is to prepend to +any proper name in your <kbd>refer</kbd> database the groff +<a href="definitions.html#discretionaryhyphen">discretionary hyphen</a> +character, <kbd>\%</kbd>, like this: +<br/> +<span class="pre-in-pp"> + %A Hill, \%Reginald +</span> +</p> + +<p class="tip-bottom" style="margin-top: -1.5em;"> +Alternatively, you can turn hyphenation off entirely in references +with the macro, +<kbd><a href="#hyphenate-refs">HYPHENATE_REFS</a></kbd> <kbd>OFF</kbd>. +</p> +</div> + +<h4 id="rcommands-ref" class="docs">2. Required <kbd>refer</kbd> commands</h4> + +<p> +Having set up your database, you now need to put some +<kbd>refer</kbd>-specific commands at the top of your mom file. You +cannot skip this step, nor can you source these commands with the +groff +<a href="definitions.html#primitives">primitive</a>, +<kbd>.so</kbd> or the mom macro, +<kbd><a href="docprocessing.html#include">.INCLUDE</a></kbd>. +They <span style="font-weight: bold; font-style: italic;">must</span> +appear, exactly as shown, at the top of every file containing +references that need to be pre-processed with <kbd>refer</kbd>. +</p> + +<p> +<kbd>refer</kbd> commands are introduced by a single +line containing <kbd>.R1</kbd>, and concluded with a single line +containing <kbd>.R2</kbd>. What you put between the <kbd>.R1</kbd> +and <kbd>.R2</kbd> lines are the commands themselves. The commands +should be entered one per line, in lowercase letters, <i>with +no initial period (dot)</i>. +</p> + +<p> +Here’s an example: +<br/> +<span class="pre-in-pp"> + .R1 + no-label-in-text + no-label-in-reference + .R2 +</span> +There are an awful lot of <kbd>refer</kbd> commands. We will focus +only on those required to get mom cooperating with <kbd>refer</kbd>. +If you’re interested, study the <kbd>refer</kbd> manpage to +discover what other commands are available and how to manipulate +them. +</p> + +<p> +At a minimum, all mom files accessing a bibliographic database must +contain the following <kbd>refer</kbd> commands, exactly as shown: +</p> + +<div id="refer-block1" class="examples" style="margin-top: -.5em;">Required <kbd>refer</kbd> block (embedded references)</div> +<div class="examples-container" style="padding-bottom: 1em;"> +<span class="pre"> +.R1 +no-label-in-text +no-label-in-reference +join-authors ", and " ", " ", and " +database <full path to the database> +.R2 +</span> +</div> + +<p> +The first two commands tell <kbd>refer</kbd> to let mom handle +everything associated with footnote and endnote markers, both in the +body of the document, and in the footnotes/endnotes themselves. +</p> + +<p> +The third command is required for mom to handle multiple authors in +proper MLA style. +</p> + +<p> +The last command, <kbd>database</kbd>, assumes you have created +your own database, and do not otherwise have a system-wide +default database. +<kbd><full path to the database></kbd> +means the full path <i>including</i> the filename, e.g. +<kbd>/home/user/refer/my-database.</kbd> +</p> + +<p> If you’re already a <kbd>refer</kbd> user, feel free to +enter whatever <kbd>refer</kbd> commands are necessary to +access the database(s) you want. +</p> + +<p> +With the above <kbd>refer</kbd> block, you can embed references +directly into the text of your document, or have them output as +footnotes or endnotes. If, on the other hand, you want to collect +references for output in a bibliography, the block must read: +</p> + +<div id="refer-block2" class="examples" style="margin-top: -.5em;">Required <kbd>refer</kbd> block (bibliographies)</div> +<div class="examples-container" style="padding-bottom: 1em;"> +<span class="pre"> +.R1 +no-label-in-text +no-label-in-reference +join-authors ", and " ", " ", and " +database <full path to the database> +sort +accumulate +.R2 +</span> +</div> + +<h4 id="accessing-ref" class="docs">3. Accessing references in your documents</h4> + +<p> +References are accessed by putting keywords, all on one line, +between the <kbd>refer</kbd> commands, <kbd>.[</kbd> (dot +left-bracket) and <kbd>.]</kbd> (dot right-bracket). Both commands +must appear on separate lines, by themselves, like this: +<br/> +<span class="pre-in-pp"> + .[ + keyword(s) + .] +</span> +Keywords are any word, or set of words, that identify a database +record (i.e. a reference) unambiguously. (<kbd>refer</kbd> +doesn’t like ambiguity.) +</p> + +<p> +If, for example, you want to reference a book by Ray Bradbury, +and the database contains only one book by Bradbury, a suitable +keyword would be “Bradbury”. If your database contains +several books by Bradbury, say, <i>Fahrenheit 451</i> and <i>The +Martian Chronicles</i>, 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 <i>The +Martian Mission</i>, suitable keywords to reference <i>The Martian +Chronicles</i> might be: +<br/> +<span class="pre-in-pp"> + .[ or .[ or .[ + Bradbury Martian Bradbury Chronicles Martian Chronicles + .] .] .] +</span> +</p> + +<p> +A special database field identifier, <kbd>%K</kbd>, lets you create +unique keywords for references. This can be very handy if you need +both a “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: +<br/> +<span class="pre-in-pp"> + %A Isherwood, Christopher %A Isherwood + %T Mr. Norris Changes Trains %T Mr. Norris Changes Trains + %d 1935 %K Nor short + %t The Last of Mr. \%Norris + %a Intro. Tom Crawford + %C New York + %I New Directions + %D 1945 + %K Norris +</span> +To access the shorter reference, you’d do +<br/> +<span class="pre-in-pp"> + .[ + Nor short + .] +</span> +To access the longer one, you’d do +<br/> +<span class="pre-in-pp"> + .[ + Norris + .] +</span> +</p> + +<h4 id="where-ref" class="docs">4. Telling mom where to put references</h4> + +<p> +Mom provides several mechanisms for outputting references where you +want: +</p> +<ul style="margin-top: -.5em; margin-left: -.5em; margin-bottom: -.75em;"> + <li><a href="#embedded">embedded in the body of the document</a></li> + <li><a href="#foot-end">in footnotes or endnotes</a> + <ul style="margin-left: -.5em;"> + <li><a href="#footnotes-recipe">recipe for references in footnotes</a></li> + <li><a href="#endnotes-recipe">recipe for references in endnotes</a></li> + </ul></li> + <li><a href="#bibliographies">collected in a bibliography</a></li> +</ul> + +<h5 id="embedded" class="docs" style="text-transform: none; margin-bottom: -1em;">Embedding references in the document body</h5> + +<p> +References may be embedded in the document body, surrounded by +parentheses, square brackets, or braces. Use whichever you prefer, +following the recipes below. +<br/> +<span class="pre-in-pp"> + Parentheses | Square brackets | Braces + =========== | =============== | ====== + .REF( | .REF[ | .REF{ + .[ | .[ | .[ + keyword(s) | keyword(s) | keyword(s) + .] | .] | .] + .REF) | .REF] | .REF} +</span> +</p> + +<h5 id="foot-end" class="docs" style="text-transform: none; margin-top: -1em; margin-bottom: -1em;">Footnote or endnote references</h5> + +<p> +Most times, you’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 +<kbd><a href="#footnote-refs">.FOOTNOTE_REFS</a></kbd> +or +<kbd><a href="#endnote-refs">.ENDNOTE_REFS</a></kbd>. +Afterwards, you enclose the <kbd>refer</kbd> commands, <kbd>.[</kbd> +and <kbd>.]</kbd>, with the mom macro, +<a href="#ref">REF</a>. +Depending on which was the last invoked, <kbd>.FOOTNOTE_REFS</kbd> or +<kbd>.ENDNOTE_REFS</kbd>, references will either go into footnotes or be +collected for output as endnotes. +</p> + +<p> +The innate flexibility of this scheme allows you to have both +footnote references and endnote references in the same document. +This would be desirable if, say, you wanted truncated +references in footnotes, and full references in endnotes. +</p> + +<p id="footnotes-recipe"> +A recipe for footnoted references looks like this:<br/> +<span class="pre-in-pp"> + .FOOTNOTE_REFS \"Can be placed anywhere in the file prior to .REF + .REF + .[ + keyword(s) + .] + .REF +</span> +The reference between the first and second <kbd>.REF</kbd> will be +treated as a footnote, as will all subsequent <kbd>.REF</kbd> pairs +unless you invoke the macro, <kbd>.ENDNOTE_REFS</kbd>. +There’s no need to repeat <kbd>.FOOTNOTE_REFS</kbd> if all +your references are going into footnotes. +</p> + +<div class="box-important"> +<p class="tip"> +<span class="important">Important:</span> +When FOOTNOTE_REFS are enabled, REF behaves identically to +<a href="docelement.html#footnote">FOOTNOTE</a> +with respect to the use of the <kbd>\c</kbd> inline escape. Please +read the +<a href="docelement.html#footnote-note">HYPER IMPORTANT NOTE</a> +found in the document entry for FOOTNOTE. +</p> +</div> + +<p id="endnotes-recipe"> +A recipe for endnote references looks like this: +<br/> +<span class="pre-in-pp"> + .ENDNOTE_REFS \"Can be placed anywhere in the file prior to .REF + .REF + .[ + keyword(s) + .] + .REF +</span> +The reference between the first and second <kbd>.REF</kbd> will +be treated as an endnote, as will all subsequent <kbd>.REF</kbd> +pairs unless you invoke the macro, <kbd>.FOOTNOTE_REFS</kbd>. +There’s no need to repeat <kbd>.ENDNOTE_REFS</kbd> if all your +references are going into endnotes. +</p> + +<div class="box-important"> +<p class="tip"> +<span class="important">Important:</span> +When ENDNOTE_REFS are enabled, REF behaves identically to +<a href="docelement.html#footnote">ENDNOTE</a> +with respect to the use of the <kbd>\c</kbd> inline escape. Please +read the +<a href="docelement.html#endnote-note">HYPER IMPORTANT NOTE</a> +found in the document entry for ENDNOTE. +</p> +</div> + +<h5 id="bibliographies" class="docs" style="text-transform: none; margin-bottom: -1em;">Collected references (bibliographies)</h5> + +<p> +Sometimes, you may want to embed references in input text near the +sections of text to which they pertain, but not have them output +until later (typically, on a bibliography page). REF is used for +this, too, but you have to make sure your <kbd>refer</kbd> commands +block is set up properly at the top of your text file. The recipe +for this is: +<br/> +<span id="refer-block3" class="pre-in-pp"> + .R1 + no-label-in-text + no-label-in-reference + join-authors ", and " ", " ", and " + database <full path to the database> + sort + accumulate + .R2 +</span> +After this set up, and provided you don’t issue a +<kbd>.FOOTNOTE_REFS</kbd> or <kbd>.ENDNOTE_REFS</kbd> command, all +reference between <kbd>.REF</kbd> pairs will be collected for later +output in a bibliography. +</p> + +<p> +As a precaution, mom will issue a message the first time you call +<kbd>.REF</kbd> if neither FOOTNOTE_REFS nor ENDNOTE_REFS is in +effect. If collected references are what you want, and you have set +up your <kbd>.R1/.R2</kbd> block as above, you may safely ignore +the message. +</p> + +<div id="limitation" class="box-important"> +<p class="tip"> +<span class="important">LIMITATION:</span> You cannot combine +“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 +<kbd>refer</kbd>, not mom. +</p> +</div> + +<h4 id="biblio-ref" class="docs">5. Creating bibliography pages</h4> + +<p> +Bibliographies are processed separately from the main document, like +endnotes. And, like endnotes, just about every element on them can +be designed to your specifications. (See +<a href="#biblio-control">Bibliography control macros and defaults</a>.) +A mom bibliography begins with the macro, +<kbd><a href="#bibliography">BIBLIOGRAPHY</a></kbd>, +like this: +<br/> +<span class="pre-in-pp"> + .BIBLIOGRAPHY +</span> +Following <kbd>.BIBLIOGRAPHY</kbd>, you have three choices of how to +proceed: +</p> + +<ol style="margin-top: -.5em; margin-left: -.5em;"> + <li> + If you have elected to have references collected from within the + body of a document (see above, + <a href="#bibliographies">Collected references [bibliographies]</a>, + for instructions), which assumes you have a <kbd>refer</kbd> + command block like the one + <a href="#refer-block2">here</a> + at the top of your document, you need only do + <br/> + <span class="pre-in-pp"> + .BIBLIOGRAPHY + .[ + $LIST$ + .] + </span></li> + <li style="margin-top: -2em;"> + If you want to create the bibliography by hand (which may be the + case if you’ve used footnote and/or endnote references throughout + your document; see + <a href="#limitation">LIMITATION</a>), + follow this recipe. It assumes you already have a + <kbd>refer</kbd> block like the one + <a href="#refer-block1">here</a> + at the top of your document. + <br/> + <span class="pre-in-pp"> + .BIBLIOGRAPHY + .R1 + sort + accumulate + .R2 + .[ -+ + keyword(s) | + .] | "keyword(s)" are keywords identifying the + .[ | particular bibliographic reference you want + keyword(s) | from your database. Order doesn't matter here; + .] | the refer command, sort, takes care of that. + .[ | + keyword(s) | + .] -+ + .[ + $LIST$ + .] + </span></li> + <li style="margin-top: -2em;"> + Your final choice is to output your whole database. Again, + assuming you have a <kbd>refer</kbd> block like the one + <a href="#refer-block1">here</a> + at the top of your file, you need only do: + <br/> + <span class="pre-in-pp" style="margin-bottom: -2em;"> + .BIBLIOGRAPHY + .R1 + bibliography <full path to database> + .R2 + </span> + If you haven’t put a <kbd>refer</kbd> block in your + file already, you can, in this instance, put one after + <kbd>.BIBLIOGRAPHY</kbd>, like this: + <br/> + <span class="pre-in-pp"> + .BIBLIOGRAPHY + .R1 + join-authors ", and " ", " ", and " + bibliography <full path to database> + .R2 + </span></li> +</ol> + +<p style="margin-top: -3em;"> +Whichever option you choose, mom will output a full bibliography +page, complete with a title (“BIBLIOGRAPHY” by default, +but that can be changed). +</p> + +<h4 id="invoking-ref" class="docs">6. Invoking groff with mom and refer</h4> + +<p> +So, now you’ve got a document formatted properly to use +references processed with <kbd>refer</kbd>, what do you do to output +the document? +</p> + +<p> +It’s simple. Instead of invoking groff with just the +<kbd>-mom</kbd> option, as explained +<a href="using.html#using-invoking">here</a>, +invoke groff with the <kbd>-R</kbd> option as well, like this: +<br/> +<span class="pre-in-pp"> + groff -R -mom filename +</span> +</p> +</div> + +<div class="macro-list-container"> +<h3 id="index-ref" class="macro-list">Bibliography and reference macros</h3> +<ul class="macro-list"> + <li><a href="#ref">REF</a> – begin/end a <kbd>refer</kbd> reference</li> + <li><a href="#footnote-refs">FOOTNOTE_REFS</a> – instruct mom to put REFs in footnotes</li> + <li><a href="#endnote-refs">ENDNOTE_REFS</a> – instruct mom to put REFs in endnotes</li> + <li><a href="#bracket-refs">Embed references in the text</a> + <ul style="margin-left: -.5em;"> + <li><a href="#bracket-refs-parens">REF(</a> – embed a reference in the text between parentheses</li> + <li><a href="#bracket-refs-brackets">REF[</a> – embed a reference in the text between square brackets</li> + <li><a href="#bracket-refs-braces">REF{</a> – embed a reference in the text between braces</li> + </ul></li> + <li><a href="#indent-refs">INDENT_REFS</a> – manage the 2nd line indent of references, per MLA standards</li> + <li><a href="#hyphenate-refs">HYPHENATE_REFS</a> – enable/disable hyphenation of references</li> + <li><a href="#bibliography">BIBLIOGRAPHY</a> – begin a bibliography</li> + <li><a href="#bibliography-type">BIBLIOGRAPHY_TYPE</a> – plain, or numbered list bibliography</li> + <li><a href="#biblio-control">Bibliography control macros and defaults</a></li> +</ul> +</div> + +<!-- -REF- --> + +<div class="macro-id-overline"> +<h3 id="ref" class="macro-id">Begin/end a <kbd style="text-transform: none;">refer</kbd> reference</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>REF</b> +</div> + +<p> +The macro, REF, tells mom that what follows is +<kbd>refer</kbd>-specific, a keyword-identified reference from a +<kbd>refer</kbd> database. Depending on whether you’ve issued +a +<kbd><a href="#footnote-refs">.FOOTNOTE_REFS</a></kbd> +or +<kbd><a href="#endnote-refs">.ENDNOTE_REFS</a></kbd> +instruction, REF also tells mom where to place the reference. If +FOOTNOTE_REFS, the reference will be formatted and placed in a +footnote. If ENDNOTE_REFS, the reference will be collected for +output as an endnote. If you have issued neither instruction, the +reference will be collected for later output, most likely in a +<a href="#bibliography">bibliography</a>. +</p> + +<p> +Before you use REF, you must create a <kbd>refer</kbd> block +containing <kbd>refer</kbd> commands (see +<a href="#rcommands-ref">Required refer commands</a> +in the tutorial, above). +</p> + +<p> +REF usage always looks like this: +<br/> +<span class="pre-in-pp"> + .REF + .[ + keyword(s) + .] + .REF +</span> +Notice that REF “brackets” the <kbd>refer</kbd> instructions, +and never takes an argument. +</p> + +<p> +What REF really is is a convenience. One could, for example, put a +reference in a footnote by doing +<br/> +<span class="pre-in-pp"> + .FOOTNOTE + .[ + keyword(s) + .] + .FOOTNOTE OFF +</span> +However, if you have a lot of references going into footnotes (or +endnotes), it’s much shorter to type <kbd>.REF/.REF</kbd> +than <kbd>.FOOTNOTE/.FOOTNOTE OFF</kbd>. It also helps you +distinguish—visually, in your input file—between +footnotes (or endnotes) which are references, and footnotes (or +endnotes) which are explanatory, or expand on the text. +</p> + +<div class="box-tip"> +<p class="tip-top"> +<span class="note">Note:</span> +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 +<a href="docelement.html#footnote">FOOTNOTE</a>. +</p> + +<p class="tip-bottom"> +<span class="additional-note">Additional note:</span> +When REF is used with +<a href="#footnote-refs">FOOTNOTE_REFS</a> +or +<a href="#endnote-refs">ENDNOTE_REFS</a>, +it behaves identically to +<a href="docelement.html#footnote">FOOTNOTE</a> +or +<a href="docelement.html#footnote">ENDNOTE</a>, +so please read the HYPER IMPORTANT NOTE found in the document entry +for +<a href="docelement.html#footnote-note">FOOTNOTE</a> +and/or +<a href="docelement.html#endnote-note">ENDNOTE</a>. +</p> +</div> + +<!-- -FOOTNOTE_REFS- --> + + +<div class="macro-id-overline"> +<h3 id="footnote-refs" class="macro-id">Instruct mom to put REFs in footnotes</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>FOOTNOTE_REFS</b> +</div> + +<p> +FOOTNOTE_REFS is an instruction to +<a href="#ref">REF</a>, +saying, “put all subsequent references bracketed by the REF +macro into footnotes.” You invoke it by itself, with no +argument. +</p> + +<p> +When FOOTNOTE_REFS is in effect, regular footnotes, (i.e. +those introduced with <kbd>.FOOTNOTE</kbd> and terminated with +<kbd>.FOOTNOTE OFF</kbd>) continue to behave normally. +</p> + +<p> +You may switch between FOOTNOTE_REFS and +<a href="#endnote-refs">ENDNOTE_REFS</a> +at any time. +</p> + +<p> +If you have a lot of footnote references, and are identifying +footnotes by line number rather than by markers in the text, you may +want to enable +<a href="docelement.html#footnotes-run-on">FOOTNOTES_RUN_ON</a> +in conjunctions with FOOTNOTE_REFS. +</p> + +<!-- -ENDNOTE_REFS- --> + +<div class="macro-id-overline"> +<h3 id="endnote-refs" class="macro-id">Instruct REF to put references in endnotes</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>ENDNOTE_REFS</b> +</div> + +<p> +ENDNOTE_REFS is an instruction to +<a href="#ref">REF</a>, +saying, “add all subsequent references bracketed by the REF +macro to endnotes.” You invoke it by itself, with no argument. +</p> + +<p> +When ENDNOTE_REFS is in effect, mom continues to format regular +endnotes, (i.e. those introduced with <kbd>.ENDNOTE</kbd> and +terminated with <kbd>.ENDNOTE OFF</kbd>) in the normal way. +</p> + +<p> +You may switch between ENDNOTE_REFS and +<a href="#footnote-refs">FOOTNOTE_REFS</a> +at any time. +</p> + +<!-- -BRACKET_REFS- --> + +<div class="macro-id-overline"> +<h3 id="bracket-refs" class="macro-id">Embed references in the text</h3> +</div> + +<div id="bracket-refs-parens" class="box-macro-args"> +Macro pair: <b>REF(</b> ... <b>REF)</b> +</div> + +<div id="bracket-refs-brackets" class="box-macro-args" style="margin-top: 1em;"> +Macro pair: <b>REF[</b> ... <b>REF]</b> +</div> + +<div id="bracket-refs-braces" class="box-macro-args" style="margin-top: 1em;"> +Macro pair: <b>REF{</b> ... <b>REF}</b> +</div> + +<p> +You may sometimes want to embed references directly into the +body of your document, typically, but not always, inside +parentheses. Mom makes this possible through the use of the +<b>REF<bracket type></b> macros. +</p> + +<p> +All three macro pairs, above, are invoked the same way, namely +by introducing the reference with the first (“open”) +macro of the <b>REF<bracket type></b> +pair, and terminating it with the second (“close”) +<b>REF<bracket type></b> of the pair. For +example +<br/> +<span class="pre-in-pp"> + .REF( + .[ + keyword(s) + .] + .REF) +</span> +will embed a reference in the body of your document, surrounded +by parentheses. <b>.REF[</b> ... <b>.REF]</b> +will surround the reference with square brackets. +<b>.REF{</b> ... <b>.REF}</b> will surround it with curly +braces. +</p> + +<!-- -INDENT_REFS- --> + +<div class="macro-id-overline"> +<h3 id="indent-refs" class="macro-id">Manage the second-line indent of references, per MLA standards</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>INDENT_REFS</b> <kbd class="macro-args">FOOTNOTE | ENDNOTE | BIBLIO <indent> </kbd> +</div> + +<p class="requires"> +• <kbd style="font-style: normal;"><indent></kbd> requires a <a href="definitions.html#unitofmeasure">unit of measure</a> +</p> + +<p> +Proper MLA-style references should have their second, and subsequent +lines, if any, indented. Since mom formats references in MLA style, +she automatically indents second lines. By default, the indent for +the second line of references, regardless of whether the references +appear in footnotes, endnotes, or bibliographies, is 1.5 +<a href="definitions.html#em">ems</a> +for +<a href="docprocessing.html#printstyle">PRINSTYLE <kbd>TYPESET</kbd></a> +and 2 ems for +<a href="docprocessing.html#printstyle">PRINSTYLE <kbd>TYPEWRITE</kbd></a>. +</p> + +<p> +If you’d like to change the 2nd-line indent for footnotes, +endnotes or bibliographies, just invoke <kbd>.INDENT_REFS</kbd> +with a first argument telling mom for which (footnote, endnote, or +bibliography) you want the indent changed, and a second argument +saying what you’d like the indent to be. For example, if you +want the second-line indent of references on a bibliography page to +be 3 +<a href="definitions.html#picas-points">picas</a>, +<br/> +<span class="pre-in-pp"> + .INDENT_REFS BIBLIO 3P +</span> +is how you’d set it up. +</p> + +<div class="box-tip"> +<p class="tip-top"> +<span class="tip">Tip:</span> +If you are identifying endnotes by line number +(<a href="docelement.html#endnote-marker-style">ENDNOTE_MARKER_STYLE <kbd>LINE</kbd></a>) +and have instructed mom to put references bracketed by +<kbd><a href="#ref">.REF</a></kbd> +into endnotes (with +<a href="#endnote-refs">ENDNOTE_REFS</a>), +you will almost certainly want to adjust the second-line indent for +references in endnotes, owing to the way mom formats line-numbered +endnotes. Study the output of such documents to see whether an +indent adjustment is required. +</p> + +<p> +The same advice applies to references in endnotes when you have enabled +<br/> +<span class="pre-in-pp"> + <a href="docelement.html#endnote-numbers-align-left">.ENDNOTE_NUMBERS_ALIGN_LEFT</a> +</span> +in favour of mom’s default, which is to align them right. +Study the output to determine what size of second-line indent works +best. +</p> + +<p class="tip-bottom"> +<i>(Frankly, endnote references formatted in MLA-style combined with +left-aligned endnote numbers is a no-win situation, and so is best +avoided. Wherever you set the indent, you’ll end up with the +endnote numbers appearing to hang into the left margin, so you might +as well have them hang, as is the case with +<kbd style="font-style: normal;">.ENDNOTE_NUMBERS_ALIGN_RIGHT</kbd>.</i> – Ed.) +</p> +</div> + +<!-- -HYPHENATE_REFS- --> + +<div class="macro-id-overline"> +<h3 id="hyphenate-refs" class="macro-id">Enable/disable hyphenation of references</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>HYPHENATE_REFS</b> <kbd class="macro-args"><toggle></kbd> +</div> + +<p> +If you have hyphenation turned on for a document (see +<a href="typesetting.html#hy">HY</a>), +and in most cases you probably do, mom will hyphenate references +bracketed by the +<a href="#ref">REF</a> +macro. Since references typically contain quite a lot of proper +names, which shouldn’t be hyphenated, you may want to disable +hyphenation for references. +</p> + +<p> +HYPHENATE_REFS is a toggle macro; invoking it by itself will turn +automatic hyphenation of REF-bracketed references on (the default). +Invoking it with any other argument (<kbd>OFF, NO, X</kbd>, etc.) +will disable automatic hyphenation for references bracketed by REF. +</p> + +<p> +An alternative to turning reference hyphenation off is to prepend +to selected proper names in your <kbd>refer</kbd> database +the groff +<a href="definitions.html#discretionaryhyphen">discretionary hyphen</a> +character, <kbd>\%</kbd>. (See +<a href="#ref-disc-hy">here</a> +in the tutorial for an example.) +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +References embedded in the body of a document with +<kbd><a href="#bracket-refs">.REF <bracket type></a></kbd> +are considered part of +<a href="definitions.html#running">running text</a>, +and are hyphenated (or not) according to whether hyphenation is +turned on or off for running text. Therefore, if you want to +disable hyphenation for such references, you must do so temporarily, +with +<a href="typesetting.html#hy">HY</a>, +like this: +<br/> +<span class="pre-in-pp"> + .HY OFF + .REF( + .[ + keyword(s) + .] + .REF) + .HY +</span> +Alternatively, sprinkle your database fields liberally with +<kbd>\%</kbd>. +</p> +</div> + +<!-- -BIBLIOGRAPHY- --> + +<div class="macro-id-overline"> +<h3 id="bibliography" class="macro-id">Begin a bibliography</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>BIBLIOGRAPHY</b> +</div> + +<p> +If you want to append a bibliography to your document, all you need +do is invoke <kbd>.BIBLIOGRAPHY</kbd> at the place you want it. +<kbd>.BIBLIOGRAPHY</kbd> breaks to a new page, prints the title +(BIBLIOGRAPHY by default, but that can be changed), and awaits +<kbd>refer</kbd> instructions. How to create bibliographies is +covered in the tutorial section, +<a href="#biblio-ref">Creating bibliography pages</a>. +</p> + +<p> +See the +<a href="#biblio-control">Bibliography control macros and defaults</a> +for macros to tweak, design and control the appearance of +bibliography pages. +</p> + +<!-- -BIBLIOGRAPHY_TYPE- --> + +<div class="macro-id-overline"> +<h3 id="bibliography-type" class="macro-id">Plain, or numbered list bibliography</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>BIBLIOGRAPHY_TYPE</b> <kbd class="macro-args">PLAIN | LIST [ <list separator> ] [ <list prefix> ]</kbd> +</div> + +<p> +Mom offers two styles of bibliography output: plain, or numbered +list style. With the argument, <kbd>PLAIN</kbd>, bibliography entries are output +with no enumerators. With the argument, <kbd>LIST</kbd>, each entry is numbered. +</p> + +<p> +The two optional arguments, <kbd><list separator></kbd> +and <kbd><list prefix></kbd> have the same meaning as the +equivalent arguments to +<a href="docelement.html#list">LIST</a> +(i.e. <kbd><separator></kbd> and <kbd><prefix></kbd>). +</p> + +<p> +You may enter the BIBLIOGRAPHY_TYPE either before or after +<kbd>.BIBLIOGRAPHY</kbd>. It must, however, always come before +the <kbd>refer</kbd> command to output bibliographies. (See the +tutorial section, +<a href="#biblio-ref">Creating bibliography pages</a>, +for instructions on how to output bibliographies.) +</p> + +<p> +Mom’s default BIBLIOGRAPHY_TYPE is LIST, with a period (dot) +as the separator, and no prefix. +</p> + +<!-- -BIBLIO_CONTROL- --> + +<div class="defaults-container" style="background-color: #ded4bd; border: none;"> +<h3 id="biblio-control" class="docs defaults">Bibliography control macros and defaults</h3> + +<p style="margin-top: .25em; margin-left: 9px;"> +Mom processes bibliography pages in a manner very similar to the +way she processes endnotes pages. The bibliography page control +macros, therefore, behave in the same way as their endnotes pages +equivalents. +</p> + +<ol style="margin-top: -.5em; padding-bottom: .5em;"> + <li><a href="#biblio-general"><b>General bibliography style control</b></a> + <ul style="margin-left: -.5em;"> + <li><a href="#biblio-style">Base family/font/quad</a></li> + <li><a href="#biblio-pt-size">Base point size</a></li> + <li><a href="#biblio-lead">Leading</a></li> + <li><a href="#biblio-spacing">Adjust the space between bibliography entries</a></li> + <li><a href="#singlespace-biblio">Singlespace bibliographies (for TYPEWRITE only)</a></li> + <li><a href="#biblio-no-columns">Turning off column mode during bibliography output</a></li> + </ul></li> + <li><a href="#biblio-pagination"><b>Pagination of bibliographies</b></a> + <ul style="margin-left: -.5em;"> + <li><a href="#biblio-pagenum-style">Page numbering style</a></li> + <li><a href="#biblio-first-pagenumber">Setting the first page number of bibliographies</a></li> + <li><a href="#biblio-no-first-pagenum">Omitting a page number on the first page of bibliographies</a></li> + <li><a href="#suspend-pagination">Suspending pagination during bibliography output</a></li> + </ul></li> + <li><a href="#biblio-header-control"><b>Header/footer control</b></a> + <ul style="margin-left: -.5em;"> + <li><a href="#biblio-modify-hdrftr">Modifying what goes in bibliography headers/footers</a></li> + <li><a href="#biblio-hdrftr-center">Header/footer centre string when doctype is CHAPTER</a></li> + <li><a href="#biblio-allows-headers">Allow headers on bibliography pages</a></li> + </ul></li> + <li><a href="#biblio-main-title"><b>Bibliography first-page title control</b></a> + <ul> + <li><a href="#biblio-string">Title string</a></li> + <li><a href="#biblio-string-control">Title string control macros and defaults</a></li> + <li><a href="#biblio-string-placement">Title string placement</a></li> + <li><a href="#biblio-string-underline">Title string underscoring</a></li> + <li><a href="#biblio-string-caps">Title string capitalization</a></li> + </ul></li> +</ol> +</div> + +<h4 id="biblio-general" class="docs" style="margin-top: -1.5em; margin-bottom: .5em;">1. General bibliography page style control</h4> + +<h5 id="biblio-style" class="docs" style="margin-top: 0; margin-bottom: .5em; margin-left: .5em;">• Base family/font/quad</h5> + +<div class="defaults-container" style="padding-bottom: 8px;"> +<p class="defaults" style="padding-top: 6px;"> +See +<a href="#control-macro-args">Arguments to the control macros</a>. +</p> +<span class="pre defaults"> +.BIBLIOGRAPHY_FAMILY default = prevailing document family; default is Times Roman +.BIBLIOGRAPHY_FONT default = roman +.BIBLIOGRAPHY_QUAD* default = justified + +*Note: BIBLIOGRAPHY_QUAD must be set to either L (LEFT) or J (JUSTIFIED); + R (RIGHT) and C (CENTER) will not work. +</span> +</div> + +<!-- -BIBLIO_PT_SIZE- --> + +<h5 id="biblio-pt-size" class="docs" style="margin-top: -1.5em; margin-bottom: .5em; margin-left: .5em;">• Base point size</h5> + +<div class="box-macro-args"> +Macro: <b>BIBLIOGRAPHY_PT_SIZE</b> <kbd class="macro-args"><base type size of bibliography></kbd> +</div> + +<p> +Unlike most other control macros that deal with size of document +elements, BIBLIOGRAPHY_PT_SIZE takes as its argument an absolute +value, relative to nothing. Therefore, the argument represents the +size of bibliography type in +<a href="definitions.html#picaspoints">points</a>, +unless you append an alternative +<a href="definitions.html#unitofmeasure">unit of measure</a>. +For example, +<br/> +<span class="pre-in-pp"> + .BIBLIOGRAPHY_PT_SIZE 12 +</span> +sets the base point size of type on the bibliography page to 12 +points, whereas +<br/> +<span class="pre-in-pp"> + .BIBLIOGRAPHY_PT_SIZE .6i +</span> +sets the base point size of type on the bibliography page to 1/6 of an +inch. +</p> + +<p> +The type size set with BIBLIOGRAPHY_PT_SIZE is the size of type used +for the text of the bibliographies, and forms the basis from which +the point size of other bibliography page elements is calculated. +</p> + +<p> +The default for +<a href="docprocessing.html#printstyle">PRINTSTYLE <kbd>TYPESET</kbd></a> +is 12.5 points (the same default size used in the body of the +document). +</p> + +<!-- -BIBLIO_LEAD- --> + +<h5 id="biblio-lead" class="docs" style="margin-top: -.5em; margin-bottom: .5em; margin-left: .5em;">• Leading</h5> + +<div class="box-macro-args"> +Macro: <b>BIBLIOGRAPHY_LEAD</b> <kbd class="macro-args"><base leading of bibliographies> [ ADJUST ]</kbd> +</div> + +<p class="requires"> +• Does not require a <a href="definitions.html#unitofmeasure">unit of measure</a>; points is assumed +</p> + +<p> +Unlike most other control macros that deal with leading of document +elements, BIBLIOGRAPHY_LEAD takes as its argument an absolute value, +relative to nothing. Therefore, the argument represents the +<a href="definitions.html#leading">leading</a> +of bibliographies in +<a href="definitions.html#picaspoints">points</a> +unless you append an alternative +<a href="definitions.html#unitofmeasure">unit of measure</a>. +For example, +<br/> +<span class="pre-in-pp"> + .BIBLIOGRAPHY_LEAD 14 +</span> +sets the base leading of type on the bibliography page to 14 +points, whereas +<br/> +<span class="pre-in-pp"> + .BIBLIOGRAPHY_LEAD .5i +</span> +sets the base leading of type on the bibliography page to 1/2 inch. +</p> + +<p> +If you want the leading of bibliographies adjusted to fill the page, +pass BIBLIOGRAPHY_LEAD the optional argument, +<kbd>ADJUST</kbd>. (See +<a href="docprocessing.html#doc-lead-adjust">DOC_LEAD_ADJUST</a> +for an explanation of leading adjustment.) +</p> + +<p> +The default for +<a href="docprocessing.html#printstyle">PRINTSTYLE <kbd>TYPESET</kbd></a> +is 14 points, adjusted. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +Even if you give mom a <kbd>.DOC_LEAD_ADJUST OFF</kbd> command, +she will still, by default, adjust bibliography leading. You +<i>must</i> enter <kbd>BIBLIOGRAPHY_LEAD <lead></kbd> +with no <kbd>ADJUST</kbd> argument to disable this default +behaviour. +</p> +</div> + +<!-- -BIBLIO_SPACING- --> + +<h5 id="biblio-spacing" class="docs" style="margin-top: -.5em; margin-bottom: .5em; margin-left: .5em;">• Adjust the space between bibliography entries</h5> + +<div class="box-macro-args"> +Macro: <b>BIBLIOGRAPHY_SPACING</b> <kbd class="macro-args"><amount of space> </kbd> +</div> + +<p class="requires"> +• Requires a <a href="definitions.html#unitofmeasure">unit of measure</a> +</p> + +<p> +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, +<br/> +<span class="pre-in-pp"> + .BIBLIOGRAPHY_SPACING .5v +</span> +would do the trick. +</p> + +Note: +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +As with endnotes pages, owing to the space inserted between +bibliography entries, bibliography pages may have hanging +bottom margins. Unlike endnotes pages, mom +is sad to report that there’s nothing you can do about +this, except a) pray things work out, or b) set your +BIBLIOGRAPHY_SPACING to zero. +</p> +</div> + +<!-- -SINGLESPACE_BIBLIO- --> + +<h5 id="singlespace-biblio" class="docs" style="margin-top: -.5em; margin-bottom: .5em; margin-left: .5em;">• Singlespace bibliography (TYPEWRITE only)</h5> + +<div class="box-macro-args"> +Macro: <b>SINGLESPACE_BIBLIOGRAPHY</b> <kbd class="macro-args"><toggle></kbd> +</div> + +<p> +If your +<a href="docprocessing.html#printstyle">PRINTSTYLE</a> +is <kbd>TYPEWRITE</kbd> and you use TYPEWRITE’s default +double-spacing, bibliographies are double-spaced. If your document +is single-spaced, bibliographies are single-spaced. +</p> + +<p> +If, for some reason, you’d prefer that bibliographies be +single-spaced in an otherwise double-spaced document (including +double-spaced +<a href="rectoverso.html#collate">collated</a> +documents), invoke <kbd>.SINGLESPACE_BIBLIOGRAPHY</kbd> with with no +argument. +</p> + +<!-- -BIBLIO_NO_COLUMNS- --> + +<h5 id="biblio-no-columns" class="docs" style="margin-top: -.5em; margin-bottom: .5em; margin-left: .5em;">• Turning off column mode during bibliography output</h5> + +<div class="box-macro-args"> +Macro: <b>BIBLIOGRAPHY_NO_COLUMNS</b> <kbd class="macro-args"><toggle></kbd> +</div> + +<p> +By default, if your document is set in +<a href="docprocessing.html#columns">columns</a>, +mom sets the bibliographies in columns, too. However, if your +document is set in columns and you’d like the bibliographies +not to be, just invoke <kbd>.BIBLIOGRAPHY_NO_COLUMNS</kbd> with +no argument. The bibliography pages will be set to the full page +measure of your document. +</p> + +<p> +If you output bibliographies at the end of each document in a +<a href="rectoverso.html#collate">collated</a> +document set in columns, column mode will automatically be +reinstated for each document, even with BIBLIOGRAPHY_NO_COLUMNS +turned on. In such circumstances, you must re-enable +ENDNOTES_NO_COLUMNS for each separate collated document. +</p> + +<h4 id="biblio-pagination" class="docs" style="margin-bottom: .5em;">2. Pagination of bibliographies</h4> + +<!-- -BIBLIO_PAGENUM_STYLE- --> + +<h5 id="biblio-pagenum-style" class="docs" style="margin-top: 0; margin-bottom: .5em; margin-left: .5em;">• Page numbering style</h5> + +<div class="box-macro-args"> +Macro: <b>BIBLIOGRAPHY_PAGENUM_STYLE</b> <kbd class="macro-args">DIGIT | ROMAN | roman | ALPHA | alpha</kbd> +</div> + +<p> +Use this macro to set the page numbering style of bibliography +pages. The arguments are identical to those for +<a href="headfootpage.html#pagenum-style">PAGENUM_STYLE</a>. +The default is <kbd>digit</kbd>. You may want to change it to, say, +<kbd>alpha</kbd>, which you would do with +<br/> +<span class="pre-in-pp"> + .BIBLIOGRAPHY_PAGENUM_STYLE alpha +</span> +</p> + +<!-- -BIBLIO_FIRST_PAGENUMBER- --> + +<h5 id="biblio-first-pagenumber" class="docs" style="margin-top: -.5em; margin-bottom: .5em; margin-left: .5em;">• Setting the first page number of bibliographies</h5> + +<div class="box-macro-args"> +Macro: <b>BIBILOGRAPHY_FIRST_PAGENUMBER</b> <kbd class="macro-args"><page # that appears on page 1 of bibliographies></kbd> +</div> + +<p> +Use this macro with caution. If the bibliography for a +<a href="rectoverso.html#collate">collated</a> +document is to be output at the document's end, +BIBLIOGRAPHY_FIRST_PAGENUMBER tells mom what page number to put on +the first page of the bibliography. +</p> + +<p> +However, if you're outputting a bibliography at the end of each +section (chapter, article, etc) of a collated document, +you have to reset every section’s first page number after +<a href="rectoverso.html#collate">COLLATE</a> +and before +<a href="docprocessing.html#start">START</a>. +</p> + +<!-- -BIBLIO_NO_FIRST_PAGENUN- --> + +<h5 id="biblio-no-first-pagenum" class="docs" style="margin-top: -.25em; margin-bottom: .5em; margin-left: .5em;">• Omitting a page number on the first page of bibliographies</h5> + +<div class="box-macro-args"> +Macro: <b>BIBLIOGRAPHY_NO_FIRST_PAGENUM</b> <kbd class="macro-args"><toggle></kbd> +</div> + +<p> +This macro is for use only if +<a href="headfootpage.html#footers">FOOTERS</a> +are on. It tells +<kbd><a href="#bibliography">BIBLIOGRAPHY</a></kbd> +not to print a page number on the first bibliography page. +Mom’s default is to print the page number. +</p> + +<!-- -SUSPEND_PAGINATION- --> + +<h5 id="suspend-pagination" class="docs" style="margin-top: -.5em; margin-bottom: .5em; margin-left: .5em;">• Suspending pagination during bibliography output</h5> + +<div class="box-macro-args" style="margin-bottom: 1em;"> +Macro: <b>SUSPEND_PAGINATION</b> +</div> + +<div class="box-macro-args"> +Macro: <b>RESTORE_PAGINATION</b> +</div> + +<p> +SUSPEND_PAGINATION doesn’t take an argument. Invoked +immediately prior to +<kbd><a href="#bibliography">BIBLIOGRAPHY</a></kbd>, +it turns off pagination for the duration of the bibliography. Mom +continues, however to increment page numbers silently. +</p> + +<p> +To restore normal document pagination after bibliographies, invoke +<kbd>.RESTORE_PAGINATION</kbd> (again, with no argument) immediately +after you’ve finished with your bibliography. +</p> + +<h4 id="biblio-header-control" class="docs" style="margin-bottom: .5em;">3. Header/footer control</h4> + +<h5 id="biblio-modify-hdrftr" class="docs" style="margin-top: 0; margin-bottom: .5em; margin-left: .5em;">• Modifying what goes in the bibliography header/footer</h5> + +<p> +If you wish to modify what appears in the header/footer that appears +on bibliography pages, make the changes before you invoke +<a href="#bibliography"><kbd>.BIBLIOGRAPHY</kbd></a>, +not afterwards. +</p> + +<p> +Except in the case of +<a href="docprocessing.html#doctype">DOCTYPE <kbd>CHAPTER</kbd></a>, +mom prints the same header or footer used throughout the document +on bibliography pages. Chapters get treated differently in that, +by default, mom does not print the header/footer centre string +(normally the chapter number or chapter title.) In most cases, this +is what you want. However, should you not want mom to remove the +centre string from the bibliography pages headers/footers, invoke +<kbd><a href="#bibliography-hdrftr-center">.BIBLIOGRAPHY_HEADER_CENTER</a></kbd> +with no argument. +</p> + +<p> +An important change you may want to make is to put the word +“Bibliography” in the header/footer centre position. To +do so, invoke +<br/> +<span class="pre-in-pp" style="margin-bottom: -1em;"> + .HEADER_CENTER "Endnotes" +</span> +or +<span class="pre-in-pp" style="margin-top: -.5em;"> + .FOOTER_CENTER "Endnotes" +</span> +prior to invoking <kbd>.BIBLIOGRAPHY</kbd>. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +If your +<a href="docprocessing.html#doctype">DOCTYPE</a> +is <kbd>CHAPTER</kbd>, you must also invoke +<a href="#endnotes-hdrftr-center">BIBLIOGRAPHY_HEADER_CENTER</a> +for the BIBLIOGRAPHY_HEADER_CENTER to appear. +</p> +</div> + +<h5 id="biblio-hdrftr-center" class="docs" style="margin-top: 0; margin-bottom: .5em; margin-left: .5em;">• Header/footer centre string when doctype is CHAPTER</h5> + +<div class="box-macro-args"> +Macro: <b>BIBLIOGRAPHY_HEADER_CENTER</b> <kbd class="macro-args">toggle</kbd> +</div> + +<p> +If your +<a href="docprocessing.html#doctype">DOCTYPE</a> +is <kbd>CHAPTER</kbd> and you want mom to include a centre +string in the headers/footers that appear on bibliography +pages, invoke <kbd>.BIBLIOGRAPHY_HEADER_CENTER</kbd> (or +<kbd>.BIBLIOGRAPHY_FOOTER_CENTER</kbd>) with no argument. +Mom’s default is NOT to print the centre string. +</p> + +<p> +If, for some reason, having enabled the header/footer centre string +on bibliography pages, you wish to disable it, invoke the same macro +with any argument (<kbd>OFF, QUIT, Q, X</kbd>...). +</p> + +<h5 id="biblio-allows-headers" class="docs" style="margin-top: -.5em; margin-bottom: .5em; margin-left: .5em;">• Allow headers on bibliography pages</h5> + +<div class="box-macro-args"> +Macro: <b>BIBLIOGRAPHY_ALLOWS_HEADERS</b> <kbd class="macro-args"><none> | ALL</kbd> +</div> + +<p> +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 +<br/> +<span class="pre-in-pp"> + .BIBLIOGRAPHY_ALLOWS_HEADERS OFF +</span> +If you want headers on every page including the first, do +<br/> +<span class="pre-in-pp"> + .BIBLIOGRAPHY_ALLOWS_HEADERS ALL +</span> +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +If FOOTERS are on, mom prints footers on every bibliography page. +This is a style convention. In mom, there is no such beast as +BIBLIOGRAPHY_ALLOWS_FOOTERS OFF. +</p> +</div> + +<h4 id="biblio-main-title" class="docs">4. Bibliography first-page title control</h4> + +<!-- -BIBLIO_STRING- --> + +<h5 id="biblio-string" class="docs" style="margin-top: 1em; margin-bottom: .5em; margin-left: .5em;">• Title string</h5> + +<div class="box-macro-args"> +Macro: <b>BIBLIOGRAPHY_STRING</b> <kbd class="macro-args">"<title to print at the top of bibliography pages>"</kbd> +</div> + +<p> +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 <kbd>.BIBLIOGRAPHY_STRING</kbd> with +the title you want, surrounded by double-quotes. +</p> + +<p> +If you don’t want a title at the top of the first bibliography +page, invoke <kbd>.BIBLIOGRAPHY_STRING</kbd> with a blank argument +(either two double-quotes side by +side—<kbd>""</kbd>—or no argument at all). +</p> + +<!-- -BIBLIO_STRING_CONTROL- --> + +<h5 id="biblio-string-control" class="docs" style="margin-top: -.5em; margin-bottom: .5em; margin-left: .5em;">• Title string control macros and defaults</h5> + +<div class="defaults-container" style="padding-bottom: 8px;"> +<p class="defaults" style="padding-top: 6px;"> +See +<a href="#control-macro-args">Arguments to the control macros</a>. +</p> +<span class="pre defaults"> +.BIBLIOGRAPHY_STRING_FAMILY default = prevailing document family; default is Times Roman +.BIBLIOGRAPHY_STRING_FONT default = bold +.BIBLIOGRAPHY_STRING_SIZE* default = +1 +.BIBLIOGRAPHY_STRING_QUAD default = centred + +*Relative to the size of the bibliography text (set with BIBLIOGRAPHY_PT_SIZE) +</span> +</div> + +<!-- -BIBLIOGRAPHY_STRING_ADVANCE- --> + +<h5 id="biblio-string-placement" class="docs" style="margin-top: -1em; margin-bottom: .5em; margin-left: .5em;">• Title string placement</h5> + +<div class="box-macro-args"> +Macro: <b>BIBLIOGRAPHY_STRING_ADVANCE</b> <kbd class="macro-args"><distance from top of page></kbd> +</div> + +<p class="requires"> +• Argument requires a <a href="definitions.html#unitofmeasure">unit of measusure</a> +</p> + +<p> +By default, mom places the title (the docheader, as it were) of +bibliographies (typically "BIBLIOGRAPHY") on the same +<a href="definitions.html#baseline">baseline</a> +that is used for the start of +<a href="definitions.html#running">running text</a>. +If you’d prefer another location, higher or lower on the page +(thereby also raising or lowering the starting position of the +bibliography itself), invoke <kbd>.BIBLIOGRAPHY_STRING_ADVANCE</kbd> +with an argument stating the distance from the top edge of the page +at which you’d like the title placed. +</p> + +<p> +The argument requires a unit of measure, so if you’d like the title +to appear 1-1/2 inches from the top edge of the page, you’d tell +mom about it like this: +<br/> +<span class="pre-in-pp"> + .BIBLIOGRAPHY_STRING_ADVANCE 1.5i +</span> +</p> + +<!-- -BIBLIO_STRING_UNDERLINE- --> + +<h5 id="biblio-string-underline" class="docs" style="margin-top: -1em; margin-bottom: .5em; margin-left: .5em;">• Title string underscoring</h5> + +<div class="box-macro-args"> +Macro: <b>BIBLIOGRAPHY_STRING_UNDERSCORE</b> <kbd class="macro-args">[DOUBLE] [<underline weight> [<underline gap> [<distance between double rules]]] | <none> | <anything></kbd> +</div> + +<p class="alias" style="margin-bottom: 0;"> +<i>Alias:</i> <b>BIBLIOGRAPHY_STRING_UNDERLINE</b> +</p> + +<p class="requires"> +• The argument +<span style="font-style: normal"><kbd><underscore weight></kbd></span> +must not have the +<a href="definitions.html#unitofmeasure">unit of measure</a>, +<span style="font-style: normal;"><kbd>p</kbd></span>, appended to it +</p> + +<p> +Invoked without an argument, +<kbd>.BIBLIOGRAPHY_STRING_UNDERSCORE</kbd> will place a single rule +underneath the bibliography's first-page title. Invoked with the +argument, <kbd>DOUBLE</kbd>, BIBLIOGRAPHY_STRING_UNDERSCORE will +double-underscore the thtile. Invoked with any other non-numeric +argument, (e.g. <kbd>OFF, NO, X</kbd>, etc.) the macro disables +underlining of the title. +</p> + +<p> +In addition, you can use BIBLIOGRAPHY_STRING_UNDERSCORE to control +the weight of the underscore rule(s), the gap between the title and +the underscore, and, in the case of double-underscores, the distance +between the two rules. +</p> + +<p> +Some examples: +<br/> +<span class="pre-in-pp"> + .BIBLIOGRAPHY_STRING_UNDERLINE 1 + - turn underlining on; set the rule weight to 1 point + + .BIBLIOGRAPHY_STRING_UNDERLINE 1 3p + - turn underlining on; set the rule weight to 1 point; set + the gap between the string and the underline to 3 points + + .BIBLIOGRAPHY_STRING_UNDERLINE DOUBLE .75 3p + - turn double-underlining on; set the rule weight to 3/4 of + a point; set the gap between the string and the upper + underline to 3 points; leave the gap between the upper + and the lower underline at the default + + .BIBLIOGRAPHY_STRING_UNDERLINE DOUBLE 1.5 1.5p 1.5p + - turn double-underlining on; set the rule weight to 1-1/2 + points; set the gap between the string and the upper + underline to 1-1/2 points; set the gap between the upper + and the lower underline to 1-1/2 points +</span> +Note, from the above, that in all instances, underscoring (single or +double) is enabled whenever BIBLIOGRAPHY_STRING_UNDERSCORE is used +in this way. +</p> + +<p> +Mom’s default is to double-underscore the title with 1/2-point +rules placed 2 points apart and 2 points below the baseline of the +title. +</p> + +<!-- -BIBLIO_STRING_CAPS- --> + +<h5 id="biblio-string-caps" class="docs" style="margin-top: -.5em; margin-bottom: .5em; margin-left: .5em;">• Title string capitalization</h5> + +<div class="box-macro-args"> +Macro: <b>BIBLIOGRAPHY_STRING_CAPS</b> <kbd class="macro-args">toggle</kbd> +</div> + +<p> +Invoked by itself, <kbd>.BIBLIOGRAPHY_STRING_CAPS</kbd> will +automatically capitalize the bibliography first-page title. Invoked +with any other argument, the macro disables automatic capitalization +of the title. +</p> + +<p> +If you’re generating a table of contents, you may want the +bibliography first-page title to be in caps, but the toc entry in +caps/lower case. If the argument to +<kbd><a href="#bibliography-string">BIBLIOGRAPHY_STRING</a></kbd> +is in caps/lower case and BIBLIOGRAPHY_STRING_CAPS is +on, this is exactly what will happen. +</p> + +<p> +Mom’s default is to capitalize the bibliography first-page +title. +</p> + +<div class="rule-long"><hr/></div> + +<!-- Navigation links --> +<table style="width: 100%; margin-top: 12px;"> +<tr> + <td style="width: 33%;"><a href="toc.html">Back to Table of Contents</a></td> + <td style="width: 33%; text-align: center;"><a href="#top">Top</a></td> + <td style="width: 33%; text-align: right;"><a href="letters.html">Next: Writing letters</a></td> +</tr> +</table> + +</div> + +<div class="bottom-spacer"><br/></div> + +</body> +</html> +<!-- vim: fileencoding=utf-8: nomodified: --> 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 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- + This file is part of groff, the GNU roff type-setting system. + + Copyright (C) 2004, 2005, 2006, 2009, 2010 Free Software Foundation, Inc. + Written by Peter Schaffter. + + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.3 or + any later version published by the Free Software Foundation; with the + Invariant Sections being this comment section, with no Front-Cover + Texts, and with no Back-Cover Texts. + + A copy of the Free Documentation License is included as a file called + FDL in the main directory of the groff source package. +--> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"> + +<head> + <meta http-equiv="content-type" content="text/html;charset=utf-8"/> + <title>Mom -- Reserved words (macros, strings, registers)</title> + <link rel="stylesheet" type="text/css" href="stylesheet.css" /> +</head> + +<body style="background-color: #f5faff;"> + +<!-- ==================================================================== --> + +<div id="top" class="page" style="width: 800px;"> + +<!-- Navigation links --> +<table style="width: 100%;"> +<tr> + <td><a href="toc.html">Back to Table of Contents</a></td> +</tr> +</table> + +<h1 id="reserved-words" class="docs">List of reserved words (macros, strings, registers)</h1> + +<p> +The following is a list of reserved words used by mom. Before +changing the name of any macro or document element tag with +<a href="goodies.html#ALIAS">ALIAS</a>, +I strongly recommend doing a search of this page for your proposed +new name. If you find it in the left hand column, choose something +else instead. +</p> + +<p> +Anyone interested in playing around inside mom’s macro file +(om.tmac) will find this list useful as well since it lists all (I +hope) the macros, strings, diversions, aliases and number registers +mom uses, along with brief descriptions of their functions. +</p> + +<div class="rule-medium"><hr/></div> + +<span class="pre" style="scroll: none;"> +<span style="display: block; text-decoration: underline;">TYPESETTING</span> +<span style="display: block; margin-top: -1em;">+++MACROS+++</span> +<span style="display: block; margin-top: -1em; margin-bottom: -1em;">*Page layout</span> + PAGELENGTH Page width + PAGE Page width/length; left, right, top, bottom margins + PAGEWIDTH Page width + PAPER Letter, legal, or A4 + B_MARGIN Space to leave at page bottom + L_MARGIN Page offset + R_MARGIN Line length as a function of + pagewidth minus pageoffset minus rightmargin + T_MARGIN Advance lead from page top + +<span style="display: block; margin-top: -.75em; margin-bottom: -1em;">*Page control</span> + DO_B_MARGIN Margin at bottom of page; trap-invoked + DO_T_MARGIN Margin at top of page; trap-invoked + +<span style="display: block; margin-top: -.75em; margin-bottom: -1em;">*Style</span> + COLOR Change color of text to predefined value + CONDENSE Set percentage of pseudo-condense (alias of + CONDENSE_OR_EXTEND) + EXTEND Set percentage of pseudo-extend (alias of + CONDENSE_OR_EXTEND) + FAMILY Family + FT Font + FALLBACK_FONT Font to use whenever FAMILY or FT errors occur + LL Line length + LS Leading (.vs) + NEWCOLOR Define a text color + PT_SIZE Point size + SETBOLDER Set degree of emboldening (pseudo-bold) in units + SETSLANT Set degree of pseudo-italic + XCOLOR Initialize a color from rgb.txt + +<span style="display: block; margin-top: -.75em; margin-bottom: -1em;">*Autolead</span> + AUTOLEAD Always lead n points more than .PT_SIZE + +<span style="display: block; margin-top: -.75em; margin-bottom: -1em;">*Quad, fill, justification</span> + JUSTIFY Justified text + QUAD Filled text, left, right, or centre + +<span style="display: block; margin-top: -.75em; margin-bottom: -1em;">*Quad, no-fill</span> + CENTER Line-for-line, non-filled text, centre + LEFT Line-for-line, non-filled text, left + RIGHT Line-for-line, non-filled text, right + +<span style="display: block; margin-top: -.75em; margin-bottom: -1em;">*Hyphenation</span> + HY Turn hyphenation on/off, or set LINES, MARGIN, SPACE + HY_SET Set LINES, MARGIN, SPACE in a single command + +<span style="display: block; margin-top: -.75em; margin-bottom: -1em;">*Advanced style</span> + KERN Turn automatic kerning on or off + LIGATURES Turn ligatures on or off + SS Sentence space control + WS Word space control + +<span style="display: block; margin-top: -.75em; margin-bottom: -1em;">*Line breaks</span> + BR Alias of br + EL Breaks line but doesn't advance + SPACE Alias of sp + SPREAD Alias of brp + +<span style="display: block; margin-top: -.75em; margin-bottom: -1em;">*Vertical motions</span> + ALD Advance lead + RLD Reverse lead + +<span style="display: block; margin-top: -.75em; margin-bottom: -1em;">*Indents</span> + HI Indent hang + IB Indent both + IBX Indent both off + IL Indent left + ILX Indent left off + IQ Indents off + IR Indent right + IRX Indent right off + IX Indents off -- deprecated + TI Indent temporary + +<span style="display: block; margin-top: -.75em; margin-bottom: -1em;">*Tabs</span> + ST String tab + TAB_SET Tab Set + TN Tab Next + TQ Tab Quit + +<span style="display: block; margin-top: -.75em; margin-bottom: -1em;">*Columnar tabs</span> + MCO Turn on multi-column mode + MCR Return to top of column + MCX Turn off multi-column mode + +<span style="display: block; margin-top: -.75em; margin-bottom: -1em;">*Underscore</span> + UNDERSCORE Underscores words or phrases + UNDERSCORE2 Double underscores words or phrases + +<span style="display: block; margin-top: -.75em; margin-bottom: -1em;">*Underline</span> + UNDERLINE Underlines whole passages (Courier only) + +<span style="display: block; margin-top: -.75em; margin-bottom: -1em;">*Smart Quotes</span> + SMARTQUOTES Turns smart quotes on or off + +<span style="display: block; margin-top: -.75em; margin-bottom: -1em;">*Graphical objects</span> + RULE_WEIGHT Weight of rules drawn with \*[RULE] + DBX Draw box + DCL Draw circle (ellipse) + DRH Draw horizontal rule + DRV Draw vertical rule + +<span style="display: block; margin-top: -.75em; margin-bottom: -1em;">*Misc + Support</span> + BR_AT_LINE_KERN Deposit a break before RW and WE + CAPS Convert u/lc to UC + COMMENT Don't print lines till COMMENT OFF (alias of SILENT) + DROPCAP_ADJUST Points (poss. fractional) to add/subtract + from drop caps + DROPCAP Create drop cap + DROPCAP_FAMILY Drop cap family + DROPCAP_FONT Drop cap font + DROPCAP_GUTTER Drop cap gutter + DROPCAP_OFF Support only; restores .in if there was one + ESC_CHAR Alias for .ec + EW Extra white -- loosen overall line kern + (character spacing) + LEADER_CHARACTER Sets leader character + PAD Insert padding spaces at marked places + PADMARKER Sets character to use instead of # in PAD + PRINT Simply prints args passed to it; keeps my code + indented nicely + RW Reduce white -- tighten overall line kern + (character spacing) + SILENT Don't print lines till SILENT OFF + SIZESPECS Get cap-height, x-height and descender depth for + current point size + SUPERSCRIPT_RAISE_AMOUNT Change default vertical displacement of superscripts + TRAP Turn traps off or on + +<span style="display: block; margin-top: -.5em; margin-bottom: -2.5em;">+++DIVERSIONS+++</span> + + NO_FLASH Diverts output of SILENT or COMMENT so they don't print + NULL Diverts SIZESPECS in PRINT_HDRFTR so it doesn't screw up + FOOTER and FOOTNOTE processing when FOOTERS are on + PAD_STRING Diverts $PAD_STRING for processing + TYPESIZE Diverts SIZESPECS routine so it doesn't print + +<span style="display: block; margin-top: -.5em; margin-bottom: -2.5em;">+++NUMBER REGISTERS+++</span> + + #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 + +<span style="display: block; margin-top: -.5em; margin-bottom: -2.5em;">+++STRINGS+++</span> + + $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 + +<span style="display: block; margin-top: -.5em; margin-bottom: -2.5em;">+++ALIASES+++</span> + + 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 + +<span style="display: block; margin-top: -.5em; margin-bottom: -2.5em;">+++ALIASES FOR NUMBER REGISTERS+++</span> + + #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 + +<span style="display: block; margin-top: -.5em; margin-bottom: -2.5em;">+++INLINE ESCAPES+++</span> + + 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 + +<span style="display: block; margin-top: -.5em; margin-bottom: -2.5em;">+++SPECIAL CHARACTERS+++</span> + + 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 +<span style="display: block; margin-top: 1em; text-decoration: underline;">DOCUMENT PROCESSING</span> +<span style="display: block; margin-top: -1em;">+++MACROS+++</span> +<span style="display: block; margin-top: -1em; margin-bottom: -1em;">*Document info (reference macros)</span> + 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 + +<span style="display: block; margin-top: -.75em; margin-bottom: -1em;">*Covers</span> + 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 + +<span style="display: block; margin-top: -.75em; margin-bottom: -1em;">*Document style</span> + 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 + +<span style="display: block; margin-top: -.75em; margin-bottom: -1em;">*Document tags and macros</span> + 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 + +<span style="display: block; margin-top: -.75em; margin-bottom: -1em;">*Headers/footers</span> + 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 + +<span style="display: block; margin-top: -.75em; margin-bottom: -1em;">*Control macros</span> +-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 + +<span style="display: block; margin-top: -.75em; margin-bottom: -1em;">*Aliases for header/footer control macros</span> + 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 + +<span style="display: block; margin-top: -.5em; margin-bottom: -2.5em;">+++LETTER MACROS+++</span> + + 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 + +<span style="display: block; margin-top: -.5em; margin-bottom: -2.5em;">+++SUPPORT+++</span> + + 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. + +<span style="display: block; margin-top: -.5em; margin-bottom: -2.5em;">+++DIVERSIONS+++</span> + + 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 + +<span style="display: block; margin-top: -.5em; margin-bottom: -2.5em;">+++NUMBER REGISTERS+++</span> + + #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. + +<span style="display: block; margin-top: -.5em; margin-bottom: -2.5em;">+++STRINGS+++</span> + + $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 + +<span style="display: block; border-top: 1px solid black; border-bottom: 1px solid black; padding-top: 2px;">**Note: "header", in the descriptions below, means either headers or footers</span> + $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 + +<span style="display: block; margin-top: -.5em; margin-bottom: -2.5em;">+++PREPROCESSOR KEYWORDS+++</span> + + (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 + +<span style="display: block; margin-top: -.5em; margin-bottom: -2.5em;">+++ALIASES+++</span> + +<span style="display: block; border: 1px solid black; padding-left: 12px; padding-bottom: 9px;"> +<span style="display: block; margin-top: -1em;">Please note:</span> +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. +</span> + +<span style="display: block; margin-top: -1.5em; margin-bottom: -2.5em;">+++These aliases are for convenience, and header/footer management+++</span> + + 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 + +<span style="display: block; margin-top: -.5em; margin-bottom: -2.5em;">+++These aliases are used for docelement type-style control+++</span> + + 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 + +<span style="display: block; margin-top: -.5em; margin-bottom: -2.5em;">+++These aliases are used to control underlining/underscoring weights+++</span> + + 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 +</span> + +<div class="rule-long" style="margin-top: 2em;"><hr/></div> + +<!-- Navigation links --> +<table style="width: 100%; margin-top: 12px;"> +<tr> + <td style="width: 33%;"><a href="toc.html">Back to Table of Contents</a></td> + <td style="width: 33%; text-align: right;"><a href="#top">Top</a></td> +</tr> +</table> + +</div> + +<div class="bottom-spacer"><br/></div> + +</body> +</html> +<!-- vim: fileencoding=utf-8: nomodified: --> 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 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- +This file is part of groff, the GNU roff type-setting system. + +Copyright (C) 2004, 2005, 2006, 2009, 2010 Free Software Foundation, Inc. +Written by Peter Schaffter. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with the +Invariant Sections being this comment section, with no Front-Cover +Texts, and with no Back-Cover Texts. + +A copy of the Free Documentation License is included as a file called +FDL in the main directory of the groff source package. +--> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"> + +<head> + <meta http-equiv="content-type" content="text/html;charset=utf-8"/> + <title>Mom -- Document processing, tables of contents</title> + <link rel="stylesheet" type="text/css" href="stylesheet.css" /> +</head> + +<body style="background-color: #f5faff;"> + +<!-- ==================================================================== --> + +<div id="top" class="page"> + +<!-- Navigation links --> +<table style="width: 100%;"> +<tr> + <td><a href="toc.html">Back to Table of Contents</a></td> + <td style="text-align: right;"><a href="refer.html#top">Next: Bibliographies and references</a></td> +</tr> +</table> + +<h1 class="docs">Tables of contents</h1> + +<div style="width: 68%; margin: auto;"> +<ul class="no-enumerator"> + <li><a href="#toc-intro">Introduction to tables of contents</a> + <ul style="margin-left: -.5em; list-style-type: disc;"> + <li><a href="#toc-behaviour">Tables of contents behaviour</a></li> + <li><a href="#psselect">Using <kbd>psselect</kbd> to put the table of contents where you want it</a></li> + </ul></li> + <li><a href="#toc">Instruct mom to output a table of contents</a></li> + <li><a href="#toc-control-top">Control macros for tables of contents</a> + <ul style="margin-left: -.5em; list-style-type: disc;"> + <li><a href="#index-toc-control">Table of contents control macros and defaults</a></li> + </ul></li> +</ul> +</div> + +<div class="rule-medium"><hr/></div> + +<h2 id="toc-intro" class="docs">Introduction to tables of contents</h2> + +<p> +Want a table of contents for your document? Easy. Just enter +<br/> +<span class="pre-in-pp"> + .TOC +</span> +as the very last macro of your document file. Mom will have picked +up all document titles (in +<a href="rectoverso.html#collate">collated</a> +documents), all heads, subheads, and paragraph heads, as well as +any endnotes pages that have been output, and assigned them the +appropriate page number (and page numbering style). Talk about a +no-brainer! +</p> + +<p> +That said, tables of contents 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 <i>and</i> flexibility. +</p> + +<h3 id="toc-behaviour" class="docs">Tables of contents behaviour</h3> + +<p> +When you output a table of contents (with +<kbd><a href="#toc">.TOC</a></kbd>), +mom finishes processing the last page of your document, then breaks +to a new page for printing the table of contents. +</p> + +<p> +Mom follows standard typesetting conventions for tables of contents. +To this end, if +<a href="headfootpage.html#headers">HEADERS</a> +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 +<a href="headfootpage.html#footers">FOOTERS</a> +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 +<a href="headfootpage.html#footer-on-first-page"><kbd>.FOOTER_ON_FIRST_PAGE</kbd></a> +immediately before <kbd>.TOC</kbd>.) Subsequent table of contents +pages have both page headers or footers and a page number. +</p> + +<p> +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 +<i>not</i> concatenated, as it is in the body of the document, +because it's visually redundant in a table of contents. +</p> + +<p> +Tables of contents are never set in columns, regardless of whether +the rest of the document is. Lastly, if +<a href="rectoverso.html#recto-verso">recto/verso</a> +printing is enabled, the 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 +<a href="#blank-page">BLANKPAGE</a> +or by using the control macro +<a href="#toc-rv-switch">TOC_RV_SWITCH</a>. +</p> + +<p> +The overall table of contents +<a href="definitions.html#family">family</a>, +<a href="definitions.html#ps">point size</a> +and +<a href="definitions.html#leading">lead</a> +can be altered with +<a href="definitions.html#controlmacro">control macros</a>, +as can the family, +<a href="definitions.html#font">font</a>, +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. +</p> + +<h5 id="psselect" class="docs">Using <kbd>psselect</kbd> to put the table of contents where you want it</h5> + +<p> +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. +</p> + +<p> +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 +<kbd>psselect</kbd> programme provided by the <b>psutils</b> suite +of tools (which you may have to install as a package from your +distribution if it is not already on your system). +</p> + +<p> +The procedure for using <kbd>psselect</kbd> 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). +</p> + +<p> +Once you know the number of pages in the table of contents, you use +<kbd>psselect</kbd> to place them where you want. +</p> + +<p> +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: +<br/> +<span class="pre-in-pp"> + psselect -p _1,1-_2 +</span> +The <kbd>-p</kbd> option instructs <kbd>psselect</kbd> 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)." +</p> + +<p> +If your table of contents runs to two pages, the option to +<kbd>psselect</kbd> would look like this: +<br/> +<span class="pre-in-pp"> + psselect -p _1-_2,1-_3 +</span> +If your table of contents runs to two pages and you have a cover +page, the command would look like this: +<br/> +<span class="pre-in-pp"> + psselect -p 1,_1-_2,2-_3 +</span> +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +<kbd>psselect</kbd> outputs to stdout, so you have to redirect the +output to a new file. +<br/> +<span class="pre-in-pp"> + psselect -p <page list> <file>.ps > <new-file>.ps +</span> +</p> +</div> + + +<!-- -TOC- --> + +<div class="macro-id-overline"> +<h3 id="toc" class="macro-id">Instruct mom to output a table of contents</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>TOC</b> +</div> + +<p> +If you want a table of contents, just place <kbd>.TOC</kbd> at the +very end of your document. Mom takes care of the rest. +</p> + +<div class="rule-short"><hr/></div> + +<h2 id="toc-control-top" class="macro-group">Control macros for tables of contents</h2> + +<div class="box-tip"> +<p class="tip-top"> +<span class="note">ERRATUM:</span> 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 +<kbd>.TOC</kbd>. +</p> + +<p class="tip-bottom"> +In fact, table of contents control macros must come before +<kbd><a href="docprocessing.html#start">.START</a></kbd>. +</p> +</div> + +<div class="defaults-container" style="background-color: #ded4bd; border: none;"> +<h3 id="index-toc-control" class="docs defaults">Table of contents control macros and defaults</h3> + +<ol style="margin-top: .5em; padding-bottom: .5em;"> + <li><a href="#toc-general">General table of contents style control</a> + <ul style="margin-left: -.5em;"> + <li><a href="#toc-family">TOC_FAMILY</a> – base family for tables of contents</li> + <li><a href="#toc-pt-size">TOC_PT_SIZE</a> – base point size for tables of contents</li> + <li><a href="#toc-lead">TOC_LEAD</a> – leading of tables of contents</li> + </ul></li> + <li><a href="#toc-pagenumbering">Table of contents page numbering</a> + <ul style="margin-left: -.5em;"> + <li><a href="#paginate-toc">PAGINATE_TOC</a> – turn table of contents pagination on or off</li> + <li><a href="#toc-pagenum-style">TOC_PAGENUM_STYLE</a> – table of contents page numbering style</li> + </ul></li> + <li><a href="#toc-header">Changing the table of contents header (title), string and style</a> + <ul style="margin-left: -.5em;"> + <li><a href="#toc-header-string">Changing the header (title) string</a> + <ul style="margin-left: -.5em;"> + <li><a href="#toc-header-style">Table of contents header (title) string control macros and defaults</a></li> + </ul></li> + </ul></li> + <li><a href="#toc-style">Changing the style of table of contents entries and page number references</a> + <ul style="margin-left: -.5em;"> + <li><a href="#toc-indent-note">Note: the table of contents _INDENT control macros</a></li> + <li><a href="#toc-title">Changing the style of table of contents title entries</a></li> + <li><a href="#toc-head">Changing the style of table of contents head entries</a></li> + <li><a href="#toc-subhead">Changing the style of table of contents subhead entries</a></li> + <li><a href="#toc-parahead">Changing the style of table of contents paragraph head entries</a></li> + <li><a href="#toc-pn">Changing the style of table of contents page number references</a></li> + </ul></li> + <li><a href="#toc-additional">Additional table of contents control macros</a> + <ul style="margin-left: -.5em;"> + <li><a href="#toc-appends-author">Append author(s) to table of contents title entries</a></li> + <li><a href="#toc-title-entry">Alter the wording of a table of contents title entry</a></li> + <li><a href="#toc-padding">Establish the number of placeholders to leave for page reference numbers</a></li> + <li><a href="#toc-rv-switch">Switch tables of contents page margins</a></li> + </ul></li> +</ol> +</div> + +<h4 id="toc-general" class="docs" style="margin-top: -1.5em; margin-bottom: .5em;">1. General tables of contents style control</h4> + +<div id="toc-family" class="box-macro-args"> +Macro: <b>TOC_FAMILY</b> <kbd class="macro-args"><family></kbd> +</div> + +<p> +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. +</p> + +<p> +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. +</p> + +<!-- -TOC_PT_SIZE- --> + +<div id="toc-pt-size" class="box-macro-args"> +Macro: <b>TOC_PT_SIZE</b> <kbd class="macro-args"><base type size of the toc></kbd> +</div> + +<p class="requires"> +• Does not require a <a href="definitions.html#unitofmeasure">unit of measure</a>; points is assumed +</p> + +<p> +Unlike most other control macros that deal with size of document +elements, TOC_PT_SIZE takes as its argument an absolute value, +relative to nothing. (Compare this with the +<a href="docelement.html#point-size">_SIZE</a> +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. +</p> + +<p> +The default for +<a href="docprocessing.html#printstyle">PRINTSTYLE <kbd>TYPESET</kbd></a> +is 12.5 points (the same default size used in the body of the +document). +</p> + +<div id="toc-lead" class="box-macro-args"> +Macro: <b>TOC_LEAD</b> <kbd class="macro-args"><leading of the toc> [ ADJUST ]</kbd> +</div> + +<p class="requires"> +• Does not require a <a href="definitions.html#unitofmeasure">unit of measure</a>; points is assumed +</p> + +<p> +Unlike most other control macros that deal with leading of document +elements, TOC_LEAD takes as its argument an absolute value, relative +to nothing. Therefore, the argument represents the +<a href="definitions.html#leading">leading</a> +of tables of contents in +<a href="definitions.html#picaspoints">points</a> +unless you append an alternative +<a href="definitions.html#unitofmeasure">unit of measure</a>. +For example, +<br/> +<span class="pre-in-pp"> + .TOC_LEAD 14 +</span> +sets the base leading of tables of contents to 14 points, whereas +<br/> +<span class="pre-in-pp"> + .TOC_LEAD .5i +</span> +sets the base leading of tables of contents to 1/2 inch. +</p> + +<p> +If you want the leading of tables of contents adjusted to fill the +page, pass TOC_LEAD the optional argument <kbd>ADJUST</kbd>. (See +<a href="docprocessing.html#doc-lead-adjust">DOC_LEAD_ADJUST</a> +for an explanation of leading adjustment.) +</p> + +<p> +The default for +<a href="docprocessing.html#printstyle">PRINTSTYLE TYPESET</a> +is the prevailing document lead (16 by default), adjusted. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +Even if you give mom a <kbd>.DOC_LEAD_ADJUST .OFF</kbd> command, +she will still, by default, adjust the leading of the table of +contents. You <i>must</i> enter +<kbd>TOC_LEAD <lead></kbd> with no <kbd>ADJUST</kbd> +argument to disable this default behaviour. +</p> + +<p class="tip-bottom"> +<span class="additional-note">Additional note:</span> +Tables of contents are always double-spaced in +<a href="docprocessing.html#printstyle">PRINTSTYLE <kbd>TYPEWRITE</kbd></a>, +regardless of whether the body of the document is single-spaced. +</p> +</div> + +<h4 id="toc-pagenumbering" class="docs">2. Table of contents page numbering</h4> + +<p> +The pagination style of tables of contents is controlled by the same +macros that control +<a href="headfootpage.html#pagination-intro">document page numbering</a>, +except +<a href="headfootpage.html#pagenum">PAGENUM</a> +(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. +</p> + +<p> +Therefore, if you wish to change some aspect of table of contents +pagination style, use the +<a href="headfootpage.html#index-pagination-control">document pagination control macros</a> +immediately prior to <kbd>.TOC</kbd>. +</p> + +<p> +A special macro, +<kbd><a href="#toc-pagenum-style">TOC_PAGENUM_STYLE</a></kbd> +controls the style of table of contents pagination (i.e. the actual +table of contents pages' numbers, not the page number references of +entries). +</p> + +<!-- -PAGINATE_TOC- --> + +<div id="paginate-toc" class="box-macro-args"> +Macro: <b>PAGINATE_TOC</b> <kbd class="macro-args"><toggle></kbd> +</div> + +<p> +By default, mom paginates tables of contents. If you’d like +her not to, do +<br/> +<span class="pre-in-pp"> + .PAGINATE_TOC OFF +</span> +(or <kbd>NO, X,</kbd> etc). +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +Simply invoking +<kbd>.PAGINATION OFF</kbd> +or +<kbd>.PAGINATE OFF</kbd> +disables table of contents pagination <i>for the first +page of the table of contents only.</i> You must use +<kbd>.PAGINATE_TOC OFF</kbd> to disable table of contents +pagination completely, even if pagination is turned off elsewhere in +your document. +</p> +</div> + +<!-- -TOC_PAGENUM_STYLE- --> + +<div id="toc-pagenum-style" class="box-macro-args"> +Macro: <b>TOC_PAGENUM_STYLE</b> <kbd class="macro-args"><DIGIT | ROMAN | roman | ALPHA | alpha></kbd> +</div> +<p class="requires"> +See +<a href="headfootpage.html#pagenum-style"><span style="font-style: normal;">PAGENUM_STYLE</span></a> +for an explanation of the arguments. +</p> + +<p> +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: +<br/> +<span class="pre-in-pp"> + .TOC_PAGENUM_STYLE DIGIT +</span> +</p> + +<h4 id="toc-header" class="docs" style="margin-top: -.5em;">3. Changing the table of contents header (title) string and style</h4> + +<p> +The table of contents header string is the title that appears at to top of the +table of contents. By default, it’s “Contents”.</p> + +<div id="toc-header-string" class="box-macro-args"> +Macro: <b>TOC_HEADER_STRING</b> <kbd class="macro-args"><string></kbd> +</div> + +<p> +If you’d like the title of the table of contents to read +something other than “Contents”, do, for +example +<br/> +<span class="pre-in-pp"> + .TOC_HEADER_STRING "Table of Contents" +</span> +</p> + +<h5 id="toc-header-style" class="docs" style="margin-top: -.5em; text-transform: none;">Table of contents header string (title) control macros and defaults</h5> + +<div class="defaults-container" style="margin-top: 1em; padding-bottom: 8px;"> +<p class="defaults" style="padding-top: 6px;"> +See +<a href="docelement.html#control-macro-args">Arguments to the control macros</a>. +</p> +<span class="pre defaults"> +.TOC_HEADER_FAMILY default = prevailing doc family +.TOC_HEADER_FONT default = bold +.TOC_HEADER_SIZE default = +4 +.TOC_HEADER_QUAD default = left +</span> +</div> + +<h4 id="toc-style" class="docs" style="margin-top: -1em;">4. Changing the style of table of contents entries and page number references</h4> + +<p> +“Entries” refers to titles in +<a href="rectoverso.html#collate-intro">collated</a> +documents +(<a href="docprocessing.html#title">TITLE</a>) +, heads +(<a href="docelement.html#head">HEAD</a>), +subheads +(<a href="docelement.html#subhead">SUBHEAD</a>), +and paragraph heads +(<a href="docelement.html#parahead">PARAHEAD</a>) +as they appear in the table of contents. Their style is managed by +the usual +<a href="definitions.html#controlmacro">control macros</a>, +which take the form <kbd>TOC_<ELEMENT>_<SPEC></kbd> +(e.g. <kbd>TOC_HEAD_FAMILY</kbd> or <kbd>TOC_SUBHEAD_INDENT</kbd>). +</p> + +<p> +“Page number references” means the page numbers associated with +entries. They take the form <kbd>TOC_PN_<SPEC></kbd>. +</p> + +<p> +The following is a list of the control macros for table of contents +entries, along with their defaults. +</p> + +<div id="toc-indent-note" class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +The table of contents _INDENT +macros set an absolute indent, relative to nothing, and therefore +require an appended +<a href="definitions.html#unitofmeasure">unit of measure</a>. +</p> +</div> +<div id="index-toc-entry-control-macros" class="defaults-container" style="padding-bottom: 8px;"> +<p class="defaults" style="padding-top: 6px;"> +See +<a href="docelement.html#control-macro-args">Arguments to the control macros</a>. +</p> + +<span class="pre defaults"> +<span id="toc-title"> +.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 +</span> +<span id="toc-head"> +.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 +</span> +<span id="toc-subhead"> +.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 +</span> +<span id="toc-parahead"> +.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 +</span> +.TOC_PN_FAMILY default = prevailing doc family +.TOC_PN_FONT default = roman +.TOC_PN_SIZE default = +0 +</span> +</div> + +<h4 id="toc-additional" class="docs" style="margin-top: -1em;">5. Additional table of contents control macros</h4> + +<p> +The following four macros allow you to +</p> +<ul style="margin-top: -.5em; margin-left: -.5em;"> + <li>instruct mom to <a href="#toc-appends-author">append author(s) to</a> <a href="docprocessing.html#title">TITLE</a> <a href="toc-appends-author">entries</a></li> + <li><a href="#toc-title-entry">alter the wording of</a> <a href="docprocessing.html#title">TITLE</a> <a href="#toc-title-entry">entries</a></li> + <li>establish <a href="#toc-padding">how many placeholders to leave for page number references</a></li> + <li><a href="#toc-rv-switch">switch table of contents page margins</a> should they be incorrect for recto/verso printing</li> +</ul> + +<!-- -TOC_APPENDS_AUTHOR- --> + +<div id="toc-appends-author" class="box-macro-args"> +Macro: <b>TOC_APPENDS_AUTHOR</b> <kbd class="macro-args"><none> | <"name(s) of authors"></kbd> +</div> + +<p> +In certain kinds of collated documents, different authors are +responsible for the articles or stories contained within them. In +such documents, you may wish to have the author or authors appended +to the table of contents’ title entry for each story or +article. +</p> + +<p> +If you invoke <kbd>.TOC_APPENDS_AUTHOR</kbd> <i>without</i> an +argument, mom appends the first argument you passed to +<a href="docprocessing.html#author">AUTHOR</a> +to table of contents title entries, separated by a front-slash. +</p> + +<p> +If you invoke <kbd>.TOC_APPENDS_AUTHOR</kbd> <i>with</i> 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 +<br/> +<span class="pre-in-pp"> + .TOC_APPENDS_AUTHOR "Blough et al." +</span> +would be a good way to identify them in the table of contents. +</p> + +<!-- -TOC_TITLE_ENTRY- --> + +<div id="toc-title-entry" class="box-macro-args"> +Macro: <b>TOC_TITLE_ENTRY</b> <kbd class="macro-args"><"alternate wording for a title entry in the toc"></kbd> +</div> + +<p> +In +<a href="rectoverso.html#collate">collated</a> +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 +<a href="definitions.html#docheader">docheader</a>. +You might, for example, want to shorten it. Or, in the case of +chapters where the docheader contains both a chapter number and a +chapter title, like this +<br/> +<span class="pre-in-pp"> + Chapter 6 + Burning Bush — Maybe God Was Right +</span> +you might want only the chapter title, not the chapter number, to +show up in the table of contents. (By default, <kbd>.TOC</kbd> +generates both.) +</p> + +<p> +If you want to change the wording of a title entry in the table of +contents, simply invoke +<br/> +<span class="pre-in-pp"> + .TOC_TITLE_ENTRY +</span> +with the desired wording, enclosed in double-quotes. Using the +example, above, +<br/> +<span class="pre-in-pp"> + .CHAPTER 6 + .CHAPTER_TITLE "Burning Bush — Maybe God Was Right" + .TOC_TITLE_ENTRY "Burning Bush" + .DOCTYPE CHAPTER +</span> + +would identify chapter 6 in the table of contents simply as +“Burning Bush”. +</p> + +<!-- -TOC_PADDING- --> + +<div id="toc-padding" class="box-macro-args"> +Macro: <b>TOC_PADDING</b> <kbd class="macro-args"><number of placeholders to allow for page number listings></kbd> +</div> + +<p> +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 +<br/> +<span class="pre-in-pp"> + .TOC_PADDING 2 +</span> +</p> + +<!-- -TOC_RV_SWITCH- --> + +<div id="toc-rv-switch" class="box-macro-args"> +Macro: <b>TOC_RV_SWITCH</b> +</div> + +<p> +TOC_RV_SWITCH doesn’t take an argument. It simply instructs +mom to switch the left and right margins of +<a href="rectoverso.html#recto-verso">recto/verso</a> +documents should the table of contents happen to begin on an even +page when you want an odd, or vice versa. +</p> + +<p> +The same result can be accomplished by outputting a +<a href="#blank-page">BLANKPAGE</a>. +</p> + +<div class="rule-long"><hr/></div> + +<!-- Navigation links --> +<table style="width: 100%; margin-top: 12px;"> +<tr> + <td style="width: 33%;"><a href="toc.html">Back to Table of Contents</a></td> + <td style="width: 24%; text-align: center;"><a href="#top">Top</a></td> + <td style="width: 42%; text-align: right;"><a href="refer.html">Next: Bibliographies and references</a></td> +</tr> +</table> + +</div> + +<div class="bottom-spacer"><br/></div> + +</body> +</html> +<!-- vim: fileencoding=utf-8: nomodified: --> + 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 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- +This file is part of groff, the GNU roff type-setting system. + +Copyright (C) 2004, 2005, 2006, 2007, 2008, 2009, 2010 Free Software Foundation, Inc. +Written by Peter Schaffter (pschaffter@ncf.ca). + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with the +Invariant Sections being this comment section, with no Front-Cover +Texts, and with no Back-Cover Texts. + +A copy of the Free Documentation License is included as a file called +FDL in the main directory of the groff source package. +--> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"> + +<head> + <meta http-equiv="content-type" content="text/html;charset=utf-8"/> + <title>Mom, version 1.5-e -- Table of Contents</title> + <link rel="stylesheet" type="text/css" href="stylesheet.css" /> +</head> + +<body style="background-color: #f5faff;"> + +<!-- ==================================================================== --> + +<div class="page"> + + <div class="version"> + mom, version 1.5-d + </div> + +<h1 class="toc" style="margin-top: 9px;">Table of Contents</h1> + + <p style="margin-left: 2.75em; margin-right: 2.75em;"> + The table of contents has grown quite large. To ease navigation, + click on any link in the + <a href="#quick-toc">Quick Table of Contents</a> + to go to the corresponding entry in the the + <a href="#full-toc">Full Table of Contents</a>. + </p> + + <p style="margin-top: -.5em; margin-left: 2.75em; margin-right: 2.5em;"> + Alternatively, if you've been using mom for a while, you might + prefer the + <a href="macrolist.html#top">Quick Reference Guide</a>. + </p> + +<div class="rule-medium"><hr/></div> + +<!-- -QUICK TABLE OF CONTENTS- --> + + <h2 id="quick-toc" class="toc" style="margin-top: 18px; text-align: center;">Quick Table of Contents</h2> + + <div style="width: 50%; margin-top: .75em; margin-left: 12px; float: left;"> + <h3 id="introductory" class="toc"><a style="color: #6e70cc" href="#what">INTRODUCTORY STUFF</a></h3> + <ul class="toc"> + <li><a href="#what">What is mom?</a></li> + <li><a href="#defs">Definitions of terms used in this manual</a></li> + <li><a href="#using">Using mom</a></li> + </ul> + + <h3 id="typesetting" class="toc"><a style="color: #6e70cc" href="#typeset">TYPESETTING WITH MOM</a></h3> + + <ul class="toc"> + <li><a href="#type-intro">Introduction to the typesetting macros</a></li> + <li><a href="#page">Page setup</a></li> + <li><a href="#param">Basic typesetting parameters</a></li> + <li><a href="#just">Justifying, quadding, etc.</a></li> + <li><a href="#refine">Refinements</a></li> + <li><a href="#mod">Modifying type</a></li> + <li><a href="#vert">Vertical movements</a></li> + <li><a href="#tab">Tabs</a></li> + <li><a href="#col">Multiple columns</a></li> + <li><a href="#ind">Indents</a></li> + <li><a href="#goodies">Goodies</a></li> + <li><a href="#escapes">Inline escapes</a></li> + <li><a href="#color">Coloured text</a></li> + <li><a href="#graphical">Graphical objects</a></li> + </ul> + </div> + + <div style="margin-left: 332px;"> + <h3 id="document-processing" class="toc" style="margin-top: 1.25em;"><a style="color: #6e70cc" href="#doc-proc">DOCUMENT PROCESSING WITH MOM</a></h3> + + <ul class="toc" style="margin-left: 3em;"> + <li><a href="#doc-proc">Introduction to document processing</a></li> + <li><a href="#doc-defaults">Document defaults</a></li> + <li><a href="#prelim">Preliminary document setup</a></li> + <li><a href="#typemacdoc">Behaviour of the typesetting macros during document processing</a></li> + <li><a href="#tags">The document element tags</a> – heads, paragraphs, subheads, footnotes, etc.</li> + <li><a href="#images">Inserting images into a document</a></li> + <li><a href="#hdrftr">Page headers and footers</a></li> + <li><a href="#paginate">Pagination</a></li> + <li><a href="#rv">Recto/verso printing and collating</a></li> + <li><a href="#cover">Cover pages</a></li> + <li><a href="#tocs">Tables of contents</a></li> + <li><a href="#ref">Bibliographies and references</a></li> + <li><a href="#letter">Writing letters</a> + <ul style="list-style-type: none;"> + <li style="display: inline-block; width: 212px; height: 0; margin-top: .5em; margin-left: -2.5em; border: solid 1px #8d8775;"> </li> + </ul></li> + <li style="margin-top: -1em;"><a href="#quick">Quick reference guide</a></li> + <li><a href="#appendices">Appendices</a></li> + <li><a href="#reserved">Reserved words (macros, strings, registers)</a></li> + </ul> + </div> + + <div class="rule-long" style="clear: both;"><hr/></div> + +<!-- -FULL TABLE OF CONTENTS- --> + + <h2 id="full-toc" class="toc" style="margin-top: 24px; text-align: center;">Full Table of Contents</h2> + + <div style="margin-left: 12px;"> + <h3 id="what" class="toc"><a style="color: #6e70cc" href="intro.html#top">1. WHAT IS MOM?</a></h3> + + <ul class="toc"> + <li><a href="intro.html#intro-intro">1.1 Who is mom meant for?</a></li> + <li><a href="intro.html#intro-typesetting">1.2 Typesetting with mom</a></li> + <li><a href="intro.html#intro-docprocessing">1.3 Document processing with mom</a></li> + <li><a href="intro.html#intro-philosophy">1.4 Mom's philosophy</a></li> + <li><a href="intro.html#intro-documentation">1.5 A note on mom's documentation</a> + <ul> + <li><a href="intro.html#macro-args">1.5.1 How to read macro arguments</a></li> + <li><a href="intro.html#toggle-macro">1.5.2 "Toggle" macros</a></li> + <li><a href="intro.html#examples">1.5.3 Examples</a></li> + </ul> + </li> + </ul> + + <h3 id="defs" class="toc"><a style="color: #6e70cc" href="definitions.html#top">2. DEFINITIONS OF TERMS USED IN THIS MANUAL</a></h3> + + <ul class="toc"> + <li><a href="definitions.html#typesetting-terms">2.1 Typesetting terms</a></li> + <li><a href="definitions.html#groff-terms">2.2 Groff terms</a></li> + <li><a href="definitions.html#mom-terms">2.3 Mom's document processing terms</a></li> + </ul> + + <h3 id="using" class="toc"><a style="color: #6e70cc" href="using.html#top">3. USING MOM</a></h3> + + <ul class="toc"> + <li><a href="using.html#using-intro">3.1 Introduction</a></li> + <li><a href="using.html#using-macros">3.2 How to input mom’s macros</a></li> + <li><a href="using.html#using-previewing">3.3 How to preview documents</a></li> + <li><a href="using.html#using-saving">3.4 Saving documents</a></li> + <li><a href="using.html#using-printing">3.3 Printing — invoking groff with mom</a></li> + </ul> + +<!-- -TYPESETTING MACROS- --> + + <h3 id="typeset" class="toc"><a style="color: #6e70cc" href="typesetting.html#top">4. TYPESETTING WITH MOM</a></h3> + + <ul class="toc"> + <li><a id="type-intro" href="typesetting.html#typesetting-intro">4.1 Introduction to the typesetting macros</a></li> + <li><a id="page" href="typesetting.html#page-setup-intro">4.2 Paper and page Setup</a> – paper size and page margins + <ul> + <li><a href="typesetting.html#index-page-setup">4.2.1 Macro list</a></li> + </ul></li> + <li><a id="param" href="typesetting.html#basic-params-intro">4.3 Basic typesetting parameters</a> – family, font, fallback font, point size, line space, line length, autolead + <ul> + <li><a href="typesetting.html#index-basic">4.3.1 Macro list</a></li> + </ul></li> + <li><a id="just" href="typesetting.html#justification-intro">4.4 Justifying, quadding, filling and breaking lines</a> + <ul> + <li><a href="typesetting.html#index-justification">4.4.1 Macro list</a></li> + </ul></li> + <li><a id="refine" href="typesetting.html#refinements-intro">4.5 Refinements</a> – word space, sentence space, letter spacing (track kerning), hyphenation, kerning, ligatures + <ul> + <li><a href="typesetting.html#index-refinements">4.5.1 Macro list</a></li> + </ul></li> + <li><a id="mod" href="typesetting.html#modifications-intro">4.6 Modifying Type</a> – pseudo-italic, -bold, -condensed, and -extended + <ul> + <li><a href="typesetting.html#index-modifications">4.6.1 Macro list</a></li> + </ul></li> + <li><a id="vert" href="typesetting.html#aldrld-intro">4.7 Vertical Movements</a> – moving up and down on the page + <ul> + <li><a href="typesetting.html#index-aldrld">4.7.1 Macro list</a></li> + </ul></li> + <li><a id="tab" href="typesetting.html#tabs-intro">4.8 Tabs</a> + <ul> + <li><a href="typesetting.html#typesetting-tabs">4.8.1 Typesetting tabs</a> + <ul> + <li><a href="typesetting.html#typesetting-tabs-tut">4.8.1.1 Quickie tutorial</a></li> + </ul></li> + <li><a href="typesetting.html#string-tabs">4.8.2 String tabs (autotabs)</a> + <ul> + <li><a href="typesetting.html#string-tabs-tut">4.8.2.1 Quickie tutorial</a></li> + </ul></li> + <li><a href="typesetting.html#index-tabs">4.8.3 Macro list</a></li> + </ul></li> + <li><a id="col" href="typesetting.html#multicolumns-intro">4.9 Multiple columns</a> + <ul> + <li><a href="typesetting.html#index-multicolumns">4.9.1 Macro list</a></li> + </ul></li> + <li><a id="ind" href="typesetting.html#indents-intro">4.10 Indents</a> + <ul> + <li><a href="typesetting.html#indents-handling">4.10.1 A brief explanation of how mom handles indents</a></li> + <li><a href="typesetting.html#index-indents">4.10.2 Macro list</a></li> + </ul></li> + <li><a id="goodies" href="goodies.html#top">4.11 Goodies</a> + – aliases, transparent (comment) lines, smartquotes, caps, + underscoring/underlining, padding lines, leaders, drop + caps, superscripts, user-definable strings, changing the + escape character + <ul> + <li><a href="goodies.html#index-goodies">4.11.1 Macro list</a></li> + </ul></li> + <li><a id="escapes" href="inlines.html#top">4.12 Inline Escapes</a> + <ul> + <li><a href="inlines.html#intro-inlines">4.12.1 Introduction to inline escapes</a></li> + <li><a href="inlines.html#index-inlines">4.12.2 List of inline escapes</a></li> + <li><a href="inlines.html#inlines-mom-top">4.12.3 Mom's personal inline escapes</a></li> + <li><a href="inlines.html#inlines-groff-top">4.12.4 Commonly-used groff inline escapes</a> + <ul> + <li><a href="inlines.html#inline-characters-groff">4.12.4.1 Special characters and symbols</a></li> + </ul></li> + </ul></li> + <li><a id="color" href="color.html#top">4.13 Coloured text</a> + <ul> + <li><a href="color.html#intro-color">4.13.1 Introduction to coloured text</a></li> + <li><a href="color.html#index-color">4.13.2 Macro list</a></li> + </ul></li> + <li><a id="graphical" href="graphical.html#top">4.14 Graphical objects</a> + – horizontal and vertical rules, boxes, ellipses (circles) + <ul> + <li><a href="graphical.html#intro-graphical">4.14.1 Introduction to graphical objects</a></li> + <li><a href="graphical.html#index-graphical">4.13.2 Macro list</a></li> + </ul></li> + </ul> + +<!-- -DOCUMENT PROCESSING MACORS- --> + + <h3 id="doc-proc" class="toc"><a style="color: #6e70cc" href="docprocessing.html#top">5. DOCUMENT PROCESSING WITH MOM</a></h3> + <ul class="toc"> + <li><a href="docprocessing.html#docprocessing-intro">5.1 Introduction to document processing</a></li> + <li><a id="doc-defaults" href="docprocessing.html#defaults">5.2 Document defaults</a> + <ul> + <li><a href="docprocessing.html#leading-note">5.2.1 Important note on leading/spacing and bottom margins</a> + <ul> + <li><a href="docprocessing.html#shim">5.2.1.1 The SHIM macro</a> – to get document leading back on track</li> + </ul></li> + </ul></li> + <li><a id="prelim" class="highlight" href="docprocessing.html#setup">5.3 PRELIMINARY DOCUMENT SETUP</a> + <ul> + <li><a href="docprocessing.html#docprocessing-tut" class="highlight">5.3.1 Tutorial</a> – setting up a mom document</li> + <li><a href="docprocessing.html#reference-macros" class="highlight">5.3.2 The reference macros</a> – meta-information mom needs to do her job + <ul> + <li><a href="docprocessing.html#title">5.3.2.1 TITLE</a></li> + <li><a href="docprocessing.html#doc-title">5.3.2.2 DOCTITLE</a></li> + <li><a href="docprocessing.html#subtitle">5.3.2.3 SUBTITLE</a></li> + <li><a href="docprocessing.html#author">5.3.2.4 AUTHOR</a></li> + <li><a href="docprocessing.html#chapter">5.3.2.5 CHAPTER</a></li> + <li><a href="docprocessing.html#chapter-title">5.3.2.6 CHAPTER_TITLE</a></li> + <li><a href="docprocessing.html#draft">5.3.2.7 DRAFT</a></li> + <li><a href="docprocessing.html#revision">5.3.2.8 REVISION</a></li> + <li><a href="docprocessing.html#copyright">5.3.2.9 COPYRIGHT</a></li> + <li><a href="docprocessing.html#misc">5.3.2.10 MISC</a></li> + <li><a href="docprocessing.html#covertitle">5.3.2.11 COVERTITLE</a></li> + <li><a href="docprocessing.html#covertitle">5.3.2.12 DOC_COVERTITLE</a></li> + </ul></li> + <li><a href="docprocessing.html#docstyle-macros" class="highlight">5.3.3 The docstyle macros</a> – general appearance; what kind of document you're creating, and how you want it to look overall + <ul> + <li><a href="docprocessing.html#doctype">5.3.3.1 DOCTYPE</a> – the kind of document</li> + <li><a href="docprocessing.html#printstyle">5.3.3.2 PRINTSTYLE</a> – typeset or “typewritten, double-spaced”</li> + <li><a href="docprocessing.html#copystyle">5.3.3.3 COPYSTYLE</a> – draft or final</li> + </ul></li> + <li><a href="docprocessing.html#start-macro" class="highlight">5.3.4 Initiate document processing</a> + <ul> + <li><a href="docprocessing.html#start">5.3.4.1 START</a> – the required macro to initiate document processing</li> + </ul></li> + <li><a href="docprocessing.html#style-before-start" class="highlight">5.3.5 Establishing type and formatting parameters before START</a> + <ul> + <li><a href="docprocessing.html#type-before-start">5.3.5.1 Use of the typesetting macros before START</a> + <ul class="fourth-level"> + <li>– <a href="docprocessing.html#include">5.3.5.1.1 Including (sourcing) style sheets and files</a></li> + <li>– <a href="docprocessing.html#color">5.3.5.1.2 Initializing colours</a></li> + </ul></li> + <li><a href="docprocessing.html#doc-lead-adjust">5.3.5.2 DOC_LEAD_ADJUST</a> – adjust document + <a href="definitions.html#leading">leading</a> + to fill pages + <ul class="fourth-level"> + <li>– <a href="docprocessing.html#shim">5.3.5.2.1 SHIM</a> – macro to get document leading back on track</li> + </ul></li> + <li><a href="docprocessing.html#docheader">5.3.5.3 Managing the document header</a></li> + <li><a href="docprocessing.html#columns-intro">5.3.5.4 COLUMNS</a> – setting documents in columns</li> + </ul></li> + <li><a href="docprocessing.html#style-after-start" class="highlight">5.3.6 Changing basic type and formatting parameters after START</a> + <ul> + <li><a id="typemacdoc" href="docprocessing.html#behaviour">5.3.6.1 Behaviour of the typesetting macros during document processing</a></li> + <li><a href="docprocessing.html#intro-doc-param">5.3.6.2 Post-START global style change macros</a> + <ul class="fourth-level"> + <li>– <a href="docprocessing.html#index-doc-param">Macro list</a></li> + </ul></li> + </ul></li> + </ul></li> + <li><a id="tags" class="highlight" href="docelement.html#top">5.4 THE DOCUMENT ELEMENT TAGS</a> + <ul> + <li><a href="docelement.html#docelement-intro">5.4.1 Introduction to the document element tags</a> + <ul> + <li><a href="docelement.html#docelement-control">5.4.1.1 Control macros</a> – changing style defaults for document element tags</li> + <li><a href="docelement.html#control-macro-args">5.4.1.2 Arguments to the control macros</a></li> + </ul></li> + <li><a href="docelement.html#epigraph-intro">5.4.2 Epigraphs</a></li> + <li><a href="docelement.html#pp-intro">5.4.3 Paragraphs</a></li> + <li><a href="docelement.html#head-intro">5.4.4 Main heads</a></li> + <li><a href="docelement.html#subhead-intro">5.4.5 Subheads</a></li> + <li><a href="docelement.html#parahead-intro">5.4.6 Paragraph heads</a></li> + <li><a href="docelement.html#linebreak-intro">5.4.7 Linebreaks</a> – author linebreaks (section breaks)</li> + <li><a href="docelement.html#quote-intro">5.4.8 Quotes</a> – line for line poetic quotes or unformatted, verbatim text (e.g. blocks of code)</li> + <li><a href="docelement.html#blockquote-intro">5.4.9 Blockquotes</a> – cited material</li> + <li><a href="docelement.html#code">5.4.10 Code</a> – inserting code snippets</li> + <li><a href="docelement.html#list-intro">5.4.11 Lists</a> – nested lists</li> + <li><a href="docelement.html#number-lines-intro">5.4.12 Line numbering</a></li> + <li><a href="docelement.html#footnote-intro">5.4.13 Footnotes</a></li> + <li><a href="docelement.html#endnote-intro">5.4.14 Endnotes</a></li> + <li><a href="docelement.html#margin-notes-intro">5.4.15 Margin notes</a></li> + <li><a href="docelement.html#finis-intro">5.4.16 Document termination string</a> – FINIS</li> + </ul></li> + <li><a id="images" class="highlight" href="images.html#top">5.5 INSERTING IMAGES</a></li> + <li><a id="hdrftr" class="highlight" href="headfootpage.html#top">5.6 PAGE HEADERS AND FOOTERS</a> + <ul> + <li><a href="headfootpage.html#headfootpage-intro">5.6.1 Introduction</a></li> + <li><a href="headfootpage.html#description-general">5.6.2 General description of headers/footers</a></li> + <li><a href="headfootpage.html#header-style">5.6.3 Default specs for headers/footers</a></li> + <li><a href="headfootpage.html#vertical-spacing">5.6.4 Vertical placement and spacing of headers/footers</a></li> + <li><a href="headfootpage.html#headfoot-management">5.6.5 Managing page headers and footers</a></li> + <li><a href="headfootpage.html#headfoot-control">5.6.6 Control macros for headers/footers</a></li> + <li><a href="headfootpage.html#userdef-hdrftr-rv">5.6.7 User-defined, single string recto/verso headers/footers</a> + <ul> + <li><a href="headfootpage.html#userdef-hdrftr">5.6.7.1 User-defined, single string headers/footers (no recto/verso)</a></li> + </ul></li> + <li><a href="headfootpage.html#headers-and-footers-intro">5.6.8 Headers and footers on the same page</a></li> + </ul></li> + <li><a id="paginate" class="highlight" href="headfootpage.html#pagination-intro">5.7 PAGINATION</a> + <ul> + <li><a href="headfootpage.html#pagination">5.7.1 Introduction</a></li> + <li><a href="headfootpage.html#index-pagination">5.7.2 Pagination macros list</a></li> + <li><a href="headfootpage.html#blank-pages">5.7.3 Blank pages</a></li> + </ul></li> + <li><a id="rv" class="highlight" href="rectoverso.html#top">5.8 RECTO/VERSO PRINTING, COLLATING</a> + <ul> + <li><a href="rectoverso.html#rectoverso-intro">5.8.1 Introduction to recto/verso printing</a> + <ul> + <li><a href="rectoverso.html#rectoverso-list">5.8.1.1 Macro list</a></li> + </ul></li> + <li><a href="rectoverso.html#collate-intro">5.8.2 Introduction to collating</a> + <ul> + <li><a href="rectoverso.html#collate">5.8.2.1 The COLLATE macro</a></li> + </ul></li> + </ul></li> + <li><a id="cover" class="highlight" href="cover.html#top">5.9 COVER PAGES</a></li> + <li><a id="tocs" class="highlight" href="tables-of-contents.html#top">5.10 TABLES OF CONTENTS</a> + <ul> + <li><a href="tables-of-contents.html#toc-behaviour">5.10.1 Table of contents behaviour</a></li> + <li><a href="tables-of-contents.html#psselect">5.10.2 Using psselect to put tables of contents where you want them</a></li> + <li><a href="tables-of-contents.html#toc-control">5.10.3 Table of contents control macros</a></li> + </ul></li> + <li><a id="ref" class="highlight" href="refer.html#top">5.11 BIBLIOGRAPHIES AND REFERENCES</a></li> + <li><a id="letter" class="highlight" href="letters.html#top">5.12 WRITING LETTERS</a> + <ul> + <li><a href="letters.html#letters-intro">5.11.1 Introduction to writing letters</a></li> + <li><a href="letters.html#tutorial">5.11.2 Tutorial on writing letters</a></li> + <li><a href="letters.html#letters-defaults">5.11.3 Default style for letters</a></li> + <li><a href="letters.html#index-letters-macros">5.11.4 The letter macros</a></li> + </ul></li> + </ul> + <h3 id="quick" class="toc highlight"><a style="color: #6e70cc" href="macrolist.html#top">6. QUICK REFERENCE GUIDE</a></h3> + <h3 id="appendices" class="toc" style="margin-top: .5em;"><a style="color: #6e70cc" href="appendices.html#top">7. APPENDICES</a></h3> + <ul class="toc"> + <li><a href="appendices.html#moredoc">7.1 Notes on the documentation</a></li> + <li><a href="appendices.html#fonts">7.2 Adding PostScript fonts to groff</a> + <ul> + <li><a href="appendices.html#howto">7.2.1 How to create a PostScript font for use with groff</a></li> + </ul></li> + <li><a href="appendices.html#codenotes">7.3 Some reflections on mom</a></li> + <li id="reserved"><a href="reserved.html#top">7.5 List of reserved words</a> + – complete list of macros, registers, strings, aliases and diversions</li> + <li><a href="appendices.html#contact">7.5 Contact the author</a></li> + </ul> + </div> + +</div> + +<div class="bottom-spacer"><br/></div> + +</body> +</html> + +<!-- vim: fileencoding=utf-8: nomodified: --> 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 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- +This file is part of groff, the GNU roff type-setting system. + +Copyright (C) 2004, 2005, 2006, 2009, 2010 Free Software Foundation, Inc. +Written by Peter Schaffter. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with the +Invariant Sections being this comment section, with no Front-Cover +Texts, and with no Back-Cover Texts. + +A copy of the Free Documentation License is included as a file called +FDL in the main directory of the groff source package. +--> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"> + +<head> + <meta http-equiv="content-type" content="text/html;charset=utf-8"/> + <title>Mom -- Typesetting Macros</title> + <link rel="stylesheet" type="text/css" href="stylesheet.css" /> +</head> + +<body style="background-color: #f5faff;"> + +<!-- ==================================================================== --> + +<div id="top" class="page"> + +<!-- Navigation links --> +<table style="width: 100%;"> +<tr> + <td><a href="toc.html">Back to Table of Contents</a></td> + <td style="text-align: right;"><a href="goodies.html#top">Next: Goodies</a></td> +</tr> +</table> + +<h1 id="typesetting" class="docs">The typesetting macros</h1> + +<div id="typesetting-macros-mini-toc" class="mini-toc"> +<div class="mini-toc-col-1"> +<ul class="no-enumerator"> + <li class="list-head"><a href="#typesetting-macros">Introduction</a></li> + <li class="list-head"><a href="#page-setup-intro">Paper and page setup</a> + <ul> + <li class="item"><a href="#page-setup-note"><i>Important note on page dimensions & papersize</i></a></li> + <li class="item"><a href="#index-page-setup">Macro list</a></li> + </ul></li> + <li class="list-head"><a href="#basic-params-intro">Basic typesetting parameters</a> + <ul> + <li class="item"><a href="#index-basic">Macro list</a></li> + </ul></li> + <li class="list-head"><a href="#justification-intro">Justification and quadding/ + <br/> + <span style="margin-left: 1em;">breaking and joining lines</span></a> + <ul> + <li class="item"><a href="#index-justification">Macro list</a></li> + </ul></li> + <li class="list-head"><a href="#refinements-intro">Typographic refinements</a> + <ul> + <li class="item"><a href="#index-refinements">Macro list</a></li> + </ul></li> + <li class="list-head"><a href="#modifications-intro">Type modifications (pseudo font styles)</a> + <ul class="no-enumerator"> + <li class="item"><a href="#index-modifications">Macro list</a></li> + </ul></li> + <li class="list-head"><a href="#aldrld-intro">Vertical movements</a> + <ul class="no-enumerator"> + <li class="item"><a href="#index-aldrld">Macro list</a> + </li> + </ul></li> +</ul> +</div> +<div class="mini-toc-col-2"> + <ul class="no-enumerator"> + <li class="list-head"><a href="#tabs-intro">Tabs</a> + <ul class="no-enumerator"> + <li class="item"><a href="#typesetting-tabs">Typesetting tabs</a> + <ul style="margin-left: -.5em;"> + <li class="item" style="margin-left: -.5em; list-style-type: circle;"><a href="#typesetting-tabs-tut">Quickie tutorial on typesetting tabs</a></li> + </ul></li> + <li class="item"><a href="#string-tabs">String tabs</a> + <ul style="margin-left: -.5em;"> + <li class="item" style="margin-left: -.5em; list-style-type: circle;"><a href="#string-tabs-tut">Quickie tutorial on string tabs</a></li> + </ul></li> + <li class="item"><a href="#index-tabs">Macro list</a></li> + </ul></li> + <li class="list-head"><a href="#multicolumns-intro">Multiple columns</a> + <ul class="no-enumerator"> + <li class="item"><a href="#index-multicolumns">Macro list</a> + </li> + </ul></li> + <li class="list-head"><a href="#indents-intro">Indents</a> + <ul class="no-enumerator"> + <li class="item"><a href="#indents-handling">How mom handles indents</a></li> + <li class="item"><a href="#index-indents">Macro list</a> + </li> + </ul></li> + <li class="list-head"><a href="goodies.html#goodies">Goodies</a> + <ul class="no-enumerator"> + <li class="item"><a href="goodies.html#goodies-macros">Macro list</a> + </li> + </ul></li> + <li class="list-head"><a href="inlines.html#top">Inline escapes</a> + <ul class="no-enumerator"> + <li class="item"><a href="inlines.html#index-inlines">List of inline escapes</a> + </li> + </ul></li> + <li class="list-head"><a href="color.html#colored-text-intro">Coloured text</a> + <ul class="no-enumerator"> + <li class="item"><a href="color.html#colored-text-macros">Macro list</a></li> + </ul></li> +</ul> +</div> +</div> + +<div class="rule-medium"><hr/></div> + +<h2 id="typesetting-intro" class="docs">Introduction</h2> + +<p> +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. +</p> + +<p> +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. +</p> + +<p> +Mom’s typesetting macros can be used as a standalone package, +independent of the +<a href="docprocessing.html#top">document processing macros</a>. +With them, you can typeset on-the-fly. Book covers, your best +friend’s résumé, a poster for a lost dog—none of these +requires structured document processing (page headers, paragraphs, +heads, footnotes, etc). What they do demand is precise control over +every element on the page. The typesetting macros give you that +control. +</p> + +<div class="rule-short" style="margin-bottom: 24px;"><hr/></div> + +<!-- ==================================================================== --> + +<h2 id="page-setup-intro" class="macro-group">Paper and page setup: paper size & page margins</h2> + +<p> +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 +<a href="docprocessing.html#docprocessing">document processing macros</a> +and are content with her defaults. +</p> + +<p> +The +<a href="#paper">PAPER</a> +macro provides a shortcut for setting the page to the correct +dimensions for a number of common paper sizes. The +<a href="#page">PAGE</a> +macro provides a convenient way of setting the page dimensions and +some or all of the page margins with a single macro. +</p> + +<div class="box-notes"> +<h3 id="page-setup-note" class="docs notes">Important note on page dimensions and papersize</h3> + +<p style="margin-top: .5em;"> +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. +</p> + +<p> +If you routinely print documents on the same size paper (you +probably do), the easiest way to make sure the PostScript driver +knows about your papersize is to edit the file +<br/> +<span class="pre-in-pp"> + <path to groff>/font/devps/DESC +</span> +In it, you will see a line that reads: +<span class="pre-in-pp"> + papersize <papersize> +</span> +Change <kbd><papersize></kbd> 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 <kbd>man papersize</kbd>). 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 +<a href="definitions.html#unitofmeasure">unit of measure</a> +appended. Valid units of measure for papersize are +inches (<kbd>i</kbd>), +centimeters (<kbd>c</kbd>), +picas (<kbd>P</kbd>) and +points (<kbd>p</kbd>). +For example, to set up a routine papersize of 8 inches by 10 inches, +the line would look like this: +<br/> +<span class="pre-in-pp"> + papersize 8i,10i +</span> +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 <kbd>-P-p<papersize></kbd> +option. +</p> + +<p> +For example, suppose your routine papersize is “letter”, +and you need to print something on a legal-sized sheet. After +telling mom about the legal-size sheet (with either +<a href="#pagelength">PAGELENGTH</a> +and +<a href="#pagewidth">PAGEWIDTH</a> +or +<a href="#paper">PAPER</a>, +or +<a href="#page">PAGE</a>) +in your mom file, when you invoke groff to process the file, the +command would look like this: +<br/> +<span class="pre-in-pp"> + groff -mom -P-plegal +</span> +</p> + +<p class="tip-bottom" style="margin-top: -1em;"> +Consult <kbd>man groff</kbd>, <kbd>man grops</kbd> and <kbd>man +groff-font</kbd> for additional information concerning papersizes, +as well as information on printing in “landscape” +orientation. +</p> +</div> + +<div class="macro-list-container"> +<h3 id="index-page-setup" class="macro-list">Paper and page setup macros</h3> + +<ul class="macro-list"> + <li><a href="#pagewidth">PAGEWIDTH</a> – page width</li> + <li><a href="#pagelength">PAGELENGTH</a> – page length</li> + <li><a href="#paper">PAPER</a> – common paper sizes</li> + <li><a href="#l-margin">L_MARGIN</a> – left margin</li> + <li><a href="#r-margin">R_MARGIN</a> – right margin</li> + <li><a href="#t-margin">T_MARGIN</a> – top margin</li> + <li><a href="#b-margin">B_MARGIN</a> – bottom margin</li> + <li><a href="#page">PAGE</a> – page dimensions and margins all in one fell swoop</li> + <li><a href="#newpage">NEWPAGE</a> – start a new page</li> +</ul> +</div> + +<!-- -PAGEWIDTH- --> + +<div class="macro-id-overline"> +<h3 id="pagewidth" class="macro-id">Page width</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>PAGEWIDTH</b> <kbd class="macro-args"><width of printer sheet></kbd> +</div> +<p class="requires"> +• Requires a <a href="definitions.html#unitofmeasure">unit of measure</a> +</p> + +<p> +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 +<br/> +<span class="pre-in-pp"> + .PAGEWIDTH 8.5i +</span> +Please read the +<a href="#page-setup-note">Important note on page dimensions and papersize</a> +for information on ensuring groff respects your +PAGEWIDTH. +</p> + +<!-- -PAGELENGTH- --> + +<div class="macro-id-overline"> +<h3 id="pagelength" class="macro-id">Page length</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>PAGELENGTH</b> <kbd class="macro-args"><length of printer sheet></kbd> +</div> +<p class="requires"> +• Requires a <a href="definitions.html#unitofmeasure">unit of measure</a> +</p> + +<p> +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 +<br/> +<span class="pre-in-pp"> + .PAGELENGTH 11i +</span> +Please read the +<a href="#page-setup-note">Important note on page dimensions and papersize</a> +for information on ensuring groff respects your PAGELENGTH. +</p> + +<!-- -PAPER- --> + +<div class="macro-id-overline"> +<h3 id="paper" class="macro-id">Paper</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>PAPER</b> <kbd class="macro-args"><paper type></kbd> +</div> + +<p> +PAPER provides a convenient way to set the page dimensions for some +common printer sheet sizes. <kbd><paper type></kbd> can +be one of: +<br/> +<span class="pre-in-pp"> + LETTER EXECUTIVE + LEGAL 10x14 + STATEMENT A3 + TABLOID A4 + LEDGER A5 + FOLIO B4 + QUARTO B5 +</span> +Say, for example, you have A4-sized sheets in your printer. It’s +shorter (and easier) to enter +<br/> +<span class="pre-in-pp"> + .PAPER A4 +</span> +than to remember the correct dimensions and enter +<br/> +<span class="pre-in-pp"> + .PAGEWIDTH 595p + .PAGELENGTH 842p +</span> +Please read the +<a href="#page-setup-note">Important note on page dimensions and papersize</a> +for information on ensuring groff respects your PAPER size. +</p> + +<!-- -L_MARGIN- --> + +<div class="macro-id-overline"> +<h3 id="l-margin" class="macro-id">Left margin</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>L_MARGIN</b> <kbd class="macro-args"><left margin></kbd> +</div> +<p class="requires"> +• Requires a <a href="definitions.html#unitofmeasure">unit of measure</a> +</p> + +<p> +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. +</p> + +<p> +<a href="#il">Left indents</a> +and +<a href="#tabs">tabs</a> +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 +<br/> +<span class="pre-in-pp"> + .L_MARGIN 3P +</span> +or +<span class="pre-in-pp"> + .L_MARGIN .5i +</span> +If you use the macros +<a href="#page">PAGE</a>, +<a href="#pagewidth">PAGEWIDTH</a> +or +<a href="#paper">PAPER</a> +without invoking L_MARGIN (either before or afterwards), mom +automatically sets L_MARGIN to 1 inch. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> L_MARGIN behaves in a special way +when you’re using the +<a href="docprocessing.html#docprocessing">document processing macros</a>. +See +<a href="docprocessing.html#behaviour">Typesetting macros during document processing</a> +for an explanation. +</p> +</div> + +<!-- -R_MARGIN- --> + +<div class="macro-id-overline"> +<h3 id="r-margin" class="macro-id">Right margin</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>R_MARGIN</b> <kbd class="macro-args"><right margin></kbd> +</div> +<p class="requires"> +• Requires a <a href="definitions.html#unitofmeasure">unit of measure</a> +</p> + +<div class="box-important"> +<p class="tip"> +<span class="important">IMPORTANT:</span> R_MARGIN, if used, must +come after +<a href="#paper">PAPER</a>, +<a href="#pagewidth">PAGEWIDTH</a>, +<a href="#l-margin">L_MARGIN</a> +and/or +<a href="#page">PAGE</a> +(if a right margin isn’t given to 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. +</p> +</div> + +<p> +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. +</p> + +<p> +The line length macro +(<a href="#linelength">LL</a>) +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. +</p> + +<p> +For example, if you’re setting a page of type you know should +have 6-pica margins left and right, it makes sense to enter a left +and right margin, like this: +<br/> +<span class="pre-in-pp"> + .L_MARGIN 6P + .R_MARGIN 6P +</span> +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. +<br/> +<span class="pre-in-pp"> + .LL 17P+3p +</span> +If you use the macros +<a href="#page">PAGE</a>, +<a href="#pagewidth">PAGEWIDTH</a> +or +<a href="#paper">PAPER</a> +without invoking <kbd>.R_MARGIN</kbd> afterwards, mom automatically +sets R_MARGIN to 1 inch. If you set a line length after these +macros (with +<a href="#linelength">LL</a>), +the line length calculated by R_MARGIN is, of course, overridden. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> R_MARGIN behaves in a special way when you’re +using the +<a href="docprocessing.html#docprocessing">document processing macros</a>. +See +<a href="docprocessing.html#behaviour">Typesetting macros during document processing</a> +for an explanation. +</p> +</div> + +<!-- -T_MARGIN- --> + +<div class="macro-id-overline"> +<h3 id="t-margin" class="macro-id">Top margin</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>T_MARGIN</b> <kbd class="macro-args"><top margin></kbd> +</div> +<p class="requires"> +• Requires a <a href="definitions.html#unitofmeasure">unit of measure</a> +</p> + +<p> +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 +<br/> +<span class="pre-in-pp"> + .T_MARGIN 2.5c +</span> +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 +<a href="definitions.html#baseline">baseline</a>. Therefore, +<br/> +<span class="pre-in-pp"> + .T_MARGIN 1.5i +</span> +puts the baseline of the first line of type 1-1/2 inches beneath the +top of the page. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> T_MARGIN means something slightly +different when you’re using the +<a href="docprocessing.html#docprocessing">document processing macros</a>. +See +<a href="docprocessing.html#tb-margins">Top and bottom margins in document processing</a> +for an explanation. +</p> +</div> + +<div class="box-important"> +<p class="tip"> +<span class="important">IMPORTANT:</span> T_MARGIN does two +things: it establishes the top margin for pages that come after +it <i>and</i> 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 +<a href="#newpage">NEWPAGE</a>, +like this: +<br/> +<span class="pre-in-pp" style="margin-bottom: -1em;"> + .NEWPAGE + .T_MARGIN 6P + <text> +</span> +</p> +</div> + +<!-- -B_MARGIN- --> + +<div class="macro-id-overline"> +<h3 id="b-margin" class="macro-id">Bottom margin</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>B_MARGIN</b> <kbd class="macro-args"><bottom margin></kbd> +</div> +<p class="requires"> +• Requires a <a href="definitions.html#unitofmeasure">unit of measure</a> +</p> + +<p> +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 +<br/> +<span class="pre-in-pp"> + .B_MARGIN .75i +</span> +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. +</p> + +<p> +Occasionally, owing to a peculiarity in groff, an extra line will +fall below the nominal bottom margin. If you’re using the +<a href="docprocessing.html#docprocessing">document processing macros</a>, +this is unlikely to happen; the document processing macros are very +hard-nosed about aligning bottom margins. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> The meaning of B_MARGIN is slightly +different when you’re using the document processing macros. +See +<a href="docprocessing.html#tb-margins">Top and bottom margins in document processing</a> +for an explanation. +</p> +</div> + +<!-- -PAGE- --> + +<div class="macro-id-overline"> +<h3 id="page" class="macro-id">Page</h3> +</div> + +<div class="box-macro-args" style="overflow: auto;"> +Macro: <b>PAGE</b> <kbd class="macro-args"><width> [ <length> [ <lm> [ <rm> [ <tm> [ <bm> ] ] ] ] ]</kbd> +</div> +<p class="requires"> +• All arguments require a <a href="definitions.html#unitofmeasure">unit of measure</a> +</p> + +<div class="box-important"> +<p class="tip"> +<span class="important">IMPORTANT:</span> If you’re using the +<a href="docprocessing.html#docprocessing">document processing macros</a>, +PAGE must come after +<a href="docprocessing.html#start">START</a>. +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 +<a href="docprocessing.html#tb-margins">Top and bottom margins in document processing</a>). +</p> +</div> + +<p> +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. <kbd><lm>, <rm>, <tm></kbd> and +<kbd><bm></kbd> refer to the left, right, top and bottom +margins respectively. +</p> + +<p> +Assuming your page dimensions are 11 inches by 17 inches, and +that’s all you want to set, enter +<br/> +<span class="pre-in-pp"> + .PAGE 11i 17i +</span> +If you want to set the left margin as well, say, at 1 inch, PAGE +would look like this: +<br/> +<span class="pre-in-pp"> + .PAGE 11i 17i 1i +</span> +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: +<br/> +<span class="pre-in-pp"> + .PAGE 11i 17i 1i 1i 1.5i + | | + required right---+ +---top margin + margin +</span> +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 +<br/> +<span class="pre-in-pp"> + .PAGE 8.5i 11i 45p 45p 45p 45p +</span> +This sets up an 8-1/2 by 11 inch page with margins of 45 points +(5/8-inch) all around. +</p> + +<p> +Additionally, if you invoke <kbd>.PAGE</kbd> with a top margin +argument, any macros you invoke after <kbd>.PAGE</kbd> will almost +certainly move the +<a href="definitions.html#baseline">baseline</a> +of the first line of text down by one linespace. To compensate, do +<br/> +<span class="pre-in-pp"> + .RLD 1v +</span> +immediately before entering any text, or, if it’s feasible, +make PAGE the last macro you invoke prior to entering text. +</p> + +<p> +Please read the +<a href="#page-setup-note">Important note on page dimensions and papersize</a> +for information on ensuring groff respects your PAGE dimensions and +margins. +</p> + +<!-- -NEWPAGE- --> + +<div class="macro-id-overline"> +<h3 id="newpage" class="macro-id">Start a new page</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>NEWPAGE</b> +</div> + +<p> +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 +<a href="#t-margin">T_MARGIN</a>). +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="experts">Experts:</span> +Prior to version 1.1.9, NEWPAGE was simply an alias of +<kbd>.bp</kbd>. 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 <kbd>.bp</kbd> whenever you wanted to +break to a new page, you now begin to use NEWPAGE instead. +</p> +</div> + +<div class="rule-short" style="margin-bottom: 24px;"><hr/></div> + +<!-- ==================================================================== --> + +<h2 id="basic-params-intro" class="macro-group">Basic typesetting parameters</h2> + +<p> +The basic typesetting parameter macros deal with fundamental +requirements for setting type: family, font, point size, leading and +line length. +</p> + +<p> +If you’re using the typesetting macros only, the arguments +passed to the basic parameter macros remain in effect until +you change them. The document processing macros handle things +differently. See +<a href="docprocessing.html#behaviour">Typesetting macros during document processing</a> +for an explanation. +</p> + +<div id="index-basic" class="macro-list-container"> +<h3 class="macro-list">Basic parameter macros</h3> +<ul class="macro-list"> + <li><a href="#family">FAMILY</a> – type family</li> + <li><a href="#font">FT</a> – font</li> + <li><a href="#fallback-font">FALLBACK_FONT</a> – for invalid fonts</li> + <li><a href="#ps">PT_SIZE</a> – point size of type</li> + <li><a href="#leading">LS</a> – line spacing/leading</li> + <li><a href="#autolead">AUTOLEAD</a> – automatic line spacing</li> + <li><a href="#linelength">LL</a> – line length</li> +</ul> +</div> + +<!-- -FAMILY- --> + +<div class="macro-id-overline"> +<h3 id="family" class="macro-id">Type family</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>FAMILY</b> <kbd class="macro-args"><family></kbd> +</div> +<p class="alias"> +<i>Alias:</i> <b>FAM</b> +</p> + +<p> +FAMILY takes one argument: the name of the +<a href="definitions.html#family">family</a> +you want. Groff comes with a number of PostScript families, each +identified by a 1-, 2-or 3-letter mnemonic. The standard families +are: +<br/> +<span class="pre-in-pp"> + A = Avant Garde + BM = Bookman + H = Helvetica + HN = Helvetica Narrow + N = New Century Schoolbook + P = Palatino + T = Times Roman + ZCM = Zapf Chancery +</span> +The argument you pass to FAMILY is the identifier at left, above. +For example, if you want Helvetica, enter +<br/> +<span class="pre-in-pp"> + .FAMILY H +</span> +</p> + +<div class="box-tip" style="margin-top: -1em;"> +<p class="tip-top"> +<span class="note">Note:</span> The font macro +(<a href="#font">FT</a>) +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. <kbd>ZCM</kbd>, for example, +only exists in one style: Italic (<kbd>I</kbd>). Therefore, +<kbd>.FT ZCMI</kbd> makes more sense than setting the family to +<kbd>ZCM</kbd>, then setting the font to <kbd>I</kbd>. +</p> + +<p id="fam-add-note" class="tip-bottom"> +<span class="additional-note">Additional note:</span> 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 +<a href="#fallback-font">fallback font</a>. +</p> +</div> + +<p style="margin-top: -.5em;"> +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: +<br/> +<span class="pre-in-pp"> + .FAMILY BM \" Bookman family + .FT I \" Medium Italic + <some text> \" Bookman Medium Italic + .FAMILY H \" Helvetica family + <more text> \" Helvetica Medium Italic +</span> +However, if the font style does not exist in the new family, mom +will set all subsequent type in the +<a href="#fallback-font">fallback font</a> +(by default, Courier Medium Roman) until she encounters a +<a href="#font">.FT</a> +request that’s valid for the family. For example, assuming +you don’t have the font “Medium Condensed Roman” +(mom extension “CD”) in the Helvetica family: +<br/> +<span class="pre-in-pp"> + .FAMILY UN \" Univers family + .FT CD \" Medium Condensed + <some text> \" Univers Medium Condensed + .FAMILY H \" Helvetica family + <more text> \" Courier Medium Roman! +</span> +In the above example, you must follow +<kbd>.FAMILY H</kbd> with a FT request +that’s valid for Helvetica. +</p> + +<p> +Please see the Appendices, +<a href="appendices.html#fonts">Adding PostScript fonts to groff</a>, +for information on adding fonts and families to groff, as well as +to see a list of the extensions mom provides to groff’s basic +<b>R</b>, <b>I</b>, <b>B</b>, <b>BI</b> styles. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="experts">Experts:</span> 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 +<br/> +<span class="pre-in-pp"> + GARAMONDR + GARAMONDI + GARAMONDB + GARAMONDBI +</span> +GARAMOND then becomes a valid family name you can pass to FAMILY. +(You could, of course, shorten GARAMOND to just G, or GD.) <b>R</b>, +<b>I</b>, <b>B</b>, and <b>BI</b> after GARAMOND are the roman, +italic, bold and bold-italic fonts respectively. +</p> +</div> + +<!-- -FT- --> + +<div class="macro-id-overline"> +<h3 id="font" class="macro-id">FT</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>FT</b> <kbd class="macro-args">R | I | B | BI | <any other valid font style></kbd> +</div> +<p class="alias"> +<i>Alias:</i> <b>FONT</b> +</p> + +<p> +By default, groff permits FT to take one of four possible arguments +specifying the desired font: +<br/> +<span class="pre-in-pp"> + R = (Medium) Roman + I = (Medium) Italic + B = Bold (Roman) + BI = Bold Italic +</span> +For example, if your +<a href="definitions.html#family">family</a> +is Helvetica, entering +<br/> +<span class="pre-in-pp"> + .FT B +</span> +will give you the Helvetica bold +<a href="definitions.html#font">font</a>. +If your family were Palatino, you’d get the Palatino bold +font. +</p> + +<p> +(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 +<a href="definitions.html#weight">weights</a> +and +<a href="definitions.html#shape">shapes</a>. +Please see the +<kbd><a href="#font-note">NOTE</a></kbd>, +below.) +</p> + +<p> +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 +<a href="#fallback-font">fallback font</a>, +either continue processing using the fallback font, or abort +(allowing you to correct the problem). If your groff version is +less than 1.19.2, mom will silently continue processing, using +either the fallback font or the font that was in effect prior to the +invalid FT call. +</p> + +<p> +FT will also accept, as an argument, a full family+font name. For +example, +<br/> +<span class="pre-in-pp"> + .FT HB +</span> +will set subsequent type in Helvetica Bold. However, I strongly +recommend keeping family and font separate except where doing so is +genuinely inconvenient. +</p> + +<p> +For inline control of fonts, see +<a href="inlines.html#inline-fonts-mom">Inline Escapes, font control</a>. +</p> + +<div id="font-note" class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> 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 +<a href="definitions.html#weight">weights</a> +and +<a href="definitions.html#shape">shapes</a> +within the same family. Have a look +<a href="appendices.html#style-extensions">here</a> +for a list of the weight/style arguments mom +allows. +</p> +</div> + +<p> +Be aware, though, that you must have the fonts, correctly installed +and named, in order to use the arguments. (See +<a href="appendices.html#howto">How to create a PostScript font for use with groff</a> +for how to add fonts to groff.) Please also read the +<a href="#fam-add-note">ADDITIONAL NOTE</a> +found in the description of the FAMILY macro. +</p> + +<!-- -FALLBACK_FONT- --> + +<div class="macro-id-overline"> +<h3 id="fallback-font" class="macro-id">Fallback font</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>FALLBACK_FONT</b> <kbd class="macro-args"><fallback font> [ ABORT | WARN ]</kbd> +</div> + +<p> +In the event that you pass an invalid argument to +<a href="#font">.FAMILY</a> +(i.e. a non-existent family), mom, by default, uses the fallback +font, Courier Medium Roman (CR), in order to continue processing +your file. +</p> + +<p> +If you’d prefer another fallback font, pass 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, +<br/> +<span class="pre-in-pp"> + .FALLBACK_FONT TR +</span> +would do the trick. +</p> + +<p> +Additionally, if your version of groff accepts accepts ”<kbd>.if +F</kbd>” and ”<kbd>.if S</kbd>” (see +<a href="#fam-add-note">above</a>), +mom issues a warning whenever a font style set with +<a href="#font">FT</a> +does not exist, either because you haven’t registered the +style (see +<a href="appendices.html#register-style">here</a> +for instructions on registering styles), or because the font style +does not exist in the current family set with +<a href="#family">FAMILY</a>. +By default, mom then aborts, which allows you to correct the +problem. +</p> + +<p> +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 <kbd>WARN</kbd>, either by itself, or in +conjunction with your chosen fallback font. +</p> + +<p> +Some examples of invoking FALLBACK_FONT: +</p> + +<ul class="no-enumerator" style="margin-left: -1em;"> +<li style="margin-top: -.5em;"> +<kbd>.FALLBACK_FONT WARN</kbd> +<br/> +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. +<br/> +</li> +<li style="margin-top: .5em;"> +<kbd>.FALLBACK_FONT TR WARN</kbd> +<br/> +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. +</li> +<li style="margin-top: .5em;"> +<kbd>.FALLBACK_FONT TR ABORT</kbd> +<br/> +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. +</li> +</ul> + +<p> +If, for some reason, you want to revert to ABORT, just enter +<kbd>.FALLBACK_FONT ABORT</kbd> and mom will once again abort +on font errors. +</p> + +<!-- -PT_SIZE- --> + +<div class="macro-id-overline"> +<h3 id="ps" class="macro-id">Point size of type</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>PT_SIZE</b> <kbd class="macro-args"><size of type in points></kbd> +</div> +<p class="requires"> +• Does not require a <a href="definitions.html#unitofmeasure">unit of measure</a> +</p> + +<p> +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 +<br/> +<span class="pre-in-pp"> + .PT_SIZE 11 +</span> +Point sizes may be fractional (e.g. 10.25 or 12.5). +</p> + +<p> +You can prepend a plus or a minus sign to the argument to 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 +<br/> +<span class="pre-in-pp"> + .PT_SIZE +2 +</span> +then later reset it to 12 with +<span class="pre-in-pp"> + .PT_SIZE -2 +</span> +The size of type can also be changed inline. See +<a href="inlines.html#inline-size-mom">Inline Escapes, changing point size</a>. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> It is unfortunate that the +<kbd>pic</kbd> preprocessor has already taken the name, +<kbd>PS</kbd>, and thus mom’s macro for setting point +sizes can’t use it. However, if you aren’t using +<kbd>pic</kbd>, you might want to +<a href="goodies.html#alias">alias</a> +PT_SIZE as PS, since there’d be no conflict. For example +<br/> +<span class="pre-in-pp"> + .ALIAS PS PT_SIZE +</span> +would allow you to set point sizes with <kbd>.PS</kbd>. +</p> +</div> + +<!-- -LS- --> + +<div class="macro-id-overline"> +<h3 id="leading" class="macro-id">Line spacing/leading</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>LS</b> <kbd class="macro-args"><distance between lines></kbd> +</div> +<p class="requires"> +• Does not require a <a href="definitions.html#unitofmeasure">unit of measure</a> +</p> + +<p> +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 +<a href="definitions.html#leading">leading</a> +is most often given in points. Therefore, to set the linespace to +14 points, you would enter +<br/> +<span class="pre-in-pp"> + .LS 14 +</span> +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 +<br/> +<span class="pre-in-pp"> + .LS .25i +</span> +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 +<br/> +<span class="pre-in-pp"> + .LS +3 +</span> +then later reset it to 14 points with +<br/> +<span class="pre-in-pp"> + .LS -3 +</span> +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="experts">Experts:</span> LS should not be confused with +the groff primitive <kbd>.ls</kbd>. LS acts like +<kbd>.vs</kbd>. mom does not provide a macro analogous to +<kbd>.ls</kbd>. +</p> +</div> + +<!-- -AUTOLEAD- --> + +<div class="macro-id-overline"> +<h3 id="autolead" class="macro-id">Automatic line spacing</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>AUTOLEAD</b> <kbd class="macro-args"><amount of automatic leading> [FACTOR]</kbd> +</div> +<p class="requires"> +• Does not require a <a href="definitions.html#unitofmeasure">unit of measure</a> +</p> + +<p> +Without the <kbd>FACTOR</kbd> argument, AUTOLEAD calculates the +linespace for you by adding its argument to the current point size +of type. All subsequent +<a href="#ps">PT_SIZE</a> +requests automatically update the linespacing by the autolead amount. +</p> + +<p> +Used in this way, 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). +</p> + +<p> +As an example, if your current point size of type is 12, entering +<br/> +<span class="pre-in-pp"> + .AUTOLEAD 2 +</span> +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 +<a href="definitions.html#inlines">inline</a>) +changes the linespace as well. If you decrease the type size to 9 +points, the leading decreases to 11 points. If you increase the +type size to 16 points, the leading increases to 18 points. +</p> + +<p> +Automatic updating of the linespacing continues until you enter a +“manual” line space value with +<a href="#leading">LS</a>. +</p> + +<p> +If you give AUTOLEAD the optional FACTOR argument, AUTOLEAD +calculates the line space as a factor of the +<a href="definitions.html#numericargument">numeric argument</a> +you gave AUTOLEAD. For example, if your point size is 12, +<br/> +<span class="pre-in-pp"> + .AUTOLEAD 1.125 FACTOR +</span> +sets the leading at 13.5 points. If you change the point size to +14, the leading automatically changes to 15.75 (14 x 1.125). +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> There’s no need to prepend a +plus sign +(<kbd>+</kbd>) +to AUTOLEAD’s argument, although you may do so if you wish. +</p> +</div> + +<!-- -LL- --> + +<div class="macro-id-overline"> +<h3 id="linelength" class="macro-id">Line length</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>LL</b> <kbd class="macro-args"><line length></kbd> +</div> +<p class="requires"> +• Requires a <a href="definitions.html#unitofmeasure">unit of measure</a> +</p> + +<p> +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. +</p> + +<p> +LL requires a unit of measure. Therefore, to set the line length to +39 picas, you would enter +<br/> +<span class="pre-in-pp"> + .LL 39P +</span> +As with other macros that require a unit of measure, the argument to +LL may be fractional. For example, +<br/> +<span class="pre-in-pp"> + .LL 4.5i +</span> +sets the line length to 4-1/2 inches. +</p> + +<p> +Additionally, you may express a new line length relative to the +current line length by prepending a plus or minus sign to the +argument. Thus, if you wanted to increase the line length by 3 +<a href="definitions.html#picaspoints">points</a>, you could +do +<br/> +<span class="pre-in-pp"> + .LL +3p +</span> +This is especially handy when you want to “hang” +punctuation outside the right margin since you can pass +groff’s +<a href="inlines.html#inline-stringwidth-groff"><kbd>\w</kbd></a> +escape as the argument to LL, like this: +<br/> +<span class="pre=in-pp"> + .LL +\w'.'u +</span> +The above example increases the current line length by the width of +a period. Notice that you must append the +<a href="definitions.html#unitofmeasure">unit of measure</a>, +<b>u</b>, to the escape since LL requires a unit of measure. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> The right margin macro, +<a href="#r-margin">(R_MARGIN)</a>, +can also be used to set line length. +</p> +</div> + +<div class="rule-short"><hr/></div> + +<!-- ==================================================================== --> + +<h2 id="justification-intro" class="macro-group">Justification and quadding/breaking and joining lines</h2> + +<p> +The justification and quadding macros deal with how type aligns +along the left and right margins. In a nutshell, type either aligns +at the left margin, at the right margin, at both margins, or at +neither margin (centred). +</p> + +<p> +These macros also determine whether or not +<a href="definitions.html#inputline">input lines</a> +are joined and +<a href="definitions.html#filled">filled</a> +during output. +</p> + +<p> +Additionally, macros that deal with how to break +<a href="definitions.html#outputline">output lines</a> +are covered in this section, as is the +<a href="definitions.html#inlines">inline escape</a> +for joining input lines. +</p> + +<p> +You may encounter some words here that are unfamiliar. Refer to +<a href="definitions.html#typesetting">Typesetting terms</a> +and +<a href="definitions.html#groff">Groff terms</a> +for an explanation. +</p> + +<div id="index-justification" class="macro-list-container"> +<h3 class="macro-list">Justification and quadding/breaking and joining lines macros</h3> +<ul class="macro-list"> + <li>Fill modes + <ul style="list-style-type: none; margin-left: -1em;"> + <li><a href="#justify">JUSTIFY</a> – set lines justified</li> + <li><a href="#quad">QUAD</a> – set filled lines flush left, right or centred</li> + </ul></li> + <li>Nofill modes + <ul style="list-style-type: none; margin-left: -1em;"> + <li><a href="#lrc">LEFT</a> – set non-filled lines flush left</li> + <li><a href="#lrc">RIGHT</a> – set non-filled lines flush right</li> + <li><a href="#lrc">CENTER</a> – set non-filled lines centred</li> + </ul></li> + <li>Breaking lines + <ul style="list-style-type: none; margin-left: -1em;"> + <li><a href="#br">BR</a> – manually break an output line</li> + <li><a href="#el">EL</a> – break a line without advancing to the next output line</li> + <li><a href="#space">SPACE</a> – break a line and add space before the next output line</li> + <li><a href="#spread">SPREAD</a> – break and force-justify an output line</li> + </ul></li> + <li>Joining input lines in <a href="definitions.html#filled">nofill mode</a> + <ul style="list-style-type: none; margin-left: -1em;"> + <li><a href="#join">\c</a> inline escape</li> + </ul></li> +</ul> +</div> + +<!-- -JUSTIFY- --> + +<div class="macro-id-overline"> +<h3 id="justify" class="macro-id">Justify lines</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>JUSTIFY</b> +</div> + +<p class="requires"> +(See +<a href="definitions.html#filled">fill mode</a> +for a definition of the difference between “fill” and +“no-fill” modes.) +</p> + +<p> +JUSTIFY doesn’t take an argument. +<a href="definitions.html#inputline">Input lines</a> +after JUSTIFY are +<a href="definitions.html#filled">filled</a> +and +<a href="definitions.html#just">justified</a> +upon output. +</p> + +<p> +To break lines and prevent them from being filled and justified, use +the +<a href="#br">BR</a> +macro. +</p> + +<!-- -QUAD- --> + +<div class="macro-id-overline"> +<h3 id="quad" class="macro-id">Quad lines left, right, or centre</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>QUAD</b> <kbd class="macro-args">L | LEFT | R | RIGHT | C | CENTER | J | JUSTIFY</kbd> +</div> + +<p class="alias" style="margin-bottom: 0;"> +<i>Alias:</i> <b>FILL</b> +</p> + +<p class="requires">(See +<a href="definitions.html#filled">fill mode</a> +for a definition of the difference between “fill” and +“no-fill” modes.) +</p> + +<p> +QUAD takes one argument: the direction in which lines should be +<a href="definitions.html#quad">quadded</a>. +<a href="definitions.html#inputline">Input lines</a> +after QUAD are +<a href="definitions.html#filled">filled</a> +upon output. +</p> + +<p> +If <kbd>L</kbd> or <kbd>LEFT</kbd>, type is set flush along the left +margin. +</p> + +<p> +If <kbd>R</kbd> or <kbd>RIGHT</kbd>, type is set flush along the +right margin. +</p> + +<p> +If <kbd>C</kbd> or <kbd>CENTER</kbd> type is set centred on the +current line length. +</p> + +<p> +<kbd>J</kbd> and <kbd>JUSTIFY</kbd> justify text, and are +included as a convenience only. Obviously, if text is +justified, it isn’t quadded. <kbd>.QUAD J</kbd> and +<kbd>.QUAD JUSTIFY</kbd> have exactly the same effect as +<a href="#justify">JUSTIFY</a>. +</p> + +<p> +To break lines and prevent them from being filled, use the +<a href="#br">BR</a> +macro. +</p> + +<!-- -LEFT, RIGHT, CENTER- --> + +<div class="macro-id-overline"> +<h3 id="lrc" class="macro-id">Set lines flush left, right or centered in no-fill mode</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>LEFT</b> +<br/> +Macro: <b>RIGHT</b> +<br/> +Macro: <b>CENTER</b> (alias CENTRE) +</div> + +<p class="requires"> +(See +<a href="definitions.html#filled">no-fill mode</a> +for a definition of the difference between “fill” and +“no-fill” modes.) +</p> + +<p> +LEFT, RIGHT and CENTER let you enter text on a line for line basis +without having to use the +<a href="#br">BR</a> +macro after each line. Consider the following: +<br/> +<span class="pre-in-pp"> + .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 +</span> +Because text after <kbd>.QUAD LEFT</kbd> is +<a href="definitions.html#filled">filled</a>, +you have to use the +<a href="#br">BR</a> +macro to prevent the lines from running together. Not only is this +annoying to type, it’s awkward to read in a text editor. Much +better to do +<br/> +<span class="pre-in-pp"> + .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. +</span> +</p> + +<div class="box-important" style="margin-top: -.5em;"> +<p class="tip"> +<span class="important">IMPORTANT:</span> Because LEFT, +RIGHT and CENTER are nofill modes, groff does not always respect the +current line length. +<a href="definitions.html#inputline">Input lines</a> +that run long may exceed it, or get broken in undesirable ways. +Therefore, when using these three macros, you should preview your +work to ensure that all lines fit as expected. +</p> +</div> + +<!-- -BR- --> + +<div class="macro-id-overline"> +<h3 id="br" class="macro-id">Manually break lines</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>BR</b> +</div> + +<p> +When using +<a href="#justify">JUSTIFY</a> +or +<a href="#quad">QUAD</a>, +BR tells mom about partial lines that you want broken (as opposed to +<a href="definitions.html#filled">filled</a>). +Any partial +<a href="definitions.html#outputline">output line</a> +that immediately precedes BR will be +<a href="definitions.html#quad">quadded</a> +in the direction of the current quad, or set flush left if text is +<a href="definitions.html#just">justified</a>. +</p> + +<p> +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. +</p> + +<div class="box-tip"> +<p class="tip-top"> +<span class="note">Note:</span> Lines of text in +<a href="definitions.html#filled">nofill mode</a> +never require a BR. Furthermore, in nofill mode, ALL macros cause a +break. If a break is not desired, use the +<a href="#join"><kbd>\c</kbd></a> +<a href="definitions.html#inlines">inline escape</a>. +</p> + +<p class="tip-bottom" style="margin-top: -1em"> +<span class="experts">Experts:</span> BR is an alias for +<kbd>.br</kbd>. You can use either, or mix +’n’ match with impunity. +</p> +</div> + +<!-- -EL- --> + +<div class="macro-id-overline"> +<h3 id="el" class="macro-id">Manually break a line without advancing on the page</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>EL</b> +</div> + +<p class="requires"> +In nofill modes +<span style="font-style: normal;"> +(<a href="#left">LEFT</a>, +<a href="#right">RIGHT</a>, +<a href="#center">CENTER</a>) +</span> +you must terminate the line input preceding +<span style="font-style: normal;">EL</span> +with the +<span style="font-style: normal;"> +<kbd>\c</kbd> inline escape. +</span> +See +<span style="font-style: normal;"> +<a href="#el-notes">NOTES</a>, +</span> +below. +</p> + +<p style="margin-top: -.5em"> +<i><b>Suggestion:</b> If you find remembering whether to put in the</i> +<kbd>\c</kbd> +<i>bothersome, you may prefer to use the</i> +<a href="definitions.html#inlines">inline escape</a> +<i>alternative to</i> EL, +<a href="inlines.html#b"><kbd>\*[B]</kbd></a>, +<i>which works consistently regardless of the fill mode. +</i>EL <i>does not work after the</i> +<a href="goodies.html#pad">PAD</a> +<i>macro. See</i> +<a href="goodies.html#nobreak"><kbd>.PAD NOBREAK</kbd></a> +<i>for the way around this.</i> +</p> + +<p> +The mnemonic “EL” is borrowed from old Compugraphic +typesetting systems, where it stood for +"<span style="text-decoration: underline;">E</span>nd <span style="text-decoration: underline;">L</span>ine." +Conceptually, EL is equivalent to the notion of a carriage return +with no linefeed. +</p> + +<p id="el-example"> +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: +<br/> +<span class="pre-in-pp"> + .LEFT + .LS 12.5 + A line of text.\c + .EL + .ALD 24p + The next line of text. +</span> +may be more intuitive than +<br/> +<span class="pre-in-pp"> + .LEFT + .LS 12.5 + A line of text. + .ALD 11.5p + The next line of text. +</span> +The first example has the further advantage that should you wish to +change the prevailing line space but keep the 24 points lead, you +don’t have to recalculate the extra space. +</p> + +<p> +ALD in the above examples stands for +“<span style="text-decoration: underline;">A</span>dvance +<span style="text-decoration: underline;">L</span>ea<span style="text-decoration: underline;">D</span>” +(another mnemonic borrowed from Compugraphic), which is covered in +the section +<a href="#vertical-movements-intro">Vertical movements</a>. +</p> + +<div class="box-notes"> +<h3 id="el-notes" class="docs notes">Notes</h3> + +<p style="margin-top: .5em;"> +In versions of mom prior to 1.1.9, EL did not always work as +advertised on the last +<a href="definitions.html#outputline">output line</a> +of pages that contained a footer trap (e.g. one set with +<a href="#b-margin">B_MARGIN</a> +or in documents formatted using the +<a href="docprocessing.html#docprocessing">document processing macros</a>). +</p> + +<p> +EL has been re-written so that this should no longer be the case. +However, in order for it to work in the +<a href="definitions.html#filled">nofill</a> +modes +(<a href="#lrc">LEFT</a>, +<a href="#lrc">RIGHT</a> +or +<a href="#lrc">CENTER</a>), +you must always “join” <kbd>.EL</kbd> to +the line before it using the +<kbd><a href="#join">\c</a></kbd> +<a href="definitions.html#inlines">inline escape</a>, +like this: +<br/> +<span class="pre-in-pp"> + .LEFT + A line I don’t want to advance\c + .EL +</span> +Conversely, in +<a href="definitions.html#filled">fill modes</a> +(<a href="#quad">QUAD LEFT</a>, +<a href="#quad">QUAD RIGHT</a>, +<a href="#quad">QUAD CENTER</a> +or +<a href="#justify">JUSTIFY</a>), +the <kbd>\c</kbd> must not be used. +</p> + +<p> +If EL is used after most macros or groff +<a href="definitions.html#primitives">primitives</a> +(see the exception, below), you don’t have to worry about +this, regardless of the fill mode. Just type +<kbd>.EL</kbd> +</p> + +<p class="tip-bottom"> +<span class="experts">Experts:</span> EL is unrelated to +groff’s <kbd>.el</kbd>. If you find the similarity confusing, +you may want to alias EL as something else (but don’t use EOL; +mom uses it internally.) +</p> +</div> + +<!-- -SP- --> + +<div class="macro-id-overline"> +<h3 id="space" class="macro-id">Break lines and add space between</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>SPACE</b> <kbd class="macro-args"><space to add between lines></kbd> +</div> +<p class="alias"> +<i>Alias:</i> <b>SP</b> +</p> + +<p> +SPACE breaks a line, just like +<a href="#br">BR</a>, +then adds space after the line. With no argument, it adds an extra +line space of a value equal to the current +<a href="definitions.html#leading">leading</a>. +If you pass it a numeric argument without supplying a +<a href="definitions.html#unitofmeasure">unit of measure</a>, +it advances that number of extra line spaces. For example: +<br/> +<span class="pre-in-pp"> + .SPACE +</span> +breaks the line then adds an extra linespace, whereas +<br/> +<span class="pre-in-pp"> + .SPACE 2 +</span> +breaks the line and adds two extra linespaces. +</p> + +<p> +If you supply a unit of measure, SPACE breaks the line then advances +one linespace (at the current +<a href="definitions.html#leading">leading</a>) +PLUS the specified amount of extra space given to SPACE, as in +<br/> +<span class="pre-in-pp"> + .SPACE 6p +</span> +which breaks the line and advances one full linespace plus six +points. +</p> + +<div class="box-tip"> +<p class="tip-top"> +<span class="tip">Tip:</span> SPACE and +<a href="#ald">ALD</a> +can be used interchangeably (<kbd>.SPACE 6p</kbd> and +<kbd>.ALD 6p</kbd> 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. +</p> + +<p class="tip-bottom"> +<span class="experts">Experts:</span> SPACE is an alias of +<kbd>.sp</kbd>. You can use either, or mix ’n’ match +with impunity. +</p> +</div> + +<!-- -SPREAD- --> + +<div class="macro-id-overline"> +<h3 id="spread" class="macro-id">Break and force justify (spread) lines</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>SPREAD</b> +</div> + +<p> +Sometimes, you need to break a line of +<a href="definitions.html#just">justified</a> +text and have it come out fully justified, not +<a href="definitions.html#quad">quadded</a> +left the way it would be with the +<a href="#br">BR</a> +macro. An example of where you’d do this would be when you +want to prevent a word at the end of a line from being hyphenated +(say, a proper name). SPREAD is the macro that lets you break the +line and have it came out fully justified. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="experts">Experts:</span> SPREAD is an alias for +<kbd>.brp</kbd> You can use either, or mix +’n’ match with impunity. +</p> +</div> + +<!-- -JOIN- --> + +<div class="macro-id-overline"> +<h3 id="join" class="macro-id">Join input lines</h3> +</div> + +<div class="box-macro-args"> +Inline: <kbd class="macro-args">\c</kbd> +</div> + +<p> +Sometimes, especially when in one of the +<a href="definitions.html#filled">nofill modes</a>, +a macro will cause a break where you don’t want one. In order +to prevent this from happening (in other words, to join +<a href="definitions.html#inputline">input lines</a> +together, forming one +<a href="definitions.html#outputline">output line</a>), +use the groff +<a href="definitions.html#inlines">inline escape</a> +<kbd>\c</kbd> at the end of each input line to be +joined to another, like this: +<br/> +<span class="pre-in-pp"> + .LEFT + .FAMILY T + .FT R + Some lines of text to be \c + .FAMILY H + .FT B + joined \c + .FAMILY T + .FT R + together. +</span> +Upon output, the lines will be joined together to read +<br/> +<span class="pre-in-pp"> + Some lines of text to be joined together. +</span> +with the word “joined” in Helvetica bold. Note the +spaces before <kbd>\c</kbd>. Without them, the last three words of +the output line would read +<br/> +<span class="pre-in-pp"> + bejoinedtogether +</span> +Please also note that had the example been in one of the +<a href="definitions.html#filled">fill modes</a>, +there’d have been no need for the <kbd>\c</kbd>. +</p> + +<div class="box-tip"> +<p class="tip"> +<b>Addendum:</b> The example, above, is designed to demonstrate the +use of <kbd>\c</kbd>. An easier and more intuitive way +to accomplish the family/font change in the example would be with +the groff +<a href="definitions.html#inlines">inline escape</a>, +<kbd><a href="inlines.html#inline-fonts-groff">\f</a></kbd>, +like this: +<br/> +<span class="pre-in-pp" style="padding-bottom: 0px;"> + Some lines of text to be \f[HB]joined\*[PREV] together. +</span> +</p> +</div> + +<div class="rule-short" style="margin-bottom: 24px;"><hr/></div> + +<!-- ==================================================================== --> + +<h2 id="refinements-intro" class="macro-group">Typographic refinements</h2> + +<p> +The macros in this section help you tweak groff’s behaviour, +ensuring that your documents look typographically professional. +</p> + +<div id="index-refinements" class="macro-list-container"> +<h3 class="macro-list">Typographic refinements macros</h3> + +<ul class="macro-list"> + <li>Word and sentence spacing + <ul style="list-style-type: none; margin-left: -1em;"> + <li><a href="#ws">WS</a> – word spacing</li> + <li><a href="#ss">SS</a> – sentence space</li> + </ul></li> + <li>Letter spacing (track kerning) + <ul style="list-style-type: none; margin-left: -1em;"> + <li><a href="#rw">RW</a> – reduce whitespace</li> + <li><a href="#ew">EW</a> – expand whitespace</li> + <li><a href="#br-at-line-kern">BR_AT_LINE_KERN</a></li> + </ul></li> + <li>Hyphenation + <ul style="list-style-type: none; margin-left: -1em;"> + <li><a href="#hy">HY</a> – turn auto hyphenation on/off, or set specific hyphenation parameters</li> + <li><a href="#hy-set">HY_SET</a> – set all hyphenation parameters</li> + </ul></li> + <li>Automatic kerning and ligatures + <ul style="list-style-type: none; margin-left: -1em;"> + <li><a href="#kern">KERN</a> – turn automatic pairwise kerning on or off</li> + <li><a href="#ligatures">LIGATURES</a> – turn automatic generation of ligatures on or off</li> + </ul></li> +</ul> +</div> + +<!-- -WS- --> + +<div class="macro-id-overline"> +<h3 id="ws" class="macro-id">Word spacing</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>WS</b> <kbd class="macro-args"><+|-wordspace> | DEFAULT</kbd> +</div> + +<p> +WS (Word Space) increases or decreases the amount of space between +words. In +<a href="definitions.html#filled">nofill modes</a>, +or if +<a href="#quad">QUAD</a> +is in effect, the space between words is fixed. Therefore, if you +change the word spacing with WS, the change applies uniformly to the +space between every word on every line. However, when text is +<a href="definitions.html#just">justified</a>, +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. +</p> + +<p> +Word space is relative to type size. Knowing how it’s +calculated is unimportant. What matters is having a sense of how +the value passed to 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. +</p> + +<p id="ws-usage"> +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 <br/> +<span class="pre-in-pp"> + .WS -4 +</span> +To increase it by a noticeable amount, you might enter +<br/> +<span class="pre-in-pp"> + .WS +12 +</span> +You can reset the word spacing to its previous value by switching +the plus or minus sign, like this: +<br/> +<span class="pre-in-pp"> + .WS +4 + A line of text + .WS -4 +</span> +The <kbd>.WS -4</kbd> undoes the effect of +<kbd>.WS +4</kbd>. You can also reset WS to its groff default +by entering +<br/> +<span class="pre-in-pp"> + .WS DEFAULT +</span> +This can be particularly useful if you’ve been playing around +with plus and minus values, and can’t remember by how much you +have to in/decrease the word space to get it back to normal. +</p> + +<!-- -SS- --> + +<div class="macro-id-overline"> +<h3 id="ss" class="macro-id">Sentence space</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>SS</b> <kbd class="macro-args"><+sentence space> | 0 | DEFAULT</kbd> +</div> + +<p> +SS (Sentence Space) tells groff how to treat double spaces it +encounters between sentences in +<a href="definitions.html#inputline">input lines</a>. +If you use SS, input sentences with two spaces after them <i>and</i> +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, +<br/> +<span class="pre-in-pp"> + .SS +2 +</span> +means that input sentences with two spaces after them receive a +normal word space PLUS the +2 value passed to SS. +</p> + +<p> +Like +<a href="#ws">WS</a>, +increasing the sentence space by a value of 1 or 2 produces a +difference that in many cases is scarcely visible; increasing by a +value of 5 or so produces a subtle but noticeable difference (i.e. +the space between double-spaced input sentences will be slightly but +visibly greater than the space between words); and increasing by a +value greater than 10 is always apparent. You should preview your +work to assess the effect of SS. +</p> + +<p> +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 +<br/> +<span class="pre-in-pp"> + .SS 0 +</span> +at the top of your files. +</p> + +<p> +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 +<br/> +<span class="pre-in-pp"> + .SS DEFAULT +</span> +If you’re using the +<a href="docprocessing.html">document processing macros</a> +and your +<a href="docprocessing.html#printstyle">PRINTSTYLE</a> +is TYPEWRITE, <kbd>.SS DEFAULT</kbd> is the +default, because you do want double spaces between sentences in copy +that imitates the look of a typewritten document. +</p> + +<div class="box-important"> +<p class="tip"> +<span class="important">IMPORTANT:</span> SS with an argument other +than <kbd>0</kbd> (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. +</p> +</div> + +<!-- -HY- --> + +<div class="macro-id-overline"> +<h3 id="hy" class="macro-id">Automatic hyphenation control</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>HY</b> <kbd class="macro-args">LINES <max. number of consecutive hyphenated lines></kbd> + <br/> +Macro: <b>HY</b> <kbd class="macro-args">MARGIN <size of hyphenation margin></kbd> + <br/> +Macro: <b>HY</b> <kbd class="macro-args">SPACE <extra interword spacing to prevent hyphenation></kbd> + <br/> +Macro: <b>HY</b> <kbd class="macro-args">DEFAULT</kbd> + <br/> +Macro: <b>HY</b> <kbd class="macro-args">toggle</kbd> +</div> +<p class="alias"> +<i>Aliases:</i> <b>HYPHENATE, HYPHENATION</b> +</p> + +<p> +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. +</p> + +<h3 class="docs">1. HY</h3> + +<p> +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 +<a href="intro.html#macro-args">How to read macro arguments</a>, +you could turn HY off by entering +<br/> +<span class="pre-in-pp"> + .HY OFF +</span> +or +<span class="pre-in-pp"> + .HY X +</span> +or +<span class="pre-in-pp"> + .HY END +</span> +HY observes the following default hyphenation rules: +</p> +<ul style="margin-top: -.5em; margin-left: 18px;"> + <li>Last lines (i.e. ones that will spring a trap—typically + the last line on a page) will not be hyphenated. + </li> + <li>The first and last two characters of a word are never + split off. + </li> +</ul> + +<h3 class="docs numbered">2. HY LINES</h3> + +<p> +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 +<br/> +<span class="pre-in-pp"> + .HY LINES 2 +</span> +By default, when you turn automatic hyphenation on, there is no +limit to the number of consecutive hyphenated lines. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +<a href="definitions.html#discretionaryhyphen">Discretionary hyphens</a> +count when groff is figuring out how many lines to hyphenate; +explicit hyphens do not. +</p> +</div> + +<h3 class="docs numbered">3. HY MARGIN</h3> + +<p> +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 +<a href="#quad">QUAD</a>, +and is really only useful if you’re using QUAD LEFT. +</p> + +<p> +As an example, if you don’t want groff to hyphenate words +when there’s only 18 points of space left at the end of a +left-quadded line, you’d enter +<br/> +<span class="pre-in-pp" style="margin-bottom: -1em"> + .HY MARGIN 18p +</span> +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> The numeric argument after HY +MARGIN requires a +<a href="definitions.html#unitofmeasure">unit of measure</a>. +</p> +</div> + +<h3 class="docs numbered">4. HY SPACE</h3> + +<p> +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 +<a href="definitions.html#just">justified lines</a>. +Generally speaking, you’ll want this value to be quite small, +since too big a value will result in lines with gaping holes between +the words. A reasonable value might be half a point, or one point, +which you’d set with +<br/> +<span class="pre-in-pp"> + .HY SPACE .5p +</span> +or +<span class="pre-in-pp" style="margin-bottom: -1em"> + .HY SPACE 1p +</span> +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> The numeric argument after HY SPACE +requires a +<a href="definitions.html#unitofmeasure">unit of measure</a>. +</p> +</div> + +<h3 class="docs numbered">5. HY DEFAULT</h3> + +<p> +HY DEFAULT resets automatic hyphenation to its default behaviour, +cancelling any changes made with HY <kbd>LINES</kbd>, HY +<kbd>MARGIN</kbd>, and/or HY <kbd>SPACE</kbd>. +</p> + +<div class="box-notes"> +<h3 id="hyphenation-thoughts" class="docs notes">Thoughts on hyphenation in general</h3> + +<p style="margin-top: .5em"> +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. +</p> + +<p class="tip-bottom"> +Furthermore, hyphenation in +<a href="definitions.html#rag">rag</a> +copy requires a great deal of attention. At best, it should be +avoided completely by individually adjusting the number of words +on consecutive lines to achieve a pleasing, natural-looking rag. +Since such adjustments are often too fussy for document processing, +I recommend playing around with HY MARGIN a bit if your copy looks +hyphen-heavy. +</p> +</div> + +<!-- -HY_SET- --> + +<div class="macro-id-overline"> +<h3 id="hy-set" class="macro-id">Set hyphenation parameters all at once</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>HY_SET</b> <kbd class="macro-args"><lines> [ <margin> [ <space> ] ]</kbd> +</div> + +<p class="alias"> +<i>Alias:</i> <b>HYSET</b> +</p> + +<p> +HY_SET lets you set the parameters for hyphenation +with a single macro. <kbd><lines>,</kbd> +<kbd><margin></kbd> and +<kbd><space></kbd> correspond to the numeric +values required by <kbd>LINES</kbd>, +<kbd>MARGIN</kbd> and <kbd>SPACE</kbd> as described +<a href="#hy">above</a>. +</p> + +<p> +To set just the maximum number of consecutive hyphenated lines, +you’d enter +<br/> +<span class="pre-in-pp"> + .HY_SET 2 +</span> +If you wanted the same number of maximum consecutive hyphenated +lines and a hyphenation margin for use with +<a href="definitions.html#rag">rag</a> +copy, +<br/> +<span class="pre-in-pp"> + .HY_SET 2 36p +</span> +would set the hyphenation margin to 36 points. +</p> + +<p> +If you wanted the same number of maximum consecutive hyphenated +lines and a hyphenation space of 2 points for use with +<a href="definitions.html#just">justified</a> +copy, +<br/> +<span class="pre-in-pp"> + .HYSET 2 0 2p +</span> +is how you’d do it. +</p> + +<!-- -RW- --> + +<div class="macro-id-overline"> +<h3 id="rw" class="macro-id">Reduce whitespace</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>RW</b> <kbd class="macro-args"><amount of whitespace reduction between letters></kbd> +</div> + +<p> +RW (<span style="text-decoration: underline;">R</span>educe <span style="text-decoration: underline;">W</span>hitespace) +and its corresponding macro, +EW (<span style="text-decoration: underline;">E</span>xpand <span style="text-decoration: underline;">W</span>hitespace), +allow you to tighten (or loosen) +<a href="definitions.html#outputline">output lines</a> +by uniformly reducing or expanding the space between characters. +This is particularly useful when you want to squeeze or stretch +lines on a narrow measure. +</p> + +<p> +The value passed to 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, +<br/> +<span class="pre-in-pp"> + .RW .1 +</span> +or +<span class="pre-in-pp"> + .RW .2 +</span> +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. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> By default, RW does not deposit a +<a href="#br">break</a> +when it’s invoked if you’re in one of the +<a href="definitions.html#fill">fill</a> +modes (i.e. +<a href="#quad">QUAD</a> +L, R, C, J or +<a href="#justify">JUSTIFY</a>). +If you want +RW to break at the ends of the previous +<a href="definitions.html#inputline">input lines</a> +while you’re in a fill mode, tell mom +that’s what you want by invoking +<kbd><a href="#br-at-line-kern">.BR_AT_LINE_KERN</a></kbd>. +</p> +</div> + +<div class="box-important"> +<p class="tip"> +<span class="important">IMPORTANT:</span> In versions prior to +1.1.9-a, RW affected all +<a href="definitions.html#font">fonts</a> +in the +<a href="definitions.html#family">family</a> +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 +(<kbd>.RW 0</kbd>) on that font. +</p> +</div> + +<!-- -EW- --> + +<div class="macro-id-overline"> +<h3 id="ew" class="macro-id">Expand whitespace</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>EW</b> <kbd class="macro-args"><amount of whitespace expansion between letters></kbd> +</div> + +<p> +EW (<span style="text-decoration: underline;">E</span>xpand <span style="text-decoration: underline;">W</span>hitespace) +expands the amount of whitespace between letters, effectively +“loosening” lines of type. +</p> + +<p> +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, +<br/> +<span class="pre-in-pp"> + .EW .1 +</span> +or +<span class="pre-in-pp"> + .EW .2 +</span> +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. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> By default, EW does not deposit a +<a href="#br">break</a> +when it’s invoked if you’re in one of the +<a href="definitions.html#fill">fill</a> +modes (i.e. +<a href="#quad">QUAD</a> +L, R, C, J or +<a href="#justify">JUSTIFY</a>). +If you want +EW to break at the ends of the previous +<a href="definitions.html#inputline">input lines</a> +while you’re in a fill mode, tell mom that’s what you +want by invoking the +<kbd><a href="#br-at-line-kern">.BR_AT_LINE_KERN</a></kbd> +toggle macro. +</p> +</div> + +<div class="box-important"> +<p class="tip"> +<span class="important">IMPORTANT:</span> In versions prior to +1.1.9-a, EW affected all +<a href="definitions.html#font">fonts</a> +in the +<a href="definitions.html#family">family</a> +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 +(<kbd>.EW 0</kbd>) on that font. +</p> +</div> + +<!-- -BR_AT_LINE_KERN- --> + +<div class="macro-id-overline"> +<h3 id="br-at-line-kern" class="macro-id">Break before line kerning</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>BR_AT_LINE_KERN</b> <kbd class="macro-args">toggle</kbd> +</div> + +<p> +By default, in +<a href="definitions.html#filled">fill</a> +modes (i.e. +<a href="#quad">QUAD</a> +L, R, C, J or +<a href="#justify">JUSTIFY</a>) +mom does not break +<a href="definitions.html#inputline">input lines</a> +when you invoke +<a href="#rw">RW</a> +or +<a href="#ew">EW</a>. +If you’d like her to break input lines prior to RW or EW, +invoke <kbd>.BR_AT_INPUT_LINE</kbd> without any argument. To +disable the breaks, invoke <kbd>.BR_AT_INPUT_LINE</kbd> with any +argument (OFF, QUIT, Q, X...), like this +<br/> +<span class="pre-in-pp"> + .BR_AT_LINE_KERN OFF +</span> +or +<span class="pre-in-pp"> + .BR_AT_LINE_KERN X +</span> +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 +<a href="definitions.html#force">force justifies</a> +the line prior to <kbd>.EW</kbd> or <kbd>.RW</kbd>. +</p> + +<!-- -KERN- --> + +<div class="macro-id-overline"> +<h3 id="kern" class="macro-id">Automatic kerning</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>KERN</b> <kbd class="macro-args">toggle</kbd> +</div> + +<p> +By itself (i.e. with no argument), KERN turns automatic pairwise +<a href="definitions.html#kern">kerning</a> +on. With any argument (e.g. OFF, Q, X), pairwise kerning is turned +off. +</p> + +<p> +Kerning of individual character pairs can be controlled with the +<a href="definitions.html#inlines">inline escapes</a> +<kbd>\*[BU <n>]</kbd> and +<kbd>\*[FU <n>]</kbd>. See +<a href="inlines.html#inline-kerning-mom">Inline Escapes, kerning</a>. +</p> + +<!-- -LIGATURES- --> + +<div class="macro-id-overline"> +<h3 id="ligatures" class="macro-id">Automatic ligature generation</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>LIGATURES</b> <kbd class="macro-args">toggle</kbd> +</div> +<p class="alias"> +<i>Alias:</i> <b>LIG</b> +</p> + +<p> +Provided your current font has +<a href="definitions.html#ligatures">ligatures</a>, +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. +</p> + +<p> +LIGATURES with any argument turns automatic ligature generation off. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> Not all fonts support ligatures. +</p> +</div> + +<div class="rule-short"><hr/></div> + +<!-- ==================================================================== --> + +<h2 id="modifications-intro" class="macro-group">Type modifications (pseudo font styles)</h2> + +<p> +It sometimes happens that a PostScript +<a href="definitions.html#family">family</a> +doesn’t contain all the fonts you need. You might, for +example, be missing an italic font, or a bold font. Or you might +not be able to get your hands on a condensed family. That’s +where these macros and inline escapes come in. With them, you +can fake the fonts you’re missing. A word of caution, +though: “faked” fonts are just that—faked. You +should only use them as a last resort, and then only sparingly. A +word or two or a line or two in a faked font will pass unnoticed; +large patches of type in a faked font look typographically cheap. +</p> + +<div id="index-modifications" class="macro-list-container"> +<h3 class="macro-list">Type modifications macros</h3> + +<ul class="macro-list"> + <li>Pseudo italic + <ul style="list-style: none; margin-left: -1em;"> + <li><a href="#setslant">SETSLANT</a> – degree of pseudo-italicizing</li> + <li><a href="#slant-inline">\*[SLANT]</a> – inline escape for pseudo-italicizing type</li> + </ul></li> + <li>Pseudo bold + <ul style="list-style: none; margin-left: -1em;"> + <li><a href="#setbolder">SETBOLDER</a> – amount of emboldening</li> + <li><a href="#bolder-inline">\*[BOLDER]</a> – inline escape for emboldening type</li> + </ul></li> + <li>Pseudo condensed + <ul style="list-style: none; margin-left: -1em;"> + <li><a href="#condense">CONDENSE</a> – percentage for pseudo-condensed type</li> + <li><a href="#cond-inline">\*[COND]</a> – inline escape for pseudo-condensed type</li> + </ul></li> + <li>Pseudo extended + <ul style="list-style: none; margin-left: -1em;"> + <li><a href="#extend">EXTEND</a> – percentage for pseudo-extended type</li> + <li><a href="#ext-inline">\*[EXT]</a> – inline escape for pseudo-extending</li> + </ul></li> +</ul> +</div> + +<!-- -SETSLANT- --> + +<div class="macro-id-overline"> +<h3 id="setslant" class="macro-id">Set degree of slant for pseudo-italicizing</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>SETSLANT</b> <kbd class="macro-args"><degrees to slant type> | RESET</kbd> +</div> + +<p> +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 +<br/> +<span class="pre-in-pp"> + .SETSLANT 13 +</span> +If you change the degree of slant and later want to set it back to +the mom default, do +<br/> +<span class="pre-in-pp"> + .SETSLANT RESET +</span> +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> 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 +<a href="definitions.html#inlines">inline escape</a> +<kbd>\*[SLANT]</kbd>. +</p> +</div> + +<!-- -\*[SLANT]- --> + +<div class="macro-id-overline"> +<h3 id="slant-inline" class="macro-id">Pseudo italic on/off</h3> +</div> + +<div class="box-macro-args"> +Inline: <kbd class="macro-args">\*[SLANT]</kbd> +<br/> +Inline: <kbd class="macro-args">\*[SLANTX</kbd>] +</div> + +<p> +<kbd class="macro-args">\*[SLANT]</kbd> begins pseudo-italicizing type. +<kbd class="macro-args">\*[SLANTX]</kbd> turns the feature off. Both are +<a href="definitions.html#inlines">inline escapes</a>, +therefore they should not appear as separate lines, but rather be +embedded in text lines, like this: +<br/> +<span class="pre-in-pp"> + Not \*[SLANT]everything\*[SLANTX] is as it seems. +</span> +Alternatively, if you wanted the whole line pseudo-italicized, +you’d do +<br/> +<span class="pre-in-pp"> + \*[SLANT]Not everything is as it seems.\*[SLANTX] +</span> +Once <kbd>\*[SLANT]</kbd> is invoked, it remains in effect until +turned off. +</p> + +<div class="box-tip" style="margin-top: .5em;"> +<p class="tip"> +<span class="note">Note:</span> If you’re using the +<a href="docprocessing.html#docprocessing">document processing macros</a> +with +<a href="docprocessing.html#printstyle">PRINTSTYLE TYPEWRITE</a>, +mom underlines pseudo-italics by default. To change this behaviour, +use the special macro +<a href="docprocessing.html#typewrite-control">SLANT_MEANS_SLANT</a>. +</p> +</div> + +<!-- -SETBOLDER- --> + +<div class="macro-id-overline"> +<h3 id="setbolder" class="macro-id">Set amount of emboldening</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>SETBOLDER</b> <kbd class="macro-args"><amount of emboldening, in machine units> | RESET</kbd> +</div> + +<p> +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 +<a href="definitions.html#units">machine units</a> +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 +<br/> +<span class="pre-in-pp"> + .SETBOLDER 500 +</span> +If you change the emboldening offset and later want to set it back +to the mom default, do +<br/> +<span class="pre-in-pp"> + .SETBOLDER RESET +</span> +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> 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 +<a href="definitions.html#inlines">inline escape</a> +<kbd>\*[BOLDER]</kbd>. +</p> +</div> + +<!-- -\*[BOLDER]- --> + +<div class="macro-id-overline"> +<h3 id="bolder-inline" class="macro-id">Emboldening on/off</h3> +</div> + +<div class="box-macro-args"> +Inline: <kbd class="macro-args">\*[BOLDER]</kbd> +<br/> +Inline: <kbd class="macro-args">\*[BOLDERX]</kbd> +</div> + +<p> +<kbd class="macro-args">\*[BOLDER]</kbd> begins emboldening type. +<kbd class="macro-args">\*[BOLDERX]</kbd> turns the feature off. Both are +<a href="definitions.html#inlines">inline escapes</a>, +therefore they should not appear as separate lines, but rather be +embedded in text lines, like this: +<br/> +<span class="pre-in-pp"> + Not \*[BOLDER]everything\*[BOLDERX] is as it seems. +</span> +Alternatively, if you wanted the whole line emboldened, +you’d do +<br/> +<span class="pre-in-pp"> + \*[BOLDER]Not everything is as it seems.\*[BOLDERX] +</span> +Once <kbd>\*[BOLDER]</kbd> is invoked, it remains in effect +until turned off. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> If you’re using the +<a href="docprocessing.html#docprocessing">document processing macros</a> +with +<a href="docprocessing.html#printstyle">PRINTSTYLE TYPEWRITE</a>, +mom ignores <kbd>\*[BOLDER]</kbd> requests. +</p> +</div> + +<!-- -CONDENSE- --> + +<div class="macro-id-overline"> +<h3 id="condense" class="macro-id">Set percentage for pseudo-condensed type</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>CONDENSE</b> <kbd class="macro-args"><pseudo-condense percentage></kbd> +</div> + +<p> +Pseudo-condensing of type is accomplished by reducing the width of +characters at a given point size without reducing their height, +effectively narrowing them so they look like condensed type. +CONDENSE tells mom what percentage of the normal character width you +want the characters to be condensed. +</p> + +<p> +Mom has no default value for CONDENSE, therefore you must set it +before using the +<a href="definitions.html#inlines">inline escape</a> +<kbd><a href="#cond-inline">\*[COND]</a></kbd>. +80 percent of the normal character width is a good value, and +you’d set it like this: +<br/> +<span class="pre-in-pp"> + .CONDENSE 80 +</span> +</p> + +<div class="box-tip"> +<p class="tip-top"> +<span class="note">Note:</span> 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 +<a href="definitions.html#inlines">inline escape</a> +<kbd>\*[COND]</kbd>. +</p> + +<p class="tip-bottom"> +<span class="additional-note">Additional note:</span> Make sure that +pseudo-condensing is off (with +<kbd><a href="#cond-inline">\*[CONDX]</a></kbd>) +before before making any changes to the pseudo-condense percentage +with CONDENSE. +</p> +</div> + +<!-- -\*[COND]- --> + +<div class="macro-id-overline"> +<h3 id="cond-inline" class="macro-id">Pseudo-condensing on/off</h3> +</div> + +<div class="box-macro-args"> +Inline: <kbd class="macro-args">\*[COND]</kbd> +<br/> +Inline: <kbd class="macro-args">\*[CONDX]</kbd> +</div> + +<p> +<kbd>\*[COND]</kbd> begins pseudo-condensing type. +<kbd>\*[CONDX]</kbd> turns the feature off. Both are +<a href="definitions.html#inlines">inline escapes</a>, +therefore they should not appear as separate lines, but rather be +embedded in text lines, like this: +<br/> +<span class="pre-in-pp"> + \*[COND]Not everything is as it seems.\*[CONDX] +</span> +<kbd>\*[COND]</kbd> remains in effect until you turn it +off with <kbd>\*[CONDX]</kbd>. +</p> + +<div class="box-important"> +<p class="tip"> +<span class="important">IMPORTANT:</span> You must turn +<kbd>\*[COND]</kbd> +off before making any changes to the point size of your type, either +via the +<a href="#ps">PT_SIZE</a> +macro or with the <kbd>\s</kbd> inline escape. If you wish +the new point size to be pseudo-condensed, simply reinvoke +<kbd>\*[COND]</kbd> afterwards. Equally, <kbd>\*[COND]</kbd> must +be turned off before changing the condense percentage with +<kbd><a href="#condense">.CONDENSE</a></kbd>. +</p> +</div> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> If you’re using the +<a href="docprocessing.html#docprocessing">document processing macros</a> +with +<a href="docprocessing.html#printstyle">PRINTSTYLE TYPEWRITE</a>, +mom ignores <kbd>\*[COND]</kbd> requests. +</p> +</div> + +<!-- -EXTEND- --> + +<div class="macro-id-overline"> +<h3 id="extend" class="macro-id">Set percentage for pseudo-extended type</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>EXTEND</b> <kbd class="macro-args"><pseudo-extend percentage></kbd> +</div> + +<p> +Pseudo-extending of type is accomplished by increasing the width of +characters at a given point size without increasing their height, +effectively widening them so they look like extended type. EXTEND +tells mom what percentage of the normal character width you want the +characters to be extended. +</p> + +<p> +Mom has no default value for EXTEND, therefore you must set it +before using the +<a href="definitions.html#inlines">inline escape</a> +<kbd><a href="#ext-inline">\*[EXT]</a></kbd>. +120% of the normal character width is a good value, and you’d +set it like this: +<br/> +<span class="pre-in-pp"> + .EXTEND 120 +</span> +</p> + +<div class="box-tip"> +<p class="tip-top"> +<span class="note">Note:</span> 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 +<a href="definitions.html#inlines">inline escape</a> +<kbd>\*[EXT]</kbd>. +</p> + +<p class="tip-bottom"> +<span class="additional-note">Additional note:</span> Make sure that +pseudo-extending is off (with +<a href="#ext-inline"><kbd>\*[EXTX]</kbd></a>) +before before making any changes to the pseudo-extend percentage +with EXTEND. +</p> +</div> + +<!-- -\*[EXT]- --> + +<div class="macro-id-overline"> +<h3 id="ext-inline" class="macro-id">Pseudo-extending on/off</h3> +</div> + +<div class="box-macro-args"> +Inline: <kbd class="macro-args">\*[EXT]</kbd> +<br/> +Inline: <kbd class="macro-args">\*[EXTX]</kbd> +</div> + +<p> +<kbd>\*[EXT]</kbd> begins pseudo-extending type. +<kbd>\*[EXTX]</kbd> turns the feature off. Both are +<a href="definitions.html#inlines">inline escapes</a>, +therefore they should not appear as separate lines, but rather be +embedded in text lines, like this: +<br/> +<span class="pre-in-pp"> + \*[EXT]Not everything is as it seems.\*[EXTX] +</span> +<kbd>\*[EXT]</kbd> remains in effect until you turn it off with +<kbd>\*[EXTX]</kbd>. +</p> + +<div class="box-important"> +<p class="tip"> +<span class="important">IMPORTANT:</span> You must turn +<kbd>\*[EXT]</kbd> off before making any changes to the point size +of your type, either via the +<a href="#ps">PT_SIZE</a> +macro or with the <kbd>\s</kbd> inline escape. If you wish the new +point size to be pseudo-extended, simply reinvoke <kbd>\*[EXT]</kbd> +afterwards. Equally, <kbd>\*[EXT]</kbd> must be turned off before +changing the extend percentage with +<a href="#extend">EXTEND</a>. +</p> +</div> +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> If you’re using the +<a href="docprocessing.html#docprocessing">document processing macros</a> +with +<a href="docprocessing.html#printstyle">PRINTSTYLE TYPEWRITE</a>, +mom ignores <kbd>\*[EXT]</kbd> requests. +</p> +</div> + +<div class="rule-short" style="margin-bottom: 24px;"><hr/></div> + +<!-- ==================================================================== --> + +<h2 id="aldrld-intro" class="macro-group">Vertical movements</h2> + +The two macros in this section allow you to move down or up on the +page relative to the current +<a href="definitions.html#baseline">baseline</a>. + +<div id="index-aldrld" class="macro-list-container"> +<h3 class="macro-list">Vertical movements macros</h3> +<ul class="macro-list"> + <li><a href="#ald">ALD</a> – Advance Lead</li> + <li><a href="#rld">RLD</a> – Reverse Lead</li> +</ul> +</div> + +<!-- -ALD- --> + +<div class="macro-id-overline"> +<h3 id="ald" class="macro-id">Advance Lead (move downward)</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>ALD</b> <kbd class="macro-args"><distance to move downward></kbd> +</div> +<p class="requires"> +• Requires a <a href="definitions.html#unitofmeasure">unit of measure</a> +</p> + +<p> +ALD takes one argument: the distance to move downward on the page +relative to the current vertical position. +</p> + +<p> +Used by itself, or preceded by +<a href="#br">BR</a>, +ALD will advance by one line space plus the distance you specify. +Preceded by +<a href="#el">EL</a>, +it will advance by exactly the distance you specify. +</p> + +<p> +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 +<br/> +<span class="pre-in-pp"> + .ALD .25i +</span> +or +<br/> +<span class="pre-in-pp"> + .ALD 1P+6p +</span> +As the mnemonic +(<span style="text-decoration: underline;">A</span>dvance <span style="text-decoration: underline;">L</span>ea<span style="text-decoration: underline;">D</span>) +suggests, you’ll most often use ALD with +<a href="definitions.html#picaspoints">points</a> +of lead. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> 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 <kbd>-1v</kbd> (minus one +line space), like this: +<br/> +<span class="pre-in-pp"> + .ALD 1i-1v +</span> +At the top of a page, this will advance one inch from the top edge +of the paper. Without the -1v, the same command would advance one +inch from the top of the page plus the distance of one line space. +</p> +</div> + +<!-- -RLD- --> + +<div class="macro-id-overline"> +<h3 id="rld" class="macro-id">Reverse Lead (move upward)</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>RLD</b> <kbd class="macro-args"><distance to move upward></kbd> +</div> +<p class="requires"> +• Requires a <a href="definitions.html#unitofmeasure">unit of measure</a> +</p> + +<p> +RLD takes one argument: the distance to move upward on the page +relative to the current vertical position. +</p> + +<p> +Used by itself, or preceded by +<a href="#br">BR</a>, +RLD will advance by one line space, then reverse by the distance you +specify. Preceded by +<a href="#el">EL</a>, +it will reverse by exactly the distance you specify. +</p> + +<p> +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 +<br/> +<span class="pre-in-pp"> + .RLD .25i +</span> +or +<span class="pre-in-pp"> + .RLD 1P+6p +</span> +As the mnemonic +(<span style="text-decoration: underline;">R</span>everse <span style="text-decoration: underline;">L</span>ea<span style="text-decoration: underline;">D</span>) +suggests, you’ll most often use RLD with +<a href="definitions.html#picaspoints">points</a> +of lead. +</p> + +<div class="rule-short" style="margin-bottom: 24px;"><hr/></div> + +<!-- ==================================================================== --> + +<h2 id="tabs-intro" class="macro-group">Tabs</h2> + +<p> +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. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> see the section +<a href="docprocessing.html#behaviour">Typesetting macros during document processing</a> +for re-assuring information on the use of tabs during +<a href="docprocessing.html#docprocessing">document processing</a>. +</p> +</div> + +<h3 id="typesetting-tabs" class="docs">Typesetting tabs</h3> + +<p> +Typesetting tabs are defined by both an indent from the left margin +and a line length. This is quite different from typewriter-style +tab stops (the groff norm) that only define the left indent. In +conjunction with the +<a href="#multicolumns-intro">multi-column macros</a>, +typesetting tabs significantly facilitate tabular and columnar work. +</p> + +<p> +Typesetting tabs are created with the +<a href="#tab-set">TAB_SET</a> +macro. 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 +<a href="#tab">TAB</a> +macro. +</p> + +<div class="examples-container"> +<h3 id="typesetting-tabs-tut" class="docs notes">Quickie tutorial on typesetting tabs</h3> + +<p style="margin-top: .5em;"> +Say you want to set up three tabs to produce an employee evaluation +that looks something like this: +</p> + +<div class="box-code" style="padding-bottom: 0;"> +<span id="typsetting-tabs-sample" class="pre-in-pp" style="color: #302419"> +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. +</span> +</div> + +<p> +You want the first tab, CRITERION, +</p> +<ul style="margin-top: -.5em; margin-bottom: -.5em;"> +<li>to begin at the left margin of the page – i.e. no indent</li> +<li>to have a line length of 5 picas</li> +<li>to be set flush left</li> +</ul> + +<p> +Tabs must be numbered, and each has to be set up with a separate +<a href="#tab-set">TAB_SET</a> +line. Therefore, to set up tab 1, you enter +<br/> +<span class="pre-in-pp"> + .TAB_SET 1 0 5P L + | | | | + tab #--+ | | +--direction + | | + indent--+ +--length +</span> +You want the second tab, EVALUATION, +</p> +<ul style="margin-top: -.5em; margin-bottom: -.5em;"> +<li>to begin 8 picas from the left margin</li> +<li>to have a length of 9 picas</li> +<li>to be set centered</li> +</ul> + +<p> +You set it up like this: +<br/> +<span class="pre-in-pp"> + .TAB_SET 2 8P 9P C + | | | | + tab #--+ | | +--direction + | | + indent--+ +--length +</span> +You want the third tab, COMMENTS, +</p> +<ul style="margin-top: -.5em; margin-bottom: -.5em;"> +<li>to begin 19 picas from the left margin</li> +<li>to have a length of 17 picas</li> +<li>to be set flush left, <a href="definitions.html#filled">filled</a></li> +</ul> + +<p> +The setup looks like this: +<br/> +<span class="pre-in-pp"> + .TAB_SET 3 19P 17P L QUAD + | | | | | + | | | | +--fill output lines + | | | | + tab #--+ | | +--direction + | | + indent--+ +--length +</span> +Once the tabs are set up, you can call them in one of two ways: +</p> +<ul style="margin-top: -.5em; margin-bottom: -.5em;"> +<li>with <kbd><a href="#tab">.TAB</a></kbd> (passing the tab + number as an argument), which breaks the current line, + advances one linespace and calls the tab.</li> +<li>with <kbd><a href="#tn">.TN</a></kbd> (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.).</li> +</ul> + +<p> +To exit from tabs and restore your original left margin, line +length, quad direction and fill mode, use +<kbd><a href="#tq">.TQ</a></kbd> +(Tab Quit). +</p> + +<p> +Here’s how the input for our sample employee evaluation looks +(with some introductory parameters): +</p> + +<div class="examples" style="margin-bottom: 0px;">Code:</div> +<div class="box-code" style="height: 324px; padding-bottom: 18px; overflow: auto;"> +<span class="pre-in-pp"> +.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 +</span> +</div> + +<p> +Try setting this up and processing it it with +<br/> +<span class="pre-in-pp"> + groff -mom <filename> > <filename>.ps +</span> +then previewing the .ps file. Notice how <kbd>.TN</kbd> +simply moves over to the next tab, while the combination +<kbd>.SP/.TAB 1</kbd> breaks the line, advances by one extra +linespace, and calls the first tab. +</p> + +<p> +Notice, too, how the <kbd>QUAD</kbd> argument passed to tab 3 means +you don’t have to worry about the length of +<a href="definitions.html#inputline">input lines</a>; +mom +<a href="definitions.html#filled">fills</a> +the tab and sets the type flush left. +</p> +</div> + +<h3 id="string-tabs" class="docs">String tabs (autotabs)</h3> + +<p> +String tabs let you mark off tab positions with +<a href="definitions.html#inlines">inline escapes</a> +embedded in +<a href="definitions.html#inputline">input lines</a>. +Left indents and line lengths are calculated from the beginning and +end positions of the marks. This is especially useful when tab +indents and lengths need to be determined from the text that goes in +each tab. +</p> + +<p> +Setting up string tabs is a two-step procedure. First, you enter an +input line in which you mark off where you want tabs to begin and +end. (This is often best done in conjunction with the +<a href="goodies.html#silent">SILENT</a> +macro.) +</p> + +<p> +Next, you invoke the +<a href="#st">ST</a> +macro for every string tab you defined, and optionally pass quad and +fill information to it. That done, string tabs are called with the +<a href="#tab">TAB</a> +macro, just like typesetting tabs. +</p> + +<p> +In combination with the +<a href="goodies.html#pad">PAD</a> +macro and the groff inline escape +<kbd><a href="inlines.html#inline-horizontal-groff">\h</a></kbd> +(move horizontally across the page) or mom’s +<kbd><a href="inlines.html#inline-horizontal-mom">\*[FWD <distance>]</a></kbd> +(move forward) inline, string tabs provide tremendous flexibility in +setting up complex tab structures. +</p> + +<div class="examples-container"> +<h3 id="string-tabs-tut" class="docs notes">Quickie tutorial on string tabs</h3> +<p style="margin-top: .5em;"> +Say you want to set up tabs for the +<a href="#typsetting-tabs-sample">employee evaluation form</a> +used as an example in the +<a href="#typesetting-tabs-tut">typesetting tabs tutorial</a>. +This time, though, you want to play around with the point size of +type, so you can’t know exactly how long the tabs will be or +where they should start. All you know is +</p> +<ul style="margin-top: -.5em; margin-bottom: -.5em;"> +<li>CRITERION is the longest line in tab 1</li> +<li>EVALUATION is the longest line in tab 2</li> +<li>tab 3 should extend to the current right margin</li> +<li>you want a 1 pica gutter between each tab</li> +</ul> + +<p> +This is an ideal job for string tabs. +</p> + +<p> +The first thing you need for string tabs is an +<a href="definitions.html#inputline">input line</a> +with tab positions marked on it. Tabs are marked with the +<a href="definitions.html#inlines">inline escapes</a> +<kbd><a href="#inline-st">\*[ST<n>]</a></kbd> +and +<kbd><a href="#inline-st">\*[ST<n>X]</a></kbd>, +where <kbd><n></kbd> +is the number you want the tab to have. (In this example, we +enclose the input line with the +<a href="goodies.html#silent">SILENT</a> +macro so the line doesn’t print. We also use the +<a href="goodies.html#pad">PAD</a> +macro to permit defining tab 3 as simply “the amount of space +remaining on the input line.”) +</p> + +<p> +The setup looks like this: +</p> + +<div class="examples" style="margin-bottom: 0px;">Code:</div> + +<div class="box-code"> +<span class="pre-in-pp"> +.SILENT +.PAD "\*[ST1]CRITERION\*[ST1X]\*[FWD 12p]\*[ST2]EVALUATION\*[ST2X]\*[FWD 12p]\*[ST3]#\*[ST3X]" +.SILENT OFF +</span> +</div> + +<p> +The long line after <kbd>.PAD</kbd> looks scary, but +it isn’t really. Here’s what it means when broken down +into its component parts: +</p> +<ul style="margin-bottom: -1em;"> +<li>The longest line in tab 1 is “CRITERION”, so we + enclose CRITERION with begin/end markers for string tab 1: +<br/> +<span class="pre-in-pp" style="margin-bottom: -.25em;"> + \*[ST1]CRITERION\*[ST1X] +</span> +</li> +<li>We want a 1 pica (12 points) gutter between tab 1 and 2, + so we insert 12 points of space with \*[FWD 12p] + (ForWarD 12 points): +<br/> +<span class="pre-in-pp" style="margin-bottom: -.25em;"> + \*[FWD 12p] +</span> +</li> +<li>The longest line in tab 2 is “EVALUATION”, so + we enclose EVALUATION with begin/end markers for string + tab 2: +<span class="pre-in-pp" style="margin-bottom: -.25em;"> + \*[ST2]EVALUATION\*[ST2X] +</span> +</li> +<li>We want 1 pica (12 points) between tab 2 and 3, so we + insert it with: +<br/> +<span class="pre-in-pp" style="margin-bottom: -.25em;"> + \*[FWD 12p] +</span> +</li> +<li>We want tab 3 to be as long as whatever space remains on + the current line length, so we enclose the + <a href="goodies.html#pad-marker">pad marker</a> + (#) with begin/end markers for string tab 3: +<span class="pre-in-pp"> + \*[ST3]#\*[ST3X] +</span> + </li> +</ul> + +<p> +The tabs are now defined, but they require +<a href="definitions.html#quad">quad direction</a> +and +<a href="definitions.html#filled">fill</a> +information. For each string tab defined above, enter a separate +<kbd><a href="#st">.ST</a></kbd> +line, like this: +<br/> +<span class="pre-in-pp"> + .ST 1 L + .ST 2 L + .ST 3 L QUAD + | | | + | | +--fill output lines + | | + tab #--+ +--direction +</span> +From here on in, you call the tabs with +<kbd><a href="#tab">.TAB</a></kbd> +and +<kbd><a href="#tn">.TN</a></kbd> +just like typesetting tabs (see +<a href="#typesetting-tabs-tut">typesetting tabs tutorial</a>). +</p> + +<p> +Here’s the complete setup and entry for the sample employee +evaluation form utilizing string tabs. +</p> + +<div class="examples" style="margin-bottom: 0px;">Code:</div> +<div class="box-code" style="height: 324px; padding-bottom: 18px; overflow: scroll;"> +<span class="pre-in-pp"> +.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 +</span> +</div> + +<p> +Try setting this up and processing it with +<br/> +<span class="pre-in-pp"> + groff -mom <filename> > <filename>.ps +</span> +and previewing the .ps file. +</p> + +<p> +Now, change the point size of the above sample to 12 and preview it +again. You’ll see that the tab structure remains identical +(tab 1=CRITERION, tab 2=EVALUATION, tab 3=space remaining, and the +gutter between tabs is still 1 pica), while the position and length +of the tabs have altered because of the new point size. +</p> + +<p> +Now try increasing the gutters to 2 picas +(<kbd>\*[FWD 24p]</kbd> or <kbd>\*[FWD 2P]</kbd> instead +of <kbd>\*[FWD 12p]</kbd>). Preview the file again, and notice +how the tab structure remains the same, but the gutters are wider. +</p> +</div> + +<div id="index-tabs" class="macro-list-container"> +<h3 class="macro-list">Tabs macros</h3> + +<ul class="macro-list"> + <li><a href="#tab-set">TAB_SET</a> – create typesetting tabs</li> + <li><a href="#inline-st">\*[ST]...\*[STX]</a> – inline escapes for marking String Tabs</li> + <li><a href="#st">ST</a> – set String Tabs</li> + <li><a href="#tab">TAB</a> – call tabs</li> + <li><a href="#tn">TN</a> – Tab Next; call next tab in a sequence</li> + <li><a href="#tq">TQ</a> – Tab Quit</li> +</ul> + +</div> + +<!-- -TAB_SET- --> + +<div class="macro-id-overline"> +<h3 id="tab-set" class="macro-id">Set up typesetting tabs</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>TAB_SET</b> <kbd class="macro-args"><tab number> <indent> <length> L | R | C | J [ QUAD ]</kbd> +</div> +<p class="requires"> +• <kbd style="font-style: normal;"><indent></kbd> and <kbd style="font-style: normal;"><length></kbd> require a <a href="definitions.html#unitofmeasure">unit of measure</a> +</p> + +<p style="margin-bottom: -.5em;"> +TAB_SET creates typesetting tabs that later can be called with +<kbd><a href="#tab">.TAB</a></kbd>. +Typesetting tabs are numbered, and defined by an indent, a length, +and a quad direction, hence TAB_SET has four required arguments: +</p> +<ul style="margin-top: .5em; margin-bottom: -.5em;"> +<li>a tab number</li> +<li>an indent (measured from the left margin of the page, + or, if you’re already in a tab, from the left margin of the tab)</li> +<li>a length</li> +<li>a direction</li> +</ul> + +<p> +To set up a centred tab 6 picas long and 9 points from the left +margin, you’d enter +<br/> +<span class="pre-in-pp"> + .TAB_SET 1 9p 6P C +</span> +The tab number in the above (”1”) is simply an +identifier. It could have been 4, or 17, or 296. There’s no +need to set up tabs in numerical sequence. +</p> + +<p> +By default, tabs are in +<a href="definitions.html#filled">nofill</a> +mode, meaning you can enter text in tabs on a line-for-line basis +without having to use the +<a href="#br">BR</a> +macro. If you want a tab to be +<a href="definitions.html#filled">filled</a>, +pass the optional argument <kbd>QUAD</kbd>, +which will make the tab behave as if you’d entered +<kbd class="bold">.QUAD L | R | C</kbd>. +</p> + +<p> +For +<a href="definitions.html#just">justified</a> +tabs, simply pass the argument J (without the QUAD argument), like +this: +<br/> +<span class="pre-in-pp"> + .TAB 1 9p 6P J +</span> +Once tabs are set, they can be called at any time with the +<a href="#tab">TAB <n></a> +macro, where <n> is the number of the desired tab. +</p> + +<p> +You can set up any number of typesetting tabs. However, be aware +that +<a href="#string-tabs">string tabs</a> +are also called with 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. </p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> 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 +<kbd><a href="#tq">.TQ</a></kbd>) +before creating new tabs (unless, of course, you want to set up a +tab structure within the confines of an existing tab). +</p> +</div> + +<div class="box-important"> +<p class="tip"> +<span class="important">IMPORTANT:</span> Turn all indents off (see +<a href="#indents">Indents</a>) +before setting up tabs with TAB_SET, or mom may get confused. +</p> +</div> + +<!-- -INLINE_ST- --> + +<div class="macro-id-overline"> +<h3 id="inline-st" class="macro-id">Mark positions of string tabs</h3> +</div> + +<div class="box-macro-args"> +Inlines: <kbd class="macro-args">\*[ST<number>]...\*[ST<number>X]</kbd> +</div> + +<p class="requires"> +The <a href="definitions.html#quad">quad</a> +direction must be +<span style="font-style: normal">LEFT</span> +or +<span style="font-style: normal">JUSTIFY</span> +(see +<a href="#quad"><span style="font-style: normal">QUAD</span></a> +and +<a href="#justify"><span style="font-style: normal">JUSTIFY</span></a>) +or the +<a href="definitions.html#filled">no-fill mode</a> +set to +<a href="#lrc"><span style="font-style: normal">LEFT</span></a> +in order for these inlines to function properly. Please see +<a href="#important"><span style="font-style: normal">IMPORTANT</span></a>, +below. +</p> + +<p> +String tabs need to be marked off with +<a href="definitions.html#inlines">inline escapes</a> +before being set up with the +<a href="#st">ST</a> +macro. Any input line may contain string tab markers. <kbd +class="bold"><number></kbd>, above, means the numeric +identifier of the tab. The following shows a sample input line with +string tab markers. +<br/> +<span class="pre-in-pp"> + \*[ST1]Now is the time\*[ST1X] for all \*[ST2]good men\*ST2X] to come to the aid of the party. +</span> +String tab 1 begins at the start of the line and ends after the word +“time”. String tab 2 starts at “good” and +ends after “men”. Inline escapes (e.g. font or point +size changes, or horizontal movements, including +<a href="goodies.html#pad">padding</a>) +are taken into account when mom determines the position and length +of string tabs. +</p> + +<p> +Up to nineteen string tabs may be marked (not necessarily all on the +same line, of course), and they must be numbered between 1 and 19. +</p> + +<p> +Once string tabs have been marked in input lines, they have to be +“set” with +<kbd><a href="#st">.ST</a></kbd>, +after which they may be called, by number, with +<kbd><a href="#tab">.TAB</a></kbd>. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> Lines with string tabs marked off +in them are normal input lines, i.e. they get printed, just like +any input line. If you want to set up string tabs without the line +printing, use the +<a href="goodies.html#silent">SILENT</a> +macro. +</p> +</div> + +<div class="box-important"> +<p class="tip-top"> +<span id="important" class="important">IMPORTANT:</span> +Owing to the way groff processes +<a href="definitions.html#inputline">input lines</a> +and turns them into +<a href="definitions.html#outputline">output lines</a>, +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. +</p> + +<p> +Equally, she cannot guess the starting position if a line is fully +justified and broken with +<a href="#spread">SPREAD</a>. +</p> + +<p> +In other words, in order to use string tabs, +<a href="#lrc">LEFT</a> +must be active, or, if +<a href="#quad">QUAD LEFT</a> +or +<a href="#justify">JUSTIFY</a> +are active, the line on which the string tabs are marked must be +broken “manually” with +<kbd><a href="#br">.BR</a></kbd> +(but not +<kbd><a href="#spread">.SPREAD</a></kbd>). +</p> + +<p class="tip-bottom"> +To circumvent this behaviour, I recommend using the +<a href="goodies.html#pad">PAD</a> +to set up string tabs in centered or flush right lines. Say, for +example, you want to use a string tab to underscore the text of a +centered line with a rule. Rather than this, +<br/> +<span class="pre-in-pp"> + .CENTER + \*[ST1]A line of text\*[ST1X]\c + .EL + .ST 1 + .TAB 1 + .PT_SIZE 24 + .ALD 3p + \*[RULE] + .RLD 3p + .TQ +</span> +you should do: +<br/> +<span class="pre-in-pp"> + .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 +</span> +</p> +</div> + +<!-- -ST- --> + +<div class="macro-id-overline"> +<h3 id="st" class="macro-id">Set string tabs</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>ST</b> <kbd class="macro-args"><tab number> L | R | C | J [ QUAD ]</kbd> +</div> + +<p> +After string tabs have been marked off on an input line (see +<a href="#inline-st"><kbd>\*[ST]...\*[STX]</kbd></a>), +you need to “set” them by giving them a direction and, +optionally, the <kbd>QUAD</kbd> argument. In this respect, ST is +like +<a href="#tab-set">TAB_SET</a> +except that you don’t have to give ST an indent or a +line length (that’s already taken care of, inline, by +<kbd>\*[ST]...\*[STX]</kbd>). If you want string tab 1 to be left, +enter +<br/> +<span class="pre-in-pp"> + .ST 1 L +</span> +If you want it to be left and +<a href="definitions.html#filled">filled</a>, enter +<br/> +<span class="pre-in-pp"> + .ST 1 L QUAD +</span> +If you want it to be justified, enter +<br/> +<span class="pre-in-pp"> + .ST 1 J +</span> +See the +<a href="#string-tabs-tut">Quickie tutorial on string tabs</a> +for a full explanation of setting up string tabs. +</p> + +<!-- -TAB- --> + +<div class="macro-id-overline"> +<h3 id="tab" class="macro-id">Call tabs</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>TAB</b> <kbd class="macro-args"><tab number></kbd> +</div> +<p class="alias"> +<i>Alias:</i> <b>TB</b> +</p> + +<p> +After tabs have been defined (either with +<a href="#tab-set">TAB_SET</a> +or +<a href="#st">ST</a>), +TAB moves to whatever tab number you pass it as an argument. For +example, +<br/> +<span class="pre-in-pp"> + .TAB 3 +</span> +<br/> +moves you to tab 3. +</p> + +<div id="note-tn" class="box-tip"> +<p class="tip-top"> +<span class="note">Note:</span> TAB breaks the line preceding it and +advances 1 linespace. Hence, +<br/> +<span class="pre-in-pp"> + .TAB 1 + A line of text in tab 1. + .TAB 2 + A line of text in tab 2. +</span> +produces, on output +<br/> +<span class="pre-in-pp"> + A line of text in tab 1. + A line of text in tab 2. +</span> +If you want the tabs to line up, use +<a href="#tn">TN</a> +(Tab Next), like this: +<br/> +<span class="pre-in-pp"> + .TAB 1 + A line of text in tab 1. + .TN + A line of text in tab 2. +</span> +which produces +<br/> +<span class="pre-in-pp"> + A line of text in tab 1. A line of text in tab 2. +</span> +If the text in your tabs runs to several lines, and you want the +first lines of each tab to align, you must use the +<a href="#multicolumns-intro">multi-column</a> macros. +</p> + +<p id="tab-add-note" class="tip-bottom"> +<span class="additional-note">Additional note:</span> 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. +</p> +</div> + +<!-- -TN- --> + +<div class="macro-id-overline"> +<h3 id="tn" class="macro-id">Tab Next</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>TN</b> +</div> +<p class="requires"> +In tabs that aren’t given the <kbd class="normal">QUAD</kbd> +argument when they’re set up with +<a href="#tab-set" class="normal">TAB_SET</a> +or +<a href="#st" class="normal">ST</a>, +you must terminate the line preceding <kbd class="normal">.TN</kbd> +with the <kbd class="normal">\c</kbd> inline escape. See the +<a href="#tn-note" class="normal">ADDITIONAL NOTE</a>. +If you find remembering whether to put in the +<kbd class="normal">\c</kbd> bothersome, you may prefer to use the +<a href="definitions.html#inlines" class="normal">inline escape</a> +alternative to +<kbd class="normal">.TN</kbd>, +<kbd class="normal"><a href="inlines.html#TB+">\*[TB+]</a></kbd>, +which works consistently regardless of the fill mode. +</p> + +<p> +TN moves over to the next tab in numeric sequence (tab n+1) without +advancing on the page. See the +<a href="#note-tn">NOTE</a> +in the description of the TAB macro for an example of how TN works. +</p> + +<div id="tn-note" class="box-tip"> +<p class="tip-top"> +<span class="note">Note:</span> You must put text in the +<a href="definitions.html#inputline">input line</a> +immediately after TN. “Stacking” of TN’s is not +allowed. In other words, you cannot do +<br/> +<span class="pre-in-pp"> + .TAB 1 + Some text + .TN + Some more text + .TN + .TN + Yet more text +</span> +The above example, assuming tabs numbered from 1 to 4, should be entered +<br/> +<span class="pre-in-pp"> + .TAB 1 + Some text + .TN + Some more text + .TAB 4 + Yet more text +</span> +<span class="additional-note">Additional note:</span> +In versions of mom prior to 1.1.9, TN did not always work as +advertised on the last +<a href="definitions.html#outputline">output line</a> +of pages that contained a footer trap (e.g. one set with +<a href="#b-margin">B_MARGIN</a> +or in documents formatted using the +<a href="docprocessing.html#docprocessing">document processing macros</a>). +</p> + +<p> +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 +<kbd>QUAD</kbd> argument (see +<a href="#tab-set">TAB_SET</a> +and +<a href="#st">ST</a>) +you must always “join” <kbd>.TN</kbd> to +the line before it using the +<kbd><a href="#join">\c</a></kbd> +<a href="definitions.html#inlines">inline escape</a>, +as in the following example: +<br/> +<span class="pre-in-pp"> + .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.” +</span> +When output, the example will look like this: +<br/> +<span class="pre-in-pp"> + 1. The first rule of survival is “make and keep good friends.” +</span> +</p> + +<p class="tip-bottom"> +Conversely, if you did give a <kbd>QUAD</kbd> argument +to TAB_SET or ST, the +<kbd>\c</kbd> must not be used. +</p> +</div> + +<!-- -TQ- --> + +<div class="macro-id-overline"> +<h3 id="tq" class="macro-id">Tab Quit</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>TQ</b> +</div> + +<p> +TQ takes you out of whatever tab you were in, advances 1 linespace, +and restores the left margin, line length, quad direction and +<a href="definitions.html#filled">fill mode</a> +that were in effect prior to invoking any tabs. +</p> + +<div class="rule-short" style="margin-bottom: 24px;"><hr/></div> + +<!-- ==================================================================== --> + +<h2 id="multicolumns-intro" class="macro-group">Multiple columns</h2> + +<p> +Tabs are not by nature columnar, which is to say that if the text +inside a tab runs to several lines, calling another tab does not +automatically move to the +<a href="definitions.html#baseline">baseline</a> +of the first line in the previous tab. To demonstrate: +<br/> +<span class="pre-in-pp"> + .TAB 1 + Carrots + Potatoes + Broccoli + .TAB 2 + $1.99/5 lbs + $0.25/lb + $0.99/bunch +</span> +produces, on output +<br/> +<span class="pre-in-pp"> + Carrots + Potatoes + Broccoli + $1.99/5 lbs + $0.25/lb + $0.99/bunch +</span> +The multi-column macros allow you to set tabs in columnar fashion, +rather than line by line. When you invoke multi-column mode (with +<kbd><a href="#mco">.MCO</a></kbd> – +<span style="text-decoration: underline">M</span>ulti-<span style="text-decoration: underline">C</span>olumn <span style="text-decoration: underline">O</span>n), +mom saves the position of the current baseline. +<kbd><a href="#mcr">.MCR</a></kbd> +(<span style="text-decoration: underline">M</span>ulti-<span style="text-decoration: underline">C</span>olumn <span style="text-decoration: underline">R</span>eturn) +at any point while multi-columns are on returns you to the saved +position. Exiting multi-columns +(<kbd><a href="#mcx">.MCX</a></kbd> – +<span style="text-decoration: underline">M</span>ulti-<span style="text-decoration: underline">C</span>olumn e<span style="text-decoration: underline">X</span>it) +quits the current tab (if you’re in one) and moves you to the +bottom of the longest column. (Note that you do not have to use +multi-columns in conjunction with tabs.) +</p> + +<p> +Using our example above, but setting it in multi-column mode, +<br/> +<span class="pre-in-pp"> + .MCO + .TAB 1 + Carrots + Potatoes + Broccoli + .MCR + .TAB 2 + $1.99/5 lbs + $0.25/lb + $0.99/bunch + .MCX +</span> +produces +<br/> +<span class="pre-in-pp"> + Carrots $1.99/5 lbs + Potatoes $0.25/lb + Broccoli $0.99/bunch +</span> +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> Do not confuse MCO with +the +<a href="docprocessing.html#columns">COLUMNS</a> +macro in the +<a href="docprocessing.html#docprocessing">document processing macros</a>. +</p> +</div> + +<div id="index-multicolumns" class="macro-list-container"> +<h3 class="macro-list">Multi-columns macros</h3> + +<ul class="macro-list"> + <li><a href="#mco">MCO</a> – begin multi-column setting</li> + <li><a href="#mcr">MCR</a> – return to top of column</li> + <li><a href="#mcx">MCX</a> – exit multi-columns</li> +</ul> +</div> + +<!-- -MCO- --> + +<div class="macro-id-overline"> +<h3 id="mco" class="macro-id">Begin multi-column setting</h3> +</div> + +<div class="box-macro-args"> + Macro: <b>MCO</b> +</div> + +<p> +MCO (<span style="text-decoration: underline;">M</span>ulti-<span style="text-decoration: underline;">C</span>olumn <span style="text-decoration: underline;">O</span>n) is the macro you use to begin multi-column +setting. It marks the current +<a href="definitions.html#baseline">baseline</a> +as the top of your columns, for use later with +<a href="#mcr">MCR</a>. +See the +<a href="#multicolumns-intro">introduction to columns</a> +for an explanation of multi-columns and some sample +input. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> Do not confuse MCO with +the +<a href="docprocessing.html#columns">COLUMNS</a> +macro in the +<a href="docprocessing.html#docprocessing">document processing macros</a>. +</p> +</div> + +<!-- -MCR- --> + +<div class="macro-id-overline"> +<h3 id="mcr" class="macro-id">Return to top of column</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>MCR</b> +</div> + +<p> +Once you’ve turned multi-columns on (with +<kbd><a href="#mco">.MCO</a></kbd>), +<kbd>.MCR</kbd>, at any time, returns you to the top of +your columns. +</p> + +<!-- -MCX- --> + +<div class="macro-id-overline"> +<h3 id="mcx" class="macro-id">Exit multi-columns</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>MCX</b> <kbd class="macro-args">[ <distance to advance below longest column> ]</kbd> +</div> +<p class="requires"> +• Optional argument requires a <a href="definitions.html#unitofmeasure">unit of measure</a> +</p> + +<p> +MCX takes you out of any tab you were in (by silently invoking +<kbd><a href="#tq">.TQ</a></kbd>) +and advances to the bottom of the longest column. +</p> + +<p> +Without an argument, MCX advances 1 linespace below the longest +column. Linespace, in this instance, is the +<a href="definitions.html#leading">leading</a> +in effect at the moment MCX is invoked. +</p> + +<p> +If you pass the <kbd><distance></kbd> 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 +<br/> +<span class="pre-in-pp"> + .MCX 6p +</span> +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> If you wish to advance a precise +distance below the +<a href="definitions.html#baseline">baseline</a> +of the longest column, use MCX with an argument of 0 (zero; no unit +of measure required) in conjunction with the +<a href="#ald">ALD</a> +macro, like this: +<br/> +<span class="pre-in-pp" style="margin-bottom: -12px;"> + .MCX 0 + .ALD 24p +</span> +</p> +</div> + +<p> +The above advances to precisely 24 points below the baseline +of the longest column. +</p> + +<div class="rule-short" style="margin-bottom: 24px;"><hr/></div> + +<!-- ==================================================================== --> + +<h2 id="indents-intro" class="macro-group">Indents</h2> + +<p> +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). +</p> + +<h3 id="indents-handling" class="docs">How mom handles indents</h3> + +<p> +Mom provides five kinds of indents: left, right, both, temporary, +and hanging. Each is invoked by its own name: +</p> +<ul style="margin-top: -.5em; margin-bottom: -.5em;"> +<li>IL – Indent Left</li> +<li>IR – Indent Right</li> +<li>IB – Indent Both</li> +<li>HI – Hanging Indent</li> +<li>TI – Temporary Indent</li> +</ul> + +<p> +In addition, there are four macros to control exiting from +indents: +</p> +<ul style="margin-top: -.5em; margin-bottom: -.5em;"> +<li>IQ – quit all active indents</li> +<li>ILX – exit indent style left</li> +<li>IRX – exit indent style right</li> +<li>IBX – exit indent style both</li> +</ul> + +<p> +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 +<a href="#hi">Hanging indents</a> +and +<a href="#ti">Temporary indents</a>. +</p> + +<p> +The first time you invoke any of mom’s indents, you must +supply a measure. For example, +<br/> +<span class="pre-in-pp"> + .IL 2P +</span> +indents text 2 picas from the left margin (or current tab indent). +</p> + +<p> +When you want to exit the above indent, use either +<br/> +<span class="pre-in-pp" style="margin-bottom: -1em;"> + .IQ +</span> +or +<span class="pre-in-pp" style="margin-top: -.5em;"> + .ILX +</span> +The next time you want the same indent, invoke it without the +argument, like this: +<br/> +<span class="pre-in-pp"> + .IL +</span> +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: +<br/> +<span class="pre-in-pp"> + .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... + ... + ... +</span> +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. +</p> + +<p> +If you wanted the third block of text in the example above to be +right indented by just 2 picas (the original measure given to IR), +you would enter <kbd>.IR</kbd> without an argument. +</p> + +<p> +Because indent arguments are additive, putting a minus sign in front +of the argument can be used to subtract from the current value. +In the following example, the first line is indented 18 points, +the second is indented 36 points (18 + 18), and the third is again +indented 18 points (36 - 18). +<br/> +<span class="pre-in-pp"> + .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. +</span> +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 <kbd>CLEAR</kbd> to any of the +“indent quit” macros resets them to zero. +</p> +<ul style="margin-top: -.5em; margin-bottom: -.5em;"> + <li>IQ CLEAR – quit and clear all indents</li> + <li>ILX CLEAR – quit and clear indent style left</li> + <li>IRX CLEAR – quit and clear indent style right</li> + <li>IBX CLEAR – quit and clear indent style both</li> +</ul> + +<p> +Indent styles may be combined and manipulated separately. You +could, for example, have a left indent of 4 picas and a right indent +of 6 picas and control each separately, as in the following example. +<br/> +<span class="pre-in-pp"> + .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 +</span> +If, at <kbd>.IRX</kbd>, you wanted the text afterwards to have no +indents (either left or right), you would enter <kbd>.IQ</kbd>, +which exits all indent styles at once. +</p> + +<p> +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. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> see the section +<a href="docprocessing.html#behaviour">Typesetting macros during document processing</a> +for information and advice on using indents with the +<a href="docprocessing.html#docprocessing">document processing macros</a>. +</p> +</div> + +<div id="index-indents" class="macro-list-container"> +<h3 class="macro-list">Indents macros</h3> + +<ul class="macro-list"> + <li><a href="#il">IL</a> – Indent left</li> + <li><a href="#ir">IR</a> – Indent right</li> + <li><a href="#ib">IB</a> – Indent both</li> + <li><a href="#ti">TI</a> – Temporary indent, left</li> + <li><a href="#hi">HI</a> – Hanging Indent + <ul style="margin-left: -.5em; list-style-type: disc;"> + <li><a href="#num-lists">Recipe: a numbered list using hanging indents</a></li> + </ul></li> + <li><a href="#iq">IQ</a> – Quit indents, all</li> + <li><a href="#iq">ILX</a> – Exit indent style left</li> + <li><a href="#iq">IRX</a> – Exit indent style right</li> + <li><a href="#iq">IBX</a> – Exit indent style both</li> +</ul> +</div> + +<!-- -IL- --> + +<div class="macro-id-overline"> +<h3 id="il" class="macro-id">Indent left</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>IL</b> <kbd class="macro-args">[ <measure> ]</kbd> +</div> +<p class="requires"> +• The optional argument requires a <a href="definitions.html#unitofmeasure">unit of measure</a> +</p> + +<p> +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. +</p> + +<p> +The first time you invoke <kbd>.IL</kbd>, you must give it a +measure. Subsequent invocations with a measure add to the previous +measure. A minus sign may be prepended to the argument to subtract +from the current measure. The +<kbd><a href="inlines.html#inline-stringwidth-groff">\w</a></kbd> +<a href="definitions.html#inlines">inline escape</a> +may be used to specify a text-dependent measure, in which case no +unit of measure is required. For example, +<br/> +<span class="pre-in-pp"> + .IL \w'margarine' +</span> +indents text by the width of the word “margarine”. +</p> + +<p> +With no argument, IL indents by its last active value. See the +<a href="#indents-explanation">brief explanation of how mom handles indents</a> +for more details. +</p> + +<div class="box-tip"> +<p class="tip-top"> +<span class="note">Note:</span> Calling a tab (with +<kbd><a href="#tab">.TAB <n></a></kbd>) +automatically cancels any active indents. +</p> + +<p class="tip-bottom"> +<span class="additional-note">Additional note:</span> Invoking IL +automatically turns off IB. +</p> +</div> + +<!-- -IR- --> + +<div class="macro-id-overline"> +<h3 id="ir" class="macro-id">Indent right</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>IR</b> <kbd class="macro-args">[ <measure> ]</kbd> +</div> +<p class="requires"> +• The optional argument requires a <a href="definitions.html#unitofmeasure">unit of measure</a> +</p> + +<p> +IR indents text from the right margin of the page, or if +you’re in a tab, from the end of the tab. +</p> + +<p> +The first time you invoke <kbd>.IR</kbd>, you must give it a +measure. Subsequent invocations with a measure add to the previous +indent measure. A minus sign may be prepended to the argument to +subtract from the current indent measure. The +<kbd><a href="inlines.html#inline-stringwidth-groff">\w</a></kbd> +<a href="definitions.html#inlines">inline escape</a> +may be used to specify a text-dependent measure, in which case no +unit of measure is required. For example, <br/> +<span class="pre-in-pp"> + .IR \w'jello' +</span> +indents text by the width of the word “jello”. +</p> + +<p> +With no argument, IR indents by its last active value. See the +<a href="#indents-explanation">brief explanation of how mom handles indents</a> +for more details. +</p> + +<div class="box-tip"> +<p class="tip-top"> +<span class="note">Note:</span> Calling a tab (with +<kbd><a href="#tab">.TAB <n></a></kbd>) +automatically cancels any active indents. +</p> + +<p class="tip-bottom"> +<span class="additional-note">Additional note:</span> Invoking IR +automatically turns off IB. +</p> +</div> + +<!-- -IB- --> + +<div class="macro-id-overline"> +<h3 id="ib" class="macro-id">Indent both</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>IB</b> <kbd class="macro-args">[ <left measure> <right measure> ]</kbd> +</div> +<p class="requires"> +• The optional arguments require a <a href="definitions.html#unitofmeasure">unit of measure</a> +</p> + +<p> +IB allows you to set or invoke a left and a right indent at the same +time. +</p> + +<p> +At its first invocation, you must supply a measure for both indents; +at subsequent invocations when you wish to supply a measure, both +must be given again. As with 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. +</p> + +<p> +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. +</p> + +<p> +A minus sign may be prepended to the arguments to subtract from +their current values. The +<a href="inlines.html#inline-stringwidth-groff"><kbd>\w</kbd></a> +<a href="definitions.html#inlines">inline escape</a> +may be used to specify text-dependent measures, in which case no +unit of measure is required. For example, +<br/> +<span class="pre-in-pp"> + .IB \w’margarine’ \w'jello' +</span> +left indents text by the width of the word “margarine” +and right indents by the width of “jello”. +</p> + +<p> +Like IL and IR, IB with no argument indents by its last active +values. See the +<a href="#indents-explanation">brief explanation of how mom handles indents</a> +for more details. +</p> + +<div class="box-tip"> +<p class="tip-top"> +<span class="note">Note:</span> Calling a tab (with +<kbd><a href="#tab">.TAB <n></a></kbd>) +automatically cancels any active indents. +</p> + +<p class="tip-bottom"> +<span class="additional-note">Additional note:</span> Invoking IB +automatically turns off IL and IR. +</p> +</div> + +<!-- -TI- --> + +<div class="macro-id-overline"> +<h3 id="ti" class="macro-id">Temporary (left) indent</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>TI</b> <kbd class="macro-args">[ <measure> ]</kbd> +</div> +<p class="requires"> +• The optional argument requires a <a href="definitions.html#unitofmeasure">unit of measure</a> +</p> + +<p> +A temporary indent is one that applies only to the first line of +text that comes after it. Its chief use is indenting the first line +of paragraphs. (Mom’s +<a href="docelement.html#pp">PP</a> +macro, for example, uses a temporary indent.) +</p> + +<p> +The first time you invoke <kbd>.TI</kbd>, you must give +it a measure. If you want to indent the first line of a paragraph +by, say, 2 +<a href="definitions.html#em">ems</a>, +do +<br/> +<span class="pre-in-pp"> + .TI 2m +</span> +Subsequent invocations of TI do not require you to supply a measure; +mom keeps track of the last measure you gave it. +</p> + +<p> +Because temporary indents are temporary, there’s no need to +turn them off. +</p> + +<div class="box-important"> +<p class="tip"> +<span class="important">IMPORTANT:</span> Unlike IL, IR and IB, +measures given to TI are NOT additive. In the following example, +the second <kbd>.TI 2P</kbd> is exactly 2 picas. +<br/> +<span class="pre-in-pp" style="margin-bottom: -18px;"> + .TI 1P + The beginning of a paragraph... + .TI 2P + The beginning of another paragraph... +</span> +</p> +</div> + +<!-- -HI- --> + +<div class="macro-id-overline"> +<h3 id="hi" class="macro-id">Hanging indent</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>HI</b> <kbd class="macro-args">[ <measure> ]</kbd> +</div> +<p class="requires"> +• The optional argument requires a <a href="definitions.html#unitofmeasure">unit of measure</a> +</p> + +<p> +A hanging indent looks like this: +<br/> +<span class="pre-in-pp"> + 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... +</span> +The first line of text “hangs” outside the left margin. +</p> + +<p> +In order to use hanging indents, you must first have a left indent +active (set with either +<kbd><a href="#il">.IL</a></kbd> +or +<kbd><a href="#ib">.IB</a></kbd>). +Mom will not hang text outside the left margin set with +<kbd><a href="#l-margin">.L_MARGIN</a></kbd> +or outside the left margin of a tab. +</p> + +<p> +The first time you invoke <kbd>.HI</kbd>, you must give +it a measure. If you want the first line of a paragraph to hang by, +say, 1 pica, do +<br/> +<span class="pre-in-pp"> + .IL 1P + .HI 1P +</span> +Subsequent invocations of HI do not require you to supply a measure; +mom keeps track of the last measure you gave it. +</p> + +<p> +Generally speaking, you should invoke HI immediately prior to the +line you want hung (i.e. without any intervening +<a href="definitions.html#controllines">control lines</a>). +And because hanging indents affect only one line, there’s no +need to turn them off. +</p> + +<h4 id="num-lists" class="macro-id">Recipe: Numbered lists using hanging indents</h4> + +<div class="box-tip" style="margin-top: -.5em; margin-bottom: -.5em;"> +<p class="tip"> +<span class="note">Note:</span> mom has macros for setting lists (see +<a href="docelement.html#list-intro">Nested lists</a>). +This recipe exists to demonstrate the use of hanging indents only. +</p> +</div> + +<p style="margin-top: 1.5em;"> +Consider the following example: +<br/> +<span class="pre-in-pp"> + .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? +</span> +First, we invoke a left indent with a measure equal to the width of +2 +<a href="definitions.html#figurespace">figures spaces</a> +plus a period (using the +<a href="inlines.html#inline-stringwidth-groff"><kbd>\w</kbd></a> +inline escape). At this point, the left indent is active; text +afterwards would normally be indented. However, we invoke a +hanging indent of exactly the same width, which hangs the first +line (and first line only!) to the left of the indent by the +same distance (in this case, that means “out to the left +margin”). Because we begin the first line with a number, +a period, and a figure space, the actual text (“The most +important point...”) starts at exactly the same spot as the +indented lines that follow. +</p> + +<p> +Notice that subsequent invocations of <kbd>.HI</kbd> without a +measure produce exactly the same effect. +</p> + +<p> +Paste the example above into a file and preview it with <kbd>groff +-mom -X <filename></kbd> to see hanging indents in action. +</p> + +<div class="box-important"> +<p class="tip"> +<span class="important">IMPORTANT:</span> 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. +</p> +</div> + +<!-- -IX- --> + +<div class="macro-id-overline"> +<h3 id="iq" class="macro-id">Quitting indents</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>IQ</b> <kbd class="macro-args">[ CLEAR ]</kbd> (quit any/all indents — see IMPORTANT NOTE) +</div> +<br/> + +Macro: <b>ILX</b> <kbd class="macro-args">[ CLEAR ]</kbd> (exit Indent Left) +<br/> + +Macro: <b>IRX</b> <kbd class="macro-args">[ CLEAR ]</kbd> (exit Indent Right) +<br/> + +Macro: <b>IBX</b> <kbd class="macro-args">[ CLEAR ]</kbd> (exit Indent Both) + +<div class="box-important"> +<p class="tip-top"> +<span class="important">IMPORTANT NOTE:</span> 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. +</p> + +<p class="tip-bottom"> +As a consequence of this change, ILX, IRX and IBX may now also be +invoked as ILQ, IRQ and IBQ. Both forms are acceptable. +</p> +</div> + +<p> +Without an argument, the macros to quit indents merely restore your +original margins and line length. The measures stored in the indent +macros themselves are saved so you can call them again without +having to supply a measure. +</p> + +<p> +If you pass these macros the optional argument <kbd>CLEAR</kbd>, +they not only restore your original left margin and line length, but +also clear any values associated with a particular indent style. +The next time you need an indent of the same style, you have to +supply a measure again. +</p> + +<p> +<kbd>.IQ CLEAR</kbd>, as you’d suspect, +quits and clears the values for all indent styles at once. +</p> + +<div class="rule-long"><hr/></div> + +<!-- Navigation links --> +<table style="width: 100%; margin-top: 12px;"> +<tr> + <td style="width: 33%;"><a href="toc.html">Back to Table of Contents</a></td> + <td style="width: 33%; text-align: center;"><a href="#top">Top</a></td> + <td style="width: 33%; text-align: right;"><a href="goodies.html#top">Next: Goodies</a></td> +</tr> +</table> + +</div> + +<div class="bottom-spacer"><br/></div> + +</body> +</html> +<!-- vim: fileencoding=utf-8: nomodified: --> 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 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- +This file is part of groff, the GNU roff type-setting system. + +Copyright (C) 2004, 2005, 2006, 2009, 2010 Free Software Foundation, Inc. +Written by Peter Schaffter. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with the +Invariant Sections being this comment section, with no Front-Cover +Texts, and with no Back-Cover Texts. + +A copy of the Free Documentation License is included as a file called +FDL in the main directory of the groff source package. +--> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"> + +<head> + <meta http-equiv="content-type" content="text/html;charset=utf-8"/> + <title>Using mom</title> + <link rel="stylesheet" type="text/css" href="stylesheet.css" /> +</head> + +<body style="background-color: #f5faff;"> + +<!-- ==================================================================== --> + +<div id="top" class="page"> + +<!-- Navigation links --> +<table style="width: 100%;"> + <tr> + <td><a href="toc.html">Back to Table of Contents</a></td> + <td style="text-align: right;"><a href="typesetting.html#top">Next: The typesetting macros</a></td> + </tr> + </table> + +<h1 id="using" class="docs">Using mom</h1> + +<div style="text-align: center;"> +<ul class="no-enumerator" style="margin-left: -2.5em;"> + <li ><a href="#using-intro">Introduction</a></li> + <li ><a href="#using-macros">How to input mom’s macros</a></li> + <li ><a href="#using-previewing">How to preview documents</a></li> + <li ><a href="#using-saving">Saving documents</a></li> + <li ><a href="#using-printing">Printing documents</a></li> +</ul> +</div> + +<div class="rule-short" style="margin-top: 18px;"><hr/></div> + +<h2 id="using-intro" class="docs">Introduction</h2> + +<p> +As explained in the section +<a href="intro.html#top">What is mom?</a>, +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. <kbd>.PP</kbd> for +paragraphs, <kbd>.HEAD</kbd> for heads, +<kbd>.FOOTNOTE</kbd> for footnotes, etc.) that make a +lot of typesetting decisions automatically. +</p> + +<p> +You tell mom that you want to use the document processing macros +with the +<a href="docprocessing.html#start"><kbd>START</kbd></a> +macro, explained below. After <kbd>START</kbd>, +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. +</p> + +<h2 id="using-macros" class="docs">How to input mom’s macros</h2> + +<p> +Regardless of which way you use mom, the following apply: +</p> + +<ol style="margin-top: -.5em; margin-bottom: -.5em;"> + <li> + You need a good text editor for inputting mom files. + <span style="display: block; margin-top: .25em; margin-bottom: .5em;"> + I cannot recommend highly enough that you use an editor that + lets you write syntax highlighting rules for mom’s + macros and + <a href="definitions.html#inlines">inline escapes</a>. + Simply colourizing macros and inlines to half-intensity can be + enough to make text stand out clearly from formatting commands. + </span> + </li> + <li> + All mom’s macros begin with a period (dot) and must be + entered in upper case (capital) letters. + </li> + <li> + Macro + <a href="definitions.html#arguments">arguments</a> + are separated from the macro itself by spaces. Multiple + arguments to the same macro are separated from each + other by spaces. Any number of spaces may be used. All + arguments to a macro must appear on the same line as the + macro. + </li> + <li> + Any argument (except a + <a href="definitions.html#stringargument">string argument</a>) + that is not a digit must be entered in upper case + (capital) letters. + </li> + <li> + Any argument that requires a plus or minus sign must + have the plus or minus sign prepended to the argument + with no intervening space (e.g. <kbd>+2</kbd>). + </li> + <li> + Any argument that requires a + <a href="definitions.html#unitofmeasure">unit of measure</a> + must have the unit appended directly to the argument, with no + intervening space (e.g. <kbd>.5i</kbd>). + </li> + <li> + <a href="definitions.html#stringargument">String arguments</a>, + in the sense that the term is used in this manual, must be + surrounded by double-quotes + (<kbd>"<text of string>"</kbd>). Multiple + string arguments are separated from each other by spaces (each + argument surrounded by double-quotes, of course). + </li> + <li> + If a string argument, as entered in your text editor, becomes + uncomfortably long (i.e. runs longer than the visible portion of + your screen or window), you may break it into two or more lines + by placing the backslash character (<kbd>\</kbd>) + at the ends of lines to break them up, like this: + <span class="pre"> + .SUBTITLE "An In-Depth Consideration of the \ + Implications of Forty-Two as the Meaning of Life, \ + The Universe, and Everything" + </span> + </li> +</ol> + +<div class="box-tip"> +<p class="tip"> +<span class="tip">Tip:</span> +It’s important that formatted documents be easy to +read/interpret when you’re looking at them in a text editor. +One way to achieve this is to group macros that serve a similar +purpose together, and separate them from other groups of macros +with a blank comment line. In groff, that’s done with +<kbd>\#</kbd> on a line by itself. Consider the +following, which is a template for starting the chapter of a book. +<br/> +<span class="pre-in-pp"> + .TITLE "My Pulitzer Novel" + .AUTHOR "Joe Blow" + .CHAPTER 1 + \# + .DOCTYPE CHAPTER + .PRINTSTYLE TYPESET + \# + .FAM P + .PT_SIZE 10 + .LS 12 + \# + .START +</span> +</p> +</div> + +<h2 id="using-previewing" class="docs">How to preview documents</h2> + +<p> +Other than printing out hard copy, there are two well-established +methods for previewing your work. Both assume you have a working +X server. +</p> + +<p> +Groff itself comes with a quick and dirty previewer called +gxditview. Invoke it with: +<br/> +<span class="pre-in-pp"> + groff -X -mom filename +</span> +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 +(<a href="goodies.html#smartquotes">smartquotes</a> +and +<a href="goodies.html#leader">leaders</a> +come to mind). What it does have going for it is that it’s +fast and doesn’t gobble up system resources. +</p> + +<p> +A surer way to preview documents is with gv (ghostview). This +involves processing documents with groff and directing the default +PostScript output to a file, like this: +<br/> +<span class="pre-in-pp"> + groff -mom filename > filename.ps +</span> +You can then then open the ps file in gv. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="tip">Tip:</span> +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: +<br/> +<span class="pre-in-pp"> + groff -mom <filename> > <filename>.ps +</span> +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. <i>Voilà!</i>—instant +previewing. +</p> +</div> + +<h2 id="using-saving" class="docs">Saving documents</h2> + +<p> +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: +<br/> +<span class="pre-in-pp"> + groff -mom <filename> > <filename>.ps +</span> +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: +<br/> +<span class="pre"> + groff -mom <filename> | ps2pdf - <filename>.pdf +</span> +</p> + +<h2 id="using-printing" class="docs">Printing documents</h2> + +<p> +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: + +<span class="pre"> + groff -mom -l <filename> + groff -mom <filename> | lpr +</span> +</p> + +<p style="margin-top: -1.5em;"> +In the first, the <kbd>-l</kbd> 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 +<i>pipe</i> 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: +<br/> +<span class="pre-in-pp"> + groff -mom <filename> | lpr -P <printer_name> +</span> +</p> + +<div class="rule-long" style="margin-top: -.5em;"><hr/></div> + +<!-- Navigation links --> +<table style="width: 100%; margin-top: 12px;"> + <tr> + <td style="width: 33%;"><a href="toc.html">Back to Table of Contents</a></td> + <td style="width: 33%; text-align: center;"><a href="#top">Top</a></td> + <td style="width: 33%; text-align: right;"><a href="typesetting.html#top">Next: The typesetting macros</a></td> +</tr> +</table> + +</div> + +<div class="bottom-spacer"><br/></div> + +</body> +</html> +<!-- vim: fileencoding=utf-8: nomodified: --> |