PageRenderTime 41ms CodeModel.GetById 2ms app.highlight 29ms RepoModel.GetById 1ms app.codeStats 1ms

/contrib/groff/contrib/mom/momdoc/cover.html

https://bitbucket.org/freebsd/freebsd-head/
HTML | 512 lines | 467 code | 43 blank | 2 comment | 0 complexity | e92e9b28b9f1687e807b02866305871b MD5 | raw 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, creating a cover page</title>
  6</head>
  7<body bgcolor="#dfdfdf">
  8
  9<!====================================================================>
 10
 11<a href="refer.html#TOP">Next</a>&nbsp;&nbsp;
 12<a href="rectoverso.html#TOP">Prev</a>&nbsp;&nbsp;
 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 &quot;cover pages&quot;) and document cover pages
 52(&quot;doc covers&quot;).
 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 &quot;PART
 68I&quot;.
 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 &quot;print
 83a section cover here even though I'm still working on the same
 84(non-collated) document.&quot;
 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&quot;null&quot; 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 &quot;1&quot;
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	&quot;style-sheet&quot; 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 &quot;sheet&quot;, 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&quot;title&quot;).
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	&lt;other stuff&gt;
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	&lt;other stuff&gt;
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	&lt;other stuff&gt;
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>&nbsp;<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> &lt;toggle&gt;</nobr>
365	<br>
366	<nobr>Macro: <strong>DOC_COVERS</strong> &lt;toggle&gt;</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 &quot;one-off's&quot; 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&quot;on&quot; 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 &quot;misc&quot; 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 &quot;misc&quot; 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>&nbsp;&nbsp;
508<a href="rectoverso.html#TOP">Prev</a>&nbsp;&nbsp;
509<a href="#TOP">Top</a>&nbsp;&nbsp;
510<a href="toc.html">Back to Table of Contents</a>
511</body>
512</html>