cover.html - This HTML code outputs a documentation page fo…

/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

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
<title>Mom -- Document processing, creating a cover page</title>
</head>
<body bgcolor="#dfdfdf">

<!====================================================================>

<a href="refer.html#TOP">Next</a>&nbsp;&nbsp;
<a href="rectoverso.html#TOP">Prev</a>&nbsp;&nbsp;
<a href="toc.html">Back to Table of Contents</a>
<p>

<a name="TOP">
<h1 align="center"><u>CREATING A COVER PAGE</u></h1>
</a>

<ul>
	<li><a href="#COVER_INTRO">Introduction to cover pages</a>
	<ul>
		<li><a href="#PLEASE">Important note -- please read</a>
		<li><a href="#DESC">Description of what mom does on cover pages</a>
		<li><a href="#PAGINATION">A note on headers/footers and pagination</a>
		<li><a href="#DESIGN">What to do if you want to design your
		own cover pages</a>
	</ul>
	<li><a href="#COVER">The cover and document cover macros</a>
	<ul>
		<li><a href="#COVER">COVER/DOC_COVER</a>
		<ul>
			<li><a href="#REQUIRED">The required argument</a>
			<li><a href="#CHAPTER">How the CHAPTER argument and friends work</a>
			<li><a href="#OPTIONAL">The optional arguments</a>
			<li><a href="#DOCTYPE">What the DOCTYPE argument means</a>
		</ul>
	</ul>
	<li><a href="#ON_OFF">Enabling/disabling automatic generation of cover pages</a>
	<li><a href="#COVER_CONTROL">Control macros--changing the
		defaults for covers and document covers</a>
</ul>

<a name="COVER_INTRO"><h2><u>Introduction to cover pages</u></h2></a>
<p>
As of version 1.19 of <strong>mom</strong>, you can now have cover
pages generated automatically.
<p>
Though identical in treatment, <strong>mom</strong> provides two
kinds of cover pages: section cover pages (which I shall refer to
simply as &quot;cover pages&quot;) and document cover pages
(&quot;doc covers&quot;).
<p>
A document cover page
(<a href="#DOC_COVER">doc cover</a>)
is what you'd most likely use at the start of a <a
href="rectoverso.html#COLLATE_INTRO">collated</a> 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>
A section
<a href="#COVER">cover</a>
page is what you'd use for cover pages that separate sections of a
collated document.  A section cover page (but not a doc cover page)
in a collated document could, for example, simply read &quot;PART
I&quot;.
<p>
In non-collated documents (say, an essay) you can use either a
section cover or a doc cover to generate a cover sheet.
<p>
In addition, nothing prevents you from generating both a doc cover
page and a section cover page for every document in a collated
document.  Or you can selectively disable the automatic generation
of either doc covers or section covers in a collated document,
on-the-fly.
<p>
<a name="PLEASE"><strong>Important note:</strong></a>
automatic generation of cover or doc cover pages after the first
one(s) only takes place if you are working with collated documents.
<strong>Mom</strong> provides no mechanism for saying &quot;print
a section cover here even though I'm still working on the same
(non-collated) document.&quot;

<a name="DESC"><h3><u>Description of what mom does on cover pages</u></h3></a>

By default, <strong>mom</strong> typesets cover (and doc cover)
pages identically to
<a href="definitions.html#TERMS_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
<br>
<ul>
	<li>the position on the page where the information is output
	<li>the (optional) addition of copyright and miscellaneous
		information
	<li>there's no running text underneath
</ul>

<p>
You tell <strong>mom</strong> what you want to appear on the cover
pages through the arguments you pass to
<a href="#COVER">COVER</a>
and/or
<a href="#COVER">DOC_COVER</a>.
Provided you have already given <strong>mom</strong> the
appropriate references macro (e.g.
<a href="docprocessing.html#TITLE">TITLE</a>
or
<a href="docprocessing.html#AUTHOR">AUTHOR</a>),
she will output cover (and doc cover) pages identically to how she
would output docheaders containing the same information.
<p>
By default, <strong>mom</strong> starts cover (and doc cover) pages
one-third of the way down the page.  This can be changed through
the use of the control macros
<a href="#COVER_CONTROL_INDEX">COVER_ADVANCE/DOC_COVER_ADVANCE</a>.
<p>
If you request copyright information (and have already given
<strong>mom</strong> the reference macro,
<a href="docprocessing.html#COPYRIGHT">COPYRIGHT</a>),
she sets it, by default, in a smaller
<a href="definitions.html#TERMS_PS">point size</a>
in the bottom right hand corner of the cover (or doc cover) page.
The default point size and the position can be controlled
with
<a href="#COVER_CONTROL_INDEX">COVER_COPYRIGHT_SIZE/DOC_COVER_COPYRIGHT_SIZE</a>
and
<a href="#COVER_CONTROL_INDEX">COVER_COPYRIGHT_QUAD/DOC_COVER_COPYRIGHT_QUAD</a>.
<p>
Similarly, if you request miscellaneous information (and have already given
<strong>mom</strong> 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) page.  The default point
size is dependent on
<strong>COVER_COPYRIGHT_SIZE/DOC_COVER_COPYRIGHT_SIZE</strong>,
but the position can be controlled with
<a href="#COVER_CONTROL_INDEX">COVER_MISC_QUAD/DOC_COVER_MISC_QUAD</a>.

<a name="PAGINATION"></a>
<p>
<strong>NOTE: mom</strong> does not set any
<a href="definitions.html#TERMS_HEADER">headers</a>
or
<a href="definitions.html#TERMS_FOOTER">footers</a>
on cover pages.  Neither does she set any page numbers.  From the
point of pagination, cover (and doc cover) pages are considered
&quot;null&quot; pages; if you wish them to be included in the
pagination scheme (even though no page numbers appear), you must
set the page number of each first page following a
<a href="rectoverso.html#COLLATE">COLLATE</a>
manually with
<a href="headfootpage.html#PAGENUMBER">PAGENUMBER</a>.

<a name="DESIGN"></a>
<p>
Finally, if you want to design your own cover page(s), you can
always typeset them (using the
<a href="typesetting.html#MACROS_TYPESETTING">typesetting macros</a>),
invoke
<a href="typesetting.html#NEWPAGE">NEWPAGE</a>,
set up your document <em>in full</em> (see
<a href="docprocessing.html#DOCPROCESSING_TUT">Tutorial -- Setting up a mom document</a>),
and lastly invoke
<a href="docprocessing.html#START">START</a>.
The cover page (and any typesetting commands on it) will have no
effect on <strong>mom</strong>'s processing of the document itself,
the first page of which, moreover, will be numbered &quot;1&quot;
unless you instruct her otherwise with
<a href="headfootpage.html#PAGENUMBER">PAGENUMBER</a>.
<p>

<!---COVER--->

<hr width="66%" align="left">
<p>
<a name="COVER"></a>
	Macro: <strong>COVER</strong>
	<br>
	Macro: <strong>DOC_COVER</strong>
	<br>
	Required argument: <nobr>TITLE | DOCTITLE | COVERTITLE | CHAPTER | CHAPTER_TITLE | CHAPTER+TITLE</nobr>
	<br>
	Optional arguments: <nobr>[ SUBTITLE AUTHOR DOCTYPE COPYRIGHT MISC ]</nobr>
	<p>
	<em>*Note: these macros should be placed in the
	&quot;style-sheet&quot; section of your document setup (see the
	<a href="docprocessing.html#DOCPROCESSING_TUT">Tutorial -- Setting up a mom document</a>),
	i.e. after PRINTSTYLE (and/or DOCTYPE and/or COPYSTYLE), but
	before START.</em>

</a>
<p>
<strong>COVER</strong> and <strong>DOC_COVER</strong> behave
identically.  The reason <strong>mom</strong> provides two macros
for automatic cover page generation is so that you can have two
different kinds of covers with different information on each.
<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 <strong>DOC_COVER</strong>
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 <strong>COVER</strong>, after each
<strong>COLLATE</strong> but before each
<a href="docprocessing.html#START">START</a>,
to generate a cover page (or cover &quot;sheet&quot;, if you prefer)
containing just the name of the section.
<br>

<a name="REQUIRED"><h3><u>The required argument</u></h3></a>

Both <strong>COVER</strong> and <strong>DOC_COVER</strong>, whenever
invoked, require a first argument, as listed above.  This first argument
will become the first bit of information <strong>mom</strong>
prints on the cover (or doc cover) page (i.e. it will be the
&quot;title&quot;).
<p>
In order for the information to appear, you must, of course, first
have given <strong>mom</strong> the appropriate
<a href="docprocessing.html#REFERENCE_MACROS">reference macro</a>.
A list of arguments with their equivalent reference macros follows.
<br>

<dl>
<dt>TITLE
<dd>-means the argument you gave to
<a href="docprocessing.html#TITLE">TITLE</a>
<dt>DOCTITLE
<dd>-means the argument you gave to
<a href="docprocessing.html#DOCTITLE">DOCTITLE</a>
<dt>COVERTITLE
<dd>-means the argument you gave to
<a href="docprocessing.html#COVERTITLE">COVERTITLE</a>
or
<a href="docprocessing.html#DOC_COVERTITLE">DOC_COVERTITLE</a>
<dt>CHAPTER, CHAPTER_TITLE, CHAPTER+TITLE
<dd>-see below (How the CHAPTER argument and friends work)
</dl>
<br>

<a name="CHAPTER"><h3><u>How the CHAPTER argument and friends work</u></h3></a>

<kbd>CHAPTER</kbd>, by itself, will print the <a
href="docprocessing.html#CHAPTER_STRING">CHAPTER_STRING</a> as well
as the chapter number that you gave to
<a href="docprocessing.html#CHAPTER">CHAPTER</a>.
For example, assuming a vanilla setup for your chapter
<p>
<pre>
	\# Reference macros
	.CHAPTER 1
	.CHAPTER_TITLE "The Bonny Blue Yonder"
	&lt;other stuff&gt;
	.COVER CHAPTER \" (or .DOC_COVER CHAPTER)
	.START
</pre>

will simply print
<p>
<pre>
	Chapter 1
</pre>

<kbd>CHAPTER_TITLE</kbd> 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
<p>
<pre>
	\# Reference macros
	.CHAPTER 1
	.CHAPTER_TITLE "The Bonny Blue Yonder"
	&lt;other stuff&gt;
	.COVER CHAPTER_TITLE \" (or .DOC_COVER CHAPTER_TITLE)
	.START
</pre>

will simply print
<p>
<pre>
	The Bonny Blue Yonder
</pre>

<p>
<kbd>CHAPTER+TITLE</kbd> will print <strong>both</strong> the
chapter string + number AND the chapter title.  For example,
assuming a vanilla setup for your chapter
<p>
<pre>
	\# Reference macros
	.CHAPTER 1
	.CHAPTER_TITLE "The Bonny Blue Yonder"
	&lt;other stuff&gt;
	.COVER CHAPTER+TITLE \" (or .DOC_COVER CHAPTER+TITLE)
	.START
</pre>

will print
<p>
<pre>
	      Chapter 1
	The Bonny Blue Yonder
</pre>

<a name="OPTIONAL"><h3><u>The optional arguments</u></h3></a>

The remainder of the arguments to <strong>COVER</strong> and
<strong>DOC_COVER</strong> are optional.  They refer specifically
to the information you gave the
<a href="docprocessing.html#REFERENCE_MACROS">reference macros</a>
bearing the same name as the arguments.
<p>
You may enter as many or as few as you would like to see on your
cover (or doc cover) page.  The only hitch is--PAY ATTENTION,
CLASS!--they must be entered in the order given above.  For
example, if you want <kbd>TITLE</kbd>, <kbd>AUTHOR</kbd>,
<kbd>COPYRIGHT</kbd> and <kbd>MISC</kbd>
<p>
<pre>
	.COVER TITLE AUTHOR COPYRIGHT MISC
</pre>

is correct, while
<p>
<pre>
	.COVER TITLE AUTHOR MISC COPYRIGHT
</pre>

is not.
<br>

<a name="DOCTYPE"><h3><u>What the DOCTYPE argument means</u></h3></a>

When you pass <strong>COVER</strong> or <strong>DOC_COVER</strong>
the argument, <kbd>DOCTYPE</kbd>, it refers to the argument you
gave to
<a href="docprocessing.html#DOCTYPE">DOCTYPE</a>&nbsp;<kbd>NAMED</kbd>.
For example, if, in your
<a href="docprocessing.html#DOCSTYLE_MACROS">docstyle macros</a>
you gave a
<p>
<pre>
	.DOCTYPE NAMED "Abstract"
</pre>

the argument, <kbd>DOCTYPE</kbd>, in the <strong>COVER</strong> or
<strong>DOC_COVER</strong> macros, would mean that you wanted the
word, Abstract, to appear on the cover (or doc cover), just as it
would in the 
<a href="docprocessing.html#DOCHEADER">docheader</a>.
<br>

<!---ENABLING/DISABLING--->

<hr width="66%" align="left">
<p>
<a name="ON_OFF"></a>
	<nobr>Macro: <strong>COVERS</strong> &lt;toggle&gt;</nobr>
	<br>
	<nobr>Macro: <strong>DOC_COVERS</strong> &lt;toggle&gt;</nobr>
</a>
<p>
By default, if you give <strong>mom</strong> a
<a href="#COVER">COVER</a>
or
<a href="#DOC_COVER">DOC_COVER</a>
macro, she will print it.  In a document that contains sections,
articles or chapters formerly treated as &quot;one-off's&quot; but
now being
<a href="rectoverso.html#COLLATE_INTRO">collated</a>,
such behaviour may not be desirable.
<p>
<strong>Mom</strong> lets you selectively enable or disable the
generation of covers and/or doc covers with the toggle macros
<strong>COVERS</strong> and <strong>DOC_COVERS</strong>.  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 (<strong>OFF, QUIT, X</strong>, etc)
disables cover (or doc cover) generation.
<p>
<strong>NOTE:</strong> You must place these macros prior to any
instance of
<a href="docprocessing.html#START">START</a>.  Since they're
&quot;on&quot; 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
<strong>OFF, NO, X</strong>, etc. argument), is immediately after the
first invocation of <strong>START</strong>.  By doing so, you ensure
they precede all subsequent instances of <strong>START</strong>.
<p>

<hr>
<p>
<a name="COVER_CONTROL"><h3><u>Control macros--changing the defaults for covers and document covers</u></h3></a>
The default typographic appearance of the items on a cover (or doc
cover) page is identical to that of the items in a
<a href="definitions.html#TERMS_DOCHEADER">docheader</a>.
(See
<a href="docprocessing.html#DOCHEADER_CONTROL">How to change the look of docheaders</a>
for a description of the defaults.)
<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:
<br>
<ol>
	<li>The copyright line is set in the bottom right hand corner
		of the page, 2
		<a href="definitions.html#TERMS_PS">point sizes</a>
		smaller than the size of
		<a href="definitions.html#TERMS_RUNNING">running text</a>
	<li>The &quot;misc&quot; line is set in the bottom left hand
		corner of the page, in the same family, font and point size
		as the copyright line.
</ol>
<p>
With the exception of the copyright and &quot;misc&quot; lines, the
defaults for the entirety of cover (and doc cover) pages, and all
the elements thereon, can be changed with control macros whose
behaviour and arguments are identical to
<a href="docprocessing.html#DOCHEADER_CONTROL_INDEX">the control macros used for docheaders</a>.
The only difference is the name by which you invoke the control
macro(s).
<p>
The complete list of cover (and doc cover) page control macros
follows; please refer to the
<a href="docprocessing.html#DOCHEADER_CONTROL_INDEX">docheader control macros index</a>
in order to understand how to use them.  
<p>
<a name="COVER_CONTROL_INDEX"><h3><u>Index of cover and doc cover control macros</u></h3></a>
<pre>
<a name="COVER_ADVANCE">.COVER_ADVANCE  .DOC_COVER_ADVANCE</a> -+
<a name="COVER_FAMILY">.COVER_FAMILY   .DOC_COVER_FAMILY</a>   | like DOCHEADER_
<a name="COVER_LEAD">.COVER_LEAD     .DOC_COVER_LEAD</a>    -+

.COVER_TITLE_FAMILY  .DOC_COVER_TITLE_FAMILY -+
.COVER_TITLE_FONT    .DOC_COVER_TITLE_FONT    | like
.COVER_TITLE_COLOR   .DOC_COVER_TITLE_COLOR   | TITLE_
.COVER_TITLE_SIZE    .DOC_COVER_TITLE_SIZE   -+

.COVER_CHAPTER_TITLE_FAMILY  .DOC_COVER_CHAPTER_TITLE_FAMILY -+
.COVER_CHAPTER_TITLE_FONT    .DOC_COVER_CHAPTER_TITLE_FONT    | like
.COVER_CHAPTER_TITLE_COLOR   .DOC_COVER_CHAPTER_TITLE_COLOR   | CHAPTER_TITLE_
.COVER_CHAPTER_TITLE_SIZE    .DOC_COVER_CHAPTER_TITLE_SIZE   -+

.COVER_SUBTITLE_FAMILY  .DOC_COVER_SUBTITLE_FAMILY -+
.COVER_SUBTITLE_FONT    .DOC_COVER_SUBTITLE_FONT    | like
.COVER_SUBTITLE_COLOR   .DOC_COVER_SUBTITLE_COLOR   | SUBTITLE_
.COVER_SUBTITLE_SIZE    .DOC_COVER_AUTHOR_SIZE     -+

.COVER_ATTRIBUTE_COLOR  .DOC_COVER_ATTRIBUTE_COLOR - like ATTRIBUTE_COLOR
 - the macro, .ATTRIBUTE_STRING, controls the attribution string
   for both docheaders and cover pages; cover pages have no
   separate ATTRIBUTE_STRING macro

.COVER_AUTHOR_FAMILY  .DOC_COVER_AUTHOR_FAMILY -+
.COVER_AUTHOR_FONT    .DOC_COVER_AUTHOR_FONT    | like
.COVER_AUTHOR_COLOR   .DOC_COVER_AUTHOR_COLOR   | AUTHOR_
.COVER_AUTHOR_SIZE    .DOC_COVER_AUTHOR_SIZE   -+

.COVER_DOCTYPE_FAMILY  .DOC_COVER_DOCTYPE_FAMILY -+
.COVER_DOCTYPE_FONT    .DOC_COVER_DOCTYPE_FONT    | like
.COVER_DOCTYPE_COLOR   .DOC_COVER_DOCTYPE_COLOR   | DOCTYPE_
.COVER_DOCTYPE_SIZE    .DOC_COVER_DOCTYPE_SIZE   -+

.COVER_COPYRIGHT_FAMILY  .DOC_COVER_COPYRIGHT_FAMILY -+
.COVER_COPYRIGHT_FONT    .DOC_COVER_COPYRIGHT_FONT    | like any
.COVER_COPYRIGHT_COLOR   .DOC_COVER_COPYRIGHT_COLOR   | of the above
.COVER_COPYRIGHT_SIZE    .DOC_COVER_COPYRIGHT_SIZE   -+
.COVER_COPYRIGHT_QUAD    .DOC_COVER_COPYRIGHT_QUAD
 - the copyright quad can be either L (left) or R (right); default is left

.COVER_MISC_COLOR  .DOC_COVER_MISC_COLOR - like any of the above _COLOR
.COVER_MISC_QUAD   .DOC_COVER_MISC_QUAD
 - the misc quad can be either L (left) or R (right); default is right
</pre>

<strong>Note: COVER_MISC</strong> and
<strong>DOC_COVER_MISC</strong> have only two control macros,
<strong>_COLOR</strong> and <strong>_QUAD</strong>.  The
family, font and size of the <kbd>MISC</kbd> argument to
<strong>COVER</strong> or <strong>DOC_COVER</strong> are always the
same as for <kbd>COPYRIGHT</kbd>.  Should you wish the family, font
or size to be different from <kbd>COPYRIGHT</kbd>, I suggest setting
the type specs for <kbd>COPYRIGHT</kbd> to the ones you want for
<kbd>MISC</kbd>, then altering them for <kbd>COPYRIGHT</kbd> using
<a href="inlines.html#INDEX_INLINES">inline escapes</a>
in the
<a href="definitions.html#TERMS_STRINGARGUMENT">string argument</a>
you pass to the macro,
<a href="docprocessing.html#COPYRIGHT">COPYRIGHT</a>.  (Of course,
you could always do the reverse, but if you pass several arguments
to
<a href="docprocessing.html#MISC">MISC</a>,
it's more likely you want to get <strong>MISC</strong> right first.)

<p>
<hr>
<a href="refer.html#TOP">Next</a>&nbsp;&nbsp;
<a href="rectoverso.html#TOP">Prev</a>&nbsp;&nbsp;
<a href="#TOP">Top</a>&nbsp;&nbsp;
<a href="toc.html">Back to Table of Contents</a>
</body>
</html>