diff options
| author | PTPi <PTPi> | 2013-08-12 04:40:10 +0000 |
|---|---|---|
| committer | PTPi <PTPi> | 2013-08-12 04:40:10 +0000 |
| commit | 81835ed1b827ee9ea3f47a3a1ba78076c783ec6c (patch) | |
| tree | 194cec30b7be30045f428e73440c346922e147b2 | |
| parent | ebbeb4daa971421b3265dce68687b9cbf3fe3b0f (diff) | |
| download | groff-81835ed1b827ee9ea3f47a3a1ba78076c783ec6c.tar.gz | |
Updated documentation concerning refer usage.
| -rw-r--r-- | contrib/mom/ChangeLog | 6 | ||||
| -rw-r--r-- | contrib/mom/momdoc/refer.html | 455 | ||||
| -rw-r--r-- | contrib/mom/momdoc/toc.html | 2 | ||||
| -rw-r--r-- | contrib/mom/om.tmac | 38 |
4 files changed, 276 insertions, 225 deletions
diff --git a/contrib/mom/ChangeLog b/contrib/mom/ChangeLog index 67b1fd22..0410012e 100644 --- a/contrib/mom/ChangeLog +++ b/contrib/mom/ChangeLog @@ -1,3 +1,9 @@ +* Sun Aug 11 2013 + +o Updated documentation concerning refer usage + +o Replaced REF_STYLE and REF<bracket-style> macros with warnings. + * Wed Jun 19 2013 o groff_mom.man: Fix inappropriate use of .UR/.UE. diff --git a/contrib/mom/momdoc/refer.html b/contrib/mom/momdoc/refer.html index d7f7eead..e971c954 100644 --- a/contrib/mom/momdoc/refer.html +++ b/contrib/mom/momdoc/refer.html @@ -48,15 +48,17 @@ FDL in the main directory of the groff source package. <ul style="margin-left: -.5em; list-style-type: disc;"> <li><a href="#db-ref">Create a <kbd>refer</kbd> database</a></li> <li><a href="#rcommands-ref">Insert a <kbd>refer</kbd> block</a></li> - <li><a href="#placement-ref">Tell mom where you want your references (footnotes/endnotes or a bibliography)</a></li> + <li><a href="#placement-ref">Tell mom where you want your references (if footnotes or endnotes)</a></li> <li><a href="#accessing-ref">Accessing references in the database</a></li> <li><a href="#fn-en-recipe">Entering footnote/endnote references</a></li> - <li><a href="#bibliography-recipe">Creating a bibliography</a></li> + <li><a href="#parenthetical">Parenthetical insertions</a></li> + <li><a href="#bibliography-from-embedded">Generating a bibliography from parenthetical insertions</h4></a></li> + <li><a href="#bibliography-recipe">Generating a comprehensive bibliography</a></li> <li><a href="#invoking-ref">Invoking groff with mom and <kbd>refer</kbd></a></li> </ul></li> <li><a href="#mla">MLA (Modern Language Association) style</a> <ul style="margin-left: -.5em; list-style-type: disc;"> - <li><a href="#ref-styles">Types of references (endnote/footnote or bibliographic)</a></li> + <li><a href="#ref-styles">Types of references (endnote, footnote, or embedded in text)</a></li> <li><a href="#parenthetical">Inserting parenthetical references into the text</a></li> </ul></li> <li><a href="#database">The <kbd>refer</kbd> database</a> @@ -143,12 +145,15 @@ or any other website or reference book on MLA style. <li><a href="#rcommands-ref">Insert a <kbd>refer</kbd> block</a> <ul style="margin-left: -.5em; list-style-type: disc;"> <li><a href="#fn-en-block">refer block for footnotes/endnotes</a></li> - <li><a href="#bibliography-block">refer block for bibliographies</a></li> + <li><a href="#in-text-block">refer block for parenthetical insertions into running text</a></li> + <li><a href="#bibliography-block">refer block for comprehensive bibliographies (reading lists)</a></li> </ul></li> - <li><a href="#placement-ref">Tell mom where you want your references (footnotes/endnotes or a bibliography)</a></li> + <li><a href="#placement-ref">Tell mom where you want your references (if footnotes or endnotes)</a></li> <li><a href="#accessing-ref">Accessing references in the database</a></li> <li><a href="#fn-en-recipe">Entering footnote/endnote references</a></li> - <li><a href="#bibliography-recipe">Creating a bibliography</a></li> + <li><a href="#parenthetical-insertions">Parenthetical insertions</a></li> + <li><a href="#bibliography-from-embedded">Generating a bibliography from parenthetical insertions</a></li> + <li><a href="#bibliography-recipe">Generating a comprehensive bibliography</a></li> <li><a href="#invoking-ref">Invoking groff with mom and <kbd>refer</kbd></a></li> </ol> @@ -219,10 +224,14 @@ containing <kbd>.R2</kbd>. What goes between the <kbd>.R1</kbd> and <kbd>.R2</kbd> lines is called a “refer block”. <kbd>Refer</kbd> commands in a refer block should be entered one per line, in lowercase letters, <i>with no initial period</i> (dot). -The specific commands, and the placement of the block, depend on -whether you want your references in footnotes/endnotes or in a -bibliography. +The actual commands depend on whether you want your references </p> +<ul> +<li>in footnotes/endnotes</li> +<li>parenthetically inserted (in abbreviated form) into running text, +referring to a works-cited list (bibliography)</li> +<li>to generate a comprehensive bibliography (a reading list)</li> +</ul> <h5 id="fn-en-block" class="docs" style="font-size: 90%; margin-top: .25em;">Refer block for footnotes/endnotes</h5> @@ -249,11 +258,42 @@ means the full path including the filename, eg <kbd>/home/user/refer/my-database-file</kbd>. </p> -<h5 id="bibliography-block" class="docs" style="font-size: 90%; margin-top: .25em;">Refer block for bibliographies</h5> +<h5 id="in-text-block" class="docs" style="font-size: 90%; margin-top: .25em;">Refer block for parenthetical insertions into running text</h5> <p style="margin-top: .5em;"> -If you want a bibliography, place this block at the <i>bottom</i> of -your mom file, either prior to or immediately after invoking +If you want short, parenthetical insertions into running text, +referring to works cited in a bibliography, place this block at +the <i>top</i> of your mom file. +</p> + +<div id="refer-block2" class="examples" style="margin-top: -.5em;"> +<div class="examples-container" style="padding-bottom: 1em;"> +<span class="pre"> +.R1 +label "(A.n|Q)" +bracket-label " (" ")" ", " +join-authors ", and " ", " ", and " +move-punctuation +reverse A1 +sort A1Q1T1B1E1 +database <full path to database> +.R2 +</span> +</div> +</div> +<p style="margin-top: .5em; font-size: 95%; line-height: 120%;"> +<kbd><full path to the database></kbd> +means the full path including the filename, eg +<kbd>/home/user/refer/my-database-file</kbd>. +</p> + +<h5 id="bibliography-block" class="docs" style="font-size: 90%; margin-top: .25em;">Refer block for comprehensive bibliographies</h5> + +<p style="margin-top: .5em;"> +If you want to output an entire <kbd>refer</kbd> database, or +generate a comprehensive bibliography (a reading list) from a +database, place this block at the <i>bottom</i> of your mom file, +either prior to or immediately after invoking <a href="#bibliography">BIBLIOGRAPHY</a>. </p> @@ -278,12 +318,7 @@ means the full path including the filename, eg <kbd>/home/user/refer/my-database</kbd>. </p> -<!-- Some sort of header saying "these blocks for these kinds of refs", followed - by en/fn block and bib block. Make embedded refs, and a discussion of why they're - not really a good idea, another section. ---> - -<h4 id="placement-ref" class="docs">3. Tell mom where you want your references (footnotes/endnotes or a bibliography)</h4> +<h4 id="placement-ref" class="docs">3. Tell mom where you want your references</h4> <p> If you want references in footnotes, issue the instruction @@ -291,7 +326,9 @@ If you want references in footnotes, issue the instruction <span class="pre-in-pp"> .FOOTNOTE_REFS </span> -anywhere before the first citation in your file. +anywhere before the first citation in your file. Footnote markers +will be inserted into the text, and the bibliographic information +for the citation will appear as a footnote. </p> <p> @@ -300,18 +337,25 @@ If you want references in endnotes, issue the instruction <span class="pre-in-pp"> .ENDNOTE_REFS </span> -anywhere before the first citation in your file. +anywhere before the first citation in your file. Endnote markers +will be inserted into the text, and the bibliographic information +for the citation will appear as an endnote entry. </p> <p> -If you want your references in a bibliography, issue the instruction -<br/> -<span class="pre-in-pp"> - .BIBLIOGRAPHY -</span> -at the end of your file, before -<a href="tables-of-contents.html#TOC">TOC</a> -(Table of Contents). +Note that if you want references parenthetically inserted +into running text, referring to entries in a works-cited list +(bibliography) that <kbd>mom</kbd> and <kbd>refer</kbd> assemble +automatically, no special instructions are required. See +<a href="#bibliography-from-embedded">Generating a bibliography from parenthetical insertions</a> +for how to output the collected references. +</p> + +<p> +For outputting an entire <kbd>refer</kbd> database, or +generating a comprehensive reading list from a database, see the +macro, +<a href="#bibliography">BIBLIOGRAPHY</a>. </p> <h4 id="accessing-ref" class="docs">4. Accessing references in the database</h4> @@ -373,7 +417,7 @@ command, entering references is done like this: If FOOTNOTE_REFS is in effect, the reference between the first and second <kbd>.REF</kbd> will be treated as a footnote. If ENDNOTE_REFS, it will be treated as an endnote. Endnote references -must be explictly output with +must be explicitly output with <a href="docelement.html#ENDNOTES">ENDNOTES</a> at the end of your file, before <a href="tables-of-contents.html#TOC">TOC</a>. @@ -394,26 +438,48 @@ ENDNOTE). </p> </div> -<h4 id="bibliography-recipe" class="docs">6. Creating a bibliography</h4> +<h4 id="parenthetical-insertions" class="docs">6. Parenthetical insertions</h4> <p> -Bibliographic references come between +See +<a href="#parenthetical">Inserting parenthetical references into +text</a>. +</p> + +<h4 id="bibliography-from-embedded" class="docs">7. Generating a bibliography from parenthetical insertions</h4> + +<p> +To generate a bibliography from works cited by parenthetical +insertions in the text, put this at the end of your document, before +<kbd><a href="tables-of-contest.html#TOC">.TOC</a></kbd>. +<br/> +<span class="pre-in-pp"> + .BIBLIOGRAPHY + .[ + $LIST$ + .] + .BIBLIOGRAPHY OFF +</span> +</p> + +<h4 id="bibliography-recipe" class="docs">8. Generating a comprehensive bibliography</h4> + +<p> +You can also generate a comprehensive bibliography, which is to say a +bibliography containing more works than are actually cited (a +“reading list”), by placing references between <kbd><a href="#bibliography">.BIBLIOGRAPHY</a></kbd> and <kbd><a href="#bibliography">.BIBLIOGRAPHY OFF</a></kbd>. -They require no <kbd>.REF</kbd>’s surrounding the - <kbd>.[</kbd> and <kbd>.]</kbd> commands. -Once you have input the desired references, issue the -following, exactly as shown: +Once you have input the desired references, insert <br/> <span class="pre-in-pp"> .[ $LIST$ .] </span> -and follow it with <kbd>.BIBLIOGRAPHY OFF</kbd>. -Study the example provided below if you’re having trouble -visualizing this. +and follow it with <kbd>.BIBLIOGRAPHY OFF</kbd>. Study the +example below if you’re having trouble visualizing this. </p> <div id="example-bibliography" class="examples" style="margin-top: -.5em;">Example bibliography</div> @@ -442,9 +508,9 @@ $LIST$ </div> <p> -Alternatively, if you wish to output your entire database as a -bibliography, do the following at the end of your document, before -<kbd><a href="tables-of-contest.html#TOC">.TOC</a></kbd>: +Alternatively, you can output an entire database as a +bibliography. Do the following at the end of your document, before +<kbd><a href="tables-of-contest.html#TOC">.TOC</a></kbd>. <br/> <span class="pre-in-pp"> .BIBLIOGRAPHY @@ -460,7 +526,7 @@ bibliography, do the following at the end of your document, before </span> </p> -<h4 id="invoking-ref" class="docs">7. Invoking groff with mom and refer</h4> +<h4 id="invoking-ref" class="docs">9. Invoking groff with mom and refer</h4> <p> So, now you’ve got a document formatted properly to use @@ -484,14 +550,14 @@ invoke groff with the <kbd>-R</kbd> option as well, like this: <h2 id="mla" class="docs">MLA (Modern Language Association) style</h2> -<h3 id="ref-styles" class="docs">Types of references (endnote/footnote or bibliographic)</h3> +<h3 id="ref-styles" class="docs">Types of references (endnote, footnote, or embedded in text)</h3> <p> MLA allows for three types of references, or referencing styles: </p> <ul style="margin-top: -.5em;"> - <li>short, parenthetical references in the text, linked to a list - of works cited (a bibliography) at the end of the document</li> + <li>short, parenthetical references in the text, linked to a + works-cited list (bibliography) at the end of the document</li> <li>footnote references</li> <li>endnote references</li> </ul> @@ -513,61 +579,138 @@ entering any other kind of <a href="docelement.html#footnote-into">footnote</a> or <a href="docelement.html#endnote-into">endnote</a>. -Parenthetical references linked to a bibliography, however, need to -be handled differently. +Parenthetical references, however, need to be handled differently. +See the next section. </p> <h3 id="parenthetical" class="docs">Inserting parenthetical references into the text</h3> <p> MLA style prefers restricting the information in parenthetical -references to the barest minimum needed to find the cited work in -the bibliography. Human judgment is usually required, therefore -it is generally best to enter the parenthetical references by hand -rather than asking mom and <kbd>refer</kbd> to generate them. While -the latter is possible with the macro pair, -<kbd><a href="#bracket-refs-parens">.REF(</a> /<a href="#bracket-refs-parens">.REF)</a></kbd>, -it requires more work to set up your -<a href="#db-ref">database</a> -and interrupts the flow of your input file. Consider these two -examples, which accomplish exactly the same thing: -</p> -<div class="examples-container" style="padding-bottom: .25em;"> +references to the barest minimum needed to identify works +in the works-cited list (the bibliography). Typically, a +parenthetical insertion is just the author’s last name +followed by the page number of the cited work (if only one work by +that author is cited), or by the author, a shortened title of the +work, and the page number (if more than one work is cited). +</p> + +<p> +This necessitates a slightly fiddly way of entering parenthetical +references, though not by any means difficult or hard to make sense +of. +</p> + +<p> +The <kbd>refer</kbd> block suggested +<a href="#refer-block2">here</a> +for parenthetical references prints only the author’s +last name from the database record identified by your keywords +(the <kbd>label</kbd> command), surrounded by parentheses (the +<kbd>bracket-label</kbd> command). Therefore, assuming you are +citing Ray Bradbury’s <i>The Martian Chronicles</i>, and it is +the only work by Bradbury mentioned in the text, +<br/> <span class="pre-in-pp"> - Ancient writers attributed the invention of the monochord - to Pythagoras, who lived in the sixth century BC (Marcuse, - \*[IT]Survey\*[ROM] 197). Marcone, however, discovered - precursors of the instrument dating at least two centuries - earlier (\*[IT]Plectrum\*[ROM] 98). + ...end of sentence. + .[ + martian chronicles + .] + A new sentence... </span> -</div> -<span style="display: inline-block; padding-top: .5em; padding-bottom: .5em;">versus</span> -<div class="examples-container" style="padding-bottom: .25em;"> +will insert “<span style="font-family: times; font-size: 105%; font-weight: bold">...end of sentence (Bradbury). A new sentence...</span>” into the text. +<i>The Martian Chronicles</i> will be added +to the works-cited list generated at the end of the document if it +is not already present as the result of an earlier reference. +</p> + +<p> +If you need a page number to identify where in <i>The Martian +Chronicles</i> to find a specific quote +<br/> <span class="pre-in-pp"> - Ancient writers attributed the invention of the monochord - to Pythagoras, who lived in the sixth century BC - .REF( + "...aluminum roaches and iron crickets." .[ - survey - %P 197 - .] - .REF) - . Marcone, however, discovered precursors of the instrument - dating at least two centuries earlier - .REF( + [ martian chronicles + .] 168) + A new sentence... +</span> +results in “<span style="font-family: times; font-size: 105%; font-weight: bold">“...aluminum roaches and iron crickets.” (Bradbury 168) A new sentence...</span>” +(which is excruciatingly correct MLA style). The +“<kbd>[</kbd>” before <kbd>martian chronicles</kbd> tells +refer to print the opening parenthesis; any text immediately +following the “<kbd>.]</kbd>”, including spaces, +<i>replaces</i> the closing parenthesis. (Notice that you have to +add the closing parenthesis yourself after the page number.) +</p> + +<p> +If your document cites more than one work by Bradbury and you need +a title and page number in addition to the author's name in the +inline reference, +<br/> +<span class="pre-in-pp"> + "...aluminum roaches and iron crickets." .[ - plectrum - %P 98 - .] - .REF) - . + [ bradbury martian + .], \fIChronicles\fP 168) + A new sentence... </span> -</div> +will produce “<span style="font-family: times; font-size: 105%; font-weight: bold">“...aluminum roaches and iron crickets.” (Bradbury, <i>Chronicles</i> 168) A new sentence...”</span>”. +</p> + +<div class="examples-container" style="margin-top: 1.5em; margin-bottom: 1.5em;"> +<h3 id="tutorial-ref" class="docs">The <span style="text-transform: none">‘label’<span style="text-transform: uppercase"> and <span style="text-transform: none">‘bracket-label’<span style="text-transform: uppercase"> commands</h3> <p> -Clearly, the first example takes less work, and is much easier to read. +The <kbd>label</kbd> and <kbd>bracket-label</kbd> commands in +the refer block allow you to customize what information goes +into parenthetical references, and how they should be formatted. +<kbd>label</kbd> dictates which fields from the database record +to print and how to punctuate them. <kbd>bracket-label</kbd> +controls the bracketing style. Users are encouraged to consult +<kbd>man refer</kbd> for usage. </p> +<p> +Here’s an example of how to set up APA-style references, which +require the author and date of publication, optionally with a page +number or range of pages. +<br/> +<span class="pre-in-pp"> + .R1 + label "(A.n|Q) ', ' D.y" + bracket-label " (" ")" ", " + join-authors ", and " ", " ", and " + move-punctuation + reverse A1 + sort A1Q1T1B1E1 + database /home/peter/Groff-mom/Testing/Refer/refer-database + .R2 +</span> +Assuming a reference to a work by Ursula Leguin published in 1980 +<br/> +<span class="pre-in-pp"> + .[ + leguin + .] +</span> +produces +<span style="font-family: times; font-size: 105%; font-weight: bold"> +(Leguin, 1980) +</span>. +If a page number is also required +<br/> +<span class="pre-in-pp"> + .[ + [ leguin + .], p. 73) +</span> +produces +<span style="font-family: times; font-size: 105%; font-weight: bold">(Leguin, 1980, p. 73)</span>. +</p> +</div> + <div class="rule-medium" style="margin-top: 1em;"><hr/></div> <h2 id="database" class="docs">The refer database</h2> @@ -935,17 +1078,9 @@ for footnotes/endnotes) the first. <div class="macro-list-container"> <h3 id="index-ref" class="macro-list">The bibliography and reference macros</h3> <ul class="macro-list"> - <li><a href="#ref">REF</a> – begin/end a <kbd>refer</kbd> reference</li> + <li><a href="#ref">REF</a> – begin/end a <kbd>refer</kbd> reference that will go in a footnote or endnote</li> <li><a href="#footnote-refs">FOOTNOTE_REFS</a> – instruct mom to put REFs in footnotes</li> <li><a href="#endnote-refs">ENDNOTE_REFS</a> – instruct mom to put REFs in endnotes</li> - <li><a href="#bracket-refs">Embed references in the text</a> - <ul style="margin-left: -.5em;"> - <li><a href="#bracket-refs-parens">REF(</a> – embed a reference in the text between parentheses</li> - <li><a href="#bracket-refs-brackets">REF[</a> – embed a reference in the text between square brackets</li> - <li><a href="#bracket-refs-braces">REF{</a> – embed a reference in the text between braces</li> - <li><a href="#bracket-refs-angle">REF<</a> – embed a reference in the text between angle brackets</li> - <li><a href="#refs-style">REF_STYLE</a> – bibliography or footnote/endnote</li> - </ul></li> <li><a href="#indent-refs">INDENT_REFS</a> – manage indenting of references, per MLA standards</li> <li><a href="#hyphenate-refs">HYPHENATE_REFS</a> – enable/disable hyphenation of references</li> <li><a href="#bibliography">BIBLIOGRAPHY</a> – begin a bibliography</li> @@ -957,7 +1092,7 @@ for footnotes/endnotes) the first. <!-- -REF- --> <div class="macro-id-overline"> -<h3 id="ref" class="macro-id">Begin/end a <kbd style="text-transform: none;">refer</kbd> reference</h3> +<h3 id="ref" class="macro-id">Begin/end a reference that goes in a footnote or endnote</h3> </div> <div class="box-macro-args"> @@ -966,18 +1101,17 @@ Macro: <b>REF</b> <p> The macro, REF, tells mom that what follows is -<kbd>refer</kbd>-specific, a keyword-identified reference from a -<kbd>refer</kbd> database. Depending on whether you’ve issued +<kbd>refer</kbd>-specific, a keyword-identified reference to a +<kbd>refer</kbd> database record. Depending on whether you’ve issued a <kbd><a href="#footnote-refs">.FOOTNOTE_REFS</a></kbd> or <kbd><a href="#endnote-refs">.ENDNOTE_REFS</a></kbd> -instruction, REF also tells mom where to place the reference. If -FOOTNOTE_REFS, the reference will be formatted and placed in a -footnote. If ENDNOTE_REFS, the reference will be collected for -output as an endnote. If you have issued neither instruction, the -reference will be collected for later output, most likely in a -<a href="#bibliography">bibliography</a>. +instruction, the reference will be formatted and placed in a +footnote, or collected for output in the endnotes. Parenthetical +insertion of references into the text do not require +<kbd>.REF</kbd> (see +<a href="#parenthetical">Inserting parenthetical references into the text</a>.) </p> <p> @@ -1031,11 +1165,7 @@ same arguments used to indent footnotes. See <p class="tip-bottom"> <span class="additional-note">Additional note:</span> -When REF is used with -<a href="#footnote-refs">FOOTNOTE_REFS</a> -or -<a href="#endnote-refs">ENDNOTE_REFS</a>, -it behaves identically to +REF behaves identically to <a href="docelement.html#footnote">FOOTNOTE</a> or <a href="docelement.html#footnote">ENDNOTE</a>, @@ -1043,7 +1173,8 @@ so please read the HYPER IMPORTANT NOTE found in the document entry for <a href="docelement.html#footnote-note">FOOTNOTE</a> and/or -<a href="docelement.html#endnote-note">ENDNOTE</a>. +<a href="docelement.html#endnote-note">ENDNOTE</a> +for instructions on correct entry of text preceding and following REF. </p> </div> @@ -1123,82 +1254,6 @@ You may switch between ENDNOTE_REFS and at any time. </p> -<!-- -BRACKET_REFS- --> - -<div class="macro-id-overline"> -<h3 id="bracket-refs" class="macro-id">Embed references in the text</h3> -</div> - -<div id="bracket-refs-parens" class="box-macro-args"> -Macro pair: <b>REF(</b> ... <b>REF)</b> -</div> - -<div id="bracket-refs-brackets" class="box-macro-args" style="margin-top: 1em;"> -Macro pair: <b>REF[</b> ... <b>REF]</b> -</div> - -<div id="bracket-refs-braces" class="box-macro-args" style="margin-top: 1em;"> -Macro pair: <b>REF{</b> ... <b>REF}</b> -</div> - -<div id="bracket-refs-angle" class="box-macro-args" style="margin-top: 1em;"> -Macro pair: <b>REF<</b> ... <b>REF></b> -</div> - -<p> -You may sometimes want to embed fairly complete references directly -into the body of your document, typically, but not always, inside -parentheses. An instance where this might be desirable would be -when there are one or two citations in a document where footnotes or -endnotes are inappropriate, and a bibliography just plain silly (as -it would be for just one or two citations). -</p> - -<p> -Mom allows you to embed references from your database directly into -documents through the use of the REF<bracket type> -macros. -</p> - -<p> -All four macro pairs, above, are invoked the same way, namely -by introducing the reference with the first (“open”) -macro of the REF<bracket type> -pair, and terminating it with the second (“close”) -REF<bracket type> of the pair. For -example -<br/> -<span class="pre-in-pp"> - .REF( - .[ - keyword(s) - .] - .REF) -</span> -will embed a reference in the body of your document, surrounded -by parentheses. <kbd>.REF[</kbd> / <kbd>.REF]</kbd> -will surround the reference with square brackets, etc. -</p> - -<h3 id="ref-style" class="docs">REF_STYLE</h3> - -<p> -When embedding references in the body of text, you’ll need to -tell mom which formatting style to use: footnote/endnote or -bibliography. Footnote/endnote referencing style uses no periods -between fields, only proper nouns and titles are capitalized, and -publication data is enclosed in parentheses. Bibliography -referencing style separates each field with a period, every -field begins with a capital letter, and publication data is not in -parentheses. -</p> - -<p> -If you want footnote/endnote style, invoke -<kbd>.REF_STYLE NOTE</kbd>. If you want bibliographic style, -invoke <kbd>.REF_STYLE BIBLIO</kbd>. -</p> - <!-- -INDENT_REFS- --> <div class="macro-id-overline"> @@ -1228,11 +1283,11 @@ second and subsequent lines in bibliographies. <p> By default, the indent for all three types of references is 1/2-inch for -<a href="docprocessing.html#printstyle">PRINSTYLE <kbd>TYPEWRITE</kbd></a> +<a href="docprocessing.html#printstyle">PRINTSTYLE <kbd>TYPEWRITE</kbd></a> and 2 <a href="definitions.html#em">ems</a> for -<a href="docprocessing.html#printstyle">PRINSTYLE <kbd>TYPESET</kbd></a>. +<a href="docprocessing.html#printstyle">PRINTSTYLE <kbd>TYPESET</kbd></a>. </p> <p> @@ -1327,9 +1382,7 @@ in the tutorial for an example.) <div class="box-tip"> <p class="tip"> <span class="note">Note:</span> -References embedded in the body of a document with -<kbd><a href="#bracket-refs">.REF <bracket type></a></kbd> -are considered part of +References embedded in the body of a document are considered part of <a href="definitions.html#running">running text</a>, and are hyphenated (or not) according to whether hyphenation is turned on or off for running text. Therefore, if you want to @@ -1340,11 +1393,9 @@ like this: <br/> <span class="pre-in-pp"> .HY OFF - .REF( .[ keyword(s) .] - .REF) .HY </span> Alternatively, sprinkle your database fields liberally with @@ -1363,12 +1414,16 @@ Macro: <b>BIBLIOGRAPHY</b> <kbd class="marco-args">toggle</kbd> </div> <p> -If you want to append a bibliography to your document, all you need +To append a bibliography to your document, whether of references +inserted parenthetically into text or a comprehensive reading list +derived from a large <kbd>refer</kbd> database, all you need do is invoke <kbd>.BIBLIOGRAPHY</kbd>. <kbd>.BIBLIOGRAPHY</kbd> breaks to a new page, prints the title (BIBLIOGRAPHY by default, but that can be changed), and awaits <kbd>refer</kbd> instructions. How to create bibliographies is covered in the tutorial section, -<a href="#bibliography-recipe">Creating bibliography pages</a>. +<a href="#bibliography-from-embedded">Generating a bibliography from parenthetical insertions</a> +and +<a href="#bibliography-recipe">Generating a comprehensive bibliography</a>. When all the required data has been entered, type <br/> <span class="pre-in-pp"> @@ -1410,11 +1465,11 @@ equivalent arguments to <p> You may enter the BIBLIOGRAPHY_TYPE either before or after -<kbd>.BIBLIOGRAPHY</kbd>. It must, however, always come before -the <kbd>refer</kbd> command to output bibliographies. (See the -tutorial section, -<a href="#biblio-ref">Creating bibliography pages</a>, -for instructions on how to output bibliographies.) +<kbd>.BIBLIOGRAPHY</kbd>. It must, however, always come before the +any <kbd>refer</kbd> commands. See +<a href="#bibliography-from-embedded">Generating a bibliography from parenthetical insertions</a> +and +<a href="#bibliography-recipe">Generating a comprehensive bibliography</a>. </p> <p> @@ -1918,7 +1973,7 @@ Macro: <b>BIBLIOGRAPHY_STRING_ADVANCE</b> <kbd class="macro-args"><distance f </div> <p class="requires"> -• Argument requires a <a href="definitions.html#unitofmeasure">unit of measusure</a> +• Argument requires a <a href="definitions.html#unitofmeasure">unit of measure</a> </p> <p> @@ -1969,7 +2024,7 @@ Invoked without an argument, <kbd>.BIBLIOGRAPHY_STRING_UNDERSCORE</kbd> will place a single rule underneath the bibliography’s first-page title. Invoked with the argument, <kbd>DOUBLE</kbd>, BIBLIOGRAPHY_STRING_UNDERSCORE will -double-underscore the thtile. Invoked with any other non-numeric +double-underscore the title. Invoked with any other non-numeric argument, (eg <kbd>OFF, NO, X</kbd>, etc.) the macro disables underlining of the title. </p> diff --git a/contrib/mom/momdoc/toc.html b/contrib/mom/momdoc/toc.html index fcab30f9..bfc620a7 100644 --- a/contrib/mom/momdoc/toc.html +++ b/contrib/mom/momdoc/toc.html @@ -21,7 +21,7 @@ FDL in the main directory of the groff source package. <head> <meta http-equiv="content-type" content="text/html;charset=utf-8"/> - <title>Mom, version 2.0-a -- Table of Contents</title> + <title>Mom, version 2.0-a_1 -- Table of Contents</title> <link rel="stylesheet" type="text/css" href="stylesheet.css" /> </head> diff --git a/contrib/mom/om.tmac b/contrib/mom/om.tmac index 785c085d..5ece7fec 100644 --- a/contrib/mom/om.tmac +++ b/contrib/mom/om.tmac @@ -3,7 +3,7 @@ Mom -- a typesetting/document-processing macro set for groff. Copyright (C) 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, -2011, 2012 +2011, 2012, 2013 Free Software Foundation, Inc. Written by Peter Schaffter <peter@schaffter.ca> PDF integration contributed by Deri James <deri.james@chuzzlewit.co.uk> @@ -23,8 +23,8 @@ for more details. You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/>. -Version 2.0-a -------------- +Version 2.0-a_1 +--------------- Antoine de St-Exupéry asserted that elegance in engineering is achieved not when there is nothing left to add, but when there is nothing left to take away. @@ -14125,7 +14125,6 @@ E\\R'#CAP_HEIGHT \\n[.cht]' . ie '\\$1'' \{\ . rr #FN_REF . rr #EN_REF -. REF_STYLE BIBLIO . nr #BIBLIOGRAPHY 1 . nr #BIB_FIRST_PAGE 1 . nr #HEADER_STATE \\n[#HEADERS_ON] @@ -16818,27 +16817,19 @@ E\\R'#CAP_HEIGHT \\n[.cht]' \# Embedded references in text (with brackets) \# ------------------------------------------- \# +.MAC REF_BRACKETS_NOTICE END +. tm1 "[mom]: \\$1 has been removed from mom. See the mom documentation 'refer.html' +. tm1 " for instructions on parenthetical insertions of references into text. +. ie '\\$1'REF_STYLE' .tm1 " Continuing to process '\\n[.F]' from line \\n[.c]. +. el .ab Aborting '\\n[.F]' at \\$1, line \\n[.c]. +.END +\# .MAC REF_BRACKETS_START END -. if \\n[#FN_REF]=1 .nr #FN_REF 2 -. if \\n[#EN_REF]=1 .nr #EN_REF 2 -. ds $CURRENT_EV \\n[.ev] -. ev REFERENCE -. evc \\*[$CURRENT_EV] -. di REFERENCE +. REF_BRACKETS_NOTICE \\$0 .END \# .MAC REF_BRACKETS_END END -. br -. di -. ev -. chop REFERENCE -. unformat REFERENCE -. if '\\$0'REF)' .nop (\\*[REFERENCE]) -. if '\\$0'REF]' .nop [\\*[REFERENCE]] -. if '\\$0'REF}' .nop {\\*[REFERENCE]} -. if '\\$0'REF>' .nop <\\*[REFERENCE]> -. if \\n[#FN_REF]=2 .nr #FN_REF 1 -. if \\n[#EN_REF]=2 .nr #EN_REF 1 +. REF_BRACKETS_NOTICE \\$0 .END \# \# These four pairs of aliases allow users to embed references in @@ -16857,8 +16848,7 @@ E\\R'#CAP_HEIGHT \\n[.cht]' .ALIAS REF> REF_BRACKETS_END \# .MAC REF_STYLE END -. if '\\$1'NOTE' .ds $REF_STYLE NOTE -. if '\\$1'BIBLIO' .ds $REF_STYLE BIBLIO +. REF_BRACKETS_NOTICE \\$0 .END \# \# Refer indenting @@ -17396,7 +17386,7 @@ E\\R'#CAP_HEIGHT \\n[.cht]' . if \\n([T .nr ref*suppress-period \\n([T .\} .el \{\ -. ie \\n([T .ref*field C "" " " " " +. ie \\n([T .ref*field C "" " " . el \{\ . ie r [e .ref*field C "" " " . el .ref*field C . " " |