<!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>
<a href="rectoverso.html#TOP">Prev</a>
<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 "cover pages") and document cover pages
("doc covers").
<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 "PART
I".
<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 "print
a section cover here even though I'm still working on the same
(non-collated) document."
<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
"null" 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 "1"
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
"style-sheet" 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 "sheet", 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
"title").
<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"
<other stuff>
.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"
<other stuff>
.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"
<other stuff>
.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> <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> <toggle></nobr>
<br>
<nobr>Macro: <strong>DOC_COVERS</strong> <toggle></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 "one-off's" 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
"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
<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 "misc" 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 "misc" 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>
<a href="rectoverso.html#TOP">Prev</a>
<a href="#TOP">Top</a>
<a href="toc.html">Back to Table of Contents</a>
</body>
</html>