contrib/mom/momdoc/docprocessing.html

   1 <?xml version="1.0" encoding="utf-8"?>
   2 <!--
   3 This file is part of groff, the GNU roff type-setting system.
   4
   5 Copyright (C) 2004-2014 Free Software Foundation, Inc.
   6 Written by Peter Schaffter (peter@schaffter.ca).
   7
   8 Permission is granted to copy, distribute and/or modify this document
   9 under the terms of the GNU Free Documentation License, Version 1.3 or
  10 any later version published by the Free Software Foundation; with the
  11 Invariant Sections being this comment section, with no Front-Cover
  12 Texts, and with no Back-Cover Texts.
  13
  14 A copy of the Free Documentation License is included as a file called
  15 FDL in the main directory of the groff source package.
  16 -->
  17
  18 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
  19 <html xmlns="http://www.w3.org/1999/xhtml">
  20
  21 <head>
  22   <meta http-equiv="content-type" content="text/html;charset=utf-8"/>
  23   <title>Mom -- Document Processing, Introduction and Setup</title>
  24   <link rel="stylesheet" type="text/css" href="stylesheet.css" />
  25 </head>
  26
  27 <body style="background-color: #f5faff;">
  28
  29 <!-- ==================================================================== -->
  30
  31 <div id="top" class="page">
  32
  33 <!-- Navigation links -->
  34 <table style="width: 100%;">
  35 <tr>
  36   <td><a href="toc.html">Back to Table of Contents</a></td>
  37   <td style="text-align: right;"><a href="docelement.html#top">Next: The document element tags</a></td>
  38 </tr>
  39 </table>
  40
  41 <h1 class="docs">Document processing with mom</h1>
  42
  43 <div style="text-align: center;">
  44 <ul class="no-enumerator" style="margin-left: -2.5em;">
  45   <li><a href="#defaults">Document defaults</a></li>
  46   <li><a href="#leading-note">Important note on leading/spacing and bottom margins</a></li>
  47   <li><a href="#shim">The SHIM macro</a></li>
  48 </ul>
  49 </div>
  50
  51 <div class="rule-medium"><hr/></div>
  52
  53 <h2 id="toc-doc-processing" class="docs" style="text-align: center;">Table of contents</h2>
  54
  55 <div id="docprocessing-mini-toc" style="font-size: 90%; line-height: 150%; margin-top: .5em;">
  56 <div class="mini-toc-col-1" style="margin-left: 0;">
  57 <h3 class="toc toc-docproc-header" style="margin-top: 1em;"><a class="header-link" href="#docprocessing-intro">Introduction</a></h3>
  58 <h3 class="toc toc-docproc-header" style="margin-top: .5em;"><a
  59 class="header-link" href="#setup">Preliminary document setup</a></h3>
  60 <ul class="toc-docproc" style="margin-top: .5em;">
  61   <li><a href="#docprocessing-tut"><b>Tutorial &ndash; Setting up a mom document</b></a></li>
  62   <li><a href="#reference-macros"><b>The reference macros (metadata)</b></a>
  63   <ul class="toc-docproc">
  64     <li><a href="#title">TITLE</a></li>
  65     <li><a href="#doc-title">DOCTITLE</a></li>
  66     <li><a href="#subtitle">SUBTITLE</a></li>
  67     <li><a href="#author">AUTHOR</a></li>
  68     <li><a href="#chapter">CHAPTER</a></li>
  69     <li><a href="#chapter-title">CHAPTER_TITLE</a></li>
  70     <li><a href="#draft">DRAFT</a></li>
  71     <li><a href="#revision">REVISION</a></li>
  72     <li><a href="#copyright">COPYRIGHT</a></li>
  73     <li><a href="#misc">MISC</a></li>
  74     <li><a href="#covertitle">COVERTITLE</a></li>
  75     <li><a href="#doc-covertitle">DOC_COVERTITLE</a></li>
  76     <li><a href="#pdftitle">PDF_TITLE</a></li>
  77   </ul></li>
  78   <li><a href="#docstyle-macros"><b>The docstyle macros (templates)</b></a>
  79   <ul class="toc-docproc">
  80     <li><a href="#doctype">DOCTYPE</a></li>
  81     <li><a href="#printstyle">PRINTSTYLE</a></li>
  82     <li><a href="#copystyle">COPYSTYLE</a></li>
  83   </ul></li>
  84 </ul>
  85 <h3 class="toc toc-docproc-header"><a class="header-link" href="#start-macro">Initiate document processing</a></h3>
  86 <ul class="toc-docproc" style="margin-top: .5em;">
  87   <li><a href="#start"><b>The START macro</b></a></li>
  88 </ul>
  89 <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>
  90 <ul class="toc-docproc" style="margin-top: .5em;">
  91   <li><a href="#type-before-start"><b>Behaviour of the typesetting macros before START</b></a>
  92   <ul class="toc-docproc">
  93     <li><a href="docprocessing.html#include">Including (sourcing) style sheets and files</a></li>
  94     <li><a href="#color">Initializing colours</a></li>
  95   </ul></li>
  96 </ul>
  97 </div>
  98 <div class="mini-toc-col-2" style="margin-top: -1em;">
  99 <br/>
 100 <ul class="toc-docproc" style="margin-top: .5em;">
 101   <li><a href="#doc-lead-adjust"><b>Adjust linespacing to fill pages</b></a>
 102   <ul class="toc-docproc">
 103     <li><a href="#doc-lead-adjust">DOC_LEAD_ADJUST</a></li>
 104     <li><a href="#shim">SHIM</a> &ndash; get document leading back on track
 105     <ul class="toc-docproc">
 106       <li><a href="#automatic-shimming">Automatic shimming (headings, etc)</a></li>
 107     </ul></li>
 108   </ul></li>
 109   <li><a href="#docheader"><b>Managing the document header</b></a>
 110   <ul class="toc-docproc">
 111     <li><a href="#docheader">DOCHEADER</a></li>
 112     <li><a href="#docheader-control">Docheader control</a>
 113     <ul class="toc-docproc">
 114       <li><a href="#docheader-desc">Docheader description</a></li>
 115       <li><a href="#index-docheader-control">Macro list</a></li>
 116     </ul></li>
 117   </ul></li>
 118   <li><a href="#columns-intro"><b>Setting documents in columns</b></a>
 119   <ul class="toc-docproc">
 120     <li><a href="#columns">COLUMNS</a></li>
 121     <li><a href="#marking-col-start">Marking the first page column start position</a>
 122     <ul class="toc-docproc">
 123       <li><a href="#col-mark">COL_MARK</a></li>
 124     </ul></li>
 125     <li><a href="#breaking-columns">Breaking columns manually</a>
 126     <ul class="toc-docproc">
 127       <li><a href="#col-next">COL_NEXT</a> and <a href="#col-break">COL_BREAK</a></li>
 128     </ul></li>
 129   </ul></li>
 130 </ul>
 131 <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>
 132 <ul class="toc-docproc" style="margin-top: .5em;">
 133   <li><a href="#behaviour"><b>Behaviour of the typesetting macros during document processing</b></a></li>
 134   <li><a href="docprocessing.html#intro-doc-param"><b>Changing document-wide style parameters after START</b></a>
 135   <ul class="toc-docproc">
 136     <li><a href="docprocessing.html#index-doc-param">Post-START global style change macros</a>
 137     <ul class="toc-docproc">
 138      <li><a href="#doc-left-margin">DOC_LEFT_MARGIN</a></li>
 139      <li><a href="#doc-right-margin">DOC_RIGHT_MARGIN</a></li>
 140      <li><a href="#doc-line-length">DOC_LINE_LENGTH</a></li>
 141      <li><a href="#doc-family">DOC_FAMILY</a></li>
 142      <li><a href="#doc-pt-size">DOC_PT_SIZE</a></li>
 143      <li><a href="#doc-lead">DOC_LEAD</a></li>
 144      <li><a href="#doc-lead-adjust">DOC_LEAD_ADJUST</a></li>
 145      <li><a href="#doc-quad">DOC_QUAD</a></li>
 146     </ul></li>
 147   </ul></li>
 148 </ul>
 149 <h3 class="toc toc-docproc-header"><a class="header-link" href="#terminating">Terminating a document</a></h3>
 150 </div>
 151 </div>
 152
 153 <div class="rule-short"><br/><hr/></div>
 154
 155 <!-- ==================================================================== -->
 156
 157 <h2 id="docprocessing-intro" class="docs" style="margin-top: 1em">Introduction to document processing</h2>
 158
 159 <p>
 160 Document processing with mom uses markup tags to identify document elements
 161 such as headings, paragraphs, blockquotes, and so on.  The tags are, of course,
 162 macros, but with sensible, readable names that make them easy
 163 to grasp and easy to remember.  (And don&#8217;t forget: if you
 164 don&#8217;t like the &#8220;official&#8221; name of a tag &mdash;
 165 too long, cumbersome to type in, not &#8220;intuitive&#8221; enough
 166 &mdash; you can change it with the
 167 <a href="goodies.html#alias">ALIAS</a>
 168 macro.)
 169 </p>
 170
 171 <p>
 172 In addition to the tags themselves, mom has an extensive array of
 173 macros that control how they look and behave.
 174 </p>
 175
 176 <p>
 177 Setting up a mom doc is a simple, four-part procedure.  You
 178 begin by entering metadata about the document itself (title,
 179 subtitle, author, etc.).  Next, you tell mom what kind of document
 180 you&#8217;re creating (eg chapter, letter, abstract, etc...) and
 181 what kind of output you want (typeset, typewritten, draft-style,
 182 etc) &mdash; essentially, templates.  Thirdly, you make as many
 183 or as few changes to the templates as you wish; in other words,
 184 create a style sheet.  Lastly, you invoke the
 185 <kbd><a href="#start">START</a></kbd>
 186 macro.  Voilà!  You&#8217;re ready to write.
 187 </p>
 188
 189 <!-- ==================================================================== -->
 190
 191 <h2 id="defaults" class="docs">Document defaults</h2>
 192
 193 <p>
 194 As is to be expected, mom has defaults for everything.  If you want
 195 to know a particular default, read about it in the description of
 196 the pertinent tag.
 197 </p>
 198
 199 <p>
 200 I fear the following may not be adequately covered in the
 201 documentation, so just in case:
 202 </p>
 203 <ul style="margin-top: -.5em; margin-bottom: .5em;">
 204   <li>the paper size is 8.5x11 inches</li>
 205   <li>the left and right margins are 1-inch</li>
 206   <li>the top and bottom margins for document text are plus/minus
 207       visually 1-inch
 208   </li>
 209   <li>pages are numbered; the number appears centred, at the
 210       bottom, surrounded by hyphens ( eg -6- )
 211   </li>
 212   <li>the first page of a document begins with a
 213       <a href="definitions.html#docheader">document header</a>
 214   </li>
 215   <li>subsequent pages have
 216       <a href="definitions.html#header">page headers</a>
 217       with a rule underneath
 218   </li>
 219 </ul>
 220
 221 <!-- ==================================================================== -->
 222
 223 <h2 id="leading-note" class="docs">Important note on leading/spacing and bottom margins</h2>
 224
 225 <p>
 226 Mom takes evenly-aligned bottom margins in
 227 <a href="definitions.html#running">running text</a>
 228 very seriously.  Only under a very few (exceptional) circumstances
 229 will she allow a bottom margin to &#8220;hang&#8221; (ie to fall
 230 short).
 231 </p>
 232
 233 <p>
 234 In order to ensure even bottom margins, mom uses the
 235 &#8220;base&#8221; document
 236 <a href="definitions.html#leading">leading</a>
 237 in effect <i>at the start of running text on each page</i> (ie
 238 the leading used in paragraphs) to calculate the spacing of every
 239 document element.  Prior to invoking
 240 <a href="#start">START</a>,
 241 this is set with the
 242 <a href="typesetting.html#macros-typesetting">typesetting macro</a>
 243 <a href="typesetting.html#leading">LS</a>,
 244 afterwards with the document
 245 <a href="definitions.html#controlmacro">control macro</a>
 246 <a href="#doc-lead">DOC_LEAD</a>.
 247 </p>
 248
 249 <p>
 250 Because mom relies so heavily on the base document
 251 leading, any change to the leading or spacing on a page will almost
 252 certainly have undesirable consequences on that page&#8217;s bottom margin
 253 unless the change is fully compensated for elsewhere on the page.
 254 </p>
 255
 256 <p>
 257 In other words, if you add a few points of space somewhere on a page,
 258 you must subtract the same number of points somewhere else on that
 259 same page, and vice versa.
 260 </p>
 261
 262 <p>
 263 If it&#8217;s a question of adding or subtracting full
 264 line spaces between or within document elements, you
 265 can do so by using the &#8220;<kbd>v</kbd>&#8221; <a
 266 href="definitions.html#unitofmeasure">unit of measure</a> with
 267 whatever spacing macro you choose &mdash;
 268 <a href="typesetting.html#ald">ALD</a>,
 269 <a href="typesetting.html#rld">RLD</a>,
 270 <a href="typesetting.html#space">SPACE</a>
 271 &mdash; and mom won&#8217;t object.  &#8220;<kbd>v</kbd>&#8221; means
 272 &#8220;the current leading&#8221;, so she isn&#8217;t confused by it.  And
 273 since &#8220;<kbd>v</kbd>&#8221; accepts decimal fractions, you can add/subtract
 274 half linespaces and quarter linespaces with &#8220;<kbd>v</kbd>&#8221; as well,
 275 <i>provided you compensate for the fractional linespace somewhere
 276 else on the page</i>.
 277 </p>
 278
 279 <p>
 280 If all this seems like too much work, mom provides a special macro
 281 to get you out of trouble if you&#8217;ve played around with leading
 282 and/or spacing.  The macro is called SHIM (like those little pieces
 283 of wood carpenters use to get their work even, level and snug), and
 284 it&#8217;s described below.
 285 </p>
 286
 287 <!-- -SHIM- -->
 288
 289 <div class="macro-id-overline">
 290 <h3 id="shim" class="macro-id">SHIM</h3>
 291 </div>
 292
 293 <div class="box-macro-args">
 294 Macro: <b>SHIM</b>
 295 </div>
 296
 297 <p>
 298 SHIM doesn&#8217;t take any argument.  Use it whenever you&#8217;ve played
 299 around with the
 300 <a href="definitions.html#leading">leading</a>
 301 or spacing on a page and you need to get mom&#8217;s document
 302 leading back on track.
 303 </p>
 304
 305 <p>
 306 For example, say you want to insert an image into a document with
 307 <a href="images.html#pspic">PSPIC</a>.
 308 Images and graphics aren&#8217;t usually conveniently sized in
 309 multiples of the document leading, which means that when you insert
 310 the picture, you disrupt mom&#8217;s ordered placement of baselines
 311 on the page.  This will certainly result in a bottom margin that
 312 doesn&#8217;t match the bottom margins of your document&#8217;s
 313 other pages.
 314 </p>
 315
 316 <p>
 317 The solution is to insert SHIM after the image, like this:
 318 <br/>
 319 <span class="pre-in-pp">
 320   &lt;text&gt;
 321   .PSPIC &lt;args&gt;
 322   .SHIM
 323   &lt;text&gt;
 324 </span>
 325 </p>
 326
 327 <p>
 328 SHIM instructs mom to insert as much or a little space after the
 329 picture as is needed to ensure that the baseline of the next
 330 <a href="definitions.html#outputline">output line</a>
 331 falls where mom would have put it had you not disrupted the normal
 332 flow of output lines with the picture.
 333 </p>
 334
 335 <p>
 336 And say, on previewing the above example, you find the image
 337 doesn&#8217;t centre nicely between the lines of text, you can
 338 adjust the image position by using
 339 <a href="typesetting.html#ald">ALD</a>
 340 or
 341 <a href="typesetting.html#rld">RLD</a>
 342 before PSPIC.  To demonstrate,
 343 <br/>
 344 <span class="pre-in-pp">
 345   &lt;text&gt;
 346   .RLD 3p
 347   .PSPIC &lt;args&gt;
 348   .SHIM
 349   &lt;text&gt;
 350 </span>
 351 which raises the image slightly and thereby balances the whitespace around it.
 352 </p>
 353
 354 <p>
 355 You may sometimes find the amount of space generated by
 356 <kbd>SHIM</kbd> looks too big, whether inserted manually into a
 357 document or as a result of automatic shimming (see immediately
 358 below).  The situation occurs when the amount of shimming applied
 359 comes close to the leading currently in effect, making it seem as if
 360 there&#8217;s one linespace too much whitespace.  The solution is
 361 simply to add <kbd>.SPACE&nbsp;-1v</kbd> or <kbd>.RLD&nbsp;1v</kbd>
 362 to the document immediately after <kbd>.SHIM</kbd>.  (Both
 363 <kbd>.SPACE&nbsp;-1v</kbd> and <kbd>.RLD&nbsp;1v</kbd> back up
 364 by one linespace.)
 365 </p>
 366 <h4 id="automatic-shimming" class="docs">Automatic shimming of headings, quotes, blockquotes, PDF images, and floats</h4>
 367
 368 <p style="margin-bottom: -1em">
 369 By default, mom automatically applies shimming
 370 </p>
 371 <ul>
 372   <li><i>before</i> headings</li>
 373   <li><i>around</i> quotes and blockquotes</li>
 374   <li><i>after</i> PDF images, floats, and tables</li>
 375 </ul>
 376
 377 <p>
 378 In documents where paragraphs are not spaced, automatic shimming is
 379 almost always desirable.  In documents where paragraphs are spaced
 380 by an amount less than the document leading, or which have numerous
 381 graphics, headings, and quotes, you may want to disable shimming,
 382 either globally or on a tag-by-tag basis.
 383 </p>
 384
 385 <p id="disable-shim">
 386 <span style="font-weight: bold; font-style: italic; font-size: 95%">To disable
 387 automatic shimming</span>, invoke the macro, <kbd>.NO_SHIM</kbd>,
 388 either in the style sheet section of your document (ie after
 389 <a href="#printstyle">PRINTSTYLE</a>
 390 and before
 391 <a href="#start">START</a>),
 392 or just before
 393 <a href="docelement.html#heading">HEADING</a>,
 394 <a href="docelement.html#quote">QUOTE</a>,
 395 <a href="docelement.html#blockquote">BLOCKQUOTE</a>,
 396 <a href="images.html#pdf-image">PDF_IMAGE</a>
 397 <a href="images.html#float">FLOAT</a>.
 398 or
 399 <a href="images.html#ts">TS</a>.
 400 </p>
 401
 402 <div class="box-tip">
 403 <p class="tip">
 404 <span class="note">Note:</span>
 405 <kbd>.NO_SHIM</kbd> also disables the SHIM macro itself.
 406 </p>
 407 </div>
 408
 409 <p>To re-enable automatic shimming and the SHIM macro itself, use
 410 <kbd>.NO_SHIM OFF</kbd> (or <kbd>QUIT, END, X</kbd>, etc).
 411 </p>
 412
 413 <div class="rule-short"><hr/></div>
 414
 415 <!-- ==================================================================== -->
 416
 417 <h2 id="setup" class="docs" style="margin-bottom: .5em;">Preliminary document setup</h2>
 418
 419 <div class="examples-container" style="margin-bottom: 1.5em;">
 420 <h3 id="docprocessing-tut" class="docs">Tutorial &ndash; Setting up a mom document</h3>
 421
 422 <p style="margin-top: 1em;">
 423 There are four parts to setting up a mom doc (three, actually,
 424 with one optional).  Before we proceed, though, be reassured that
 425 something as simple as
 426 <br/>
 427 <span class="pre-in-pp">
 428   .TITLE     "By the Shores of Lake Attica"
 429   .AUTHOR    "Rosemary Winspeare"
 430   .PRINTSTYLE TYPESET
 431   .START
 432 </span>
 433 produces a beautifully typeset 8.5x11 document, with a
 434 <a href="definitions.html#docheader">docheader</a>
 435 at the top of page 1,
 436 <a href="definitions.html#header">page headers</a>
 437 with the title and author on subsequent pages, and page numbers at
 438 the bottom of each page.  In the course of the document, headings,
 439 citations, quotes, epigraphs, and so on, all come out looking neat,
 440 trim, and professional.
 441 </p>
 442
 443 <p>
 444 For the purposes of this tutorial, we&#8217;re going to set up
 445 a short story&mdash;<i>My Pulitzer Winner</i>&mdash;by Joe Blow.
 446 Thankfully, we don&#8217;t have to look at story itself, just the
 447 setup.  Joe wants the document
 448 </p>
 449 <ul style="margin-top: -.5em; margin-bottom: -.5em;">
 450   <li>to be draft 7, revision 39;</li>
 451   <li>to use the DEFAULT template;</li>
 452   <li>to print as draft-style output (instead of final-copy output);</li>
 453   <li>to be typeset, in Helvetica, 12 on 14,
 454       <a href="definitions.html#rag">rag-right</a>;
 455   </li>
 456   <li>to have <a href="definitions.html#footer">footers</a>
 457       instead of
 458       <a href="definitions.html#header">headers</a>;
 459   </li>
 460   <li>to use a single asterisk for
 461       <a href="definitions.html#linebreak">author linebreaks</a>.
 462   </li>
 463 </ul>
 464
 465 <p>
 466 Joe Blow has no taste in typography.  His draft won&#8217;t look
 467 pretty, but this is, after all, a tutorial; we&#8217;re after
 468 examples, not beauty.
 469 </p>
 470
 471 <h4 class="docs" style="margin-top: -.5em;">Step 1</h4>
 472
 473 <p style="margin-bottom: -.5em;">
 474 The first step in setting up any document is giving mom some
 475 reference information (metadata).  The reference macros are:
 476 </p>
 477 <div style="width: 50%; float: left;">
 478 <ul>
 479   <li>TITLE</li>
 480   <li>SUBTITLE</li>
 481   <li>AUTHOR</li>
 482   <li>CHAPTER &ndash; chapter number</li>
 483   <li>CHAPTER_TITLE &ndash; chapter name</li>
 484   <li>DRAFT &ndash; the draft number</li>
 485   <li>REVISION &ndash; the revision number</li>
 486 </ul>
 487 </div>
 488 <div>
 489 <ul>
 490   <li>COPYRIGHT &ndash; only used on cover pages</li>
 491   <li>MISC &ndash; only used on cover pages</li>
 492   <li>DOCTITLE</li>
 493   <li>COVERTITLE</li>
 494   <li>DOC_COVERTITLE</li>
 495   <li>PDF_TITLE</li>
 496 </ul>
 497 </div>
 498
 499 <p style="margin-top: -.5em; clear: both;">
 500 You can use as many or as few as you wish, although at a minimum,
 501 you&#8217;ll probably fill in TITLE (unless the document&#8217;s a
 502 letter) and AUTHOR.  Order doesn&#8217;t matter.  You can separate
 503 the
 504 <a href="definitions.html#arguments">arguments</a>
 505 from the macros by any number of spaces.  The following are what
 506 you&#8217;d need to start Joe Blow&#8217;s story.
 507 <br/>
 508 <span class="pre-in-pp">
 509   .TITLE    "My Pulitzer Winner"
 510   .AUTHOR   "Joe Blow"
 511   .DRAFT     7
 512   .REVISION  39
 513 </span>
 514 </p>
 515
 516 <h4 class="docs" style="margin-top: -1.5em;">Step 2</h4>
 517
 518 <p>
 519 Once you&#8217;ve given mom the reference information she needs, you
 520 tell her how you want your document formatted.  What kind of
 521 document is it?  Should it be typeset or typewritten?  Is this a
 522 final copy (for the world to see) or just a draft?  Mom calls
 523 the macros that answer these questions &#8220;the docstyle
 524 macros.&#8221;, and they're essentially templates.
 525 </p>
 526 <ul style="margin-top: -.5em; margin-bottom: -.5em;">
 527   <li>PRINTSTYLE&mdash;typeset or typewritten</li>
 528   <li>DOCTYPE&mdash;the type of document (default, chapter, user-defined, letter)</li>
 529   <li>COPYSTYLE &mdash;draft or final copy</li>
 530 </ul>
 531
 532 <p>
 533 Mom has defaults for DOCTYPE and COPYSTYLE; if they&#8217;re what
 534 you want, you don&#8217;t need to include them.  However,
 535 PRINTSTYLE has no default and must be present in every formatted
 536 document.  If you omit it, mom won&#8217;t process the document
 537 AND she&#8217;ll complain (both to stderr and as a single printed
 538 sheet with a warning).  Moms&mdash;they can be so annoying
 539 sometimes. &lt;sigh&gt;
 540 </p>
 541
 542 <p>
 543 Adding to what we already have, the next bit of setup for Joe
 544 Blow&#8217;s story looks like this:
 545 <br/>
 546 <span class="pre-in-pp">
 547     .TITLE    "My Pulitzer Winner"
 548     .AUTHOR   "Joe Blow"
 549     .DRAFT     7
 550     .REVISION  39
 551     \#
 552     .DOCTYPE     DEFAULT \"Superfluous; mom uses DOCTYPE DEFAULT by default
 553     .PRINTSTYLE  TYPESET
 554     .COPYSTYLE   DRAFT
 555 </span>
 556 Notice the use of the
 557 <a href="definitions.html#commentlines">comment line</a>
 558 ( <kbd>\#</kbd> ), a handy way to keep groups of macros visually
 559 separated for easy reading in a text editor.
 560 </p>
 561
 562 <h4 class="docs" style="margin-top: -.5em; margin-bottom: -.5em;">Step 3</h4>
 563
 564 <p>
 565 This step&mdash;completely optional&mdash;is where you, the user,
 566 take charge.  Mom has reasonable defaults for every document element
 567 and tag, but who&#8217;s ever satisfied with defaults?  Use any of
 568 the
 569 <a href="typesetting.html#macros-typesetting">typesetting macros</a>
 570 here to change mom&#8217;s document defaults (paper size, margins,
 571 family, point size, line space, rag, etc), or use any of the
 572 document processing
 573 <a href="definitions.html#controlmacro">control macros</a>.
 574 This is the style-sheet section of a document, and
 575 must come after the
 576 <a href="#printstyle">PRINTSTYLE</a>
 577 directive.  Failure to observe this condition will result in
 578 PRINTSTYLE overriding your changes.
 579 </p>
 580
 581 <p>
 582 Joe Blow wants his story printed in Helvetica, 12 on 14, rag right,
 583 with
 584 <a href="definitions.html#footer">page footers</a>
 585 instead of
 586 <a href="definitions.html#header">page headers</a>
 587 and a single asterisk for the
 588 <a href="definitions.html#linebreak">linebreak</a>
 589 character.  None of these requirements conforms to mom&#8217;s
 590 defaults for the chosen PRINTSTYLE (TYPESET), so we change them
 591 here.  The setup for Joe Blow&#8217;s story now looks like this:
 592 <br/>
 593 <span class="pre-in-pp">
 594   .TITLE    "My Pulitzer Winner"
 595   .AUTHOR   "Joe Blow"
 596   .DRAFT     7
 597   .REVISION  39
 598   \#
 599   .DOCTYPE     DEFAULT
 600   .PRINTSTYLE  TYPESET
 601   .COPYSTYLE   DRAFT
 602   \#
 603   .FAMILY  H
 604   .PT_SIZE 12
 605   .LS      14
 606   .QUAD    LEFT    \"ie rag right
 607   .FOOTERS
 608   .LINEBREAK_CHAR *
 609 </span>
 610 </p>
 611
 612 <h4 class="docs" style="margin-top: -1.5em; margin-bottom: -.5em;">Step 4</h4>
 613
 614 <p>
 615 The final step in setting up a document is telling mom to start
 616 document processing.  It&#8217;s a no-brainer, just the single
 617 macro, START.  Other than PRINTSTYLE, it&#8217;s the only macro
 618 required for document processing.
 619 </p>
 620
 621 <p>
 622 Here&#8217;s the complete setup for <i>My Pulitzer Winner</i>:
 623 <br/>
 624 <span class="pre-in-pp">
 625   .TITLE    "My Pulitzer Winner"
 626   .AUTHOR   "Joe Blow"
 627   .DRAFT     7
 628   .REVISION  39
 629   \#
 630   .DOCTYPE     DEFAULT
 631   .PRINTSTYLE  TYPESET
 632   .COPYSTYLE   DRAFT
 633   \#
 634   .FAMILY   H
 635   .PT_SIZE  12
 636   .LS       14
 637   .QUAD     LEFT    \"ie rag right
 638   .FOOTERS
 639   .LINEBREAK_CHAR *
 640   \#
 641   .START
 642 </span>
 643 As pointed out earlier, Joe Blow is no typographer.  Given that all he
 644 needs is a printed draft of his work, a simpler setup would have been:
 645 <br/>
 646 <span class="pre-in-pp">
 647   .TITLE    "My Pulitzer Winner"
 648   .AUTHOR   "Joe Blow"
 649   .DRAFT     7
 650   .REVISION  39
 651   \#
 652   .PRINTSTYLE  TYPEWRITE
 653   .COPYSTYLE   DRAFT
 654   \#
 655   .START
 656 </span>
 657 <kbd>.PRINTSTYLE&nbsp;TYPEWRITE</kbd>, above, means that Joe&#8217;s
 658 work will come out &#8220;typewritten, double-spaced&#8221;,
 659 making the blue-pencilling he (or someone else) is sure to do much
 660 easier (which is why many publishers and agents still insist on
 661 typewritten, double-spaced copy).
 662 </p>
 663
 664 <p>
 665 When J. Blow stops re-writing and decides to print off a final,
 666 typeset copy of his work for the world to see, he need only make two
 667 changes to the (simplified) setup:
 668 <br/>
 669 <span class="pre-in-pp">
 670   .TITLE    "My Pulitzer Winner"
 671   .AUTHOR   "Joe Blow"
 672   .DRAFT     7
 673   .REVISION  39
 674   \#
 675   .PRINTSTYLE  TYPESET  \"first change
 676   .COPYSTYLE   FINAL    \"second change
 677   \#
 678   .START
 679 </span>
 680 In the above, <kbd>.DRAFT&nbsp;7,&nbsp;.REVISION 39,</kbd> and
 681 <kbd>.COPYSTYLE FINAL</kbd> are actually superfluous.  The draft
 682 and revision numbers aren&#8217;t used when COPYSTYLE is FINAL,
 683 and <b>COPYSTYLE FINAL</b> is mom&#8217;s default unless you tell
 684 her otherwise.
 685 </p>
 686
 687 <p>
 688 But... to judge from the number of drafts already,
 689 J. Blow may very well decide his &#8220;final&#8221; version still
 690 isn&#8217;t up to snuff.  Hence, he might as well leave in the
 691 superfluous macros.  That way, when draft 7, rev. 62 becomes draft
 692 8, rev. 1, he&#8217;ll be ready to tackle his Pulitzer winner again.
 693 </p>
 694 </div>
 695
 696 <div class="rule-short"><hr/></div>
 697
 698 <!-- ======================================================================== -->
 699
 700 <h2 id="reference-macros" class="macro-group">The reference macros (metadata)</h2>
 701
 702 <p>
 703 The reference macros give mom the metadata she needs to generate
 704 <a href="definitions.html#docheader">docheaders</a>,
 705 <a href="definitions.html#header">page headers</a>,
 706 and
 707 <a href="cover.html#cover-top">covers</a>.
 708 They must go at the top of any file that uses mom&#8217;s document
 709 processing macros.
 710 </p>
 711
 712 <div class="macro-list-container">
 713 <h3 id="index-reference" class="macro-list">Reference macros</h3>
 714
 715 <ul class="macro-list">
 716   <li><a href="#title">TITLE</a> &ndash; title of a story, article, etc</li>
 717   <li><a href="#doc-title">DOCTITLE</a> &ndash; title of a book, or any collated document</li>
 718   <li><a href="#subtitle">SUBTITLE</a></li>
 719   <li><a href="#author">AUTHOR</a></li>
 720   <li><a href="#chapter">CHAPTER</a> &ndash; the chapter number
 721   <ul>
 722     <li class="sublist"><a href="#chapter-string">CHAPTER_STRING</a> &ndash; &#8220;Chapter&#8221;, &#8220;CHAPTER&#8221;, &#8220;Chapître&#8221;, etc</li>
 723   </ul></li>
 724   <li><a href="#chapter-title">CHAPTER_TITLE</a></li>
 725   <li><a href="#draft">DRAFT</a>
 726   <ul>
 727     <li class="sublist"><a href="#draft-string">DRAFT_STRING</a> &ndash; &#8220;Draft&#8221;, &#8220;DRAFT&#8221;, &#8220;Jet&#8221;, etc</li>
 728   </ul></li>
 729   <li><a href="#revision">REVISION</a>
 730   <ul>
 731     <li class="sublist"><a href="#revision-string">REVISION_STRING</a> &ndash; &#8220;Revision&#8221;, &#8220;Rev.&#8221;, &#8220;Révision&#8221;, etc</li>
 732   </ul></li>
 733   <li><a href="#copyright">COPYRIGHT</a></li>
 734   <li><a href="#misc">MISC</a></li>
 735   <li><a href="#covertitle">COVERTITLE</a> &ndash; frontispiece, title page, etc</li>
 736   <li><a href="#doc-covertitle">DOC_COVERTITLE</a> &ndash; book cover, collated document cover, etc</li>
 737   <li><a href="#pdftitle">PDF_TITLE</a> &ndash; window title for PDF viewers</li>
 738 </ul>
 739 </div>
 740
 741 <!-- -TITLE- -->
 742
 743 <div class="macro-id-overline">
 744 <h3 id="title" class="macro-id">TITLE</h3>
 745 </div>
 746
 747 <div class="box-macro-args">
 748 Macro: <b>TITLE</b> <kbd>&quot;&lt;title string&gt;&quot; [&quot;&lt;2nd line&gt;&quot; [&quot;&lt;3rd line&gt;&quot; ... ] ]</kbd>
 749 </div>
 750 <p class="requires">
 751 &bull;&nbsp;Arguments must be enclosed in double-quotes
 752 </p>
 753
 754 <p>
 755 The title string can be caps or caps/lower-case; it&#8217;s up to you.  In
 756 <a href="#printstyle">PRINTSTYLE TYPESET</a>,
 757 the title will appear in the
 758 <a href="definitions.html#docheader">docheader</a>
 759 exactly as you typed it.  However, mom converts the title to all
 760 caps in
 761 <a href="definitions.html#header">page headers</a>
 762 unless you turn that feature off (see
 763 <a href="headfootpage.html#_caps">HEADER_&lt;POSITION&gt;_CAPS</a>).
 764 In
 765 <a href="#printstyle">PRINTSTYLE TYPEWRITE</a>,
 766 the title always gets converted to caps.
 767 </p>
 768
 769 <p>
 770 TITLE accepts multiple arguments, each surrounded by double-quotes.
 771 Each argument is printed on a separate line, permitting you to
 772 create multi-line titles in your docheaders.
 773 </p>
 774
 775 <div class="box-tip">
 776 <p class="tip">
 777 <span class="note">Note:</span>
 778 If your <kbd><a href="#doctype">DOCTYPE</a></kbd> is CHAPTER, TITLE
 779 should be the title of the opus, not &#8220;CHAPTER whatever&#8221;.
 780 </p>
 781 </div>
 782
 783 <!-- -DOCTITLE- -->
 784
 785 <div class="macro-id-overline">
 786 <h3 id="doc-title" class="macro-id">DOCUMENT TITLE</h3>
 787 </div>
 788
 789 <div class="box-macro-args">
 790 Macro: <b>DOCTITLE</b> <kbd class="macro-args">&quot;&lt;overall document title&gt;&quot; [&quot;&lt;2nd line&gt;&quot; [&quot;&lt;3rd line&gt;&quot; ... ] ]</kbd>
 791 </div>
 792 <p class="requires">
 793 &bull;&nbsp;Arguments must be enclosed in double-quotes
 794 </p>
 795
 796 <div class="box-tip">
 797 <p class="tip">
 798 <span class="note">Note:</span>
 799 This macro should be used only if your <a
 800 href="#doctype">DOCTYPE</a> is <kbd>DEFAULT</kbd> (which is
 801 mom&#8217;s default).  If your DOCTYPE is CHAPTER, use
 802 <a href="#title">TITLE</a>
 803 to set the overall document title for cover pages, document cover
 804 pages, and page headers or footers.
 805 </p>
 806 </div>
 807
 808 <p style="margin-top: -.5em;">
 809 When you&#8217;re creating a single document, say, an essay or a
 810 short story, you have no need of this macro.
 811 <a href="#title">TITLE</a>
 812 takes care of all your title needs.
 813 </p>
 814
 815 <p>
 816 However if you&#8217;re
 817 <a href="rectoverso.html#collate">collating</a>
 818 a bunch of documents together, say, to print out a report containing
 819 many articles with different titles, or a book of short stories with
 820 different authors, you need DOCTITLE.
 821 </p>
 822
 823 <p>
 824 DOCTITLE tells mom the title of the complete document (as opposed to
 825 the title of each article or entitled section), and appears
 826 </p>
 827
 828 <ol style="list-style-type: lower-alpha">
 829   <li>as the window title in PDF viewers (eg Okular or Evince)</li>
 830   <li>in the initial rightmost position of page headers in the document</li>
 831 </ol>
 832
 833 <p>
 834 Moreover, DOCTITLE does not appear in the
 835 <a href="definitions.html#pdfoutline">PDF outline </a>,
 836 as its presence in window title would make it redundant.
 837 </p>
 838
 839 <p>
 840 The doctitle string can be caps or caps/lower-case; it&#8217;s up to
 841 you.  In
 842 <a href="#printstyle">PRINTSTYLE TYPESET</a>,
 843 by default, the doctitle in
 844 <a href="definitions.html#header">page headers</a>
 845 is all in caps, unless you turn that feature off (see
 846 <a href="headfootpage.html#_caps">HEADER_&lt;POSITION&gt;_CAPS</a>).
 847 In
 848 <a href="#printstyle">PRINTSTYLE TYPEWRITE</a>,
 849 the doctitle always gets converted to caps.
 850 </p>
 851
 852 <p>
 853 DOCTITLE accepts multiple arguments, each surrounded
 854 by double-quotes.  Each argument is printed on a separate line,
 855 permitting you to create multi-line document titles for use on
 856 <a href="cover.html#cover">Covers</a>
 857 and/or
 858 <a href="cover.html#doc-cover">Doc covers</a>.
 859 </p>
 860
 861 <div class="box-tip">
 862 <p class="tip">
 863 <span class="note">Note:</span>
 864 If your
 865 <a href="#doctype">DOCTYPE</a>
 866 is CHAPTER, you don&#8217;t need DOCTITLE.  TITLE takes care of
 867 everything.
 868 </p>
 869 </div>
 870
 871 <!-- -SUBTITLE- -->
 872
 873 <div class="macro-id-overline">
 874 <h3 id="subtitle" class="macro-id">SUBTITLE</h3>
 875 </div>
 876
 877 <div class="box-macro-args">
 878 Macro: <b>SUBTITLE</b> <kbd class="macro-args">[COVER | DOC_COVER] &quot;&lt;subtitle&gt;&quot; [&quot;&lt;2nd line&gt;&quot; [&quot;&lt;3rd line&gt;&quot; ... ] ]</kbd>
 879 </div>
 880 <p class="requires">
 881 &bull;&nbsp;String arguments must be enclosed in double-quotes
 882 </p>
 883
 884 <p>
 885 The subtitle string can be caps or caps/lower-case.  I recommend
 886 caps/lower case.
 887 </p>
 888
 889 <p>
 890 SUBTITLE accepts multiple arguments, each surrounded
 891 by double-quotes.  Each argument is printed on a separate line,
 892 permitting you to create multi-line subtitles.
 893 </p>
 894
 895 <p>
 896 If the optional argument, <kbd>COVER</kbd> or <kbd>DOC_COVER</kbd>,
 897 is given to SUBTITLE, the remaining string
 898 arguments represent the subtitle that will appear on cover or
 899 document cover pages (see the
 900 <a href="cover.html#cover-intro">Introduction to cover pages</a>
 901 for a description of the difference between &#8220;document
 902 covers&#8221; and &#8220;covers&#8221;).  Thus, it is possible to have
 903 differing subtitles appear on the document cover, the cover
 904 (&#8220;title&#8221;) page, and in the document header.  An extreme
 905 example would be:
 906 <br/>
 907 <span class="pre-in-pp">
 908   .SUBTITLE "The Docheader Subtitle"
 909   .SUBTITLE DOC_COVER "The Document Cover Subtitle"
 910   .SUBTITLE COVER "The Cover Subtitle"
 911 </span>
 912 The first invocation of <kbd>.SUBTITLE</kbd> establishes the
 913 subtitle that appears in the docheader at the top of the first page
 914 of a document.  The second invocation establishes the subtitle that
 915 appears on the document cover; the third establishes the subtitle
 916 that appears on the cover (&#8220;title&#8221;) page.
 917 </p>
 918
 919 <p>
 920 If you don&#8217;t require differing subtitles for doc cover and cover
 921 pages, <kbd>.SUBTITLE</kbd>, without the optional first argument, is
 922 sufficient, provided you give the word, <kbd>SUBTITLE</kbd>, as an
 923 argument to the macro
 924 <a href="cover.html#doc-cover">DOC_COVER</a>
 925 or
 926 <a href="cover.html#cover">COVER</a>
 927 </p>
 928
 929 <!-- -AUTHOR- -->
 930
 931 <div class="macro-id-overline">
 932 <h3 id="author" class="macro-id">AUTHOR</h3>
 933 </div>
 934
 935 <div class="box-macro-args">
 936 Macro: <b>AUTHOR</b> <kbd class="macro-args">[COVER | DOC_COVER] &quot;&lt;author&gt;&quot; [ &quot;&lt;author2&gt;&quot; [&quot;&lt;author3&gt;&quot; ... ] ]</kbd>
 937 </div>
 938
 939 <p class="alias" style="margin-bottom: 0;">
 940 <i>Alias:</i> <b>EDITOR</b>
 941 </p>
 942 <p class="requires">
 943 &bull;&nbsp;String arguments must be enclosed in double-quotes
 944 </p>
 945
 946 <p>
 947 Each author string can hold as many names as you like, eg
 948 <br/>
 949 <span class="pre-in-pp" style="margin-bottom: -1em;">
 950   .AUTHOR "Joe Blow"
 951 </span>
 952 or
 953 <br/>
 954 <span class="pre-in-pp" style="margin-top: -.5em;">
 955   .AUTHOR "Joe Blow, Jane Doe" "John Hancock"
 956 </span>
 957 Mom prints each string that&#8217;s enclosed in double-quotes on a
 958 separate line in the
 959 <a href="definitions.html#docheader">docheader</a>,
 960 however only the first string appears in
 961 <a href="definitions.html#header">page headers</a>.
 962 If you want mom to put something else in the author part of page
 963 headers (say, just the last names of a document&#8217;s two
 964 authors), redefine the appropriate part of the header (see
 965 <a href="headfootpage.html#header-control">header/footer control</a>).
 966 </p>
 967
 968 <p>
 969 The strings can be caps or caps/lower-case.  I recommend caps/lower
 970 case.
 971 </p>
 972
 973 <p>
 974 If the optional argument, <kbd>COVER</kbd> or <kbd>DOC_COVER</kbd>,
 975 is given to AUTHOR, the remaining string arguments represent the
 976 author(s) that will appear on cover or document cover pages (see the
 977 <a href="cover.html#cover-intro">Introduction to cover pages</a>
 978 for a description of the difference between &#8220;document
 979 covers&#8221; and &#8220;covers&#8221;).  Thus, it is possible
 980 to have differing authors on the document cover, the cover
 981 (&#8220;title&#8221;) page, in the document first-page header and
 982 subsequent page headers/footers.  An example might be:
 983 <br/>
 984 <span class="pre-in-pp">
 985   .AUTHOR "Joe Blow"
 986   .EDITOR DOC_COVER "John Smith" "and" "Jane Doe"  \" EDITOR is an alias for AUTHOR
 987   .AUTHOR COVER "Joe Blow" "(assisted by Jane Doe)"
 988 </span>
 989 The first invocation of <kbd>.AUTHOR</kbd> establishes the author
 990 that appears in the docheader at the top of the first page of
 991 a document and in subsequent page headers/footers.  The second
 992 invocation establishes the authors (editors, in this instance) that
 993 appear on the document cover; the third establishes the author(s)
 994 that appear(s) on the cover (&#8220;title&#8221;) page.
 995 </p>
 996
 997 <p>
 998 If you don&#8217;t require differing authors for doc cover and cover
 999 pages, <kbd>.AUTHOR</kbd>, without the optional first argument, is
1000 sufficient, provided you give the word, <kbd>AUTHOR</kbd> as an
1001 argument to the macro
1002 <a href="cover.html#doc-cover">DOC_COVER</a>
1003 or
1004 <a href="cover.html#cover">COVER</a>
1005 </p>
1006
1007 <!-- -CHAPTER- -->
1008
1009 <div class="macro-id-overline">
1010 <h3 id="chapter" class="macro-id">CHAPTER</h3>
1011 </div>
1012
1013 <div class="box-macro-args">
1014 Macro: <b>CHAPTER</b> <kbd class="macro-args">&lt;chapter number&gt;</kbd>
1015 </div>
1016
1017 <p>
1018 The chapter number can be in any form you like&mdash;a digit, a roman
1019 numeral, a word.  If you choose
1020 <a href="#doctype">DOCTYPE CHAPTER</a>,
1021 mom prints whatever argument you pass CHAPTER beside the word,
1022 &#8220;Chapter&#8221;, as a single line
1023 <a href="definitions.html#docheader">docheader</a>.
1024 She also puts the same thing in the middle of
1025 <a href="definitions.html#header">page headers</a>.
1026 </p>
1027
1028 <p>
1029 Please note that if your argument to CHAPTER runs to more than one
1030 word, you must enclose the argument in double-quotes.
1031 </p>
1032
1033 <p>
1034 If you&#8217;re not using DOCTYPE CHAPTER, the macro can
1035 be used to identify any document as a chapter <i>for the purpose of
1036 prepending a chapter number to numbered head elements</i>, provided
1037 you pass it a
1038 <a href="definitions.html#numericargument">numeric argument</a>.
1039 See
1040 <a href="docelement.html#prefix-chapter-number">PREFIX_CHAPTER_NUMBER</a>.
1041 </p>
1042
1043 <!-- -CHAPTER_STRING- -->
1044
1045 <h3 id="chapter-string" class="docs">Chapter string</h3>
1046
1047 <p>
1048 If you&#8217;re not writing in English, you can ask mom to use the
1049 word for &#8220;chapter&#8221; in your own language by telling her
1050 what it is with the CHAPTER_STRING macro, like this:
1051 <br/>
1052 <span class="pre">
1053   .CHAPTER_STRING "Chapître"
1054 </span>
1055 </p>
1056
1057 <p>
1058 You can also use CHAPTER_STRING if you want
1059 &#8220;CHAPTER&#8221; (all caps) instead of &#8220;Chapter&#8221;
1060 (caps/lowercase) in the doc- and page-headers.
1061 </p>
1062
1063 <!-- -CHAPTER_TITLE- -->
1064
1065 <div class="macro-id-overline">
1066 <h3 id="chapter-title" class="macro-id">CHAPTER_TITLE</h3>
1067 </div>
1068
1069 <div class="box-macro-args">
1070 Macro: <b>CHAPTER_TITLE</b>  <kbd class="macro-args">&quot;&lt;chapter title&gt;&quot; [&quot;&lt;2nd line&gt;&quot; [&quot;&lt;3rd line&gt;&quot; ... ] ]</kbd>
1071 </div>
1072 <p class="requires">
1073 &bull;&nbsp;Arguments must be enclosed in double-quotes
1074 </p>
1075
1076 <p>
1077 If, either in addition to or instead of &#8220;Chapter
1078 &lt;n&gt;&#8221; appearing at the top of chapters, you want your
1079 chapter to have a title, use CHAPTER_TITLE, with your title enclosed
1080 in double-quotes, like this:
1081 <br/>
1082 <span class="pre">
1083   .CHAPTER_TITLE "The DMCA Nazis"
1084 </span>
1085 </p>
1086
1087 <p>
1088 CHAPTER_TITLE accepts multiple arguments, each surrounded by
1089 double-quotes.  Each argument is printed on a separate line,
1090 permitting you to create multi-line chapter titles in your
1091 docheaders.
1092 </p>
1093
1094 <p>
1095 If you&#8217;ve used
1096 <a href="#chapter">CHAPTER</a>
1097 to give the chapter a number, both &#8220;Chapter &lt;n&gt;&#8221;
1098 and the chapter title will appear at the top of the chapter, like
1099 this:
1100 <br/>
1101 <span class="pre-in-pp">
1102        Chapter 1
1103     The DMCA Nazis
1104 </span>
1105 In such a case, by default, only the chapter&#8217;s title will appear in
1106 the
1107 <a href="definitions.html#header">page headers</a>,
1108 not &#8220;Chapter &lt;n&gt;&#8221;.
1109 </p>
1110
1111 <p>
1112 If you omit CHAPTER when setting up your reference macros, only the
1113 title will appear, both at the top of page one and in subsequent
1114 page headers.
1115 </p>
1116
1117 <p>
1118 The style of the chapter title can be altered by
1119 <a href="docelement.html#docelement-control">control macros</a>,
1120 eg CHAPTER_TITLE_FAMILY, CHAPTER_TITLE_FONT, etc.  The default
1121 family, font and point size are Times Roman, Bold Italic, 4 points
1122 larger than
1123 <a href="definitions.html#running">running text</a>.
1124 </p>
1125
1126 <!-- -DRAFT- -->
1127
1128 <div class="macro-id-overline">
1129 <h3 id="draft" class="macro-id">DRAFT</h3>
1130 </div>
1131
1132 <div class="box-macro-args">
1133 Macro: <b>DRAFT</b> <kbd class="macro-args">&lt;draft number&gt;</kbd>
1134 </div>
1135
1136 <p>
1137 DRAFT only gets used with
1138 <a href="#copystyle">COPYSTYLE&nbsp;DRAFT</a>.
1139 If the COPYSTYLE is FINAL (the default), mom ignores DRAFT.  DRAFT
1140 accepts both alphabetic and numeric arguments, hence it&#8217;s
1141 possible to do either
1142 <br/>
1143 <span class="pre">
1144   .DRAFT 2
1145      or
1146   .DRAFT Two
1147 </span>
1148 </p>
1149
1150 <p>
1151 Mom prints the argument to <kbd>.DRAFT</kbd> (ie the draft number)
1152 beside the word &#8220;Draft&#8221; in the middle part of
1153 <a href="definitions.html#header">page headers</a>.
1154 </p>
1155
1156 <div class="box-tip">
1157 <p class="tip">
1158 <span class="note">A small word of caution:</span>
1159 If your argument to <kbd>.DRAFT</kbd> is more than one word long,
1160 you must enclose the argument in double-quotes.
1161 </p>
1162 </div>
1163
1164 <p>
1165 You may, if you wish, invoke <kbd>.DRAFT</kbd> without an
1166 argument, in which case, no draft number will be printed beside
1167 &#8220;Draft&#8221; in headers or footers.
1168 </p>
1169
1170 <!-- -DRAFT_STRING- -->
1171
1172 <h3 id="draft-string" class="docs">The draft string</h3>
1173
1174 <p>
1175 If you&#8217;re not writing in English, you can ask mom
1176 to use the word for &#8220;draft&#8221; in your own language by
1177 telling her what it is with the DRAFT_STRING macro,
1178 like this:
1179 <br/>
1180 <span class="pre">
1181   .DRAFT_STRING "Jet"
1182 </span>
1183 </p>
1184
1185 <p>
1186 Equally, DRAFT_STRING can be used to roll your own solution to
1187 something other than the word &#8220;Draft.&#8221; For example, you
1188 might want &#8220;Trial run alpha-three&#8221; to appear in the
1189 headers of a draft version.  You&#8217;d accomplish this by doing
1190 <br/>
1191 <span class="pre">
1192   .DRAFT alpha-three
1193   .DRAFT_STRING "Trial run"
1194 </span>
1195 </p>
1196
1197 <p>
1198 If you wanted only &#8220;Trial run&#8221; to appear, entering
1199 <kbd>.DRAFT</kbd> without an argument as well as
1200 <kbd>.DRAFT_STRING&nbsp;"Trial&nbsp;run"</kbd> is how you&#8217;d do it.
1201 </p>
1202
1203 <div class="box-tip">
1204 <p class="tip">
1205 <span class="note">Note:</span>
1206 If you define both a blank <kbd>.DRAFT</kbd> and a blank
1207 <kbd>.DRAFT_STRING</kbd>, mom skips the draft field in headers
1208 entirely.  If this is what you want, this is also the only way
1209 to do it.  Simply omitting invocations of <kbd>.DRAFT</kbd> and
1210 <kbd>.DRAFT_STRING</kbd> will result in mom using her default, which
1211 is to print &#8220;Draft &lt;number&gt;&#8221;.
1212 </p>
1213 </div>
1214
1215 <!-- -REVISION- -->
1216
1217 <div class="macro-id-overline">
1218 <h3 id="revision" class="macro-id">REVISION</h3>
1219 </div>
1220
1221 <div class="box-macro-args">
1222 Macro: <b>REVISION</b> <kbd class="macro-args">&lt;revision number&gt;</kbd>
1223 </div>
1224
1225 <p>
1226 REVISION only gets used with
1227 <a href="#copystyle">COPYSTYLE DRAFT</a>.
1228 If the COPYSTYLE is FINAL (the default), mom ignores the REVISION
1229 macro. REVISION accepts both alphabetic and numeric arguments, hence
1230 it&#8217;s possible to do either
1231 <br/>
1232 <span class="pre" style="margin-bottom: -1em;">
1233   .REVISION 2
1234 </span>
1235 or
1236 <span class="pre" style="margin-top: -.5em;">
1237   .REVISION Two
1238 </span>
1239 </p>
1240
1241 <p>
1242 Mom prints the revision number beside the shortform
1243 &#8220;Rev.&#8221; in the middle part of
1244 <a href="definitions.html#header">page headers</a>.
1245 </p>
1246
1247 <div class="box-tip">
1248 <p class="tip">
1249 <span class="note">A small word of caution:</span>
1250 If your argument to <kbd>.REVISION</kbd> is more than one word long,
1251 you must enclose the argument in double-quotes.
1252 </p>
1253 </div>
1254
1255 <p>
1256 You may, if you wish, invoke <kbd>.REVISION</kbd> without an
1257 argument, in which case, no revision number will be printed beside
1258 &quot;Rev.&quot; in headers or footers.
1259 </p>
1260
1261 <!-- -REVISION_STRING- -->
1262
1263 <h3 id="revision-string" class="docs">The revision string</h3>
1264
1265 <p>
1266 If you&#8217;re not writing in English, you can ask mom
1267 to use the word for &#8220;revision,&#8221; or a shortform
1268 thereof, in your own language by telling her what it is with the
1269 REVISION_STRING macro, like this:
1270 <br/>
1271 <span class="pre">
1272   .REVISION_STRING "Rév."
1273 </span>
1274 </p>
1275
1276 <p>
1277 Additionally, you may sometimes want to make use of mom&#8217;s
1278 <a href="#copystyle">COPYSTYLE DRAFT</a>
1279 but not actually require any draft information.  For example,
1280 you might like mom to indicate only the revision number of
1281 your document.  The way to do that is to define an empty
1282 <kbd>.DRAFT</kbd> and <kbd>.DRAFT_STRING</kbd> in addition to
1283 <kbd>.REVISION</kbd>, like this:
1284 <br/>
1285 <span class="pre">
1286   .DRAFT
1287   .DRAFT_STRING
1288   .REVISION 2
1289 </span>
1290 </p>
1291
1292 <p>
1293 Equally, if you want to roll your own solution to what revision
1294 information appears in headers, you could do something like this:
1295 <br/>
1296 <span class="pre">
1297   .DRAFT
1298   .DRAFT_STRING
1299   .REVISION "two-twenty-two"
1300   .REVISION_STRING "Revision"
1301 </span>
1302 </p>
1303
1304 <p>
1305 The above, naturally, has no draft information.  If you want to roll
1306 your own <kbd>.DRAFT</kbd> and/or <kbd>.DRAFT_STRING</kbd> as well,
1307 simply supply arguments to either or both.
1308 </p>
1309
1310 <!-- -COPYRIGHT- -->
1311
1312 <div class="macro-id-overline">
1313 <h3 id="copyright" class="macro-id">COPYRIGHT</h3>
1314 </div>
1315
1316 <div class="box-macro-args">
1317 Macro: <b>COPYRIGHT</b> <kbd class="macro-args">[COVER | DOC_COVER] &quot;&lt;copyright info&gt;&quot;</kbd>
1318 </div>
1319
1320 <p class="requires">
1321 &bull;&nbsp;Argument must be enclosed in double-quotes
1322 </p>
1323
1324 <p>
1325 The argument passed to COPYRIGHT is only used on cover or doc cover
1326 pages, and then only if the argument COPYRIGHT is passed to
1327 <a href="cover.html#cover">COVER</a>
1328 or
1329 <a href="cover.html#doc-cover">DOC_COVER</a>.
1330 Do not include the copyright symbol in the argument passed to
1331 COPYRIGHT; mom puts it in for you.
1332 </p>
1333
1334 <p>
1335 If the optional argument, <kbd>COVER</kbd> or <kbd>DOC_COVER</kbd>,
1336 is given to COPYRIGHT, the string argument represents the copyright
1337 information that will appear on cover or document cover pages (see
1338 the
1339 <a href="cover.html#cover-intro">Introduction to cover pages</a>
1340 for a description of the difference between &#8220;document
1341 covers&#8221; and &#8220;covers&#8221;).  Thus, it is possible to
1342 have differing copyright information on the document cover and on
1343 the cover (&#8220;title&#8221;) page.  An example might be:
1344 <br/>
1345 <span class="pre-in-pp">
1346   .COPYRIGHT DOC_COVER "2010 John Smith and Jane Doe"
1347   .COPYRIGHT COVER "2008 Joe Blow"
1348 </span>
1349 The first invocation of <kbd>.COPYRIGHT</kbd> establishes the
1350 copyright information that appears on the document cover; the second
1351 establishes the copyright information that appears on the cover
1352 (&#8220;title&#8221;) page.
1353 </p>
1354
1355 <p>
1356 If you don&#8217;t require differing copyright information for
1357 doc cover and cover pages, <kbd>.COPYRIGHT</kbd>, without the
1358 optional first argument, is sufficient, provided you give the word,
1359 <kbd>COPYRIGHT</kbd>, as an argument to the macro
1360 <a href="cover.html#doc-cover">DOC_COVER</a>
1361 or
1362 <a href="cover.html#cover">COVER</a>
1363 </p>
1364
1365 <!-- -MISC- -->
1366
1367 <div class="macro-id-overline">
1368 <h3 id="misc" class="macro-id">MISC</h3>
1369 </div>
1370
1371 <div class="box-macro-args">
1372 Macro: <b>MISC</b> <kbd class="macro-args">[COVER | DOC_COVER] &quot;&lt;argument 1&gt;&quot; [&quot;&lt;argument 2&gt;&quot; &quot;&lt;argument 3&gt;&quot; ...]</kbd>
1373 </div>
1374
1375 <p class="requires">
1376 &bull;&nbsp;String arguments must be enclosed in double-quotes
1377 </p>
1378
1379 <p>
1380 The argument(s) passed to MISC are only used on cover or doc cover
1381 pages, and then only if the argument <kbd>MISC</kbd> is passed to
1382 <a href="cover.html#cover">COVER</a>
1383 or
1384 <a href="cover.html#doc-cover">DOC_COVER</a>.
1385 MISC can contain any information you like.  Each argument appears on
1386 a separate line at the bottom of the cover or doc cover page.
1387 </p>
1388
1389 <p>
1390 For example, if you&#8217;re submitting an essay where the prof has
1391 requested that you include the course number, his name and the date,
1392 you could do
1393 <br/>
1394 <span class="pre-in-pp">
1395   .MISC "Music History 101" "Professor Hasbeen" "Dec. 24, 2010"
1396 </span>
1397 and the information would appear on the essay&#8217;s cover page.
1398 </p>
1399
1400 <p>
1401 If the optional argument, <kbd>COVER</kbd> or <kbd>DOC_COVER</kbd>,
1402 is given to MISC, the string arguments represent the miscellaneous
1403 information that will appear on cover or document cover pages (see
1404 the
1405 <a href="cover.html#cover-intro">Introduction to cover pages</a>
1406 for a description of the difference between &#8220;document
1407 covers&#8221; and &#8220;covers&#8221;).  Thus, it is possible to
1408 have differing miscellaneous information on the document cover and
1409 on the cover (&#8220;title&#8221;) page.  An example might be:
1410 <br/>
1411 <span class="pre">
1412   .MISC DOC_COVER "Music History 101" "Professor Hasbeen"
1413   .MISC COVER "Spring Term Paper"
1414 </span>
1415 </p>
1416
1417 <p>
1418 The first invocation of <kbd>.MISC</kbd> establishes the
1419 miscellaneous information that appears on the document cover; the
1420 second establishes the miscellaneous information that appears on the
1421 cover (&#8220;title&#8221;) page.
1422 </p>
1423
1424 <p>
1425 If you don&#8217;t require differing miscellaneous information
1426 for doc cover and cover pages, <kbd>.MISC</kbd>, without the
1427 optional first argument, is sufficient, provided you give the word
1428 &#8220;MISC&#8221; as an argument to the macro
1429 <a href="cover.html#doc-cover">DOC_COVER</a>
1430 or
1431 <a href="cover.html#cover">COVER</a>
1432 </p>
1433
1434 <!-- -COVER_TITLE- -->
1435
1436 <div class="macro-id-overline">
1437 <h3 class="macro-id">COVERTITLE &amp; DOC_COVERTITLE</h3>
1438 </div>
1439
1440 <div id="covertitle" class="box-macro-args">
1441 Macro: <b>COVERTITLE</b> <kbd class="macro-args">&quot;&lt;user defined cover page title&gt;&quot; [&quot;&lt;2nd line&gt;&quot; [&quot;&lt;3rd line&gt;&quot; ... ] ]</kbd>
1442 </div>
1443 <p class="requires">
1444 &bull;&nbsp;Arguments must be enclosed in double-quotes
1445 </p>
1446
1447 <div id="doc-covertitle" class="box-macro-args">
1448 Macro: <b>DOC_COVERTITLE</b> <kbd class="macro-args">&quot;&lt;user defined document cover page title&gt;&quot; [&quot;&lt;2nd line&gt;&quot; [&quot;&lt;3rd line&gt;&quot; ... ] ]</kbd>
1449 </div>
1450 <p class="requires">
1451 &bull;&nbsp;Arguments must be enclosed in double-quotes
1452 </p>
1453
1454 <p>
1455 The arguments passed to COVERTITLE or DOC_COVERTITLE are only
1456 used on cover or doc cover pages, and then only if the argument
1457 COVERTITLE or DOC_COVERTITLE is passed to
1458 <a href="cover.html#cover">COVER</a>
1459 or
1460 <a href="cover.html#doc-cover">DOC_COVER</a>.
1461 </p>
1462
1463 <p>
1464 The only time you require a COVERTITLE or DOC_COVERTITLE is when
1465 none of the required first arguments to COVER or DOC_COVER fits
1466 your needs for the title you want to appear on cover (or doc cover)
1467 pages.
1468 </p>
1469
1470 <p>
1471 COVERTITLE and DOC_COVERTITLE accept multiple arguments, each
1472 surrounded by double-quotes.  Each argument is printed on a separate
1473 line, permitting you to create multi-line titles on your cover
1474 and/or doc cover pages.
1475 </p>
1476
1477 <div class="macro-id-overline">
1478 <h3 class="macro-id">PDF Title</h3>
1479 </div>
1480
1481 <div id="pdftitle" class="box-macro-args">
1482 Macro: <b>PDF_TITLE</b> <kbd class="macro-args">&quot;&lt;pdf viewer window title&gt;&quot; </kbd>
1483 </div>
1484 <p class="requires">
1485 &bull;&nbsp;Arguments must be enclosed in double-quotes
1486 </p>
1487
1488 <p>
1489 Except for
1490 <a href="#doctitle">DOCTITLE</a>,
1491 mom does not, by default, provide PDF viewers with a document title.
1492 You may set one, if you like, with PDF_TITLE.
1493 </p>
1494
1495 <div class="rule-short"><hr/></div>
1496
1497 <!-- ======================================================================== -->
1498
1499 <h2 id="docstyle-macros" class="macro-group">The docstyle macros</h2>
1500
1501 <p>
1502 The docstyle macros tell mom what type of document you&#8217;re
1503 writing, whether you want the output typeset or &#8220;typewritten,
1504 double-spaced&#8221;, and whether you want a draft copy (with draft
1505 and revision information in the headers) or a final copy.
1506 </p>
1507
1508 <div class="macro-list-container">
1509 <h3 id="index-docstyle" class="macro-list">Docstyle macros</h3>
1510 <ul class="macro-list">
1511   <li><a href="#doctype">DOCTYPE</a>
1512   <ul style="margin-left: -.5em; list-style-type: disc;">
1513     <li><a href="#doctype-underline">DOCTYPE_UNDERLINE</a> &ndash; how to control DOCTYPE <kbd>NAMED</kbd> underlining</li>
1514   </ul></li>
1515   <li><a href="#printstyle">PRINTSTYLE</a> &ndash; non-optional macro required for document processing
1516   <ul style="margin-left: -.5em; list-style-type: disc;">
1517     <li><a href="#typeset-defaults">Defaults for PRINTSTYLE TYPESET</a></li>
1518     <li><a href="#typewrite-defaults">Defaults for PRINTSTYLE TYPEWRITE</a>
1519     <ul style="margin-left: -.5em; list-style-type: circle;">
1520       <li><a href="#typewrite-control">PRINTSTYLE TYPEWRITE control macros</a>
1521       <ul style="margin-left: -1.5em; list-style-type: square;">
1522         <li><a href="#typewriter-family">Family</a></li>
1523         <li><a href="#typewriter-size">Point size</a></li>
1524         <li><a href="#typewriter-underlining">Underlining of italics</a></li>
1525       </ul></li>
1526     </ul></li>
1527   </ul></li>
1528   <li><a href="#copystyle">COPYSTYLE</a></li>
1529 </ul>
1530 </div>
1531
1532 <!-- -DOCTYPE- -->
1533
1534 <div class="macro-id-overline">
1535 <h3 id="doctype" class="macro-id">DOCTYPE</h3>
1536 </div>
1537
1538 <div class="box-macro-args">
1539 Macro: <b>DOCTYPE</b> <kbd class="macro-args">DEFAULT | CHAPTER | NAMED &quot;&lt;name&gt;&quot; | LETTER</kbd>
1540 </div>
1541
1542 <p>
1543 The arguments <kbd>DEFAULT,</kbd> <kbd>CHAPTER</kbd> and
1544 <kbd>NAMED</kbd> tell mom what to put in the
1545 <a href="definitions.html#docheader">docheader</a>
1546 and
1547 <a href="definitions.html#header">page headers</a>.
1548 <kbd>LETTER</kbd> tells her that you want to write a letter.
1549 </p>
1550
1551 <p>
1552 Mom&#8217;s default DOCTYPE is <kbd>DEFAULT</kbd>.  If that&#8217;s
1553 what you want, you don&#8217;t have to give a DOCTYPE command.
1554 </p>
1555
1556 <p>
1557 <kbd>DEFAULT</kbd> prints a
1558 <a href="definitions.html#docheader">docheader</a>
1559 containing the title, subtitle and author information given to the
1560 <a href="#reference-macros">reference macros</a>,
1561 and page headers with the author and title.  (See
1562 <a href="headfootpage.html#header-style">Default specs for headers</a>
1563 for how mom outputs each part of the page header.)
1564 </p>
1565
1566 <p>
1567 <kbd>CHAPTER</kbd> prints &#8220;Chapter &lt;n&gt;&#8221; in place
1568 of a
1569 <a href="definitions.html#docheader">docheader</a>
1570 (&lt;n&gt; is what you gave to the
1571 <a href="#reference-macros">reference macro</a>,
1572 <kbd><a href="#chapter">CHAPTER</a></kbd>).
1573 If you give the chapter a title with
1574 <a href="#chapter-title">CHAPTER TITLE</a>,
1575 mom prints &#8220;Chapter &lt;n&gt;&#8221; and the
1576 title underneath.  If you omit the
1577 <a href="#chapter">CHAPTER</a>
1578 reference macro but supply a
1579 <a href="#chapter-title">CHAPTER_TITLE</a>,
1580 mom prints only the chapter title.
1581 </p>
1582
1583 <p>
1584 The page headers in DOCTYPE <kbd>CHAPTER</kbd> contain the author,
1585 the title of the book (which you gave with
1586 <a href="#title">TITLE</a>),
1587 and &#8220;Chapter &lt;n&gt;&#8221; (or the chapter title).  See
1588 <a href="headfootpage.html#header-style">Default Specs for Headers</a>
1589 for mom&#8217;s default type parameters for each part of
1590 the page header.
1591 </p>
1592
1593 <p>
1594 <kbd>NAMED</kbd> takes an additional argument: a name for this
1595 particular kind of document (eg outline, synopsis, abstract,
1596 memorandum), enclosed in double-quotes. <kbd>NAMED</kbd> is
1597 identical to <kbd>DEFAULT</kbd> except that mom prints the argument
1598 to <kbd>NAMED</kbd> beneath the
1599 <a href="definitions.html#docheader">docheader</a>,
1600 as well as in page headers.
1601 (See
1602 <a href="headfootpage.html#header-style">Default specs for headers</a>
1603 for how mom outputs each part of the page header.)
1604 </p>
1605
1606 <p>
1607 Additionally, if you wish the name of this particular kind of
1608 document to be coloured, you can pass DOCTYPE <kbd>NAMED</kbd> a
1609 third (optional) argument: the name of a colour pre-defined (or
1610 &#8220;initialized&#8221;) with
1611 <a href="color.html#newcolor">NEWCOLOR</a>
1612 or
1613 <a href="color.html#xcolor">XCOLOR</a>.
1614 For example, if you have a doctype named &#8220;Warning&#8221;,
1615 and you&#8217;d like &#8220;Warning&#8221; to be in red, assuming you&#8217;ve
1616 pre-defined (or &#8220;initialized&#8221;) the color, red, this is
1617 what the DOCTYPE entry would look like:
1618 <br/>
1619 <span class="pre">
1620   .DOCTYPE NAMED "Warning" red
1621 </span>
1622 </p>
1623
1624 <div class="box-tip" style="margin-top: 1.5em;">
1625 <h3 id="doctype-underline" class="docs control">How to control DOCTYPE NAMED underlining</h3>
1626
1627 <p style="tip">
1628 By default, the string passed to DOCTYPE <kbd>NAMED</kbd> is
1629 underlined in the docheader, and on document-cover pages and cover
1630 (&#8220;title&#8221;) pages.  (See the
1631 <a href="cover.html#intro">Introduction to covers</a>
1632 for the difference between &#8220;doc cover&#8221; and
1633 &#8220;cover&#8221; pages.)
1634 </p>
1635
1636 <p>
1637 You can use the macro DOCTYPE_UNDERLINE to set the weight of
1638 the underline and its distance from where the doctype-name appears
1639 in the docheader (doc covers and covers handle underlining of the
1640 doctype-name differently; see
1641 <a href="cover.html#cover-underline">COVER_UNDERLINE</a>),
1642 or simply toggle doctype underlining on or off.  Mom&#8217;s default
1643 is to underline the doctype-name.
1644 </p>
1645
1646 <p>
1647 The order of arguments is <kbd>weight</kbd>, optionally followed by
1648 <kbd>gap</kbd>, where &#8220;gap&#8221; is the distance from the
1649 <a href="definitions.html#baseline">baseline</a>
1650 of the doctype-name to the underline.
1651 </p>
1652
1653 <p>
1654 The <kbd>weight</kbd> argument is given in points, or fractions
1655 thereof, and must not have the
1656 <a href="definitions.html#unitofmeasure">unit of measure</a>,
1657 <kbd>p</kbd>, appended.  Like
1658 <a href="inlines.html#rule-weight">RULE_WEIGHT</a>,
1659 weights must be greater than 0 and less than 100.  Mom&#8217;s
1660 default for DOCTYPE <kbd>NAMED</kbd> underlining is 1/2 point.
1661 </p>
1662
1663 <p>
1664 The <kbd>gap</kbd> argument can be given using any unit of measure,
1665 and must have the unit of measure appended to the argument.
1666 The distance of the gap is measured from the baseline of the
1667 DOCTYPE <kbd>NAMED</kbd> name to the upper edge of the underline.
1668 Mom&#8217;s default gap for named-doctype underlining is 2 points.
1669 </p>
1670
1671 <p>
1672 As an example, suppose you want the doctype-name underlined in the
1673 docheader with a 2-point rule separated from the doctype-name by 3
1674 points.  The way to accomplish it is:
1675 <br/>
1676 <span class="pre-in-pp">
1677   .DOCTYPE_UNDERLINE 2 3p
1678 </span>
1679 If you wanted the same thing, but were content with mom&#8217;s
1680 default gap of 2 points,
1681 <br/>
1682 <span class="pre-in-pp">
1683   .DOCTYPE_UNDERLINE 2
1684 </span>
1685 would do the trick.
1686 </p>
1687
1688 <p>
1689 If you merely want to toggle the underlining of
1690 the doctype-name in docheaders on or off, invoke
1691 <kbd>.DOCTYPE_UNDERLINE</kbd> by itself to turn the underlining on,
1692 or <kbd>.DOCTYPE_UNDERLINE&nbsp;OFF</kbd> (or NO, X, etc.)
1693 </p>
1694
1695 <p class="tip-bottom">
1696 Please note that if you supply a weight to DOCTYPE_UNDERLINE, and
1697 optionally a gap, you also turn the underlining of the doctype-name
1698 in docheaders on; if this is not what you want, you must turn the
1699 underlining off manually afterwards.
1700 </p>
1701 </div>
1702
1703 <p>
1704 <kbd>LETTER</kbd> tells mom you&#8217;re writing a letter.  See the
1705 section
1706 <a href="letters.html#letters">Writing Letters</a>
1707 for instructions on using mom to format letters.
1708 </p>
1709
1710 <!-- -PRINTSTYLE- -->
1711
1712 <div class="macro-id-overline">
1713 <h3 id="printstyle" class="macro-id">PRINTSTYLE</h3>
1714 </div>
1715
1716 <div class="box-macro-args">
1717 Macro: <b>PRINTSTYLE</b> <kbd class="macro-args">TYPESET | TYPEWRITE [ SINGLESPACE ]</kbd>
1718 </div>
1719
1720 <p class="requires">
1721 &bull;&nbsp;Required for document processing
1722 <br/>
1723 Must come before any changes to default document style
1724 </p>
1725
1726 <p>
1727 PRINTSTYLE tells mom whether to typeset a document, or to print it
1728 out &#8220;typewritten, doubled-spaced&#8221;.
1729 </p>
1730
1731 <div class="box-important">
1732 <p class="tip-top">
1733 <span class="important">Important:</span>
1734 <b>This macro may not be omitted.</b> In order for document
1735 processing to take place, mom requires a PRINTSTYLE.  If you
1736 don&#8217;t give one, mom will warn you on stderr and print a single
1737 page with a nasty message.
1738 </p>
1739
1740 <p class="tip-bottom">
1741 <span class="important">Just as important:</span>
1742 PRINTSTYLE <b>must precede any and all page and style
1743 parameters associated with a document</b> with the exception of
1744 <kbd>PAPER</kbd>, <kbd>PAGEWIDTH</kbd>, and/or
1745 <kbd>PAGELENGTH</kbd>, which should be placed at the top of your
1746 file.  PRINTSTYLE sets up complete templates that include default
1747 margins, family, fonts, point sizes, and so on.  Therefore, changes
1748 to any aspect of document style must come afterwards.  For example,
1749 <br/>
1750 <span class="pre-in-pp">
1751   .PAPER A4
1752   .LS 14
1753   .QUAD LEFT
1754   .PRINTSTYLE TYPESET
1755 </span>
1756 will not change mom&#8217;s default document leading to 14 points,
1757 nor the default justification style (fully justified) to left
1758 justified, whereas
1759 <br/>
1760 <span class="pre-in-pp">
1761   .PAPER A4
1762   .PRINTSTYLE TYPESET
1763   .LS 14
1764   .QUAD LEFT
1765 </span>
1766 will.
1767 </p>
1768
1769 </div>
1770
1771 <p>
1772 <kbd>TYPESET</kbd>, as the argument implies, typesets
1773 documents (by default in Times Roman; see
1774 <a href="#typeset-defaults">TYPESET defaults</a>).
1775 You have full access to all the
1776 <a href="typesetting.html#macros-typesetting">typesetting macros</a>
1777 as well as the
1778 <a href="definitions.html#style-control">style control macros</a>
1779 of document processing.
1780 </p>
1781
1782 <p>
1783 With <kbd>TYPEWRITE</kbd>, mom does her best to reproduce the look
1784 and feel of typewritten, double-spaced copy (see
1785 <a href="#typewrite-defaults">TYPEWRITE defaults</a>).
1786 <a href="docelement.html#docelement-control">Control macros</a>
1787 and
1788 <a href="typesetting.html#intro-macros-typesetting">typesetting macros</a>
1789 that alter family, font, point size, and
1790 <a href="definitions.html#leading">leading</a>
1791 are (mostly) ignored.  An important exception is
1792 <a href="headfootpage.html#hdrftr-global-size">HEADER_SIZE</a>
1793 (and, by extension, FOOTER_SIZE), which allows you to reduce the
1794 point size of headers/footers should they become too crowded.  Most
1795 of mom&#8217;s inlines affecting the appearance of type are also
1796 ignored
1797 (<kbd><a href="inlines.html#inline-size-mom">\*S[&lt;size&gt;]</a></kbd>
1798 is an exception; there may be a few others).
1799 </p>
1800
1801 <p>
1802 In short, <kbd>TYPEWRITE</kbd> never produces effects
1803 other than those available on a typewriter.  Don&#8217;t be fooled
1804 by how brainless this sounds; mom is remarkably sophisticated when
1805 it comes to conveying the typographic sense of a document within the
1806 confines of <kbd>TYPEWRITE</kbd>.
1807 </p>
1808
1809 <p>
1810 The primary uses of <kbd>TYPEWRITE</kbd> are: outputting hard
1811 copy drafts of your work (for editing) and producing documents
1812 for submission to publishers and agents who (wisely) insist on
1813 typewritten, double-spaced copy.  To get a nicely typeset version of
1814 work that&#8217;s in the submission phase of its life (say, to show
1815 fellow writers for critiquing), simply change <kbd>TYPEWRITE</kbd>
1816 to <kbd>TYPESET</kbd> and print out a copy.
1817 </p>
1818
1819 <p>
1820 If, for some reason, you would prefer the output of
1821 <kbd>TYPEWRITE</kbd> single-spaced, pass PRINTSTYLE
1822 <kbd>TYPEWRITE</kbd> the optional argument, <kbd>SINGLESPACE</kbd>.
1823 </p>
1824
1825 <div class="defaults-container">
1826 <h3 id="typeset-defaults" class="docs defaults" style="margin-top: 0;">PRINTSTYLE TYPESET defaults</h3>
1827 <span class="pre defaults">
1828   Family            = Times Roman
1829   Point size        = 12.5
1830   Paragraph leading = 16 points, adjusted
1831   Fill mode         = justified
1832   Hyphenation       = enabled
1833                       max. lines = 2
1834                       margin = 36 points
1835                       interword adjustment = 1 point
1836   Kerning           = enabled
1837   Ligatures         = enabled
1838   Smartquotes       = enabled
1839   Word space        = groff default
1840   Sentence space    = 0
1841 </span>
1842 </div>
1843
1844 <div class="defaults-container">
1845 <h3 id="typewrite-defaults" class="docs defaults" style="margin-top: 0;">PRINTSTYLE TYPEWRITE defaults</h3>
1846 <span class="pre defaults">
1847   Family            = Courier
1848   Italics           = underlined
1849   Point size        = 12
1850   Paragraph leading = 24 points, adjusted; 12 points for SINGLESPACE
1851   Fill mode         = left
1852   Hyphenation       = disabled
1853   Kerning           = disabled
1854   Ligatures         = disabled
1855   Smartquotes       = disabled
1856   Word space        = groff default
1857   Sentence space    = groff default
1858   Columns           = ignored
1859 </span>
1860 </div>
1861
1862 <div class="box-tip" style="margin-top: 1.5em;">
1863 <h3 id="typewrite-control" class="docs control">PRINTSTYLE TYPEWRITE control macros</h3>
1864
1865 <h4 id="typewriter-family" class="docs">Family</h4>
1866
1867 <p style="margin-top: .5em;">
1868 If you&#8217;d prefer a monospace
1869 <a href="definitions.html#family">family</a>
1870 for PRINTSTYLE <kbd>TYPEWRITE</kbd> other than than mom's default,
1871 Courier, you can change it with
1872 <kbd>.TYPEWRITER_FAMILY&nbsp;&lt;family&gt;</kbd> (or
1873 <kbd>.TYPEWRITER_FAM</kbd>).  Since groff ships with only the
1874 Courier family, you will have to install any other monospace family
1875 yourself.  See
1876 <a href="appendices.html#fonts">Adding fonts to
1877 groff</a>.
1878 </p>
1879
1880 <h4 id="typewriter-size" class="docs">Point size</h4>
1881
1882 <p style="margin-top: .5em;">
1883 If you&#8217;d like a smaller or larger point size for
1884 for PRINTSTYLE <kbd>TYPEWRITE</kbd> (mom&#8217;s default is 12-point),
1885 you can change it with
1886 <kbd>.TYPEWRITER_SIZE&nbsp;&lt;size&gt;</kbd>.  There&#8217;s no need to
1887 add a
1888 <a href="definitions.html#unitofmeasure">unit of measure</a>
1889 to the <kbd>&lt;size&gt;</kbd> argument; points is assumed.  Be
1890 aware, however, that regardless of point size, mom&#8217;s
1891 leading/linespacing for <kbd>TYPEWRITE</kbd> is fixed at 24-point
1892 for double-spaced, and 12-point for single-spaced.
1893 </p>
1894
1895 <h4 id="typewriter-underlining" class="docs">Underlining of italics</h4>
1896
1897 <p>
1898 In PRINTSTYLE <kbd>TYPEWRITE</kbd>, mom, by default, underlines
1899 anything that looks like italics.  This includes the
1900 <a href="typesetting.html#slant-inline"><kbd>\*[SLANT]</kbd></a>
1901 <a href="definitions.html#inlines">inline escape</a>
1902 for pseudo-italics.
1903 </p>
1904
1905 <p id="printstyle-italics">
1906 If you&#8217;d prefer that mom were less bloody-minded
1907 about pretending to be a typewriter (ie you&#8217;d like italics and
1908 pseudo-italics to come out as italics), use the control macros
1909 <br/>
1910 <span class="pre-in-pp">
1911   .ITALIC_MEANS_ITALIC
1912 </span>
1913 and
1914 <span class="pre-in-pp">
1915   .SLANT_MEANS_SLANT
1916 </span>
1917 Neither requires an argument.
1918 </p>
1919
1920 <p>
1921 Although it&#8217;s unlikely, should you wish to reverse
1922 the sense of these macros in the midst of a document,
1923 <kbd>.UNDERLINE_ITALIC</kbd> and <kbd>.UNDERLINE_SLANT</kbd> restore
1924 underlining of italics and pseudo-italics.
1925 </p>
1926
1927 <p id="underline-quotes">
1928 Additionally, by default, mom underlines
1929 <a href="definitions.html#quotes">quotes</a>
1930 (but not
1931 <a href="definitions.html#blockquotes">blockquotes</a>)
1932 in PRINTSTYLE <kbd>TYPEWRITE</kbd>.  If you don&#8217;t like this
1933 behaviour, turn it off with
1934 <br/>
1935 <span class="pre">
1936   .UNDERLINE_QUOTES OFF
1937 </span>
1938 </p>
1939
1940 <p>
1941 To turn underlining of quotes back on, use UNDERLINE_QUOTES without
1942 an argument.
1943 </p>
1944
1945 <p class="tip-bottom">
1946 While most of the
1947 <a href="docelement.html#docelement-control">control macros</a>
1948 have no effect on <b>PRINTSTYLE TYPEWRITE</b>, there
1949 is an important exception:
1950 <a href="headfootpage.html#hdrftr-global-size">HEADER_SIZE</a>
1951 (and by extension, FOOTER_SIZE).  This is
1952 particularly useful for reducing the point size of
1953 headers/footers should they become crowded (quite likely to
1954 happen if the title of your document is long and your
1955 <kbd><a href="#copystyle">COPYSTYLE</a></kbd>
1956 is DRAFT).
1957 </p>
1958 </div>
1959
1960 <!-- -COPYSTYLE- -->
1961
1962 <div class="macro-id-overline">
1963 <h3 id="copystyle" class="macro-id">COPYSTYLE</h3>
1964 </div>
1965
1966 <div class="box-macro-args">
1967 Macro: <b>COPYSTYLE</b> <kbd class="macro-args">DRAFT | FINAL</kbd>
1968 </div>
1969
1970 <p>
1971 Mom&#8217;s default COPYSTYLE is <kbd>FINAL</kbd>, so you
1972 don&#8217;t have to use this macro unless you want to.
1973 </p>
1974
1975 <p>
1976 COPYSTYLE <kbd>DRAFT</kbd> exhibits the following behaviour:
1977 </p>
1978 <ol style="margin-top: -.5em;">
1979   <li>Documents start on page 1, whether or not you
1980       request a different starting page number with
1981       <a href="headfootpage.html#pagenumber">PAGENUMBER</a>.
1982   </li>
1983   <li>Page numbers are set in lower case roman numerals.</li>
1984   <li>The draft number supplied by
1985       <a href="#draft">DRAFT</a>
1986       and a revision number, if supplied with
1987       <a href="#revision">REVISION</a>
1988       (see
1989       <a href="#reference-macros">reference macros</a>),
1990       appear in the centre part of
1991       <a href="definitions.html#header">page headers</a>
1992       (or footers, depending on which you&#8217;ve selected) along with
1993       any other information that normally appears there.
1994   </li>
1995 </ol>
1996
1997 <div class="box-important">
1998 <p class="tip">
1999 <span class="important">Important:</span>
2000 If you define your own centre part for page headers with
2001 <a href="headfootpage.html#hdrftr-center">HEADER_CENTER</a>,
2002 no draft and/or revision number will appear there.  If you want
2003 draft and revision information in this circumstance, use
2004 <a href="headfootpage.html#draft-with-pagenumber">DRAFT_WITH_PAGENUMBER</a>.
2005 </p>
2006 </div>
2007
2008 <p>
2009 COPYSTYLE <kbd>FINAL</kbd> differs from <kbd>DRAFT</kbd> in that:
2010 </p>
2011 <ol style="margin-top: -.5em;">
2012   <li>It respects the starting page number you give the document.</li>
2013   <li>Page numbers are set in normal (Arabic) digits.</li>
2014   <li>No draft or revision number appears in the page headers.</li>
2015 </ol>
2016
2017 <div class="box-tip">
2018 <p id="copystyle-note" class="tip">
2019 <span class="note">Note:</span>
2020 The centre part of page headers can get crowded, especially with
2021 <a href="docprocessing.html#doctype">DOCTYPE <kbd>CHAPTER</kbd></a>
2022 and
2023 <a href="docprocessing.html#doctype">DOCTYPE <kbd>NAMED</kbd></a>,
2024 when the COPYSTYLE is <kbd>DRAFT</kbd>.  Three mechanisms are
2025 available to overcome this problem.  One is to reduce the overall
2026 size of headers (with
2027 <a href="headfootpage.html#hdrftr-global-size">HEADER_SIZE</a>).
2028 Another, which only works with
2029 <a href="docprocessing.html#printstyle">PRINTSTYLE <kbd>TYPESET</kbd></a>,
2030 is to reduce the size of the header&#8217;s centre part only (with
2031 <a href="headfootpage.html#_size">HEADER_CENTER_SIZE</a>).
2032 And finally, you can elect to have the draft/revision information
2033 attached to page numbers instead of having it appear in the centre
2034 of page headers (see
2035 <a href="headfootpage.html#draft-with-pagenumber">DRAFT_WITH_PAGENUMBER</a>).
2036 </p>
2037 </div>
2038
2039 <div class="rule-short"><hr/></div>
2040
2041 <!-- ======================================================================== -->
2042
2043 <h2 id="start-macro" class="macro-group">Initiate document processing</h2>
2044
2045 <p>
2046 In order to use mom&#8217;s document element macros (tags), you have
2047 to tell her you want them.  The macro to do this is
2048 <a href="#start">START</a>.
2049 </p>
2050
2051 <p>
2052 START collects the information you gave mom in the setup section at
2053 the top of your file (see
2054 <a href="#docprocessing-tut">Tutorial &ndash; Setting up a mom document</a>),
2055 merges it with her defaults, sets up headers and page numbering,
2056 and prepares mom to process your document using the document
2057 element tags.  No document processing takes place until you invoke
2058 <kbd>.START</kbd>.
2059 </p>
2060
2061 <!-- -START- -->
2062
2063 <div class="macro-id-overline">
2064 <h3 id="start" class="macro-id">START</h3>
2065 </div>
2066
2067 <div class="box-macro-args">
2068 Macro: <b>START</b>
2069 </div>
2070 <p class="requires">
2071 &bull;&nbsp;Required for document processing
2072 </p>
2073
2074 <p>
2075 START takes no arguments.  It simply instructs mom to begin document
2076 processing.  If you don&#8217;t want document processing (ie you
2077 only want the
2078 <a href="typesetting.html#macros-typesetting">typesetting macros</a>),
2079 don&#8217;t use START.
2080 </p>
2081
2082 <p>
2083 At a barest minimum before START, you must enter a
2084 <a href="#printstyle">PRINTSTYLE</a>
2085 command.
2086 </p>
2087
2088 <div class="rule-short"><hr/></div>
2089
2090 <!-- ======================================================================== -->
2091
2092 <h2 id="style-before-start" class="macro-group">Establishing typestyle and formatting parameters before START</h2>
2093
2094 <p>
2095 In the third (optional) part of setting up a document (the
2096 stylesheet; see
2097 <a href="#docprocessing-tut">Tutorial &ndash; Setting up a mom document</a>),
2098 you can use the
2099 <a href="typesetting.html">typesetting macros</a>
2100 to change mom&#8217;s document-wide defaults for margins,
2101 line length, family, base point size,
2102 <a href="definitions.html#leading">leading</a>,
2103 and justification style.
2104 </p>
2105
2106 <p>
2107 Two additional style concerns have to be addressed here (ie in
2108 macros before
2109 <a href="#start">START</a>):
2110 changes to the
2111 <a href="definitions.html#docheader">docheader</a>,
2112 and whether you want you want the document&#8217;s nominal leading
2113 adjusted to fill pages fully to the bottom margin.
2114 </p>
2115
2116 <div class="macro-list-container" style="margin-top: 2em;">
2117 <h3 id="index-style-before-start" class="macro-list">Type &amp; formatting parameters before START</h3>
2118 <ul class="macro-list">
2119   <li><a href="#type-before-start">Behaviour of the typesetting macros before START</a>
2120   <ul class="sublist" style="line-height: 120%; margin-bottom: .25em;">
2121     <li><a href="#meanings">List of meanings</a></li>
2122     <li><a href="#lrc-note">Special note on LEFT, RIGHT and CENTER</a></li>
2123     <li><a href="#include">Including (sourcing) style sheets and files</a></li>
2124     <li><a href="#color">Initializing colors</a></li>
2125   </ul></li>
2126   <li><a href="#doc-lead-adjust">DOC_LEAD_ADJUST</a> &ndash; adjust linespacing to fill pages and align bottom margins</li>
2127   <li><a href="#docheader">DOCHEADER</a>
2128   <ul class="sublist" style="line-height: 120%;">
2129     <li><a href="#docheader-control">Docheader control</a></li>
2130   </ul></li>
2131   <li><a href="#columns">COLUMNS</a>
2132   <ul class="sublist" style="line-height: 120%;">
2133     <li><a href="#col-next">COL_NEXT</a></li>
2134     <li><a href="#col-break">COL_BREAK</a></li>
2135   </ul></li>
2136 </ul>
2137 </div>
2138
2139 <h3 id="type-before-start" class="docs">Behaviour of the typesetting macros before START</h3>
2140
2141 <p>
2142 From time to time (or maybe frequently), you&#8217;ll want the
2143 overall look of a document to differ from mom&#8217;s defaults.
2144 Perhaps you&#8217;d like her to use a different
2145 <a href="definitions.html#family">family</a>,
2146 or a different overall
2147 <a href="definitions.html#leading">leading</a>,
2148 or have different left and/or right page margins.
2149 </p>
2150
2151 <p>
2152 To accomplish such alterations, use the appropriate
2153 <a href="typesetting.html#macros-typesetting">typesetting macros</a>
2154 (listed below) after
2155 <a href="#printstyle">PRINTSTYLE</a>
2156 and before
2157 <a href="#start">START</a>.
2158 </p>
2159
2160 <p>
2161 More than one user has, quite understandably, not fully grasped the
2162 significance of the preceding sentence.  The part they&#8217;ve missed is
2163 <i>after</i> PRINTSTYLE.
2164 </p>
2165
2166 <p>
2167 Changes to any aspect of the default look and/or formatting of a mom
2168 document must come after PRINTSTYLE.  For example, it might seem
2169 natural to set up page margins at the very top of a document with
2170 <br/>
2171 <span class="pre-in-pp">
2172   .L_MARGIN 1i
2173   .R_MARGIN 1.5i
2174 </span>
2175 However, when you invoke <kbd>.PRINTSTYLE</kbd>, those margins
2176 will be overridden.  The correct place to set margins&mdash;and
2177 all other changes to the look of a document&mdash;is <i>after</i>
2178 PRINTSTYLE.
2179 </p>
2180
2181 <div class="box-tip">
2182 <p class="tip">
2183 <span class="important">Important:</span>
2184 Do not use the macros listed in
2185 <a href="#doc-param-macros">Changing document-wide typesetting parameters after START</a>
2186 prior to START; they are exclusively for use afterwards.
2187 </p>
2188 </div>
2189
2190 <div id="meanings" class="defaults-container">
2191 <h3 class="docs defaults" style="margin-top: 0;">Meanings</h3>
2192 <p style="margin-left: 9px; margin-top: -.25em;">
2193 When used before START, the
2194 <a href="typesetting.html#macros-typesetting">typesetting macros</a>,
2195 below have the following meanings:
2196 <br/>
2197 <span class="pre">
2198   L_MARGIN       Left margin of pages, including headers/footers
2199   R_MARGIN       Right margin of pages, including headers/footers
2200   T_MARGIN       The point at which running text (ie not
2201                  headers/footers or page numbers) starts on each
2202                  page
2203   B_MARGIN*      The point at which running text (ie not
2204   (see note)     headers/footers or page numbers) ends on each page
2205
2206   PAGE           If you use PAGE, its final four arguments have the
2207                  same meaning as L_ R_ T_ and B_MARGIN (above).
2208
2209   LL             The line length for everything on the page;
2210                  equivalent to setting the right margin with
2211                  R_MARGIN
2212   FAMILY         The family of all type in the document
2213   PT_SIZE        The point size of type in paragraphs; mom uses
2214                  this to calculate automatic point size changes
2215                  (eg for heads, footnotes, quotes, headers, etc)
2216   LS/AUTOLEAD**  The leading used in paragraphs; all leading and
2217                  spacing of running text is calculated from this
2218
2219   QUAD/JUSTIFY   Affects paragraphs only
2220   LEFT***        No effect
2221   RIGHT***       No effect
2222   CENTER***      No effect
2223
2224 ------
2225   *See <a href="headfootpage.html#footer-margin">FOOTER MARGIN AND BOTTOM MARGIN</a> for an important warning
2226  **See <kbd><a href="#doc-lead-adjust">DOC_LEAD_ADJUST</a></kbd>
2227 ***See <a href="#lrc-note">Special note</a>
2228 </span>
2229 </p>
2230 </div>
2231
2232 <p style="margin-top: -.75em;">
2233 Other macros that deal with type style, or refinements thereof
2234 (<b>KERN, LIGATURES, HY, WS, SS,</b> etc.), behave normally.
2235 It is not recommended that you set up tabs or indents prior to
2236 START.
2237 </p>
2238
2239 <p>
2240 If you want to change any of the basic parameters (above)
2241 <i>after</i> START and have them affect a document globally (as if
2242 you&#8217;d entered them <i>before</i> START), you must use the macros
2243 listed in
2244 <a href="#doc-param-macros">Changing document-wide style parameters after START</a>.
2245 </p>
2246
2247 <h4 id="lrc-note" class="docs">Special note on LEFT, RIGHT and CENTER prior to START</h4>
2248
2249 <p>
2250 In a word, these three macros have no effect on document processing
2251 when invoked prior to START.
2252 </p>
2253
2254 <p>
2255 All mom&#8217;s document element tags (PP, HEAD, BLOCKQUOTE,
2256 FOOTNOTE, etc.) except
2257 <a href="docelement.html#quote">QUOTE</a>
2258 set a
2259 <a href="definitions.html#filled">fill mode</a>
2260 as soon as they&#8217;re invoked.  If you wish to turn fill mode off
2261 for the duration of any tag (with
2262 <a href="typesetting.html#lrc">LEFT, RIGHT or CENTER</a>)
2263 you must do so immediately after invoking the tag.  Furthermore,
2264 the change affects <i>only</i> the current invocation of the tag.
2265 Subsequent invocations of the same tag for which you want the same
2266 change require that you invoke <kbd>.LEFT</kbd>, <kbd>.RIGHT</kbd>
2267 or <kbd>.CENTER</kbd> immediately after every invocation of the tag.
2268 </p>
2269
2270 <!-- -INCLUDE- -->
2271
2272 <h4 id="include" class="docs">Including (sourcing) style sheets and files</h4>
2273
2274 <p>
2275 If you routinely make the same changes to mom&#8217;s defaults in
2276 order to create similar documents in a similar style&mdash;in other
2277 words, you need a template&mdash; you can create style-sheet files
2278 and include, or "source", them into your mom documents with the
2279 macro, INCLUDE.  The right place for such style sheets is after
2280 <a href="#printstyle">PRINTSTYLE</a>
2281 and before
2282 <a href="#start">START</a>.
2283 </p>
2284
2285 <p>
2286 Say, for example, in a particular kind of document, you always
2287 want main heads set in Helvetica Bold Italic, flush left,
2288 with no underscore.  You&#8217;d create a file, let&#8217;s call it
2289 <kbd>head-template</kbd>, in which you&#8217;d place the pertinent HEAD
2290 control macros.
2291 <br/>
2292 <span class="pre-in-pp">
2293   .HEADING_STYLE 1 \
2294   FAMILY    H \
2295   FONT      BI \
2296   QUAD      L \
2297   NO_UNDERSCORE
2298 </span>
2299 Then, in the preliminary document set-up section of your main file,
2300 you&#8217;d include the style sheet, or template, like this:
2301 <br/>
2302 <span class="pre-in-pp">
2303   .TITLE      "Sample Document
2304   .AUTHOR     "Joe Blow
2305   .PRINTSTYLE TYPESET
2306   \#
2307   .INCLUDE    head-template
2308   \#
2309   .START
2310 </span>
2311
2312 The blank comment lines ( <kbd>\#</kbd> ) aren&#8217;t required, but
2313 they do make your file(s) easier to read.
2314 </p>
2315
2316 <p>
2317 If the file to be included is in the same directory as the file
2318 you&#8217;re working, you simply enter the filename after
2319 <kbd>.INCLUDE</kbd>.  If the file&#8217;s in another directory, you must
2320 provide a full path name to it.  For example, if you&#8217;re working in
2321 a directory called <kbd>/home/joe/stories</kbd> and your
2322 style-sheet is in <kbd>/home/joe/style-sheets</kbd>, the above
2323 example would have to look like this:
2324 <br/>
2325 <span class="pre-in-pp">
2326   .TITLE      "Sample Document
2327   .AUTHOR     "Joe Blow
2328   .PRINTSTYLE TYPESET
2329   \#
2330   .INCLUDE    /home/joe/style-sheets/head-template
2331   \#
2332   .START
2333 </span>
2334 </p>
2335
2336 <p>
2337 INCLUDE is not restricted to style sheets or templates.  You can
2338 include any file at any point into a document, provided the file
2339 contains only text and valid groff or mom formatting commands.
2340 Neither is INCLUDE restricted to use with mom&#8217;s document
2341 processing macros.  You can use it in plain typeset documents as
2342 well.
2343 </p>
2344
2345 <div class="box-tip">
2346 <p class="tip">
2347 <span class="experts">Experts:</span>
2348 INCLUDE is an alias for the groff request, <kbd>.so</kbd>.  Mix 'n'
2349 match with impunity.
2350 </p>
2351 </div>
2352
2353 <!-- -COLOUR- -->
2354
2355 <h4 id="color" class="docs">Initializing colours</h4>
2356
2357 <p>
2358 Although it doesn&#8217;t really matter where you define/initialize
2359 colours for use in document processing (see
2360 <a href="color.html#newcolor">NEWCOLOR</a>
2361 and
2362 <a href="color.html#xcolor">XCOLOR</a>
2363 in the section
2364 <a href="color.html#color-intro">Coloured text</a>),
2365 I recommend doing so before you begin document processing with
2366 <kbd><a href="#start">START</a></kbd>.
2367 </p>
2368
2369 <p>
2370 The macro,
2371 <a href="color.html#color">COLOR</a>,
2372 and the
2373 <a href="definitions.html#inlines">inline escape</a>,
2374 <a href="color.html#color-inline"><kbd>\[&lt;colorname&gt;]</kbd></a>,
2375 can be used at any time during document processing for occasional
2376 colour effects.  However, consistent and reliable colourizing of
2377 various document elements (the docheader, heads, linebreaks,
2378 footnotes, pagenumbers, and so on) must be managed through the use
2379 of the
2380 <a href="docelement.html#docelement-control">document element control macros</a>.
2381 </p>
2382
2383 <div class="box-tip">
2384 <p class="tip">
2385 <span class="note">Note:</span>
2386 If you plan to have mom generate a
2387 <a href="docelement.html#toc">table of contents</a>,
2388 do not embed colour
2389 <a href="definitions.html#inlines">inline escapes</a>
2390 (<a href="color.html#color-inline"><kbd>\[&lt;colorname&gt;]</kbd></a>)
2391 in the
2392 <a href="definitions.html#stringargument">string arguments</a>
2393 given to any of the
2394 <a href="docprocessing.html#reference-macros">reference macros</a>,
2395 nor in the string arguments given to
2396 <a href="docelement.html#head">HEAD</a>,
2397 <a href="docelement.html#subhead">SUBHEAD</a>
2398 or
2399 <a href="docelement.html#parahead">PARAHEAD</a>.
2400 Use, rather, the
2401 <a href="definitions.html#controlmacro">control macros</a>
2402 mom provides to automatically colourize these
2403 elements.
2404 </p>
2405 </div>
2406
2407 <!-- -DOC LEAD ADJUST- -->
2408
2409 <div class="macro-id-overline">
2410 <h3 id="doc-lead-adjust" class="macro-id">Adjust linespacing to fill pages and align bottom margins</h3>
2411 </div>
2412
2413 <div class="box-macro-args">
2414 Macro: <b>DOC_LEAD_ADJUST</b> <kbd class="macro-args">toggle</kbd>
2415 </div>
2416
2417 <p class="requires">
2418 &bull;&nbsp;Must come after
2419 <a href="typesetting.html#ls"><span class="normal">LS</span></a>
2420 or
2421 <a href="typesetting.html.#autoloead"><span class="normal">AUTOLEAD</span></a>
2422 and before
2423 <a href="#start"><span class="normal">START</span></a>
2424 </p>
2425
2426 <p>
2427 DOC_LEAD_ADJUST is a special macro to adjust document
2428 <a href="definitions.html#leading">leading</a>
2429 so that bottom margins fall precisely where you expect.
2430 </p>
2431
2432 <p>
2433 When you invoke <kbd>.DOC_LEAD_ADJUST</kbd>, mom takes the number
2434 of lines that fit on the page at your requested leading, then
2435 incrementally adds
2436 <a href="definitions.html#units">machine units</a>
2437 to the leading until the maximum number of lines at the new leading
2438 that fit on the page coincides perfectly with the bottom margin of
2439 <a href="definitions.html#running">running text</a>.
2440 </p>
2441
2442 <p>
2443 In most instances, the difference between the requested lead and
2444 the adjusted lead is unnoticeable, and since in almost all cases
2445 adjusted leading is what you want, it&#8217;s mom&#8217;s default
2446 and you don't have to invoke it explicitly.
2447 </p>
2448
2449 <p>
2450 However, should you not want adjusted document leading, you must
2451 turn it off manually, like this:
2452 <br/>
2453 <span class="pre">
2454   .DOC_LEAD_ADJUST OFF
2455 </span>
2456 </p>
2457
2458 <p>
2459 If you set the document leading prior to START with
2460 <a href="typesetting.html#leading">LS</a>
2461 or
2462 <a href="typesetting.html#autolead">AUTOLEAD</a>,
2463 DOC_LEAD_ADJUST&nbsp;<kbd>OFF</kbd> must come afterwards, like
2464 this:
2465 <br/>
2466 <span class="pre-in-pp">
2467   .LS 12
2468   .DOC_LEAD_ADJUST OFF
2469 </span>
2470 In this scenario, the maximum number of lines that fit on a page at
2471 a
2472 <a href="definitions.html#leading">leading</a>
2473 of 12
2474 <a href="definitions.html#picaspoints">points</a>
2475 determine where mom ends a page.  The effect will be that last lines
2476 usually fall (slightly) short of the &#8220;official&#8221; bottom
2477 margin.
2478 </p>
2479
2480 <p>
2481 In
2482 <a href="docprocessing.html#printstyle">PRINTSTYLE</a>&nbsp;<kbd>TYPEWRITE</kbd>,
2483 the leading is always adjusted and can&#8217;t be turned off.
2484 </p>
2485
2486 <div class="box-tip">
2487 <p class="tip-top">
2488 <span class="note">Note:</span>
2489 DOC_LEAD_ADJUST, if used, must be invoked after
2490 <a href="typesetting.html#leading">LS</a>
2491 or
2492 <a href="typesetting.html#autolead">AUTOLEAD</a>
2493 and before
2494 <a href="#start">START</a>.
2495 </p>
2496
2497 <p class="tip-bottom">
2498 <span class="additional-note">Additional note:</span>
2499 Even if you disable DOC_LEAD_ADJUST, mom will still adjust the
2500 leading of endnotes pages and toc pages.  See
2501 <a href="docelement.html#endnote-lead">ENDNOTE_LEAD</a>
2502 and
2503 <a href="docelement.html#toc-lead">TOC_LEAD</a>
2504 for an explanation of how to disable this default behaviour.
2505 </p>
2506 </div>
2507
2508 <!-- -DOCHEADER- -->
2509
2510 <div class="macro-id-overline">
2511 <h3 id="docheader" class="macro-id">Managing the docheader</h3>
2512 </div>
2513
2514 <div class="box-macro-args">
2515 Macro: <b>DOCHEADER</b> <kbd class="macro-args">&lt;toggle&gt; [ distance to advance from top of page ]</kbd>
2516 </div>
2517
2518 <p class="requires">
2519 &bull;&nbsp;Must come before
2520 <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>
2521 </p>
2522
2523 <p>
2524 By default, mom prints a
2525 <a href="definitions.html#docheader">docheader</a>
2526 on the first page of any document (see
2527 <a href="#docheader-desc">below</a>
2528 for a description of the docheader).  If you don&#8217;t want a docheader,
2529 turn it off with
2530 <br/>
2531 <span class="pre-in-pp">
2532   .DOCHEADER OFF
2533 </span>
2534 DOCHEADER is a toggle macro, so the argument doesn&#8217;t
2535 have to be OFF; it can be anything you like.
2536 </p>
2537
2538 <p>
2539 If you turn the docheader off, mom, by default, starts
2540 the running text of your document on the same top
2541 <a href="definitions.html#baseline">baseline</a>
2542 as all subsequent pages.  If you&#8217;d like her to start at a different
2543 vertical position, give her the distance you&#8217;d like as a second
2544 argument.
2545 <br/>
2546 <span class="pre-in-pp">
2547   .DOCHEADER OFF 1.5i
2548 </span>
2549 This starts the document 1.5 inches from the top of the page PLUS
2550 whatever spacing adjustment mom has to make in order to ensure that
2551 the first baseline of running text falls on a &#8220;valid&#8221;
2552 baseline (ie one that ensures that the bottom margin of the first
2553 page falls where it should).  The distance is measured from the top
2554 edge of the paper to the
2555 <a href="definitions.html#baseline">baseline</a>
2556 of the first line of type.
2557 </p>
2558
2559 <div class="box-tip">
2560 <p class="tip">
2561 <span class="tip">Tip:</span>
2562 Since no document processing happens until you invoke
2563 <a href="#start"><kbd>.START</kbd></a>&mdash;including
2564 anything to do with docheaders&mdash;you can
2565 typeset your own docheader prior to START (if
2566 you don&#8217;t like the way mom does things) and use
2567 <kbd>.DOCHEADER&nbsp;OFF</kbd> with its optional distance
2568 argument to ensure that the body of your document starts where
2569 you want.  You can even insert a PDF or PostScript image file (see
2570 <a href="images.html#pspic">PSPIC</a>).
2571 and
2572 <a href="images.html#pdf-image">PDF_IMAGE</a>).
2573 </p>
2574 </div>
2575
2576 <!-- DOCHEADER CONTROL -->
2577
2578 <h3 id="docheader-control" class="docs">Docheader control: How to change the look of docheaders</h3>
2579
2580 <p>
2581 In
2582 <a href="#printstyle">PRINTSTYLE <kbd>TYPEWRITE</kbd></a>,
2583 the look of docheaders is carved in stone.  In
2584 <a href="#printstyle">PRINTSTYLE <kbd>TYPESET</kbd></a>,
2585 however, you can make a lot of changes.  Macros that alter
2586 docheaders must come before
2587 <a href="#start">START</a>.
2588 </p>
2589
2590 <h4 id="docheader-desc" class="docs">Docheader description</h4>
2591
2592 <p>
2593 A typeset docheader has the following characteristics:
2594 </p>
2595 <div class="box-code" style="margin-left: 24px;">
2596 <span class="pre" style="color: #302419;">
2597     TITLE       bold, 3.5 points larger than running text (not necessarily caps)
2598    Subtitle     medium, same size as running text
2599       by        medium italic, same size as running text
2600    Author(s)    medium italic, same size as running text
2601
2602 (Document type) bold italic, underscored, 3 points larger than running text
2603
2604 </span>
2605 </div>
2606
2607 <p>
2608 Or, if the
2609 <a href="#doctype">DOCTYPE</a>
2610 is <kbd>CHAPTER</kbd>,
2611 </p>
2612 <div class="box-code" style="margin-left: 24px;">
2613 <span class="pre" style="color: #302419;">
2614  Chapter &lt;n&gt;   bold, 4 points larger than running text
2615 Chapter Title  bold italic, 4 points larger than running text
2616
2617 </span>
2618 </div>
2619
2620 <p>
2621 The
2622 <a href="definitions.html#family">family</a>
2623 is the prevailing family of the whole document.  Title, subtitle,
2624 author and document type are what you supply with the
2625 <a href="#reference-macros">reference macros</a>.
2626 Any you leave out will not appear; mom will compensate:
2627
2628 </p>
2629
2630 <div class="box-tip">
2631 <p class="tip">
2632 <span class="note">Note:</span>
2633 If your DOCTYPE is <kbd>CHAPTER</kbd> and you have both &#8220;Chapter
2634 &lt;n&gt;&#8221; and a &#8220;Chapter Title&#8221; (as above), mom
2635 inserts a small amount of whitespace between them, equal to
2636 one-quarter of the <a href="definitions.html#leading">leading</a> in
2637 effect.  If this doesn&#8217;t suit you, you can alter the space by
2638 including the
2639 <a href="definitions.html#inlines">inline escapes</a>,
2640 <a href="inlines.html#up"><kbd>\*[UP]</kbd></a>
2641 or
2642 <a href="inlines.html#down"><kbd>\*[DOWN]</kbd></a>,
2643 in the argument you pass to
2644 <a href="#chapter-title">CHAPTER_TITLE</a>,
2645 like this:
2646 <br/>
2647 <span class="pre-in-pp" style="margin-bottom: -1em;">
2648   .CHAPTER_TITLE "\*[DOWN 2p]Why Not Patent Calculus?"
2649 </span>
2650 or
2651 <span class="pre-in-pp" style="margin-top: -.5em;">
2652   .CHAPTER_TITLE "\*[UP 2p]Why Not Patent Calculus?"
2653 </span>
2654 </p>
2655 </div>
2656
2657 <div class="macro-list-container">
2658 <h3 id="index-docheader-control" class="macro-list">Docheader control</h3>
2659 <ol class="macro-list">
2660   <li><a href="#change-start">Change the starting position of the docheader</a></li>
2661   <li><a href="#docheader-quad">Change quad direction the entire docheader</a></li>
2662   <li><a href="#docheader-family">Change the family of the entire docheader</a></li>
2663   <li><a href="#change-family">Change the family of individual docheader elements</a></li>
2664   <li><a href="#change-font">Change the font of individual docheader elements</a></li>
2665   <li><a href="#change-size">Adjust the size of docheader elements</a></li>
2666   <li><a href="#adjust-leading">Adjust the docheader leading</a></li>
2667   <li><a href="#docheader-color">Change the colour of the entire docheader</a></li>
2668   <li><a href="#change-color">Change the colour of the individual docheader elements</a></li>
2669   <li><a href="#change-attribute">Change the attribution string (&#8220;by&#8221;)</a></li>
2670 </ol>
2671 </div>
2672
2673 <h4 id="change-start" class="docs">1. Change the starting position of the docheader</h4>
2674
2675 <p>
2676 By default, a docheader starts on the same
2677 <a href="definitions.html#baseline">baseline</a>
2678 as
2679 <a href="definitions.html#running">running text</a>.
2680 If you&#8217;d like it to start somewhere else, use the macro,
2681 DOCHEADER_ADVANCE, and give it the distance you want (measured from
2682 the top edge of the paper to the first baseline of the docheader),
2683 like this:
2684 <br/>
2685 <span class="pre-in-pp">
2686     .DOCHEADER_ADVANCE 4P
2687 </span>
2688 A
2689 <a href="definitions.html#unitofmeasure">unit of measure</a>
2690 is required.
2691 </p>
2692
2693 <div class="box-tip">
2694 <p class="tip">
2695 <span class="note">Note:</span>
2696 If
2697 <a href="headfootpage.html#headers">HEADERS</a>
2698 are <kbd>OFF</kbd>, mom&#8217;s normal top margin for
2699 <a href="definitions.html#running">running text</a>
2700 (7.5
2701 <a href="definitions.html#picaspoints">picas</a>)
2702 changes to 6 picas (visually approx. 1 inch).  Since the first
2703 baseline of the docheader falls on the same baseline as the first
2704 line of running text (on pages after page 1), you might find the
2705 docheaders a bit high when headers are off.  Use DOCHEADER_ADVANCE
2706 to place them where you want.
2707 </p>
2708 </div>
2709
2710 <h4 id="docheader-quad" class="docs">2. Change the quad direction of the docheader</h4>
2711
2712 <p>
2713 By default, mom centers the docheader.  If you&#8217;d prefer to
2714 have your docheaders set flush left or right, or need to restore
2715 the default centering, invoke <kbd>.DOCHEADER_QUAD</kbd> with the
2716 quad direction you want, either <kbd>LEFT</kbd> (or <kbd>L</kbd>),
2717 <kbd>RIGHT</kbd> (or <kbd>R</kbd>) or <kbd>CENTER</kbd> (or
2718 <kbd>C</kbd>).
2719 </p>
2720
2721 <h4 id="docheader-family" class="docs">3. Change the family of the entire docheader</h4>
2722
2723 <p>
2724 By default, mom sets the docheader in the same
2725 family used for
2726 <a href="definitions.html#running">running text</a>.
2727 If you&#8217;d prefer to have your docheaders set in a different
2728 family, invoke <kbd>.DOCHEADER_FAMILY</kbd> with the family you
2729 want.  The argument to DOCHEADER_FAMILY is the same as for
2730 <a href="typesetting.html#family">FAMILY</a>.
2731 </p>
2732
2733 <p>
2734 For example, mom&#8217;s default family for running text is Times
2735 Roman.  If you&#8217;d like to keep that default, but have the
2736 docheaders set entirely in Helvetica,
2737 <br/>
2738 <span class="pre-in-pp">
2739   .DOCHEADER_FAMILY H
2740 </span>
2741 is how you&#8217;d do it.
2742 </p>
2743
2744 <p>
2745 Please note that if you use DOCHEADER_FAMILY, you can still alter
2746 the family of individual parts of the docheader with the macros
2747 listed
2748 <a href="#change-family">here</a>.
2749 </p>
2750
2751 <h4 id="change-family" class="docs">4. Change the family of individual docheader elements</h4>
2752
2753 <p>
2754 The following macros let you change the
2755 <a href="definitions.html#family">family</a>
2756 of each docheader element separately:
2757 </p>
2758 <ul style="list-style-type: none; margin: -.5em;">
2759   <li>Macro: <b>TITLE_FAMILY</b> <kbd class="macro-args">&lt;family&gt;</kbd></li>
2760   <li>Macro: <b>CHAPTER_TITLE_FAMILY</b> <kbd class="macro-args">&lt;family&gt;</kbd></li>
2761   <li>Macro: <b>SUBTITLE_FAMILY</b> <kbd class="macro-args">&lt;family&gt;</kbd></li>
2762   <li>Macro: <b>AUTHOR_FAMILY</b> <kbd class="macro-args">&lt;family&gt;</kbd></li>
2763   <li>Macro: <b>DOCTYPE_FAMILY</b> <kbd class="macro-args">&lt;family&gt;</kbd>
2764       (if <a href="#doctype">DOCTYPE</a> is <kbd>NAMED</kbd>)
2765   </li>
2766 </ul>
2767
2768 <p>
2769 Simply pass the appropriate macro the family you want, just as you
2770 would with
2771 <a href="typesetting.html#family">FAMILY</a>.
2772 </p>
2773
2774 <h4 id="change-font" class="docs">5. Change the font of individual docheader elements</h4>
2775
2776 <p>
2777 The following macros let you change the
2778 <a href="definitions.html#font">font</a>
2779 of each docheader element separately:
2780 </p>
2781 <ul style="list-style-type: none; margin: -.5em;">
2782   <li>Macro: <b>TITLE_FONT</b> <kbd class="macro-args">R | B | I | BI</kbd></li>
2783   <li>Macro: <b>CHAPTER_TITLE_FONT</b> <kbd class="macro-args">R | B | I | BI</kbd></li>
2784   <li>Macro: <b>SUBTITLE_FONT</b> <kbd class="macro-args">R | B | I | BI</kbd></li>
2785   <li>Macro: <b>AUTHOR_FONT</b> <kbd class="macro-args">R | B | I | BI</kbd></li>
2786   <li>Macro: <b>DOCTYPE_FONT</b> <kbd class="macro-args">R | B | I | BI</kbd>
2787       (if <a href="#doctype">DOCTYPE</a> is <kbd>NAMED</kbd>)
2788   </li>
2789 </ul>
2790
2791 <p>
2792 Simply pass the appropriate macro the font you want. <kbd>R, B,
2793 I</kbd> and <kbd>BI</kbd> have the same meaning as they do for
2794 <a href="typesetting.html#font">FT</a>.  You may also use any of the
2795 <a href="appendices.html#style-extensions">style extensions</a>
2796 provided by mom.
2797 </p>
2798
2799 <h4 id="change-size" class="docs">6. Adjust the size of individual docheader elements</h4>
2800
2801 <p>
2802 The following macros let you adjust the point size of each docheader
2803 element separately.
2804 </p>
2805
2806 <p>
2807 Mom calculates the point size of docheader elements from the point
2808 size of paragraphs in running text, so you must prepend a + or -
2809 sign to the argument.  Points is assumed as the
2810 <a href="definitions.html#unitofmeasure">unit of measure</a>,
2811 so there&#8217;s no need to append a unit to the argument.
2812 Fractional point sizes are allowed.
2813 </p>
2814
2815 <ul style="list-style-type: none; margin: -.5em;">
2816   <li>Macro: <b>TITLE_SIZE</b> <kbd class="macro-args">&lt;+/-points&gt;</kbd>
2817       <br/>
2818       &nbsp;&nbsp;&nbsp;default = +3.5 (+4 if docheader title is &quot;Chapter &lt;n&gt;&quot;)
2819   </li>
2820   <li>Macro: <b>CHAPTER_TITLE_SIZE</b> <kbd class="macro-args">&lt;+/-points&gt;</kbd>
2821       <br/>
2822       &nbsp;&nbsp;&nbsp;default = +4
2823   </li>
2824   <li>Macro: <b>SUBTITLE_SIZE</b> <kbd class="macro-args">&lt;+/-points&gt;</kbd>
2825       <br/>
2826       &nbsp;&nbsp;&nbsp;default = +0
2827   </li>
2828   <li>Macro: <b>AUTHOR_SIZE</b> <kbd class="macro-args">&lt;+/-points&gt;</kbd>
2829       <br/>
2830       &nbsp;&nbsp;&nbsp;default = +0
2831   </li>
2832   <li>Macro: <b>DOCTYPE_SIZE</b> <kbd class="macro-args">&lt;+/-points&gt;</kbd>
2833       (if <a href="#doctype">DOCTYPE</a> is <kbd>NAMED</kbd>)
2834       <br/>
2835       &nbsp;&nbsp;&nbsp;default = +3
2836   </li>
2837 </ul>
2838
2839 <p>
2840 Simply pass the appropriate macro the size adjustment you want.
2841 </p>
2842
2843 <h4 id="adjust-leading" class="docs">7. Adjust the docheader leading</h4>
2844
2845 <p>
2846 The
2847 <a href="definitions.html#leading">leading</a>
2848 of docheaders is the same as running text.  If you&#8217;d like your
2849 docheaders to have a different leading, say, 2 points more than the
2850 lead of running text, use:
2851 <br/>
2852 <span class="pre-in-pp">
2853   .DOCHEADER_LEAD +2
2854 </span>
2855 Since the leading of docheaders is calculated from the lead of running
2856 text, a + or - sign is required before the argument (how much to add
2857 or subtract from the lead of running text).  No
2858 <a href="definitions.html#unitofmeasure">unit of measure</a>
2859 is required; points is assumed.
2860 </p>
2861
2862 <h4 id="docheader-color" class="docs">8. Change the colour of the entire docheader</h4>
2863
2864 <p>
2865 If you want to colourize the entire docheader:
2866 <br/>
2867 <span class="pre-in-pp">
2868   .DOCHEADER_COLOR <kbd class="macro-args">&lt;color name&gt;</kbd>
2869 </span>
2870 You must pre-define (or &#8220;initialize&#8221;) the colour with
2871 <a href="color.html#newcolor">NEWCOLOR</a>
2872 or
2873 <a href="color.html#xcolor">XCOLOR</a>.
2874 </p>
2875
2876
2877 <h4 id="change-color" class="docs">9. Change the colour of the docheader elements individually</h4>
2878
2879 <p>
2880 The following macros let you change the colour of each
2881 docheader element separately.  You must pre-define (or
2882 &#8220;initialize&#8221;) the colour with
2883 <a href="color.html#newcolor">NEWCOLOR</a>
2884 or
2885 <a href="color.html#xcolor">XCOLOR</a>.
2886 </p>
2887 <ul style="list-style-type: none; margin: -.5em;">
2888   <li>Macro: <b>TITLE_COLOR</b> <kbd class="macro-args">&lt;colorname&gt;</kbd></li>
2889   <li>Macro: <b>CHAPTER_TITLE_COLOR</b> <kbd class="macro-args">&lt;colorname&gt;</kbd>
2890   <ul style="list-style-type: disc; margin-left: -.5em;">
2891     <li>Note: <b>CHAPTER_TITLE_COLOR</b> is needed only if you supply both a
2892         <a href="#chapter">CHAPTER</a>
2893         reference macro and a
2894         <a href="#chapter-title">CHAPTER_TITLE</a>
2895         macro.  Otherwise, TITLE_COLOR takes care of colorizing the
2896         chapter header.
2897     </li>
2898   </ul></li>
2899   <li>Macro: <b>SUBTITLE_COLOR</b> <kbd class="macro-args">&lt;colorname&gt;</kbd></li>
2900   <li>Macro: <b>ATTRIBUTE_COLOR</b> <kbd class="macro-args">&lt;colorname&gt;</kbd>
2901       (the &#8220;by&#8221; string preceding author[s] name[s])
2902   </li>
2903   <li>Macro: <b>AUTHOR_COLOR</b> <kbd class="macro-args">&lt;colorname&gt;</kbd></li>
2904   <li>Macro: <b>DOCTYPE_COLOR</b> <kbd class="macro-args"> &lt;colorname&gt;</kbd>
2905       (if <a href="#doctype">DOCTYPE</a> is <kbd>NAMED</kbd>)
2906   </li>
2907 </ul>
2908
2909 <p>
2910 It is not recommended that you embed colour (with the
2911 <a href="definitions.html#inlines">inline escape</a>,
2912 <a href="color.html#color-inline"><kbd>\*[&lt;colorname&gt;]</kbd></a>)
2913 in the strings passed to TITLE, CHAPTER_TITLE, SUBTITLE, AUTHOR or
2914 the name you give DOCTYPE <kbd>NAMED</kbd>.  The strings passed to
2915 these macros are used to generate page
2916 <a href="definitions.html#header">headers</a>
2917 and
2918 <a href="definitions.html#footer">footers</a>,
2919 with the result that an embedded colour will cause the string to be
2920 colourized in headers and/or footers as well.  (If you want headers
2921 or footers colourized, or parts thereof, use the header/footer
2922 control macros.)
2923 </p>
2924
2925 <h4 id="change-attribute" class="docs">10. Change the attribution string (&#8220;by&#8221;)</h4>
2926
2927 <p>
2928 If you&#8217;re not writing in English, you can change what mom
2929 prints where &#8220;by&#8221; appears in docheaders.  For example,
2930 <br/>
2931 <span class="pre-in-pp">
2932   .ATTRIBUTE_STRING "par"
2933 </span>
2934 changes &#8220;by&#8221; to &#8220;par&#8221;.  ATTRIBUTE_STRING
2935 can also be used, for example, to make the attribution read
2936 &quot;Edited by&quot;.
2937 </p>
2938
2939 <p>
2940 If you don&#8217;t want an attribution string at all, simply pass
2941 ATTRIBUTE_STRING an empty argument, like this:
2942 <br/>
2943 <span class="pre-in-pp">
2944   .ATTRIBUTE_STRING ""
2945 </span>
2946 Mom will deposit a blank line where the attribution string normally
2947 appears.
2948 </p>
2949
2950 <p>
2951 If the optional argument, <kbd>COVER</kbd> or <kbd>DOC_COVER</kbd>,
2952 is given to ATTRIBUTE_STRING, the string argument represents the
2953 attribution string that will appear on cover or document cover pages
2954 (see the
2955 <a href="cover.html#cover-intro">Introduction to cover pages</a>
2956 for a description of the difference between &#8220;document
2957 covers&#8221; and &#8220;covers&#8221;).  Thus, it is possible to
2958 have different attribution strings on the document cover page, the
2959 cover (&#8220;title&#8221;) page, and in the first-page docheader.
2960 An extreme example would be:
2961 <br/>
2962 <span class="pre-in-pp">
2963   .ATTRIBUTE_STRING ""
2964   .ATTRIBUTE_STRING DOC_COVER "Edited by"
2965   .ATTRIBUTE_STRING COVER "by"
2966 </span>
2967 The first invocation of <kbd>.ATTRIBUTE_STRING</kbd> establishes a
2968 blank attribution string that will be incorporated in the first-page
2969 docheader.  The second will print &#8220;Edited by&#8221; on the
2970 document cover; the third will print &#8220;by&#8221; on the cover
2971 (&#8220;title&#8221;) page.
2972 </p>
2973
2974 <p>
2975 If you don&#8217;t require differing attribute strings for
2976 doc cover pages, cover pages, or the first-page docheader,
2977 <kbd>.ATTRIBUTE_STRING</kbd>, without either of the optional first
2978 arguments, is sufficient.
2979 </p>
2980
2981 <div class="box-tip">
2982 <p class="tip">
2983 <span class="note">Note:</span>
2984 The type specs for the attribution line in docheaders are the
2985 same as for the author line.  Although it&#8217;s highly unlikely
2986 you&#8217;ll want the attribution line in a different family, font,
2987 or point size, you can make such changes using
2988 <a href="definitions.html#inlines">inline escapes</a>
2989 in the argument to ATTRIBUTE_STRING.  For example,
2990 <br/>
2991 <span class="pre-in-pp">
2992   .ATTRIBUTE_STRING "\f[HBI]\*[SIZE -2p] by \*[SIZE +2p]\*[PREV]"
2993 </span>
2994 would set &#8220;by&#8221; in Helvetica bold italic, 2 points
2995 smaller than normal.
2996 </p>
2997 </div>
2998
2999 <div class="rule-short"><hr/></div>
3000
3001 <!-- -COLUMNS- -->
3002
3003 <h2 id="columns-intro" class="docs">Setting documents in columns</h2>
3004
3005 <p>
3006 Setting documents in columns is easy with mom.  All you have to do
3007 is is say how many columns you want and how much space you want
3008 between them (the
3009 <a href="definitions.html#gutter">gutters</a>).
3010 That&#8217;s it. Mom takes care of everything else, from soup to
3011 nuts.
3012 </p>
3013
3014 <h3 class="docs">Some words of advice</h3>
3015
3016 <p>
3017 If you want your type to achieve a pleasing
3018 <a href="definitions.html#just">justification</a>
3019 or
3020 <a href="definitions.html#rag">rag</a>
3021 in columns, reduce the point size of type (and probably the
3022 <a href="definitions.html#leading">leading</a>
3023 as well).  Mom&#8217;s default document point size is 12.5, which
3024 works well across her default 39
3025 <a href="definitions.html#picaspoints">pica</a>
3026 full page line length, but with even just two columns on a page, the
3027 default point size is awkward to work with.
3028 </p>
3029
3030 <p>
3031 Furthermore, you&#8217;ll absolutely need to reduce the indents for
3032 <a href="docelement.html#epigraph-control">epigraphs</a>,
3033 <a href="docelement.html#quote-general">quotes</a>,
3034 and
3035 <a href="docelement.html#blockquote-general">blockquotes</a>
3036 (and probably the
3037 <a href="docelement.html#para-indent">paragraph first-line indent</a>
3038 as well).
3039 </p>
3040
3041 <!-- -COLUMN- -->
3042
3043 <div class="macro-id-overline">
3044 <h3 id="columns" class="macro-id">COLUMNS</h3>
3045 </div>
3046
3047 <div class="box-macro-args">
3048 Macro: <b>COLUMNS</b> <kbd class="macro-args">&lt;number of columns&gt; &lt;width of gutters&gt;</kbd>
3049 </div>
3050
3051 <p class="requires">
3052 &bull;&nbsp;Should be the last macro before START
3053 <br/>
3054
3055 <i>The second argument requires a <a href="definitions.html#unitofmeasure">unit of measure</a></i>
3056 </p>
3057
3058 <p>
3059 COLUMNS takes two arguments: the number of columns you want on
3060 document pages, and the width of the
3061 <a href="definitions.html#gutter">gutter</a>
3062 between them.  For example, to set up a page with two columns
3063 separated by an 18 point gutter, you&#8217;d do
3064 <br/>
3065 <span class="pre-in-pp">
3066   .COLUMNS 2 18p
3067 </span>
3068 Nothing to it, really.  However, as noted above, COLUMNS should
3069 always be the last document setup macro prior to
3070 <a href="#start">START</a>.
3071 </p>
3072
3073 <div class="box-tip">
3074 <p class="tip">
3075 <span class="note">Note:</span>
3076 Mom ignores columns completely when the
3077 <a href="#printstyle">PRINTSTYLE</a>
3078 is <kbd>TYPEWRITE</kbd>.  The notion of typewriter-style
3079 output in columns is just too ghastly for her to bear.
3080 </p>
3081 </div>
3082
3083 <h3 class="docs" id="marking-col-start">Marking the first page column start position</h3>
3084
3085 <p>
3086 If you insert or remove space after the docheader, i.e. immediately after
3087 <a href="#start">START</a>
3088 in your input file, mom needs to know where your first column begins
3089 in order to align subsequent columns on the first page.
3090 </p>
3091
3092 <div id="col-mark" class="box-macro-args">
3093 Macro: <b>COL_MARK</b>
3094 </div>
3095
3096 <p>
3097 <kbd>COL_MARK</kbd> tells mom where the first column after the
3098 docheader begins, in order for the top of subsequent columns on the
3099 first page to be aligned.  Note that if you do not manually add
3100 or remove space after the docheader, there is no need to invoke
3101 <kbd>COL_MARK</kbd>.
3102 </p>
3103
3104 <div class="box-tip">
3105 <p class="tip">
3106 <span class="note">Note:</span>
3107 If you add or subtract space after the docheader, e.g. with
3108 <a href="typesetting.html#ald">ALD</a>
3109 or
3110 <a href="typesetting.html#SP">SP</a>,
3111 and your
3112 <a href="definitions.html#unitofmeasure">unit of measure</a>
3113 is something other than &#8220;<kbd>v</kbd>&#8221;, be sure to follow the spacing
3114 command with
3115 <a href="docprocessing.html#shim"><kbd>.SHIM</kbd></a>
3116 unless shimming has been disabled with
3117 <a href="#disable-shim">NO_SHIM</a>.
3118 </p>
3119 </div>
3120
3121 <h3 class="docs">Using tabs when COLUMNS are enabled</h3>
3122
3123 <p>
3124 Mom&#8217;s tabs (both
3125 <a href="typesetting.html#typesetting-tabs">typesetting tabs</a>
3126 and
3127 <a href="typesetting.html#string-tabs">string tabs</a>)
3128 behave as you&#8217;d expect during document processing, even
3129 when COLUMNS are enabled.  Tab structures set up during document
3130 processing carry over from page to page and column to column.
3131 </p>
3132
3133 <!-- -BREAKING COLUMNS- -->
3134
3135 <h3 id="breaking-columns" class="docs">Breaking columns manually</h3>
3136
3137 <p>
3138 Mom takes care of breaking columns when they reach the bottom
3139 margin of a page.  However, there may be times you want to break
3140 the columns yourself.  There are two macros for breaking columns
3141 manually: COL_NEXT and COL_BREAK.
3142 </p>
3143
3144 <div id="col-next" class="box-macro-args">
3145 Macro: <b>COL_NEXT</b>
3146 </div>
3147
3148 <p>
3149 <kbd>.COL_NEXT</kbd> breaks the line just before it,
3150 <a href="definitions.html#quad">quads</a>
3151 it left (assuming the type is justified or quad left), and moves over
3152 to the top of the next column.  If the column happens to be the last
3153 (rightmost) one on the page, mom starts a new page
3154 at the &quot;column 1&quot; position.  This is the macro to use when
3155 you want to start a new column after the end of a paragraph.
3156 </p>
3157
3158 <div id="col-break" class="box-macro-args">
3159 Macro: <b>COL_BREAK</b>
3160 </div>
3161
3162 <p>
3163 <kbd>.COL_BREAK</kbd> is almost the same as <kbd>.COL_NEXT</kbd>,
3164 except that instead of breaking and quadding the line preceding it,
3165 mom breaks and spreads it (see
3166 <a href="typesetting.html#spread">SPREAD</a>).
3167 Use this macro whenever you need to start a new column in the middle
3168 of a paragraph.
3169 </p>
3170
3171 <div class="box-important">
3172 <p class="tip">
3173 <span class="important">Warning:</span>
3174 If you need COL_BREAK in the middle of a blockquote or (god help
3175 you) an epigraph, you must do the following in order for COL_BREAK
3176 to work:
3177 <br/>
3178 <span class="pre-in-pp">
3179   .SPREAD
3180   \!.COL_BREAK
3181 </span>
3182 </p>
3183 </div>
3184
3185 <div class="rule-short"><hr/></div>
3186
3187 <!-- ======================================================================== -->
3188
3189 <!-- *** -->
3190
3191
3192 <h2 id="style-after-start" class="macro-group">Changing basic type and formatting parameters after START</h2>
3193
3194 <ul id="changing-basic-type">
3195   <li><a href="#behaviour">Behaviour of the typesetting macros during document processing</a>
3196   <ul style="margin-left: -.5em;">
3197     <li><a href="#behaviour-specific">Effect of specific typesetting macros</a></li>
3198   </ul></li>
3199   <li><a href="#tb-margins">Top and bottom margins in document processing</a></li>
3200   <li><a href="#space">Inserting space at the top of a new page</a>
3201   <ul style="margin-left: -.5em;">
3202     <li><a href="#add-space">ADD_SPACE</a></li>
3203   </ul></li>
3204 </ul>
3205
3206 <div class="rule-medium"><hr/></div>
3207
3208 <h3 id="behaviour" class="docs">Behaviour of the typesetting macros during document processing</h3>
3209
3210 <p>
3211 During document processing, most of the
3212 <a href="typesetting.html#macros-typesetting">typesetting macros</a>
3213 affect type in the document globally.  For example, if you turn
3214 kerning off, pairwise kerning is disabled not only in paragraphs,
3215 but also in headers, footers, quotes, and so on.
3216 </p>
3217
3218 <p>
3219 Typesetting macros that alter margins and line lengths affect
3220 <a href="definitions.html#running">running text</a>
3221 globally (or at least try to), but leave headers/footers and
3222 footnotes alone.  (To indent footnotes, see the full explanation of
3223 the
3224 <a href="docelement.html#footnote">FOOTNOTE</a>
3225 macro.)
3226 </p>
3227
3228 <p>
3229 Mom&#8217;s tabs (both
3230 <a href="typesetting.html#typesetting-tabs">typesetting tabs</a>
3231 and
3232 <a href="typesetting.html#string-tabs">string tabs</a>)
3233 behave as expected in running text during document processing.  Tab
3234 structures that do not exceed the line length of running text are
3235 preserved sensibly from page to page, and, if
3236 <a href="docprocessing.html#columns">COLUMNS</a>
3237 are enabled, from column to column.
3238 </p>
3239
3240 <p>
3241 Some typesetting macros, however, when used during document
3242 processing, behave in special ways.  These are the macros that deal
3243 with the basic parameters of type style: horizontal and vertical
3244 margins, line length,
3245 <a href="definitions.html#family">family</a>,
3246 <a href="definitions.html#font">font</a>,
3247 <a href="definitions.html#ps">point size</a>,
3248 <a href="definitions.html#leading">leading</a>,
3249 and
3250 <a href="definitions.html#quad">quad</a>.
3251 </p>
3252
3253 <p>
3254 Mom assumes that any changes to these parameters stem from a
3255 temporary need to set type in a style different from that provided
3256 by mom&#8217;s
3257 <a href="docelement.html#index-docelement">document element tags</a>.
3258 In other words, you need to do a bit of creative typesetting in the
3259 middle of a document.
3260 </p>
3261
3262 <p>
3263 The following lists those typesetting macros whose behaviour during
3264 document processing requires some explanation.
3265 (Please refer to
3266 <a href="#tb-margins">Top and bottom margins in document processing</a>
3267 for information on how mom interprets
3268 <a href="typesetting.html#t-margin">T_MARGIN</a>
3269 and
3270 <a href="typesetting.html#b-margin">B_MARGIN</a>
3271 in document processing.  Additionally, see
3272 <a href="#add-space">ADD_SPACE</a>
3273 if you encounter the problem of trying to get mom to put space at
3274 the tops of pages after the first.)
3275 </p>
3276 <div id="behaviour-specific" class="box-code" style="margin-left: 24px;">
3277 <span class="pre" style="color: #302419;">
3278   MACRO       EFFECT DURING DOCUMENT PROCESSING
3279   -----       ---------------------------------
3280
3281   L_MARGIN    &bull;The left margin of all running text
3282                assumes the new value.
3283
3284               &bull;The line length remains unaltered.
3285
3286               &bull;The header and footer left margin
3287                remain at the current document default.
3288
3289               (You won&#8217;t use this often by itself.  Most
3290                likely, you&#8217;ll use it in combination with
3291                R_MARGIN or LL.)
3292
3293   R_MARGIN    &bull;The right margin of all running text
3294                assumes the new value.  In other words,
3295                the line length is altered.
3296
3297               &bull;The header and footer right margin
3298                remain at the current document default.
3299
3300   LL          &bull;The line length of all running text
3301                is set to the new value.
3302
3303               &bull;The header and footer line length remain
3304                at the current document default.
3305
3306   FAMILY      &bull;Changes family for the duration of the
3307                current tag only.  As soon as another document
3308                element tag is invoked, the family reverts to
3309                the current default for the new tag.
3310
3311   FT          &bull;Changes font for the duration of the
3312                current tag only.  As soon as another document
3313                element tag is entered, the font reverts
3314                to the current default for the new tag.
3315
3316                N.B. &mdash; \&bull;[SLANT] and \&bull;[BOLDER] affect
3317                paragraph text, and remain in effect for all
3318                paragraphs until turned off.  If you want to
3319                use them in a macro that takes a string
3320                argument, include the escape in the string.
3321                \&bull;[COND] and \&bull;[EXT] behave similarly.
3322
3323   PT_SIZE     &bull;Changes point size for the duration of the
3324                current tag only.  As soon as another document
3325                element tag is entered, the point size reverts
3326                to the current document default for the new
3327                tag.
3328
3329   LS          &bull;Changes line space for the duration of the
3330                current tag only.  As soon as another document
3331                element tag is entered, the line space reverts
3332                to the current document default for the new
3333                tag.
3334
3335                Using LS to temporarily change leading within
3336                a document will almost certainly result in a
3337                bottom margin that doesn&#8217;t align with the
3338                bottom margin of subsequent pages.  You&#8217;ll
3339                need to use the SHIM macro to get mom back on
3340                track when you&#8217;re ready to return to the
3341                document&#8217;s default leading.
3342
3343
3344 <a id="autolead"></a>
3345   AUTOLEAD   &bull;Invoked before START, sets the overall document
3346               leading as a function of the overall document
3347               point size (ie the point size used in paragraphs);
3348               subsequently disabled after START, except for calls
3349               to DOC_PT_SIZE
3350
3351              &bull;DOC_LEAD before DOC_PT_SIZE cancels the AUTOLEAD
3352               set before START
3353
3354              &bull;Invoked after START, remains in effect for all
3355               subsequent point size changes made with PT_SIZE,
3356               but does not affect the leading of the document
3357               element tags (eg HEADING, PP, QUOTE...), or calls
3358               to DOC_PT_SIZE
3359
3360   QUAD        &bull;Changes quad for the duration of the
3361                current tag only.  As soon as another document
3362                element tag is entered, the quad reverts to
3363                the current document default for the new
3364                tag.
3365
3366                N.B. &mdash; Line-for-line quadding macros
3367                (LEFT, CENTER, RIGHT) are also temporary,
3368                overridden by the QUAD value of any subsequent
3369                document element tag.
3370 </span>
3371 </div>
3372
3373 <h3 id="tb-margins" class="docs" style="margin-top: 1.5em;">Top and bottom margins in document processing</h3>
3374
3375 <p>
3376 Normally, mom establishes the top and bottom
3377 margins of
3378 <a href="definitions.html#running">running text</a>
3379 in documents from the values of <b>HEADER_MARGIN +
3380 HEADER_GAP</b> and <b>FOOTER_MARGIN + FOOTER_GAP</b>
3381 respectively.  However, if you invoke
3382 <a href="typesetting.html#t-margin">T_MARGIN</a>
3383 or
3384 <a href="typesetting.html#b-margin">B_MARGIN</a>
3385 either before or after
3386 <a href="docelement.html#start">START</a>,
3387 they set the top and bottom margins of running text irrespective of
3388 HEADER_GAP and FOOTER_GAP.
3389 </p>
3390
3391 <p>
3392 Put another way, in document processing, T_MARGIN
3393 and B_MARGIN set the top and bottom margins of
3394 running text, but have no effect on the placement of
3395 <a href="definitions.html#header">headers</a>,
3396 <a href="definitions.html#footer">footers</a>,
3397 or page numbers.
3398 </p>
3399
3400 <!-- ==================================================================== -->
3401
3402 <h3 id="space" class="docs">Inserting space at the top of a new page</h3>
3403
3404 <p>
3405 Occasionally, you may want to insert space before the start of
3406 <a href="definitions.html#running">running text</a>
3407 on pages after the first.
3408 </p>
3409
3410 <p>
3411 You might have tried using
3412 <a href="typesetting.html#ald">ALD</a>
3413 or
3414 <a href="typesetting.html#space">SPACE</a>
3415 and found it did nothing.  This is because mom normally inhibits
3416 any extra space before the start of running text on pages after the
3417 first.
3418 </p>
3419
3420 <p>
3421 If you need the space, you must use the macro, ADD_SPACE, in
3422 conjunction with
3423 <a href="typesetting.html#newpage">NEWPAGE</a>.
3424 </p>
3425
3426 <!-- -ADD_SPACE- -->
3427
3428 <div class="macro-id-overline">
3429 <h3 id="add-space" class= "macro-id">ADD_SPACE</h3>
3430 </div>
3431
3432 <div class="box-macro-args">
3433 Macro: <b>ADD_SPACE</b> <kbd class="macro-args">&lt;amount of space&gt;</kbd>
3434 </div>
3435
3436 <p class="requires">
3437 &bull;&nbsp;Requires a <a href="definitions.html#unitofmeasure">unit of measure</a>
3438 </p>
3439
3440 <p>
3441 ADD_SPACE takes as its single argument the distance
3442 you want mom to advance from the normal
3443 baseline position at the top of any page after the first
3444 (ie the one on which the docheader is normally printed).  A
3445 <a href="definitions.html#unitofmeasure">unit of measure</a> is
3446 required.
3447 </p>
3448
3449 <p>
3450 For example, say you wanted to insert 2 inches of space before the
3451 start of
3452 <a href="definitions.html#running">running text</a>
3453 on a page other than the first.  You&#8217;d accomplish it with
3454 <br/>
3455 <span class="pre-in-pp">
3456   .NEWPAGE
3457   .ADD_SPACE 2i
3458 </span>
3459 which would terminate your current page, break to a new page, print
3460 the header (assuming headers are on) and insert 2 inches of space
3461 before the start of running text.
3462 </p>
3463
3464 <p>
3465 Since adding space in this way is almost sure to disrupt mom&#8217;s
3466 ability to guarantee perfectly flush bottom margins, I highly
3467 recommend using the
3468 <a href="docprocessing.html#shim">SHIM</a>
3469 macro immediately after ADD_SPACE.
3470 </p>
3471
3472 <!-- *** -->
3473
3474 <h2 id="intro-doc-param" class="macro-group">Changing document-wide style parameters after START</h2>
3475
3476 <p>
3477 In the normal course of things, you establish the basic type style
3478 parameters of a document prior to invoking
3479 <a href="#start">START</a>,
3480 using the
3481 <a href="typesetting.html#macros-typesetting">typesetting macros</a>
3482 (<b>L_MARGIN, FAMILY, PT_SIZE, LS,</b> etc).  After START, you must
3483 use the following macros if you wish to make global changes to the
3484 basic type style parameters, for example changing the overall leading or
3485 the justification style.
3486 </p>
3487
3488 <div class="box-important">
3489 <p class="tip">
3490 <span class="important">Important:</span>
3491 Because these macros globally update the chosen parameter, they
3492 should only be used immediately prior to
3493 <a href="rectoverso.html#collate">COLLATE</a>
3494 or, if an occasional effect is desired,
3495 <a href="typesetting.html#newpage">NEWPAGE</a>.
3496 <a href="#doc-pt-size">DOC_PT_SIZE</a>,
3497 for example, updates the point size of every page element, including
3498 headers, footers, page numbers, and so on, which is almost certainly
3499 not what you want in the middle of a page.
3500 </p>
3501 </div>
3502
3503 <div class="macro-list-container">
3504 <h3 id="index-doc-param" class="macro-list">Post-START global style change macros</h3>
3505 <ul class="macro-list">
3506   <li><a href="#doc-left-margin">DOC_LEFT_MARGIN</a></li>
3507   <li><a href="#doc-right-margin">DOC_RIGHT_MARGIN</a></li>
3508   <li><a href="#doc-line-length">DOC_LINE_LENGTH</a></li>
3509   <li><a href="#doc-family">DOC_FAMILY</a></li>
3510   <li><a href="#doc-pt-size">DOC_PT_SIZE</a></li>
3511   <li><a href="#doc-lead">DOC_LEAD</a></li>
3512   <li><a href="#doc-lead-adjust">DOC_LEAD_ADJUST</a></li>
3513   <li><a href="#doc-quad">DOC_QUAD</a></li>
3514 </ul>
3515 </div>
3516
3517 <!-- -DOC_LEFT_MARGIN -->
3518
3519 <div class="macro-id-overline">
3520 <h3 id="doc-left-margin" class="macro-id">DOC_LEFT_MARGIN</h3>
3521 </div>
3522
3523 <div class="box-macro-args">
3524 Macro: <b>DOC_LEFT_MARGIN</b> <kbd class="macro-args">&lt;left margin&gt;</kbd>
3525 </div>
3526
3527 <p class="requires">
3528 &bull;&nbsp;Requires a <a href="definitions.html#unitofmeasure">unit of measure</a>
3529 </p>
3530
3531 <h4 class="docs doc-param-macros">Arguments and behaviour</h4>
3532
3533 <ul class="doc-param-macros">
3534   <li>the argument is the same as for
3535       <a href="typesetting.html#l-margin">L_MARGIN</a>
3536   </li>
3537   <li>changes all left margins, including headers, footers, and page
3538       numbers to the new value
3539   </li>
3540   <li>any document elements that use a left indent calculate
3541       the indent from the new value
3542   </li>
3543   <li>the line length remains the same (ie the right margin
3544       shifts when you change the left margin)
3545   </li>
3546 </ul>
3547
3548 <!-- -DOC_RIGHT_MARGIN -->
3549
3550 <div class="macro-id-overline">
3551 <h3 id="doc-right-margin" class="macro-id">DOC_RIGHT_MARGIN</h3>
3552 </div>
3553
3554 <div class="box-macro-args">
3555 Macro: <b>DOC_RIGHT_MARGIN</b> <kbd class="macro-args">&lt;right margin&gt;</kbd>
3556 </div>
3557
3558 <p class="requires">
3559 &bull;&nbsp;Requires a <a href="definitions.html#unitofmeasure">unit of measure</a>
3560 </p>
3561
3562 <h4 class="docs doc-param-macros">Arguments and behaviour</h4>
3563
3564 <ul class="doc-param-macros">
3565   <li>the argument is the same as for
3566       <a href="typesetting.html#r-margin">R_MARGIN</a>
3567   </li>
3568   <li>changes all right margins, including headers, footers, and
3569       page numbers to the new value;
3570   </li>
3571   <li>any document elements that use a right indent calculate
3572       the indent from the new value
3573   </li>
3574 </ul>
3575
3576 <!-- -DOC_RIGHT_MARGIN -->
3577
3578 <div class="macro-id-overline">
3579 <h3 id="doc-line-length" class="macro-id">DOC_LINE_LENGTH</h3>
3580 </div>
3581
3582 <div class="box-macro-args">
3583 Macro: <b>DOC_LINE_LENGTH</b> <kbd class="macro-args">&lt;length&gt;</kbd>
3584 </div>
3585
3586 <p class="requires">
3587 &bull;&nbsp;Requires a <a href="definitions.html#unitofmeasure">unit of measure</a>
3588 </p>
3589
3590 <h4 class="docs doc-param-macros">Arguments and behaviour</h4>
3591
3592 <ul class="doc-param-macros">
3593   <li>the argument is the same as for
3594       <a href="typesetting.html#linelength">LL</a>
3595   </li>
3596   <li>exactly equivalent to changing the right margin with
3597       DOC_RIGHT_MARGIN (see
3598       <a href="#doc-right-margin">above</a>);
3599   </li>
3600 </ul>
3601
3602 <!-- -DOC_FAMILY- -->
3603
3604 <div class="macro-id-overline">
3605 <h3 id="doc-family" class="macro-id">DOC_FAMILY</h3>
3606 </div>
3607
3608 <div class="box-macro-args">
3609 Macro: <b>DOC_FAMILY</b> <kbd class="macro-args">&lt;family&gt;</kbd>
3610 </div>
3611
3612 <h4 class="docs doc-param-macros" style="margin-top: 1em;">Arguments and behaviour</h4>
3613
3614 <ul class="doc-param-macros">
3615   <li>the argument is the same as for
3616       <a href="typesetting.html#family">FAMILY</a>
3617   </li>
3618   <li>globally changes the type family for
3619   <ul>
3620     <li style="margin-left: -.5em;">the <a href="definitions.html#docheader">docheader</a></li>
3621     <li style="margin-left: -.5em;">all <a href="docelement.html#index-docelement">document element tags</a>, including footnotes</li>
3622     <li style="margin-left: -.5em;"><a href="definitions.html#header">headers and/or footers</a></li>
3623     <li style="margin-left: -.5em;"><a href="docelement.html#number-lines-intro">line numbering</a></li>
3624     <li style="margin-left: -.5em;"><a href="headfootpage.html#pagination">page numbering</a></li>
3625   </ul></li>
3626   <li>does <i>not</i> change the family of
3627   <ul>
3628       <li><a href="cover.html#doc-cover">document cover pages</a></li>
3629       <li><a href="cover.html#cover">cover pages</a></li>
3630       <li><a href="docelement.html#endnote-intro">endnotes pages</a></li>
3631       <li><a href="docelement.html#toc-intro">table of contents</a></li>
3632   </ul></li>
3633   <li>any page elements (eg headers page numbers, footnotes) whose
3634       families you wish to remain at their old values must be
3635       reset with the appropriate
3636       <a href="docelement.html#docelement-control">control macros</a>
3637   </li>
3638 </ul>
3639
3640 <!-- -DOC_PT_SIZE- -->
3641
3642 <div class="macro-id-overline">
3643 <h3 id="doc-pt-size" class="macro-id">DOC_PT_SIZE</h3>
3644 </div>
3645
3646 <div class="box-macro-args">
3647 Macro: <b>DOC_PT_SIZE</b> <kbd class="macro-args">&lt;point size&gt;</kbd>
3648 </div>
3649
3650 <p class="requires">
3651 &bull;&nbsp;Does not require a <a href="definitions.html#unitofmeasure">unit of measure</a>; points is assumed
3652 </p>
3653
3654 <h4 class="docs doc-param-macros">Arguments and behaviour</h4>
3655
3656 <ul class="doc-param-macros">
3657   <li>the argument is the same as for
3658       <a href="typesetting.html#ps">PT_SIZE</a>,
3659       and refers to the point size of type in paragraphs
3660   </li>
3661   <li>all automatic point size changes (heads, quotes,
3662       footnotes, headers, etc.) are affected by the new size;
3663       anything you do not want affected must be reset to
3664       its former value (see the Control Macros section of
3665       the pertinent document element for instructions on
3666       how to do this)
3667   </li>
3668   <li>if
3669       <a href="typesetting.html#autolead">AUTOLEAD</a>
3670       was invoked before START; the value of AUTOLEAD will be used
3671       to update the leading of all document element tags except
3672       FOOTNOTE and EPIGRAPH
3673   </li>
3674 </ul>
3675
3676 <!-- -DOC_LEAD- -->
3677
3678 <div class="macro-id-overline">
3679 <h3 id="doc-lead" class="macro-id">DOC_LEAD</h3>
3680 </div>
3681
3682 <div class="box-macro-args">
3683 Macro: <b>DOC_LEAD</b> <kbd class="macro-args">&lt;points&gt; [ ADJUST ]</kbd>
3684 </div>
3685
3686 <p class="requires">
3687 &bull;&nbsp;Does not require a <a href="definitions.html#unitofmeasure">unit of measure</a>; points is assumed
3688 </p>
3689
3690 <h4 class="docs doc-param-macros">Arguments and behaviour</h4>
3691
3692 <ul class="doc-param-macros">
3693   <li>the argument is the same as for
3694       <a href="typesetting.html#leading">LS</a>,
3695       and refers to the
3696       <a href="definitions.html#lead">leading</a>
3697       of paragraphs
3698   </li>
3699   <li>because paragraphs will have a new leading, the leading and
3700       spacing of most running text is influenced by the new value
3701   </li>
3702   <li>epigraphs and footnotes remain unaffected;
3703       if you wish to change their leading, use
3704       <a href="docelement.html#epigraph-autolead">EPIGRAPH_AUTOLEAD</a>
3705       and
3706       <a href="docelement.html#footnote-autolead">FOOTNOTE_AUTOLEAD</a>.
3707   </li>
3708   <li>the optional argument <kbd>ADJUST</kbd> performs
3709       leading adjustment as explained in
3710       <a href="#doc-lead-adjust">DOC_LEAD_ADJUST</a>
3711   </li>
3712   <li>if
3713       <a href="typesetting.html#autolead">AUTOLEAD</a>
3714       was invoked before START; the value of that AUTOLEAD will be
3715       cancelled
3716   </li>
3717 </ul>
3718
3719 <div class="box-tip">
3720 <p class="tip">
3721 <span class="note">Note:</span>
3722 Even if you don&#8217;t pass DOC_LEAD the optional argument
3723 <kbd>ADJUST</kbd>, mom will still adjust the leading of endnotes
3724 pages and toc pages.  See
3725 <a href="docelement.html#endnote-lead">ENDNOTE_LEAD</a>
3726 and
3727 <a href="docelement.html#toc-lead">TOC_LEAD</a>
3728 for an explanation of how to disable this default behaviour.
3729 </p>
3730 </div>
3731
3732 <!-- -DOC_QUAD- -->
3733
3734 <div class="macro-id-overline">
3735 <h3 id="doc-quad" class="macro-id">DOC_QUAD</h3>
3736 </div>
3737
3738 <div class="box-macro-args">
3739 Macro: <b>DOC_QUAD</b> <kbd class="macro-args">L | R | C | J</kbd>
3740 </div>
3741
3742 <h4 class="docs doc-param-macros" style="margin-top: 1em;">Arguments and behaviour</h4>
3743
3744 <ul class="doc-param-macros">
3745   <li>the arguments are the same as for
3746       <a href="typesetting.html#quad">QUAD</a>
3747   </li>
3748   <li>affects paragraphs, epigraphs and footnotes; does not
3749       affect blockquotes
3750   </li>
3751 </ul>
3752
3753 <h2 id="terminating" class="macro-group">Terminating a document</h2>
3754
3755 <p>
3756 You need do nothing special to terminate a document.  When groff
3757 finishes processing the last
3758 <a href="definitions.html#inputline">input line</a>
3759 of a file, the page is ejected, subject to whatever routines are
3760 needed to complete it (eg printing footnotes or adding the page
3761 number).
3762 </p>
3763
3764 <p>
3765 It happens sometimes, however, that a last line of
3766 <a href="definitions.html#running">running text</a>,
3767 falling on or very near the bottom of the page, tricks groff into
3768 breaking to a new page before terminating.  The result is a blank
3769 page at the end of the formatted document.
3770 </p>
3771
3772 <p>
3773 The situation is rare, generally occurring only when some additional
3774 macro is required after the input text, eg to exit a
3775 <a href="docelement.html#list-intro">list</a>
3776 or terminate a
3777 <a href="docelement.html#quote">quote</a>.
3778 To prevent it from ever happening, I recommend getting into the habit
3779 of following the final input line of all your mom files with
3780 <a href="typesetting.html#el"><kbd>.EL</kbd></a>.
3781 Depending on the
3782 <a href="definitions.html#filled">fill mode</a>
3783 in effect, you may also have to append the &#8220;join line&#8221;
3784 <a href="definitions.html#inlines">escape</a>,
3785 <kbd>\c</kbd>, to the final line.</p>
3786
3787 <p>
3788 Thus, for normal text at the end of a paragraph, which is in fill
3789 mode,
3790 <br/>
3791 <span class="pre-in-pp">
3792   and they all lived happily ever after.
3793   .EL
3794 </span>
3795 or for ending a
3796 <a href="docelement.html#list-intro">LIST</a>
3797 (also in fill mode)
3798 <span class="pre-in-pp">
3799   .ITEM
3800   peaches, pears, plums
3801   .EL
3802   .LIST OFF
3803 </span>
3804 whereas, at the end of a
3805 <a href="docelement.html#quote-intro">QUOTE</a>
3806 (which is in nofill mode),
3807 <span class="pre-in-pp">
3808   Shall be lifted\[em]nevermore!\c
3809   .EL
3810   .QUOTE OFF
3811 </span>
3812 Notice that the <kbd>.EL</kbd> comes after the last line of input
3813 text, not any macros following.
3814 </p>
3815
3816 <div class="box-tip">
3817 <p class="tip">
3818 <span class="note">Note:</span>
3819 <a href="inlines.html#b"><kbd>\*[B]</kbd></a>
3820 cannot be used as a replacement for <kbd>.EL</kbd> when terminating
3821 a document.
3822 </p>
3823 </div>
3824
3825
3826 <div class="rule-long"><hr/></div>
3827
3828 <!-- Navigation links -->
3829 <table style="width: 100%; margin-top: 12px;">
3830 <tr>
3831   <td style="width: 33%;"><a href="toc.html">Back to Table of Contents</a></td>
3832   <td style="width: 24%; text-align: center;"><a href="#top">Top</a></td>
3833   <td style="width: 43%; text-align: right;"><a href="docelement.html#top">Next: The document element tags</a></td>
3834 </tr>
3835 </table>
3836
3837 </div>
3838
3839 <div class="bottom-spacer"><br/></div>
3840
3841 </body>
3842 </html>
3843 <!-- vim: fileencoding=utf-8: nomodified: -->