PageRenderTime 117ms CodeModel.GetById 68ms app.highlight 33ms RepoModel.GetById 1ms app.codeStats 0ms

/contrib/groff/contrib/mom/momdoc/docprocessing.html

https://bitbucket.org/freebsd/freebsd-head/
HTML | 2484 lines | 2413 code | 63 blank | 8 comment | 0 complexity | ae70fc015e8d0d4392e8a452046265cf MD5 | raw file

Large files files are truncated, but you can click here to view the full file

   1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
   2<html>
   3<head>
   4<meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
   5<title>Mom -- Document Processing, Introduction and Setup</title>
   6</head>
   7<body bgcolor="#dfdfdf">
   8
   9<!====================================================================>
  10
  11<a href="typemacdoc.html#TOP">Next</a>&nbsp;&nbsp;
  12<a href="color.html#TOP">Prev</a>&nbsp;&nbsp;
  13<a href="toc.html">Back to Table of Contents</a>
  14<p>
  15<a name="TOP"></a>
  16<a name="DOCPROCESSING">
  17	<h1 align="center"><u>DOCUMENT PROCESSING WITH MOM</u></h1>
  18</a>
  19<a href="#INTRO_MACROS_DOCPROCESSING">Introduction to document processing</a>
  20<br>
  21<a href="#DEFAULTS">Some document defaults</a>
  22<br>
  23<a href="#LEADING_NOTE">* IMPORTANT NOTE on leading/spacing and bottom margins *</a>
  24<br>
  25<a href="#SHIM">The SHIM macro</a>
  26<br>
  27<h3><u>Table of Contents for document processing</u></h3>
  28<ul>
  29	<li><a href="#SETUP"><strong>DOCUMENT SETUP</strong></a>
  30	<br>
  31	<a href="#DOCPROCESSING_TUT">Tutorial -- Setting up a mom document</a>
  32	<br>
  33	<ul>
  34		<li><a href="#REFERENCE_MACROS"><strong>The Reference Macros</strong></a>
  35		<ul>
  36			<li><a href="#TITLE">TITLE</a>
  37			<li><a href="#DOC_TITLE">DOCTITLE</a>
  38			<li><a href="#SUBTITLE">SUBTITLE</a>
  39			<li><a href="#AUTHOR">AUTHOR</a>
  40			<li><a href="#CHAPTER">CHAPTER</a>
  41			<li><a href="#CHAPTER_TITLE">CHAPTER_TITLE</a>
  42			<li><a href="#DRAFT">DRAFT</a>
  43			<li><a href="#REVISION">REVISION</a>
  44			<li><a href="#COPYRIGHT">COPYRIGHT</a>
  45			<li><a href="#MISC">MISC</a>
  46		</ul>
  47		<li><a href="#DOCSTYLE_MACROS"><strong>The Docstyle Macros</strong></a>
  48		<ul>
  49			<li><a href="#DOCTYPE">DOCTYPE</a>
  50			<li><a href="#PRINTSTYLE">PRINTSTYLE</a>
  51			<li><a href="#COPYSTYLE">COPYSTYLE</a>
  52		</ul>
  53		
  54		<li><a href="#STYLE_BEFORE_START"><strong>Changing type/style parameters prior to START</strong></a>
  55		<ul>
  56			<li><a href="#TYPE_BEFORE_START">Using typesetting macros prior to START</a>
  57			<ul>
  58				<li><a href="#COLOR">Colour</a>
  59			</ul>
  60			<li><a href="#DOC_LEAD_ADJUST">Adjusting document leading to fill pages -- DOC_LEAD_ADJUST</a>
  61			<li><a href="#DOCHEADER">Managing the document header</a>
  62			<ul>
  63				<li><a href="#DOCHEADER">DOCHEADER -- turning docheaders off</a>
  64				<li><a href="#DOCHEADER_CONTROL">Docheader control</a>
  65			</ul>
  66		</ul>
  67
  68		<li><a href="#COLUMNS_INTRO"><strong>Setting documents in columns</strong></a>
  69		<ul>
  70			<li><a href="#COLUMNS">COLUMNS</a>
  71			<li><a href="#BREAKING_COLUMNS">Breaking columns manually</a>
  72			<ul>
  73			    <li><a href="#COL_NEXT">COL_NEXT</a>
  74			    <li><a href="#COL_BREAK">COL_BREAK</a>
  75			</ul>
  76
  77		</ul>
  78
  79		<li><a href="#START_MACRO"><strong>Initiate document processing</strong></a>
  80		<ul>
  81			<li><a href="#START">START</a>
  82		</ul>
  83	
  84		<li><a href="#DOC_PARAM_MACROS"><strong>Changing document-wide typesetting parameters after START</strong></a>
  85		<ul>
  86			<li><a href="#DOC_LEFT_MARGIN">DOC_LEFT_MARGIN</a>
  87			<li><a href="#DOC_RIGHT_MARGIN">DOC_RIGHT_MARGIN</a>
  88			<li><a href="#DOC_LINE_LENGTH">DOC_LINE_LENGTH</a>
  89			<li><a href="#DOC_FAMILY">DOC_FAMILY</a>
  90			<li><a href="#DOC_PT_SIZE">DOC_PT_SIZE</a>
  91			<li><a href="#DOC_LEAD">DOC_LEAD</a>
  92			<li><a href="#DOC_LEAD_ADJUST">DOC_LEAD_ADJUST</a>
  93			<li><a href="#DOC_QUAD">DOC_QUAD</a>
  94		</ul>
  95		<br>
  96		<li><a href="docelement.html#DOCELEMENT"><strong>THE DOCUMENT ELEMENT MACROS (TAGS)</strong></a>
  97		<ul>
  98			<li><a href="docelement.html#DOCELEMENT_INTRO">Introduction to the document element tags</a>
  99			<ul>
 100				<li><a href="docelement.html#DOCELEMENT_CONTROL">Document element (tag) control macros</a>
 101				<li><a href="docelement.html#CONTROL_MACRO_ARGS">Arguments to the control macros</a>
 102			</ul>
 103			<li><a href="docelement.html#EPIGRAPH_INTRO"><strong>Epigraphs</strong></a>
 104			<ul>
 105				<li><a href="docelement.html#EPIGRAPH">EPIGRAPH</a>
 106				<li><a href="docelement.html#EPIGRAPH_CONTROL">Epigrah control</a>
 107			</ul>
 108			<li><a href="docelement.html#PP_INTRO"><strong>Paragraphs</strong></a>
 109			<ul>
 110				<li><a href="docelement.html#PP">PP</a>
 111				<li><a href="docelement.html#PP_CONTROL">Paragraph control</a>
 112			</ul>
 113			<li><a href="docelement.html#HEAD_INTRO"><strong>Main heads</strong></a>
 114			<ul>
 115				<li><a href="docelement.html#HEAD">HEAD</a>
 116				<li><a href="docelement.html#HEAD_CONTROL">Head control</a>
 117			</ul>
 118			<li><a href="docelement.html#SUBHEAD_INTRO"><strong>Subheads</strong></a>
 119			<ul>
 120				<li><a href="docelement.html#SUBHEAD">SUBHEAD</a>
 121				<li><a href="docelement.html#SUBHEAD_CONTROL">Subhead control</a>
 122			</ul>
 123			<li><a href="docelement.html#PARAHEAD_INTRO"><strong>Paragraph heads</strong></a>
 124			<ul>
 125				<li><a href="docelement.html#PARAHEAD">PARAHEAD</a>
 126				<li><a href="docelement.html#PARAHEAD_CONTROL">Parahead control</a>
 127			</ul>
 128			<li><a href="docelement.html#LINEBREAK_INTRO"><strong>Linebreaks (author linebreaks, also called section breaks)</strong></a>
 129			<ul>
 130				<li><a href="docelement.html#LINEBREAK">LINEBREAK</a>
 131				<li><a href="docelement.html#LINEBREAK_CONTROL">Linebreak control</a>
 132			</ul>
 133			<li><a href="docelement.html#QUOTE_INTRO"><strong>Quotes (line for line poetic quotes)</strong></a>
 134			<ul>
 135				<li><a href="docelement.html#QUOTE">QUOTE</a>
 136				<li><a href="docelement.html#QUOTE_CONTROL">Quote control</a>
 137			</ul>
 138			<li><a href="docelement.html#BLOCKQUOTE_INTRO"><strong>Blockquotes (cited material)</strong></a>
 139			<ul>
 140				<li><a href="docelement.html#BLOCKQUOTE">BLOCKQUOTE</a>
 141				<li><a href="docelement.html#BLOCKQUOTE_CONTROL">Blockquote control</a>
 142			</ul>
 143			<li><a href="docelement.html#FOOTNOTE_INTRO"><strong>Footnotes</strong></a>
 144			<ul>
 145				<li><a href="docelement.html#FOOTNOTE">FOOTNOTE</a>
 146				<li><a href="docelement.html#FOOTNOTE_CONTROL">Footnote control</a>
 147			</ul>
 148			<li><a href="docelement.html#ENDNOTE_INTRO"><strong>Endnotes</strong></a>
 149			<ul>
 150				<li><a href="docelement.html#ENDNOTE">ENDNOTE</a>
 151				<li><a href="docelement.html#ENDNOTE_CONTROL">Endnote control</a>
 152			</ul>
 153			<li><a href="docelement.html#FINIS_INTRO"><strong>Document termination</strong></a>
 154			<ul>
 155				<li><a href="docelement.html#FINIS">FINIS</a>
 156				<li><a href="docelement.html#FINIS_CONTROL">Finis control</a>
 157			</ul>
 158		</ul>
 159		
 160		<li><a href="headfootpage.html#HEADFOOTPAGE"><strong>HEADERS and FOOTERS</strong></a>
 161		<br>
 162		<ul>
 163			<li><a href="headfootpage.html#HEADFOOTPAGE_INTRO">Introduction to headers/footers</a>
 164			<li><a href="headfootpage.html#HEADFOOT_MANAGEMENT">Managing headers/footers</a>
 165			<ul>
 166				<li><a href="headfootpage.html#HEADERS">HEADERS</a> -- on or off
 167				<li><a href="headfootpage.html#FOOTERS">FOOTERS</a> -- on or off
 168				<li><a href="headfootpage.html#FOOTER_ON_FIRST_PAGE">FOOTER_ON_FIRST_PAGE</a>
 169			</ul>
 170			<li><a href="headfootpage.html#HEADFOOT_CONTROL">Header/footer control</a>
 171			<ul>
 172				<li><a href="headfootpage.html#HDRFTR_STRINGS">Header/footer strings</a>
 173				<li><a href="headfootpage.html#HDRFTR_STYLE">Header/footer style</a> -- global and part-by-part
 174				<li><a href="headfootpage.html#HDRFTR_VERTICAL">Header/footer placement and spacing</a>
 175				<li><a href="headfootpage.html#HDRFTR_SEPARATOR">The header/footer separator rule</a>
 176			</ul>
 177		</ul>
 178		<li><a href="headfootpage.html#PAGINATION"><strong>PAGINATION</strong></a>
 179		<br>
 180		<ul>
 181			<li><a href="headfootpage.html#PAGINATE">PAGINATE</a> -- on or off
 182			<li><a href="headfootpage.html#PAGENUMBER">PAGENUMBER</a> -- user supplied page number
 183			<li><a href="headfootpage.html#PAGENUM_STYLE">PAGENUM_STYLE</a> -- digits, roman numerals, etc.
 184			<li><a href="headfootpage.html#DRAFT_WITH_PAGENUMBER">DRAFT_WITH_PAGENUMBER</a> -- attach draft/revision information to page numbers
 185			<li><a href="headfootpage.html#PAGINATE_CONTROL">Pagination control</a>
 186		</ul>
 187		<br>
 188		<li><a href="rectoverso.html#RECTOVERSO"><strong>RECTO_VERSO PRINTING and COLLATING</strong></a>
 189		<br>
 190		<ul>
 191			<li><a href="rectoverso.html#RECTOVERSO_INTRO">Introduction to recto/verso</a>
 192			<ul>
 193				<li><a href="rectoverso.html#RECTO_VERSO">RECTO_VERSO</a>
 194				<li><a href="rectoverso.html#SWITCH_HDRFTR">SWITCH_HEADERS</a> (also FOOTERS)
 195			</ul>
 196			<li><a href="rectoverso.html#COLLATE_INTRO">Introduction to collating</a>
 197			<ul>
 198				<li><a href="rectoverso.html#COLLATE">COLLATE</a>
 199			</ul>
 200		</ul>
 201	
 202		<li><a href="cover.html#TOP"><strong>CREATING A COVER PAGE</strong></a>
 203		<br>
 204		<li><a href="letters.html#LETTERS"><strong>WRITING LETTERS</strong></a>
 205		<ul>
 206			<li><a href="letters.html#LETTERS_INTRO">Introduction to writing letters</a>
 207			<li><a href="letters.html#TUTORIAL">Tutorial on writing letters</a>
 208			<li><a href="letters.html#LETTERS_DEFAULTS">Default style for letters</a>
 209			<li><a href="letters.html#LETTERS_MACROS">The letter macros</a>
 210		</ul>
 211	</ul>
 212</ul>
 213<br>
 214<hr>
 215
 216<h2><a name="INTRO_MACROS_DOCPROCESSING"><u>Introduction to document processing</u></a></h2>
 217
 218As explained in
 219<a href="intro.html#INTRO_DOCPROCESSING">Document processing with mom</a>,
 220document processing uses markup tags to identify document elements
 221such as heads, paragraphs, and so on.  The tags are, of course, macros,
 222but with sensible, readable names that make them easy to grasp and
 223easy to remember.  (And don't forget: if you don't like the
 224&quot;official&quot; name of a tag -- too long, cumbersome
 225to type in, not &quot;intuitive&quot; enough -- you can change it
 226with the
 227<a href="goodies.html#ALIAS">ALIAS</a>
 228macro.)
 229<p>
 230In addition to the tags themselves, <strong>mom</strong> has an
 231extensive array of macros that control how they look and behave.
 232<p>
 233Setting up a <strong>mom</strong> doc is a simple, four-part procedure.
 234You begin by entering information about the document itself (title,
 235subtitle, author, etc.).  Next, you tell <strong>mom</strong> what
 236kind of document you're creating (e.g. chapter, letter, abstract,
 237etc...) and what kind of output you want (typeset, typewritten,
 238draft-style, etc).  Thirdly, you make as many or as few changes to
 239<strong>mom</strong>'s default behaviour as you wish.  Lastly, you
 240invoke the
 241<a href="#START">START</a>
 242macro.  Voilà!  You're ready to write.
 243<p>
 244<hr>
 245
 246
 247<h2><a name="DEFAULTS"><u>Some document defaults</u></a></h2>
 248
 249As is to be expected, <strong>mom</strong> has defaults for everything.
 250If you want to know a particular default, read about it in the
 251description of the pertinent tag.
 252<p>
 253I fear the following may not be adequately covered in the
 254documentation.  Just in case, here they are.
 255<p>
 256<ul>
 257	<li>the paper size is 8.5x11 inches
 258	<li>the left and right margins are 1-inch
 259	<li>the top and bottom margins for document text are plus/minus
 260		visually 1-inch
 261	<li>pages are numbered; the number appears centred, at the
 262		bottom, surrounded by hyphens ( e.g. -6- )
 263	<li>the first page of a document begins with a
 264		<a href="definitions.html#TERMS_DOCHEADER">document header</a>
 265	<li>subsequent pages have
 266		<a href="definitions.html#TERMS_HEADER">page headers</a>
 267		with a rule underneath
 268</ul>
 269<p>
 270Another way to check up on document processing defaults is to have
 271a look at the macro file (om.tmac).  Each macro is preceded by a
 272description that (generally) says what its default is (if it has
 273one).
 274<p>
 275<hr>
 276
 277<a name="LEADING_NOTE">
 278	<h2><u>IMPORTANT NOTE on leading/spacing and  bottom margins</u></h2>
 279</a>
 280
 281<strong>Mom</strong> takes evenly-aligned  bottom margins in
 282<a href="definitions.html#TERMS_RUNNING">running text</a>
 283very seriously.  Only under a very few (exceptional) circumstances
 284will she allow a bottom margin to &quot;hang&quot; (i.e. to fall
 285short).
 286<p>
 287In order to ensure even bottom margins, <strong>mom</strong>
 288uses the &quot;base&quot; document
 289<a href="definitions.html#TERMS_LEADING">leading</a>
 290in effect <em>at the start of running text on each page</em> (i.e.
 291the leading used in paragraphs) to calculate the spacing of every
 292document element.  Prior to invoking
 293<a href="#START">START</a>,
 294this is set with the
 295<a href="typesetting.html#MACROS_TYPESETTING">typesetting macro</a>
 296<a href="typesetting.html#LEADING">LS</a>,
 297afterwards with the document
 298<a href="definitions.html#TERMS_CONTROLMACRO">control macro</a>
 299<a href="#DOC_LEAD">DOC_LEAD</a>.
 300<p>
 301Because <strong>mom</strong> relies so heavily on the base document
 302leading, any change to the leading or spacing on a page will almost
 303certainly have undesirable consequences on that page's bottom margin
 304unless the change is fully compensated for elsewhere on the page.
 305<p>
 306In other words, if you add a few points of space somewhere on a page,
 307you must subtract the same number of points somewhere else on that
 308same page, and vice versa.
 309<p>
 310If it's a question of adding or subtracting full line spaces between
 311or within document elements, you can do so by using the &quot;v&quot;
 312<a href="definitions.html#TERMS_UNITOFMEASURE">unit of measure</a>
 313with whatever spacing macro you choose --
 314<a href="typesetting.html#ALD">ALD</a>,
 315<a href="typesetting.html#RLD">RLD</a>,
 316<a href="typesetting.html#SPACE">SPACE</a>
 317-- and <strong>mom</strong> won't object.  &quot;v&quot; means
 318&quot;the current leading&quot;, so she isn't confused by it.  And
 319since &quot;v&quot; accepts decimal fractions, you can add/subtract
 320half linespaces and quarter linespaces with &quot;v&quot; as well,
 321<em>provided you compensate for the fractional linespace somewhere
 322else on the page</em>.
 323<p>
 324If all this seems like too much work, <strong>mom</strong>
 325provides a special macro to get you out of trouble if you've played
 326around with leading and/or spacing.  The macro is called
 327<strong>SHIM</strong> (like those little pieces of wood carpenters
 328use to get their work even, level and snug), and it's described
 329below.
 330<p>
 331
 332<!---SHIM--->
 333
 334<hr width="66%" align="left">
 335<p>
 336<a name="SHIM"></a>
 337Macro: <strong>SHIM</strong>
 338
 339<p>
 340<strong>SHIM</strong> doesn't take any argument.  Use it whenever
 341you've played around with the
 342<a href="definitions.html#TERMS_LEADING">leading</a>
 343or spacing on a page and you
 344need to get <strong>mom</strong>'s document leading back on track.
 345<p>
 346For example, say you want to insert a picture into a document with
 347the special groff macro, <strong>PSPIC</strong> (see the
 348<strong>groff_tmac</strong> man page for usage).
 349<p>
 350Pictures aren't usually conveniently sized in multiples of document
 351leading, which means that when you insert the picture, you disrupt
 352<strong>mom</strong>'s ordered placement of baselines on the page.
 353This will certainly result in a bottom margin that doesn't match the
 354bottom margins of your document's other pages.
 355<p>
 356The solution is to insert <strong>SHIM</strong> after the picture,
 357like this:
 358<p>
 359<pre>
 360	&lt;some lines of text&gt;
 361	.PSPIC &lt;full path to picture&gt;
 362	.SHIM
 363	&lt;more lines of text&gt;
 364</pre>
 365<strong>SHIM</strong> instructs <strong>mom</strong> to insert as
 366much or a little space after the picture as is needed to ensure that
 367the baseline of the next
 368<a href="definitions.html#TERMS_OUTPUTLINE">output line</a>
 369falls where <strong>mom</strong> would have put it had you not
 370disrupted the normal flow of output lines with the picture.
 371<p>
 372And say, on previewing the above example, you find that the picture
 373doesn't centre nicely between the lines of text, you can always do
 374<p>
 375<pre>
 376	&lt;some lines of text&gt;
 377	.RLD 3p
 378	.PSPIC &lt;full path to picture&gt;
 379	.SHIM
 380	&lt;more lines of text&gt;
 381</pre>
 382
 383to raise the picture slightly
 384(<strong>R</strong>everse <strong>L</strong>ea<strong>D</strong>
 3853 points; see
 386<a href="typesetting.html#RLD">RLD</a>),
 387and still have <strong>SHIM</strong> ensure that text underneath
 388falls exactly where it's supposed to.
 389<p>
 390<hr>
 391
 392<a name="SETUP"><h2><u>Document setup</u></h2></a>
 393<p>
 394<a name="DOCPROCESSING_TUT">
 395	<h3><u>Tutorial -- Setting up a mom document</u></h3>
 396</a>
 397There are four &quot;parts&quot; to setting up a <strong>mom</strong>
 398doc (three, actually, with one optional).  Before we proceed, though,
 399be reassured that something as simple as
 400<p>
 401<pre>
 402	.TITLE     "By the Shores of Lake Attica"
 403	.AUTHOR    "Rosemary Winspeare"
 404	.PRINTSTYLE TYPESET
 405	.START
 406</pre>
 407
 408produces a beautifully typeset 8.5x11 document, with a
 409<a href="definitions.html#TERMS_DOCHEADER">docheader</a>
 410at the top of page 1,
 411<a href="definitions.html#TERMS_HEADER">page headers</a>
 412with the title and author on subsequent
 413pages, and page numbers at the bottom of each page.  In the course
 414of the document, heads, subheads, citations, quotes, epigraphs,
 415and so on, all come out looking neat, trim, and professional.
 416<p>
 417For the purposes of this tutorial, we're going to set up a short
 418story -- <em>My Pulitzer Winner</em> by Joe Blow.  Thankfully,
 419we don't have to look at story itself, just the setup.
 420Joe wants the document
 421<p>
 422<ul>
 423	<li>to be draft 7, revision 39;
 424	<li>to use the &quot;default&quot; style of document formatting:
 425	<li>to print as draft-style output (instead of &quot;final&quot; copy output);
 426	<li>to be typeset, in Helvetica, 12 on 14,
 427		<a href="definitions.html#TERMS_RAG">rag-right</a>;
 428	<li>to have <a href="definitions.html#TERMS_FOOTER">footers</a>
 429		instead of
 430		<a href="definitions.html#TERMS_HEADER">headers</a>;
 431	<li>to use a single asterisk for
 432		<a href="definitions.html#TERMS_LINEBREAK">author linebreaks</a>.
 433</ul>
 434<p>
 435Joe Blow has no taste in typography.  His draft won't look pretty,
 436but this is, after all, a tutorial; we're after examples, not beauty.
 437<h3><u>Step 1</u></h3>
 438
 439The first step in setting up any document is giving <strong>mom</strong>
 440some reference information.  The reference macros are:
 441<p>
 442<ul>
 443	<li>TITLE
 444	<li>DOCTITLE
 445	<li>COVERTITLE
 446	<li>SUBTITLE
 447	<li>AUTHOR
 448	<li>CHAPTER -- the chapter number
 449	<li>DRAFT -- the draft number
 450	<li>REVISION -- the revision number
 451	<li>COPYRIGHT -- only used on cover pages
 452	<li>MISC -- only used on cover pages
 453	<li>COVER_TITLE -- only on cover pages; only if needed
 454	<li>DOC_COVER_TITLE -- only on document cover pages; only if needed
 455</ul>
 456<p>
 457You can use as many or as few as you wish, although at a minimum,
 458you'll probably fill in <strong>TITLE</strong> (unless the document's
 459a letter) and <strong>AUTHOR</strong>.  Order doesn't matter.
 460You can separate the
 461<a href="definitions.html#TERMS_ARGUMENTS">arguments</a>
 462from the macros by any number of spaces.  The following are
 463what you'd need to start Joe Blow's story.
 464<p>
 465<pre>
 466	.TITLE    "My Pulitzer Winner"
 467	.AUTHOR   "Joe Blow"
 468	.DRAFT     7
 469	.REVISION  39
 470</pre>
 471
 472<h3><u>Step 2</u></h3>
 473
 474Once you've given <strong>mom</strong> the reference information she
 475needs, you tell her how you want your document formatted.  What kind
 476of document is it?  Should it be typeset or typewritten?  Is this
 477a &quot;final&quot; copy (for the world to see) or just a draft?
 478<strong>Mom</strong> calls the macros that answer these questions
 479&quot;the docstyle macros.&quot;  They are:
 480<p>
 481<ul>
 482	<li>DOCTYPE -- the type of document (default, chapter, user-defined, letter)
 483	<li>PRINTSTYLE -- typeset or typewritten
 484	<li>COPYSTYLE  -- draft or final copy
 485</ul>
 486<p>
 487<strong>Mom</strong> has defaults for <strong>DOCTYPE</strong>
 488and <strong>COPYSTYLE</strong>; if they're what you want, you
 489don't need to include them here.  However, <strong>PRINTSTYLE</strong>
 490has no default and MUST be present in every formatted document.
 491If you omit it, <strong>mom</strong> won't process the document AND
 492she'll complain (both to stderr and as a single printed sheet with
 493a warning).  Moms -- they can be so annoying sometimes. &lt;sigh&gt;
 494<p>
 495Adding to what we already have, the next bit of setup for Joe
 496Blow's story looks like this:
 497<p>
 498<pre>
 499	.TITLE    "My Pulitzer Winner"
 500	.AUTHOR   "Joe Blow"
 501	.DRAFT     7
 502	.REVISION  39
 503	\#
 504	.DOCTYPE     DEFAULT \"Superfluous; mom uses DOCTYPE DEFAULT by default
 505	.PRINTSTYLE  TYPESET
 506	.COPYSTYLE   DRAFT
 507</pre>
 508
 509Notice the use of the
 510<a href="definitions.html#TERMS_COMMENTLINES">comment line</a>
 511( \# ), a handy way to keep groups of macros visually separated
 512for easy reading in a text editor.
 513
 514<h3><u>Step 3</u></h3>
 515
 516This step -- completely optional -- is where you, the user, take
 517charge.  <strong>Mom</strong> has defaults for <em>everything</em>,
 518but who's ever satisfied with defaults?  Use any of the <a
 519href="typesetting.html#MACROS_TYPESETTING">typesetting macros</a>
 520here to change <strong>mom</strong>'s document defaults (paper
 521size, margins, family, point size, line space, rag, etc), or
 522any of the document processing macros that set/change/control
 523the appearance of document elements.  Think of this as the
 524&quot;style-sheet &quot; section of a document.  And please note:
 525you MUST give <strong>mom</strong> a
 526<a href="#PRINTSTYLE">PRINTSTYLE</a>
 527directive <strong>before</strong> making any such changes.
 528<p>
 529Joe Blow wants his story printed in Helvetica, 12 on 14, rag
 530right, with
 531<a href="definitions.html#TERMS_FOOTER">page footers</a>
 532instead of
 533<a href="definitions.html#TERMS_HEADER">page headers</a>
 534and a single asterisk for the
 535<a href="definitions.html#TERMS_LINEBREAK">linebreak</a>
 536character.  None of these requirements conforms
 537to <strong>mom</strong>'s defaults for the chosen
 538<strong>PRINTSTYLE</strong> (TYPESET), so we change them here.
 539The setup for Joe Blow's story now looks like this:
 540<p>
 541<pre>
 542	.TITLE    "My Pulitzer Winner"
 543	.AUTHOR   "Joe Blow"
 544	.DRAFT     7
 545	.REVISION  39
 546	\#
 547	.DOCTYPE     DEFAULT
 548	.PRINTSTYLE  TYPESET
 549	.COPYSTYLE   DRAFT
 550	\#
 551	.FAMILY  H
 552	.PT_SIZE 12
 553	.LS      14
 554	.QUAD    LEFT    \"i.e. rag right
 555	.FOOTERS
 556	.LINEBREAK_CHAR *
 557</pre>
 558
 559<h3><u>Step 4</u></h3>
 560The final step in setting up a document is telling <strong>mom</strong>
 561to start document processing.  It's a no-brainer, just the single macro
 562<strong>START</strong>.  Other than <strong>PRINTSTYLE</strong>, it's
 563the only macro required for document processing (although
 564I can't guarantee you'll like the results of using just the two).
 565<p>
 566Here's the complete setup for <em>My Pulitzer Winner</em>:
 567<p>
 568<pre>
 569	.TITLE    "My Pulitzer Winner"
 570	.AUTHOR   "Joe Blow"
 571	.DRAFT     7
 572	.REVISION  39
 573	\#
 574	.DOCTYPE     DEFAULT
 575	.PRINTSTYLE  TYPESET
 576	.COPYSTYLE   DRAFT
 577	\#
 578	.FAMILY   H
 579	.PT_SIZE  12
 580	.LS       14
 581	.QUAD     LEFT    \"i.e. rag right
 582	.FOOTERS
 583	.LINEBREAK_CHAR *
 584	\#
 585	.START
 586</pre>
 587
 588As pointed out earlier, Joe Blow is no typographer.  Given that all he
 589needs is a printed draft of his work, a simpler setup would have been:
 590<p>
 591<pre>
 592	.TITLE    "My Pulitzer Winner"
 593	.AUTHOR   "Joe Blow"
 594	.DRAFT     7
 595	.REVISION  39
 596	\#
 597	.PRINTSTYLE  TYPEWRITE
 598	.COPYSTYLE   DRAFT
 599	\#
 600	.START
 601</pre>
 602
 603<kbd>.PRINTSTYLE TYPEWRITE</kbd>, above, means that Joe's work
 604will come out &quot;typewritten, double-spaced&quot;, making the
 605blue-pencilling he (or someone else) is sure to do much
 606easier (which is why many publishers and agents still insist on
 607typewritten, double-spaced copy).
 608<p>
 609When J. Blow stops re-writing and decides to print off a final,
 610typeset copy of his work for the world to see, he need only
 611make two changes to the (simplified) setup:
 612<p>
 613<pre>
 614	.TITLE    "My Pulitzer Winner"
 615	.AUTHOR   "Joe Blow"
 616	.DRAFT     7
 617	.REVISION  39
 618	\#
 619	.PRINTSTYLE  TYPESET  \"first change
 620	.COPYSTYLE   FINAL    \"second change
 621	\#
 622	.START
 623</pre>
 624
 625In the above, <kbd>.DRAFT 7, .REVISION 39,</kbd> and <kbd>.COPYSTYLE
 626FINAL</kbd> are actually superfluous.  The draft and revision numbers
 627aren't used when <strong>COPYSTYLE</strong> is <strong>FINAL</strong>,
 628and <strong>COPYSTYLE FINAL</strong> is <strong>mom</strong>'s
 629default unless you tell her otherwise.  BUT... to judge from the
 630number of drafts already, J. Blow may very well decide his
 631&quot;final&quot; version still isn't up to snuff.  Hence, he might
 632as well leave in the superfluous macros.  That way, when draft 7,
 633rev. 62 becomes draft 8, rev. 1, he'll be ready to tackle his Pulitzer
 634winner again.
 635<p>
 636<hr>
 637
 638<!========================================================================>
 639
 640<a name="REFERENCE_MACROS">
 641	<h2><u>The Reference Macros</u></h2>
 642</a>
 643
 644The reference macros give <strong>mom</strong> the information
 645she needs to generate
 646<a href="definitions.html#TERMS_DOCHEADER">docheaders</a>,
 647<a href="definitions.html#TERMS_HEADER">page headers</a>,
 648and
 649<a href="cover.html#COVER_TOP">covers</a>.
 650They must go at the top of any file that uses <strong>mom</strong>'s
 651document processing macros.
 652<p>
 653<a name="INDEX_REFERENCE">
 654	<h3><u>Reference macros list</u></h3>
 655</a>
 656
 657<ul>
 658	<li><a href="#TITLE">TITLE</a>
 659	<li><a href="#DOC_TITLE">DOCTITLE</a>
 660	<li><a href="#SUBTITLE">SUBTITLE</a>
 661	<li><a href="#AUTHOR">AUTHOR</a>
 662	<li><a href="#CHAPTER">CHAPTER</a>
 663	<li><a href="#CHAPTER_TITLE">CHAPTER_TITLE</a>
 664	<li><a href="#DRAFT">DRAFT</a>
 665	<li><a href="#REVISION">REVISION</a>
 666	<li><a href="#COPYRIGHT">COPYRIGHT</a>
 667	<li><a href="#MISC">MISC</a>
 668	<li><a href="#COVERTITLE">COVERTITLE</a>
 669</ul>
 670<br>
 671
 672<!---TITLE--->
 673
 674<hr width="66%" align="left">
 675<p>
 676<a name="TITLE"></a>
 677<nobr>Macro: <strong>TITLE</strong> &quot;&lt;title&gt;&quot;</nobr>
 678<br>
 679<em>*Argument must be enclosed in double-quotes</em>
 680
 681<p>
 682The title string can be caps or caps/lower-case; it's up to you.
 683In
 684<a href="#PRINTSTYLE">PRINTSTYLE TYPESET</a>,
 685the title will appear in the
 686<a href="definitions.html#TERMS_DOCHEADER">docheader</a>
 687exactly as you typed it.  However, <strong>mom</strong> converts
 688the title to all caps in
 689<a href="definitions.html#TERMS_HEADER">page headers</a>
 690unless you turn that feature off (see
 691<a href="headfootpage.html#_CAPS">HEADER_&lt;POSITION&gt;_CAPS</a>). In
 692<a href="#PRINTSTYLE">PRINTSTYLE TYPEWRITE</a>,
 693the title always gets converted to caps.
 694<p>
 695<strong>NOTE:</strong> If your
 696<a href="#DOCTYPE">DOCTYPE</a>
 697is <strong>CHAPTER</strong>, <strong>TITLE</strong> should be the
 698title of the opus, not &quot;CHAPTER whatever&quot;.
 699<p>
 700
 701<!---DOCTITLE--->
 702
 703<hr width="66%" align="left">
 704<p>
 705<a name="DOCTITLE"></a>
 706<nobr>Macro: <strong>DOCTITLE</strong> &quot;&lt;overall document title&gt;&quot;</nobr>
 707<br>
 708<em>*Argument must be enclosed in double-quotes</em>
 709
 710<p>
 711<strong>NOTE:</strong> This macro should be used only if your
 712<a href="#DOCTYPE">DOCTYPE</a>
 713is <strong>DEFAULT</strong> (which is <strong>mom</strong>'s
 714default).
 715<p>
 716When you're creating a single document, say, an essay or a short
 717story, you have no need of this macro.
 718<a href="#TITLE">TITLE</a>
 719takes care of all your title needs.
 720<p>
 721However if you're 
 722<a href="rectoverso.html#COLLATE">collating</a>
 723a bunch of documents together, say, to print out a report containing
 724many articles with different titles, or a book of short stories, you
 725need <strong>DOCTITLE</strong>.
 726<p>
 727<strong>DOCTITLE</strong> tells <strong>mom</strong> the title
 728of the complete document (as opposed to the title of each article
 729or entitled section).
 730<p>
 731The doctitle string can be caps or caps/lower-case; it's up to you.
 732In
 733<a href="#PRINTSTYLE">PRINTSTYLE TYPESET</a>,
 734by default, the doctitle appears in the rightmost position of
 735<a href="definitions.html#TERMS_HEADER">page headers</a>,
 736all in caps unless you turn that feature off (see
 737<a href="headfootpage.html#_CAPS">HEADER_&lt;POSITION&gt;_CAPS</a>). In
 738<a href="#PRINTSTYLE">PRINTSTYLE TYPEWRITE</a>,
 739the doctitle always gets converted to caps.
 740<p>
 741<strong>NOTE:</strong> If your
 742<a href="#DOCTYPE">DOCTYPE</a>
 743is <strong>CHAPTER</strong>, you don't need
 744<strong>DOCTITLE</strong>.  <strong>TITLE</strong> takes care of
 745everything.
 746<p>
 747
 748<!---SUBTITLE--->
 749
 750<hr width="66%" align="left">
 751<p>
 752<a name="SUBTITLE"></a>
 753<nobr>Macro: <strong>SUBTITLE</strong> &quot;&lt;subtitle&gt;&quot;</nobr>
 754<br>
 755<em>*Argument must be enclosed in double-quotes</em>
 756
 757<p>
 758The subtitle string can be caps or caps/lower-case.  Since a
 759document's subtitle appears only in the
 760<a href="definitions.html#TERMS_DOCHEADER">docheader</a>,
 761and the title is most likely in caps, I recommend caps/lower case.
 762<p>
 763
 764<!---AUTHOR--->
 765
 766<hr width="66%" align="left">
 767<p>
 768<a name="AUTHOR"></a>
 769<nobr>Macro: <strong>AUTHOR</strong> &quot;&lt;author string&gt;&quot; [ &quot;&lt;author2 string&gt;&quot; &quot;&lt;author3 string&gt;&quot; ... ]</nobr>
 770<br>
 771<em>*Multiple arguments must all be enclosed in double-quotes</em>
 772
 773<p>
 774Each author string can hold as many names as you like, e.g.
 775<p>
 776<pre>
 777	.AUTHOR "Joe Blow"
 778	    or
 779	.AUTHOR "Joe Blow, Jane Doe" "John Hancock"
 780</pre>
 781
 782<strong>Mom</strong> prints each string that's enclosed in
 783double-quotes on a separate line in the
 784<a href="definitions.html#TERMS_DOCHEADER">docheader</a>,
 785however only the first string appears in
 786<a href="definitions.html#TERMS_HEADER">page headers</a>.
 787If you want <strong>mom</strong> to put something else in the author
 788part of page headers (say, just the last names of a document's two
 789authors), redefine the appropriate part of the header (see
 790<a href="headfootpage.html#HEADER_CONTROL">header/footer control</a>).
 791<p>
 792The strings can be caps or caps/lower-case.  I recommend caps/lower
 793case.
 794<p>
 795
 796<!---CHAPTER--->
 797
 798<hr width="66%" align="left">
 799<p>
 800<a name="CHAPTER"></a>
 801<nobr>Macro: <strong>CHAPTER</strong> &lt;chapter number&gt;</nobr>
 802
 803<p>
 804The chapter number can be in any form you like -- a digit, a roman
 805numeral, a word.  If you choose
 806<a href="#DOCTYPE">DOCTYPE CHAPTER</a>,
 807<strong>mom</strong> prints whatever argument you pass
 808<strong>CHAPTER</strong> beside the word &quot;Chapter&quot; as a
 809single line
 810<a href="definitions.html#TERMS_DOCHEADER">docheader</a>.
 811She also puts the same thing in the middle of
 812<a href="definitions.html#TERMS_HEADER">page headers</a>.
 813<p>
 814Please note that if your argument to <strong>CHAPTER</strong> runs
 815to more than one word, you must enclose the argument in
 816double-quotes.
 817<p>
 818If you're not using <strong>DOCTYPE CHAPTER</strong>, the macro serves
 819no purpose and <strong>mom</strong> ignores it.
 820<p>
 821<a name="CHAPTER_STRING"><strong>CHAPTER_STRING</strong></a>
 822<p>
 823If you're not writing in English, you can ask <strong>mom</strong>
 824to use the word for &quot;chapter&quot; in your own language by
 825telling her what it is with the <strong>CHAPTER_STRING</strong>
 826macro, like this:
 827<p>
 828<pre>
 829	.CHAPTER_STRING "Chapître"
 830</pre>
 831
 832You can also use <strong>CHAPTER_STRING</strong> if you want
 833&quot;CHAPTER&quot; instead of &quot;Chapter&quot; in the doc- and
 834page-headers.
 835<p>
 836
 837<!---CHAPTER_TITLE--->
 838
 839<hr width="66%" align="left">
 840<p>
 841<a name="CHAPTER_TITLE"></a>
 842<nobr>Macro: <strong>CHAPTER_TITLE</strong> &quot;&lt;chapter title&gt;&quot;</nobr>
 843<br>
 844<em>*Argument must be enclosed in double-quotes</em>
 845
 846<p>
 847If, either in addition to or instead of &quot;Chapter #&quot; appearing
 848at the top of chapters, you want your chapter to have a title, use
 849<strong>CHAPTER_TITLE</strong>, with your title enclosed in
 850double-quotes, like this:
 851<p>
 852<pre>
 853	.CHAPTER_TITLE "The DMCA Nazis"
 854</pre>
 855
 856If you've used
 857<a href="#CHAPTER">CHAPTER</a> to give the chapter a number,
 858both &quot;Chapter #&quot; and the chapter title will appear at the
 859top of the chapter, like this:
 860<p>
 861<pre>
 862                       Chapter 1
 863                    The DMCA Nazis
 864</pre>
 865
 866In such a case, by default, only the chapter's title will appear in the
 867<a href="definitions.html#TERMS_HEADER">page headers</a>,
 868not &quot;Chapter #&quot;.
 869<p>
 870If you omit <strong>CHAPTER</strong> when setting up your reference
 871macros, only the title will appear, both at the top of page one and in
 872subsequent page headers.
 873<p>
 874The style of the chapter title can be altered by
 875<a href="docelement.html#DOCELEMENT_CONTROL">control macros</a>,
 876e.g. <strong>CHAPTER_TITLE_FAMILY</strong>,
 877<strong>CHAPTER_TITLE_FONT</strong>, etc.  The default family,
 878font and point size are Times Roman, Bold Italic, 4 points larger
 879than
 880<a href="definitions.html#TERMS_RUNNING">running text</a>.
 881<p>
 882
 883<!---DRAFT--->
 884
 885<hr width="66%" align="left">
 886<p>
 887<a name="DRAFT"></a>
 888<nobr>Macro: <strong>DRAFT</strong> &lt;draft #&gt;</nobr>
 889
 890<p>
 891<strong>DRAFT</strong> only gets used with
 892<a href="#COPYSTYLE">COPYSTYLE DRAFT</a>.
 893If the <strong>COPYSTYLE</strong> is <strong>FINAL</strong> (the
 894default), <strong>mom</strong> ignores <strong>DRAFT</strong>.
 895<strong>DRAFT</strong> accepts both alphabetic and numeric
 896arguments, hence it's possible to do either
 897<p>
 898<pre>
 899	.DRAFT 2
 900	   or
 901	.DRAFT Two
 902</pre>
 903
 904<strong>Mom</strong> prints the argument to <strong>.DRAFT</strong>
 905(i.e. the draft number) beside the word &quot;Draft&quot; in the
 906middle part of
 907<a href="definitions.html#TERMS_HEADER">page headers</a>.
 908<p>
 909<strong>A small word of caution:</strong> If your argument to
 910<strong>.DRAFT</strong> is more than one word long, you must
 911enclose the argument in double-quotes.
 912<p>
 913You may, if you wish, invoke <strong>.DRAFT</strong> without an
 914argument, in which case, no draft number will be printed beside
 915&quot;Draft&quot; in headers or footers.
 916<p>
 917<a name="DRAFT_STRING"><strong>DRAFT_STRING</strong></a>
 918<p>
 919If you're not writing in English, you can ask <strong>mom</strong>
 920to use the word for &quot;draft&quot; in your own language by
 921telling her what it is with the <strong>DRAFT_STRING</strong> macro,
 922like this:
 923<p>
 924<pre>
 925	.DRAFT_STRING "Jet"
 926</pre>
 927
 928Equally, <strong>DRAFT_STRING</strong> can be used to roll your own
 929solution to something other than the word &quot;Draft.&quot;  For
 930example, you might want &quot;Trial run alpha-three&quot; to appear
 931in the headers of a draft version.  You'd accomplish this by doing
 932<p>
 933<pre>
 934	.DRAFT alpha-three
 935	.DRAFT_STRING "Trial run
 936</pre>
 937
 938<strong>.DRAFT</strong> without an argument, above, ensures that
 939only the <strong>DRAFT_STRING</strong> gets printed.
 940<p>
 941<strong>NOTE:</strong> If you define both a blank <strong>.DRAFT</strong>
 942and a blank <strong>.DRAFT_STRING</strong>, <strong>mom</strong>
 943skips the draft field in headers entirely.  If this is what you
 944want, this is also the only way to do it.  Simply leaving out
 945<strong>.DRAFT</strong> and <strong>.DRAFT_STRING</strong> will
 946result in <strong>mom</strong> using her default, which is to print
 947&quot;Draft 1&quot;.
 948<p>
 949
 950<!---REVISION--->
 951
 952<hr width="66%" align="left">
 953<p>
 954<a name="REVISION"></a>
 955<nobr>Macro: <strong>REVISION</strong> &lt;revision #&gt;</nobr>
 956
 957<p>
 958<strong>REVISION</strong> only gets used with
 959<a href="#COPYSTYLE">COPYSTYLE DRAFT</a>.
 960If the <strong>COPYSTYLE</strong> is <strong>FINAL</strong>
 961(the default), <strong>mom</strong> ignores the
 962<strong>REVISION</strong> macro. <strong>REVISION</strong> accepts
 963both alphabetic and numeric arguments, hence it's possible to do
 964either
 965<p>
 966<pre>
 967	.REVISION 2
 968	   or
 969	.REVISION Two
 970</pre>
 971
 972<strong>Mom</strong> prints the revision number beside the shortform
 973&quot;Rev.&quot; in the middle part of
 974<a href="definitions.html#TERMS_HEADER">page headers</a>.
 975<p>
 976<strong>A small word of caution:</strong> If your argument to
 977<strong>.REVISION</strong> is more than one word long, you must
 978enclose the argument in double-quotes.
 979<p>
 980You may, if you wish, invoke <strong>.REVISION</strong> without an
 981argument, in which case, no revision number will be printed beside
 982&quot;Rev.&quot; in headers or footers.
 983<p>
 984<a name="REVISION_STRING"><strong>REVISION_STRING</strong></a>
 985<p>
 986If you're not writing in English, you can ask <strong>mom</strong>
 987to use the word for &quot;revision,&quot; or a shortform
 988thereof, in your own language by telling her what it is with the
 989<strong>REVISION_STRING</strong> macro, like this:
 990<p>
 991<pre>
 992	.REVISION_STRING "Rév."
 993</pre>
 994
 995Additionally, you may sometimes want to make use of
 996<strong>mom</strong>'s
 997<a href="#COPYSTYLE">COPYSTYLE DRAFT</a>
 998but not actually require any draft information.  For example, you
 999might like <strong>mom</strong> to indicate only the revision number
1000of your document.  The way to do that is to define an empty
1001<strong>.DRAFT</strong> and <strong>.DRAFT_STRING</strong> in
1002addition to <strong>.REVISION</strong>, like this:
1003<p>
1004<pre>
1005	.DRAFT
1006	.DRAFT_STRING
1007	.REVISION 2
1008</pre>
1009
1010<p>
1011Equally, if you want to roll your own solution to what revision
1012information appears in headers, you could do something like this:
1013<pre>
1014	.DRAFT
1015	.DRAFT_STRING
1016	.REVISION "two-twenty-two"
1017	.REVISION_STRING "Revision"
1018</pre>
1019
1020<p>
1021The above, naturally, has no draft information.  If you want to
1022roll your own <strong>.DRAFT</strong> and/or
1023<strong>.DRAFT_STRING</strong> as well, simply supply arguments to
1024either or both.
1025<p>
1026
1027<!---COPYRIGHT--->
1028
1029<hr width="66%" align="left">
1030<p>
1031<a name="COPYRIGHT"></a>
1032<nobr>Macro: <strong>COPYRIGHT</strong> &quot;&lt;copyright info&gt;&quot;</nobr>
1033<br>
1034<em>*Argument must be enclosed in double-quotes</em>
1035
1036<p>
1037The argument passed to <strong>COPYRIGHT</strong> is only used on
1038cover or doc cover pages, and then only if the argument COPYRIGHT is
1039passed to
1040<a href="cover.html#COVER">COVER</a>
1041or
1042<a href="cover.html#DOC_COVER">DOC_COVER</a>.
1043Do not include the copyright symbol in the argument passed to
1044<strong>COPYRIGHT</strong>; <strong>mom</strong> puts it in for
1045you.
1046<p>
1047
1048<!---MISC--->
1049
1050<hr width="66%" align="left">
1051<p>
1052<a name="MISC"></a>
1053<nobr>Macro: <strong>MISC</strong> &quot;&lt;argument 1&gt;&quot; [&quot;&lt;argument 2&gt;&quot; &quot;&lt;argument 3&gt;&quot; ...]</nobr>
1054<br>
1055<em>*Multliple arguments must all be enclosed in double-quotes</em>
1056
1057<p>
1058The argument(s) passed to <strong>MISC</strong> are only used on
1059cover or doc cover pages, and then only if the argument MISC is
1060passed to
1061<a href="cover.html#COVER">COVER</a>
1062or
1063<a href="cover.html#DOC_COVER">DOC_COVER</a>.
1064<strong>MISC</strong> can contain any information you like.  Each
1065argument appears on a separate line at the bottom of the cover or
1066doc cover page.
1067<p>
1068For example, if you're submitting an essay where the prof has
1069requested that you include the course number, his name and the
1070date, you could do
1071<p>
1072<pre>
1073	.MISC &quot;Music History 101&quot; &quot;Professor Hasbeen&quot; &quot;Dec. 24, 2006&quot;
1074</pre>
1075
1076and the information would appear on the essay's cover page.
1077<p>
1078
1079<!---COVER_TITLE--->
1080
1081<hr width="66%" align="left">
1082<p>
1083<a name="COVERTITLE"></a>
1084<nobr>Macro: <strong>COVERTITLE</strong> &quot;&lt;user defined cover page title&gt;&quot;</nobr>
1085<br>
1086<nobr>Macro: <strong>DOC_COVERTITLE</strong> &quot;&lt;user defined document cover page title&gt;&quot;</nobr>
1087<br>
1088<em>*Argument must be enclosed in double-quotes</em>
1089
1090<p>
1091The argument passed to <strong>COVERTITLE</strong> or
1092<strong>DOC_COVERTITLE</strong> is only used on cover or doc cover
1093pages, and then only if the argument COVERTITLE is passed to
1094<a href="cover.html#COVER">COVER</a>
1095or
1096<a href="cover.html#DOC_COVER">DOC_COVER</a>.
1097<p>
1098The only time you require a <strong>COVERTITLE</strong> or
1099<strong>DOC_COVERTITLE</strong>is when none of the required first
1100arguments to <strong>COVER</strong> or <strong>DOC_COVER</strong>
1101fits your needs for the title you want to appear on cover (or doc
1102cover) pages.
1103
1104<p>
1105<hr>
1106<!========================================================================>
1107
1108<a name="DOCSTYLE_MACROS">
1109	<h2><u>The Docstyle Macros</u></h2>
1110</a>
1111
1112The docstyle macros tell <strong>mom</strong> what type of document you're
1113writing, whether you want the output typeset or
1114&quot;typewritten&quot;, and whether you want a draft copy (with
1115draft and revision information in the headers) or a final copy.
1116
1117<a name="INDEX_DOCSTYLE">
1118	<h3><u>Docstyle macros list</u></h3>
1119</a>
1120
1121<ul>
1122	<li><a href="#DOCTYPE">DOCTYPE</a>
1123	<li><a href="#PRINTSTYLE">PRINTSTYLE</a>
1124	<ul>
1125		<li><a href="#TYPESET_DEFAULTS">Defaults for PRINTSTYLE TYPESET</a>
1126		<li><a href="#TYPEWRITE_DEFAULTS">Defaults for PRINTSTYLE TYPEWRITE</a>
1127		<ul>
1128			<li><a href="#TYPEWRITE_CONTROL">TYPEWRITE control macros</a>
1129		</ul>
1130	</ul>
1131	<li><a href="#COPYSTYLE">COPYSTYLE</a>
1132</ul>
1133<br>
1134
1135<!---DOCTYPE--->
1136
1137<hr width="66%" align="left">
1138<p>
1139<a name="DOCTYPE"></a>
1140<nobr>Macro: <strong>DOCTYPE</strong> DEFAULT | CHAPTER | NAMED &quot;&lt;name&gt;&quot; | LETTER</nobr>
1141<p>
1142The arguments <strong>DEFAULT, CHAPTER</strong> and
1143<strong>NAMED</strong> tell <strong>mom</strong> what to put
1144in the
1145<a href="definitions.html#TERMS_DOCHEADER">docheader</a>
1146and
1147<a href="definitions.html#TERMS_HEADER">page headers</a>.
1148<strong>LETTER</strong> tells her that you want to write a
1149letter.
1150<p>
1151<strong>Mom</strong>'s default <strong>DOCTYPE</strong> is
1152<strong>DEFAULT</strong>.  If that's what you want, you don't
1153have to give a <strong>DOCTYPE</strong> command.
1154<p>
1155<strong>DEFAULT</strong> prints a
1156<a href="definitions.html#TERMS_DOCHEADER">docheader</a>
1157containing the title, subtitle and author information given to the
1158<a href="#REFERENCE_MACROS">reference macros</a>,
1159and page headers with the author and title.
1160(See
1161<a href="headfootpage.html#HEADER_STYLE">Default specs for headers</a>
1162for how <strong>mom</strong> outputs each part of the page header.)
1163<p>
1164<strong>CHAPTER</strong> prints &quot;Chapter #&quot; in place of a
1165<a href="definitions.html#TERMS_DOCHEADER">docheader</a>
1166(# is what you gave to the
1167<a href="#REFERENCE_MACROS">reference macro</a>
1168<a href="#CHAPTER">CHAPTER</a>).
1169If you give the chapter a title with
1170<a href="#CHAPTER_TITLE">CHAPTER TITLE</a>,
1171<strong>mom</strong> prints &quot;Chapter #&quot; and the title
1172underneath.  If you omit the
1173<a href="#CHAPTER">CHAPTER</a>
1174reference macro but supply a
1175<a href="#CHAPTER_TITLE">CHAPTER_TITLE</a>,
1176<strong>mom</strong> prints only the chapter title. <em>(*For
1177backward compatibility with pre-1.1.5 versions of</em>
1178<strong>mom</strong><em>, you can also supply a chapter title by
1179omitting the</em> <strong>CHAPTER</strong> <em>reference macro and
1180supplying a chapter title with</em>
1181<a href="#CHAPTER_STRING">CHAPTER_STRING</a>.)
1182<p>
1183The page headers in <strong>DOCTYPE CHAPTER</strong> contain the author,
1184the title of the book (which you gave with
1185<a href="#TITLE">TITLE</a>),
1186and &quot;Chapter #&quot; (or the chapter title).  See
1187<a href="headfootpage.html#HEADER_STYLE">Default Specs for Headers</a>
1188for <strong>mom</strong>'s default type parameters for each part of
1189the page header.
1190<p>
1191<strong>NAMED</strong> takes an additional argument: a name
1192for this particular kind of document  (e.g. outline, synopsis,
1193abstract, memorandum), enclosed in double-quotes.
1194<strong>NAMED</strong> is identical to <strong>DEFAULT</strong>
1195except that <strong>mom</strong> prints the argument to
1196<strong>NAMED</strong> beneath the
1197<a href="definitions.html#TERMS_DOCHEADER">docheader</a>,
1198as well as in page headers.
1199(See
1200<a href="headfootpage.html#HEADER_STYLE">Default specs for headers</a>
1201for how <strong>mom</strong> outputs each part of the page header.)
1202<p>
1203Additionally, if you wish the name of this particular kind of
1204document to be coloured, you can pass <strong>DOCTYPE NAMED</strong>
1205a third (optional) argument: the name of a colour pre-defined (or
1206&quot;initialized&quot;) with
1207<a href="color.html#NEWCOLOR">NEWCOLOR</a>
1208or
1209<a href="color.html#XCOLOR">XCOLOR</a>.
1210For example, if you have a doctype named &quot;Warning&quot;, and
1211you'd like &quot;Warning&quot; to be in red, assuming you've
1212pre-defined (or &quot;initialized&quot;) the color, red, this is
1213what the <strong>DOCTYPE</strong> entry would look like:
1214<p>
1215<pre>
1216	.DOCTYPE NAME "Warning" red
1217</pre>
1218
1219<p>
1220<strong>LETTER</strong> tells mom you're writing a letter.  See
1221the section
1222<a href="letters.html#INTRO">Writing Letters</a>
1223for instructions on using <strong>mom</strong> to format letters.
1224<p>
1225
1226<!---PRINTSTYLE--->
1227
1228<hr width="66%" align="left">
1229<p>
1230<a name="PRINTSTYLE"></a>
1231<nobr>Macro: <strong>PRINTSTYLE</strong> TYPESET | TYPEWRITE [ SINGLESPACE ]</nobr>
1232<br>
1233<em>*Required for document processing.</em>
1234<br>
1235<em>*Must come before any changes to default document style</em>
1236
1237<p>
1238<strong>PRINTSTYLE</strong> tells <strong>mom</strong> whether to typeset
1239a document, or to print it out &quot;typewritten, doubled-spaced&quot;.
1240<p>
1241<strong>THIS MACRO MAY NOT BE OMITTED.</strong>  In order for
1242document processing to take place, <strong>mom</strong> requires
1243a <strong>PRINTSTYLE</strong>.  If you don't give one,
1244<strong>mom</strong> will warn you on stderr and print a single
1245page with a nasty message.
1246<p>
1247Furthermore, <strong>PRINTSTYLE</strong> must come before any
1248changes to <strong>mom</strong>'s default typestyle parameters.
1249(This applies primarily to, but is by no means restricted to,
1250<strong>PRINTSTYLE TYPESET</strong>.)  <strong>PRINTSTYLE</strong>
1251sets up complete &quot;templates&quot; that include default
1252papersize, margins, family, fonts, point sizes, and so on.
1253Therefore, changes to any aspect of document style must come
1254afterwards.
1255<p>
1256<strong>TYPESET</strong>, as the argument implies, typesets documents
1257(by default in Times Roman; see
1258<a href="#TYPESET_DEFAULTS">TYPESET defaults</a>).
1259You have full access to all the
1260<a href="typesetting.html#MACROS_TYPESETTING">typesetting macros</a>
1261as well as the
1262<a href="definitions.html#STYLE_CONTROL">style control macros</a>
1263of document processing.
1264<p>
1265As mentioned above, <strong>PRINTSTYLE TYPESET</strong> must come
1266before any changes to <strong>mom</strong>'s default typographic
1267settings.  For example,
1268
1269<pre>
1270	.PAPER A4
1271	.LS 14
1272	.PRINTSTYLE TYPESET
1273</pre>
1274
1275will not changes <strong>mom</strong>'s default paper size to A4,
1276nor her default document leading 14 points, whereas
1277
1278<pre>
1279	.PRINTSTYLE TYPESET
1280	.PAPER A4
1281	.LS 14
1282</pre>
1283
1284will.
1285<p>
1286With <strong>TYPEWRITE</strong>, <strong>mom</strong> does her best
1287to reproduce the look and feel of typewritten, double-spaced copy (see
1288<a href="#TYPEWRITE_DEFAULTS">TYPEWRITE defaults</a>).
1289<a href="docelement.html#DOCELEMENT_CONTROL">Control macros</a>
1290and
1291<a href="typesetting.html#INTRO_MACROS_TYPESETTING">typesetting macros</a>
1292that alter family, font, point size, and
1293<a href="definitions.html#TERMS_LEADING">leading</a>
1294are (mostly) ignored.  An important exception is
1295<a href="headfootpage.html#HDRFTR_GLOBAL_SIZE">HEADER_SIZE</a>
1296(and, by extension, <strong>FOOTER_SIZE</strong>), which allows
1297you to reduce the point size of headers/footers should they become
1298too crowded.  Most of <strong>mom</strong>'s inlines affecting the
1299appearance of type are also ignored (<strong>\*S</strong> is an
1300exception; there may be a few others).
1301<p>
1302In short, <strong>TYPEWRITE</strong> never produces effects other than
1303those available on a typewriter.  Don't be fooled by how brainless
1304this sounds; <strong>mom</strong> is remarkably sophisticated when
1305it comes to conveying the typographic sense of a document within the
1306confines of <strong>TYPEWRITE</strong>.
1307<p>
1308The primary uses of <strong>TYPEWRITE</strong> are: outputting hard
1309copy drafts of your work (for editing), and producing documents
1310for submission to publishers and agents who (wisely) insist on
1311typewritten, double-spaced copy. To get a nicely typeset version of
1312work that's in the submission phase of its life (say, to show fellow
1313writers for critiquing), simply change <strong>TYPEWRITE</strong>
1314to <strong>TYPESET</strong> and print out a copy.
1315<p>
1316If, for some reason, you would prefer the output of
1317<strong>TYPEWRITE</strong> single-spaced, pass <strong>PRINTSTYLE
1318TYPEWRITE</strong> the optional argument, <strong>SINGLESPACE</strong>.
1319<p>
1320If you absolutely must have a leading other than typewriter double-
1321or singlespaced, the only way to get it is with the
1322<a href="#DOC_LEAD">DOC_LEAD</a>
1323macro, and then ONLY if <strong>DOC_LEAD</strong> is set
1324<strong>before</strong> you invoke the <strong>START</strong>
1325macro.
1326<p>
1327<a name="TYPESET_DEFAULTS"><h3><u>TYPESET defaults</u></h3></a>
1328<pre>
1329	Family            = Times Roman
1330	Point size        = 12.5
1331	Paragraph leading = 16 points, adjusted
1332	Fill mode         = justified
1333	Hyphenation       = enabled
1334	                    max. lines = 2
1335	                    margin = 36 points
1336	                    interword adjustment = 1 point
1337	Kerning           = enabled
1338	Ligatures         = enabled
1339	Smartquotes       = enabled
1340	Word space        = groff default
1341	Sentence space    = 0
1342</pre>
1343
1344<a name="TYPEWRITE_DEFAULTS"><h3><u>TYPEWRITE defaults</u></h3></a>
1345<pre>
1346	Family            = Courier
1347	Italics           = underlined
1348	Point size        = 12
1349	Paragraph leading = 24 points, adjusted; 12 points for SINGLESPACE
1350	Fill mode         = left
1351	Hyphenation       = disabled
1352	Kerning           = disabled
1353	Ligatures         = disabled
1354	Smartquotes       = disabled
1355	Word space        = groff default
1356	Sentence space    = groff default
1357	Columns           = ignored
1358</pre>
1359
1360<a name="TYPEWRITE_CONTROL"><h3><u>PRINTSTYLE TYPEWRITE control macros</u></h3></a>
1361<p>
1362In <strong>PRINTSTYLE TYPEWRITE</strong>, <strong>mom</strong>,
1363by default, underlines anything that looks like italics.  This
1364includes the
1365<a href="typesetting.html#SLANT_INLINE">\*[SLANT]</a>
1366<a href="definitions.html#TERMS_INLINES">inline escape</a>
1367for pseudo-italics.
1368<p>
1369If you'd prefer that <strong>mom</strong> were
1370less bloody-minded about pretending to be a typewriter (i.e.
1371you'd like italics and pseudo-italics to come out as italics),
1372use the control macros <strong>.ITALIC_MEANS_ITALIC</strong> and
1373<strong>.SLANT_MEANS_SLANT</strong>.  Neither requires an
1374argument.
1375<p>
1376Although it's unlikely, should you wish to reverse the sense of
1377these macros in the midst of a document,
1378<strong>.UNDERLINE_ITALIC</strong> and
1379<strong>.UNDERLINE_SLANT</strong> restore underlining of
1380italics and pseudo-italics.
1381<p>
1382<a name="UNDERLINE_QUOTES"></a>
1383Additionally, by default, <strong>mom</strong> underlines
1384<a href="definitions.html#TERMS_QUOTES">quotes</a>
1385(but not
1386<a href="definitions.html#TERMS_BLOCKQUOTES">blockquotes</a>)
1387in <strong>PRINTSTYLE TYPEWRITE</strong>.
1388If you don't like this behaviour, turn it off with
1389<p>
1390<pre>
1391	.UNDERLINE_QUOTES OFF
1392</pre>
1393
1394To turn underlining of quotes back on, use
1395<strong>UNDERLINE_QUOTES</strong> without an argument.
1396<p>
1397While most of the
1398<a href="docelement.html#DOCELEMENT_CONTROL">control macros</a>
1399have no effect on <strong>PRINTSTYLE TYPEWRITE</strong>, there
1400is an important exception:
1401<a href="headfootpage.html#HDRFTR_GLOBAL_SIZE">HEADER_SIZE</a>
1402(and by extension, <strong>FOOTER_SIZE</strong>).  This is
1403particularly useful for reducing the point size of
1404headers/footers should they become crowded (quite likely to
1405happen if the title of your document is long and your
1406<a href="#COPYSTYLE">COPYSTYLE</a>
1407is <strong>DRAFT</strong>).
1408<p>
1409
1410<!---COPYSTYLE--->
1411
1412<hr width="66%" align="left">
1413<p>
1414<a name="COPYSTYLE"></a>
1415<nobr>Macro: <strong>COPYSTYLE</strong> D…

Large files files are truncated, but you can click here to view the full file