contrib/groff/contrib/mom/momdoc/refer.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
   2 <html>
   3 <head>
   4 <meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
   5 <title>Mom -- Bibliographies and References</title>
   6 </head>
   7 <body bgcolor="#dfdfdf">
   8
   9 <!====================================================================>
  10
  11 <a href="letters.html#TOP">Next</a>&nbsp;&nbsp;
  12 <a href="cover.html#TOP">Prev</a>&nbsp;&nbsp;
  13 <a href="toc.html">Back to Table of Contents</a>
  14
  15 <a name="TOP"></a>
  16 <h1 align="center">
  17     <a name="REF_INTRO"><u>Bibliographies and references</u></a>
  18 </h1>
  19 <p>
  20 <a href="#INTRO_REF">Introduction to bibliographies and references</a>
  21 <br>
  22 <a href="#TUTORIAL_REF">Tutorial</a>
  23 <ul>
  24         <li><a href="#DB_REF">Creating a refer database</a>
  25         <li><a href="#RCOMMANDS_REF">Required "refer" commands</a>
  26         <li><a href="#ACCESSING_REF">Accessing references</a>
  27         <li><a href="#WHERE_REF">Telling mom where to put references</a>
  28         <li><a href="#BIBLIO_REF">Creating bibliography pages</a>
  29         <li><a href="#INVOKING_REF">Invoking groff with mom and refer</a>
  30 </ul>
  31 <br>
  32 <a href="#MACROS_REF">Index of bibliography and reference macros</a>
  33 <p>
  34
  35 <a name="INTRO_REF">
  36         <h2><u>Introduction to bibliographies and references</u></h2>
  37 </a>
  38
  39 <strong>Mom</strong> provides the ability to automatically format
  40 and generate bibliography pages, as well as footnote or endnote
  41 bibliographic references, or references embedded in text.  She
  42 accomplishes this by working in conjunction with a special
  43 <strong>groff</strong> program called "refer".
  44 <p>
  45 <strong>refer</strong> is a <strong>groff</strong>
  46 "pre-processor", which is to say that it scans your files looking
  47 for very specific commands (i.e. lines that begin with a period
  48 [dot], just like macros and document element tags).  If the
  49 commands aren't there, <strong>refer</strong> can't do it's job,
  50 and neither can <strong>mom</strong>.  The scanning is done
  51 <strong>before</strong> any actual <strong>mom</strong> processing
  52 occurs.
  53 <p>
  54 <strong>refer</strong> is a program that's been around for a long
  55 time.  It's powerful and has many, many features.  Unfortunately,
  56 the manpage (<kbd>man refer</kbd>), while complete and accurate, is
  57 dense and not a good introduction to <strong>refer</strong>.  (It's
  58 a classic manpage Catch-22: the information it contains is most
  59 useful only after you already grasp it.)
  60 <p>
  61 In order to get <strong>mom</strong> users up and running with
  62 <strong>refer</strong>, this section of <strong>mom</strong>'s
  63 documentation focuses exclusively, in a recipe-like manner, on
  64 what you need to know to use <strong>refer</strong> satisfactorily
  65 in conjunction with <strong>mom</strong>.  The information and
  66 instructions are <strong><em><u>not</u></em></strong> to be taken as
  67 a manual or tutorial on full <strong>refer</strong> usage.  Much has
  68 been left out, on purpose.
  69 <p>
  70 It is tempting to provide two levels of documentation, one for
  71 users familiar with <strong>refer</strong> and one for newcomers
  72 to <strong>groff</strong> and <strong>mom</strong>, but such an
  73 approach may muddy the waters for newcomers. <strong>Mom</strong>'s
  74 allegiance, first and foremost, is to newcomers.  If you're already
  75 a <strong>refer</strong> user, the information herein will be useful
  76 for adapting your current <strong>refer</strong> usage to
  77 <strong>mom</strong>'s way of doing things.  If you've never used
  78 <strong>refer</strong>, the information is essential, and, in many
  79 cases, may be all you need.
  80 <p>
  81 (For the benefit of old groff-hands: <strong>refer</strong>
  82 support in <strong>mom</strong> is heavily based on the
  83 <strong>refer</strong> module of the ms macros.  The choice
  84 was deliberate so that those wishing to play around with
  85 <strong>mom</strong>'s bibliography formatting style would be
  86 tinkering with the familiar.)
  87 <p>
  88 <strong>refer</strong> requires first that you create a
  89 bibliographic database.  From the information contained in the
  90 database, <strong>mom</strong> formats and generates bibliographies
  91 and references in MLA (Modern Language Association) style.  MLA
  92 style is clean, contemporary and flexible, and is widely used in
  93 the humanities, where the range of material that has to be
  94 referenced can run from simple books to live interviews and film.
  95 <p>
  96 Once you have created your database, you instruct
  97 <strong>refer</strong> (and <strong>mom</strong>) to access entries
  98 in it by supplying keywords from the entries.  Depending on what
  99 you've instructed <strong>mom</strong> to do, she will put the
 100 entries--fully and properly formatted with respect to order, punctuation
 101 and italicization--in footnotes, endnotes, or a full bibliography.
 102 <p>
 103 I encourage anyone interested in what MLA style looks like--and, by
 104 extension, how your bibliographies and references will look after
 105 <strong>mom</strong> formats them--to check out
 106 <p>
 107 <pre>
 108         http://www.aresearchguide.com/12biblio.html
 109 </pre>
 110
 111 or any other website or reference book on MLA style.
 112 <p>
 113 <strong>NOTE:</strong> MLA style requires that second and
 114 subsequent lines of individual references be indented.  <strong>Mom</strong>
 115 takes care of this for you with a default indent, which
 116 can be changed with the macro
 117 <a href="#INDENT_REFS">INDENT_REFS</a>.
 118
 119
 120 <a name="TUTORIAL_REF"><h2><u>Tutorial</u></h2></a>
 121
 122 <ol>
 123         <li><a href="#DB_REF">Creating a refer database</a>
 124         <li><a href="#RCOMMANDS_REF">Required "refer" commands</a>
 125         <li><a href="#ACCESSING_REF">Accessing references</a>
 126         <li><a href="#WHERE_REF">Telling mom where to put references</a>
 127         <li><a href="#BIBLIO_REF">Creating bibliography pages</a>
 128         <li><a href="#INVOKING_REF">Invoking groff with mom and refer</a>
 129 </ol>
 130 <p>
 131
 132 <a name="DB_REF"><h3><u>1. Creating a refer database</u></h3><a>
 133 <p>
 134 The first step in using <strong>refer</strong> with
 135 <strong>mom</strong> is setting up your bibliographic database.
 136 The database is a file containing separate entries for each
 137 reference you want to access from your <strong>mom</strong> files.
 138 The file is <em>not</em> a "mom" file; it is a separate database.
 139 You may set up individual databases for individual documents, or
 140 create a large database that contains all the references you'll
 141 ever need.
 142 <p>
 143 Entries ("records") in the database file are separated from each
 144 other by a single, blank line.  The records themselves are composed
 145 of single lines ("fields") with no blank lines between them.  Each
 146 field begins with a percent sign and a single letter (the "field
 147 identifier") e.g. %A or %T. The letter identifies what part of a
 148 bibliographic entry the field refers to: Author, Title, Publisher,
 149 Date, etc.  After the field identifier comes a single space,
 150 followed by the information appropriate to field.  No punctuation
 151 should go at the ends of fields; <strong>mom</strong> adds what's
 152 correct automatically.  Do note, however, that author(s) (%A)
 153 requires that you enter the author information exactly as you wish
 154 it to come out (minus the period), including the comma after the
 155 first author's last name.
 156 <p>
 157 Here's a sample database containing two records so you can
 158 visualize what the above paragraph says:
 159 <p>
 160 <pre>
 161 %A Schweitzer, Albert
 162 %A C.M. Widor
 163 %T J.S. Bach
 164 %l Ernest Newman
 165 %V Vol 2
 166 %C London
 167 %I Adam and Charles Black
 168 %D 1923
 169 %O 2 vols
 170 %K bach vol 2
 171
 172 %A Schaffter, Peter
 173 %T The Schumann Proof
 174 %C Toronto
 175 %I RendezVous Press
 176 %D 2004
 177 %K schumann schaffter
 178 </pre>
 179
 180 The order in which you enter fields doesn't matter.
 181 <strong>mom</strong> and <strong>refer</strong> will re-arrange
 182 them in the correct order for you.
 183 <p>
 184 The meaning of the letters follows.  There are, with
 185 <strong>refer</strong>, quite a few--all uppercase--which have, over
 186 time, come to be "standard". <strong>Mom</strong> respects these.
 187 However, she adds to the list (mostly the lowercase letters).
 188 <p>
 189 <pre>
 190         %A Author           -- additional authors may be entered on separate %A
 191                                lines as in first entry of the sample, above; mom
 192                                and refer will figure out what to do with multiple
 193                                authors according to MLA rules
 194         %T Title            -- either the primary title (e.g. of a book), or the
 195                                title of an article (e.g. within a book or
 196                                journal or magazine)
 197         %B Book title       -- the title of a book when %T contains the title
 198                                of an article; otherwise, use %T for book
 199                                titles
 200         %R Report number    -- for technical reports
 201         %J Journal name     -- the name of a journal or magazine when %T
 202                                contains the title of an article
 203         %E Editor           -- additional editors may be entered on separate %E
 204                                lines (like authors); mom and refer will figure
 205                                out what to do with them according to MLA rules
 206         %e Edition          -- the number of name of a specific edition
 207                                (e.g. Second, 2nd, Collector's, etc.)
 208         %V Volume           -- volume number of a journal or series of books
 209         %N Journal number   -- journal or magazine number
 210         %S Series           -- series name for books or journals that are part of
 211                                a series
 212         %C City             -- the city of publication
 213         %I Publisher        -- the publisher; %I stands for "Issuer"
 214         %D Publication date
 215         %P Page number(s)   -- enter page ranges as, e.g., 22-25
 216         %G Gov't.
 217            ordering number  -- for government publications
 218         %O Other            -- additional information or comments you want
 219                                to appear at the end of the reference
 220         %K Keywords         -- any words that will clear up ambiguities
 221                                resulting from database entries that
 222                                contain, say, the same author or the
 223                                same title
 224         %d original
 225            publication date -- if different from the date
 226                                            of publication
 227         %a additions        -- for books, any additions to the original work,
 228                                                such as the preface to a new edition or a new
 229                                introduction
 230         %t reprint title    -- if different from a work's original title
 231         %l translator       -- if the translator is not the editor; if more
 232                                 than one translator, this field should contain
 233                                 all the names, with appropriate punctuation
 234         %r translator
 235            and editor       -- if tr. and ed. are one in the same;
 236         %s site name        -- for web sites, the site name
 237         %c content
 238            of site          -- for web sites, the content, if unclear
 239                                (i.e. advertisement, cartoon, blog)
 240         %o organization     -- for web sites, the organization, group or
 241                                sponsor of the site
 242         %a access date      -- for a website, the date you accessed it
 243         %u URL              -- for websites, the full URL of the site
 244 </pre>
 245
 246 <a name="REF_DISC_HY"></a>
 247 <strong>Tip:</strong> If you have hyphenation turned on in your
 248 document (you probably do), <strong>mom</strong> will hyphenate
 249 your references.  This can be a problem because references
 250 typically contain several proper names.  Proper names shouldn't be
 251 hyphenated.  The solution is to prepend to any proper name in the
 252 database the <strong>groff</strong>
 253 <a href="definitions.html#TERMS_DISCRETIONARYHYPHEN">discretionary hyphen</a>
 254 character, <strong>\%</strong>, like this:
 255 <p>
 256 <pre>
 257         %A Hill, \%Reginald
 258 </pre>
 259
 260 Alternatively, you can turn hyphenation off entirely in
 261 references with the macro,
 262 <a href="#HYPHENATE_REFS">HYPHENATE_REFS</a> <kbd>OFF</kbd>.
 263 <p>
 264
 265 <a name="RCOMMANDS_REF"><h3><u>2. Required "refer" commands</u></h3><a>
 266 <p>
 267 Having set up your database, you now need to put some
 268 <strong>refer</strong>-specific commands at the top of your
 269 <strong>mom</strong> file.  You cannot skip this step, nor can you
 270 "source" these commands with the <strong>groff</strong>
 271 <a href="definitions.html#TERMS_PRIMITIVES">primitive</a>,
 272 <strong>.so</strong>.  They <strong><em>must</em></strong>
 273 appear, exactly as shown, in every file requiring bibliographic
 274 references.
 275 <p>
 276 <strong>refer</strong> commands are introduced with a single
 277 line containing <kbd>.R1</kbd>, and concluded with a single line
 278 containing <kbd>.R2</kbd>.  What you put between the <kbd>.R1</kbd>
 279 and <kbd>.R2</kbd> lines are the commands themselves.  The commands
 280 should be entered one per line, in lowercase letters, <em><u>with
 281 no initial period (dot)</u></em>.
 282 <p>
 283 Here's an example:
 284 <p>
 285 <pre>
 286         .R1
 287         no-label-in-text
 288         no-label-in-reference
 289         .R2
 290 </pre>
 291
 292 There are an awful lot of <strong>refer</strong> commands.  We will
 293 focus only on those required to get <strong>mom</strong> cooperating
 294 with <strong>refer</strong>.  If you're interested, study the
 295 <strong>refer</strong> manpage to discover what other commands are
 296 available and how to manipulate them.
 297 <p>
 298 At a minimum, all <strong>mom</strong> files accessing
 299 a bibliographic database must contain the following
 300 <strong>refer</strong> commands, exactly as shown:
 301 <p>
 302 <a name="REFER_BLOCK1"></a>
 303 <pre>
 304 .R1
 305 no-label-in-text
 306 no-label-in-reference
 307 join-authors ", and " ", " ", and "
 308 database &lt;full path to the database&gt;
 309 .R2
 310 </pre>
 311
 312 The first two commands tell <strong>refer</strong> to let
 313 <strong>mom</strong> handle everything associated with footnote
 314 and endnote markers, both in the body of the document, and in the
 315 footnotes/endnotes themselves.
 316 <p>
 317 The third command is required for <strong>mom</strong> to handle
 318 multiple authors in proper, MLA style.
 319 <p>
 320 The last command, <kbd>database</kbd>, assumes you have created
 321 your own database, and do not otherwise have a system-wide
 322 "default" database.  "...full path to the database" means the full
 323 path <em>including</em> the database filename, e.g.
 324 /home/user/refer/my_database.
 325 <p> If you're already a <strong>refer</strong> user, feel free to
 326 enter whatever <strong>refer</strong> commands are necessary to
 327 access the database(s) you want.
 328 <p>
 329 With the above <strong>refer</strong> block, you can embed
 330 references directly into the text of your document, or have them
 331 output as footnotes or endnotes.  If you want to "collect"
 332 references for later output on a bibliography page, the block must
 333 read:
 334 <p>
 335 <pre>
 336 .R1
 337 no-label-in-text
 338 no-label-in-reference
 339 join-authors ", and " ", " ", and "
 340 database &lt;full path to the database&gt;
 341 sort
 342 accumulate
 343 .R2
 344 </pre>
 345
 346 <a name="ACCESSING_REF"><h3><u>3. Accessing references</u></h3><a>
 347 <p>
 348 References are accessed by putting keywords, all on one line,
 349 between the <strong>refer</strong> commands <strong>.[</strong> and
 350 <strong>.]</strong>.  Both of these commands must appear on separate
 351 lines, by themselves, like this:
 352 <p>
 353 <pre>
 354         .[
 355         keyword(s)
 356         .]
 357 </pre>
 358
 359 Keywords are any word, or set of words, that identify a database
 360 record (i.e. a reference) unambiguously. (<strong>refer</strong>
 361 doesn't like ambiguity.)
 362 <p>
 363 If, for example, you want to reference a book by Ray Bradbury,
 364 and the database contains only one book by Bradbury, a suitable
 365 keyword would be "Bradbury".  If your database contains several
 366 books by Bradbury, say, <em>Fahrenheit 451</em> and <em>The Martian
 367 Chronicles</em>, you could reference them with the keywords, "451"
 368 and "Martian".  If, in addition to the two books by Bradbury, you
 369 also had one whose title was <em>The Martian Mission</em>, suitable
 370 keywords to reference <em>The Martian Chronicles</em> might be:
 371 <p>
 372 <pre>
 373         .[                or    .[                   or  .[
 374         Bradbury Martian        Bradbury Chronicles      Martian Chronicles
 375         .]                      .]                       .]
 376 </pre>
 377
 378 The database field identifier, %K, lets you create special keywords
 379 for references.  This can be very handy if you need both a "short"
 380 and a "long" reference to the same work.  The short reference might
 381 be used in footnotes; the long one in a bibliography.  Consider the
 382 following:
 383 <p>
 384 <pre>
 385         %A Isherwood, Christopher      %A Isherwood
 386         %T Mr. Norris Changes Trains   %T Mr. Norris Changes Trains
 387         %d 1935                        %K Nor short
 388         %t The Last of Mr. \%Norris
 389         %a Intro. Tom Crawford
 390         %C New York
 391         %I New Directions
 392         %D 1945
 393         %K Norris
 394
 395 </pre>
 396
 397 To access the shorter reference, you'd do
 398 <p>
 399 <pre>
 400         .[
 401         Nor short
 402         .]
 403 </pre>
 404
 405 To access the longer one, you'd do
 406 <pre>
 407         .[
 408         Norris
 409         .]
 410 </pre>
 411
 412 <a name="WHERE_REF"><h3><u>4. Telling mom where to put references</u></h3><a>
 413 <p>
 414 <strong>Mom</strong> provides several mechanisms for outputting
 415 references where you want.
 416 <p>
 417 <h3>Embedding references in the document body</h3>
 418 <p>
 419 References may be embedded in the document body, surrounded by
 420 parentheses, square brackets, or braces.  Use whichever you prefer,
 421 following the recipes below.
 422 <p>
 423 <pre>
 424         Parentheses    Square brackets    Braces
 425         -----------    ---------------    ------
 426
 427         .REF(          .REF[              .REF{
 428         .[             .[                 .[
 429         keyword(s)     keyword(s)         keyword(s)
 430         .]             .]                 .]
 431         .REF)          .REF]              .REF}
 432 </pre>
 433
 434 <h3>Footnote or endnote references</h3>
 435 <p>
 436 Most times, you'll probably want references in either footnotes or
 437 endnotes.  <strong>Mom</strong> provides a simple mechanism whereby
 438 you can choose which, or even switch back and forth.  The primary
 439 tag is
 440 <a href="#REF">REF</a>, which is used like this:
 441 <p>
 442 <pre>
 443         .REF
 444         .[
 445         keyword(s)
 446         .]
 447         .REF
 448 </pre>
 449
 450 <strong>REF</strong> collects references and outputs them
 451 where you say with the macros,
 452 <a href="#FOOTNOTE_REFS">FOOTNOTE_REFS</a>
 453 or
 454 <a href="#ENDNOTE_REFS">ENDNOTE_REFS</a>.
 455 Neither
 456 <strong>FOOTNOTE_REFS</strong> nor <strong>ENDNOTE_REFS</strong>
 457 requires an argument.  All they do is tell <strong>REF</strong>,
 458 whenever it's invoked, where to put the references.
 459 <p>
 460 A recipe for footnote references looks like this:
 461 <pre>
 462         .FOOTNOTE_REFS
 463         .REF
 464         .[
 465         keyword(s)
 466         .]
 467         .REF
 468 </pre>
 469
 470 When <strong>FOOTNOTE_REFS</strong> are enabled, <strong>REF</strong>
 471 behaves identically to
 472 <a href="docelement.html#FOOTNOTE">FOOTNOTE</a>,
 473 so please read the
 474 <a href="docelement.html#FOOTNOTE_NOTE">HYPER IMPORTANT NOTE</a>
 475 found in the document entry for <strong>FOOTNOTE</strong>.
 476 <p>
 477 The reference between the first and second <strong>REF</strong>
 478 will be treated as a footnote, as will all subsequent
 479 <strong>REF</strong> pairs unless you invoke the macro,
 480 <strong>ENDNOTE_REFS</strong>.
 481 <p>
 482 A recipe for endnote references looks like this:
 483 <pre>
 484         .ENDNOTE_REFS
 485         .REF
 486         .[
 487         keyword(s)
 488         .]
 489         .REF
 490 </pre>
 491
 492 The reference between the first and second <strong>REF</strong>
 493 will be treated as an endnote, as will all subsequent
 494 <strong>REF</strong> pairs unless you invoke the macro,
 495 <strong>FOOTNOTE_REFS</strong>.
 496 <p>
 497 When <strong>ENDNOTE_REFS</strong> are enabled, <strong>REF</strong>
 498 behaves identically to
 499 <a href="docelement.html#FOOTNOTE">ENDNOTE</a>,
 500 so please read the
 501 <a href="docelement.html#ENDNOTE_NOTE">HYPER IMPORTANT NOTE</a>
 502 found in the document entry for <strong>ENDNOTE</strong>.
 503 <p>
 504 The innate flexibility of this scheme allows you to have both
 505 footnote references and endnote references in the same document.
 506 This would be desirable if, say, you wanted "short" references in
 507 footnotes, and complete references in endnotes.
 508 <p>
 509
 510 <a name="COLLECTED_REF"><h3>Collected references</h3></a>
 511 <p>
 512 Sometimes, you may want to put references in input text near
 513 sections of text to which they pertain, but not actually want
 514 them output until later (typically, on a bibliography page).
 515 <strong>REF</strong> is used for this, too, but you have to make
 516 sure your <strong>refer</strong> commands block is set up properly.
 517 The recipe for this is:
 518 <p>
 519 <a name="REFER_BLOCK2"></a>
 520 <pre>
 521 .R1
 522 no-label-in-text
 523 no-label-in-reference
 524 join-authors ", and " ", " ", and "
 525 database &lt;full path to the database&gt;
 526 sort
 527 accumulate
 528 .R2
 529 </pre>
 530
 531 After this set up, and provided you don't issue a
 532 <strong>FOOTNOTE_REFS</strong> or <strong>ENDNOTE_REFS</strong>
 533 command, all reference between <strong>REF</strong> pairs will be
 534 collected for later output.
 535 <p>
 536 As a precaution, <strong>mom</strong> will issue a message the
 537 first time you call <strong>.REF</strong> if neither
 538 <strong>FOOTNOTE_REFS</strong> nor <strong>ENDNOTE_REFS</strong> is
 539 in effect.  If collected references are what you want, and you have
 540 set up your <strong>.R1 - .R2</strong> block as above, you may
 541 safely ignore the message.
 542 <p>
 543 <strong>LIMITATION:</strong> You cannot combine "collected"
 544 references (plain <strong>REF</strong>) with <strong>REF</strong>s
 545 that are instructed to go into footnotes (with
 546 <strong>FOOTNOTE_REFS</strong>) or endnotes (with
 547 <strong>ENDNOTE_REFS</strong>).  This is a limitation imposed by
 548 <strong>refer</strong>, not <strong>mom</strong>.
 549
 550 <a name="BIBLIO_REF"><h3><u>5. Creating bibliography pages</u></h3><a>
 551 <p>
 552 Bibliography pages are separate pages, like endnotes, on which
 553 complete bibliographies are output.  And, like endnotes pages, just
 554 about every element on them can be designed to your specifications
 555 with control macros.  (See
 556 <a href="#BIBLIO_CONTROL_MACROS">Control macros for bibliographies</a>.)
 557 A bibliography page that uses <strong>mom</strong>'s defaults
 558 begins with the macro,
 559 <a href="BIBLIOGRAPHY">BIBLIOGRAPHY</a>,
 560 like this:
 561 <p>
 562 <pre>
 563         .BIBLIOGRAPHY
 564 </pre>
 565
 566 <p>
 567 Following <strong>BIBLIOGRAPHY</strong>, you have three choices of
 568 how to proceed.
 569 <p>
 570 If you have elected to have references collected from within the
 571 body of a document (see above,
 572 <a href="#COLLECTED_REF">Collected references</a>,
 573 for instructions), which assumes you have a <strong>refer</strong>
 574 command block like the one
 575 <a href="#REFER_BLOCK2">here</a>
 576 at the top of your document, you need only do
 577 <p>
 578 <pre>
 579         .BIBLIOGRAPHY
 580         .[
 581         $LIST$
 582         .]
 583 </pre>
 584
 585 If you want to create the bibliography by hand (which may be the
 586 case if you've used footnote and/or endnote references throughout
 587 your document), follow this recipe, which assumes you already have a
 588 <strong>refer</strong> block like the one
 589 <a href="#REFER_BLOCK1">here</a>
 590 at the top of your document:
 591 <p>
 592 <pre>
 593         .BIBLIOGRAPHY
 594         .R1
 595         sort
 596         accumulate
 597         .R2
 598         .[          -+
 599         keyword(s)   |
 600         .]           | "keyword(s)" are keywords identifying the
 601         .[           | particular bibliographic reference you want
 602         keyword(s)   | from your database.  Order doesn't matter here;
 603         .]           | the refer command, sort, takes care of that.
 604         .[           |
 605         keyword(s)   |
 606         .]          -+
 607         .[
 608         $LIST$
 609         .]
 610 </pre>
 611
 612 Your final choice is to output your whole database.  Again,
 613 assuming you have a <strong>refer</strong> block like the one
 614 <a href="#REFER_BLOCK1">here</a> at the top of your file, you need
 615 only do:
 616 <p>
 617 <pre>
 618         .BIBLIOGRAPHY
 619         .R1
 620         bibliography &lt;full path to database&gt;
 621         .R2
 622 </pre>
 623
 624 If you haven't put a <strong>refer</strong> block in
 625 your file already, you can put the whole thing after
 626 <strong>BIBLIOGRAPHY</strong>, like this:
 627 <p>
 628 <pre>
 629         .BIBLIOGRAPHY
 630         .R1
 631         no-label-in-text                       -+
 632         no-label-in-reference                   | These are actually optional
 633         database &lt;full path to the database&gt;   -+
 634         join-authors ", and " ", " ", and "
 635         bibliography &lt;full path to database&gt;
 636         .R2
 637 </pre>
 638
 639 Whichever option you choose, <strong>mom</strong> will output a
 640 full bibliography page, complete with a title (BIBLIOGRAPHY by
 641 default, but that can be changed).
 642
 643 <a name="INVOKING_REF"><h3><u>6. Invoking groff with mom and refer</u></h3><a>
 644 <p>
 645 So, now you've got a document, formatted properly to use
 646 references processed with <strong>refer</strong>, what do you do to
 647 output the document?
 648 <p>
 649 It's simple.  Instead of invoking <strong>groff</strong> with just
 650 the -mom option, as explained
 651 <a href="using.html#USING_INVOKING">here</a>,
 652 invoke groff with the -R option as well, like this:
 653 <p>
 654 <pre>
 655         groff -R -mom filename
 656 </pre>
 657
 658 <hr width="66%">
 659
 660 <p>
 661 <a name="MACROS_REF"><h3><u>Index of bibliography and reference macros</u></h3></a>
 662 <ul>
 663     <li><a href="#REF">Tag: REF</a> -- collected, footnote or endnote references tag
 664     <li><a href="#FOOTNOTE_REFS">FOOTNOTE_REFS</a> -- REFs go to footnotes
 665     <li><a href="#ENDNOTE_REFS">ENDNOTE_REFS</a> -- REFs go to endnotes
 666     <li><a href="#BRACKET_REFS">REF(</a> -- references embedded in text between parentheses
 667     <li><a href="#BRACKET_REFS">REF[</a> -- references embedded in text between square brackets
 668     <li><a href="#BRACKET_REFS">REF{</a> -- references embedded in text between braces
 669     <li><a href="#INDENT_REFS">INDENT_REFS</a> -- manage the 2nd line indent of references
 670     <li><a href="#HYPHENATE_REFS">HYPHENATE_REFS</a> -- en/disable hyphenation of references
 671     <li><a href="#BIBLIOGRAPHY">BIBLIOGRAPHY</a> -- begin a bibliography page
 672     <li><a href="#BIBLIOGRAPHY_TYPE">BIBLIOGRAPHY_TYPE</a> -- plain, or numbered list bibliography
 673     <li><a href="#BIBLIO_CONTROL">Bibliography page style control</a>
 674 </ul>
 675 <p>
 676
 677 <!---REF--->
 678
 679 <hr width="66%" align="left">
 680 <a name="REF"><h3><u>Marking off references for footnotes, endnotes, or collection</u></h3></a>
 681 <p>
 682
 683 Tag: <strong>REF</strong>
 684 <p>
 685 The macro, <strong>REF</strong>, tells <strong>mom</strong> that
 686 what follows is <strong>refer</strong>-specific, a
 687 keyword-identified reference from a
 688 <strong>refer</strong> database.  Depending on whether you've
 689 issued a
 690 <a href="#FOOTNOTE_REFS">FOOTNOTE_REFS</a>
 691 or
 692 <a href="#ENDNOTE_REFS">ENDNOTE_REFS</a>
 693 instruction, <strong>REF</strong> also tells <strong>mom</strong>
 694 where to place the reference.  If <strong>FOOTNOTE_REFS</strong>,
 695 the reference will be formatted and placed in a footnote.  If
 696 <strong>ENDNOTE_REFS</strong>, the reference will be collected for
 697 output as an endnote.  If you have issued neither instruction, the
 698 reference will be collected for later output, most likely on a
 699 <a href="#BIBLIOGRAPHY">bibliography page</a>.
 700 <p>
 701 Before you use <strong>REF</strong>, you must create a
 702 <strong>refer</strong> block containing <strong>refer</strong>
 703 commands (see
 704 <a href="#RCOMMANDS_REF">Required refer commands</a>
 705 in the tutorial, above).
 706 <p>
 707 <strong>REF</strong> usage always looks like this:
 708 <p>
 709 <pre>
 710         .REF
 711         .[
 712         keyword(s)
 713         .]
 714         .REF
 715 </pre>
 716
 717 Notice that <strong>REF</strong> "brackets" the
 718 <strong>refer</strong> call, and never takes an argument.
 719 <p>
 720 What <strong>REF</strong> really is is a convenience.  One could,
 721 for example, put a reference in a footnote by doing
 722 <p>
 723 <pre>
 724         .FOOTNOTE
 725         .[
 726         keyword(s)
 727         .]
 728         .FOOTNOTE OFF
 729 </pre>
 730
 731 However, if you have a lot of references going into footnotes (or
 732 endnotes), it's much shorter to type <kbd>.REF/.REF</kbd> than
 733 <kbd>.FOOTNOTE/.FOOTNOTE OFF</kbd>.  It also helps you
 734 distinguish--visually, in your input file--between footnotes (or
 735 endnotes) which are references, and footnotes (or endnotes) which
 736 are explanatory, or expand on the text.
 737 <p>
 738 <strong>Additional arguments:</strong> If you're using
 739 <strong>REF</strong> to put references in footnotes and your
 740 footnotes need to be indented, you may (indeed, should) pass
 741 <strong>REF</strong> the same arguments used to indent footnotes.
 742 See
 743 <a href="docelement.html#FOOTNOTE">FOOTNOTE</a>.
 744 <p>
 745 <strong>Note:</strong>
 746 When <strong>REF</strong> is used with
 747 <a href="#FOOTNOTE_REFS">FOOTNOTE_REFS</a>,
 748 it behaves identically to
 749 <a href="docelement.html#FOOTNOTE">FOOTNOTE</a>,
 750 so please read the
 751 <a href="docelement.html#FOOTNOTE_NOTE">HYPER IMPORTANT NOTE</a>
 752 found in the document entry for <strong>FOOTNOTE</strong>.
 753 <p>
 754 When <strong>REF</strong> is used with
 755 <a href="#ENDNOTE_REFS">ENDNOTE_REFS</a>,
 756 it behaves identically to
 757 <a href="docelement.html#FOOTNOTE">ENDNOTE</a>,
 758 so please read the
 759 <a href="docelement.html#ENDNOTE_NOTE">HYPER IMPORTANT NOTE</a>
 760 found in the document entry for <strong>ENDNOTE</strong>.
 761
 762 <br>
 763
 764 <!---FOOTNOTE_REFS--->
 765
 766 <hr width="33%" align="left">
 767 <a name="FOOTNOTE_REFS"><h3><u>Instruct REF to put references in footnotes</u></h3></a>
 768 <p>
 769
 770 Macro: <strong>FOOTNOTE_REFS</strong>
 771 <p>
 772 <strong>FOOTNOTE_REFS</strong> is an instruction to
 773 <a href="#REF">REF</a>,
 774 saying, "put all subsequent references bracketed by the
 775 <strong>REF</strong> macro into footnotes."  You invoke it by
 776 itself, with no argument.
 777 <p>
 778 When <strong>FOOTNOTE_REFS</strong> is in effect, regular
 779 footnotes, (i.e. those introduced with <kbd>.FOOTNOTE</kbd> and
 780 terminated with <kbd>.FOOTNOTE OFF</kbd>) continue to behave
 781 normally.
 782 <p>
 783 You may switch between <strong>FOOTNOTE_REFS</strong> and
 784 <a href="#ENDNOTE_REFS">ENDNOTE_REFS</a>
 785 at any time.
 786 <p>
 787 If you have a lot of footnote references, and are identifying
 788 footnotes by line number rather than by markers in the text, you may
 789 want to enable
 790 <a href="docelement.html#FOOTNOTES_RUN_ON">FOOTNOTES_RUN_ON</a>
 791 in conjunctions with <strong>FOOTNOTE_REFS</strong>.
 792
 793 <br>
 794
 795 <!---ENDNOTE_REFS--->
 796
 797 <hr width="33%" align="left">
 798 <a name="ENDNOTE_REFS"><h3><u>Instruct REF to put references in endnotes</u></h3></a>
 799 <p>
 800
 801 Macro: <strong>ENDNOTE_REFS</strong>
 802 <p>
 803 <strong>ENDNOTE_REFS</strong> is an instruction to
 804 <a href="#REF">REF</a>,
 805 saying, "add all subsequent references bracketed by the
 806 <strong>REF</strong> macro to endnotes."  You invoke it by
 807 itself, with no argument.
 808 <p>
 809 When <strong>ENDNOTE_REFS</strong> is in effect,
 810 <strong>mom</strong> continues to format regular endnotes, (i.e.
 811 those introduced with <kbd>.ENDNOTE</kbd> and terminated with
 812 <kbd>.ENDNOTE OFF</kbd>) in the normal way.
 813 <p>
 814 You may switch between <strong>ENDNOTE_REFS</strong> and
 815 <a href="#FOOTNOTE_REFS">FOOTNOTE_REFS</a>
 816 at any time.
 817
 818 <br>
 819
 820 <!---BRACKET_REFS--->
 821
 822 <hr width="33%" align="left">
 823 <a name="BRACKET_REFS"><h3><u>References embedded in text</u></h3></a>
 824 <p>
 825
 826 Macro pair: <strong>REF(</strong>&nbsp;&nbsp;...&nbsp;&nbsp;<strong>REF)</strong>
 827 <br>
 828 Macro pair: <strong>REF[</strong>&nbsp;&nbsp;...&nbsp;&nbsp;<strong>REF]</strong>
 829 <br>
 830 Macro pair: <strong>REF{</strong>&nbsp;&nbsp;...&nbsp;&nbsp;<strong>REF}</strong>
 831 <p>
 832 You may sometimes want to embed references directly into the body
 833 of your documents, typically, but not always, inside parentheses.
 834 <strong>Mom</strong> makes this possible through the use of the
 835 <strong>REF&lt;bracket&nbsp;type&gt;</strong> macros.
 836 <p>
 837 All three macro pairs, above, are invoked the same way, namely by
 838 introducing the reference with the first ("open") macro of
 839 the <strong>REF&lt;bracket&nbsp;type&gt;</strong> pair, and
 840 terminating it with the second ("close")
 841 <strong>REF&lt;bracket&nbsp;type&gt;</strong> of the pair.  For
 842 example
 843 <p>
 844 <pre>
 845         .REF(
 846         .[
 847         keyword(s)
 848         .]
 849         .REF)
 850 </pre>
 851
 852 will embed a reference in the body of your document, surrounded by
 853 parentheses.  <strong>.REF[</strong>&nbsp;...&nbsp;<strong>.REF]</strong> will
 854 surround the reference with square brackets.
 855 <strong>.REF{</strong>&nbsp;...&nbsp;<strong>.REF}</strong> will surround it with
 856 curly braces.
 857 <br>
 858
 859 <!---INDENT_REFS--->
 860
 861 <hr width="33%" align="left">
 862 <a name="INDENT_REFS"><h3><u>Manage the second-line indent of references</u></h3></a>
 863 <p>
 864
 865 <nobr>Macro: <strong>INDENT_REFS</strong> FOOTNOTE | ENDNOTE | BIBLIO &lt;indent&gt; </nobr>
 866 <br>
 867 <em>*&lt;indent&gt; requires a <a href="definitions.html#TERMS_UNITOFMEASURE">unit of measure</a></em>
 868 <p>
 869 Proper MLA-style references should have their second, and subsequent
 870 lines, if any, indented.  Since <strong>mom</strong> formats
 871 references in MLA style, she automatically indents second lines.
 872 By default, the indent for the second line of references,
 873 regardless of whether the references appear in footnotes, endnotes,
 874 or bibliographies, is 1.5
 875 <a href="definitions.html#TERMS_EM">ems</a>
 876 for
 877 <a href="docprocessing.html#PRINTSTYLE">PRINSTYLE</a>
 878 <strong>TYPESET</strong>
 879 and 2 ems for
 880 <a href="docprocessing.html#PRINTSTYLE">PRINSTYLE</a>
 881 <strong>TYPEWRITE</strong>.
 882 <p>
 883 If you'd like to change the indent for footnotes, endnotes or
 884 bibliographies, just invoke <strong>INDENT_REFS</strong> with a
 885 first argument telling <strong>mom</strong> for which you want the
 886 indent changed, and a second argument saying what you'd like the
 887 indent to be.  For example, if you want the second-line indent of
 888 references on a bibliography page to be 3
 889 <a href="definitions.html#TERMS_PICAS_POINTS">picas</a>,
 890 <p>
 891 <pre>
 892         .INDENT_REFS BIBLIO 3P
 893 </pre>
 894
 895 is how you'd set it up.
 896 <p>
 897 <strong>Tip:</strong> if you are identifying endnotes by line
 898 number
 899 (<a href="docelement.html#ENDNOTE_MARKER_STYLE">ENDNOTE_MARKER_STYLE</a> <strong>LINE</strong>)
 900 and you have instructed <strong>mom</strong> to put references
 901 bracketed by
 902 <a href="#REF">REF</a>
 903 into endnotes (with
 904 <a href="#ENDNOTE_REFS">ENDNOTE_REFS</a>),
 905 you will probably want to adjust the second-line indent for
 906 references in endnotes, owing to the way <strong>mom</strong>
 907 formats line-numbered endnotes.  Study the output of such
 908 documents to see whether an indent adjustment is required.
 909 <br>
 910
 911 <!---HYPHENATE_REFS--->
 912
 913 <hr width="33%" align="left">
 914 <a name="HYPHENATE_REFS"><h3><u>Enable/disable hyphenation of references</u></h3></a>
 915 <p>
 916
 917 <nobr>Macro: <strong>HYPHENATE_REFS</strong> &lt;toggle&gt;</nobr>
 918 <p>
 919 If you have hyphenation turned on for a document (see <a
 920 href="typesetting.html#HY">HY</a>),
 921 and in most cases you probably do, <strong>mom</strong> will
 922 hyphenate references bracketed by the
 923 <a href="#REF">REF</a>
 924 macro.  Since references typically contain quite a lot of proper
 925 names, which shouldn't be hyphenated, you may want to disable
 926 hyphenation for references.
 927 <p>
 928 <strong>HYPHENATE_REFS</strong> is a toggle macro;
 929 invoking it by itself will turn automatic hyphenation of
 930 <strong>REF</strong>-bracketed references on (the default).
 931 Invoking it with any other argument (<strong>OFF</strong>,
 932 <strong>NO</strong>, <strong>X</strong>, etc.) will disable
 933 automatic hyphenation for references bracketed by
 934 <strong>REF</strong>.
 935 <p>
 936 An alternative to turning reference hyphenation off is to prepend
 937 to selected proper names in your <strong>refer</strong> database
 938 the <strong>groff</strong>
 939 <a href="definitions.html#TERMS_DISCRETIONARYHYPHEN">discretionary hyphen</a>
 940 character, <strong>\%</strong>.  (See
 941 <a href="#REF_DISC_HY">here</a>
 942 in the tutorial for an example.)
 943 <p>
 944 <strong>Note:</strong> references embedded in the body of a document
 945 with
 946 <a href="#BRACKET_REFS">REF</a><strong>&lt;bracket&nbsp;type&gt;</strong>
 947 are considered part of
 948 <a href="definitions.html#TERMS_RUNNING">running text</a>,
 949 and are hyphenated (or not) according to whether hyphenation
 950 is turned on or off for running text.  Therefore, if you want to
 951 disable hyphenation for such references, you must do so
 952 temporarily, with <strong>HY</strong>, like this:
 953 <p>
 954 <pre>
 955         .HY OFF
 956         .REF(
 957         .[
 958         keyword(s)
 959         .]
 960         .REF)
 961         .HY
 962 </pre>
 963
 964 Alternatively, sprinkle your database fields liberally with
 965 <strong>\%</strong>.
 966 <br>
 967
 968 <!---BIBLIOGRAPHY--->
 969
 970 <hr width="33%" align="left">
 971 <a name="BIBLIOGRAPHY"><h3><u>Begin a bibliography page</u></h3></a>
 972 <p>
 973
 974 Macro: <strong>BIBLIOGRAPHY</strong>
 975 <br>
 976 <p>
 977 If you want to append a bibliography to your document, all you need
 978 do is invoke <strong>BIBLIOGRAPHY</strong> at the place you want
 979 it.  <strong>BIBLIOGRAPHY</strong> breaks to a new page, prints the
 980 title (BIBLIOGRAPHY by default, but that can be changed), and awaits
 981 <strong>refer</strong> instructions.  How to create bibliographies
 982 is covered in the tutorial section,
 983 <a href="#BIBLIO_REF">Creating bibliography pages</a>.
 984 <p>
 985 See the
 986 <a href="#BIBLIO_CONTROL">Bibliography page style control macros</a>
 987 for macros to tweak, design and control the appearance of
 988 bibliography pages.
 989 <br>
 990
 991 <!---BIBLIOGRAPHY_TYPE--->
 992
 993 <hr width="33%" align="left">
 994 <a name="BIBLIOGRAPHY_TYPE"><h3><u>Plain, or numbered list bibliography</u></h3></a>
 995 <p>
 996
 997 <nobr>Macro: <strong>BIBLIOGRAPHY_TYPE</strong> PLAIN | LIST [ &lt;list separator&gt; ] [ &lt;list prefix&gt; ]</nobr>
 998 <p>
 999 <strong>Mom</strong> offers two styles of bibliography output: plain,
1000 or numbered list style.  With <strong>PLAIN</strong>, bibliography
1001 entries are output with no enumerators.  With <strong>LIST</strong>,
1002 each entry is numbered.
1003 <p>
1004 Entering <kbd>.BIBLIOGRPHY_TYPE PLAIN</kbd> gives you a plain
1005 bibliography.
1006 <p>
1007 Entering <kbd>.BIBLIOGRAPHY_TYPE LIST</kbd> gives you an enumerated
1008 bibliography.  The two optional arguments,
1009 <strong>&lt;list&nbsp;separator&gt;</strong> and
1010 <strong>&lt;list&nbsp;prefix&gt;</strong> have the same meaning as
1011 the equivalent arguments to
1012 <a href="docelement.html#LIST">LIST</a>
1013 (i.e. <strong>&lt;separator&gt;</strong> and <strong>&lt;prefix&gt;</strong>).
1014 <p>
1015 You may enter <strong>BIBLIOGRAPHY_TYPE</strong> either before or
1016 after <strong>BIBLIOGRAPHY</strong>.  It must, however, always come
1017 before the <strong>refer</strong> command to output bibliographies.
1018 (See the tutorial section,
1019 <a href="#BIBLIO_REF">Creating bibliography pages</a>,
1020 for instructions on how to output bibliographies.)
1021 <p>
1022 <strong>Mom</strong>'s default <strong>BIBLIOGRAPHY_TYPE</strong>
1023 is <strong>LIST</strong>, with a period (dot) as the separator, and
1024 no prefix.
1025
1026 <br>
1027
1028 <!---BIBLIO_CONTROL--->
1029
1030 <hr width="66%" align="left">
1031 <a name="BIBLIO_CONTROL"><h3><u>Bibliography page style control</u></h3></a>
1032
1033 <p>
1034 <strong>Mom</strong> processes bibliography pages in a manner very
1035 similar to the way she processes endnotes pages.  The bibliography
1036 page control macros, therefore, behave in the same way as their
1037 endnotes pages equivalents.
1038 <br>
1039 <ol>
1040         <li><a href="#BIBLIO_GENERAL"><strong>General bibliography page style control</strong></a>
1041                 <ul>
1042                         <li><a href="#BIBLIO_STYLE">Base family/font/quad for bibliographies</a>
1043                         <li><a href="#BIBLIO_PT_SIZE">Base point size for bibliographies</a>
1044                         <li><a href="#BIBLIO_LEAD">Leading of bibliographies</a>
1045                         <li><a href="#SINGLESPACE_BIBLIO">Singlespace bibliographies (for TYPEWRITE only)</a>
1046                         <li><a href="#BIBLIO_NO_COLUMNS">Turning off column mode during bibliography output</a>
1047                         <li>Pagination of bibliographies:
1048                         <ul>
1049                                 <li><a href="#BIBLIO_PAGENUM_STYLE">Bibliography pages page numbering style</a>
1050                                 <li><a href="#BIBLIO_FIRST_PAGENUMBER">Setting the first page number of bibliography pages</a>
1051                                 <li><a href="#BIBLIO_NO_FIRST_PAGENUM">Omitting a page number on the first page of bibliographies</a>
1052                         </ul>
1053                         <li><a href="#SUSPEND_PAGINATION">Suspending pagination of bibliographies</a>
1054                 </ul>
1055         <li><a href="#BIBLIO_HEADER_CONTROL"><strong>Bibliography pages header/footer control</strong></a>
1056                 <ul>
1057                         <li><a href="#BIBLIO_MODIFY_HDRFTR">Modifying what goes in the bibliography pages header/footer</a>
1058                         <li><a href="#BIBLIO_HDRFTR_CENTER">Enabling a header/footer centre when doctype is CHAPTER</a>
1059                         <li><a href="#BIBLIO_ALLOWS_HEADERS">Allow headers on bibliography pages</a>
1060                 </ul>
1061         <li><a href="#BIBLIO_MAIN_TITLE"><strong>Bibliography page head (i.e. the title at the top) control</strong></a>
1062                 <ul>
1063                         <li><a href="#BIBLIO_STRING">Creating/modifying the bibliography page head</a>
1064                         <li><a href="#BIBLIO_STRING_CONTROL">Bibliography page head control</a>
1065                         <li><a href="#BIBLIO_STRING_UNDERSCORE">Bibliography page head underscoring</a>
1066                         <li><a href="#BIBLIO_STRING_CAPS">Bibliography page head capitalization</a>
1067                 </ul>
1068     </ul>
1069 </ol>
1070 <hr>
1071
1072 <a name="BIBLIO_GENERAL"><h2><u>1. General bibliography page style control</u></h2>
1073
1074 <a name="BIBLIO_STYLE"><h3><u>*Bibliography family/font/quad</u></h3></a>
1075 <p>
1076 See
1077 <a href="#CONTROL_MACRO_ARGS">Arguments to the control macros</a>.
1078 <p>
1079 <pre>
1080 .BIBLIOGRAPHY_FAMILY    default = prevailing document family; default is Times Roman
1081 .BIBLIOGRAPHY_FONT      default = roman
1082 .BIBLIOGRAPHY_QUAD*     default = justified
1083
1084 *Note: BIBLIOGRAPHY_QUAD must be set to either L or J
1085 </pre>
1086
1087 <!---BIBLIO_PT_SIZE--->
1088
1089 <a name="BIBLIO_PT_SIZE"><h3><u>*Bibliography point size</u></h3></a>
1090 <p>
1091 <nobr>Macro: <strong>BIBLIOGRAPHY_PT_SIZE</strong> &lt;base type size of bibliography&gt;</nobr>
1092
1093 <p>
1094 Unlike most other control macros that deal with size of document
1095 elements, <strong>BIBLIOGRAPHY_PT_SIZE</strong> takes as its argument an
1096 absolute value, relative to nothing.  Therefore, the argument represents
1097 the size of bibliography type in
1098 <a href="definitions.html#TERMS_PICASPOINTS">points</a>,
1099 unless you append an alternative
1100 <a href="definitions.html#TERMS_UNITOFMEASURE">unit of measure</a>.
1101 For example,
1102 <p>
1103 <pre>
1104         .BIBLIOGRAPHY_PT_SIZE 12
1105 </pre>
1106
1107 sets the base point size of type on the bibliography page to 12
1108 points, whereas
1109 <p>
1110 <pre>
1111         .BIBLIOGRAPHY_PT_SIZE .6i
1112 </pre>
1113
1114 sets the base point size of type on the bibliography page to 1/6 of an
1115 inch.
1116 <p>
1117 The type size set with <strong>BIBLIOGRAPHY_PT_SIZE</strong> is the size of
1118 type used for the text of the bibliographies, and forms the basis from which
1119 the point size of other bibliography page elements is calculated.
1120 <p>
1121 The default for
1122 <a href="docprocessing.html#PRINTSTYLE">PRINTSTYLE TYPESET</a>
1123 is 12.5 points (the same default size used in the body of the document).
1124 <p>
1125
1126 <!---BIBLIO_LEAD--->
1127
1128 <a name="BIBLIO_LEAD"><h3><u>*Bibliography lead</u></h3></a>
1129 <p>
1130 <nobr>Macro: <strong>BIBLIOGRAPHY_LEAD</strong> &lt;base leading of bibliographies&gt; [ ADJUST ]</nobr>
1131 <br>
1132 <em>*Does not require a <a href="definitions.html#TERMS_UNITOFMEASURE">unit of measure</a>; points is assumed</em>
1133
1134 <p>
1135 Unlike most other control macros that deal with leading of document
1136 elements, <strong>BIBLIOGRAPHY_LEAD</strong> takes as its argument an
1137 absolute value, relative to nothing.  Therefore, the argument represents
1138 the
1139 <a href="definitions.html#TERMS_LEADING">leading</a>
1140 of endnotes in
1141 <a href="definitions.html#TERMS_PICASPOINTS">points</a>
1142 unless you append an alternative
1143 <a href="definitions.html#TERMS_UNITOFMEASURE">unit of measure</a>.
1144 For example,
1145 <p>
1146 <pre>
1147         .BIBLIOGRAPHY_LEAD 14
1148 </pre>
1149
1150 sets the base leading of type on the bibliography page to 14
1151 points, whereas
1152 <p>
1153 <pre>
1154         .BIBLIOGRAPHY_LEAD .5i
1155 </pre>
1156
1157 sets the base leading of type on the bibliography page to 1/2 inch.
1158 <p>
1159 If you want the leading of bibliographies adjusted to fill the page,
1160 pass <strong>BIBLIOGRAPHY_LEAD</strong> the optional argument
1161 <strong>ADJUST</strong>.  (See
1162 <a href="docprocessing.html#DOC_LEAD_ADJUST">DOC_LEAD_ADJUST</a>
1163 for an explanation of leading adjustment.)
1164 <p>
1165 The default for
1166 <a href="docprocessing.html#PRINTSTYLE">PRINTSTYLE TYPESET</a>
1167 is 14 points, adjusted.
1168 <p>
1169 <strong>NOTE:</strong> Even if you give <strong>mom</strong> a
1170 <strong>DOC_LEAD_ADJUST OFF</strong> command, she will still, by
1171 default, adjust bibliography leading.  You MUST enter
1172 <strong>BIBLIOGRAPHY_LEAD &lt;lead&gt;</strong> with no
1173 <strong>ADJUST</strong> argument to disable this default behaviour.
1174 <p>
1175
1176 <!---SINGLESPACE_BIBLIO--->
1177
1178 <a name="SINGLESPACE_BIBLIO"><h3><u>*Singlespace bibliographies (TYPEWRITE only)</u></h3></a>
1179 <p>
1180 <nobr>Macro: <strong>SINGLESPACE_BIBLIOGRAPHY</strong> &lt;toggle&gt;</nobr>
1181
1182 <p>
1183 If your
1184 <a href="docprocessing.html#PRINTSTYLE">PRINTSTYLE</a>
1185 is <strong>TYPEWRITE</strong> and you use TYPEWRITE's default
1186 double-spacing, bibliographies are double-spaced.  If your document
1187 is single-spaced, bibliographies are single-spaced.
1188 <p>
1189 If, for some reason, you'd prefer that bibliographies be single-spaced
1190 in an otherwise double-spaced document (including double-spaced
1191 <a href="rectoverso.html#COLLATE">collated</a>
1192 documents), invoke <strong>SINGLESPACE_BIBLIOGRAPHY</strong> with
1193 with no argument.
1194 <p>
1195
1196 <!---BIBLIO_SPACING--->
1197
1198 <a name="BIBLIO_SPACING"><h3><u>*Adjusting the space between bibliography entries</u></h3></a>
1199 <p>
1200 <nobr>Macro: <strong>BIBLIOGRAPHY_SPACING</strong> &lt;amount of space&gt; </nobr>
1201 <br>
1202 <em>*Requires a <a href="definitions.html#TERMS_UNITOFMEASURE">unit of measure</a></em>
1203
1204 <p>
1205 By default, <strong>mom</strong> inserts 1 linespaces between
1206 bibliography entries on bibliography pages.  If you'd prefer she
1207 add a different amount of space, instruct her to do so with the
1208 macro, <strong>BIBLIOGRAPHY_SPACING</strong>.  Say, for example,
1209 you'd prefer only 1/2 linespace.  That would be done with
1210 <p>
1211 <pre>
1212         .BIBLIOGRAPHY_SPACING .5v
1213 </pre>
1214
1215 As with endnotes pages, owing to the space inserted between bibliography
1216 entries, bibliography pages may have hanging bottom margins.
1217 Unlike endnotes pages, <strong>mom</strong> is sad to report that
1218 there's nothing you can do about this, except a) pray things work
1219 out, or b) set your <strong>BIBLIOGRAPHY_SPACING</strong> to zero.
1220
1221 <!---BIBLIO_NO_COLUMNS--->
1222
1223 <a name="BIBLIO_NO_COLUMNS"><h3><u>*Turning off column mode during bibliography output</u></h3></a>
1224 <p>
1225 <nobr>Macro: <strong>BIBLIOGRAPHY_NO_COLUMNS</strong> &lt;toggle&gt;</nobr>
1226
1227 <p>
1228 By default, if your document is
1229 <a href="columns.html#COLUMNS">set in columns</a>,
1230 <strong>mom</strong> sets the bibliographies in columns, too.  However,
1231 if your document is set in columns and you'd like the bibliographies not
1232 to be, just invoke <strong>BIBLIOGRAPHY_NO_COLUMNS</strong> with no
1233 argument.  The bibliography pages will be set to the full page measure
1234 of your document.
1235 <p>
1236 If you output bibliographies at the end of each document in a
1237 <a href="rectoverso.html#COLLATE">collated</a>
1238 document set in columns, column mode will automatically
1239 be reinstated for each document, even with
1240 <strong>BIBLIOGRAPHY_NO_COLUMNS</strong> turned on.
1241 <p>
1242
1243 <!---BIBLIO_PAGENUM_STYLE--->
1244
1245 <a name="BIBLIO_PAGENUM_STYLE"><h3><u>*Bibliography-page page numbering style</u></h3></a>
1246 <p>
1247 <nobr>Macro: <strong>BIBLIOGRAPHY_PAGENUM_STYLE</strong> DIGIT | ROMAN | roman | ALPHA | alpha</nobr>
1248
1249 <p>
1250 Use this macro to set the page numbering style of bibliography pages.
1251 The arguments are identical to those for
1252 <a href="headfootpage.html#PAGENUM_STYLE">PAGENUM_STYLE</a>.
1253 The default is <strong>digit</strong>.  You may want to change it
1254 to, say, <strong>alpha</strong>, which you would do with
1255 <p>
1256 <pre>
1257         .BIBLIOGRAPHY_PAGENUM_STYLE alpha
1258 </pre>
1259
1260 <!---BIBLIO_FIRST_PAGENUMBER--->
1261
1262 <a name="BIBLIO_FIRST_PAGENUMBER"><h3><u>*Setting the first page number of bibliography pages</u></h3></a>
1263 <p>
1264 <nobr>Macro: <strong>BIBILOGRAPHY_FIRST_PAGENUMBER</strong> &lt;page # that appears on page 1 of bibliographies&gt;</nobr>
1265
1266 <p>
1267 Use this macro with caution.  If all bibliographies for several
1268 <a href="rectoverso.html#COLLATE">collated</a>
1269 documents are to be output at once, i.e. not at the end of each
1270 separate doc, <strong>BIBLIOGRAPHY_FIRST_PAGENUMBER</strong> tells
1271 <strong>mom</strong> what page number to put on the first page of
1272 the bibliography.
1273 <p>
1274 If you set <strong>BIBLIOGRAPHY_FIRST_PAGENUMBER</strong> in collated
1275 documents where the bibliographies are output after each separate doc,
1276 you have to reset every separate document's first page number after
1277 <a href="rectoverso.html#COLLATE">COLLATE</a>
1278 and before
1279 <a href="docprocessing.html#START">START</a>.
1280 <p>
1281
1282 <!---BIBLIO_NO_FIRST_PAGENUN--->
1283
1284 <a name="BIBLIO_NO_FIRST_PAGENUM"><h3><u>*Omitting a page number on the first page of bibliographies</u></h3></a>
1285 <p>
1286 <nobr>Macro: <strong>BIBLIOGRAPHY_NO_FIRST_PAGENUM</strong> &lt;toggle&gt;</nobr>
1287
1288 <p>
1289 This macro is for use only if <strong>FOOTERS</strong> are on.  It
1290 tells
1291 <a href="#BIBLIOGRAPHY">BIBLIOGRAPHY</a>
1292 not to print a page number on the first bibliography page.
1293 <strong>Mom</strong>'s default is to print the page number.
1294 <p>
1295
1296 <!---SUSPEND_PAGINATION--->
1297
1298 <a name="SUSPEND_PAGINATION"><h3><u>*Suspending pagination of bibliography pages</u></h3></a>
1299 <p>
1300 Macro: <strong>SUSPEND_PAGINATION</strong>
1301 <br>
1302 Macro: <strong>RESTORE_PAGINATION</strong>
1303
1304 <p>
1305 <strong>SUSPEND_PAGINATION</strong> doesn't take an argument.
1306 Invoked immediately prior to
1307 <a href="#BIBLIOGRAPHY">BIBLIOGRAPHY</a>,
1308 it turns off pagination for the duration of the bibliography.
1309 <strong>Mom</strong> continues, however to increment page numbers
1310 silently.
1311 <p>
1312 To restore normal document pagination after bibliographies, invoke
1313 <strong>RESTORE_PAGINATION</strong> (again, with no argument)
1314 immediately after you've finished with your bibliography.
1315
1316 <a name="BIBLIO_HEADER_CONTROL"><h2><u>2. Bibliography page header/footer control</u></h2></a>
1317 <p>
1318 <a name="BIBLIO_MODIFY_HDRFTR"></a>
1319 If you wish to modify what appears in the header/footer that appears
1320 on bibliography pages, make the changes before you invoke
1321 <a href="#BIBLIOGRAPHY">BIBLIOGRAPHY</a>,
1322 not afterwards.
1323 <p>
1324 Except in the case of
1325 <a href="docprocessing.html#DOCTYPE">DOCTYPE CHAPTER</a>,
1326 <strong>mom</strong> prints the same header or footer used throughout
1327 the document on bibliography pages.  Chapters get treated differently
1328 in that, by default, <strong>mom</strong> does not print the
1329 header/footer centre string (normally the chapter number or chapter
1330 title.)  In most cases, this is what you want.  However, should you
1331 <em>not</em> want <strong>mom</strong> to remove the centre string from
1332 the bibliography pages headers/footers, invoke
1333 <a href="#BIBLIOGRAPHY_HDRFTR_CENTER">BIBLIOGRAPHY_HEADER_CENTER</a>
1334 with no argument.
1335 <p>
1336 An important change you may want to make is to put the word
1337 &quot;Bibliography&quot; in the header/footer centre position.
1338 To do so, do
1339 <p>
1340 <pre>
1341         .HEADER_CENTER "Bibliography"
1342                    or
1343         .FOOTER_CENTER "Bibliography"
1344 </pre>
1345
1346 prior to invoking <strong>.BIBLIOGRAPHY</strong>.  If your
1347 <a href="docprocessing.html#DOCTYPE">DOCTYPE</a>
1348 is <kbd>CHAPTER</kbd>, you must also invoke
1349 <a href="#BIBLIOGRAPHY_HDRFTR_CENTER">BIBLIOGRAPHY_HEADER_CENTER</a>
1350 for the <strong>HEADER_CENTER</strong> to appear.
1351 <p>
1352
1353 <a name="BIBLIO_HDRFTR_CENTER"><h3><u>*Bibliography page header/footer centre string</u></h3></a>
1354 <p>
1355 <nobr>Macro: <strong>BIBLIOGRAPHY_HEADER_CENTER</strong> toggle</nobr>
1356
1357 <p>
1358 If your
1359 <a href="docprocessing.html#DOCTYPE">DOCTYPE</a>
1360 is <kbd>CHAPTER</kbd> and you want <strong>mom</strong> to include
1361 a centre string in the headers/footers that appear on bibliography pages,
1362 invoke <strong>BIBLIOGRAPHY_HEADER_CENTER</strong> (or
1363 <strong>BIBLIOGRAPHY_FOOTER_CENTER</strong>) with no argument.
1364 <strong>Mom</strong>'s default is NOT to print the centre string.
1365 <p>
1366 If, for some reason, having enabled the header/footer centre string
1367 on bibliography pages, you wish to disable it, invoke the same macro
1368 with any argument (<strong>OFF, QUIT, Q, X</strong>...).
1369 <p>
1370
1371 <a name="BIBLIO_ALLOWS_HEADERS"><h3><u>*Allow headers on bibliography pages</u></h3></a>
1372 <p>
1373 <nobr>Macro: <strong>BIBLIOGRAPHY_ALLOWS_HEADERS</strong> &lt;none&gt; | ALL</nobr>
1374
1375 <p>
1376 By default, if <strong>HEADERS</strong> are on, <strong>mom</strong>
1377 prints page headers on all bibliography pages except the first.  If you
1378 don't want her to print headers on bibliography pages, do
1379 <p>
1380 <pre>
1381         .BIBLIOGRAPHY_ALLOWS_HEADERS OFF
1382 </pre>
1383
1384 If you want headers on every page <em>including the first</em>, do
1385 <p>
1386 <pre>
1387         .BIBLIOGRAPHY_ALLOWS_HEADERS ALL
1388 </pre>
1389
1390 <strong>NOTE:</strong> If <strong>FOOTERS</strong> are on,
1391 <strong>mom</strong> prints footers on every bibliography page.  This is
1392 a style convention.  In <strong>mom</strong>, there is no such beast
1393 as <strong>BIBLIOGRAPHY_ALLOWS_FOOTERS OFF</strong>.
1394 <p>
1395
1396 <a name="BIBLIO_MAIN_TITLE"><h2><u>3. Bibliography page first page head (title) control</u></h2>
1397
1398 <!---BIBLIO_STRING--->
1399
1400 <a name="BIBLIO_STRING"><h3><u>*Bibliography pages first page head (title) string</u></h3></a>
1401 <p>
1402 <nobr>Macro: <strong>BIBLIOGRAPHY_STRING</strong> &quot;&lt;head to print at the top of bibliography pages&gt;&quot;</nobr>
1403
1404 <p>
1405 By default, <strong>mom</strong> prints the word &quot;BIBLIOGRAPHY&quot;
1406 as a head at the top of the first page of a bibliography.  If you want her
1407 to print something else, invoke <strong>BIBLIOGRAPHY_STRING</strong> with
1408 the bibliography page head you want, surrounded by double-quotes.  If
1409 you don't want a head at the top of the first bibliography page, invoke
1410 <strong>BIBLIOGRAPHY_STRING</strong> with a blank argument (either two
1411 double-quotes side by side -- <kbd>&quot;&quot;</kbd> -- or no argument
1412 at all).
1413 <p>
1414
1415 <!---BIBLIO_STRING_CONTROL--->
1416
1417 <a name="BIBLIO_STRING_CONTROL"><h3><u>*Bibliography page first page head (title) control</u></h3></a>
1418 <p>
1419 See
1420 <a href="#CONTROL_MACRO_ARGS">Arguments to the control macros</a>.
1421 <p>
1422 <pre>
1423 .BIBLIOGRAPHY_STRING_FAMILY    default = prevailing document family; default is Times Roman
1424 .BIBLIOGRAPHY_STRING_FONT      default = bold
1425 .BIBLIOGRAPHY_STRING_SIZE*     default = +1
1426 .BIBLIOGRAPHY_STRING_QUAD      default = centred
1427
1428 *Relative to the size of the bibliography text (set with BIBLIOGRAPHY_PT_SIZE)
1429 </pre>
1430
1431 <!---BIBLIO_STRING_UNDERSCORE--->
1432
1433 <a name="BIBLIO_STRING_UNDERSCORE"><h3><u>*Bibliography-page head (title) underscoring</h3></u></a>
1434 <p>
1435 <nobr>Macro: <strong>BIBLIOGRAPHY_STRING_UNDERSCORE</strong> toggle | 2</nobr>
1436
1437 <p>
1438 Invoked by itself, <strong>BIBLIOGRAPHY_STRING_UNDERSCORE</strong> will
1439 underscore the bibliography page head.  Invoked with the argument 2
1440 (i.e. the digit 2), <strong>BIBLIOGRAPHY_STRING_UNDERSCORE</strong> will
1441 double-underscore the head.  Invoked with any other argument, the macro
1442 disables underscoring of the head.
1443 <p>
1444 <strong>Mom</strong>'s default is to double-underscore the
1445 head, therefore if you want no underscoring, you must insert
1446 <kbd>.BIBLIOGRAPHY_STRING_UNDERSCORE OFF</kbd> (or <kbd>QUIT, X, NO,
1447 NONE,</kbd> etc.) into your document prior to outputting a
1448 bibliography with
1449 <a href="#BIBLIOGRAPHY">BIBLIOGRAPHY</a>.
1450
1451 <!---BIBLIO_STRING_CAPS--->
1452
1453 <a name="BIBLIO_STRING_CAPS"><h3><u>*Bibliography-page head (title) automatic capitalization</h3></u></a>
1454 <p>
1455 <nobr>Macro: <strong>BIBLIOGRAPHY_STRING_CAPS</strong> toggle</nobr>
1456
1457 <p>
1458 Invoked by itself, <strong>BIBLIOGRAPHY_STRING_CAPS</strong> will
1459 automatically capitalize the bibliography page head.  Invoked with any
1460 other argument, the macro disables automatic capitalization of the
1461 head.
1462 <p>
1463 If you're generating a table of contents, you may want the
1464 bibliography page head string in caps, but the toc entry in caps/lower
1465 case.  If the argument to
1466 <a href="#BIBLIOGRAPHY_STRING">BIBLIOGRAPHY_STRING</a>
1467 is in caps/lower case and <strong>BIBLIOGRAPHY_STRING_CAPS</strong> is
1468 on, this is exactly what will happen.
1469 <p>
1470 <strong>Mom</strong>'s default is to capitalize the bibliography-page
1471 head string.
1472 <p>
1473
1474 <br>
1475
1476 <hr>
1477 <a href="letter.html#TOP">Next</a>&nbsp;&nbsp;
1478 <a href="cover.html#TOP">Prev</a>&nbsp;&nbsp;
1479 <a href="#TOP">Top</a>&nbsp;&nbsp;
1480 <a href="toc.html">Back to Table of Contents</a>
1481 </body>
1482 </html>