contrib/mom/momdoc/cover.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-2018  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 no
  11 Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
  12 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, creating cover pages</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="tables-of-contents.html#top">Next: Tables of contents</a></td>
  38 </tr>
  39 </table>
  40
  41 <h1 class="docs">Creating cover pages</h1>
  42
  43 <div style="width: 66%; margin: auto;">
  44 <ul class="no-enumerator">
  45   <li><a href="#cover-intro">Introduction to cover pages</a>
  46   <ul style="margin-left: -.5em; list-style-type: disc;">
  47     <li><a href="#important-note">Important note</a></li>
  48     <li><a href="#desc">Description of cover pages</a></li>
  49     <li><a href="#pagination">Headers/footers/pagination</a>
  50       <ul style="margin-left: -1.25em; list-style-type: circle;">
  51         <li><a href="#pagination">DOC_COVERS_COUNT_PAGES</a></li>
  52         <li><a href="#pagination">COVERS_COUNT_PAGES</a></li>
  53       </ul>
  54     </li>
  55     <li><a href="#design">Designing your own cover pages</a></li>
  56     <li><a href="#persistence">Persistence of data and formatting</a></li>
  57   </ul></li>
  58   <li><a href="#index-covers">Doc-cover and cover macros</a>
  59   <ul style="margin-left: -.5em; list-style-type: disc;">
  60     <li><a href="#cover">DOC_COVER / COVER</a>
  61     <ul style="margin-left: -1.25em; list-style-type: circle;">
  62       <li><a href="#cover-args">The argument list: saying what goes on doc-cover and cover pages</a></li>
  63       <li><a href="#meanings">What the arguments mean</a></li>
  64       <li><a href="#chapter">How the CHAPTER argument and friends work</a></li>
  65     </ul></li>
  66     <li><a href="#covertext">DOC_COVERTEXT / COVERTEXT</a>
  67       <ul style="margin-left: -1.25em; list-style-type: circle;">
  68         <li><a href="#placement">Placement</a></li>
  69       </ul>
  70     </li>
  71     <li><a href="#coverimage">DOC_COVER_IMAGE / COVER_IMAGE</a>
  72       <ul style="margin-left: -1.25em; list-style-type: circle;">
  73         <li><a href="#positioning">Positioning of doc-cover and cover images</a></li>
  74       </ul>
  75     </li>
  76   </ul></li>
  77   <li><a href="#on-off">Enabling/disabling automatic generation of cover pages</a></li>
  78   <li><a href="#cover-control">Control macros for covers and doc-covers</a></li>
  79 </ul>
  80 </div>
  81
  82 <div class="rule-medium"><hr/></div>
  83
  84 <h2 id="cover-intro" class="docs">Introduction to cover pages</h2>
  85
  86 <p>
  87 Though identical in treatment, mom provides two kinds of cover
  88 pages: document cover pages (&#8221;doc-covers&#8221;), and section
  89 cover pages (which I shall refer to simply as cover pages).
  90 </p>
  91
  92 <p>
  93 A doc-cover is what you&#8217;d most likely use at the start of a
  94 collated document, where you might want the name of the complete
  95 document, the author(s) and the copyright line to appear.  Another
  96 place you might use a doc-cover is for a novel, where you want the
  97 title of the novel, not the chapter title or chapter number, as the
  98 first cover page.
  99 </p>
 100
 101 <p>
 102 A cover is what you&#8217;d use for pages that separate sections
 103 of a collated document, ie title pages.  A cover page (but not a
 104 doc-cover) in a collated document could, for example, simply read:
 105 &#8221;PART 1&#8221;.
 106 </p>
 107
 108 <p>
 109 In non-collated documents (say, an essay) you can use either a cover
 110 or doc-cover to generate the cover sheet.
 111 </p>
 112
 113 <p>
 114 In addition, nothing prevents you from generating both a doc-cover
 115 and a cover for every document in a collated document.  Or you can
 116 selectively disable the automatic generation of either doc-covers or
 117 covers in a collated document on-the-fly.
 118 </p>
 119
 120 <div id="important-note" class="box-important">
 121 <p class="tip">
 122 <span class="important">Important note:</span>
 123 Automatic generation of covers or doc-covers after the first one(s)
 124 only takes place if you are working with collated documents.  Mom
 125 provides no mechanism for saying &#8221;print a section cover
 126 here even though I'm still working on the same (non-collated)
 127 document.&#8221;
 128 </p>
 129 </div>
 130
 131 <h3 id="desc" class="docs">Description of cover pages</h3>
 132
 133 <p>
 134 By default, mom typesets covers and doc-covers  identically to
 135 <a href="definitions.html#docheader">docheaders</a>
 136 (see
 137 <a href="docprocessing.html#docheader-control">How to change the look of docheaders</a>
 138 for a description of what a docheader looks like).  The only
 139 differences are
 140 </p>
 141 <ul style="margin-top: -.5em;  margin-bottom: -.5em;">
 142   <li>the position on the page where the information is output</li>
 143   <li>the (optional) addition of copyright and miscellaneous information</li>
 144   <li>there&#8217;s no running text underneath, although you can add text
 145       to a cover or doc-cover (for example, an Abstract) with
 146       <a href="#covertext">COVERTEXT</a>
 147    </li>
 148 </ul>
 149
 150 <p>
 151 You tell mom what you want to appear on cover pages through the
 152 arguments you pass to
 153 <a href="#cover">DOC_COVER</a>
 154 and/or
 155 <a href="#cover">COVER</a>.
 156 Provided you have already given mom the appropriate reference macros
 157 (e.g.,
 158 <a href="docprocessing.html#title">TITLE</a>
 159 or
 160 <a href="docprocessing.html#author">AUTHOR</a>),
 161 she will output covers and doc-covers identically to how she
 162 would output docheaders containing the same information.
 163 </p>
 164
 165 <p>
 166 By default, mom starts covers and doc-covers one-third of the way
 167 down the page.  This can be changed through the use of the control
 168 macros DOC_COVER_START_POS / COVER_START_POS (or DOC_COVER_ADVANCE /
 169 COVER_ADVANCE).
 170 </p>
 171
 172 <p>
 173 If you request copyright information (and have already given mom the
 174 reference macro
 175 <a href="docprocessing.html#copyright">COPYRIGHT</a>)
 176 she sets it, by default, in a smaller
 177 <a href="definitions.html#ps">point size</a>
 178 in the bottom right hand corner of the cover or doc-cover.  The
 179 position, as well as all of the standard typesetting parameters, can be
 180 altered via control macros.
 181 </p>
 182
 183 <p>
 184 Similarly, if you request miscellaneous information (and have
 185 already given mom the reference macro
 186 <a href="docprocessing.html#misc">MISC</a>)
 187 she sets it, by default, in a smaller point size in the bottom left
 188 hand corner of the cover or doc-cover.  As with the copyright, the
 189 position and type specs can be altered via control macros.
 190 </p>
 191
 192 <h3 id="pagination" class="docs">Headers/footers/pagination</h3>
 193
 194 <p>
 195 Mom does not set any
 196 <a href="definitions.html#header">headers</a>
 197 or
 198 <a href="definitions.html#footer">footers</a>
 199 on cover pages.  Neither does she set any page numbers.  From
 200 the point of view of pagination, covers and doc-covers are by
 201 default considered &#8221;null&#8221; pages.  If you wish them to
 202 be included in the pagination scheme (even though no page numbers
 203 appear), you must tell mom that&#8217;s what you want by invoking
 204 <br/>
 205 <span class="pre-in-pp">
 206   .DOC_COVERS_COUNT_PAGES
 207 </span>
 208 or
 209 <br/>
 210 <span class="pre-in-pp">
 211   .COVERS_COUNT_PAGES
 212 </span>
 213 </p>
 214
 215 <h3 id="design" class="docs">Designing your own cover pages</h3>
 216
 217 <p>
 218 Finally, if you want to design your own cover page(s), you can
 219 typeset them by hand inside a
 220 <a href="#covertext">COVERTEXT</a>
 221 block using mom&#8217;s typesetting macros to format the text.
 222 </p>
 223
 224 <h3 id="persistence" class="docs">Persistence of data and formatting</h3>
 225
 226 <p>
 227 Doc-cover and cover data&mdash;that is to say, the strings passed to
 228 reference macros that appear on doc-cover and cover
 229 pages&mdash;does not persist after
 230 <a href="docprocessing.html#start">START</a>,
 231 however the formatting of the various parts (TITLE, AUTHOR,
 232 COPYRIGHT, etc.) does.
 233 </p>
 234
 235 <div class="macro-list-container">
 236 <h3 id="index-covers" class="macro-list">Cover and document cover macros</h3>
 237 <ul class="macro-list">
 238   <li><a href="#cover">DOC_COVER and COVER</a>
 239   <ul style="margin-left: -.5em; list-style-type: disc;">
 240     <li><a href="#cover-args">The arguments: saying what goes on doc-cover and cover pages</a></li>
 241   </ul></li>
 242   <li><a href="#covertext">DOC_COVERTEXT / COVERTEXT</a></li>
 243   <li><a href="#coverimage">DOC_COVER_IMAGE / COVER_IMAGE</a></li>
 244   <li><a href="#on-off">Enabling/disabling automatic generation of cover pages</a>
 245   <ul style="margin-left: -.5em; list-style-type: disc;">
 246     <li><a href="#doc-covers">DOC_COVERS</a></li>
 247     <li><a href="#covers">COVERS</a></li>
 248   </ul></li>
 249   <li><a href="#cover-control">Control macros for doc-covers and covers</a></li>
 250 </ul>
 251 </div>
 252
 253 <!-- -COVER- -->
 254
 255 <div class="macro-id-overline">
 256 <h3 id="cover" class="macro-id">DOC_COVER and COVER</h3>
 257 </div>
 258
 259 <div id="doc-cover" class="box-macro-args">
 260 Macro: <b>DOC_COVER</b> <kbd class="macro-args">(see argument list, below)</kbd>
 261 </div>
 262
 263 <div class="box-macro-args" style="margin-top: 1em;">
 264 Macro: <b>COVER</b> <kbd class="macro-args">(see argument list, below)</kbd>
 265 </div>
 266
 267 <p>
 268 DOC_COVER and COVER behave identically.  The reason mom provides
 269 two macros for cover page generation is so that you can have two
 270 different kinds of covers with different information on each.
 271 </p>
 272
 273 <p>
 274 Imagine, for a moment, you&#8217;ve written a document comprised of
 275 three sections.  When you
 276 <a href="rectoverso.html#collate">COLLATE</a>
 277 the document for output, you could use DOC_COVER to generate a cover
 278 page that contained the name of the entire document, your (the
 279 author&#8217;s) name, and perhaps the copyright date.  Subsequently,
 280 you could use COVER, after each <kbd>.COLLATE</kbd> but before each
 281 <kbd><a href="docprocessing.html#start">.START</a></kbd>,
 282 to generate a cover page (title page, cover sheet) containing
 283 just the name of the section, for example, &#8220;Part 1&#8221;.
 284 </p>
 285
 286 <p>
 287 The arguments to <kbd>DOC_COVER</kbd> and <kbd>COVER</kbd> tell mom
 288 what you&#8217;d like on cover pages.  You may give as many or as
 289 few arguments as you need, in any order.  A very common setup would
 290 be:
 291 <br/>
 292 <span class="pre-in-pp">
 293   .COVER TITLE AUTHOR COPYRIGHT
 294 </span>
 295 </p>
 296
 297 <h4 id="cover-args" class="docs" style="margin-top: -1em;">The argument list</h4>
 298
 299 <p style="margin-top: 1em">
 300 The arguments to <kbd>COVER</kbd> and <kbd>DOC_COVER</kbd> tell mom
 301 what you want on the cover page:
 302 <br/>
 303 <span class="pre-in-pp">
 304   TITLE | DOCTITLE | DOC_COVERTITLE | COVERTITLE
 305   CHAPTER | CHAPTER_TITLE | CHAPTER+TITLE
 306   SUBTITLE
 307   AUTHOR
 308   DOCTYPE
 309   DOC_COVERTEXT | COVERTEXT
 310   DOC_COVER_IMAGE | COVER_IMAGE
 311   COPYRIGHT
 312   MISC
 313   PDF_OUTLINE_LABEL "&lt;label&gt;"
 314   BLANKPAGE
 315 </span>
 316 </p>
 317
 318 <h4 id="meanings" class="docs" style="margin-top: -1em;">What the arguments mean</h4>
 319
 320 <dl>
 321   <dt class="params">TITLE</dt>
 322     <dd class="cover-args">&ndash; the string(s) you gave to
 323       <a href="docprocessing.html#title">TITLE</a>
 324     </dd>
 325   <dt class="params">DOCTITLE</dt>
 326     <dd class="cover-args">&ndash; the string(s) you gave to
 327       <a href="docprocessing.html#doc-title">DOCTITLE</a>
 328     </dd>
 329   <dt class="params">DOC_COVERTITLE / COVERTITLE</dt>
 330     <dd class="cover-args">&ndash; the string(s) you gave to
 331       <a href="docprocessing.html#doc-covertitle">DOC_COVERTITLE</a>
 332       or
 333       <a href="docprocessing.html#covertitle">COVERTITLE</a>
 334     </dd>
 335   <dt class="params">CHAPTER, CHAPTER_TITLE, CHAPTER+TITLE</dt>
 336     <dd class="cover-args">&ndash; see below,
 337       <a href="#chapter">How the CHAPTER argument and friends work</a>
 338     </dd>
 339   <dt class="params">SUBTITLE</dt>
 340     <dd class="cover-args">&ndash; the string(s) you gave to
 341       <a href="docprocessing.html#subtitle">SUBTITLE</a>
 342     </dd>
 343   <dt class="params">AUTHOR</dt>
 344     <dd class="cover-args">&ndash; the string(s) you gave to
 345       <a href="docprocessing.html#author">AUTHOR</a>
 346     </dd>
 347   <dt class="params">DOCTYPE</dt>
 348     <dd class="cover-args">&ndash; the string you gave to
 349       <a href="docprocessing.html#doctype">DOCTYPE NAMED</a>
 350     </dd>
 351   <dt class="params">DOC_COVERTEXT / COVERTEXT</dt>
 352     <dd class="cover-args">&ndash; the block of type you entered for
 353       <a href="#covertext">DOC_COVERTEXT</a>
 354       or
 355       <a href="#covertext">COVERTEXT</a>
 356     </dd>
 357   <dt class="params">DOC_COVER_IMAGE / COVER_IMAGE</dt>
 358     <dd class="cover-args">&ndash; the image file you gave to
 359       <a href="#covertext">DOC_COVER_IMAGE</a>
 360       or
 361       <a href="#covertext">COVER_IMAGE</a>
 362     </dd>
 363   <dt class="params">COPYRIGHT</dt>
 364     <dd class="cover-args">&ndash; the string you gave to
 365       <a href="docprocessing.html#copyright">COPYRIGHT</a>
 366     </dd>
 367   <dt class="params">MISC</dt>
 368     <dd class="cover-args">&ndash; the string(s) you gave to
 369       <a href="docprocessing.html#misc">MISC</a>
 370     </dd>
 371   <dt class="params">PDF_OUTLINE_LABEL &lt;label&gt;</dt>
 372     <dd class="cover-args">
 373       <span style="display:block; margin-left: 1em">
 374       By default, mom identifies doc-covers in the outline panel of PDF
 375       viewers with the prepended label, &#8220;Cover:&#8221;, and covers
 376       with the label &#8220;Title Page:&#8221;.  If you would like
 377       to change the label, give the <kbd>PDF_OUTLINE_LABEL</kbd>
 378       argument to DOC_COVER or COVER along with the new label, in
 379       quotation marks, as in this example:
 380       <br/>
 381       <kbd>&nbsp;&nbsp;.COVER TITLE AUTHOR COPYRIGHT PDF_LABEL "Cover Sheet: "</kbd>
 382       </span>
 383     </dd>
 384   <dt class="params">BLANKPAGE</dt>
 385     <dd class="cover-args">
 386       <span style="display:block; margin-left: 1em">
 387       If the final argument to DOC_COVER or COVER is <kbd>BLANKPAGE</kbd>,
 388       mom will insert a blank page after the doc-cover or cover.  This is
 389       particularly useful if you intend to print your document two-sided,
 390       since, in two-sided printing, there may be instances where you do
 391       not want text on the reverse side of cover or title pages
 392       </span>
 393       <span style="display:block; margin-left: 1em; margin-top: .5em">
 394       If you enable
 395       <a href="#pagination">DOC_COVERS_COUNT_PAGES</a>
 396       and/or
 397       <a href="#pagination">COVERS_COUNT_PAGES</a>,
 398       the blank page will be taken into account in the pagination
 399       scheme, though no page number appears on it.  Otherwise, blank
 400       pages are invisible to mom's pagination.
 401       </span>
 402     </dd>
 403 <dl/>
 404
 405 <p>
 406 Please note that in all cases, if you have passed
 407 a reference macro one of the optional arguments
 408 <kbd>DOC_COVER</kbd> or <kbd>COVER</kbd> (e.g.
 409 <kbd>.TITLE&nbsp;DOC_COVER&nbsp;"Title"</kbd>), mom will print the
 410 appropriate string on the appropriate cover page.  Thus,
 411 <br/>
 412 <span class="pre-in-pp">
 413   .TITLE DOC_COVER "Collected Essays"
 414   .TITLE COVER "1985-2015"
 415   .TITLE "Neo-liberalism: Who Did They Think They Were Fooling?"
 416   .DOC_COVER TITLE
 417   .COVER TITLE
 418 </span>
 419 will print &#8220;Collected Essays&#8221; on the doc-cover page,
 420 &#8220;1985-2015&#8221; on the cover page, and, assuming the
 421 docheader hasn&#8217;t been disabled, &#8220;Neo-liberalism: Who
 422 Did They Think They Were Fooling?&#8221; as the title in the
 423 docheader.
 424 </p>
 425
 426 <p>
 427 Note that
 428 <br/>
 429 <span class="pre-in-pp">
 430   .DOC_COVERTITLE "Collected Essays"
 431   .COVERTITLE "1985-2015"
 432   .TITLE "Neo-liberalism: Who Did They Think They Were Fooling?"
 433   .DOC_COVER DOC_COVERTITLE
 434   .COVER COVERTITLE
 435 </span>
 436 could be used to accomplish the same thing.
 437 </p>
 438
 439 <h5 id="chapter" class="docs" style="margin-top: 0; text-transform: none;">How the CHAPTER argument and friends work</h5>
 440
 441 <p style="margin-top: .75em">
 442 <span style="display: block; margin-bottom: -1.25em; font-weight: bold;">&bull;&nbsp;CHAPTER</span>
 443 <br/>
 444 The <kbd>CHAPTER</kbd> argument will print the
 445 <a href="docprocessing.html#chapter-string">CHAPTER_STRING</a>
 446 concatenated with the chapter number you gave to
 447 <a href="docprocessing.html#chapter">CHAPTER</a>.
 448 For example, assuming a vanilla setup for your chapter:
 449 <br/>
 450 <span class="pre-in-pp" style="color: #64614a;">
 451   .CHAPTER 1
 452   .CHAPTER_TITLE "The Bonny Blue Yonder"
 453   <span style="color: #941614;">.COVER CHAPTER</span>  \" (or <span style="color: #941614;">.DOC_COVER CHAPTER</span>)
 454 </span>
 455 will print (and only print)
 456 <br/>
 457 <span class="pre-in-pp">
 458   Chapter 1
 459 </span>
 460 </p>
 461
 462 <p style="margin-top: -1em;">
 463 <span style="display: block; margin-bottom: -1.25em; font-weight: bold;">&bull;&nbsp;CHAPTER_TITLE</span>
 464 <br/>
 465 The <kbd>CHAPTER_TITLE</kbd> argument will print the chapter title
 466 you gave to
 467 <a href="docprocessing.html#chapter-title">CHAPTER_TITLE</a>.
 468 For example, assuming a vanilla setup for your chapter:
 469 <br/>
 470 <span class="pre-in-pp" style="color: #64614a;">
 471   .CHAPTER 1
 472   .CHAPTER_TITLE "The Bonny Blue Yonder"
 473   <span style="color: #941614;">.COVER CHAPTER_TITLE</span>  \"(or <span style="color: #941614;">.DOC_COVER CHAPTER_TITLE</span>)
 474 </span>
 475 will print (and only print)
 476 <br/>
 477 <span class="pre-in-pp">
 478     The Bonny Blue Yonder
 479 </span>
 480 </p>
 481
 482 <p style="margin-top: -1em;">
 483 <span style="display: block; margin-bottom: -1.25em; font-weight: bold;">&bull;&nbsp;CHAPTER+TITLE</span>
 484 <br/>
 485 The <kbd>CHAPTER+TITLE</kbd> argument will print both the
 486 concatenated chapter string+number and the chapter title.  For
 487 example, assuming a vanilla setup for your chapter:
 488 <br/>
 489 <span class="pre-in-pp" style="color: #64614a;">
 490   .CHAPTER 1
 491   .CHAPTER_TITLE "The Bonny Blue Yonder"
 492   <span style="color: #941614;">.COVER CHAPTER+TITLE</span> \"(or <span style="color: #941614;">.DOC_COVER CHAPTER+TITLE</span>)
 493 </span>
 494 will print
 495 <br/>
 496 <span class="pre-in-pp">
 497         Chapter 1
 498   The Bonny Blue Yonder
 499 </span>
 500 </p>
 501
 502 <div class="macro-id-overline">
 503 <h3 id="covertext" class="macro-id">DOC_COVERTEXT and COVERTEXT</h3>
 504 </div>
 505
 506 <div class="box-macro-args">
 507 Macro: <b>DOC_COVERTEXT</b> <kbd class="macro-args">&lt;toggle&gt;</kbd>
 508 </div>
 509 <div class="box-macro-args" style="margin-top: 1em;">
 510 Macro: <b>COVERTEXT</b> <kbd class="macro-args">&lt;toggle&gt;</kbd>
 511 </div>
 512
 513 <p class="requires">
 514 &bull;&nbsp;Must come after
 515 <a href="#printstyle"><span class="normal">PRINTSTYLE</span></a>
 516 </p>
 517
 518 <p>
 519 <kbd>DOC_COVERTEXT</kbd> and <kbd>COVERTEXT</kbd> allow you to add
 520 text to doc-covers and covers in addition to, or instead of, what is
 521 generated by mom from the arguments you give to
 522 <a href="#doccover">DOC_COVER</a>
 523 and
 524 <a href="#doccover">COVER</a>.
 525 </p>
 526
 527 <p>
 528 Invoke <kbd>.DOC_COVERTEXT</kbd> or <kbd>.COVERTEXT</kbd> on a line
 529 by itself, follow it with the text and formatting you desire, and
 530 terminate the text block with <kbd>.DOC_COVERTEXT&nbsp;OFF</kbd> or
 531 <kbd>COVERTEXT&nbsp;OFF</kbd> (or <kbd>QUIT, END, DONE</kbd>, etc.).
 532 </p>
 533
 534 <p>
 535 By default, cover text is set over the full line length of the
 536 document, using the style parameters of
 537 <a href="definitions.html#running">running text</a>.
 538 Therefore, as noted, these macros must come after PRINTSTYLE
 539 and any global style changes (margins, family, size, leading,
 540 etc.).  Formatting within a cover text block must be done
 541 &#8220;manually&#8221; with mom&#8217;s typesetting macros;
 542 <a href="docelement.html#pp">PP</a>
 543 is the only allowed document element tag.
 544 </p>
 545
 546 <h4 id="placement" class="docs">Placement</h4>
 547
 548 <p>
 549 If you do not instruct mom to put anything on doc-cover or cover
 550 pages except <kbd>DOC_COVERTEXT</kbd> or <kbd>COVERTEXT</kbd>, the
 551 cover text will begin at the document&#8217;s top margin.  You must
 552 use
 553 <a href="typesetting.html#space">SP</a>
 554 or
 555 <a href="typesetting.html#ald">ALD</a>
 556 to move it further down the page.  Equally, if only
 557 <kbd>COPYRIGHT</kbd> and/or <kbd>MISC</kbd> are to go on the pages,
 558 cover text begins at the top margin.  In all other cases, cover text
 559 begins below the last element on the page (excluding COPYRIGHT or
 560 MISC), separated by a blank line.
 561 </p>
 562
 563 <p>
 564 <kbd>DOC_COVERTEXT</kbd> and <kbd>COVERTEXT</kbd> are particularly
 565 useful for putting abstracts on cover pages, as technical reports
 566 often require.
 567 </p>
 568
 569 <p>
 570 Here's a simple recipe for setting an abstract:
 571 <br/>
 572 <span class="pre-in-pp">
 573   .COVERTEXT
 574   .FT BI
 575   .PT_SIZE 14
 576   .LS 14
 577   .CENTER
 578   Abstract
 579   .SP .5v
 580   .FT R
 581   .PT_SIZE 12
 582   .IB 6P
 583   .JUSTIFY
 584   Text of Abstract...
 585   .COVERTEXT OFF
 586 </span>
 587 Assuming you have told mom to put the title and author on the
 588 cover page, the abstract will appear beneath the author with a
 589 14-point bold-italic title, centered, with the text of the abstract
 590 medium-roman and justified, indented 6 picas from both margins.
 591 </p>
 592
 593 <div class="macro-id-overline">
 594 <h3 id="coverimage" class="macro-id">DOC_COVER_IMAGE and COVER_IMAGE</h3>
 595 </div>
 596
 597 <div id="coverimage" class="box-macro-args">
 598 Macro: <b>DOC_COVER_IMAGE</b> <kbd class="macro-args">&lt;image&gt; &lt;width&gt; &lt;height&gt; [ -L | -C | -R | -I &lt;indent&gt; &lt;Y-pos&gt; [ &lt;X-pos&gt; ] ]</kbd>
 599 </div>
 600
 601 <div id="coverimage" class="box-macro-args" style="margin-top: 1em;">
 602 Macro: <b>COVER_IMAGE</b> <kbd class="macro-args">&lt;image&gt; &lt;width&gt; &lt;height&gt; [ -L | -C | -R | -I &lt;indent&gt; &lt;Y-pos&gt; [ &lt;X-pos&gt; ] ]</kbd>
 603 </div>
 604
 605 <p>
 606 There are times you need a full page image on a cover, for example
 607 the jacket of a book.  Equally, there are times when you need a small
 608 image on the cover, perhaps a company logo.
 609 </p>
 610
 611 <p>
 612 DOC_COVER_IMAGE and COVER_IMAGE take the same arguments
 613 as PDF_IMAGE, and in the same order.  Consult
 614 <a href="images.html#pdf-image">PDF_IMAGE</a>
 615 for a desciption.
 616 </p>
 617
 618 <p>
 619 Two additional arguments allow you to place images using x-y
 620 coordinates.  Please note that if you use x-y coordinates for
 621 positioning, <b>Y-pos</b> comes before <b>X-pos</b> in the order of
 622 arguments.
 623 </p>
 624
 625 <p>
 626 Like PDF_IMAGE, the image file must be in PDF format.  Mom
 627 apologizes, but PostScript images are not supported for inclusion on
 628 covers.  See
 629 <a href="images.html#pdf">Image conversion and file processing</a>
 630 for instructions on converting various image types to PDF, and
 631 <a href="images.html#bounding-box">here</a>
 632 for instructions on obtaining image dimensions.
 633 </p>
 634
 635 <h4 id="positioning" class="docs">Positioning of doc-cover and cover images</h4>
 636
 637 <p>
 638 With no arguments other than <kbd>&lt;file name&gt;</kbd>,
 639 <kbd>&lt;width&gt;</kbd>, and <kbd>&lt;height&gt;</kbd>,
 640 DOC_COVER_IMAGE and COVER_IMAGE place images flush with the top
 641 left corner of the printer sheet.  This allows placing full-page
 642 background images on covers.  For example, assuming a US-letter page
 643 size,
 644 <br/>
 645 <span class="pre-in-pp">
 646   .DOC_COVER_IMAGE image.pdf 612p 792p
 647   .DOC_COVER TITLE AUTHOR DOC_COVER_IMAGE
 648 </span>
 649 will fill the doc-cover page with &#8220;image.pdf&#8221; and set
 650 the title and author in their usual locations.
 651 </p>
 652
 653 <p>
 654 For smaller images, the horizontal position is established
 655 with one of the <kbd>-L</kbd>, <kbd>-C</kbd>, <kbd>-R</kbd>, or
 656 <kbd>-I&nbsp;&lt;indent&gt;</kbd> arguments, just like
 657 <a href="images.html#pdf-image">PDF_IMAGE</a>.
 658 You may instead use the <kbd>X-pos</kbd> argument, provided that it
 659 is preceded by a <kbd>Y-pos</kbd> argument.  The values given to
 660 <kbd>-I</kbd>, <kbd>Y-pos</kbd> and <kbd>X-pos</kbd> must have a
 661 <a href="definitions.html#unitofmeasure">unit of measure</a>
 662 appended to them.
 663 </p>
 664
 665 <p>
 666 Vertical positioning of smaller images requires the <kbd>Y-pos</kbd>
 667 argument (which is why it precedes <kbd>X-pos</kbd> in the order of
 668 arguments) otherwise the image will be flush with the top edge of
 669 the printer sheet
 670 </p>
 671
 672 <p>
 673 The positioning of images does not effect the placement of type on
 674 doc-cover and cover pages.
 675 </p>
 676
 677 <div class="box-tip">
 678 <p class="tip">
 679 <span class="note">Tip:</span>
 680 The combination of
 681 <a href="#covertext">COVERTEXT</a>
 682 and COVER_IMAGE make it possible to design covers entirely to your
 683 own specifications.
 684 </p>
 685 </div>
 686
 687 <div class="macro-id-overline" style="margin-top: .5em">
 688 <h3 id="on-off" class="macro-id">Enabling/disabling automatic generation of cover pages</h3>
 689 </div>
 690
 691 <div id="covers" class="box-macro-args" style="margin-top: .5em">
 692 Macro: <b>COVERS</b> <kbd class="macro-args">&lt;toggle&gt;</kbd>
 693 </div>
 694
 695 <div id="doc-covers" class="box-macro-args" style="margin-top: 1em;">
 696 Macro: <b>DOC_COVERS</b> <kbd class="macro-args">&lt;toggle&gt;</kbd>
 697 </div>
 698
 699 <p>
 700 By default, if you give mom a
 701 <a href="#cover">COVER</a>
 702 or
 703 <a href="#doc-cover">DOC_COVER</a>
 704 directive, she will print the cover or doc-cover.  In a document
 705 that contains sections, articles or chapters formerly treated as
 706 &#8221;one-off&#8217;s&#8221; but now being
 707 <a href="rectoverso.html#collate-intro">collated</a>,
 708 such behaviour may not be desirable.
 709 </p>
 710
 711 <p>
 712 Mom lets you selectively enable or disable the generation of covers
 713 and/or doc-covers with the toggle macros, COVERS and DOC_COVERS.
 714 Because they&#8217;re toggle macros, simply invoking them by
 715 themselves enables automatic cover or doc-cover generation, while
 716 invoking them with any argument at all (<kbd>OFF, QUIT, X</kbd>,
 717 etc) disables cover or doc-cover generation. </p>
 718
 719 <div class="box-tip">
 720 <p class="tip">
 721 <span class="note">Note:</span>
 722 You must place these macros prior to any instance of
 723 <a href="docprocessing.html#start">START</a>.
 724 Since they&#8217;re &#8221;on&#8221; by default, there&#8217;s no
 725 need to use them if you want covers.  However, if you don&#8217;t,
 726 especially in the kind of scenario described above, the best place
 727 to put them (most likely with an <kbd>OFF, NO, X</kbd>, etc. argument),
 728 is immediately after the first invocation of START.  By doing so,
 729 you ensure they meet the requirement of preceding all subsequent
 730 instances of START.
 731 </p>
 732 </div>
 733
 734 <div class="rule-short"><hr/></div>
 735
 736 <h2 id="cover-control" class="macro-group">Control macros for doc-covers and covers</h2>
 737
 738 <p>
 739 The default typographic appearance of the items on a doc-cover or
 740 cover is identical to that of the items in a
 741 <a href="definitions.html#docheader">docheader</a>.
 742 (See
 743 <a href="docprocessing.html#docheader-desc">Docheader description</a>
 744 for a description of the defaults.)
 745 </p>
 746
 747 <p>
 748 <a href="docprocessing.html#copyright">COPYRIGHT</a>
 749 and
 750 <a href="docprocessing.html#misc">MISC</a>,
 751 which do not appear in docheaders, have the following default
 752 characteristics:
 753 </p>
 754 <ul style="margin-top: -.5em; margin-bottom: -.5em;">
 755   <li>the COPYRIGHT line is set flush with the document&#8217;s right
 756       and bottom margins, 2
 757       <a href="definitions.html#ps">point sizes</a>
 758       smaller than the size of
 759       <a href="definitions.html#running">running text</a>
 760   </li>
 761   <li>MISC lines are set flush with the document&#8217;s left and bottom
 762       margins, in the same family, font and point size as the
 763       copyright line.
 764   </li>
 765 </ul>
 766
 767 <p>
 768 The defaults for the entirety of doc-covers and covers, and all the
 769 elements thereon, can be changed with control macros whose defaults
 770 and arguments are identical to the corresponding
 771 <a href="docprocessing.html#index-docheader-control">Control macros for docheaders</a>
 772 (q.v.)  The only difference is the name by which you invoke them.  Wherever
 773 <kbd>DOCHEADER</kbd> is used for overall changes, replace it
 774 with <kbd>DOC_COVER</kbd> or <kbd>COVER</kbd>.  For part-by-part
 775 changes, prepend <kbd>DOC_COVER_</kbd> or <kbd>COVER_</kbd> to the
 776 part/parameter.
 777 </p>
 778
 779 <p>
 780 Thus, to change the overall family, color, leading, quad and
 781 starting position of a doc-cover, you&#8217;d do
 782 <br/>
 783 <span class="pre-in-pp">
 784   .DOC_COVER_FAMILY  H
 785   .DOC_COVER_COLOR   blue
 786   .DOC_COVER_LEAD    +2
 787   .DOC_COVER_QUAD    L
 788   .DOC_COVER_ADVANCE 3i \" or .DOC_COVER_START_POS 3i
 789 </span>
 790 To change the style parameters for selected parts of a cover, you
 791 might do something like this:
 792 <br/>
 793 <span class="pre-in-pp">
 794   .COVER_TITLE_FONT B
 795   .COVER_TITLE_SIZE +4
 796   .COVER_SUBTITLE_FONT I
 797   .COVER_AUTHOR_FONT R
 798   .COVER_AUTHOR_SPACE_BEFORE 6p
 799   .COVER_DOCTYPE_COLOR red
 800   .COVER_MISC_SIZE -1
 801   .COVER_MISC_LEAD 12
 802   .COVER_COPYRIGHT_SIZE -2
 803   .COVER_COPYRIGHT_QUAD L
 804   .COVER_MISC_QUAD R
 805 </span>
 806 Note in the above example that _COPYRIGHT_QUAD and _MISC_QUAD set
 807 both the horizontal position on the page and the quad direction,
 808 either L (or LEFT) or R (or RIGHT), and have no corresponding
 809 docheader control macro.
 810 </p>
 811
 812 <div class="box-tip">
 813 <p class="tip-top">
 814 <span class="note">Tip:</span>
 815 As with the docheader control macros, <kbd>DOC_COVER_</kbd> and
 816 <kbd>COVER_</kbd> part/parameter style changes may be
 817 <a href="docprocessing.html#grouping">grouped</a>,
 818 for example
 819 </br>
 820 <span class="pre-in-pp">
 821   .DOC_COVER_TITLE_STYLE \
 822   FAMILY A \
 823   FONT B \
 824   SIZE +4 \
 825   CAPS
 826 </span>
 827 </p>
 828 </div>
 829
 830 <!-- Navigation links -->
 831 <table style="width: 100%; margin-top: 12px;">
 832 <tr>
 833   <td style="width: 33%;"><a href="toc.html">Back to Table of Contents</a></td>
 834   <td style="width: 33%; text-align: center;"><a href="#top">Top</a></td>
 835   <td style="width: 33%; text-align: right;"><a href="tables-of-contents.html">Next: Tables of contents</a></td>
 836 </tr>
 837 </table>
 838
 839 </div>
 840
 841 <div class="bottom-spacer"><br/></div>
 842
 843 </body>
 844 </html>