contrib/mom/momdoc/refer.html

   1 <?xml version="1.0" encoding="utf-8"?>
   2 <!--
   3 This file is part of groff, the GNU roff type-setting system.
   4
   5 Copyright (C) 2004-2014 Free Software Foundation, Inc.
   6 Written by Peter Schaffter (peter@schaffter.ca).
   7
   8 Permission is granted to copy, distribute and/or modify this document
   9 under the terms of the GNU Free Documentation License, Version 1.3 or
  10 any later version published by the Free Software Foundation; with the
  11 Invariant Sections being this comment section, with no Front-Cover
  12 Texts, and with no Back-Cover Texts.
  13
  14 A copy of the Free Documentation License is included as a file called
  15 FDL in the main directory of the groff source package.
  16 -->
  17
  18 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
  19 <html xmlns="http://www.w3.org/1999/xhtml">
  20
  21 <head>
  22   <meta http-equiv="content-type" content="text/html;charset=utf-8"/>
  23   <title>Mom -- Document processing, bibliographies and references</title>
  24   <link rel="stylesheet" type="text/css" href="stylesheet.css" />
  25 </head>
  26
  27 <body style="background-color: #f5faff;">
  28
  29 <!-- ==================================================================== -->
  30
  31 <div id="top" class="page">
  32
  33 <!-- Navigation links -->
  34 <table style="width: 100%;">
  35 <tr>
  36   <td><a href="toc.html">Back to Table of Contents</a></td>
  37   <td style="text-align: right;"><a href="letters.html#top">Next: Writing letters</a></td>
  38 </tr>
  39 </table>
  40
  41 <h1 class="docs">Bibliographies and references</h1>
  42
  43 <div style="width: 75%; margin: auto;">
  44 <ul class="no-enumerator">
  45   <li><a href="#intro-ref">Introduction to bibliographies and references</a></li>
  46   <li><a href="#tutorial-ref">Tutorial on <kbd>refer</kbd> usage with mom</a>
  47   <ul style="margin-left: -.5em; list-style-type: disc;">
  48     <li><a href="#db-ref">Create a <kbd>refer</kbd> database</a></li>
  49     <li><a href="#rcommands-ref">Insert a <kbd>refer</kbd> block</a></li>
  50     <li><a href="#placement-ref">Tell mom where you want your references (if footnotes or endnotes)</a></li>
  51     <li><a href="#accessing-ref">Accessing references in the database</a></li>
  52     <li><a href="#fn-en-recipe">Entering footnote/endnote references</a></li>
  53     <li><a href="#parenthetical">Parenthetical insertions</a></li>
  54     <li><a href="#bibliography-from-embedded">Generating a bibliography from parenthetical insertions</h4></a></li>
  55     <li><a href="#bibliography-recipe">Generating a comprehensive bibliography</a></li>
  56     <li><a href="#invoking-ref">Invoking groff with mom and <kbd>refer</kbd></a></li>
  57   </ul></li>
  58   <li><a href="#mla">MLA (Modern Language Association) style</a>
  59   <ul style="margin-left: -.5em; list-style-type: disc;">
  60     <li><a href="#ref-styles">Types of references (endnote, footnote, or embedded in text)</a></li>
  61     <li><a href="#parenthetical">Inserting parenthetical references into the text</a></li>
  62   </ul></li>
  63   <li><a href="#database">The <kbd>refer</kbd> database</a>
  64   <ul style="margin-left: -.5em; list-style-type: disc;">
  65     <li><a href="#database-intro">Introduction</a></li>
  66     <li><a href="#database-rules">Rules</a></li>
  67     <li><a href="#fields-quick">Quick guide to field identifiers (%A for author, %T for title, etc)</a></li>
  68     <li><a href="#fields-specifics">Field identifiers: specifics, usage and examples</a>
  69     <ul style="margin-left: -.5em; list-style-type: square;">
  70       <li><a href="#ibid">avoiding ibid, idem and their ilk</a></li>
  71     </ul></li>
  72   </ul></li>
  73   <li><a href="#index-ref">The bibliography and reference macros</a>
  74   <ul style="margin-left: -.5em; list-style-type: disc;">
  75     <li><a href="#biblio-control">Bibliography control macros and defaults</a></li>
  76   </ul></li>
  77 </ul>
  78 </div>
  79
  80 <div class="rule-medium"><hr/></div>
  81
  82 <h2 id="intro-ref" class="docs">Introduction to bibliographies and references</h2>
  83
  84 <p>
  85 Mom provides the ability to format and generate bibliographies, as
  86 well as footnote or endnote references, in MLA (Modern Language
  87 Association) style.  She accomplishes this by working in conjunction
  88 with a special groff program called <kbd>refer</kbd>.
  89 </p>
  90
  91 <p>
  92 <kbd>Refer</kbd> requires first that you create a database of works
  93 that will be cited in your documents.  Once that&#8217;s done, special
  94 macros let you briefly key in references to entries in the database
  95 and have mom format them with respect to order, punctuation and
  96 italicization in footnotes, endnotes, or a full bibliography.
  97 </p>
  98
  99 <p>
 100 <kbd>Refer</kbd> has been around for a long time.  It&#8217;s
 101 powerful and has many, many features.  Unfortunately, the manpage
 102 (<kbd>man&nbsp;refer</kbd>), while complete and accurate, is
 103 dense and not a good introduction.  (It&#8217;s a classic manpage
 104 Catch-22: the manpage is useful only after you know how to use the
 105 program.)
 106 </p>
 107
 108 <p>
 109 In order to get mom users up and running with <kbd>refer</kbd>,
 110 this section of mom&#8217;s documentation focuses exclusively, in a
 111 recipe-like manner, on what you need to know to use <kbd>refer</kbd>
 112 satisfactorily in conjunction with mom.  The instructions are not to
 113 be taken as a manual on full <kbd>refer</kbd> usage.
 114 </p>
 115
 116 <p>
 117 If you&#8217;re already a <kbd>refer</kbd> user, the information
 118 herein will be useful for adapting your current <kbd>refer</kbd>
 119 usage to mom&#8217;s way of doing things.  If you&#8217;ve never
 120 used <kbd>refer</kbd>, the information is essential, and, in many
 121 cases, may be all you need.
 122 </p>
 123
 124 <p>
 125 I encourage anyone interested in what MLA style looks
 126 like&mdash;and, by extension, how your bibliographies and references
 127 will look after mom formats them&mdash;to check out
 128 <br/>
 129 <span class="pre-in-pp">
 130   <a href="http://www.aresearchguide.com/12biblio.html">http://www.aresearchguide.com/12biblio.html</a>
 131 </span>
 132 or any other website or reference book on MLA style.
 133 </p>
 134
 135 <div class="rule-short" style="margin-top: 1em;"><hr/></div>
 136
 137 <div class="examples-container" style="margin-top: 1.5em; margin-bottom: 1.5em;">
 138 <h3 id="tutorial-ref" class="docs">Tutorial on refer usage with mom</h3>
 139 <ol style="margin-top: 1em; margin-bottom: -.5em;">
 140   <li><a href="#db-ref">Create a <kbd>refer</kbd> database</a>
 141   <ul style="margin-left: -.5em; list-style-type: disc;">
 142     <li><a href="#example-refer-database">example <kbd>refer</kbd> database</a></li>
 143   </ul></li>
 144   <li><a href="#rcommands-ref">Insert a <kbd>refer</kbd> block</a>
 145   <ul style="margin-left: -.5em; list-style-type: disc;">
 146     <li><a href="#fn-en-block">refer block for footnotes/endnotes</a></li>
 147     <li><a href="#in-text-block">refer block for parenthetical insertions into running text</a></li>
 148     <li><a href="#bibliography-block">refer block for comprehensive bibliographies (reading lists)</a></li>
 149   </ul></li>
 150   <li><a href="#placement-ref">Tell mom where you want your references (if footnotes or endnotes)</a></li>
 151   <li><a href="#accessing-ref">Accessing references in the database</a></li>
 152   <li><a href="#fn-en-recipe">Entering footnote/endnote references</a></li>
 153   <li><a href="#parenthetical-insertions">Parenthetical insertions</a></li>
 154   <li><a href="#bibliography-from-embedded">Generating a bibliography from parenthetical insertions</a></li>
 155   <li><a href="#bibliography-recipe">Generating a comprehensive bibliography</a></li>
 156   <li><a href="#invoking-ref">Invoking groff with mom and <kbd>refer</kbd></a></li>
 157 </ol>
 158
 159 <h4 id="db-ref" class="docs">1. Create a refer database</h4>
 160
 161 <p>
 162 The first step in using <kbd>refer</kbd> with mom is creating a
 163 database.  The database is a text file containing entries for the
 164 works you will be citing.  You may set up separate databases for
 165 individual documents, or create a large database that can be
 166 accessed by many documents.
 167 </p>
 168
 169 <p>
 170 Entries (&#8220;records&#8221; in refer-speak) in the database
 171 are separated from each other by a single, blank line.  The records
 172 themselves are composed of single lines (&#8220;fields&#8221;) with
 173 no blank lines between them.  Each field begins with a percent
 174 sign and a single letter (the &quot;field identifier&quot;)
 175 eg <kbd>%A</kbd> or <kbd>%T</kbd>.  The letter identifies
 176 what part of a bibliographic entry the field refers to: Author,
 177 Title, Publisher, Date, etc.  After the field identifier comes
 178 a single space, followed by the information appropriate to
 179 field.
 180 </p>
 181
 182 <!-- Add rules for punctuation and italics -->
 183
 184 <p>
 185 Here&#8217;s an example database containing two records so you can
 186 visualize what the above paragraph says.
 187 </p>
 188
 189 <div id="example-refer-database" class="examples" style="margin-top: -.5em;">Example <kbd>refer</kbd> database</div>
 190 <div class="examples-container" style="padding-bottom: 1em;">
 191 <span class="pre">
 192 %A Terry Pratchett
 193 %A Neil Gaiman
 194 %T Good Omens
 195 %C London
 196 %I Gollancz
 197 %D 1990
 198
 199 %A Peter Schaffter
 200 %T The Schumann Proof
 201 %C Toronto
 202 %I RendezVous Press
 203 %D 2004
 204 </span>
 205 </div>
 206
 207 <p>
 208 The order in which you enter fields doesn&#8217;t matter.
 209 <kbd>Refer</kbd> will re-arrange them for you.
 210 </p>
 211
 212 <h4 id="rcommands-ref" class="docs">2. Insert a refer block</h4>
 213
 214 <p>
 215 Having set up your database, you now need to put some
 216 <kbd>refer</kbd>-specific commands in your mom file.
 217 </p>
 218
 219 <p>
 220 <kbd>Refer</kbd> commands are introduced by a single line
 221 containing <kbd>.R1</kbd>, and concluded with a single line
 222 containing <kbd>.R2</kbd>.  What goes between the <kbd>.R1</kbd>
 223 and <kbd>.R2</kbd> lines is called a &#8220;refer block&#8221;.
 224 <kbd>Refer</kbd> commands in a refer block should be entered one per
 225 line, in lowercase letters, <i>with no initial period</i> (dot).
 226 The actual commands depend on whether you want your references
 227 </p>
 228 <ul>
 229 <li>in footnotes/endnotes</li>
 230 <li>parenthetically inserted (in abbreviated form) into running text,
 231 referring to a works-cited list (bibliography)</li>
 232 <li>to generate a comprehensive bibliography (a reading list)</li>
 233 </ul>
 234
 235 <h5 id="fn-en-block" class="docs" style="font-size: 90%; margin-top: .25em;">Refer block for footnotes/endnotes</h5>
 236
 237 <p style="margin-top: .5em;">
 238 If you want footnote or endnote references, place this block at
 239 the <i>top</i> of your mom file.
 240 </p>
 241
 242 <div id="refer-block1" class="examples" style="margin-top: -.5em;">
 243 <div class="examples-container" style="padding-bottom: 1em;">
 244 <span class="pre">
 245 .R1
 246 no-label-in-text
 247 no-label-in-reference
 248 join-authors " and " ", " ", and "
 249 database &lt;full path to database&gt;
 250 .R2
 251 </span>
 252 </div>
 253 </div>
 254 <p style="margin-top: .5em; font-size: 95%; line-height: 120%;">
 255 <kbd>&lt;full&nbsp;path&nbsp;to&nbsp;the&nbsp;database&gt;</kbd>
 256 means the full path including the filename, eg
 257 <kbd>/home/user/refer/my-database-file</kbd>.
 258 </p>
 259
 260 <h5 id="in-text-block" class="docs" style="font-size: 90%; margin-top: .25em;">Refer block for parenthetical insertions into running text</h5>
 261
 262 <p style="margin-top: .5em;">
 263 If you want short, parenthetical insertions into running text,
 264 referring to works cited in a bibliography, place this block at
 265 the <i>top</i> of your mom file.
 266 </p>
 267
 268 <div id="refer-block2" class="examples" style="margin-top: -.5em;">
 269 <div class="examples-container" style="padding-bottom: 1em;">
 270 <span class="pre">
 271 .R1
 272 label "(A.n|Q)"
 273 bracket-label " (" ")" ", "
 274 join-authors ", and " ", " ", and "
 275 move-punctuation
 276 reverse A1
 277 sort A1Q1T1B1E1
 278 database &lt;full path to database&gt;
 279 .R2
 280 </span>
 281 </div>
 282 </div>
 283 <p style="margin-top: .5em; font-size: 95%; line-height: 120%;">
 284 <kbd>&lt;full&nbsp;path&nbsp;to&nbsp;the&nbsp;database&gt;</kbd>
 285 means the full path including the filename, eg
 286 <kbd>/home/user/refer/my-database-file</kbd>.
 287 </p>
 288
 289 <h5 id="bibliography-block" class="docs" style="font-size: 90%; margin-top: .25em;">Refer block for comprehensive bibliographies</h5>
 290
 291 <p style="margin-top: .5em;">
 292 If you want to output an entire <kbd>refer</kbd> database, or
 293 generate a comprehensive bibliography (a reading list) from a
 294 database, place this block at the <i>bottom</i> of your mom file,
 295 either prior to or immediately after invoking
 296 <a href="#bibliography">BIBLIOGRAPHY</a>.
 297 </p>
 298
 299 <div id="refer-block2" class="examples" style="margin-top: -.5em;">
 300 <div class="examples-container" style="padding-bottom: 1em;">
 301 <span class="pre">
 302 .R1
 303 no-label-in-text
 304 no-label-in-reference
 305 join-authors ", and " ", " ", and "
 306 sort A1Q1T1B1E1
 307 reverse A1
 308 database &lt;full path to database&gt;
 309 .R2
 310 </span>
 311 </div>
 312 </div>
 313
 314 <p style="margin-top: .5em; font-size: 95%; line-height: 120%;">
 315 <kbd>&lt;full&nbsp;path&nbsp;to&nbsp;the&nbsp;database&gt;</kbd>
 316 means the full path including the filename, eg
 317 <kbd>/home/user/refer/my-database</kbd>.
 318 </p>
 319
 320 <h4 id="placement-ref" class="docs">3. Tell mom where you want your references</h4>
 321
 322 <p>
 323 If you want references in footnotes, issue the instruction
 324 <br/>
 325 <span class="pre-in-pp">
 326   .FOOTNOTE_REFS
 327 </span>
 328 anywhere before the first citation in your file.  Footnote markers
 329 will be inserted into the text, and the bibliographic information
 330 for the citation will appear as a footnote.
 331 </p>
 332
 333 <p>
 334 If you want references in endnotes, issue the instruction
 335 <br/>
 336 <span class="pre-in-pp">
 337   .ENDNOTE_REFS
 338 </span>
 339 anywhere before the first citation in your file.  Endnote markers
 340 will be inserted into the text, and the bibliographic information
 341 for the citation will appear as an endnote entry.
 342 </p>
 343
 344 <p>
 345 Note that if you want references parenthetically inserted
 346 into running text, referring to entries in a works-cited list
 347 (bibliography) that <kbd>mom</kbd> and <kbd>refer</kbd> assemble
 348 automatically, no special instructions are required.  See
 349 <a href="#bibliography-from-embedded">Generating a bibliography from parenthetical insertions</a>
 350 for how to output the collected references.
 351 </p>
 352
 353 <p>
 354 For outputting an entire <kbd>refer</kbd> database, or
 355 generating a comprehensive reading list from a database, see the
 356 macro,
 357 <a href="#bibliography">BIBLIOGRAPHY</a>.
 358 </p>
 359
 360 <h4 id="accessing-ref" class="docs">4. Accessing references in the database</h4>
 361
 362 <p>
 363 References are accessed by putting keywords from the desired database
 364 record between two special <kbd>refer</kbd> commands:
 365 <br/>
 366 <span class="pre-in-pp">
 367   .[
 368 </span>
 369 and
 370 <br/>
 371 <span class="pre-in-pp">
 372   .]
 373 </span>
 374 Keywords are any word, or set of words, that identify a database
 375 record unambiguously.  Thus, if you have only one database record for
 376 the author Ray Bradbury,
 377 <br/>
 378 <span class="pre-in-pp">
 379   .[
 380   bradbury
 381   .]
 382 </span>
 383 is sufficient.  However, if your database contains several records
 384 for books by Bradbury, say, <i>Fahrenheit 451</i> and <i>The
 385 Martian Chronicles</i>,
 386 &#8220;<kbd>bradbury&nbsp;451</kbd>&#8221; and
 387 &#8220;<kbd>bradbury&nbsp;martian</kbd>&#8221; would identify the two records unambiguously.
 388 </p>
 389
 390 <p>
 391 A special database field identifier, <kbd>%K</kbd>, lets you create
 392 unique keywords for database records to help clear up any ambiguity.
 393 </p>
 394
 395 <p>
 396 Notice that you don&#8217;t have to worry about capitalization when
 397 entering keywords.
 398 </p>
 399
 400 <h4 id="fn-en-recipe" class="docs">5. Entering footnote/endnote references</h4>
 401
 402 <p>
 403 Depending on which you have issued, a
 404 <kbd><a href="#footnote-refs">.FOOTNOTE_REFS</a></kbd>
 405 or an
 406 <kbd><a href="#endnote-refs">.ENDNOTE_REFS</a></kbd>
 407 command, entering references is done like this:
 408 <br/>
 409 <span class="pre-in-pp">
 410   .REF
 411   .[
 412   keyword(s)
 413   .]
 414   .REF
 415 </span>
 416 If FOOTNOTE_REFS is in effect, the reference between the first
 417 and second <kbd>.REF</kbd> will be treated as a footnote.  If
 418 ENDNOTE_REFS, it will be treated as an endnote.  Endnote references
 419 must be explicitly output with
 420 <a href="docelement.html#ENDNOTES">ENDNOTES</a>
 421 at the end of your file, before
 422 <a href="tables-of-contents.html#TOC">TOC</a>.
 423 </p>
 424
 425 <div class="box-important">
 426 <p class="tip">
 427 <span class="important">Important:</span>
 428 REF behaves identically to
 429 <a href="docelement.html#footnote">FOOTNOTE</a>
 430 and
 431 <a href="docelement.html#endnote">ENDNOTE</a>
 432 with respect to the use of the <kbd>\c</kbd> inline escape.  Please
 433 read the
 434 <a href="docelement.html#footnote-note">HYPER IMPORTANT NOTE</a>
 435 found in the document entry for FOOTNOTE (which also applies to
 436 ENDNOTE).
 437 </p>
 438 </div>
 439
 440 <h4 id="parenthetical-insertions" class="docs">6. Parenthetical insertions</h4>
 441
 442 <p>
 443 See
 444 <a href="#parenthetical">Inserting parenthetical references into
 445 text</a>.
 446 </p>
 447
 448 <h4 id="bibliography-from-embedded" class="docs">7. Generating a bibliography from parenthetical insertions</h4>
 449
 450 <p>
 451 To generate a bibliography from works cited by parenthetical
 452 insertions in the text, put this at the end of your document, before
 453 <kbd><a href="tables-of-contest.html#TOC">.TOC</a></kbd>.
 454 <br/>
 455 <span class="pre-in-pp">
 456   .BIBLIOGRAPHY
 457   .[
 458   $LIST$
 459   .]
 460   .BIBLIOGRAPHY OFF
 461 </span>
 462 </p>
 463
 464 <h4 id="bibliography-recipe" class="docs">8. Generating a comprehensive bibliography</h4>
 465
 466 <p>
 467 You can also generate a comprehensive bibliography, which is to say a
 468 bibliography containing more works than are actually cited (a
 469 &#8220;reading list&#8221;), by placing references between
 470 <kbd><a href="#bibliography">.BIBLIOGRAPHY</a></kbd>
 471 and
 472 <kbd><a href="#bibliography">.BIBLIOGRAPHY&nbsp;OFF</a></kbd>.
 473 Once you have input the desired references, insert
 474 <br/>
 475 <span class="pre-in-pp">
 476   .[
 477   $LIST$
 478   .]
 479 </span>
 480 and follow it with <kbd>.BIBLIOGRAPHY&nbsp;OFF</kbd>.  Study the
 481 example below if you&#8217;re having trouble visualizing this.
 482 </p>
 483
 484 <div id="example-bibliography" class="examples" style="margin-top: -.5em;">Example bibliography</div>
 485 <div class="examples-container" style="padding-bottom: 1em;">
 486 <span class="pre">
 487 .BIBLIOGRAPHY
 488 .R1
 489 no-label-in-text
 490 no-label-in-reference
 491 join-authors ", and " ", " ", and "
 492 sort A1Q1T1B1E1
 493 reverse A1
 494 database &lt;full path to database&gt;
 495 .R2
 496 .[
 497 bradbury
 498 .]
 499 .[
 500 pratchett
 501 .]
 502 .[
 503 $LIST$
 504 .]
 505 .BIBLIOGRAPHY OFF
 506 </span>
 507 </div>
 508
 509 <p>
 510 Alternatively, you can output an entire database as a
 511 bibliography.  Do the following at the end of your document, before
 512 <kbd><a href="tables-of-contest.html#TOC">.TOC</a></kbd>.
 513 <br/>
 514 <span class="pre-in-pp">
 515   .BIBLIOGRAPHY
 516   .R1
 517   no-label-in-text
 518   no-label-in-reference
 519   join-authors ", and " ", " ", and "
 520   sort A1Q1T1B1E1
 521   reverse A1
 522   bibliography &lt;full path to database&gt;
 523   .R2
 524   .BIBLIOGRAPHY OFF
 525 </span>
 526 </p>
 527
 528 <h4 id="invoking-ref" class="docs">9. Invoking groff with mom and refer</h4>
 529
 530 <p>
 531 So, now you&#8217;ve got a document formatted properly to use
 532 references processed with <kbd>refer</kbd>, what do you do to output
 533 the document?
 534 </p>
 535
 536 <p>
 537 It&#8217;s simple.  Instead of invoking groff with just the
 538 <kbd>-mom</kbd> option, as explained
 539 <a href="using.html#using-saving">here</a>,
 540 invoke groff with the <kbd>-R</kbd> option as well, like this:
 541 <br/>
 542 <span class="pre-in-pp">
 543   groff -R -mom &lt;filename&gt; ...
 544 </span>
 545 </p>
 546 </div>
 547
 548 <div class="rule-medium" style="margin-top: 1em;"><hr/></div>
 549
 550 <h2 id="mla" class="docs">MLA (Modern Language Association) style</h2>
 551
 552 <h3 id="ref-styles" class="docs">Types of references (endnote, footnote, or embedded in text)</h3>
 553
 554 <p>
 555 MLA allows for three types of references, or referencing styles:
 556 </p>
 557 <ul style="margin-top: -.5em;">
 558   <li>short, parenthetical references in the text, linked to a
 559       works-cited list (bibliography) at the end of the document</li>
 560   <li>footnote references</li>
 561   <li>endnote references</li>
 562 </ul>
 563
 564 <p style="margin-top: -.5em;">
 565 There are significant differences between the way footnote/endnote
 566 references should be formatted, and the formatting style of
 567 bibliographies.  One example is that footnote/endnote references
 568 should have their first lines indented, whereas bibliographic
 569 references should have their second lines indented.  Fortunately,
 570 with mom, there&#8217;s no need to concern yourself with the differences;
 571 they&#8217;re taken care of automatically.
 572 </p>
 573
 574 <p>
 575 In terms of inserting references into your documents,
 576 footnote/endnote references are input in a manner similar to
 577 entering any other kind of
 578 <a href="docelement.html#footnote-into">footnote</a>
 579 or
 580 <a href="docelement.html#endnote-into">endnote</a>.
 581 Parenthetical references, however, need to be handled differently.
 582 See the next section.
 583 </p>
 584
 585 <h3 id="parenthetical" class="docs">Inserting parenthetical references into the text</h3>
 586
 587 <p>
 588 MLA style prefers restricting the information in parenthetical
 589 references to the barest minimum needed to identify works
 590 in the works-cited list (the bibliography).  Typically, a
 591 parenthetical insertion is just the author&#8217;s last name
 592 followed by the page number of the cited work (if only one work by
 593 that author is cited), or by the author, a shortened title of the
 594 work, and the page number (if more than one work is cited).
 595 </p>
 596
 597 <p>
 598 This necessitates a slightly fiddly way of entering parenthetical
 599 references, though not by any means difficult or hard to make sense
 600 of.
 601 </p>
 602
 603 <p>
 604 The <kbd>refer</kbd> block suggested
 605 <a href="#refer-block2">here</a>
 606 for parenthetical references prints only the author&#8217;s
 607 last name from the database record identified by your keywords
 608 (the <kbd>label</kbd> command), surrounded by parentheses (the
 609 <kbd>bracket-label</kbd> command).  Therefore, assuming you are
 610 citing Ray Bradbury&#8217;s <i>The Martian Chronicles</i>, and it is
 611 the only work by Bradbury mentioned in the text,
 612 <br/>
 613 <span class="pre-in-pp">
 614   ...end of sentence.
 615   .[
 616   martian chronicles
 617   .]
 618   A new sentence...
 619 </span>
 620 will insert &#8220;<span style="font-family: times; font-size: 105%; font-weight: bold">...end of sentence (Bradbury). A new sentence...</span>&#8221; into the text.
 621 <i>The Martian Chronicles</i> will be added
 622 to the works-cited list generated at the end of the document if it
 623 is not already present as the result of an earlier reference.
 624 </p>
 625
 626 <p>
 627 If you need a page number to identify where in <i>The Martian
 628 Chronicles</i> to find a specific quote
 629 <br/>
 630 <span class="pre-in-pp">
 631   "...aluminum roaches and iron crickets."
 632   .[
 633   [ martian chronicles
 634   .] 168)
 635   A new sentence...
 636 </span>
 637 results in &#8220;<span style="font-family: times; font-size: 105%; font-weight: bold">&#8220;...aluminum roaches and iron crickets.&#8221; (Bradbury 168)  A new sentence...</span>&#8221;
 638 (which is excruciatingly correct MLA style).  The
 639 &#8220;<kbd>[</kbd>&#8221; before <kbd>martian&nbsp;chronicles</kbd> tells
 640 refer to print the opening parenthesis; any text immediately
 641 following the &#8220;<kbd>.]</kbd>&#8221;, including spaces,
 642 <i>replaces</i> the closing parenthesis.  (Notice that you have to
 643 add the closing parenthesis yourself after the page number.)
 644 </p>
 645
 646 <p>
 647 If your document cites more than one work by Bradbury and you need
 648 a title and page number in addition to the author's name in the
 649 inline reference,
 650 <br/>
 651 <span class="pre-in-pp">
 652   "...aluminum roaches and iron crickets."
 653   .[
 654   [ bradbury martian
 655   .], \fIChronicles\fP 168)
 656   A new sentence...
 657 </span>
 658 will produce &#8220;<span style="font-family: times; font-size: 105%; font-weight: bold">&#8220;...aluminum roaches and iron crickets.&#8221; (Bradbury, <i>Chronicles</i> 168) A new sentence...</span>&#8221;.
 659 </p>
 660
 661 <div class="examples-container" style="margin-top: 1.5em; margin-bottom: 1.5em;">
 662 <h3 id="tutorial-ref" class="docs">The <span style="text-transform: none">&#8216;label&#8217;<span style="text-transform: uppercase"> and <span style="text-transform: none">&#8216;bracket-label&#8217;<span style="text-transform: uppercase"> commands</h3>
 663
 664 <p>
 665 The <kbd>label</kbd> and <kbd>bracket-label</kbd> commands in
 666 the refer block allow you to customize what information goes
 667 into parenthetical references, and how they should be formatted.
 668 <kbd>label</kbd> dictates which fields from the database record
 669 to print and how to punctuate them. <kbd>bracket-label</kbd>
 670 controls the bracketing style.  Users are encouraged to consult
 671 <kbd>man&nbsp;refer</kbd> for usage.
 672 </p>
 673
 674 <p>
 675 Here&#8217;s an example of how to set up APA-style references, which
 676 require the author and date of publication, optionally with a page
 677 number or range of pages.
 678 <br/>
 679 <span class="pre-in-pp">
 680   .R1
 681   label "(A.n|Q) ', ' D.y"
 682   bracket-label " (" ")" ", "
 683   join-authors ", and " ", " ", and "
 684   move-punctuation
 685   reverse A1
 686   sort A1Q1T1B1E1
 687   database /home/peter/Groff-mom/Testing/Refer/refer-database
 688   .R2
 689 </span>
 690 Assuming a reference to a work by Ursula Leguin published in 1980
 691 <br/>
 692 <span class="pre-in-pp">
 693   .[
 694   leguin
 695   .]
 696 </span>
 697 produces
 698 <span style="font-family: times; font-size: 105%; font-weight: bold">
 699 (Leguin, 1980)
 700 </span>.
 701 If a page number is also required
 702 <br/>
 703 <span class="pre-in-pp">
 704   .[
 705   [ leguin
 706   .], p. 73)
 707 </span>
 708 produces
 709 <span style="font-family: times; font-size: 105%; font-weight: bold">(Leguin, 1980, p. 73)</span>.
 710 </p>
 711 </div>
 712
 713 <div class="rule-medium" style="margin-top: 1em;"><hr/></div>
 714
 715 <h2 id="database" class="docs">The refer database</h2>
 716
 717 <h3 id="database-intro" class="docs">Introduction</h3>
 718
 719 <p style="margin-top: .5em;">
 720 The heart and soul of <kbd>refer</kbd> is the bibliographic
 721 database.  Knowing how to create records (ie. the entries for works
 722 cited in a document) is largely a question matching data (author,
 723 title, publisher, etc) with the correct field identifier.  For
 724 example, if you&#8217;re citing from a scholarly journal, you need to know
 725 that <kbd>%J</kbd> is the field identifier for journal names and
 726 <kbd>%N</kbd> is the field identifier for the journal number.  Use
 727 the
 728 <a href="#fields-quick">Quick list of field identifiers</a>
 729 as your guide.
 730 </p>
 731
 732 <h3 id="database-rules" class="docs">The rules</h3>
 733
 734 <p style="margin-top: .5em;">
 735 Entering the data correctly is also important.  Fortunately, there
 736 are very few rules, and those there are make sense.  In a nutshell:
 737 </p>
 738 <ul style="margin-top: -.5em;">
 739   <li>enter the data in each field in natural order; author John Smith is
 740       &#8220;John Smith&#8221;, editor Jane Doe is &#8220;Jane Doe&#8221;</li>
 741   <li>capitalize all proper nouns and words in titles as you expect
 742       to see them; otherwise, use lowercase</li>
 743   <li>use no terminating punctuation unless required; typically,
 744       required punctuation is the period after a shortform
 745       (&#8220;ed.&#8221; or &#8220;eds.&#8221;, &#8220;Jr.&#8221;,
 746       etc) or a question mark or exclamation mark at the end of a
 747       title</li>
 748   <li>if part of a field needs to be set off in single-quotes, use
 749       <kbd>\[oq]</kbd> and <kbd>\[cq]</kbd> (openquote, closequote) rather than the
 750       single-quote (or apostrophe) character on your keyboard</li>
 751   <li>if part of a field needs to be forced into italics, use the
 752       escapes <kbd>\*[IT]</kbd> and <kbd>\*[PREV]</kbd>; if the italicized
 753       portion concludes the field, omit <kbd>\*[PREV]</kbd></li>
 754   <li>if you require characters with accents, ligatures or special
 755       symbols, use groff&#8217;s &#8220;named&#8221; glyphs (eg.
 756       <kbd>\['e]</kbd> for <kbd>é</kbd>); a full list can be found in
 757       <kbd>man groff_char</kbd></li>
 758 </ul>
 759
 760 <h3 id="fields-quick" class="docs" style="margin-top: 1.25em; margin-bottom: .5em;">Quick guide to field identifiers <span style="text-transform: none;">(click on any that are links for more information)</span></h3>
 761
 762 <div class="examples-container" style="padding-bottom: 1em;">
 763 <span class="pre">
 764 <a class="quick" href="#A">%A</a> author           &ndash; records may contain multiple authors,
 765                       one per line
 766 <a class="quick" href="#Q">%Q</a> non-human author &ndash; corporate author, eg. National Geographic;
 767                       may also be used for exceptional reference types
 768 <a class="quick" href="#m">%m</a> multiple authors &ndash; whenever "et al." is desirable
 769 <a class="quick" href="#i">%i</a> idem             &ndash; multiple works by the same author
 770 <a class="quick" href="#p">%p</a> post-author      &ndash; post-author information (eg appendix,
 771                       foreword, letter)
 772 %T title            &ndash; primary title (of a book) or the
 773                       title of an article (within a scholarly
 774                       journal or a magazine)
 775 %B book title       &ndash; when %T contains the title of an article;
 776 <a class="quick" href="#q">%q</a> force quote      &ndash; force a title into double-quotes
 777 %t reprint title    &ndash; if different from a work's original title
 778 %b main author      &ndash; when citing a preface, foreword,
 779                       introduction, or afterword, the author of
 780                       the complete original work
 781 <a class="quick" href="#E">%E</a> editor           &ndash; records may contain multiple editors,
 782                       one per line
 783 <a class="quick" href="#l">%l</a> translator       &ndash; if more than one translator, all the
 784                       names
 785 %r translator       &ndash; if tr. and ed. are one in the same
 786     and editor
 787 %M magazine or      &ndash; when %T contains the title of an article
 788     newspaper
 789 %J journal          &ndash; when %T contains the title of an article
 790 %e edition          &ndash; number or name of an edition
 791                       (eg Second, 2nd, Collector's, etc.)
 792 %S series           &ndash; series name of books or journals
 793 %V volume           &ndash; volume number (of books)
 794 %N journal number   &ndash; journal or magazine number
 795 %R report number    &ndash; technical report number
 796 %G gov&#8217;t.           &ndash; government ordering number
 797 <a class="quick" href="#O">%O</a> other            &ndash; information or which there is no appropriate
 798                       field letter
 799 <a class="quick" href="#C">%C</a> city             &ndash; city of publication
 800 %I publisher        &ndash; publisher
 801 %D date             &ndash; publication date
 802 <a class="quick" href="#d">%d</a> original
 803    publication date &ndash; if different from date of publication
 804 <a class="quick" href="#P">%P</a> page(s)          &ndash; page number or range
 805 <a class="quick" href="#n">%n</a> annotation       &ndash; annotation to the reference
 806 %s site name        &ndash; for internet references, the website name
 807 %c content          &ndash; for internet references, the source of
 808                       the material (eg. Web or Email); for websites,
 809                       the content, if unclear
 810 %o organization     &ndash; for internet sites, the organization, group
 811                       or sponsor of the site
 812 %a access date      &ndash; for internet sites, the date of access
 813 %u URL              &ndash; for internet sites, the full URL
 814 <a class="quick" href="#K">%K</a> keywords         &ndash; words that help clear up ambiguities in
 815                       the database
 816 </span>
 817 </div>
 818
 819 <h3 id="fields-specifics" class="docs">Field identifiers: specifics, usage and examples</h3>
 820
 821 <h4 id="A" class="docs fields">%A &ndash; author field</h4>
 822
 823 <p>
 824 For multiple authors, enter each in a separate <kbd>%A</kbd>
 825 field in the order in which they should appear.  If the author on
 826 the title page is the editor (say, a book of short stories edited by
 827 Ray Bradbury), add <kbd>, ed.</kbd> to the end of the
 828 <kbd>%A</kbd> field, like this:
 829 <br/>
 830 <span class="pre-in-pp">
 831   %A Ray Bradbury, ed.
 832 </span>
 833 Do not use the <kbd>%E</kbd> field in these instances.  If the work
 834 has several such editors, enter each in a separate <kbd>%A</kbd>
 835 field, as for multiple authors, and add <kbd>, eds.</kbd> to the
 836 last one, like this:
 837 <br/>
 838 <span class="pre-in-pp">
 839   %A Jane Dearborne
 840   %A Bill Parsons, eds.
 841 </span>
 842 </p>
 843
 844 <h4 id="Q" class="docs fields">%Q &ndash; exceptional entries</h4>
 845
 846 <p>
 847 Sometimes, a work has no author or title information, for example a
 848 book review in a newspaper.  In such cases, use <kbd>%Q</kbd>, like
 849 this:
 850 <br/>
 851 <span class="pre-in-pp">
 852   %Q Rev. of \*[IT]Mean Streets Omnibus\*[PREV], ed. Raymond Hammett
 853   %M Times Literary Supplement
 854   %D 7 July 1972
 855 </span>
 856 </p>
 857
 858 <h4 id="m" class="docs fields">%m &ndash; multiple authors (et al.)</h4>
 859
 860 <p>
 861 Whenever it&#8217;s desirable to abbreviate a list of authors with
 862 &#8220;et al.&#8221; enter it in the <kbd>%m field</kbd>, like this:
 863 <br/>
 864 <span class="pre-in-pp">
 865   %A Paul Lauter
 866   %A Doug Scofield
 867   %m et al.
 868 </span>
 869 </p>
 870
 871 <h4 id="i" class="docs fields">%i &ndash; idem</h4>
 872
 873 <p>
 874 Whenever there are several works by the same author, fill out the
 875 <kbd>%A</kbd> field with the author&#8217;s name and follow it with the
 876 <kbd>%i idem</kbd>, like this:
 877 <br/>
 878 <span class="pre-in-pp">
 879   %A Jonathon Schmidt
 880   %i idem
 881 </span>
 882 Per MLA style, the author&#8217;s name will be replaced by a long dash.
 883 </p>
 884
 885 <p>
 886 If it&#8217;s necessary to state the role the author served (say,
 887 editor or translator), fill out the <kbd>%i</kbd> field with the
 888 information minus <kbd>idem</kbd>, like this:
 889 <br/>
 890 <span class="pre-in-pp">
 891   %A Ray Bradbury
 892   %i ed.
 893   %T Timeless Stories for Today and Tomorrow
 894 </span>
 895 </p>
 896
 897 <h4 id="p" class="docs fields">%p &ndash; post-author information</h4>
 898
 899 <p>
 900 When citing from a preface, foreword, introduction, afterword or
 901 appendix, MLA requires that the information come between the
 902 author&#8217;s name and the work&#8217;s title, like this:
 903 <br/>
 904 <span class="pre-in-pp">
 905   %A Martin Packham, Jr.
 906   %p appendix
 907   %T Why the West was Won
 908 </span>
 909 Do not capitalize the first word in the <kbd>%p</kbd> field unless
 910 it is a proper noun.
 911 </p>
 912
 913 <h4 id="q" class="docs fields">%q &ndash; force title into double-quotes</h4>
 914
 915 <p>
 916 Occasionally, you may not be able to use <kbd>%T</kbd> for the
 917 title because doing so will cause it to come out in italics when
 918 double-quotes are called for.  An example of this is when citing
 919 from a dissertation.  Use <kbd>%q</kbd> to get around the problem,
 920 like this:
 921 <br/>
 922 <span class="pre-in-pp">
 923   %A Carol Sakala
 924   %q Maternity Care Policy in the United States
 925   %O diss., Boston U, 1993
 926 </span>
 927 </p>
 928
 929 <h4 id="E" class="docs fields">%E &ndash; editor</h4>
 930
 931 <p>
 932 Use this only if the author and the editor are not one in the same,
 933 eg
 934 <br/>
 935 <span class="pre-in-pp">
 936   %A Geoffrey Chaucer
 937   %T The Works of Geoffrey Chaucer
 938   %E F. W. Robinson
 939 </span>
 940 </p>
 941
 942 <h4 id="l" class="docs fields">%l &ndash; translator</h4>
 943
 944 <p>
 945 If there is more than one translator, enter all the names, with
 946 appropriate conjunctions and punctuation, like this:
 947 <br/>
 948 <span class="pre-in-pp">
 949   %A Feodor Dostoevsky
 950   %T Crime and Punishment
 951   %l Jessie Coulson, Marjorie Benton, and George Bigian
 952 </span>
 953 </p>
 954
 955 <h4 id="O" class="docs fields">%O &ndash; other</h4>
 956
 957 <p>
 958 Occasionally, MLA requires additional information after the title
 959 but before the publication data (city/publisher/date), for instance,
 960 the number of volumes in a series, or the fact that the work cited
 961 is a dissertation.  Here are two examples:
 962 <br/>
 963 <span class="pre-in-pp">
 964   %A Arthur M. Schlesinger
 965   %T History of U.S. Political Parties
 966   %O 4 vols.
 967   %C New York
 968   %I Chelsea
 969   %D 1973
 970
 971   %A Carol Sakala
 972   %q Maternity Care Policy in the United States
 973   %O diss., Boston U, 1993
 974 </span>
 975 Do not capitalize the first word of the <kbd>%O</kbd> field unless
 976 it is a proper noun.
 977 </p>
 978
 979 <p>
 980 Generally, consider <kbd>%O</kbd> a catch-all for information that
 981 does not match the criterion of any existing field identifier.
 982 </p>
 983
 984 <h4 id="C" class="docs fields">%C &ndash; city</h4>
 985
 986 <p>
 987 Normally, <kbd>%C</kbd> takes the name of the city of publication,
 988 and that&#8217;s all.  In the case of a republished book, if new material
 989 has been added, put such information in the <kbd>%C</kbd>
 990 field, like this:
 991 <br/>
 992 <span class="pre-in-pp">
 993   %A Theodore Dreiser
 994   %T Sister Carrie
 995   %d 1900
 996   %C Introd. E. L. Doctorow, New York
 997 </span>
 998 </p>
 999
1000 <h4 id="d" class="docs fields">%d &ndash; original date of publication</h4>
1001
1002 <p>
1003 Normally, all that is required in the <kbd>%d</kbd> field is the
1004 original date of publication.  However, if supplementary original
1005 publication data is desired, include it in the field, like this:
1006 <br/>
1007 <span class="pre-in-pp">
1008   %A Kazuo Ishiguro
1009   %T The Remains of the Day
1010   %d London: Faber, 1989
1011   %D New York
1012   %I Knopf
1013   %D 1990
1014 </span>
1015 </p>
1016
1017 <h4 id="K" class="docs fields">%K &ndash; keywords</h4>
1018
1019 <p>
1020 <kbd>Refer</kbd> hates ambiguity, and complains when encountering
1021 it.  Ambiguities result from the duplication of any word in more
1022 than one database record when that word is used to identify a
1023 reference in your input file.  Use <kbd>%K</kbd> to create unique
1024 keywords found nowhere else in the database.
1025 </p>
1026
1027 <p>
1028 Imagine, for example, that your database contains records for
1029 Ray Bradbury&#8217;s <i>The Illustrated Man</i>, another record for
1030 <i>The Illustrated Bradbury</i> and a third for <i>Bradbury,
1031 Illustrated</i>.  <kbd>%K</kbd> can be used to clear up any
1032 ambiguities by assigning a unique word to each record, for example
1033 <kbd>%K ill-man</kbd> for the first, <kbd>%K ill-brad</kbd> for the
1034 second, and <kbd>%K brad-ill</kbd> for the third.
1035 </p>
1036
1037 <h4 id="P" class="docs fields">%P &ndash; pages</h4>
1038
1039 <p>
1040 When citing page numbers, which is often the case with footnotes
1041 and endnotes, it is not necessary to put the numbers in the database
1042 records.  The <kbd>%P</kbd> field can be added underneath the
1043 keyword(s) in the <kbd>.[</kbd> / <kbd>.]</kbd> entries in your
1044 input file, allowing you to recycle database records.  For example,
1045 <br/>
1046 <span class="pre-in-pp">
1047   %A Frye
1048   %T Anatomy
1049   %K frye-anat
1050 </span>
1051 could be your short record for Northrop Frye&#8217;s <i>The Anatomy of
1052 Criticism</i>.  Any time you wanted to cite a particular page or
1053 range of pages from that work in a footnote or endnote, you can
1054 put
1055 <br/>
1056 <span class="pre-in-pp">
1057   .REF
1058   .[
1059   frye-anat
1060   %P 67-8
1061   .]
1062   .REF
1063 </span>
1064 in your input file, and have it show up with the correct page(s).
1065 </p>
1066
1067 <h4 id="n" class="docs fields">%n &ndash; annotations</h4>
1068
1069 <p>
1070 Annotations come at the very end of references.  Capitalize all
1071 words that require it, including, for bibliographic references (but not
1072 for footnotes/endnotes) the first.
1073 </p>
1074
1075 <div class="rule-short"><hr/></div>
1076
1077 <div class="macro-list-container">
1078 <h3 id="index-ref" class="macro-list">The bibliography and reference macros</h3>
1079 <ul class="macro-list">
1080   <li><a href="#ref">REF</a> &ndash; begin/end a <kbd>refer</kbd> reference that will go in a footnote or endnote</li>
1081   <li><a href="#footnote-refs">FOOTNOTE_REFS</a> &ndash; instruct mom to put REFs in footnotes</li>
1082   <li><a href="#endnote-refs">ENDNOTE_REFS</a> &ndash; instruct mom to put REFs in endnotes</li>
1083   <li><a href="#indent-refs">INDENT_REFS</a> &ndash; manage indenting of references, per MLA standards</li>
1084   <li><a href="#hyphenate-refs">HYPHENATE_REFS</a> &ndash; enable/disable hyphenation of references</li>
1085   <li><a href="#bibliography">BIBLIOGRAPHY</a> &ndash; begin a bibliography</li>
1086   <li><a href="#bibliography-type">BIBLIOGRAPHY_TYPE</a> &ndash; plain, or numbered list bibliography</li>
1087   <li><a href="#biblio-control">Bibliography control macros and defaults</a></li>
1088 </ul>
1089 </div>
1090
1091 <!-- -REF- -->
1092
1093 <div class="macro-id-overline">
1094 <h3 id="ref" class="macro-id">Begin/end a reference that goes in a footnote or endnote</h3>
1095 </div>
1096
1097 <div class="box-macro-args">
1098 Macro: <b>REF</b>
1099 </div>
1100
1101 <p>
1102 The macro, REF, tells mom that what follows is
1103 <kbd>refer</kbd>-specific, a keyword-identified reference to a
1104 <kbd>refer</kbd> database record.  Depending on whether you&#8217;ve issued
1105 a
1106 <kbd><a href="#footnote-refs">.FOOTNOTE_REFS</a></kbd>
1107 or
1108 <kbd><a href="#endnote-refs">.ENDNOTE_REFS</a></kbd>
1109 instruction, the reference will be formatted and placed in a
1110 footnote, or collected for output in the endnotes.  Parenthetical
1111 insertion of references into the text do not require
1112 <kbd>.REF</kbd> (see
1113 <a href="#parenthetical">Inserting parenthetical references into the text</a>.)
1114 </p>
1115
1116 <p>
1117 Before you use REF, you must create a <kbd>refer</kbd> block
1118 containing <kbd>refer</kbd> commands (see
1119 <a href="#rcommands-ref">Required refer commands</a>
1120 in the tutorial, above).
1121 </p>
1122
1123 <p>
1124 REF usage always looks like this:
1125 <br/>
1126 <span class="pre-in-pp">
1127   .REF
1128   .[
1129   keyword(s)
1130   .]
1131   .REF
1132 </span>
1133 Notice that REF &#8220;brackets&#8221; the <kbd>refer</kbd> instructions,
1134 and never takes an argument.
1135 </p>
1136
1137 <p>
1138 What REF really is is a convenience.  One could, for example, put a
1139 reference in a footnote by doing
1140 <br/>
1141 <span class="pre-in-pp">
1142   .FOOTNOTE
1143   .[
1144   keyword(s)
1145   .]
1146   .FOOTNOTE OFF
1147 </span>
1148 However, if you have a lot of references going into footnotes (or
1149 endnotes), it&#8217;s much shorter to type <kbd>.REF/.REF</kbd>
1150 than <kbd>.FOOTNOTE/.FOOTNOTE OFF</kbd>.  It also helps you
1151 distinguish&mdash;visually, in your input file&mdash;between
1152 footnotes (or endnotes) which are references, and footnotes (or
1153 endnotes) which are explanatory, or expand on the text.
1154 </p>
1155
1156 <div class="box-tip">
1157 <p class="tip-top">
1158 <span class="note">Note:</span>
1159 If you&#8217;re using REF to put references in footnotes and your
1160 footnotes need to be indented, you may (indeed, should) pass REF the
1161 same arguments used to indent footnotes.  See
1162 <a href="docelement.html#footnote">FOOTNOTE</a>.
1163 </p>
1164
1165 <p class="tip-bottom">
1166 <span class="additional-note">Additional note:</span>
1167 REF behaves identically to
1168 <a href="docelement.html#footnote">FOOTNOTE</a>
1169 or
1170 <a href="docelement.html#footnote">ENDNOTE</a>,
1171 so please read the HYPER IMPORTANT NOTE found in the document entry
1172 for
1173 <a href="docelement.html#footnote-note">FOOTNOTE</a>
1174 and/or
1175 <a href="docelement.html#endnote-note">ENDNOTE</a>
1176 for instructions on correct entry of text preceding and following REF.
1177 </p>
1178 </div>
1179
1180 <!-- -FOOTNOTE_REFS- -->
1181
1182
1183 <div class="macro-id-overline">
1184 <h3 id="footnote-refs" class="macro-id">Instruct mom to put references in footnotes</h3>
1185 </div>
1186
1187 <div class="box-macro-args">
1188 Macro: <b>FOOTNOTE_REFS</b>
1189 </div>
1190
1191 <p>
1192 FOOTNOTE_REFS is an instruction to
1193 <a href="#ref">REF</a>,
1194 saying, &#8220;put all subsequent references bracketed by the REF
1195 macro into footnotes.&#8221; You invoke it by itself, with no
1196 argument.
1197 </p>
1198
1199 <p>
1200 When FOOTNOTE_REFS is in effect, regular footnotes, (ie
1201 those introduced with <kbd>.FOOTNOTE</kbd> and terminated with
1202 <kbd>.FOOTNOTE OFF</kbd>) continue to behave normally.
1203 </p>
1204
1205 <p>
1206 You may switch between FOOTNOTE_REFS and
1207 <a href="#endnote-refs">ENDNOTE_REFS</a>
1208 at any time.
1209 </p>
1210
1211 <p>
1212 By default, FOOTNOTE_REFS sets the
1213 <a href="docelement.html#footnote-marker-style">FOOTNOTE_MARKER_STYLE</a>
1214 to <kbd>NUMBER</kbd> (ie superscript numbers).  You may change
1215 change that if you wish by invoking FOOTNOTE_MARKER_STYLE, with the
1216 argument you want after FOOTNOTE_REFS.
1217 </p>
1218
1219 <p>
1220 If you have a lot of footnote references, and are identifying
1221 footnotes by line number rather than by markers in the text, you may
1222 want to enable
1223 <a href="docelement.html#footnotes-run-on">FOOTNOTES_RUN_ON</a>
1224 in conjunctions with FOOTNOTE_REFS.
1225 </p>
1226
1227 <!-- -ENDNOTE_REFS- -->
1228
1229 <div class="macro-id-overline">
1230 <h3 id="endnote-refs" class="macro-id">Instruct mom to put references in endnotes</h3>
1231 </div>
1232
1233 <div class="box-macro-args">
1234 Macro: <b>ENDNOTE_REFS</b>
1235 </div>
1236
1237 <p>
1238 ENDNOTE_REFS is an instruction to
1239 <a href="#ref">REF</a>,
1240 saying, &#8220;add all subsequent references bracketed by the REF
1241 macro to endnotes.&#8221; You invoke it by itself, with no argument.
1242 </p>
1243
1244 <p>
1245 When ENDNOTE_REFS is in effect, mom continues to format regular
1246 endnotes, (ie those introduced with <kbd>.ENDNOTE</kbd> and
1247 terminated with <kbd>.ENDNOTE OFF</kbd>) in the normal way.
1248 </p>
1249
1250 <p>
1251 You may switch between ENDNOTE_REFS and
1252 <a href="#footnote-refs">FOOTNOTE_REFS</a>
1253 at any time.
1254 </p>
1255
1256 <!-- -INDENT_REFS- -->
1257
1258 <div class="macro-id-overline">
1259 <h3 id="indent-refs" class="macro-id">Manage indenting of references, per MLA standards</h3>
1260 </div>
1261
1262 <div class="box-macro-args">
1263 Macro: <b>INDENT_REFS</b> <kbd class="macro-args">FOOTNOTE | ENDNOTE | BIBLIO &lt;indent&gt; </kbd>
1264 </div>
1265
1266 <p class="requires">
1267 &bull;&nbsp;<kbd style="font-style: normal;">&lt;indent&gt;</kbd> requires a <a href="definitions.html#unitofmeasure">unit of measure</a>
1268 </p>
1269
1270 <p>
1271 MLA-style requires that footnote or endnote references should
1272 have their first lines indented, whereas bibliographic references
1273 should have their second and subsequent lines indented.  Thus, if
1274 you invoke INDENT_REFS with a first argument of <kbd>FOOTNOTE</kbd>
1275 or <kbd>ENDNOTE</kbd>, the value you give to
1276 <kbd>&lt;indent&gt;</kbd> sets the indent of the first line for
1277 those types of references; if you invoke it with <kbd>BIBLIO</kbd>,
1278 the value you give <kbd>&lt;indent&gt;</kbd> sets the indent of
1279 second and subsequent lines in bibliographies.
1280 </p>
1281
1282 <p>
1283 By default, the indent for all three types of references is 1/2-inch
1284 for
1285 <a href="docprocessing.html#printstyle">PRINTSTYLE <kbd>TYPEWRITE</kbd></a>
1286 and 2
1287 <a href="definitions.html#em">ems</a>
1288 for
1289 <a href="docprocessing.html#printstyle">PRINTSTYLE <kbd>TYPESET</kbd></a>.
1290 </p>
1291
1292 <p>
1293 If you&#8217;d like to change the indent for footnote, endnote or
1294 bibliography references, just invoke <kbd>.INDENT_REFS</kbd> with
1295 a first argument saying which one you want the indent changed for, and
1296 a second argument saying what you&#8217;d like the indent to be.
1297 For example, if you want the second-line indent of references on a
1298 bibliography page to be 3
1299 <a href="definitions.html#picas-points">picas</a>,
1300 <br/>
1301 <span class="pre-in-pp">
1302   .INDENT_REFS BIBLIO 3P
1303 </span>
1304 is how you&#8217;d set it up.
1305 </p>
1306
1307 <div class="box-tip">
1308 <p class="tip-top">
1309 <span class="tip">Tip:</span>
1310 If you are identifying endnotes by line number
1311 (<a href="docelement.html#endnote-marker-style">ENDNOTE_MARKER_STYLE&nbsp;<kbd>LINE</kbd></a>)
1312 and have instructed mom to put references bracketed by
1313 <kbd><a href="#ref">.REF</a></kbd>
1314 into endnotes (with
1315 <a href="#endnote-refs">ENDNOTE_REFS</a>),
1316 you will almost certainly want to adjust the second-line indent for
1317 references in endnotes, owing to the way mom formats line-numbered
1318 endnotes.  Study the output of such documents to see whether an
1319 indent adjustment is required.
1320 </p>
1321
1322 <p>
1323 The same advice applies to references in endnotes when you have enabled
1324 <br/>
1325 <span class="pre-in-pp">
1326   <a href="docelement.html#endnote-numbers-align-left">.ENDNOTE_NUMBERS_ALIGN_LEFT</a>
1327 </span>
1328 in favour of mom&#8217;s default, which is to align them right.
1329 Study the output to determine what size of second-line indent works
1330 best.
1331 </p>
1332
1333 <p class="tip-bottom">
1334 <i>(Frankly, endnote references formatted in MLA-style combined with
1335 left-aligned endnote numbers is a no-win situation, and so is best
1336 avoided.  Wherever you set the indent, you&#8217;ll end up with the
1337 endnote numbers appearing to hang into the left margin, so you might
1338 as well have them hang, as is the case with
1339 <kbd style="font-style: normal;">.ENDNOTE_NUMBERS_ALIGN_RIGHT</kbd>.</i>&nbsp;&nbsp;&ndash;&nbsp;Ed.)
1340 </p>
1341 </div>
1342
1343 <!-- -HYPHENATE_REFS- -->
1344
1345 <div class="macro-id-overline">
1346 <h3 id="hyphenate-refs" class="macro-id">Enable/disable hyphenation of references</h3>
1347 </div>
1348
1349 <div class="box-macro-args">
1350 Macro: <b>HYPHENATE_REFS</b> <kbd class="macro-args">&lt;toggle&gt;</kbd>
1351 </div>
1352
1353 <p>
1354 If you have hyphenation turned on for a document (see
1355 <a href="typesetting.html#hy">HY</a>),
1356 and in most cases you probably do, mom will hyphenate references
1357 bracketed by the
1358 <a href="#ref">REF</a>
1359 macro.  Since references typically contain quite a lot of proper
1360 names, which shouldn&#8217;t be hyphenated, you may want to disable
1361 hyphenation for references.
1362 </p>
1363
1364 <p>
1365 HYPHENATE_REFS is a toggle macro; invoking it by itself will turn
1366 automatic hyphenation of REF-bracketed references on (the default).
1367 Invoking it with any other argument (<kbd>OFF, NO, X</kbd>, etc.)
1368 will disable automatic hyphenation for references bracketed by REF.
1369 </p>
1370
1371 <p>
1372 An alternative to turning reference hyphenation off is to prepend
1373 to selected proper names in your <kbd>refer</kbd> database
1374 the groff
1375 <a href="definitions.html#discretionaryhyphen">discretionary hyphen</a>
1376 character, <kbd>\%</kbd>.  (See
1377 <a href="#ref-disc-hy">here</a>
1378 in the tutorial for an example.)
1379 </p>
1380
1381 <div class="box-tip">
1382 <p class="tip">
1383 <span class="note">Note:</span>
1384 References embedded in the body of a document are considered part of
1385 <a href="definitions.html#running">running text</a>,
1386 and are hyphenated (or not) according to whether hyphenation is
1387 turned on or off for running text.  Therefore, if you want to
1388 disable hyphenation for such references, you must do so temporarily,
1389 with
1390 <a href="typesetting.html#hy">HY</a>,
1391 like this:
1392 <br/>
1393 <span class="pre-in-pp">
1394   .HY OFF
1395   .[
1396   keyword(s)
1397   .]
1398   .HY
1399 </span>
1400 Alternatively, sprinkle your database fields liberally with
1401 <kbd>\%</kbd>.
1402 </p>
1403 </div>
1404
1405 <!-- -BIBLIOGRAPHY- -->
1406
1407 <div class="macro-id-overline">
1408 <h3 id="bibliography" class="macro-id">Begin a bibliography</h3>
1409 </div>
1410
1411 <div class="box-macro-args">
1412 Macro: <b>BIBLIOGRAPHY</b> <kbd class="marco-args">toggle</kbd>
1413 </div>
1414
1415 <p>
1416 To append a bibliography to your document, whether of references
1417 inserted parenthetically into text or a comprehensive reading list
1418 derived from a large <kbd>refer</kbd> database, all you need
1419 do is invoke <kbd>.BIBLIOGRAPHY</kbd>. <kbd>.BIBLIOGRAPHY</kbd>
1420 breaks to a new page, prints the title (BIBLIOGRAPHY by default, but
1421 that can be changed), and awaits <kbd>refer</kbd> instructions.  How
1422 to create bibliographies is covered in the tutorial section,
1423 <a href="#bibliography-from-embedded">Generating a bibliography from parenthetical insertions</a>
1424 and
1425 <a href="#bibliography-recipe">Generating a comprehensive bibliography</a>.
1426 When all the required data has been entered, type
1427 <br/>
1428 <span class="pre-in-pp">
1429   .BIBLIOGRAPHY OFF
1430 </span>
1431 to complete the bibliography.
1432 </p>
1433
1434 <p>
1435 See the
1436 <a href="#biblio-control">Bibliography control macros and defaults</a>
1437 for macros to tweak, design and control the appearance of
1438 bibliography pages.
1439 </p>
1440
1441 <!-- -BIBLIOGRAPHY_TYPE- -->
1442
1443 <div class="macro-id-overline">
1444 <h3 id="bibliography-type" class="macro-id">Plain, or numbered list bibliography</h3>
1445 </div>
1446
1447 <div class="box-macro-args">
1448 Macro: <b>BIBLIOGRAPHY_TYPE</b> <kbd class="macro-args">PLAIN | LIST [ &lt;list separator&gt; ] [ &lt;list prefix&gt; ]</kbd>
1449 </div>
1450
1451 <p>
1452 Mom offers two styles of bibliography output: plain, or numbered
1453 list style.  With the argument, <kbd>PLAIN</kbd>, bibliography entries are output
1454 with no enumerators.  With the argument, <kbd>LIST</kbd>, each entry is numbered.
1455 </p>
1456
1457 <p>
1458 The two optional arguments, <kbd>&lt;list&nbsp;separator&gt;</kbd>
1459 and <kbd>&lt;list&nbsp;prefix&gt;</kbd> have the same meaning as the
1460 equivalent arguments to
1461 <a href="docelement.html#list">LIST</a>
1462 (ie <kbd>&lt;separator&gt;</kbd> and <kbd>&lt;prefix&gt;</kbd>).
1463 </p>
1464
1465 <p>
1466 You may enter the BIBLIOGRAPHY_TYPE either before or after
1467 <kbd>.BIBLIOGRAPHY</kbd>.  It must, however, always come before the
1468 any <kbd>refer</kbd> commands.  See
1469 <a href="#bibliography-from-embedded">Generating a bibliography from parenthetical insertions</a>
1470 and
1471 <a href="#bibliography-recipe">Generating a comprehensive bibliography</a>.
1472 </p>
1473
1474 <p>
1475 Mom&#8217;s default BIBLIOGRAPHY_TYPE is PLAIN.
1476 </p>
1477
1478 <!-- -BIBLIO_CONTROL- -->
1479
1480 <div class="defaults-container" style="background-color: #ded4bd; border: none;">
1481 <h3 id="biblio-control" class="docs defaults">Bibliography control macros and defaults</h3>
1482
1483 <p style="margin-top: .25em; margin-left: 9px;">
1484 Mom processes bibliography pages in a manner very similar to the
1485 way she processes endnotes pages.  The bibliography page control
1486 macros, therefore, behave in the same way as their endnotes pages
1487 equivalents.
1488 </p>
1489
1490 <ol style="margin-top: -.5em; padding-bottom: .5em;">
1491   <li><a href="#biblio-general"><b>General bibliography style control</b></a>
1492   <ul style="margin-left: -.5em;">
1493     <li><a href="#biblio-style">Base family/font/quad</a></li>
1494     <li><a href="#biblio-pt-size">Base point size</a></li>
1495     <li><a href="#biblio-lead">Leading</a></li>
1496     <li><a href="#biblio-spacing">Adjust the space between bibliography entries</a></li>
1497     <li><a href="#singlespace-biblio">Singlespace bibliographies (for TYPEWRITE only)</a></li>
1498     <li><a href="#biblio-no-columns">Turning off column mode during bibliography output</a></li>
1499   </ul></li>
1500   <li><a href="#biblio-pagination"><b>Pagination of bibliographies</b></a>
1501   <ul style="margin-left: -.5em;">
1502     <li><a href="#biblio-pagenum-style">Page numbering style</a></li>
1503     <li><a href="#biblio-first-pagenumber">Setting the first page number of bibliographies</a></li>
1504     <li><a href="#biblio-no-first-pagenum">Omitting a page number on the first page of bibliographies</a></li>
1505     <li><a href="#suspend-pagination">Suspending pagination during bibliography output</a></li>
1506   </ul></li>
1507   <li><a href="#biblio-header-control"><b>Header/footer control</b></a>
1508   <ul style="margin-left: -.5em;">
1509     <li><a href="#biblio-modify-hdrftr">Modifying what goes in bibliography headers/footers</a></li>
1510     <li><a href="#biblio-hdrftr-center">Header/footer centre string when doctype is CHAPTER</a></li>
1511     <li><a href="#biblio-allows-headers">Allow headers on bibliography pages</a></li>
1512   </ul></li>
1513   <li><a href="#biblio-main-title"><b>Bibliography first-page title control</b></a>
1514   <ul>
1515     <li><a href="#biblio-string">Title string</a></li>
1516     <li><a href="#biblio-string-control">Title string control macros and defaults</a></li>
1517     <li><a href="#biblio-string-placement">Title string placement</a></li>
1518     <li><a href="#biblio-string-underline">Title string underscoring</a></li>
1519     <li><a href="#biblio-string-caps">Title string capitalization</a></li>
1520   </ul></li>
1521 </ol>
1522 </div>
1523
1524 <h4 id="biblio-general" class="docs" style="margin-top: -1.5em; margin-bottom: .5em;">1. General bibliography page style control</h4>
1525
1526 <h5 id="biblio-style" class="docs" style="margin-top: 0; margin-bottom: .5em; margin-left: .5em;">&bull;&nbsp;Base family/font/quad</h5>
1527
1528 <div class="defaults-container" style="padding-bottom: 8px;">
1529 <p class="defaults" style="padding-top: 6px;">
1530 See
1531 <a href="#control-macro-args">Arguments to the control macros</a>.
1532 </p>
1533 <span class="pre defaults">
1534 .BIBLIOGRAPHY_FAMILY    default = prevailing document family; default is Times Roman
1535 .BIBLIOGRAPHY_FONT      default = roman
1536 .BIBLIOGRAPHY_QUAD*     default = justified
1537
1538 *Note: BIBLIOGRAPHY_QUAD must be set to either L (LEFT) or J (JUSTIFIED);
1539  R (RIGHT) and C (CENTER) will not work.
1540 </span>
1541 </div>
1542
1543 <!-- -BIBLIO_PT_SIZE- -->
1544
1545 <h5 id="biblio-pt-size" class="docs" style="margin-top: -1.5em; margin-bottom: .5em; margin-left: .5em;">&bull;&nbsp;Base point size</h5>
1546
1547 <div class="box-macro-args">
1548 Macro: <b>BIBLIOGRAPHY_PT_SIZE</b> <kbd class="macro-args">&lt;base type size of bibliography&gt;</kbd>
1549 </div>
1550
1551 <p>
1552 Unlike most other control macros that deal with size of document
1553 elements, BIBLIOGRAPHY_PT_SIZE takes as its argument an absolute
1554 value, relative to nothing.  Therefore, the argument represents the
1555 size of bibliography type in
1556 <a href="definitions.html#picaspoints">points</a>,
1557 unless you append an alternative
1558 <a href="definitions.html#unitofmeasure">unit of measure</a>.
1559 For example,
1560 <br/>
1561 <span class="pre-in-pp">
1562   .BIBLIOGRAPHY_PT_SIZE 12
1563 </span>
1564 sets the base point size of type on the bibliography page to 12
1565 points, whereas
1566 <br/>
1567 <span class="pre-in-pp">
1568   .BIBLIOGRAPHY_PT_SIZE .6i
1569 </span>
1570 sets the base point size of type on the bibliography page to 1/6 of an
1571 inch.
1572 </p>
1573
1574 <p>
1575 The type size set with BIBLIOGRAPHY_PT_SIZE is the size of type used
1576 for the text of the bibliographies, and forms the basis from which
1577 the point size of other bibliography page elements is calculated.
1578 </p>
1579
1580 <p>
1581 The default for
1582 <a href="docprocessing.html#printstyle">PRINTSTYLE <kbd>TYPESET</kbd></a>
1583 is 12.5 points (the same default size used in the body of the
1584 document).
1585 </p>
1586
1587 <!-- -BIBLIO_LEAD- -->
1588
1589 <h5 id="biblio-lead" class="docs" style="margin-top: -.5em; margin-bottom: .5em; margin-left: .5em;">&bull;&nbsp;Leading</h5>
1590
1591 <div class="box-macro-args">
1592 Macro: <b>BIBLIOGRAPHY_LEAD</b> <kbd class="macro-args">&lt;base leading of bibliographies&gt; [ ADJUST ]</kbd>
1593 </div>
1594
1595 <p class="requires">
1596 &bull;&nbsp;Does not require a <a href="definitions.html#unitofmeasure">unit of measure</a>; points is assumed
1597 </p>
1598
1599 <p>
1600 Unlike most other control macros that deal with leading of document
1601 elements, BIBLIOGRAPHY_LEAD takes as its argument an absolute value,
1602 relative to nothing.  Therefore, the argument represents the
1603 <a href="definitions.html#leading">leading</a>
1604 of bibliographies in
1605 <a href="definitions.html#picaspoints">points</a>
1606 unless you append an alternative
1607 <a href="definitions.html#unitofmeasure">unit of measure</a>.
1608 For example,
1609 <br/>
1610 <span class="pre-in-pp">
1611   .BIBLIOGRAPHY_LEAD 14
1612 </span>
1613 sets the base leading of type on the bibliography page to 14
1614 points, whereas
1615 <br/>
1616 <span class="pre-in-pp">
1617   .BIBLIOGRAPHY_LEAD .5i
1618 </span>
1619 sets the base leading of type on the bibliography page to 1/2 inch.
1620 </p>
1621
1622 <p>
1623 If you want the leading of bibliographies adjusted to fill the page,
1624 pass BIBLIOGRAPHY_LEAD the optional argument,
1625 <kbd>ADJUST</kbd>.  (See
1626 <a href="docprocessing.html#doc-lead-adjust">DOC_LEAD_ADJUST</a>
1627 for an explanation of leading adjustment.)
1628 </p>
1629
1630 <p>
1631 The default for
1632 <a href="docprocessing.html#printstyle">PRINTSTYLE <kbd>TYPESET</kbd></a>
1633 is the prevailing document lead (16 by default), adjusted.
1634 </p>
1635
1636 <div class="box-tip">
1637 <p class="tip">
1638 <span class="note">Note:</span>
1639 Even if you give mom a <kbd>.DOC_LEAD_ADJUST&nbsp;OFF</kbd> command,
1640 she will still, by default, adjust bibliography leading.  You
1641 <i>must</i> enter <kbd>BIBLIOGRAPHY_LEAD&nbsp;&lt;lead&gt;</kbd>
1642 with no <kbd>ADJUST</kbd> argument to disable this default
1643 behaviour.
1644 </p>
1645 </div>
1646
1647 <!-- -BIBLIO_SPACING- -->
1648
1649 <h5 id="biblio-spacing" class="docs" style="margin-top: -.5em; margin-bottom: .5em; margin-left: .5em;">&bull;&nbsp;Adjust the space between bibliography entries</h5>
1650
1651 <div class="box-macro-args">
1652 Macro: <b>BIBLIOGRAPHY_SPACING</b> <kbd class="macro-args">&lt;amount of space&gt; </kbd>
1653 </div>
1654
1655 <p class="requires">
1656 &bull;&nbsp;Requires a <a href="definitions.html#unitofmeasure">unit of measure</a>
1657 </p>
1658
1659 <p>
1660 By default, mom inserts no space between bibliography entries.
1661 If you&#8217;d prefer she add some, instruct her to do so with
1662 BIBLIOGRAPHY_SPACING.  Say, for example, you want a half a linespace
1663 between entries,
1664 <br/>
1665 <span class="pre-in-pp">
1666   .BIBLIOGRAPHY_SPACING .5v
1667 </span>
1668 would do the trick.
1669 </p>
1670
1671 <div class="box-tip">
1672 <p class="tip">
1673 <span class="note">Note:</span>
1674 As with endnotes pages, inserting space between bibliography entries
1675 will most likely result in hanging bottom margins.
1676 </p>
1677 </div>
1678
1679 <!-- -SINGLESPACE_BIBLIO- -->
1680
1681 <h5 id="singlespace-biblio" class="docs" style="margin-top: -.5em; margin-bottom: .5em; margin-left: .5em;">&bull;&nbsp;Singlespace bibliography (TYPEWRITE only)</h5>
1682
1683 <div class="box-macro-args">
1684 Macro: <b>SINGLESPACE_BIBLIOGRAPHY</b> <kbd class="macro-args">&lt;toggle&gt;</kbd>
1685 </div>
1686
1687 <p>
1688 If your
1689 <a href="docprocessing.html#printstyle">PRINTSTYLE</a>
1690 is <kbd>TYPEWRITE</kbd> and you use TYPEWRITE&#8217;s default
1691 double-spacing, bibliographies are double-spaced.  If your document
1692 is single-spaced, bibliographies are single-spaced.
1693 </p>
1694
1695 <p>
1696 If, for some reason, you&#8217;d prefer that bibliographies be
1697 single-spaced in an otherwise double-spaced document (including
1698 double-spaced
1699 <a href="rectoverso.html#collate">collated</a>
1700 documents), invoke <kbd>.SINGLESPACE_BIBLIOGRAPHY</kbd> with with no
1701 argument.
1702 </p>
1703
1704 <!-- -BIBLIO_NO_COLUMNS- -->
1705
1706 <h5 id="biblio-no-columns" class="docs" style="margin-top: -.5em; margin-bottom: .5em; margin-left: .5em;">&bull;&nbsp;Turning off column mode during bibliography output</h5>
1707
1708 <div class="box-macro-args">
1709 Macro: <b>BIBLIOGRAPHY_NO_COLUMNS</b> <kbd class="macro-args">&lt;toggle&gt;</kbd>
1710 </div>
1711
1712 <p>
1713 By default, if your document is set in
1714 <a href="docprocessing.html#columns">columns</a>,
1715 mom sets the bibliographies in columns, too.  However, if your
1716 document is set in columns and you&#8217;d like the bibliographies
1717 not to be, just invoke <kbd>.BIBLIOGRAPHY_NO_COLUMNS</kbd> with
1718 no argument.  The bibliography pages will be set to the full page
1719 measure of your document.
1720 </p>
1721
1722 <p>
1723 If you output bibliographies at the end of each document in a
1724 <a href="rectoverso.html#collate">collated</a>
1725 document set in columns, column mode will automatically be
1726 reinstated for each document, even with BIBLIOGRAPHY_NO_COLUMNS
1727 turned on.  In such circumstances, you must re-enable
1728 ENDNOTES_NO_COLUMNS for each separate collated document.
1729 </p>
1730
1731 <h4 id="biblio-pagination" class="docs" style="margin-bottom: .5em;">2. Pagination of bibliographies</h4>
1732
1733 <!-- -BIBLIO_PAGENUM_STYLE- -->
1734
1735 <h5 id="biblio-pagenum-style" class="docs" style="margin-top: 0; margin-bottom: .5em; margin-left: .5em;">&bull;&nbsp;Page numbering style</h5>
1736
1737 <div class="box-macro-args">
1738 Macro: <b>BIBLIOGRAPHY_PAGENUM_STYLE</b> <kbd class="macro-args">DIGIT | ROMAN | roman | ALPHA | alpha</kbd>
1739 </div>
1740
1741 <p>
1742 Use this macro to set the page numbering style of bibliography
1743 pages.  The arguments are identical to those for
1744 <a href="headfootpage.html#pagenum-style">PAGENUM_STYLE</a>.
1745 The default is <kbd>digit</kbd>.  You may want to change it to, say,
1746 <kbd>alpha</kbd>, which you would do with
1747 <br/>
1748 <span class="pre-in-pp">
1749   .BIBLIOGRAPHY_PAGENUM_STYLE alpha
1750 </span>
1751 </p>
1752
1753 <!-- -BIBLIO_FIRST_PAGENUMBER- -->
1754
1755 <h5 id="biblio-first-pagenumber" class="docs" style="margin-top: -.5em; margin-bottom: .5em; margin-left: .5em;">&bull;&nbsp;Setting the first page number of bibliographies</h5>
1756
1757 <div class="box-macro-args">
1758 Macro: <b>BIBILOGRAPHY_FIRST_PAGENUMBER</b> <kbd class="macro-args">&lt;page # that appears on page 1 of bibliographies&gt;</kbd>
1759 </div>
1760
1761 <p>
1762 Use this macro with caution.  If the bibliography for a
1763 <a href="rectoverso.html#collate">collated</a>
1764 document is to be output at the document&#8217;s end,
1765 BIBLIOGRAPHY_FIRST_PAGENUMBER tells mom what page number to put on
1766 the first page of the bibliography.
1767 </p>
1768
1769 <p>
1770 However, if you&#8217;re outputting a bibliography at the end of each
1771 section (chapter, article, etc) of a collated document,
1772 you have to reset every section&#8217;s first page number after
1773 <a href="rectoverso.html#collate">COLLATE</a>
1774 and before
1775 <a href="docprocessing.html#start">START</a>.
1776 </p>
1777
1778 <!-- -BIBLIO_NO_FIRST_PAGENUN- -->
1779
1780 <h5 id="biblio-no-first-pagenum" class="docs" style="margin-top: -.25em; margin-bottom: .5em; margin-left: .5em;">&bull;&nbsp;Omitting a page number on the first page of bibliographies</h5>
1781
1782 <div class="box-macro-args">
1783 Macro: <b>BIBLIOGRAPHY_NO_FIRST_PAGENUM</b> <kbd class="macro-args">&lt;toggle&gt;</kbd>
1784 </div>
1785
1786 <p>
1787 This macro is for use only if
1788 <a href="headfootpage.html#footers">FOOTERS</a>
1789 are on.  It tells
1790 <kbd><a href="#bibliography">BIBLIOGRAPHY</a></kbd>
1791 not to print a page number on the first bibliography page.
1792 Mom&#8217;s default is to print the page number.
1793 </p>
1794
1795 <!-- -SUSPEND_PAGINATION- -->
1796
1797 <h5 id="suspend-pagination" class="docs" style="margin-top: -.5em; margin-bottom: .5em; margin-left: .5em;">&bull;&nbsp;Suspending pagination during bibliography output</h5>
1798
1799 <div class="box-macro-args" style="margin-bottom: 1em;">
1800 Macro: <b>SUSPEND_PAGINATION</b>
1801 </div>
1802
1803 <div class="box-macro-args">
1804 Macro: <b>RESTORE_PAGINATION</b>
1805 </div>
1806
1807 <p>
1808 SUSPEND_PAGINATION doesn&#8217;t take an argument.  Invoked
1809 immediately prior to
1810 <kbd><a href="#bibliography">BIBLIOGRAPHY</a></kbd>,
1811 it turns off pagination for the duration of the bibliography.  Mom
1812 continues, however to increment page numbers silently.
1813 </p>
1814
1815 <p>
1816 To restore normal document pagination after bibliographies, invoke
1817 <kbd>.RESTORE_PAGINATION</kbd> (again, with no argument) immediately
1818 after you&#8217;ve finished with your bibliography.
1819 </p>
1820
1821 <h4 id="biblio-header-control" class="docs" style="margin-bottom: .5em;">3. Header/footer control</h4>
1822
1823 <h5 id="biblio-modify-hdrftr" class="docs" style="margin-top: 0; margin-bottom: .5em; margin-left: .5em;">&bull;&nbsp;Modifying what goes in the bibliography header/footer</h5>
1824
1825 <p>
1826 If you wish to modify what appears in the header/footer that appears
1827 on bibliography pages, make the changes before you invoke
1828 <a href="#bibliography"><kbd>.BIBLIOGRAPHY</kbd></a>,
1829 not afterwards.
1830 </p>
1831
1832 <p>
1833 Except in the case of
1834 <a href="docprocessing.html#doctype">DOCTYPE <kbd>CHAPTER</kbd></a>,
1835 mom prints the same header or footer used throughout the document
1836 on bibliography pages.  Chapters get treated differently in that,
1837 by default, mom does not print the header/footer centre string
1838 (normally the chapter number or chapter title.)  In most cases, this
1839 is what you want.  However, should you not want mom to remove the
1840 centre string from the bibliography pages headers/footers, invoke
1841 <kbd><a href="#bibliography-hdrftr-center">.BIBLIOGRAPHY_HEADER_CENTER</a></kbd>
1842 with no argument.
1843 </p>
1844
1845 <p>
1846 An important change you may want to make is to put the word
1847 &#8220;Bibliography&#8221; in the header/footer centre position.  To
1848 do so, invoke
1849 <br/>
1850 <span class="pre-in-pp" style="margin-bottom: -1em;">
1851   .HEADER_CENTER "Bibliography"
1852 </span>
1853 or
1854 <span class="pre-in-pp" style="margin-top: -.5em;">
1855   .FOOTER_CENTER "Bibliography"
1856 </span>
1857 prior to invoking <kbd>.BIBLIOGRAPHY</kbd>.
1858 </p>
1859
1860 <div class="box-tip">
1861 <p class="tip">
1862 <span class="note">Note:</span>
1863 If your
1864 <a href="docprocessing.html#doctype">DOCTYPE</a>
1865 is <kbd>CHAPTER</kbd>, you must also invoke
1866 <a href="#endnotes-hdrftr-center">BIBLIOGRAPHY_HEADER_CENTER</a>
1867 for the BIBLIOGRAPHY_HEADER_CENTER to appear.
1868 </p>
1869 </div>
1870
1871 <h5 id="biblio-hdrftr-center" class="docs" style="margin-top: 0; margin-bottom: .5em; margin-left: .5em;">&bull;&nbsp;Header/footer centre string when doctype is CHAPTER</h5>
1872
1873 <div class="box-macro-args">
1874 Macro: <b>BIBLIOGRAPHY_HEADER_CENTER</b> <kbd class="macro-args">toggle</kbd>
1875 </div>
1876
1877 <p>
1878 If your
1879 <a href="docprocessing.html#doctype">DOCTYPE</a>
1880 is <kbd>CHAPTER</kbd> and you want mom to include a centre
1881 string in the headers/footers that appear on bibliography
1882 pages, invoke <kbd>.BIBLIOGRAPHY_HEADER_CENTER</kbd> (or
1883 <kbd>.BIBLIOGRAPHY_FOOTER_CENTER</kbd>) with no argument.
1884 Mom&#8217;s default is NOT to print the centre string.
1885 </p>
1886
1887 <p>
1888 If, for some reason, having enabled the header/footer centre string
1889 on bibliography pages, you wish to disable it, invoke the same macro
1890 with any argument (<kbd>OFF, QUIT, Q, X</kbd>...).
1891 </p>
1892
1893 <h5 id="biblio-allows-headers" class="docs" style="margin-top: -.5em; margin-bottom: .5em; margin-left: .5em;">&bull;&nbsp;Allow headers on bibliography pages</h5>
1894
1895 <div class="box-macro-args">
1896 Macro: <b>BIBLIOGRAPHY_ALLOWS_HEADERS</b> <kbd class="macro-args">&lt;none&gt; | ALL</kbd>
1897 </div>
1898
1899 <p>
1900 By default, if HEADERS are on, mom prints page headers on all
1901 bibliography pages except the first.  If you don&#8217;t want her to
1902 print headers on bibliography pages, do
1903 <br/>
1904 <span class="pre-in-pp">
1905   .BIBLIOGRAPHY_ALLOWS_HEADERS OFF
1906 </span>
1907 If you want headers on every page including the first, do
1908 <br/>
1909 <span class="pre-in-pp">
1910   .BIBLIOGRAPHY_ALLOWS_HEADERS ALL
1911 </span>
1912 </p>
1913
1914 <div class="box-tip">
1915 <p class="tip">
1916 <span class="note">Note:</span>
1917 If FOOTERS are on, mom prints footers on every bibliography page.
1918 This is a style convention.  In mom, there is no such beast as
1919 BIBLIOGRAPHY_ALLOWS_FOOTERS OFF.
1920 </p>
1921 </div>
1922
1923 <h4 id="biblio-main-title" class="docs">4. Bibliography first-page title control</h4>
1924
1925 <!-- -BIBLIO_STRING- -->
1926
1927 <h5 id="biblio-string" class="docs" style="margin-top: 1em; margin-bottom: .5em; margin-left: .5em;">&bull;&nbsp;Title string</h5>
1928
1929 <div class="box-macro-args">
1930 Macro: <b>BIBLIOGRAPHY_STRING</b> <kbd class="macro-args">&quot;&lt;title to print at the top of bibliography pages&gt;&quot;</kbd>
1931 </div>
1932
1933 <p>
1934 By default, mom prints the word &#8220;BIBLIOGRAPHY&#8221; as a title
1935 at the top of the first page of a bibliography.  If you want her to
1936 print something else, invoke <kbd>.BIBLIOGRAPHY_STRING</kbd> with
1937 the title you want, surrounded by double-quotes.
1938 </p>
1939
1940 <p>
1941 If you don&#8217;t want a title at the top of the first bibliography
1942 page, invoke <kbd>.BIBLIOGRAPHY_STRING</kbd> with a blank argument
1943 (either two double-quotes side by
1944 side&mdash;<kbd>&quot;&quot;</kbd>&mdash;or no argument at all).
1945 </p>
1946
1947 <!-- -BIBLIO_STRING_CONTROL- -->
1948
1949 <h5 id="biblio-string-control" class="docs" style="margin-top: -.5em; margin-bottom: .5em; margin-left: .5em;">&bull;&nbsp;Title string control macros and defaults</h5>
1950
1951 <div class="defaults-container" style="padding-bottom: 8px;">
1952 <p class="defaults" style="padding-top: 6px;">
1953 See
1954 <a href="#control-macro-args">Arguments to the control macros</a>.
1955 </p>
1956 <span class="pre defaults">
1957 .BIBLIOGRAPHY_STRING_FAMILY  default = prevailing document family; default is Times Roman
1958 .BIBLIOGRAPHY_STRING_FONT    default = bold
1959 .BIBLIOGRAPHY_STRING_SIZE*   default = +1
1960 .BIBLIOGRAPHY_STRING_QUAD    default = centred
1961
1962 *Relative to the size of the bibliography text (set with BIBLIOGRAPHY_PT_SIZE)
1963 </span>
1964 </div>
1965
1966 <!-- -BIBLIOGRAPHY_STRING_ADVANCE- -->
1967
1968 <h5 id="biblio-string-placement" class="docs" style="margin-top: -1em; margin-bottom: .5em; margin-left: .5em;">&bull;&nbsp;Title string placement</h5>
1969
1970 <div class="box-macro-args">
1971 Macro: <b>BIBLIOGRAPHY_STRING_ADVANCE</b> <kbd class="macro-args">&lt;distance from top of page&gt;</kbd>
1972 </div>
1973
1974 <p class="requires">
1975 &bull;&nbsp;Argument requires a <a href="definitions.html#unitofmeasure">unit of measure</a>
1976 </p>
1977
1978 <p>
1979 By default, mom places the title (the docheader, as it were) of
1980 bibliographies (typically "BIBLIOGRAPHY") on the same
1981 <a href="definitions.html#baseline">baseline</a>
1982 that is used for the start of
1983 <a href="definitions.html#running">running text</a>.
1984 If you&#8217;d prefer another location, higher or lower on the page
1985 (thereby also raising or lowering the starting position of the
1986 bibliography itself), invoke <kbd>.BIBLIOGRAPHY_STRING_ADVANCE</kbd>
1987 with an argument stating the distance from the top edge of the page
1988 at which you&#8217;d like the title placed.
1989 </p>
1990
1991 <p>
1992 The argument requires a unit of measure, so if you&#8217;d like the title
1993 to appear 1-1/2 inches from the top edge of the page, you&#8217;d tell
1994 mom about it like this:
1995 <br/>
1996 <span class="pre-in-pp">
1997   .BIBLIOGRAPHY_STRING_ADVANCE 1.5i
1998 </span>
1999 </p>
2000
2001 <!-- -BIBLIO_STRING_UNDERLINE- -->
2002
2003 <h5 id="biblio-string-underline" class="docs" style="margin-top: -1em; margin-bottom: .5em; margin-left: .5em;">&bull;&nbsp;Title string underscoring</h5>
2004
2005 <div class="box-macro-args">
2006 Macro: <b>BIBLIOGRAPHY_STRING_UNDERSCORE</b> <kbd class="macro-args">[DOUBLE] [&lt;underline weight&gt; [&lt;underline gap&gt; [&lt;distance between double rules]]] | &lt;none&gt; | &lt;anything&gt;</kbd>
2007 </div>
2008
2009 <p class="alias" style="margin-bottom: 0;">
2010 <i>Alias:</i> <b>BIBLIOGRAPHY_STRING_UNDERLINE</b>
2011 </p>
2012
2013 <p class="requires">
2014 &bull;&nbsp;The argument
2015 <span style="font-style: normal"><kbd>&lt;underscore weight&gt;</kbd></span>
2016 must not have the
2017 <a href="definitions.html#unitofmeasure">unit of measure</a>,
2018 <span style="font-style: normal;"><kbd>p</kbd></span>, appended to it
2019 </p>
2020
2021 <p>
2022 Invoked without an argument,
2023 <kbd>.BIBLIOGRAPHY_STRING_UNDERSCORE</kbd> will place a single rule
2024 underneath the bibliography&#8217;s first-page title.  Invoked with the
2025 argument, <kbd>DOUBLE</kbd>, BIBLIOGRAPHY_STRING_UNDERSCORE will
2026 double-underscore the title.  Invoked with any other non-numeric
2027 argument, (eg <kbd>OFF, NO, X</kbd>, etc.) the macro disables
2028 underlining of the title.
2029 </p>
2030
2031 <p>
2032 In addition, you can use BIBLIOGRAPHY_STRING_UNDERSCORE to control
2033 the weight of the underscore rule(s), the gap between the title and
2034 the underscore, and, in the case of double-underscores, the distance
2035 between the two rules.
2036 </p>
2037
2038 <p>
2039 Some examples:
2040 <br/>
2041 <span class="pre-in-pp">
2042   .BIBLIOGRAPHY_STRING_UNDERLINE 1
2043       - turn underlining on; set the rule weight to 1 point
2044
2045   .BIBLIOGRAPHY_STRING_UNDERLINE 1 3p
2046       - turn underlining on; set the rule weight to 1 point; set
2047         the gap between the string and the underline to 3 points
2048
2049   .BIBLIOGRAPHY_STRING_UNDERLINE DOUBLE .75 3p
2050       - turn double-underlining on; set the rule weight to 3/4 of
2051         a point; set the gap between the string and the upper
2052         underline to 3 points; leave the gap between the upper
2053         and the lower underline at the default
2054
2055   .BIBLIOGRAPHY_STRING_UNDERLINE DOUBLE 1.5 1.5p 1.5p
2056       - turn double-underlining on; set the rule weight to 1-1/2
2057         points; set the gap between the string and the upper
2058         underline to 1-1/2 points; set the gap between the upper
2059         and the lower underline to 1-1/2 points
2060 </span>
2061 Note, from the above, that in all instances, underscoring (single or
2062 double) is enabled whenever BIBLIOGRAPHY_STRING_UNDERSCORE is used
2063 in this way.
2064 </p>
2065
2066 <p>
2067 Mom&#8217;s default is to double-underscore the title with 1/2-point
2068 rules placed 2 points apart and 2 points below the baseline of the
2069 title.
2070 </p>
2071
2072 <!-- -BIBLIO_STRING_CAPS- -->
2073
2074 <h5 id="biblio-string-caps" class="docs" style="margin-top: -.5em; margin-bottom: .5em; margin-left: .5em;">&bull;&nbsp;Title string capitalization</h5>
2075
2076 <div class="box-macro-args">
2077 Macro: <b>BIBLIOGRAPHY_STRING_CAPS</b> <kbd class="macro-args">toggle</kbd>
2078 </div>
2079
2080 <p>
2081 Invoked by itself, <kbd>.BIBLIOGRAPHY_STRING_CAPS</kbd> will
2082 automatically capitalize the bibliography first-page title.  Invoked
2083 with any other argument, the macro disables automatic capitalization
2084 of the title.
2085 </p>
2086
2087 <p>
2088 If you&#8217;re generating a table of contents, you may want the
2089 bibliography first-page title to be in caps, but the toc entry in
2090 caps/lower case.  If the argument to
2091 <kbd><a href="#bibliography-string">BIBLIOGRAPHY_STRING</a></kbd>
2092 is in caps/lower case and BIBLIOGRAPHY_STRING_CAPS is
2093 on, this is exactly what will happen.
2094 </p>
2095
2096 <p>
2097 Mom&#8217;s default is to capitalize the bibliography first-page
2098 title.
2099 </p>
2100
2101 <div class="rule-long"><hr/></div>
2102
2103 <!-- Navigation links -->
2104 <table style="width: 100%; margin-top: 12px;">
2105 <tr>
2106   <td style="width: 33%;"><a href="toc.html">Back to Table of Contents</a></td>
2107   <td style="width: 33%; text-align: center;"><a href="#top">Top</a></td>
2108   <td style="width: 33%; text-align: right;"><a href="letters.html">Next: Writing letters</a></td>
2109 </tr>
2110 </table>
2111
2112 </div>
2113
2114 <div class="bottom-spacer"><br/></div>
2115
2116 </body>
2117 </html>
2118 <!-- vim: fileencoding=utf-8: nomodified: -->