Mom -- Document processing, creating cover pages

Back to Table of Contents | Next: Tables of contents

# Creating cover pages

- Introduction to cover pages
  - Important note
  - Description of cover pages
  - Headers/footers/pagination
    - DOC_COVERS_COUNT_PAGES
    - COVERS_COUNT_PAGES
  - Designing your own cover pages
  - Persistence of data and formatting
- Doc-cover and cover macros
  - DOC_COVER / COVER
    - The argument list: saying what goes on doc cover and cover pages
    - What the arguments mean
    - How the CHAPTER argument and friends work
  - DOC_COVERTEXT / COVERTEXT
    - Placement
  - DOC_COVER_IMAGE / COVER_IMAGE
    - Positioning of doc cover and cover images
- Enabling/disabling automatic generation of cover pages
- Control macros for covers and doc covers

## Introduction to cover pages

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.

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.

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”.

In non-collated documents (say, an essay) you can use either a cover or doc cover to generate the cover sheet.

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.

Important note: 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.”

### Description of cover pages

By default, mom typesets covers and doc covers identically to docheaders (see How to change the look of docheaders for a description of what a docheader looks like). The only differences are

- the position on the page where the information is output
- the (optional) addition of copyright and miscellaneous information
- there’s no running text underneath, although you can add text to a cover or doc cover (for example, an Abstract) with COVERTEXT

You tell mom what you want to appear on cover pages through the arguments you pass to DOC_COVER and/or COVER. Provided you have already given mom the appropriate reference macros (e.g. TITLE or AUTHOR), she will output covers and doc covers identically to how she would output docheaders containing the same information.

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).

If you request copyright information (and have already given mom the reference macro COPYRIGHT) she sets it, by default, in a smaller point size 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.

Similarly, if you request miscellaneous information (and have already given mom the reference macro MISC) 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.

### Headers/footers/pagination

Mom does not set any headers or footers 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
.DOC_COVER_COUNTS_PAGES or
.COVER_COUNTS_PAGES

### Designing your own cover pages

Finally, if you want to design your own cover page(s), you can typeset them by hand inside a COVERTEXT block using mom’s typesetting macros to format the text.

### Persistence of data and formatting

Doc-cover and cover data—that is to say, the strings passed to reference macros that appear on doc cover and cover pages—do not persist after START, however the formatting of the various parts (TITLE, AUTHOR, COPYRIGHT, etc.) does.

### Cover and document cover macros

- DOC_COVER and COVER
  - The arguments: saying what goes on doc cover and cover pages
- DOC_COVERTEXT / COVERTEXT
- DOC_COVER_IMAGE / COVER_IMAGE
- Enabling/disabling automatic generation of cover pages
  - DOC_COVERS
  - COVERS
- Control macros for doc covers and covers

### DOC_COVER and COVER

Macro: DOC_COVER `(see argument list, below)`
Macro: COVER `(see argument list, below)`

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.

Imagine, for a moment, you’ve written a document comprised of three sections. When you COLLATE 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 `.COLLATE` but before each `.START`, to generate a cover page (title page, cover sheet) containing just the name of the section, for example, “Part 1”.

The arguments to `DOC_COVER` and `COVER` 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:
.COVER TITLE AUTHOR COPYRIGHT

#### The argument list

The arguments to `COVER` and `DOC_COVER` tell mom what you want on the cover page:
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

#### What the arguments mean

TITLE
  – the string(s) you gave to TITLE
DOCTITLE
  – the string(s) you gave to DOCTITLE
DOC_COVERTITLE / COVERTITLE
  – the string(s) you gave to DOC_COVERTITLE or COVERTITLE
CHAPTER, CHAPTER_TITLE, CHAPTER+TITLE
  – see below, How the CHAPTER argument and friends work
SUBTITLE
  – the string(s) you gave to SUBTITLE
AUTHOR
  – the string(s) you gave to AUTHOR
DOCTYPE
  – the string you gave to DOCTYPE NAMED
DOC_COVERTEXT / COVERTEXT
  – the block of type you entered for DOC_COVERTEXT or COVERTEXT
DOC_COVER_IMAGE / COVER_IMAGE
  – the image file you gave to DOC_COVER_IMAGE or COVER_IMAGE
COPYRIGHT
  – the string you gave to COPYRIGHT
MISC
  – the string(s) you gave to MISC
PDF_OUTLINE_LABEL <label>
  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 `PDF_OUTLINE_LABEL` argument to DOC_COVER or COVER along with the new label, in quotation marks, as in this example:
  `.COVER TITLE AUTHOR COPYRIGHT PDF_LABEL "Cover Sheet: "`
BLANKPAGE
  If the final argument to DOC_COVER or COVER is `BLANKPAGE`, 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 If you enable DOC_COVERS_COUNT_PAGES and/or COVERS_COUNT_PAGES, 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.

Please note that in all cases, if you have passed a reference macro one of the optional arguments `DOC_COVER` or `COVER` (e.g. `.TITLE DOC_COVER "Title"`), mom will print the appropriate string on the appropriate cover page. Thus,
.TITLE DOC_COVER "Collected Essays" .TITLE COVER "1985-2015" .TITLE "Neo-liberalism: Who Did They Think They Were Fooling?" .DOC_COVER TITLE .COVER TITLE 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.

Note that
.DOC_COVERTITLE "Collected Essays" .COVERTITLE "1985-2015" .TITLE "Neo-liberalism: Who Did They Think They Were Fooling?" .DOC_COVER DOC_COVERTITLE .COVER COVERTITLE could be used to accomplish the same thing.

##### How the CHAPTER argument and friends work

• CHAPTER
The `CHAPTER` argument will print the CHAPTER_STRING concatenated with the chapter number you gave to CHAPTER. For example, assuming a vanilla setup for your chapter:
.CHAPTER 1 .CHAPTER_TITLE "The Bonny Blue Yonder" .COVER CHAPTER \" (or .DOC_COVER CHAPTER) will print (and only print)
Chapter 1

• CHAPTER_TITLE
The `CHAPTER_TITLE` argument will print the chapter title you gave to CHAPTER_TITLE. For example, assuming a vanilla setup for your chapter:
.CHAPTER 1 .CHAPTER_TITLE "The Bonny Blue Yonder" .COVER CHAPTER_TITLE \"(or .DOC_COVER CHAPTER_TITLE) will print (and only print)
The Bonny Blue Yonder

• CHAPTER+TITLE
The `CHAPTER+TITLE` argument will print both the concatenated chapter string+number and the chapter title. For example, assuming a vanilla setup for your chapter:
.CHAPTER 1 .CHAPTER_TITLE "The Bonny Blue Yonder" .COVER CHAPTER+TITLE \"(or .DOC_COVER CHAPTER+TITLE) will print
Chapter 1 The Bonny Blue Yonder

### DOC_COVERTEXT and COVERTEXT

Macro: DOC_COVERTEXT `[START <starting position>] <toggle>`
Macro: COVERTEXT `[START <starting position>] <toggle>`

• Must come after PRINTSTYLE

`DOC_COVERTEXT` and `COVERTEXT` 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 DOC_COVER and COVER.

Invoke `.DOC_COVERTEXT` or `.COVERTEXT` on a line by itself, follow it with the text and formatting you desire, and terminate the text block with `.DOC_COVERTEXT OFF` or `COVERTEXT OFF` (or `QUIT, END, DONE`, etc.).

By default, cover text is set over the full line length of the document, using the style parameters of running text. 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; PP is the only allowed document element tag.

#### Placement

If you do not instruct mom to put anything on doc cover or cover pages except `DOC_COVERTEXT` or `COVERTEXT`, the cover text will begin at the document’s top margin. Equally, if only `COPYRIGHT` and/or `MISC` 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.

If you wish to change the starting position of the text, you must use SP or ALD 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.

`DOC_COVERTEXT` and `COVERTEXT` are particularly useful for putting abstracts on cover pages, as technical reports often require.

Here’s a simple recipe for setting an abstract:
.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 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.

### DOC_COVER_IMAGE and COVER_IMAGE

Macro: DOC_COVER_IMAGE `<image> <width> <height> [ -L | -C | -R | -I <indent> <Y-pos> [ <X-pos> ] ]`
Macro: COVER_IMAGE `<image> <width> <height> [ -L | -C | -R | -I <indent> <Y-pos> [ <X-pos> ] ]`

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.

DOC_COVER_IMAGE and COVER_IMAGE take the same arguments as PDF_IMAGE, and in the same order. Consult PDF_IMAGE for a description.

Two additional arguments allow you to place images using x-y coordinates. Please note that if you use x-y coordinates for positioning, Y-pos comes before X-pos in the order of arguments.

Like PDF_IMAGE, the image file must be in PDF format. Mom apologizes, but PostScript images are not supported for inclusion on covers. See Image conversion and file processing for instructions on converting various image types to PDF, and here for instructions on obtaining image dimensions.

#### Positioning of doc cover and cover images

With no arguments other than `<file name>`, `<width>`, and `<height>`, 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,
.DOC_COVER_IMAGE image.pdf 612p 792p .DOC_COVER TITLE AUTHOR DOC_COVER_IMAGE will fill the doc cover page with “image.pdf” and set the title and author in their usual locations.

For smaller images, the horizontal position is established with one of the `-L`, `-C`, `-R`, or `-I <indent>` arguments, just like PDF_IMAGE. You may instead use the `X-pos` argument, provided that it is preceded by a `Y-pos` argument. The values given to `-I`, `Y-pos` and `X-pos` must have a unit of measure appended to them.

Vertical positioning of smaller images requires the `Y-pos` argument (which is why it precedes `X-pos` in the order of arguments) otherwise the image will be flush with the top edge of the printer sheet

The positioning of images does not effect the placement of type on doc cover and cover pages.

Tip: The combination of COVERTEXT and COVER_IMAGE make it possible to design covers entirely to your own specifications.

### Enabling/disabling automatic generation of cover pages

Macro: COVERS `<toggle>`
Macro: DOC_COVERS `<toggle>`

By default, if you give mom a COVER or DOC_COVER 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 collated, such behaviour may not be desirable.

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 (`OFF, QUIT, X`, etc) disables cover or doc cover generation.

Note: You must place these macros prior to any instance of START. 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 `OFF, NO, X`, 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.

## Control macros for doc covers and covers

The default typographic appearance of the items on a doc cover or cover is identical to that of the items in a docheader. (See Docheader description for a description of the defaults.)

COPYRIGHT and MISC, which do not appear in docheaders, have the following default characteristics:

- the COPYRIGHT line is set flush with the document’s right and bottom margins, 2 point sizes smaller than the size of running text
- 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.

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 Control macros for docheaders (q.v.) The only difference is the name by which you invoke them. Wherever `DOCHEADER` is used for overall changes, replace it with `DOC_COVER` or `COVER`. For part-by-part changes, prepend `DOC_COVER_` or `COVER_` to the part/parameter.

Thus, to change the overall family, color, leading, quad, and starting position of a doc cover, you’d do
.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 To change the style parameters for selected parts of a cover, you might do something like this:
.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 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.

Tip: As with the docheader control macros, `DOC_COVER_` and `COVER_` part/parameter style changes may be grouped, for example
.DOC_COVER_TITLE_STYLE \ FAMILY A \ FONT B \ SIZE +4 \ CAPS

Back to Table of Contents | Top | Next: Tables of contents