PageRenderTime 54ms CodeModel.GetById 13ms RepoModel.GetById 0ms app.codeStats 1ms

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

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