Mom -- Document processing, creating a cover page

Next Prev Back to Table of Contents

# CREATING A COVER PAGE

- Introduction to cover pages
  - Important note -- please read
  - Description of what mom does on cover pages
  - A note on headers/footers and pagination
  - What to do if you want to design your own cover pages
- The cover and document cover macros
  - COVER/DOC_COVER
    - The required argument
    - How the CHAPTER argument and friends work
    - The optional arguments
    - What the DOCTYPE argument means
- Enabling/disabling automatic generation of cover pages
- Control macros--changing the defaults for covers and document covers

## Introduction to cover pages

As of version 1.19 of mom, you can now have cover pages generated automatically.

Though identical in treatment, mom provides two kinds of cover pages: section cover pages (which I shall refer to simply as "cover pages") and document cover pages ("doc covers").

A document cover page (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 section cover 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".

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

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.

Important note: automatic generation of cover or doc cover pages 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 what mom does on cover pages

By default, mom typesets cover (and doc cover) pages 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

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

By default, mom 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 COVER_ADVANCE/DOC_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) page. The default point size and the position can be controlled with COVER_COPYRIGHT_SIZE/DOC_COVER_COPYRIGHT_SIZE and COVER_COPYRIGHT_QUAD/DOC_COVER_COPYRIGHT_QUAD.

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) page. The default point size is dependent on COVER_COPYRIGHT_SIZE/DOC_COVER_COPYRIGHT_SIZE, but the position can be controlled with COVER_MISC_QUAD/DOC_COVER_MISC_QUAD.

NOTE: mom does not set any headers or footers 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 COLLATE manually with PAGENUMBER.

Finally, if you want to design your own cover page(s), you can always typeset them (using the typesetting macros), invoke NEWPAGE, set up your document in full (see Tutorial -- Setting up a mom document), and lastly invoke START. The cover page (and any typesetting commands on it) will have no effect on mom's processing of the document itself, the first page of which, moreover, will be numbered "1" unless you instruct her otherwise with PAGENUMBER.

Macro: COVER
Macro: DOC_COVER
Required argument: TITLE | DOCTITLE | COVERTITLE | CHAPTER | CHAPTER_TITLE | CHAPTER+TITLE
Optional arguments: [ SUBTITLE AUTHOR DOCTYPE COPYRIGHT MISC ]

*Note: these macros should be placed in the "style-sheet" section of your document setup (see the Tutorial -- Setting up a mom document), i.e. after PRINTSTYLE (and/or DOCTYPE and/or COPYSTYLE), but before START.

COVER and DOC_COVER behave identically. The reason mom provides two macros for automatic 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 (or cover "sheet", if you prefer) containing just the name of the section.

### The required argument

Both COVER and DOC_COVER, whenever invoked, require a first argument, as listed above. This first argument will become the first bit of information mom prints on the cover (or doc cover) page (i.e. it will be the "title").

In order for the information to appear, you must, of course, first have given mom the appropriate reference macro. A list of arguments with their equivalent reference macros follows.

TITLE
  -means the argument you gave to TITLE
DOCTITLE
  -means the argument you gave to DOCTITLE
COVERTITLE
  -means the argument you gave to COVERTITLE or DOC_COVERTITLE
CHAPTER, CHAPTER_TITLE, CHAPTER+TITLE
  -see below (How the CHAPTER argument and friends work)

### How the CHAPTER argument and friends work

`CHAPTER`, by itself, will print the CHAPTER_STRING as well as the chapter number that you gave to CHAPTER. For example, assuming a vanilla setup for your chapter

    	\# Reference macros
    	.CHAPTER 1
    	.CHAPTER_TITLE "The Bonny Blue Yonder"
    	<other stuff>
    	.COVER CHAPTER \" (or .DOC_COVER CHAPTER)
    	.START

will simply print

    	Chapter 1

`CHAPTER_TITLE` will print the chapter title you gave to CHAPTER_TITLE. For example, assuming a vanilla setup for your chapter

    	\# Reference macros
    	.CHAPTER 1
    	.CHAPTER_TITLE "The Bonny Blue Yonder"
    	<other stuff>
    	.COVER CHAPTER_TITLE \" (or .DOC_COVER CHAPTER_TITLE)
    	.START

will simply print

    	The Bonny Blue Yonder

`CHAPTER+TITLE` will print both the chapter string + number AND the chapter title. For example, assuming a vanilla setup for your chapter

    	\# Reference macros
    	.CHAPTER 1
    	.CHAPTER_TITLE "The Bonny Blue Yonder"
    	<other stuff>
    	.COVER CHAPTER+TITLE \" (or .DOC_COVER CHAPTER+TITLE)
    	.START

will print

    	      Chapter 1
    	The Bonny Blue Yonder

### The optional arguments

The remainder of the arguments to COVER and DOC_COVER are optional. They refer specifically to the information you gave the reference macros bearing the same name as the arguments.

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 `TITLE`, `AUTHOR`, `COPYRIGHT` and `MISC`

    	.COVER TITLE AUTHOR COPYRIGHT MISC

is correct, while

    	.COVER TITLE AUTHOR MISC COPYRIGHT

is not.

### What the DOCTYPE argument means

When you pass COVER or DOC_COVER the argument, `DOCTYPE`, it refers to the argument you gave to DOCTYPE `NAMED`. For example, if, in your docstyle macros you gave a

    	.DOCTYPE NAMED "Abstract"

the argument, `DOCTYPE`, in the COVER or DOC_COVER macros, would mean that you wanted the word, Abstract, to appear on the cover (or doc cover), just as it would in the docheader.

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

By default, if you give mom a COVER or DOC_COVER macro, she will print it. 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 precede all subsequent instances of START.

### Control macros--changing the defaults for covers and document covers

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

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

1. The copyright line is set in the bottom right hand corner of the page, 2 point sizes smaller than the size of running text
2. 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.

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 the control macros used for docheaders. The only difference is the name by which you invoke the control macro(s).

The complete list of cover (and doc cover) page control macros follows; please refer to the docheader control macros index in order to understand how to use them.

### Index of cover and doc cover control macros

    .COVER_ADVANCE  .DOC_COVER_ADVANCE -+
    .COVER_FAMILY   .DOC_COVER_FAMILY   | like DOCHEADER_
    .COVER_LEAD     .DOC_COVER_LEAD    -+

    .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

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

Next Prev Top Back to Table of Contents