[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Groff-commit] groff/contrib/mom ChangeLog om.tmac momdoc/refe...
|
From: |
Peter Schaffter |
|
Subject: |
[Groff-commit] groff/contrib/mom ChangeLog om.tmac momdoc/refe... |
|
Date: |
Mon, 12 Aug 2013 04:40:11 +0000 |
CVSROOT: /sources/groff
Module name: groff
Changes by: Peter Schaffter <PTPi> 13/08/12 04:40:11
Modified files:
contrib/mom : ChangeLog om.tmac
contrib/mom/momdoc: refer.html toc.html
Log message:
Updated documentation concerning refer usage.
CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/mom/ChangeLog?cvsroot=groff&r1=1.78&r2=1.79
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/mom/om.tmac?cvsroot=groff&r1=1.72&r2=1.73
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/mom/momdoc/refer.html?cvsroot=groff&r1=1.16&r2=1.17
http://cvs.savannah.gnu.org/viewcvs/groff/contrib/mom/momdoc/toc.html?cvsroot=groff&r1=1.42&r2=1.43
Patches:
Index: ChangeLog
===================================================================
RCS file: /sources/groff/groff/contrib/mom/ChangeLog,v
retrieving revision 1.78
retrieving revision 1.79
diff -u -b -r1.78 -r1.79
--- ChangeLog 10 Jun 2013 13:39:30 -0000 1.78
+++ ChangeLog 12 Aug 2013 04:40:10 -0000 1.79
@@ -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.
Index: om.tmac
===================================================================
RCS file: /sources/groff/groff/contrib/mom/om.tmac,v
retrieving revision 1.72
retrieving revision 1.73
diff -u -b -r1.72 -r1.73
--- om.tmac 7 Jun 2013 15:19:58 -0000 1.72
+++ om.tmac 12 Aug 2013 04:40:11 -0000 1.73
@@ -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 <address@hidden>
PDF integration contributed by Deri James <address@hidden>
@@ -23,8 +23,8 @@
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 @@
. 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 @@
\# 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 @@
.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 @@
. 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 . " "
Index: momdoc/refer.html
===================================================================
RCS file: /sources/groff/groff/contrib/mom/momdoc/refer.html,v
retrieving revision 1.16
retrieving revision 1.17
diff -u -b -r1.16 -r1.17
--- momdoc/refer.html 29 Jan 2013 05:02:46 -0000 1.16
+++ momdoc/refer.html 12 Aug 2013 04:40:11 -0000 1.17
@@ -48,15 +48,17 @@
<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 @@
<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 @@
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 @@
<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 @@
<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 @@
<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 @@
<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 @@
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 @@
</p>
</div>
-<h4 id="bibliography-recipe" class="docs">6. Creating a bibliography</h4>
+<h4 id="parenthetical-insertions" class="docs">6. Parenthetical insertions</h4>
+
+<p>
+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>
-Bibliographic references come between
+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 @@
</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 @@
</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 @@
<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 @@
<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;">
-<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).
-</span>
-</div>
-<span style="display: inline-block; padding-top: .5em; padding-bottom:
.5em;">versus</span>
-<div class="examples-container" style="padding-bottom: .25em;">
-<span class="pre-in-pp">
- Ancient writers attributed the invention of the monochord
- to Pythagoras, who lived in the sixth century BC
- .REF(
+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">
+ ...end of sentence.
.[
- survey
- %P 197
+ martian chronicles
.]
- .REF)
- . Marcone, however, discovered precursors of the instrument
- dating at least two centuries earlier
- .REF(
+ A new sentence...
+</span>
+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">
+ "...aluminum roaches and iron crickets."
.[
- plectrum
- %P 98
- .]
- .REF)
- .
+ [ martian chronicles
+ .] 168)
+ A new sentence...
</span>
-</div>
+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>
-Clearly, the first example takes less work, and is much easier to read.
+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."
+ .[
+ [ bradbury martian
+ .], \fIChronicles\fP 168)
+ A new sentence...
+</span>
+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>
+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 @@
<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 @@
<!-- -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 @@
<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 @@
<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 @@
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 @@
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 @@
<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 @@
<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 @@
<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 @@
</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 @@
<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 @@
</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 @@
<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>
Index: momdoc/toc.html
===================================================================
RCS file: /sources/groff/groff/contrib/mom/momdoc/toc.html,v
retrieving revision 1.42
retrieving revision 1.43
diff -u -b -r1.42 -r1.43
--- momdoc/toc.html 29 Jan 2013 05:02:46 -0000 1.42
+++ momdoc/toc.html 12 Aug 2013 04:40:11 -0000 1.43
@@ -21,7 +21,7 @@
<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>
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- [Groff-commit] groff/contrib/mom ChangeLog om.tmac momdoc/refe...,
Peter Schaffter <=