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