Next Prev Back to Table of Contents

# Bibliographies and references

Introduction to bibliographies and references
Tutorial

- Creating a refer database
- Required refer commands
- Accessing references
- Telling mom where to put references
- Creating bibliography pages
- Invoking groff with mom and refer

Index of bibliography and reference macros

- Bibliography page style control macros

## Introduction to bibliographies and references

Mom provides the ability to automatically format and generate bibliography pages, as well as footnote or endnote bibliographic references, or references embedded in text. She accomplishes this by working in conjunction with a special groff program called "refer".

refer is a groff "pre-processor", which is to say that it scans your files looking for very specific commands (i.e. lines that begin with a period [dot], just like macros and document element tags). If the commands aren't there, refer can't do it's job, and neither can mom. The scanning is done before any actual mom processing occurs.

refer is a program that's been around for a long time. It's powerful and has many, many features. Unfortunately, the manpage (`man refer`), while complete and accurate, is dense and not a good introduction to refer. (It's a classic manpage Catch-22: the documentation is useful only after you already understand it.)

In order to get mom users up and running with refer, this section of mom's documentation focuses exclusively, in a recipe-like manner, on what you need to know to use refer satisfactorily in conjunction with mom. The information and instructions are not to be taken as a manual or tutorial on full refer usage. Much has been left out, on purpose.

It is tempting to provide two levels of documentation, one for users familiar with refer and one for newcomers to groff and mom, but such an approach may muddy the waters for newcomers. Mom's allegiance, first and foremost, is to newcomers. If you're already a refer user, the information herein will be useful for adapting your current refer usage to mom's way of doing things. If you've never used refer, the information is essential, and, in many cases, may be all you need.

(For the benefit of old groff-hands: refer support in mom is heavily based on the refer module of the "ms" macros. The choice was deliberate so that those wishing to play around with mom's bibliography formatting style would be tinkering with the familiar.)

refer requires first that you create a bibliographic database. From the information contained in the database, mom formats and generates bibliographies and references in MLA (Modern Language Association) style. MLA style is clean, contemporary and flexible, and is widely used in the humanities, where the range of material that has to be referenced can run from simple books to live interviews and film.

Once you have created your database, you instruct refer (and mom) to access entries in it by supplying keywords from the entries. Depending on what you've instructed mom to do, she will put the entries — fully and properly formatted with respect to order, punctuation and italicization — in footnotes, endnotes, or a full bibliography.

I encourage anyone interested in what MLA style looks like — and, by extension, how your bibliographies and references will look after mom formats them — to check out

        http://www.aresearchguide.com/12biblio.html

or any other website or reference book on MLA style.

NOTE: MLA style requires that second and subsequent lines of individual references be indented. Mom takes care of this for you with a default indent, which can be changed with the macro INDENT_REFS.

## Tutorial

1. Creating a refer database
2. Required "refer" commands
3. Accessing references
4. Telling mom where to put references
5. Creating bibliography pages
6. Invoking groff with mom and refer

### 1. Creating a refer database

The first step in using refer with mom is setting up your bibliographic database. The database is a file containing separate entries for each reference you want to access from your mom files. The file is not a "mom file"; it is a separate database. You may set up individual databases for individual documents, or create a large database that contains all the references you'll ever need.

Entries ("records") in the database file are separated from each other by a single, blank line. The records themselves are composed of single lines ("fields") with no blank lines between them. Each field begins with a percent sign and a single letter (the "field identifier") e.g. `%A` or `%T`. The letter identifies what part of a bibliographic entry the field refers to: Author, Title, Publisher, Date, etc. After the field identifier comes a single space, followed by the information appropriate to field. No punctuation should go at the ends of fields; mom adds what's correct automatically. Do note, however, that author(s) (`%A`) requires that you enter the author information exactly as you wish it to come out (minus the period), including the comma after the first author's last name.

Here's a sample database containing two records so you can visualize what the above paragraph says:

    %A Schweitzer, Albert
    %A C.M. Widor
    %T J.S. Bach
    %l Ernest Newman
    %V Vol 2
    %C London
    %I Adam and Charles Black
    %D 1923
    %O 2 vols
    %K bach vol 2

    %A Schaffter, Peter
    %T The Schumann Proof
    %C Toronto
    %I RendezVous Press
    %D 2004
    %K schumann schaffter

The order in which you enter fields doesn't matter. mom and refer will re-arrange them in the correct order for you.

The meaning of the letters follows. There are, with refer, quite a few — all uppercase — which have, over time, come to be "standard". Mom respects these. However, she adds to the list (mostly the lowercase letters).

        %A Author           — additional authors may be entered on separate %A
                               lines as in first entry of the sample, above; mom
                               and refer will figure out what to do with multiple
                               authors according to MLA rules
        %T Title            — either the primary title (e.g. of a book), or the
                               title of an article (e.g. within a book or
                               journal or magazine)
        %B Book title       — the title of a book when %T contains the title
                               of an article; otherwise, use %T for book
                               titles
        %R Report number    — for technical reports
        %J Journal name     — the name of a journal or magazine when %T
                               contains the title of an article
        %E Editor           — additional editors may be entered on separate %E
                               lines (like authors); mom and refer will figure
                               out what to do with them according to MLA rules
        %e Edition          — the number of name of a specific edition
                               (e.g. Second, 2nd, Collector's, etc.)
        %V Volume           — volume number of a journal or series of books
        %N Journal number   — journal or magazine number
        %S Series           — series name for books or journals that are part of
                               a series
        %C City             — the city of publication
        %I Publisher        — the publisher; %I stands for "Issuer"
        %D Publication date
        %P Page number(s)   — enter page ranges as, e.g., 22-25
        %G Gov't.
           ordering number  — for government publications
        %O Other            — additional information or comments you want
                               to appear at the end of the reference
        %K Keywords         — any words that will clear up ambiguities
                               resulting from database entries that
                               contain, say, the same author or the
                               same title
        %d original
           publication date — if different from the date
                                           of publication
        %a additions        — for books, any additions to the original work,
                               such as the preface to a new edition or a new
                               introduction
        %t reprint title    — if different from a work's original title
        %l translator       — if the translator is not the editor; if more
                                than one translator, this field should contain
                                all the names, with appropriate punctuation
        %r translator
           and editor       — if tr. and ed. are one in the same;
        %s site name        — for web sites, the site name
        %c content
           of site          — for web sites, the content, if unclear
                               (i.e. advertisement, cartoon, blog)
        %o organization     — for web sites, the organization, group or
                               sponsor of the site
        %a access date      — for a website, the date you accessed it
        %u URL              — for websites, the full URL of the site

Tip: If you have hyphenation turned on in your document (you probably do), mom will hyphenate your references. This can be a problem because references typically contain several proper names. Proper names shouldn't be hyphenated. The solution is to prepend to any proper name in the database the groff discretionary hyphen character, `\%`, like this:

        %A Hill, \%Reginald

Alternatively, you can turn hyphenation off entirely in references with the macro, HYPHENATE_REFS `OFF`.

### 2. Required "refer" commands

Having set up your database, you now need to put some refer-specific commands at the top of your mom file. You cannot skip this step, nor can you "source" these commands with the groff primitive, `.so` or the mom macro, INCLUDE. They must appear, exactly as shown, in every file requiring bibliographic references.

refer commands are introduced with a single line containing `.R1`, and concluded with a single line containing `.R2`. What you put between the `.R1` and `.R2` lines are the commands themselves. The commands should be entered one per line, in lowercase letters, with no initial period (dot).

Here's an example:

        .R1
        no-label-in-text
        no-label-in-reference
        .R2

There are an awful lot of refer commands. We will focus only on those required to get mom cooperating with refer. If you're interested, study the refer manpage to discover what other commands are available and how to manipulate them.

At a minimum, all mom files accessing a bibliographic database must contain the following refer commands, exactly as shown:

    .R1
    no-label-in-text
    no-label-in-reference
    join-authors ", and " ", " ", and "
    database <full path to the database>
    .R2

The first two commands tell refer to let mom handle everything associated with footnote and endnote markers, both in the body of the document, and in the footnotes/endnotes themselves.

The third command is required for mom to handle multiple authors in proper, MLA style.

The last command, `database`, assumes you have created your own database, and do not otherwise have a system-wide "default" database. "...full path to the database" means the full path including the database filename, e.g. `/home/user/refer/my_database.`

If you're already a refer user, feel free to enter whatever refer commands are necessary to access the database(s) you want.

With the above refer block, you can embed references directly into the text of your document, or have them output as footnotes or endnotes. If you want to "collect" references for later output on a bibliography page, the block must read:

    .R1
    no-label-in-text
    no-label-in-reference
    join-authors ", and " ", " ", and "
    database <full path to the database>
    sort
    accumulate
    .R2

### 3. Accessing references

References are accessed by putting keywords, all on one line, between the refer commands `.[` and `.]`. Both of these commands must appear on separate

        .[
        keyword(s)
        .]

lines, by themselves, like this:

Keywords are any word, or set of words, that identify a database record (i.e. a reference) unambiguously. (refer doesn't like ambiguity.)

If, for example, you want to reference a book by Ray Bradbury, and the database contains only one book by Bradbury, a suitable keyword would be "Bradbury". If your database contains several books by Bradbury, say, Fahrenheit 451 and The Martian Chronicles, you could reference them with the keywords, "451" and "Martian". If, in addition to the two books by Bradbury, you also had one whose title was The Martian Mission, suitable keywords to reference The Martian Chronicles might be:

        .[                or    .[                   or  .[
        Bradbury Martian        Bradbury Chronicles      Martian Chronicles
        .]                      .]                       .]

The database field identifier, `%K`, lets you create special keywords for references. This can be very handy if you need both a "short" and a "long" reference to the same work. The short reference might be used in footnotes; the long one in a bibliography. Consider the following:

        %A Isherwood, Christopher      %A Isherwood
        %T Mr. Norris Changes Trains   %T Mr. Norris Changes Trains
        %d 1935                        %K Nor short
        %t The Last of Mr. \%Norris
        %a Intro. Tom Crawford
        %C New York
        %I New Directions
        %D 1945
        %K Norris

To access the shorter reference, you'd do

        .[
        Nor short
        .]

To access the longer one, you'd do

        .[
        Norris
        .]

### 4. Telling mom where to put references

Mom provides several mechanisms for outputting references where you want.

#### Embedding references in the document body

References may be embedded in the document body, surrounded by parentheses, square brackets, or braces. Use whichever you prefer, following the recipes below.

        Parentheses    Square brackets    Braces
        -----------    ---------------    ------

        .REF(          .REF[              .REF{
        .[             .[                 .[
        keyword(s)     keyword(s)         keyword(s)
        .]             .]                 .]
        .REF)          .REF]              .REF}

#### Footnote or endnote references

Most times, you'll probably want references in either footnotes or endnotes. Mom provides a simple mechanism whereby you can choose which, or even switch back and forth. The primary tag is REF, which is used like this:

        .REF
        .[
        keyword(s)
        .]
        .REF

REF collects references and outputs them where you say with the macros, FOOTNOTE_REFS or ENDNOTE_REFS. Neither FOOTNOTE_REFS nor ENDNOTE_REFS requires an argument. All they do is tell REF, whenever it's invoked, where to put the references.

A recipe for footnote references looks like this:

        .FOOTNOTE_REFS
        .REF
        .[
        keyword(s)
        .]
        .REF

When FOOTNOTE_REFS are enabled, REF behaves identically to FOOTNOTE, so please read the HYPER IMPORTANT NOTE found in the document entry for FOOTNOTE.

The reference between the first and second REF will be treated as a footnote, as will all subsequent REF pairs unless you invoke the macro, `.ENDNOTE_REFS`.

A recipe for endnote references looks like this:

        .ENDNOTE_REFS
        .REF
        .[
        keyword(s)
        .]
        .REF

The reference between the first and second REF will be treated as an endnote, as will all subsequent REF pairs unless you invoke the macro, `.FOOTNOTE_REFS`.

When ENDNOTE_REFS are enabled, REF behaves identically to ENDNOTE, so please read the HYPER IMPORTANT NOTE found in the document entry for ENDNOTE.

The innate flexibility of this scheme allows you to have both footnote references and endnote references in the same document. This would be desirable if, say, you wanted "short" references in footnotes, and complete references in endnotes.

#### Collected references

Sometimes, you may want to put references in input text near sections of text to which they pertain, but not actually want them output until later (typically, on a bibliography page). REF is used for this, too, but you have to make sure your refer commands block is set up properly. The recipe for this is:

    .R1
    no-label-in-text
    no-label-in-reference
    join-authors ", and " ", " ", and "
    database <full path to the database>
    sort
    accumulate
    .R2

After this set up, and provided you don't issue a `.FOOTNOTE_REFS` or `.ENDNOTE_REFS` command, all reference between REF pairs will be collected for later output.

As a precaution, mom will issue a message the first time you call `.REF` if neither FOOTNOTE_REFS nor ENDNOTE_REFS is in effect. If collected references are what you want, and you have set up your `.R1 -.R2` block as above, you may safely ignore the message.

LIMITATION: You cannot combine "collected" references (plain REF) with REFs that are instructed to go into footnotes (with FOOTNOTE_REFS) or endnotes (with ENDNOTE_REFS). This is a limitation imposed by refer, not mom.

### 5. Creating bibliography pages

Bibliography pages are separate pages, like endnotes, on which complete bibliographies are output. And, like endnotes pages, just about every element on them can be designed to your specifications with control macros. (See Control macros for bibliographies.) A bibliography page that uses mom's defaults begins with the macro, BIBLIOGRAPHY, like this:

        .BIBLIOGRAPHY

Following BIBLIOGRAPHY, you have three choices of how to proceed.

If you have elected to have references collected from within the body of a document (see above, Collected references, for instructions), which assumes you have a refer command block like the one here at the top of your document, you need only do

        .BIBLIOGRAPHY
        .[
        $LIST$
        .]

If you want to create the bibliography by hand (which may be the case if you've used footnote and/or endnote references throughout your document), follow this recipe, which assumes you already have a refer block like the one here at the top of your document:

        .BIBLIOGRAPHY
        .R1
        sort
        accumulate
        .R2
        .[          -+
        keyword(s)   |
        .]           | "keyword(s)" are keywords identifying the
        .[           | particular bibliographic reference you want
        keyword(s)   | from your database.  Order doesn't matter here;
        .]           | the refer command, sort, takes care of that.
        .[           |
        keyword(s)   |
        .]          -+
        .[
        $LIST$
        .]

Your final choice is to output your whole database. Again, assuming you have a refer block like the one here at the top of your file, you need only do:

        .BIBLIOGRAPHY
        .R1
        bibliography <full path to database>
        .R2

If you haven't put a refer block in your file already, you can put the whole thing after BIBLIOGRAPHY, like this:

        .BIBLIOGRAPHY
        .R1
        no-label-in-text                       -+
        no-label-in-reference                   | These are actually optional
        database <full path to the database>   -+
        join-authors ", and " ", " ", and "
        bibliography <full path to database>
        .R2

Whichever option you choose, mom will output a full bibliography page, complete with a title ("BIBLIOGRAPHY" by default, but that can be changed).

### 6. Invoking groff with mom and refer

So, now you've got a document, formatted properly to use references processed with refer, what do you do to output the document?

It's simple. Instead of invoking groff with just the `-mom` option, as explained here, invoke groff with the `-R` option as well, like this:

        groff -R -mom filename

### Index of bibliography and reference macros

- Tag: REF — collected, footnote or endnote references tag
- FOOTNOTE_REFS — REFs go to footnotes
- ENDNOTE_REFS — REFs go to endnotes
- REF( — references embedded in text between parentheses
- REF[ — references embedded in text between square brackets
- REF{ — references embedded in text between braces
- INDENT_REFS — manage the 2nd line indent of references
- HYPHENATE_REFS — en/disable hyphenation of references
- BIBLIOGRAPHY — begin a bibliography page
- BIBLIOGRAPHY_TYPE — plain, or numbered list bibliography
- Bibliography page style control macros

#### Marking off references for footnotes, endnotes, or collection

Tag: REF

The macro, REF, tells mom that what follows is refer-specific, a keyword-identified reference from a refer database. Depending on whether you've issued a FOOTNOTE_REFS or ENDNOTE_REFS instruction, REF also tells mom where to place the reference. If FOOTNOTE_REFS, the reference will be formatted and placed in a footnote. If ENDNOTE_REFS, the reference will be collected for output as an endnote. If you have issued neither instruction, the reference will be collected for later output, most likely on a bibliography page.

Before you use REF, you must create a refer block containing refer commands (see Required refer commands in the tutorial, above).

REF usage always looks like this:

        .REF
        .[
        keyword(s)
        .]
        .REF

Notice that REF "brackets" the refer call, and never takes an argument.

What REF really is is a convenience. One could, for example, put a reference in a footnote by doing

        .FOOTNOTE
        .[
        keyword(s)
        .]
        .FOOTNOTE OFF

However, if you have a lot of references going into footnotes (or endnotes), it's much shorter to type `.REF/.REF` than `.FOOTNOTE/.FOOTNOTE OFF`. It also helps you distinguish — visually, in your input file — between footnotes (or endnotes) which are references, and footnotes (or endnotes) which are explanatory, or expand on the text.

Additional arguments: If you're using REF to put references in footnotes and your footnotes need to be indented, you may (indeed, should) pass REF the same arguments used to indent footnotes. See FOOTNOTE.

Note: When REF is used with FOOTNOTE_REFS, it behaves identically to FOOTNOTE, so please read the HYPER IMPORTANT NOTE found in the document entry for FOOTNOTE.

When REF is used with ENDNOTE_REFS, it behaves identically to ENDNOTE, so please read the HYPER IMPORTANT NOTE found in the document entry for ENDNOTE.

#### Instruct REF to put references in footnotes

Macro: FOOTNOTE_REFS

FOOTNOTE_REFS is an instruction to REF, saying, "put all subsequent references bracketed by the REF macro into footnotes." You invoke it by itself, with no argument.

When FOOTNOTE_REFS is in effect, regular footnotes, (i.e. those introduced with `.FOOTNOTE` and terminated with `.FOOTNOTE OFF`) continue to behave normally.

You may switch between FOOTNOTE_REFS and ENDNOTE_REFS at any time.

If you have a lot of footnote references, and are identifying footnotes by line number rather than by markers in the text, you may want to enable FOOTNOTES_RUN_ON in conjunctions with FOOTNOTE_REFS.

#### Instruct REF to put references in endnotes

Macro: ENDNOTE_REFS

ENDNOTE_REFS is an instruction to REF, saying, "add all subsequent references bracketed by the REF macro to endnotes." You invoke it by itself, with no argument.

When ENDNOTE_REFS is in effect, mom continues to format regular endnotes, (i.e. those introduced with `.ENDNOTE` and terminated with `.ENDNOTE OFF`) in the normal way.

You may switch between ENDNOTE_REFS and FOOTNOTE_REFS at any time.

#### References embedded in text

Macro pair: REF( ... REF)
Macro pair: REF[ ... REF]
Macro pair: REF{ ... REF}

You may sometimes want to embed references directly into the body of your documents, typically, but not always, inside parentheses. Mom makes this possible through the use of the REF<bracket type> macros.

All three macro pairs, above, are invoked the same way, namely by introducing the reference with the first ("open") macro of the REF<bracket type> pair, and terminating it with the second ("close") REF<bracket type> of the pair. For example

        .REF(
        .[
        keyword(s)
        .]
        .REF)

will embed a reference in the body of your document, surrounded by parentheses. .REF[ ... .REF] will surround the reference with square brackets. .REF{ ... .REF} will surround it with curly braces.

#### Manage the second-line indent of references

Macro: INDENT_REFS `FOOTNOTE | ENDNOTE | BIBLIO <indent>`
*<indent> requires a unit of measure

Proper MLA-style references should have their second, and subsequent lines, if any, indented. Since mom formats references in MLA style, she automatically indents second lines. By default, the indent for the second line of references, regardless of whether the references appear in footnotes, endnotes, or bibliographies, is 1.5 ems for PRINSTYLE TYPESET and 2 ems for PRINSTYLE TYPEWRITE.

If you'd like to change the indent for footnotes, endnotes or bibliographies, just invoke `.INDENT_REFS` with a first argument telling mom for which you want the indent changed, and a second argument saying what you'd like the indent to be. For example, if you want the second-line indent of references on a bibliography page to be 3 picas,

        .INDENT_REFS BIBLIO 3P

is how you'd set it up.

Tip: if you are identifying endnotes by line number (ENDNOTE_MARKER_STYLE `LINE`) and you have instructed mom to put references bracketed by REF into endnotes (with ENDNOTE_REFS), you will almost certainly want to adjust the second-line indent for references in endnotes, owing to the way mom formats line-numbered endnotes. Study the output of such documents to see whether an indent adjustment is required.

The same advice applies to references in endnotes when you have enabled ENDNOTE_NUMBERS_ALIGN_LEFT in favour of mom's default ENDNOTE_NUMBERS_ALIGN_RIGHT. Study the output to determine what size of second-line indent works best.

(Frankly, endnote references formatted in MLA-style combined with left-aligned endnote numbers is a no-win situation, and so is best avoided. Wherever you set the indent, you'll end up with the endnote numbers appearing to hang into the left margin, so you might as well have them hang, as is the case with `.ENDNOTE_NUMBERS_ALIGN_RIGHT`. Ed.)

#### Enable/disable hyphenation of references

Macro: HYPHENATE_REFS `<toggle>`

If you have hyphenation turned on for a document (see HY), and in most cases you probably do, mom will hyphenate references bracketed by the REF macro. Since references typically contain quite a lot of proper names, which shouldn't be hyphenated, you may want to disable hyphenation for references.

HYPHENATE_REFS is a toggle macro; invoking it by itself will turn automatic hyphenation of REF-bracketed references on (the default). Invoking it with any other argument (OFF, NO, X, etc.) will disable automatic hyphenation for references bracketed by REF.

An alternative to turning reference hyphenation off is to prepend to selected proper names in your refer database the groff discretionary hyphen character, `\%`. (See here in the tutorial for an example.)

Note: references embedded in the body of a document with REF<bracket type> are considered part of running text, and are hyphenated (or not) according to whether hyphenation is turned on or off for running text. Therefore, if you want to disable hyphenation for such references, you must do so temporarily, with HY, like this:

        .HY OFF
        .REF(
        .[
        keyword(s)
        .]
        .REF)
        .HY

Alternatively, sprinkle your database fields liberally with `\%`.

#### Begin a bibliography page

Macro: BIBLIOGRAPHY

If you want to append a bibliography to your document, all you need do is invoke `.BIBLIOGRAPHY` at the place you want it. BIBLIOGRAPHY breaks to a new page, prints the title (BIBLIOGRAPHY by default, but that can be changed), and awaits refer instructions. How to create bibliographies is covered in the tutorial section, Creating bibliography pages.

See the Bibliography page style control macros for macros to tweak, design and control the appearance of bibliography pages.

#### Plain, or numbered list bibliography

Macro: BIBLIOGRAPHY_TYPE `PLAIN | LIST [ <list separator> ] [ <list prefix> ]`

Mom offers two styles of bibliography output: plain, or numbered list style. With `PLAIN`, bibliography entries are output with no enumerators. With `LIST`, each entry is numbered.

Entering `.BIBLIOGRPHY_TYPE PLAIN` gives you a plain bibliography.

Entering `.BIBLIOGRAPHY_TYPE LIST` gives you an enumerated bibliography. The two optional arguments, `<list separator>` and `<list prefix>` have the same meaning as the equivalent arguments to LIST (i.e. `<separator>` and `<prefix>`).

You may enter `.BIBLIOGRAPHY_TYPE` either before or after `.BIBLIOGRAPHY`. It must, however, always come before the refer command to output bibliographies. (See the tutorial section, Creating bibliography pages, for instructions on how to output bibliographies.)

Mom's default BIBLIOGRAPHY_TYPE is LIST, with a period (dot) as the separator, and no prefix.

### Bibliography pages style control

Mom processes bibliography pages in a manner very similar to the way she processes endnotes pages. The bibliography page control macros, therefore, behave in the same way as their endnotes pages equivalents.

1. General bibliography pages style control

- Base family/font/quad for bibliographies
- Base point size for bibliographies
- Leading of bibliographies
- Singlespace bibliographies (for TYPEWRITE only)
- Turning off column mode during bibliography output
- Pagination of bibliographies:

- Bibliography pages page numbering style
- Setting the first page number of bibliography pages
- Omitting a page number on the first page of bibliographies

- Suspending pagination of bibliographies

2. Bibliography pages header/footer control

- Modifying what goes in the bibliography pages header/footer
- Enabling a header/footer centre when doctype is CHAPTER
- Allow headers on bibliography pages

3. Bibliography page head (i.e. the title at the top) control

- Creating/modifying the bibliography page head
- Bibliography page head control
- Bibliography page head underlining
- Bibliography page head capitalization

#### 1. General bibliography page style control

##### *Bibliography family/font/quad

See Arguments to the control macros.

    .BIBLIOGRAPHY_FAMILY    default = prevailing document family; default is Times Roman
    .BIBLIOGRAPHY_FONT      default = roman
    .BIBLIOGRAPHY_QUAD*     default = justified

    *Note: BIBLIOGRAPHY_QUAD must be set to either L or J

##### *Bibliography point size

Macro: BIBLIOGRAPHY_PT_SIZE `<base type size of bibliography>`

Unlike most other control macros that deal with size of document elements, BIBLIOGRAPHY_PT_SIZE takes as its argument an absolute value, relative to nothing. Therefore, the argument represents the size of bibliography type in points, unless you append an alternative unit of measure. For example,

        .BIBLIOGRAPHY_PT_SIZE 12

sets the base point size of type on the bibliography page to 12 points, whereas

        .BIBLIOGRAPHY_PT_SIZE .6i

sets the base point size of type on the bibliography page to 1/6 of an inch.

The type size set with BIBLIOGRAPHY_PT_SIZE is the size of type used for the text of the bibliographies, and forms the basis from which the point size of other bibliography page elements is calculated.

The default for PRINTSTYLE TYPESET is 12.5 points (the same default size used in the body of the document).

##### *Bibliography lead

Macro: BIBLIOGRAPHY_LEAD `<base leading of bibliographies> [ ADJUST ]`
*Does not require a unit of measure; points is assumed

Unlike most other control macros that deal with leading of document elements, BIBLIOGRAPHY_LEAD takes as its argument an absolute value, relative to nothing. Therefore, the argument represents the leading of endnotes in points unless you append an alternative unit of measure. For example,

        .BIBLIOGRAPHY_LEAD 14

sets the base leading of type on the bibliography page to 14 points, whereas

        .BIBLIOGRAPHY_LEAD .5i

sets the base leading of type on the bibliography page to 1/2 inch.

If you want the leading of bibliographies adjusted to fill the page, pass BIBLIOGRAPHY_LEAD the optional argument, `ADJUST`. (See DOC_LEAD_ADJUST for an explanation of leading adjustment.)

The default for PRINTSTYLE TYPESET is 14 points, adjusted.

NOTE: Even if you give mom a `.DOC_LEAD_ADJUST OFF` command, she will still, by default, adjust bibliography leading. You MUST enter `BIBLIOGRAPHY_LEAD <lead>` with no `ADJUST` argument to disable this default behaviour.

##### *Singlespace bibliographies (TYPEWRITE only)

Macro: SINGLESPACE_BIBLIOGRAPHY `<toggle>`

If your PRINTSTYLE is TYPEWRITE and you use TYPEWRITE's default double-spacing, bibliographies are double-spaced. If your document is single-spaced, bibliographies are single-spaced.

If, for some reason, you'd prefer that bibliographies be single-spaced in an otherwise double-spaced document (including double-spaced collated documents), invoke `.SINGLESPACE_BIBLIOGRAPHY` with with no argument.

##### *Adjusting the space between bibliography entries

Macro: BIBLIOGRAPHY_SPACING `<amount of space>`
*Requires a unit of measure

By default, mom inserts 1 linespaces between bibliography entries on bibliography pages. If you'd prefer she add a different amount of space, instruct her to do so with the macro, BIBLIOGRAPHY_SPACING. Say, for example, you'd prefer only 1/2 linespace. That would be done with

        .BIBLIOGRAPHY_SPACING .5v

As with endnotes pages, owing to the space inserted between bibliography entries, bibliography pages may have hanging bottom margins. Unlike endnotes pages, mom is sad to report that there's nothing you can do about this, except a) pray things work out, or b) set your BIBLIOGRAPHY_SPACING to zero.

##### *Turning off column mode during bibliography output

Macro: BIBLIOGRAPHY_NO_COLUMNS `<toggle>`

By default, if your document is set in columns, mom sets the bibliographies in columns, too. However, if your document is set in columns and you'd like the bibliographies not to be, just invoke `.BIBLIOGRAPHY_NO_COLUMNS` with no argument. The bibliography pages will be set to the full page measure of your document.

If you output bibliographies at the end of each document in a collated document set in columns, column mode will automatically be reinstated for each document, even with BIBLIOGRAPHY_NO_COLUMNS turned on.

##### *Bibliography-page page numbering style

Macro: BIBLIOGRAPHY_PAGENUM_STYLE `DIGIT | ROMAN | roman | ALPHA | alpha`

Use this macro to set the page numbering style of bibliography pages. The arguments are identical to those for PAGENUM_STYLE. The default is `digit`. You may want to change it to, say, `alpha`, which you would do with

        .BIBLIOGRAPHY_PAGENUM_STYLE alpha

##### *Setting the first page number of bibliography pages

Macro: BIBILOGRAPHY_FIRST_PAGENUMBER `<page # that appears on page 1 of bibliographies>`

Use this macro with caution. If all bibliographies for several collated documents are to be output at once, i.e. not at the end of each separate doc, BIBLIOGRAPHY_FIRST_PAGENUMBER tells mom what page number to put on the first page of the bibliography.

If you set BIBLIOGRAPHY_FIRST_PAGENUMBER in collated documents where the bibliographies are output after each separate doc, you have to reset every separate document's first page number after COLLATE and before START.

##### *Omitting a page number on the first page of bibliographies

Macro: BIBLIOGRAPHY_NO_FIRST_PAGENUM `<toggle>`

This macro is for use only if FOOTERS are on. It tells BIBLIOGRAPHY not to print a page number on the first bibliography page. Mom's default is to print the page number.

##### *Suspending pagination of bibliography pages

Macro: SUSPEND_PAGINATION
Macro: RESTORE_PAGINATION

SUSPEND_PAGINATION doesn't take an argument. Invoked immediately prior to BIBLIOGRAPHY, it turns off pagination for the duration of the bibliography. Mom continues, however to increment page numbers silently.

To restore normal document pagination after bibliographies, invoke `.RESTORE_PAGINATION` (again, with no argument) immediately after you've finished with your bibliography.

#### 2. Bibliography page header/footer control

If you wish to modify what appears in the header/footer that appears on bibliography pages, make the changes before you invoke `.BIBLIOGRAPHY`, not afterwards.

Except in the case of DOCTYPE CHAPTER, mom prints the same header or footer used throughout the document on bibliography pages. Chapters get treated differently in that, by default, mom does not print the header/footer centre string (normally the chapter number or chapter title.) In most cases, this is what you want. However, should you not want mom to remove the centre string from the bibliography pages headers/footers, invoke `.BIBLIOGRAPHY_HEADER_CENTER` with no argument.

An important change you may want to make is to put the word "Bibliography" in the header/footer centre position. To do so, do

        .HEADER_CENTER "Bibliography"
                   or
        .FOOTER_CENTER "Bibliography"

prior to invoking `.BIBLIOGRAPHY`. If your DOCTYPE is `CHAPTER`, you must also invoke `.BIBLIOGRAPHY_HEADER_CENTER` for the HEADER_CENTER to appear.

##### *Bibliography page header/footer centre string

Macro: BIBLIOGRAPHY_HEADER_CENTER `toggle`

If your DOCTYPE is `CHAPTER` and you want mom to include a centre string in the headers/footers that appear on bibliography pages, invoke `.BIBLIOGRAPHY_HEADER_CENTER` (or `.BIBLIOGRAPHY_FOOTER_CENTER`) with no argument. Mom's default is NOT to print the centre string.

If, for some reason, having enabled the header/footer centre string on bibliography pages, you wish to disable it, invoke the same macro with any argument (OFF, QUIT, Q, X...).

##### *Allow headers on bibliography pages

Macro: BIBLIOGRAPHY_ALLOWS_HEADERS `<none> | ALL`

By default, if HEADERS are on, mom prints page headers on all bibliography pages except the first. If you don't want her to print headers on bibliography pages, do

        .BIBLIOGRAPHY_ALLOWS_HEADERS OFF

If you want headers on every page including the first, do

        .BIBLIOGRAPHY_ALLOWS_HEADERS ALL

NOTE: If FOOTERS are on, mom prints footers on every bibliography page. This is a style convention. In mom, there is no such beast as BIBLIOGRAPHY_ALLOWS_FOOTERS OFF.

#### 3. Bibliography page first page head (title) control

##### *Bibliography pages first page head (title) string

Macro: BIBLIOGRAPHY_STRING `"<head to print at the top of bibliography pages>"`

By default, mom prints the word "BIBLIOGRAPHY" as a head at the top of the first page of a bibliography. If you want her to print something else, invoke `.BIBLIOGRAPHY_STRING` with the bibliography page head you want, surrounded by double-quotes. If you don't want a head at the top of the first bibliography page, invoke `.BIBLIOGRAPHY_STRING` with a blank argument (either two double-quotes side by side — `""` — or no argument at all).

##### *Bibliography page first page head (title) control

See Arguments to the control macros.

    .BIBLIOGRAPHY_STRING_FAMILY    default = prevailing document family; default is Times Roman
    .BIBLIOGRAPHY_STRING_FONT      default = bold
    .BIBLIOGRAPHY_STRING_SIZE*     default = +1
    .BIBLIOGRAPHY_STRING_QUAD      default = centred

    *Relative to the size of the bibliography text (set with BIBLIOGRAPHY_PT_SIZE)

##### *Bibliography-page head (title) underlining

Macro: BIBLIOGRAPHY_STRING_UNDERLINE `[DOUBLE] [<underline weight> [<underline gap> [<distance between double rules]]] | <none> | <anything>`
Alias: BIBLIOGRAPHY_STRING_UNDERSCORE
*The argument `<underline weight>` must NOT have the unit of measure, `p`, appended to it

Invoked without an argument, `.BIBLIOGRAPHY_STRING_UNDERLINE` will place a single rule underneath the bibliography-page head. Invoked with the argument `DOUBLE`, BIBLIOGRAPHY_STRING_UNDERLINE will double-underline the head. Invoked with any other non-numeric argument, (e.g. OFF, NO, X, etc.) the macro disables underlining of the head.

In addition, you can use BIBLIOGRAPHY_STRING_UNDERLINE to control the weight of the underline rule(s), the gap between the head and the underline, and, in the case of double-underlines, the distance between the two rules.

Some examples:

        .BIBLIOGRAPHY_STRING_UNDERLINE 1
            - turn underlining on; set the rule weight to 1 point

        .BIBLIOGRAPHY_STRING_UNDERLINE 1 3p
            - turn underlining on; set the rule weight to 1 point; set
              the gap between the string and the underline to 3 points

        .BIBLIOGRAPHY_STRING_UNDERLINE DOUBLE .75 3p
            - turn double-underlining on; set the rule weight to 3/4 of
              a point; set the gap between the string and the upper
              underline to 3 points; leave the gap between the upper
              and the lower underline at the default

        .BIBLIOGRAPHY_STRING_UNDERLINE DOUBLE 1.5 1.5p 1.5p
            - turn double-underlining on; set the rule weight to 1-1/2
              points; set the gap between the string and the upper
              underline to 1-1/2 points; set the gap between the upper
              and the lower underline to 1-1/2 points

Note, from the above, that in all instances, underlining (single or double) is enabled whenever BIBLIOGRAPHY_STRING_UNDERLINE is used in this way.

Mom's default is to double-underline the head with 1/2-point rules placed 2 points apart and 2 points below the baseline of the head.

##### *Bibliography-page head (title) automatic capitalization

Macro: BIBLIOGRAPHY_STRING_CAPS `toggle`

Invoked by itself, `.BIBLIOGRAPHY_STRING_CAPS` will automatically capitalize the bibliography page head. Invoked with any other argument, the macro disables automatic capitalization of the head.

If you're generating a table of contents, you may want the bibliography page head string in caps, but the toc entry in caps/lower case. If the argument to BIBLIOGRAPHY_STRING is in caps/lower case and BIBLIOGRAPHY_STRING_CAPS is on, this is exactly what will happen.

Mom's default is to capitalize the bibliography-page head string.

Next Prev Top Back to Table of Contents