diff options
Diffstat (limited to 'contrib/mom/momdoc/docprocessing.html')
| -rw-r--r-- | contrib/mom/momdoc/docprocessing.html | 4420 |
1 files changed, 4420 insertions, 0 deletions
diff --git a/contrib/mom/momdoc/docprocessing.html b/contrib/mom/momdoc/docprocessing.html new file mode 100644 index 0000000..4d09553 --- /dev/null +++ b/contrib/mom/momdoc/docprocessing.html @@ -0,0 +1,4420 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- +This file is part of groff, the GNU roff type-setting system. + +Copyright (C) 2004-2020 Free Software Foundation, Inc. +Written by Peter Schaffter (peter@schaffter.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 no +Invariant Sections, 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> + +<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 to document processing</a></h3> +<h3 class="toc toc-docproc-header" style="margin-top: .5em;"><a class="header-link" href="#defaults">Document defaults</a></h3> +<h3 class="toc toc-docproc-header" style="margin-top: .5em;"><a class="header-link" href="#vertical-whitespace-management">Vertical whitespace management</a></h3> +<h3 class="toc toc-docproc-header" style="margin-top: .5em;"><a class="header-link" href="#setup">Preliminary 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 (metadata)</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> + <li><a href="#pdftitle">PDF_TITLE</a></li> + <li><a href="#toc-heading">TOC_HEADING</a></li> + </ul></li> + <li><a href="#docstyle-macros"><b>The docstyle macros (templates)</b></a> + <ul class="toc-docproc"> + <li><a href="#doctype">DOCTYPE (default, chapter, letter, named, slides)</a></li> + <li><a href="#slides">DOCTYPE SLIDES</a> + <ul class="toc-docproc"> + <li><a href="#newslide">NEWSLIDE</a></li> + <li><a href="#pause">PAUSE</a></li> + <li><a href="#transition">TRANSITION</a></li> + </ul></li> + <li><a href="#printstyle">PRINTSTYLE</a></li> + <li><a href="#copystyle">COPYSTYLE</a></li> + </ul></li> + <li><a href="cover.html"><b>Cover pages</b></a></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> +</ul> +</div> +<div class="mini-toc-col-2"> +<br/> +<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"> + <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> +<ul class="toc-docproc" style="margin-top: -1em"> + <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> – get document leading back on track + <ul class="toc-docproc"> + <li><a href="#automatic-shimming">Automatic shimming (headings, etc)</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="#marking-col-start">Marking the first page column start position</a> + <ul class="toc-docproc"> + <li><a href="#col-mark">COL_MARK</a></li> + </ul></li> + <li><a href="#breaking-columns">Breaking columns manually</a> + <ul class="toc-docproc"> + <li><a href="#col-next">COL_NEXT</a> and <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#intro-doc-param"><b>Changing document-wide typesetting parameters after START</b></a> + <ul class="toc-docproc"> + <li><a href="docprocessing.html#index-doc-param">Post-START global style change macros</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></li> +</ul> +<h3 class="toc toc-docproc-header"><a class="header-link" href="#terminating">Terminating a document</a></h3> +</div> +</div> + +<div class="rule-short" style="margin-top: -1.75em"><br/><hr/></div> + +<!-- ==================================================================== --> + +<h2 id="docprocessing-intro" class="docs" style="margin-top: 1em">Introduction to document processing</h2> + +<p> +Document processing with mom uses markup tags to identify document elements +such as headings, paragraphs, blockquotes, and so on. The tags are, of course, +macros, but with sensible, readable names that make them easy +to grasp and easy to remember. (And don’t forget: if you +don’t like the “official” name of a tag — +too long, cumbersome to type in, not “intuitive” enough +— you can change it with the +<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 metadata about the document itself (title, +subtitle, author, etc.). Next, you tell mom what kind of document +you’re creating (e.g. a chapter, letter, abstract, etc...) and +what kind of output you want (typeset, typewritten, draft-style, +etc) — essentially, templates. Thirdly, you make as many +or as few changes to the templates as you wish; in other words, +create a style sheet. Lastly, you invoke the +<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 elsewhere 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="vertical-whitespace-management" class="macro-group">Vertical whitespace management</h2> + +<ul style="margin-left: -.5em;"> + <li><a href="#shim">Macro: SHIM</a></li> + <li><a href="#no-shim">Macro: NO_SHIM</a></li> + <li><a href="#flex">Macro: FLEX</a></li> + <li><a href="#no-flex">Macro: NO_FLEX</a></li> +</ul> + + +<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> +Mom offers two modes of operation for ensuring flush bottom margins: +shimming and flex-spacing. Shimming means that mom nudges the +next line after a significant break in running text back onto the +<a href="definitions.html#baseline-grid">baseline grid</a> +(e.g. after the insertion of a graphic). Flex-spacing means that any +vertical whitespace remaining between the end of running text and +the bottom margin is distributed equally at logical points on the +page. +</p> + +<p> +Mom uses the +<a href="definitions.html#leading">leading</a> +of running text (the “document leading”) that’s in effect +<i>at the start of running text on each page</i> +to establish the grid and space document elements such as heads or +blockquotes so that they adhere to it. (Prior to invoking +<a href="#start">START</a>, +the document leading is set with the +<a href="typesetting.html#macros-typesetting">typesetting macro</a> +<a href="typesetting.html#leading">LS</a>, +afterwards with the +<a href="definitions.html#controlmacro">document control macro</a> +<a href="#doc-lead">DOC_LEAD</a>.) +</p> + +<p> +What this means is that documents whose paragraphs are not separated +by whitespace and which do not contain graphics or +<a href="definitions.html#pre-processor">pre-processor material</a> +will fill the page completely to the bottom margin. +However, if your paragraphs are spaced, or if there are any leading +changes on a page, or if graphics or pre-processor material are +inserted, it’s very likely the bottom margins will hang +unless shimming or flex-spacing is enabled. +</p> + +<h3 id="shim-vs-flex" class="docs">Shimming <span style="text-transform: none">vs.</span> flex-spacing</h3> + +<p> +<b>Shimming</b> is mom’s default mode of operation. She applies it +automatically before headings, around quotes and blockquotes, and +beneath +<a href="definitions.html#float">floats</a> +and +<a href="definitions.html#preprocessor">pre-processor material</a>. +In addition, the +<a href="#shim">SHIM</a> +macro can be inserted into a document at any point to make sure +the text following falls on the baseline grid. +</p> + +<p> +This mode of operation works well in documents whose paragraphs are +not spaced. Deviations from the baseline grid, usually +caused by floats or pre-processor material, are corrected +immediately. If the shimming results in slightly unbalanced +whitespace around them, it can easily be remedied by passing the +<kbd>ADJUST</kbd> argument to the appropriate macro. +</p> + +<p> +If you do not want mom shimming automatically, +<a href="#no-shim">NO_SHIM</a> +turns shimming off globally and suppresses the SHIM macro. If you +want to disable shimming only for a particular float or +pre-processor, the <kbd>NO_SHIM</kbd> argument may be given to the +appropriate macro. +</p> + +<p> +<b>Flex-spacing</b> kicks in automatically whenever you turn shimming +off. In other words, if you want a document flex-spaced, +<kbd>.NO_SHIM</kbd> is how you achieve it. If, in addition to not +shimming, you don’t want mom flex-spacing either, +<a href="#no-flex">NO_FLEX</a> +lets you disable it, too. +</p> + +<p> +Flex-spacing differs from shimming in that mom doesn’t +correct deviations from the baseline grid. Rather, she distributes +whitespace left at the bottom of the page equally in appropriate +places. Like shimming, flex-spacing is automatically applied +before heads, after floats and pre-processor material, and around +quotes and blockquotes. Like shimming, flex-spacing can be +disabled for individual floats or pre-processor material with the +<kbd>NO_FLEX</kbd> flag. +</p> + +<p> +In addition, you can use the +<a href="#flex">FLEX</a> +macro to insert flex-spacing yourself into the document, which you +will almost certainly want to do if your paragraphs are spaced. +This is because paragraphs are not flex-spaced. Typographically, +the ideal for spaced paragraphs is that the space between them +remain constant. Paradoxically, the only way to achieve flush +bottom margins, or to correct excessive flex-spacing before a +heading, is by adding flex-space between the paragraphs. This +requires human judgment, and mom does not presume to decide for you. +</p> + +<p> +Shimming and flex-spacing are mutually exclusive. If the one is +active, the other isn’t unless you have disabled both. This means +that you cannot use the FLEX macro when shimming is enabled, or the +SHIM macro when flex-spacing is enabled. Mom will issue a warning +if you do. +</p> + +<p> +The choice of whether to use shimming or flex-spacing depends on +whether or not your paragraphs are spaced. In a document with +indented, non-spaced paragraphs, shimming and flex-spacing produce +nearly the same result, with shimming winning by an aesthetic hair. +In documents with spaced paragraphs, flex-spacing is the only way to +achieve flush bottom margins. +</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> +When shimming is enabled, which it is by default, the SHIM macro +allows you to nudge the line following it back onto the baseline +grid. In documents with non-spaced paragraphs, this prevents +the bottom margins from hanging. +</p> + +<p style="margin-bottom: -1em"> +Mom herself automatically applies shimming +</p> +<ul> + <li><i>before</i> headings</li> + <li><i>around</i> quotes and blockquotes</li> + <li><i>after</i> PDF images, tables, pic diagrams, equations, and floats</li> +</ul> + +<p> +You may sometimes find the amount of space generated by +<kbd>SHIM</kbd> looks too big, whether inserted manually into a +document or as a result of automatic shimming. +The situation occurs when the amount of shimming applied +comes close to the leading currently in effect, making it seem as if +there’s one linespace too much whitespace. +</p> + +<p> +The solution is simply to add <kbd>.SPACE -1v</kbd> or +<kbd>.RLD 1v</kbd> to the document immediately after +<kbd>.SHIM</kbd>. (Both <kbd>.SPACE -1v</kbd> and +<kbd>.RLD 1v</kbd> back up by one linespace.) +</p> + +<div class="macro-id-overline"> +<h3 id="no-shim" class="macro-id">NO_SHIM</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>NO_SHIM</b> <kbd class="macro-args"><none> | <anything></kbd> +</div> + +<p> +NO_SHIM, without an argument, disables automatic shimming, +suppresses the SHIM macro, and enables flex-spacing. +</p> + +<p> +NO_SHIM with any argument (e.g. <kbd>OFF</kbd>, <kbd>QUIT</kbd>, +<kbd>END</kbd>, <kbd>X</kbd>, etc) re-enables shimming if it has +been disabled and disables flex-spacing. +</p> + +<!-- -FLEX- --> + +<div class="macro-id-overline"> +<h3 id="flex" class="macro-id">FLEX</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>FLEX</b> <kbd class="macro-args">[ FORCE ]</kbd> +</div> + +<p> +When flex-spacing is enabled, the FLEX macro inserts flexible +vertical whitespace into a document. The amount of flex-space is +determined from any extra whitespace at the bottom of a page divided +by the number of flex points on the same page. +</p> + +<p style="margin-bottom: -1em"> +If flex-spacing is enabled, mom herself automatically applies +flex-spacing +</p> +<ul style="margin-bottom: -.5em"> + <li><i>before</i> headings</li> + <li><i>around</i> quotes and blockquotes</li> + <li><i>after</i> PDF images, tables, pic diagrams, equations, and floats</li> +</ul> + +<p> +Near the bottom of some pages, you may find that +<a href="definitions.html#float">floated</a> +or +<a href="definitions.html#preprocessor">pre-processor material</a>, +including images, or a single line of text afterwards, is not flush +with the bottom margin. This is a result of mom flex-spacing +<i>after</i> such material but not before. The solution to is +insert <kbd>.FLEX</kbd> immediately beforehand. +</p> + +<p> +There are some instances where mom inhibits flex-spacing, notably +after outputting floated material deferred from one page to the +next. Introducing FLEX by itself in these instances—say, +before a head or paragraph—will not have any effect; you must +pass FLEX the <kbd>FORCE</kbd> argument. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="important">Important note on flex-spacing policy:</span><br/> +Mom disables flex-spacing on +</p> +<ul style="margin-top: -1em; margin-bottom: -.5em"> + <li>the last page or column of a document, before the Table of Contents, + Endnotes, Bibliography, and/or any “Lists of...” + </li> + <li>the page preceding a + <a href="rectoverso.html#collate">COLLATE</a> + </li> + <li>the page preceding a + <a href="typesetting.html#NEWPAGE">NEWPAGE</a> + or + <a href="headfootpage.html#blankpage">BLANKPAGE</a> + </li> + <li>the column preceding a + <a href="#col-next">COL_NEXT</a> + or + <a href="#col-break">COL_BREAK</a> + </li> +</ul> + +<p> +If this is not what you want, insert +<a href="#no-flex"><kbd>.NO_FLEX OFF</kbd></a> +before the first flex-space point on the affected page or in the +affected column. +</p> + +<p> +Flex-spacing is also disabled for any page or column where +insufficient room at or near the bottom causes a +<a href="docelement.html#heading">HEADING</a> +or +<a href="images.html#tbl">table</a> +to be moved to the top of the next page. These situations cannot +be harmonized with flex-spacing except by adjusting your layout +to prevent them. You may try re-enabling flex-spacing for the +page (<kbd>.NO_FLEX OFF</kbd>) and manually inserting +flex-spaces at appropriate points, but the original whitespace is +usually large enough that re-distributing it merely changes +one layout gaffe into another. +</p> + +<p> +Very occasionally you may notice that a document element (spaced +paragraph, floated material, pre-processor material, or a PDF image) +near the bottom of page has also caused mom to disable flex-spacing +for that page. This occurs when the document element following it +is a +<a href="docelement.html#pp-space">spaced paragraph</a>. +</p> + +<p> +It is typographically acceptable for there to be space between +insertions in running text (e.g. an image) and the bottom margin when +the next page begins with a paragraph. If you’d like to +nudge the insertion a little closer to the bottom margin—not +all the way; that isn’t possible without pushing it to the +next page and disrupting subsequent flex-spacing—insert a +small amount of space beforehand with +<a href="typesetting.html#sp">SP</a>. +Do not, in these cases, use the <kbd>ADJUST</kbd> +argument (for example to +<a href="images.html#pdf-image">PDF_IMAGE</a>.) +</p> + +<p class="tip-bottom"> +In the case of a spaced paragraph itself near the bottom of the page +causing a break, re-enabling flex-spacing +(<kbd>.NO_FLEX OFF</kbd>) at an appropriate place in your input +file will resolve the issue, provided there is at least one +flex-point on the page. If not, add one or more. +</p> +</div> + +<div class="macro-id-overline"> +<h3 id="no-flex" class="macro-id">NO_FLEX</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>NO_FLEX</b> <kbd class="macro-args"><none> | <anything></kbd> +</div> + +<p> +NO_FLEX, without an argument, disables automatic flex-spacing +and suppresses the FLEX macro. If, in addition to NO_FLEX, NO_SHIM +has also been given, your document will be neither flex-spaced nor +shimmed. +</p> + +<p> +NO_FLEX with any argument (e.g. <kbd>OFF</kbd>, <kbd>QUIT</kbd>, +<kbd>END</kbd>, <kbd>X</kbd>, etc) re-enables flex-spacing if it has +been disabled. +</p> + +<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, headings, +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 template;</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 (metadata). The reference macros are: +</p> +<div style="width: 50%; float: left;"> +<ul> + <li>TITLE</li> + <li>SUBTITLE</li> + <li>AUTHOR</li> + <li>CHAPTER – chapter number</li> + <li>CHAPTER_TITLE</li> + <li>DRAFT – draft number</li> + <li>REVISION – revision number</li> +</ul> +</div> +<div> +<ul> + <li>COPYRIGHT – only used on cover pages</li> + <li>MISC – only used on cover pages</li> + <li>DOCTITLE</li> + <li>COVERTITLE</li> + <li>DOC_COVERTITLE</li> + <li>PDF_TITLE</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”, and they’re essentially templates. +</p> +<ul style="margin-top: -.5em; margin-bottom: -.5em;"> + <li>PRINTSTYLE—typeset or typewritten</li> + <li>DOCTYPE—the type of document (default, chapter, user-defined, letter, slide)</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. 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 reasonable defaults for every document element +and tag, 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 +<a href="definitions.html#controlmacro">control macros</a>. +This is the stylesheet section of a document, and +must come after the +<a href="#printstyle">PRINTSTYLE</a> +directive. Failure to observe this condition will result in +PRINTSTYLE overriding your 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 \"ie 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. +</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 \"ie 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 (metadata)</h2> + +<p> +The reference macros give mom the metadata 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> + <li><a href="#pdftitle">PDF_TITLE</a> – window title for PDF viewers</li> + <li><a href="#toc-heading">TOC_HEADING</a> – single, non-pagenumbered line of text in table of contents</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 class="macro-args">[COVER | DOC_COVER] "<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> + +<p> +If the optional argument, <kbd>COVER</kbd> or <kbd>DOC_COVER</kbd>, +is given to TITLE, the remaining string arguments represent the +title 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 titles appear on the document cover, the cover +(“title”) page, and in the document header. For +example, +<br/> +<span class="pre-in-pp"> + .TITLE DOC_COVER "Collected Essays" + .TITLE COVER "The Meming of Meaning" + .TITLE "LOL Cat Corruption" + .AUTHOR "D. Rawkins" + .DOC_COVER TITLE AUTHOR + .COVER TITLE + .START +</span> +creates a document cover with “Collected Essays” and the +author, a cover page with “The Meming of Meaning”, +and a docheader title, “LOL Cat Corruption” at the top +of the essay. +</p> + +<p> +Alternatively, you can use the macros +<a href="#doc-covertitle">DOC_COVERTITLE</a> +and +<a href="#covertitle">COVERTITLE</a> +to accomplish the same thing. +</p> + +<h4 id="no-toc-entry" class="docs">Table of Contents exceptions</h4> +<p> +Except for standalone documents (i.e. non-collated documents such +as essays), the TITLE string appears as an entry in the Table of +Contents. If you would like a document section not to appear in the +Table of Contents (e.g. the copyright page), invoke the macro +<kbd>.NO_TOC_ENTRY</kbd> after <kbd>.TITLE</kbd>. +</p> + + +<!-- -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), and appears +</p> + +<ol style="list-style-type: lower-alpha"> + <li>as the window title in PDF viewers (e.g. Okular or Evince)</li> + <li>in the initial rightmost position of page headers in the document</li> +</ol> + +<p> +Moreover, DOCTITLE does not appear in the +<a href="definitions.html#pdfoutline">PDF outline</a>, +as its presence in window title would make it redundant. +</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 in +<a href="definitions.html#header">page headers</a> +is 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> + +<!-- -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> +If you would like a blank chapter string, i.e., you’d like the +chapter number to appear without “Chapter” beforehand, +enter <kbd>.CHAPTER_STRING "\&"</kbd>. +</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 required argument 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> +The optional argument, <kbd>COVER</kbd> or <kbd>DOC_COVER</kbd>, +should only be used if you have both a doc cover and a cover and want +differing copyright information on each (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> + +<p> +Style parameters for the copyright line may be +entered as individual macros or +<a href="docelement.html#grouping">grouped</a>, +e.g. +<br/> +<span class="pre-in-pp"> + .COPYRIGHT_FAMILY H + .COPYRIGHT_FONT R + .COPYRIGHT_SIZE -2 +</span> +or +<br/> +<span class="pre-in-pp"> + .COPYRIGHT_STYLE \ + FAMILY H \ + FONT R \ + SIZE -2 +</span> +The vertical position of the copyright line may be raised (-) or +lowered (+) with the macro COPYRIGHT_V_ADJUST. For example, to +raise the copyright line by 3 +<a href="definitions.html#picaspoints">points</a>, you’d do +<br/> +<span class="pre-in-pp"> + .COPYRIGHT_V_ADJUST -3p +</span> +Alternatively, the COPYRIGHT_STYLE macro may be used with the +argument <kbd>V_ADJUST</kbd>: +<span class="pre-in-pp"> + .COPYRIGHT_STYLE \ + FAMILY H \ + FONT R \ + SIZE -2 \ + V_ADJUST -3p +</span> +</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 +<kbd>COVERTITLE</kbd> or <kbd>DOC_COVERTITLE</kbd> is explicitly +passed to +<a href="cover.html#cover">COVER</a> +or +<a href="cover.html#doc-cover">DOC_COVER</a>. +</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> + +<p> +You only require COVERTITLE or DOC_COVERTITLE if they differ from +TITLE. Note that +<a href="#title">TITLE</a> +itself has two optional arguments that accomplish the same thing. +</p> + +<div class="macro-id-overline"> +<h3 class="macro-id">PDF Title</h3> +</div> + +<div id="pdftitle" class="box-macro-args"> +Macro: <b>PDF_TITLE</b> <kbd class="macro-args">"<pdf viewer window title>"</kbd> +</div> +<p class="requires"> +• Argument must be enclosed in double-quotes +</p> + +<p> +Except for +<a href="#doc-title">DOCTITLE</a>, +mom does not, by default, provide PDF viewers with a document title. +You may set one, if you like, with PDF_TITLE. +</p> + +<div class="macro-id-overline"> +<h3 class="macro-id">TOC heading</h3> +</div> + +<div id="toc-heading" class="box-macro-args"> +Macro: <b>TOC_HEADING</b> <kbd class="macro-args">"<single line TOC heading>"</kbd> +</div> +<p class="requires"> +• Argument must be enclosed in double-quotes +</p> + +<p> +Mom generates tables of contents automatically (see +<a href="tables-of-contents.html#toc">TOC</a>). +You may sometimes want to insert a line of text into the table of +contents without it referring to a page number, for example to +identify a “Part I” and a “Part II.” +</p> + +<p> +Placed before any instance of +<a href="#start">START,</a> +TOC_HEADING inserts its text into the table of contents with a +modest amount of whitespace around it to distinguish it easily +from table of contents entries. +</p> + +<p> +The appearance of the heading may be controlled with +the macro +<a href="#toc-heading-style">TOC_HEADING_STYLE</a>. +</p> + +<div id="toc-heading-style" class="box-macro-args"> +Macro: <b>TOC_HEADING_STYLE</b> <kbd class="macro-args">"<arguments>"</kbd> +</div> + +<p> +TOC_HEADING_STYLE controls the look of TOC headings. It is a +<a href="docelement.html#grouping">“grouping”</a> +style macro with multiple arguments. It is recommended that +you use the backslash character to separate them into individual +lines rather than entering a single, very long line. +</p> + +<p> +TOC_HEADING_STYLE accepts as many or as few arguments as you need: +<span class="pre-in-pp"> + FAMILY <family> \ + FONT <font> \ + SIZE <+|-n> \ + COLOR <colorname>* \ + QUAD L | C | R \ + SPACE_ABOVE <n>** \ + SPACE_BENEATH <n>** +</span> + * <kbd>COLOR</kbd> must be pre-initialized with +<a href="color.html#newcolor">NEWCOLOR</a> +or +<a href="color.html#xcolor">XCOLOR</a>. +<br/> +** <kbd>SPACE_ABOVE</kbd> and <kbd>SPACE_BENEATH</kbd> require a +<a href="definitions.html#unitofmeasure">unit of measure</a> +to be appended to their numeric argument. +</p> + +<p> +For example, if you want your TOC headings to be bold, slightly +larger than the rest of the table of contents, centred, and with +one linespace beforehand, +<span class="pre-in-pp"> + FONT B \ + SIZE +.5 \ + QUAD C \ + SPACE_ABOVE 1v +</span> +</p> + +<p> + See +<a href="docelement.html#control-macro-args">Arguments to the control macros</a> +for further information about the arguments. Note that +<kbd>SPACE_ABOVE</kbd> and <kbd>SPACE_BENEATH</kbd> are unique to +TOC_HEADING_STYLE. + +</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></li> + <li><a href="#printstyle">PRINTSTYLE</a> – non-optional macro required for document processing + <ul style="margin-left: -.5em; list-style-type: disc;"> + <li><a href="#typeset-defaults">Defaults for PRINTSTYLE TYPESET</a></li> + <li><a href="#typewrite-defaults">Defaults for PRINTSTYLE TYPEWRITE</a> + <ul style="margin-left: -.5em; list-style-type: circle;"> + <li><a href="#typewrite-control">PRINTSTYLE TYPEWRITE control macros</a> + <ul style="margin-left: -1.5em; list-style-type: square;"> + <li><a href="#typewriter-family">Family</a></li> + <li><a href="#typewriter-size">Point size</a></li> + <li><a href="#typewriter-underlining">Underlining of italics</a></li> + </ul></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 | SLIDES</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> and <kbd>SLIDES</kbd> tells her you want to write +a letter or create slides. +</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 id="default-doctype"> +<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> + +<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> + +<div class="box-tip"> +<p id="doctype-note" class="tip"> +<span class="note">Note: version 2.1 change</span> +<br/> +<kbd>DOCTYPE NAMED "string"</kbd> no longer accepts a colour +argument after <kbd>"string"</kbd>. Setting the colour +of the string is now done with <kbd><span class="nobr">DOCTYPE_COLOR +<color></span></kbd>. Default underscoring of +<kbd>"string"</kbd> in the docheader and on covers +has been removed. Use <kbd>DOCTYPE_UNDERSCORE</kbd>, +<kbd>DOC_COVER_DOCTYPE_UNDERSCORE</kbd> and/or +<kbd>COVER_DOCTYPE_UNDERSCORE</kbd> to re-enable it. All three take +the same arguments listed in the +<a href="docelement.html#underscore">Underscore style, rule weight</a> +section of +<a href="docelement.html#control-macro-args">Arguments to the control macros</a>. +</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> + +<h4 id="slides" class="docs" style="font-size: 100%; text-transform: uppercase">Slides</h4> + +<p> +PDF slides are a special kind of mom document, formatted for viewing +in a PDF reader’s presentation mode. In most respects, they +behave identically to the other document types. Key differences +are: +</p> +<ul style="margin-top: -.5em"> +<li>headers, footers, and pagination are disabled by default</li> +<li>type is set +<a href="typesetting.html#quad">QUAD CENTER</a> +by default</li> +<li> +<a href="#flex">flex-spacing</a> +and +<a href="#shim">shimming</a> +are disabled by default; shimming may +be re-enabled (with <kbd>NO_SHIM OFF</kbd>), but not flex-spacing</li> +<li>there’s no need for +<a href="#printstyle">PRINTSTYLE</a></li> +</ul> + +<p> +DOCTYPE SLIDES takes up to five optional arguments, which come +immediately after SLIDES. They may be entered in any order. +<br/> +<span class="pre-in-pp"> + DOCTYPE SLIDES \ + ASPECT 4:3 | 16:9 \ + HEADER "left" "centre" "right" \ + FOOTER "left" "centre" "right" \ + TRANSITION "<slide transition effect>" (mode + parameters) \ + PAUSE "<text reveal effect>" (mode + parameters) +</span> +For convenience, you many want to enter each argument on a single +line as shown above; all but the last must be terminated by a +backslash. +</p> + +<h5 class="docs" style="margin-top: .5em">Aspect</h5> + +<p> +Slides can be formatted for one of two aspect ratios common to +monitors and screens: 4:3 and 16:9. The default is 16:9. +<span class="pre-in-pp"> + 4:3 16:9 + media size: 11" x 8.25" media size: 11" x 8.1875" + left/right margins: 36 points left/right margins: 36 points + top margin: 90 points top margin: 80 points + bottom margin: 84 points bottom margin: 72 points + base text size: 16 points base text size: 14 points + autoleading: 6 points, adjusted autoleading: 4 points, adjusted + (header/footer size: -3 points) (header/footer size: -2 points) +</span> +Note that both media sizes fit on either A4 or US LETTER papersizes. +</p> + +<h5 class="docs" style="margin-top: .5em">Headers, footers, and pagination</h5> + +<p> +If you want a header, footer, or both for your slides, pass SLIDES +the <kbd>HEADER</kbd> and/or <kbd>FOOTER</kbd> argument(s). Both +take three additional +<a href="definitions.html#stringargument">string arguments</a>, +which must be enclosed in double-quotes, defining the left, centre, +and right parts of the header/footer. Any parts you want left blank +should be entered as two double-quotes. For example, +<span class="pre-in-pp"> + HEADER "" "My slide presentation" "" +</span> +will result in a header with only the centre part. +</p> + +<p> +Normal pagination is disabled for slides. If you want your slides +numbered, the slide number must be given to one of the header/footer +parts with the +<a href="definitions.html#inlines">inline escape</a> +<br/> +<kbd><span class="nobr">\*[SLIDE#]</span></kbd>. For example: +<span class="pre-in-pp"> + HEADER "" "My slide presentation" "" \ + FOOTER "" "" "\*[SLIDE#]" +</span> +will give you a centred header with numbering at the bottom right of +the slide. +</p> + +<p> +The overall family, size, and colour of headers may be set with +HEADER_FAMILY, HEADER_SIZE, and HEADER_COLOR. If you request +FOOTERS, you may use the FOOTER_ equivalent of these macros. +If you request both headers and footers, use one or the other but +not both. For example, in a header/footer situation, HEADER_FAMILY +would determine the family for both headers and footers, but if you +attempted to do this +<span class="pre-in-pp"> + .HEADER_FAMILY T + .FOOTER_FAMILY H +</span> +FOOTER_FAMILY would take precedence, and your header family would be +“<kbd>H</kbd>”. +</p> + +<p> +All other formatting of individual header/footer parts must be +entered as inline escapes inside the double-quotes. If you want, +say, your headers to be red but your footer page numbering to be +black and two points larger, this is how you’d do it: +<span class="pre-in-pp"> + .HEADER_COLOR red + .DOCTYPE SLIDES \ + HEADER "" "My slide presentation" "" \ + FOOTER "" "" "\*[black]\*S[+2]\*[SLIDE#]\*S[-2]" +</span> +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +Do not use mom’s +<a href="inlines.html#inline-size-mom"><kbd><span class="nobr">\*[SIZE ±n]</span></kbd></a> +inline escape to change point size in the strings +passed to HEADER or FOOTER. Prefer either mom’s +<kbd><span class="nobr">\*S[±n]</span></kbd> or groff’s +<kbd><span class="nobr">\s[±n]</span></kbd>. +</p> +</div> + +<h5 class="docs" style="margin-top: .5em">Transition</h5> + +<p> +“Transition” refers to how new slides appear during a +presentation. The official PDF specification lists a number of modes, +each with a choice of configurable parameters. Modes include Box, +Blinds, Wipe, Fade, and several others. Parameters include things +like duration, dimension, and direction. There are a total of +twelve modes; for each one there are from one to six configurable +parameters. Consult <kbd>man gropdf(1)</kbd> for a complete listing +of modes and parameters. +</p> + +<p> +If you pass SLIDES the <kbd>TRANSITION</kbd> argument, you must +at a minimum follow it with a mode. Afterwards, you may give as +many or as few parameters as you wish. Parameters are, in order, +<span class="pre-in-pp"> + 1. duration + 2. dimension + 3. motion + 4. direction + 5. scale + 6. bool +</span> +You don’t have to fill them all out. If you only need the +first three, that’s all you need to input. If you need the +first and third, enter the second as a period (dot), which is used +any time you want to leave a parameter at its current default or +when it isn’t applicable. For example, if you want a Box +transition that lasts 1 second, filling the screen from the centre +outwards, you’d enter +<span class="pre-in-pp"> + TRANSITION "Box 1 . O" +</span> +because Box does not take a “dimension” parameter but it +does take a motion parameter. +</p> + +<p> +Notice that the entire string (mode+parameters) must be enclosed in +double-quotes. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +Not all PDF viewers support all modes. Any that are not supported +are replaced by the “R” mode, which simply replaces one +slide with the next unless the PDF viewer has a different default +transition mode. +</p> +</div> + +<h5 class="docs" style="margin-top: .5em">Pause</h5> + +<p> +A “pause” occurs when material on a slide is halted (see +<a href="#pause">PAUSE</a>), +awaiting a mouse click, PgDown, Next, or the spacebar to reveal +subsequent material. All the same modes and parameters as +<kbd>TRANSITION</kbd> may be used. The manner of entering them is +is identical, including that the entire mode+parameter string must +be enclosed in double-quotes. +</p> + +<div class="macro-id-overline"> +<h3 id="slide-macros" class="macro-id">SLIDE MACROS</h3> +</div> + +<div id="newslide" class="box-macro-args"> +Macro: <b>NEWSLIDE</b> <kbd class="macro-args">["<transition mode and parameters>"]</kbd> +</div> + +<p> +Unless you want material from one slide to flow onto the next, you +need to tell mom when to start a new slide with the macro NEWSLIDE. +Without any arguments, the new slide will appear with the default +TRANSITION you gave to DOCTYPE SLIDES. +</p> + +<p> +If you would like a different transition, you may pass NEWSLIDE a +new mode and associated parameters, following the same rules as the +TRANSITION argument to DOCTYPE. Note that the new effect becomes +the default. If you wish to return to the original transition, you +must give it explicitly to the appropriate NEWSLIDE. +</p> + +<div id="pause" class="box-macro-args"> +Macro: <b>PAUSE</b> <kbd class="macro-args">["<pause mode and parameters>"]</kbd> +</div> + +<p> +Pauses in slides are accomplished by entering the macro PAUSE at +desired locations in your input file. Subsequent material will be +revealed using the pause mode given to DOCTYPE SLIDES. +</p> + +<p> +If you would like a different mode, you may pass PAUSE a +new mode and associated parameters, following the same rules as the +PAUSE argument to DOCTYPE. +</p> + +<div id="transition" class="box-macro-args"> +Macro: <b>TRANSITION</b> <kbd class="macro-args">["<transition mode and parameters>"]</kbd> +</div> + +<p> +If for some reason you have material that flows from one slide to +the next <i>and</i> you want the next slide to have a transition +different from the current one, you can tell mom about the new +transition with the macro TRANSITION anywhere prior to the break to +the next slide. +</p> + +<h4 id="slide-printing" class="docs" style="font-size: 100%; text-transform: uppercase">Printing slides</h4> + +<p> +If you want to print slides as handouts, you have to tell +<kbd>pdfmom</kbd> or <kbd>gropdf</kbd>, otherwise printing will +stop at the first pause. Simply precede <kbd>pdfmom</kbd> or +<kbd>gropdf</kbd> with GROPDF_NOSLIDE=1, like this: +<br/> +<span class="pre-in-pp"> + GROPDF_NOSLIDE=1 pdfmom <options> slidefile.mom > slidefile.pdf +</span> + +</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, except in the case of +slides +<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"> +<span class="important">Just as important:</span> +<b>PRINTSTYLE must precede any and all page and style +parameters associated with a document</b> with the exception of +<kbd>PAPER</kbd>, which should be placed at the top of your file. +PRINTSTYLE sets up complete templates that include default margins, +family, fonts, point sizes, and so on. Therefore, changes to any +aspect of document style must come afterwards. For example, +<br/> +<span class="pre-in-pp"> + .PAPER A4 + .LS 14 + .QUAD LEFT + .PRINTSTYLE TYPESET +</span> +will not change mom’s default document leading to 14 points, +nor the default justification style (fully justified) to left +justified, whereas +<br/> +<span class="pre-in-pp"> + .PAPER A4 + .PRINTSTYLE TYPESET + .LS 14 + .QUAD LEFT +</span> +will. +</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> +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 +(<a href="inlines.html#inline-size-mom"><kbd><span class="nobr">\*S[<size>]</span></kbd></a> +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="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</h3> + +<h4 id="typewriter-family" class="docs">Family</h4> + +<p style="margin-top: .5em;"> +If you’d prefer a monospace +<a href="definitions.html#family">family</a> +for PRINTSTYLE <kbd>TYPEWRITE</kbd> other than mom’s +default, Courier, you can change it with +<kbd>.TYPEWRITER_FAMILY <family></kbd> (or +<kbd>.TYPEWRITER_FAM</kbd>). Since groff ships with only the +Courier family, you will have to install any other monospace family +yourself. See +<a href="appendices.html#fonts">Adding fonts to +groff</a>. +</p> + +<h4 id="typewriter-size" class="docs">Point size</h4> + +<p style="margin-top: .5em;"> +If you’d like a smaller or larger point size for +PRINTSTYLE <kbd>TYPEWRITE</kbd> (mom’s default is 12-point), +you can change it with +<kbd>.TYPEWRITER_SIZE <size></kbd>. There’s no need to +add a +<a href="definitions.html#unitofmeasure">unit of measure</a> +to the <kbd><size></kbd> argument; points is assumed. Be +aware, however, that regardless of point size, mom’s +leading/linespacing for <kbd>TYPEWRITE</kbd> is fixed at 24-point +for double-spaced, and 12-point for single-spaced. +</p> + +<h4 id="typewriter-underlining" class="docs">Underlining of italics</h4> + +<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><span class="nobr">\*[SLANT]</span></kbd></a> +<a href="definitions.html#inlines">inline escape</a> +for pseudo-italics. (See +<a href="goodies.html#underline">UNDERLINE</a> +for a note on how to process TYPEWRITE files that underline +italics.) +</p> + +<p id="printstyle-italics"> +If you’d prefer that mom were less bloody-minded +about pretending to be a typewriter (i.e., you’d like italics and +pseudo-italics to come out as italics), use the control macros +<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 id="underline-quotes"> +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> +While most of the +<a href="docelement.html#docelement-control">control macros</a> +have no effect on PRINTSTYLE <kbd>TYPEWRITE</kbd>, 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 +<a href="#copystyle">COPYSTYLE</a> +is <kbd>DRAFT</kbd>). +</p> + +<p class="tip-bottom"> +Finally, note that colour is disabled for <kbd>TYPEWRITE</kbd>. If +you would like it enabled, for example so PDF links are colourised, +invoke the groff +<a href="definitions.html#primitives">primitive</a> +'<kbd>.color</kbd>' after PRINTSTYLE. +</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 typestyle and formatting parameters before START</h2> + +<p> +In the third (optional) part of setting up a document (the +stylesheet; 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="font-size: 100%; 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="#color">Initializing colours</a></li> + </ul></li> + <li><a href="#include">Including (sourcing) style sheets and files</a></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="font-size: 100%; line-height: 120%;"> + <li><a href="#docheader-control">Docheader control</a></li> + </ul></li> + <li><a href="#columns">COLUMNS</a> + <ul class="sublist" style="font-size: 100%; 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="important">Important:</span> +Do not use the macros listed in +<a href="#intro-doc-param">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 style="margin-top: -.75em;"> +Other macros that deal with type style, or refinements thereof +(<a href="typesetting.html#kern">KERN</a>, +<a href="typesetting.html#ligatures">LIGATURES</a>, +<a href="typesetting.html#hy">HY</a>, +<a href="typesetting.html#ws">WS</a>, +<a href="typesetting.html#ss">SS</a>, +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="#intro-doc-param">Changing document-wide typesetting 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 +(<a href="docelement.html#pp">PP</a>, +<a href="docelement.html#heading">HEADING</a>, +<a href="docelement.html#blockquote">BLOCKQUOTE</a>, +<a href="docelement.html#footnote">FOOTNOTE</a>, +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 stylesheet files +and include, or “source”, them into your mom documents +with the macro <kbd>.INCLUDE</kbd>. 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 +HEADIING control macros. +<br/> +<span class="pre-in-pp"> + .HEADING_STYLE 1 \ + FAMILY H \ + FONT BI \ + QUAD L \ + NO_UNDERSCORE +</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 +stylesheet is in <kbd>/home/joe/stylesheets</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/stylesheets/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="note">Note:</span> +INCLUDE is an alias for the groff request <kbd>.so</kbd>. If the +sourced file contains material that requires pre-processing (e.g. +a table made with <b>tbl(1)</b> or non-English characters), use +<kbd>.so</kbd> rather than INCLUDE and invoke pdfmom thus: +<br/> +<span class="pre-in-pp"> + soelim file.mom | pdfmom [flags] > file.pdf +</span> +<b>soelim</b> only looks for lines that begin with <kbd>.so</kbd>, +which furthermore must not have any space between the period and +the “s”. +</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><span class="nobr">\*[<colorname>]</span></kbd></a> +can be used at any time during document processing for occasional +colour effects. However, consistent and reliable colourising of +various document elements (the docheader, heads, linebreaks, +footnotes, pagenumbers, and so on) must be managed through the use +of the +<a href="docelement.html#docelement-control">document element control macros</a>. +</p> + +<p> +Please note that colour is disabled if your +<a href="#printstyle">PRINTSTYLE</a> +is <kbd>TYPEWRITE</kbd>. If you would like it enabled, for example +so PDF links are colourised, invoke the groff +<a href="definitions.html#primitives">primitive</a> +'<kbd>.color</kbd>' after PRINTSTYLE. +</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><span class="nobr">\*[<colourname>]</span></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#heading">HEADING</a>. +Use, rather, the +<a href="definitions.html#controlmacro">control macros</a> +mom provides to automatically colourise 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>, +<kbd>.DOC_LEAD_ADJUST 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 ] [ NO_SHIM ]</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> + +<p> +With <kbd>.DOCHEADER OFF</kbd>, it is possible to create your own +custom docheaders (after +<a href="#start">START</a>) +using mom’s typesetting macros. It is recommended that if you +do create a custom docheader, you make +<a href="docprocessing.html#shim"><kbd>.SHIM</kbd></a> +the last macro before the first item of your document (for +example, <kbd>.PP</kbd> or <kbd>.HEADING 1</kbd>. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +You may have tried <kbd>DOCHEAHER OFF</kbd> with a distance argument +and discovered that mom will not budge the starting position of the document +from her chosen default location. This is byproduct of +<a href="#shim">shimming</a>, +which mom always applies before the first line of running text after +the docheader, regardless of which +<a href="#vertical-whitespace-management">vertical whitespace management</a> +strategy is in effect. If you encounter the problem, pass +<kbd>DOCHEADER OFF <distance></kbd> +the additional final argument, <kbd>NO_SHIM</kbd>. +</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, 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 remove or alter +the space with +<a href="#space-before">CHAPTER_TITLE_SPACE_BEFORE</a>. +</p> +</div> + +<div class="macro-list-container"> +<h3 id="index-docheader-control" class="macro-list">Docheader control</h3> + +<p style="margin-top: -1.5em; margin-left: .5em; margin-right: .5em"> +With the docheader control macros, you can change the family, +colour, leading, and quad direction of the entire docheader. You can +also set the style parameters for each part individually. Style +parameters include family, font, size, colour, lead, space before, +caps, smallcaps, and underscoring. +</p> + +<ul class="macro-list" style="margin-top: -.5em"> + <li><a href="#change-whole-docheader">1. Changes to the whole docheader</a> + <ul style="list-style-type: disc"> + <li><a href="#change-start">Change the starting position of the docheader</a></li> + <li><a href="#docheader-family">Change the family of the whole docheader</a></li> + <li><a href="#docheader-color">Change the colour of the whole docheader</a></li> + <li><a href="#docheader-lead">Change the leading of the whole docheader</a></li> + <li><a href="#docheader-quad">Change the quad direction of the docheader</a></li> + </ul> + </li> + <li><a href="#part-by-part">2. Part by part changes</a> + <ul style="list-style-type: disc"> + <li><a href="#list-of-params">List of parameters and arguments</a></li> + <li><a href="#grouping">Grouping part/parameter changes</a> – very handy</li> + </ul> + </li> + <li><a href="#change-attribute">3. Changing or removing the attribution string (“by”)</a></li> +</ul> +</div> + +<h4 id="change-whole-docheader" class="docs" style="font-size: 100%">1. Changes to the whole docheader</h4> + +<h5 id="change-start" class="docs">Change the starting position of the docheader</h5> + +<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> + +<h5 id="docheader-quad" class="docs">Change the quad direction of the docheader</h5> + +<p> +By default, mom centres the docheader. If you’d prefer to +have your docheaders set flush left or right, or need to restore +the default centering, invoke <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> + +<h5 id="docheader-family" class="docs">Change the family of the entire docheader</h5> + +<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. +</p> + +<h5 id="docheader-color" class="docs">Change the colour of the entire docheader</h5> + +<p> +The default colour for docheaders is black, as you’d expect. +If you wish to change it, use +<kbd>.DOCHEADER_COLOR <colour></kbd>, where +<kbd> <colour></kbd> is a colour pre-initialized with +<a href="color.html#xcolor">XCOLOR</a> +or +<a href="color.html#newcolor">NEWCOLOR</a>. +</p> + +<h5 id="docheader-lead" class="docs">Change the leading of the entire docheader</h5> + +<p> +By default, mom uses the leading in effect for +<a href="definitions.html#running">running text</a> +for docheaders. If you want to increase or +decrease the overall docheader leading, use +<kbd>.DOCHEADER_LEAD +|-<amount></kbd>, where +<kbd><amount></kbd> is the number of +<a href="definitions.html#picaspoints">points</a> +by which to make the adjustment. +</p> + +<h4 id="part-by-part" class="docs" style="font-size: 100%">2. Part by part changes</h4> + +<p> +Whenever you want to change the style parameters for any part of +the docheader, simply join the name of the part to the parameter +you wish to change using an underscore, then supply any necessary +arguments. The subtitle double-underlined? No problem. +<br/> +<span class="pre-in-pp"> + .SUBTITLE_UNDERSCORE DOUBLE +</span> +Author in red? +<br/> +<span class="pre-in-pp"> + .AUTHOR_COLOR red +</span> +Title in smallcaps? +<span class="pre-in-pp"> + .TITLE_SMALLCAPS +</span> +</p> + +<div class="box-tip" style="margin-top: -1em;"> +<p class="tip"> +<span class="note">Note:</span> +Use <kbd>ATTRIBUTE</kbd> as the part name for the attribution string +(“by”) that precedes the author, and <kbd>DOCTYPE</kbd> +as the name for the string passed to <kbd>DOCTYPE NAMED "string"</kbd>. +</p> +</div> + +<h5 id="list-of-params" class="docs">List of parameters with arguments</h5> + +<dl> + <dt class="params">_FAMILY</dt> + <dd> + Takes the same argument as <a href="typesetting.html#family">FAMILY</a>. + </dd> + <dt class="params">_FONT</dt> + <dd> + Takes the same argument as <a href="typesetting.html#font">FT</a>. + </dd> + <dt class="params">_SIZE</dt> + <dd> + Takes a <kbd>+</kbd> or <kbd>-</kbd> value relative to the size of + <a href="definitions.html#running">running text</a>. + </dd> + <dt class="params">_COLOR</dt> + <dd> + Takes the same argument as <a href="color.html#color">COLOR</a>. + Colours should be pre-initialized with + <a href="color.html#xcolor">XCOLOR</a> + or + <a href="color.html#newcolor">NEWCOLOR</a>. + </dd> + <dt class="params">_LEAD</dt> + <dd> + Takes an absolute leading value, i.e. not relative to the + overall leading of the docheader. The leading applies to + multiple lines of type within the same docheader part, e.g. + several authors or a long title that must be split over two + lines. No + <a href="definitions.html#unitofmeasure">unit of measure</a> + is required; + <a href="definitions.html#picaspoints">points</a> + is assumed. + </dd> + <dt id="space-before" class="params">_SPACE</dt> + <dd> + Takes a numeric value with a + <a href="definitions.html#unitofmeasure">unit of measure</a> + appended to it. The value may be negative. This allows you + to adjust the whitespace before a docheader part, for example + if you want more whitespace between the title and the author. + <span style="display: block; margin-top: .5em"> + Note that <kbd>TITLE</kbd> does not have a <kbd>_SPACE</kbd> + parameter; use + <a href="#change-start">DOCHEADER_ADVANCE</a> + to move the title further down on the page. + </span> + </dd> + <dt class="params">_CAPS</dt> + <dd> + Capitalizes the entire docheader part. No argument is + required. + </dd> + <dt class="params">_NO_CAPS</dt> + <dd> + Only used if you need to reverse the sense of <kbd>_CAPS</kbd>, as + can sometimes happen when + <a href="rectoverso.html#collate">collating</a> + documents that have differing docheader style requirements. + </dd> + <dt class="params">_SMALLCAPS</dt> + <dd> + Set the entire docheader part in smallcaps. No argument is + required. + </dd> + <dt class="params">_NO_SMALLCAPS</dt> + <dd> + Only used if you need to reverse the sense of + <kbd>_SMALLCAPS</kbd>, as can sometimes happen when + <a href="rectoverso.html#collate">collating</a> + documents that have differing docheader style requirements. + </dd> + <dt class="params">_UNDERSCORE</dt> + <dd> + With no argument, underscores the docheader part. With a + single, possibly decimal numeric argument, sets the weight of + the underscore. A second numeric argument to which a + <a href="definitions.html#unitofmeasure">unit of measure</a> + is appended (most likely <kbd>p</kbd>) sets the distance + between the baseline and the underscore. + <span style="display: block; margin-top: .5em"> + If the argument <kbd>DOUBLE</kbd> is given, double underscores + the docheader part. With a single, possibly decimal numeric + argument afterwards, sets the weight of the underscore rules. + A third numeric argument to which a + <a href="definitions.html#unitofmeasure">unit of measure</a> + is appended (most likely <kbd>p</kbd>) sets the distance + between the baseline and the first underscore rule. A fourth + numeric argument to which a unit of measure is appended sets + the distance between the two underscore rules. + </span> + <span style="display: block; margin-top: .5em"> + You may give <kbd>_UNDERLINE</kbd> as the parameter instead of + <kbd>_UNDERSCORE</kbd> if you prefer. + </span> + </dd> + <dt class="params">NO_UNDERSCORE</dt> + <dd> + Only used if you need to reverse the sense of + <kbd>_UNDERSCORE</kbd>, as can sometimes happen when + <a href="rectoverso.html#collate">collating</a> + documents that have differing docheader style requirements. + </dd> +</dl> + +<h5 id="grouping" class="docs">Grouping part/parameter changes</h5> + +<p> +If you want to change several parameters for a particular docheader +part, you may group the changes together in a single macro by +joining the name of the part to <kbd>STYLE</kbd> with an underscore, +for example <kbd>TITLE_STYLE</kbd> or <kbd>AUTHOR_STYLE</kbd>. +The following demonstrates: +<span class="pre-in-pp"> + .CHAPTER_TITLE_STYLE \ + FAMILY T \ + SIZE +4 \ + UNDERSCORE 2 \ + SMALLCAPS +</span> +Notice the use of the backslash character, which is required after +the macro name and all parameters except the last. Grouping reduces +clutter and the finger fatigue caused by entering +<span class="pre-in-pp"> + .CHAPTER_TITLE_FAMILY T + .CHAPTER_TITLE_SIZE +4 + .CHAPTER_TITLE_UNDERSCORE 2 + .CHAPTER_TITLE_SMALLCAPS +</span> +</p> + +<h4 id="change-attribute" class="docs" style="font-size: 100%">3. Changing or removing 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="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 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" id="marking-col-start">Marking the first page column start position</h3> + +<p> +If you insert or remove space after the docheader, i.e. immediately after +<a href="#start">START</a> +in your input file, mom needs to know where your first column begins +in order to align subsequent columns on the first page. +</p> + +<div id="col-mark" class="box-macro-args"> +Macro: <b>COL_MARK</b> +</div> + +<p> +<kbd>COL_MARK</kbd> tells mom where the first column after the +docheader begins, in order for the top of subsequent columns on the +first page to be aligned. Note that if you do not manually add +or remove space after the docheader, there is no need to invoke +<kbd>COL_MARK</kbd>. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +If you do add or subtract space after the docheader, e.g. with +<a href="typesetting.html#ald">ALD</a> +or +<a href="typesetting.html#SP">SP</a>, +and your +<a href="definitions.html#unitofmeasure">unit of measure</a> +is something other than a multiple of “<kbd>v</kbd>”, be +sure to follow the spacing command with +<a href="docprocessing.html#shim">SHIM</a> +before entering <kbd>.COL_MARK</kbd> unless shimming has been +disabled with +<a href="#no-shim">NO_SHIM</a>. +If your document is being flex-spaced, do not use +<a href="docprocessing.html#flex">FLEX</a>. +Rather, disable flex-spacing temporarily with +<br/> +<span class="pre-in-pp"> + .NO_FLEX + .NO_SHIM off + .SHIM + .COL_MARK +</span> +and re-enable it afterwards with +<span class="pre-in-pp"> + .NO_SHIM + .NO_FLEX off +</span> +</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: 3.5%"> +<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 or FLEX macro to get mom back + on track when you’re ready to return to the + document’s default leading. + + <a id="autolead" style="margin-top: -1em">AUTOLEAD</a> •Invoked before START, sets the overall document + leading as a function of the overall document + point size (i.e. the point size used in paragraphs); + subsequently disabled after START, except for calls + to DOC_PT_SIZE + + •DOC_LEAD before DOC_PT_SIZE cancels the AUTOLEAD + set before START + + •Invoked after START, remains in effect for all + subsequent point size changes made with PT_SIZE, + but does not affect the leading of the document + element tags (e.g. HEADING, PP, QUOTE...), or calls + to DOC_PT_SIZE + + QUAD •Changes quad for the duration of the + current tag only. As soon as another document + element tag is entered, the quad reverts to + the current document default for the new + tag. + + N.B. — Line-for-line quadding macros + (LEFT, CENTER, RIGHT) are also temporary, + overridden by the QUAD value of any subsequent + document element tag. +</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 +conjunction 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/RESTORE_SPACE</h3> +</div> + +<div class="box-macro-args"> +Macro: <b>ADD_SPACE</b> <kbd class="macro-args"><amount of space></kbd> +<br/> +Macro: <b>RESTORE_SPACE</b> +</div> + +<p class="requires"> +• Requires a <a href="definitions.html#unitofmeasure">unit of measure</a> +</p> + +<p> +If your +<a href="#doctype">DOCTYPE</a> +is DEFAULT, CHAPTER, NAMED, or LETTER, ADD_SPACE takes as its +single argument the distance you want mom to advance from the normal +baseline position at the top of any page <i>after the first</i> (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> +or +<a href="docprocessing.html#flex">FLEX</a> +macro immediately after ADD_SPACE, which will add the space plus +whatever correction is required by the +<a href="docprocessing.html#vertical-whitespace-management">vertical whitespace management</a> +strategy in effect. +</p> + +<p> +If your +<a href="#doctype">DOCTYPE</a> +is SLIDES, ADD_SPACE may be used on any slide <i>including the +first</i> to introduce additional white space at the top. +</p> + +<h4 class="docs doc-param-macros" style="margin-top: .5em">RESTORE_SPACE</h4> + +<p style="margin-top: .5em"> +You may sometimes find that mom refuses to respect +<a href="typesetting.html#space">SP</a>, +<a href="typesetting.html#index-aldrld">ALD/RLD</a>, +<a href="docprocessing.html#shim">SHIM</a>, +or +<a href="docprocessing.html#flex">FLEX</a> +after the first element (line of text, floated material) output +at the top of a page. Should this happen, insert the macro +RESTORE_SPACE before issuing the spacing command. +</p> + +<!-- *** --> + +<h2 id="intro-doc-param" class="macro-group">Changing document-wide typesetting parameters after START</h2> + +<p> +In the normal course of things, you establish the basic type style +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 must +use the following macros if you wish to make global changes to the +basic type style parameters, for example changing the overall leading or +the justification style. +</p> + +<div class="box-important"> +<p class="tip"> +<span class="important">Important:</span> +Because these macros globally update the chosen parameter, they +should only be used immediately prior to +<a href="rectoverso.html#collate">COLLATE</a> +or, if an occasional effect is desired, +<a href="typesetting.html#newpage">NEWPAGE</a>. +<a href="#doc-pt-size">DOC_PT_SIZE</a>, +for example, updates the point size of every page element, including +headers, footers, page numbers, and so on, which is almost certainly +not what you want in the middle of a page. +</p> +</div> + +<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, including headers, footers, and page + numbers to the new value + </li> + <li>any document elements that use a left indent calculate + the indent from 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 headers, footers, and + page numbers to the new value; + </li> + <li>any document elements that use 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>); + </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> + <li>if + <a href="typesetting.html#autolead">AUTOLEAD</a> + was invoked before START; the value of AUTOLEAD will be used + to update the leading of all document element tags except + FOOTNOTE and EPIGRAPH + </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> + <li>if + <a href="typesetting.html#autolead">AUTOLEAD</a> + was invoked before START; the value of that AUTOLEAD will be + cancelled + </li> +</ul> + +<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> + +<h2 id="terminating" class="macro-group">Terminating a document</h2> + +<p> +You need do nothing special to terminate a document. When groff +finishes processing the last +<a href="definitions.html#inputline">input line</a> +of a file, the page is ejected, subject to whatever routines are +needed to complete it (e.g. printing footnotes or adding the page +number). +</p> + +<p> +It happens sometimes, however, that a last line of +<a href="definitions.html#running">running text</a>, +falling on or very near the bottom of the page, tricks groff into +breaking to a new page before terminating. The result is a blank +page at the end of the formatted document. +</p> + +<p> +The situation is rare, generally occurring only when some additional +macro is required after the input text, e.g. to exit a +<a href="docelement.html#list-intro">list</a> +or terminate a +<a href="docelement.html#quote">quote</a>. +To prevent it from ever happening, I recommend getting into the habit +of following the final input line of all your mom files with +<a href="typesetting.html#el"><kbd>.EL</kbd></a>. +Depending on the +<a href="definitions.html#filled">fill mode</a> +in effect, you may also have to append the “join line” +<a href="definitions.html#inlines">escape</a>, +<kbd>\c</kbd>, to the final line.</p> + +<p> +Thus, for normal text at the end of a paragraph, which is in fill +mode, +<br/> +<span class="pre-in-pp"> + and they all lived happily ever after. + .EL +</span> +or for ending a +<a href="docelement.html#list-intro">LIST</a> +(also in fill mode) +<span class="pre-in-pp"> + .ITEM + peaches, pears, plums + .EL + .LIST OFF +</span> +whereas, at the end of a +<a href="docelement.html#quote-intro">QUOTE</a> +(which is in nofill mode), +<span class="pre-in-pp"> + Shall be lifted\[em]nevermore!\c + .EL + .QUOTE OFF +</span> +Notice that the <kbd>.EL</kbd> comes after the last line of input +text, not any macros following. +</p> + +<div class="box-tip"> +<p class="tip"> +<span class="note">Note:</span> +<a href="inlines.html#b"><kbd><span class="nobr">\*[B]</span></kbd></a> +cannot be used as a replacement for <kbd>.EL</kbd> when terminating +a document. +</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: 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> |