/contrib/groff/contrib/mom/momdoc/cover.html
HTML | 512 lines | 467 code | 43 blank | 2 comment | 0 complexity | e92e9b28b9f1687e807b02866305871b MD5 | raw file
Possible License(s): MPL-2.0-no-copyleft-exception, BSD-3-Clause, LGPL-2.0, LGPL-2.1, BSD-2-Clause, 0BSD, JSON, AGPL-1.0, GPL-2.0
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, creating a cover page</title> 6</head> 7<body bgcolor="#dfdfdf"> 8 9<!====================================================================> 10 11<a href="refer.html#TOP">Next</a> 12<a href="rectoverso.html#TOP">Prev</a> 13<a href="toc.html">Back to Table of Contents</a> 14<p> 15 16<a name="TOP"> 17<h1 align="center"><u>CREATING A COVER PAGE</u></h1> 18</a> 19 20<ul> 21 <li><a href="#COVER_INTRO">Introduction to cover pages</a> 22 <ul> 23 <li><a href="#PLEASE">Important note -- please read</a> 24 <li><a href="#DESC">Description of what mom does on cover pages</a> 25 <li><a href="#PAGINATION">A note on headers/footers and pagination</a> 26 <li><a href="#DESIGN">What to do if you want to design your 27 own cover pages</a> 28 </ul> 29 <li><a href="#COVER">The cover and document cover macros</a> 30 <ul> 31 <li><a href="#COVER">COVER/DOC_COVER</a> 32 <ul> 33 <li><a href="#REQUIRED">The required argument</a> 34 <li><a href="#CHAPTER">How the CHAPTER argument and friends work</a> 35 <li><a href="#OPTIONAL">The optional arguments</a> 36 <li><a href="#DOCTYPE">What the DOCTYPE argument means</a> 37 </ul> 38 </ul> 39 <li><a href="#ON_OFF">Enabling/disabling automatic generation of cover pages</a> 40 <li><a href="#COVER_CONTROL">Control macros--changing the 41 defaults for covers and document covers</a> 42</ul> 43 44<a name="COVER_INTRO"><h2><u>Introduction to cover pages</u></h2></a> 45<p> 46As of version 1.19 of <strong>mom</strong>, you can now have cover 47pages generated automatically. 48<p> 49Though identical in treatment, <strong>mom</strong> provides two 50kinds of cover pages: section cover pages (which I shall refer to 51simply as "cover pages") and document cover pages 52("doc covers"). 53<p> 54A document cover page 55(<a href="#DOC_COVER">doc cover</a>) 56is what you'd most likely use at the start of a <a 57href="rectoverso.html#COLLATE_INTRO">collated</a> document, where 58you might want the name of the complete document, the author(s) and 59the copyright line to appear. Another place you might use a doc 60cover is for a novel, where you want the title of the novel, not 61the chapter title or chapter number, as the first cover page. 62<p> 63A section 64<a href="#COVER">cover</a> 65page is what you'd use for cover pages that separate sections of a 66collated document. A section cover page (but not a doc cover page) 67in a collated document could, for example, simply read "PART 68I". 69<p> 70In non-collated documents (say, an essay) you can use either a 71section cover or a doc cover to generate a cover sheet. 72<p> 73In addition, nothing prevents you from generating both a doc cover 74page and a section cover page for every document in a collated 75document. Or you can selectively disable the automatic generation 76of either doc covers or section covers in a collated document, 77on-the-fly. 78<p> 79<a name="PLEASE"><strong>Important note:</strong></a> 80automatic generation of cover or doc cover pages after the first 81one(s) only takes place if you are working with collated documents. 82<strong>Mom</strong> provides no mechanism for saying "print 83a section cover here even though I'm still working on the same 84(non-collated) document." 85 86<a name="DESC"><h3><u>Description of what mom does on cover pages</u></h3></a> 87 88By default, <strong>mom</strong> typesets cover (and doc cover) 89pages identically to 90<a href="definitions.html#TERMS_DOCHEADER">docheaders</a> 91(see 92<a href="docprocessing.html#DOCHEADER_CONTROL">How to change the look of docheaders</a> 93for a description of what a docheader looks like). The only 94differences are 95<br> 96<ul> 97 <li>the position on the page where the information is output 98 <li>the (optional) addition of copyright and miscellaneous 99 information 100 <li>there's no running text underneath 101</ul> 102 103<p> 104You tell <strong>mom</strong> what you want to appear on the cover 105pages through the arguments you pass to 106<a href="#COVER">COVER</a> 107and/or 108<a href="#COVER">DOC_COVER</a>. 109Provided you have already given <strong>mom</strong> the 110appropriate references macro (e.g. 111<a href="docprocessing.html#TITLE">TITLE</a> 112or 113<a href="docprocessing.html#AUTHOR">AUTHOR</a>), 114she will output cover (and doc cover) pages identically to how she 115would output docheaders containing the same information. 116<p> 117By default, <strong>mom</strong> starts cover (and doc cover) pages 118one-third of the way down the page. This can be changed through 119the use of the control macros 120<a href="#COVER_CONTROL_INDEX">COVER_ADVANCE/DOC_COVER_ADVANCE</a>. 121<p> 122If you request copyright information (and have already given 123<strong>mom</strong> the reference macro, 124<a href="docprocessing.html#COPYRIGHT">COPYRIGHT</a>), 125she sets it, by default, in a smaller 126<a href="definitions.html#TERMS_PS">point size</a> 127in the bottom right hand corner of the cover (or doc cover) page. 128The default point size and the position can be controlled 129with 130<a href="#COVER_CONTROL_INDEX">COVER_COPYRIGHT_SIZE/DOC_COVER_COPYRIGHT_SIZE</a> 131and 132<a href="#COVER_CONTROL_INDEX">COVER_COPYRIGHT_QUAD/DOC_COVER_COPYRIGHT_QUAD</a>. 133<p> 134Similarly, if you request miscellaneous information (and have already given 135<strong>mom</strong> the reference macro, 136<a href="docprocessing.html#MISC">MISC</a>), 137she sets it, by default, in a smaller point size in the bottom left 138hand corner of the cover (or doc cover) page. The default point 139size is dependent on 140<strong>COVER_COPYRIGHT_SIZE/DOC_COVER_COPYRIGHT_SIZE</strong>, 141but the position can be controlled with 142<a href="#COVER_CONTROL_INDEX">COVER_MISC_QUAD/DOC_COVER_MISC_QUAD</a>. 143 144<a name="PAGINATION"></a> 145<p> 146<strong>NOTE: mom</strong> does not set any 147<a href="definitions.html#TERMS_HEADER">headers</a> 148or 149<a href="definitions.html#TERMS_FOOTER">footers</a> 150on cover pages. Neither does she set any page numbers. From the 151point of pagination, cover (and doc cover) pages are considered 152"null" pages; if you wish them to be included in the 153pagination scheme (even though no page numbers appear), you must 154set the page number of each first page following a 155<a href="rectoverso.html#COLLATE">COLLATE</a> 156manually with 157<a href="headfootpage.html#PAGENUMBER">PAGENUMBER</a>. 158 159<a name="DESIGN"></a> 160<p> 161Finally, if you want to design your own cover page(s), you can 162always typeset them (using the 163<a href="typesetting.html#MACROS_TYPESETTING">typesetting macros</a>), 164invoke 165<a href="typesetting.html#NEWPAGE">NEWPAGE</a>, 166set up your document <em>in full</em> (see 167<a href="docprocessing.html#DOCPROCESSING_TUT">Tutorial -- Setting up a mom document</a>), 168and lastly invoke 169<a href="docprocessing.html#START">START</a>. 170The cover page (and any typesetting commands on it) will have no 171effect on <strong>mom</strong>'s processing of the document itself, 172the first page of which, moreover, will be numbered "1" 173unless you instruct her otherwise with 174<a href="headfootpage.html#PAGENUMBER">PAGENUMBER</a>. 175<p> 176 177<!---COVER---> 178 179<hr width="66%" align="left"> 180<p> 181<a name="COVER"></a> 182 Macro: <strong>COVER</strong> 183 <br> 184 Macro: <strong>DOC_COVER</strong> 185 <br> 186 Required argument: <nobr>TITLE | DOCTITLE | COVERTITLE | CHAPTER | CHAPTER_TITLE | CHAPTER+TITLE</nobr> 187 <br> 188 Optional arguments: <nobr>[ SUBTITLE AUTHOR DOCTYPE COPYRIGHT MISC ]</nobr> 189 <p> 190 <em>*Note: these macros should be placed in the 191 "style-sheet" section of your document setup (see the 192 <a href="docprocessing.html#DOCPROCESSING_TUT">Tutorial -- Setting up a mom document</a>), 193 i.e. after PRINTSTYLE (and/or DOCTYPE and/or COPYSTYLE), but 194 before START.</em> 195 196</a> 197<p> 198<strong>COVER</strong> and <strong>DOC_COVER</strong> behave 199identically. The reason <strong>mom</strong> provides two macros 200for automatic cover page generation is so that you can have two 201different kinds of covers with different information on each. 202<p> 203Imagine, for a moment, you've written a document comprised of three 204sections. When you 205<a href="rectoverso.html#COLLATE">COLLATE</a> 206the document for output, you could use <strong>DOC_COVER</strong> 207to generate a cover page that contained the name of the entire 208document, your (the author's) name, and perhaps the copyright date. 209Subsequently, you could use <strong>COVER</strong>, after each 210<strong>COLLATE</strong> but before each 211<a href="docprocessing.html#START">START</a>, 212to generate a cover page (or cover "sheet", if you prefer) 213containing just the name of the section. 214<br> 215 216<a name="REQUIRED"><h3><u>The required argument</u></h3></a> 217 218Both <strong>COVER</strong> and <strong>DOC_COVER</strong>, whenever 219invoked, require a first argument, as listed above. This first argument 220will become the first bit of information <strong>mom</strong> 221prints on the cover (or doc cover) page (i.e. it will be the 222"title"). 223<p> 224In order for the information to appear, you must, of course, first 225have given <strong>mom</strong> the appropriate 226<a href="docprocessing.html#REFERENCE_MACROS">reference macro</a>. 227A list of arguments with their equivalent reference macros follows. 228<br> 229 230<dl> 231<dt>TITLE 232<dd>-means the argument you gave to 233<a href="docprocessing.html#TITLE">TITLE</a> 234<dt>DOCTITLE 235<dd>-means the argument you gave to 236<a href="docprocessing.html#DOCTITLE">DOCTITLE</a> 237<dt>COVERTITLE 238<dd>-means the argument you gave to 239<a href="docprocessing.html#COVERTITLE">COVERTITLE</a> 240or 241<a href="docprocessing.html#DOC_COVERTITLE">DOC_COVERTITLE</a> 242<dt>CHAPTER, CHAPTER_TITLE, CHAPTER+TITLE 243<dd>-see below (How the CHAPTER argument and friends work) 244</dl> 245<br> 246 247<a name="CHAPTER"><h3><u>How the CHAPTER argument and friends work</u></h3></a> 248 249<kbd>CHAPTER</kbd>, by itself, will print the <a 250href="docprocessing.html#CHAPTER_STRING">CHAPTER_STRING</a> as well 251as the chapter number that you gave to 252<a href="docprocessing.html#CHAPTER">CHAPTER</a>. 253For example, assuming a vanilla setup for your chapter 254<p> 255<pre> 256 \# Reference macros 257 .CHAPTER 1 258 .CHAPTER_TITLE "The Bonny Blue Yonder" 259 <other stuff> 260 .COVER CHAPTER \" (or .DOC_COVER CHAPTER) 261 .START 262</pre> 263 264will simply print 265<p> 266<pre> 267 Chapter 1 268</pre> 269 270<kbd>CHAPTER_TITLE</kbd> will print the chapter title you 271gave to 272<a href="docprocessing.html#CHAPTER_TITLE">CHAPTER_TITLE</a>. 273For example, assuming a vanilla setup for your chapter 274<p> 275<pre> 276 \# Reference macros 277 .CHAPTER 1 278 .CHAPTER_TITLE "The Bonny Blue Yonder" 279 <other stuff> 280 .COVER CHAPTER_TITLE \" (or .DOC_COVER CHAPTER_TITLE) 281 .START 282</pre> 283 284will simply print 285<p> 286<pre> 287 The Bonny Blue Yonder 288</pre> 289 290<p> 291<kbd>CHAPTER+TITLE</kbd> will print <strong>both</strong> the 292chapter string + number AND the chapter title. For example, 293assuming a vanilla setup for your chapter 294<p> 295<pre> 296 \# Reference macros 297 .CHAPTER 1 298 .CHAPTER_TITLE "The Bonny Blue Yonder" 299 <other stuff> 300 .COVER CHAPTER+TITLE \" (or .DOC_COVER CHAPTER+TITLE) 301 .START 302</pre> 303 304will print 305<p> 306<pre> 307 Chapter 1 308 The Bonny Blue Yonder 309</pre> 310 311<a name="OPTIONAL"><h3><u>The optional arguments</u></h3></a> 312 313The remainder of the arguments to <strong>COVER</strong> and 314<strong>DOC_COVER</strong> are optional. They refer specifically 315to the information you gave the 316<a href="docprocessing.html#REFERENCE_MACROS">reference macros</a> 317bearing the same name as the arguments. 318<p> 319You may enter as many or as few as you would like to see on your 320cover (or doc cover) page. The only hitch is--PAY ATTENTION, 321CLASS!--they must be entered in the order given above. For 322example, if you want <kbd>TITLE</kbd>, <kbd>AUTHOR</kbd>, 323<kbd>COPYRIGHT</kbd> and <kbd>MISC</kbd> 324<p> 325<pre> 326 .COVER TITLE AUTHOR COPYRIGHT MISC 327</pre> 328 329is correct, while 330<p> 331<pre> 332 .COVER TITLE AUTHOR MISC COPYRIGHT 333</pre> 334 335is not. 336<br> 337 338<a name="DOCTYPE"><h3><u>What the DOCTYPE argument means</u></h3></a> 339 340When you pass <strong>COVER</strong> or <strong>DOC_COVER</strong> 341the argument, <kbd>DOCTYPE</kbd>, it refers to the argument you 342gave to 343<a href="docprocessing.html#DOCTYPE">DOCTYPE</a> <kbd>NAMED</kbd>. 344For example, if, in your 345<a href="docprocessing.html#DOCSTYLE_MACROS">docstyle macros</a> 346you gave a 347<p> 348<pre> 349 .DOCTYPE NAMED "Abstract" 350</pre> 351 352the argument, <kbd>DOCTYPE</kbd>, in the <strong>COVER</strong> or 353<strong>DOC_COVER</strong> macros, would mean that you wanted the 354word, Abstract, to appear on the cover (or doc cover), just as it 355would in the 356<a href="docprocessing.html#DOCHEADER">docheader</a>. 357<br> 358 359<!---ENABLING/DISABLING---> 360 361<hr width="66%" align="left"> 362<p> 363<a name="ON_OFF"></a> 364 <nobr>Macro: <strong>COVERS</strong> <toggle></nobr> 365 <br> 366 <nobr>Macro: <strong>DOC_COVERS</strong> <toggle></nobr> 367</a> 368<p> 369By default, if you give <strong>mom</strong> a 370<a href="#COVER">COVER</a> 371or 372<a href="#DOC_COVER">DOC_COVER</a> 373macro, she will print it. In a document that contains sections, 374articles or chapters formerly treated as "one-off's" but 375now being 376<a href="rectoverso.html#COLLATE_INTRO">collated</a>, 377such behaviour may not be desirable. 378<p> 379<strong>Mom</strong> lets you selectively enable or disable the 380generation of covers and/or doc covers with the toggle macros 381<strong>COVERS</strong> and <strong>DOC_COVERS</strong>. Because 382they're toggle macros, simply invoking them by themselves enables 383automatic cover (or doc cover) generation, while invoking them 384with any argument at all (<strong>OFF, QUIT, X</strong>, etc) 385disables cover (or doc cover) generation. 386<p> 387<strong>NOTE:</strong> You must place these macros prior to any 388instance of 389<a href="docprocessing.html#START">START</a>. Since they're 390"on" by default, there's no need to use them if you want 391covers. However, if you don't, especially in the kind of scenario 392described above, the best place to put them (most likely with an 393<strong>OFF, NO, X</strong>, etc. argument), is immediately after the 394first invocation of <strong>START</strong>. By doing so, you ensure 395they precede all subsequent instances of <strong>START</strong>. 396<p> 397 398<hr> 399<p> 400<a name="COVER_CONTROL"><h3><u>Control macros--changing the defaults for covers and document covers</u></h3></a> 401The default typographic appearance of the items on a cover (or doc 402cover) page is identical to that of the items in a 403<a href="definitions.html#TERMS_DOCHEADER">docheader</a>. 404(See 405<a href="docprocessing.html#DOCHEADER_CONTROL">How to change the look of docheaders</a> 406for a description of the defaults.) 407<p> 408<a href="docprocessing.html#COPYRIGHT">COPYRIGHT</a> 409and 410<a href="docprocessing.html#MISC">MISC</a>, 411which do not appear in docheaders, have the following default 412characteristics: 413<br> 414<ol> 415 <li>The copyright line is set in the bottom right hand corner 416 of the page, 2 417 <a href="definitions.html#TERMS_PS">point sizes</a> 418 smaller than the size of 419 <a href="definitions.html#TERMS_RUNNING">running text</a> 420 <li>The "misc" line is set in the bottom left hand 421 corner of the page, in the same family, font and point size 422 as the copyright line. 423</ol> 424<p> 425With the exception of the copyright and "misc" lines, the 426defaults for the entirety of cover (and doc cover) pages, and all 427the elements thereon, can be changed with control macros whose 428behaviour and arguments are identical to 429<a href="docprocessing.html#DOCHEADER_CONTROL_INDEX">the control macros used for docheaders</a>. 430The only difference is the name by which you invoke the control 431macro(s). 432<p> 433The complete list of cover (and doc cover) page control macros 434follows; please refer to the 435<a href="docprocessing.html#DOCHEADER_CONTROL_INDEX">docheader control macros index</a> 436in order to understand how to use them. 437<p> 438<a name="COVER_CONTROL_INDEX"><h3><u>Index of cover and doc cover control macros</u></h3></a> 439<pre> 440<a name="COVER_ADVANCE">.COVER_ADVANCE .DOC_COVER_ADVANCE</a> -+ 441<a name="COVER_FAMILY">.COVER_FAMILY .DOC_COVER_FAMILY</a> | like DOCHEADER_ 442<a name="COVER_LEAD">.COVER_LEAD .DOC_COVER_LEAD</a> -+ 443 444.COVER_TITLE_FAMILY .DOC_COVER_TITLE_FAMILY -+ 445.COVER_TITLE_FONT .DOC_COVER_TITLE_FONT | like 446.COVER_TITLE_COLOR .DOC_COVER_TITLE_COLOR | TITLE_ 447.COVER_TITLE_SIZE .DOC_COVER_TITLE_SIZE -+ 448 449.COVER_CHAPTER_TITLE_FAMILY .DOC_COVER_CHAPTER_TITLE_FAMILY -+ 450.COVER_CHAPTER_TITLE_FONT .DOC_COVER_CHAPTER_TITLE_FONT | like 451.COVER_CHAPTER_TITLE_COLOR .DOC_COVER_CHAPTER_TITLE_COLOR | CHAPTER_TITLE_ 452.COVER_CHAPTER_TITLE_SIZE .DOC_COVER_CHAPTER_TITLE_SIZE -+ 453 454.COVER_SUBTITLE_FAMILY .DOC_COVER_SUBTITLE_FAMILY -+ 455.COVER_SUBTITLE_FONT .DOC_COVER_SUBTITLE_FONT | like 456.COVER_SUBTITLE_COLOR .DOC_COVER_SUBTITLE_COLOR | SUBTITLE_ 457.COVER_SUBTITLE_SIZE .DOC_COVER_AUTHOR_SIZE -+ 458 459.COVER_ATTRIBUTE_COLOR .DOC_COVER_ATTRIBUTE_COLOR - like ATTRIBUTE_COLOR 460 - the macro, .ATTRIBUTE_STRING, controls the attribution string 461 for both docheaders and cover pages; cover pages have no 462 separate ATTRIBUTE_STRING macro 463 464.COVER_AUTHOR_FAMILY .DOC_COVER_AUTHOR_FAMILY -+ 465.COVER_AUTHOR_FONT .DOC_COVER_AUTHOR_FONT | like 466.COVER_AUTHOR_COLOR .DOC_COVER_AUTHOR_COLOR | AUTHOR_ 467.COVER_AUTHOR_SIZE .DOC_COVER_AUTHOR_SIZE -+ 468 469.COVER_DOCTYPE_FAMILY .DOC_COVER_DOCTYPE_FAMILY -+ 470.COVER_DOCTYPE_FONT .DOC_COVER_DOCTYPE_FONT | like 471.COVER_DOCTYPE_COLOR .DOC_COVER_DOCTYPE_COLOR | DOCTYPE_ 472.COVER_DOCTYPE_SIZE .DOC_COVER_DOCTYPE_SIZE -+ 473 474.COVER_COPYRIGHT_FAMILY .DOC_COVER_COPYRIGHT_FAMILY -+ 475.COVER_COPYRIGHT_FONT .DOC_COVER_COPYRIGHT_FONT | like any 476.COVER_COPYRIGHT_COLOR .DOC_COVER_COPYRIGHT_COLOR | of the above 477.COVER_COPYRIGHT_SIZE .DOC_COVER_COPYRIGHT_SIZE -+ 478.COVER_COPYRIGHT_QUAD .DOC_COVER_COPYRIGHT_QUAD 479 - the copyright quad can be either L (left) or R (right); default is left 480 481.COVER_MISC_COLOR .DOC_COVER_MISC_COLOR - like any of the above _COLOR 482.COVER_MISC_QUAD .DOC_COVER_MISC_QUAD 483 - the misc quad can be either L (left) or R (right); default is right 484</pre> 485 486<strong>Note: COVER_MISC</strong> and 487<strong>DOC_COVER_MISC</strong> have only two control macros, 488<strong>_COLOR</strong> and <strong>_QUAD</strong>. The 489family, font and size of the <kbd>MISC</kbd> argument to 490<strong>COVER</strong> or <strong>DOC_COVER</strong> are always the 491same as for <kbd>COPYRIGHT</kbd>. Should you wish the family, font 492or size to be different from <kbd>COPYRIGHT</kbd>, I suggest setting 493the type specs for <kbd>COPYRIGHT</kbd> to the ones you want for 494<kbd>MISC</kbd>, then altering them for <kbd>COPYRIGHT</kbd> using 495<a href="inlines.html#INDEX_INLINES">inline escapes</a> 496in the 497<a href="definitions.html#TERMS_STRINGARGUMENT">string argument</a> 498you pass to the macro, 499<a href="docprocessing.html#COPYRIGHT">COPYRIGHT</a>. (Of course, 500you could always do the reverse, but if you pass several arguments 501to 502<a href="docprocessing.html#MISC">MISC</a>, 503it's more likely you want to get <strong>MISC</strong> right first.) 504 505<p> 506<hr> 507<a href="refer.html#TOP">Next</a> 508<a href="rectoverso.html#TOP">Prev</a> 509<a href="#TOP">Top</a> 510<a href="toc.html">Back to Table of Contents</a> 511</body> 512</html>