aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorJohn Ankarström <john@ankarstrom.se>2020-11-12 00:56:40 +0100
committerJohn Ankarström <john@ankarstrom.se>2020-11-12 00:56:40 +0100
commit0535b7262f9fbd79efd2dd471971c1d94fcc3bf5 (patch)
tree7fbb9e57430dcca6bfd281cc19448dc2cb9f340a
parent5ac0bf9632f4475ef82f3bda2528d76e0e84c5d8 (diff)
downloadrf-readme.tar.gz
regen (change terminology)readme
-rw-r--r--index.html176
1 files changed, 99 insertions, 77 deletions
diff --git a/index.html b/index.html
index 23462fd..9fd23dc 100644
--- a/index.html
+++ b/index.html
@@ -33,17 +33,17 @@
Furthermore, you never run the risk of accidentally losing the
references attached to a document.</p>
</li>
- <li><code class="Nm">rf</code> is around 150 lines of Perl. If you find a bug
- or an (in your opinion) undesirable behavior in
+ <li><code class="Nm">rf</code> consists of circa 200 lines of Perl. If you
+ find a bug or an (in your opinion) undesirable behavior in
<code class="Nm">rf</code>, you can easily patch it.</li>
- <li>Finally, <code class="Nm">rf</code> is much more simple and offers much
- more basic functionality than <a class="Xr">refer(1)</a>. This means that
- you can learn all of it in five minutes.</li>
+ <li>Finally, <code class="Nm">rf</code> is much simpler, much less opaque and
+ offers much more basic functionality than <a class="Xr">refer(1)</a>. You
+ can learn all of it in five minutes.</li>
</ol>
<p class="Pp">The performance of <code class="Nm">rf</code> primarily depends on
- the number of entries in the reference list at the end of the document. On
- my HP Compaq dc5700 from 2007, the relationship between number of entries in
- the reference list and total execution time is roughly the following:</p>
+ the number of references (but not citations). On my HP Compaq dc5700 from
+ 2007, the relationship between number of references and total execution time
+ is roughly the following:</p>
<table class="Bl-column Bd-indent">
<tr>
<td><i class="Em">Entries&#x00A0;&#x00A0;&#x00A0;&#x00A0;</i></td>
@@ -51,56 +51,69 @@
</tr>
<tr>
<td>3</td>
- <td>0.03s</td>
+ <td>0.01s</td>
</tr>
<tr>
<td>50</td>
- <td>0.09s</td>
+ <td>0.07s</td>
</tr>
<tr>
- <td>107</td>
- <td>0.15s</td>
+ <td>100</td>
+ <td>0.14s</td>
</tr>
<tr>
- <td>182</td>
- <td>0.24s</td>
+ <td>200</td>
+ <td>0.26s</td>
+ </tr>
+ <tr>
+ <td>500</td>
+ <td>0.65s</td>
+ </tr>
+ <tr>
+ <td>2,000</td>
+ <td>2.59s</td>
+ </tr>
+ <tr>
+ <td>10,000</td>
+ <td>12.94s</td>
</tr>
</table>
-<p class="Pp">I would deem it rare to have more than a couple of hundred unique
- references in a troff document.</p>
+<p class="Pp">Luckily, I would deem it extremely rare to have more than a couple
+ of hundred unique references in a troff document.</p>
</section>
<section class="Sh">
<h2 class="Sh" id="USAGE"><a class="permalink" style="color: black; text-decoration: none;" href="#USAGE">USAGE</a></h2>
-<code class="Nm">rf</code> is controlled by several macros, all consisting of
- one uppercase and one lowercase letter, beginning with either an
- &#x2018;F&#x2019; or an &#x2018;R&#x2019;. Macros beginning with
- &#x2018;R&#x2019; control the two primary &#x201C;units&#x201D; of
- <code class="Nm">rf</code>:
-<ol class="Bl-enum">
- <li><i class="Em">entries</i> in the reference list, and</li>
- <li><i class="Em">inline references</i> to these entries.</li>
-</ol>
-<p class="Pp">Macros beginning with &#x2018;F&#x2019;, in turn, control the
- appearance of these two units.</p>
+<code class="Nm">rf</code> provides two features, which it calls
+ <i class="Em">references</i> and <i class="Em">citations</i>:
+<dl class="Bl-tag">
+ <dt><i class="Em">reference</i></dt>
+ <dd>a bibliographic entry written at the end of the document</dd>
+ <dt><i class="Em">citation</i></dt>
+ <dd>an inline reference to a bibliographic entry</dd>
+</dl>
+<p class="Pp"><code class="Nm">rf</code> is controlled by several macros, all
+ consisting of one uppercase and one lowercase letter, beginning with either
+ an &#x2018;R&#x2019; &#x2013; macros controlling references and citations
+ &#x2013; or an &#x2018;F&#x2019; &#x2013; macros controlling the appearance
+ of references and citations.</p>
<section class="Ss">
<h3 class="Ss" id="Format_macros"><a class="permalink" style="color: black; text-decoration: none;" href="#Format_macros">Format
macros</a></h3>
-You can control the appearance of your references as they are displayed in-line
- as well as in the final reference list by using the format macros.
+These macros control control the appearance of references and citations.
<dl class="Bl-tag">
- <dt><b class="Sy">Fe</b></dt>
- <dd>Defines the format for reference list entries.
+ <dt><b class="Sy">Fr</b></dt>
+ <dd>Defines the format for references in the bibliography.
<p class="Pp">Default: %a (%y). {\fI%t\fR}. {\*Q%q\*U}. %n, %d. %c: %p.
{Available: %w.}</p>
</dd>
<dt><b class="Sy">Ff</b></dt>
- <dd>Defines the format for &#x201C;full&#x201D; inline references, which by
- default contain both author and year.
+ <dd>Defines the format for &#x201C;full&#x201D; citations, which by default
+ contain both author and year.
<p class="Pp">Default: (%A %y)</p>
</dd>
<dt><b class="Sy">Fx</b></dt>
- <dd>Defines the format for &#x201C;alternate&#x201D; inline references, which
- by default contain only the year.
+ <dd>Defines the format for &#x201C;alternate&#x201D; citations, which by
+ default contain only the year.
<p class="Pp">Default: (%y)</p>
</dd>
</dl>
@@ -108,17 +121,18 @@ You can control the appearance of your references as they are displayed in-line
<a class="Sx" href="#FORMAT_SYNTAX">FORMAT SYNTAX</a>.</p>
</section>
<section class="Ss">
-<h3 class="Ss" id="Entry_definition_macros"><a class="permalink" style="color: black; text-decoration: none;" href="#Entry_definition_macros">Entry
+<h3 class="Ss" id="Reference_definition_macros"><a class="permalink" style="color: black; text-decoration: none;" href="#Reference_definition_macros">Reference
definition macros</a></h3>
-In the reference list, each entry is defined by a <b class="Sy">contiguous</b>
- block of lines containing definition macros, describing various
- <i class="Em">fields</i> belonging to the reference, such as author and year.
- The definition of one reference is separated from that of another by any other
- lines, <b class="Sy">including</b> text lines and empty lines.
+In the reference list or bibliography, a single reference is defined by a
+ <b class="Sy">contiguous</b> block of lines containing any of the macros
+ described below. The definition of one reference is separated from that of
+ another by any other lines, <b class="Sy">including</b> text lines, empty
+ lines and lines containing other macros than the ones listed below.
<dl class="Bl-tag">
<dt><b class="Sy">Ra</b></dt>
- <dd>Adds to the list of <i class="Em">authors</i> of the current reference.
- <p class="Pp">Format: Surname(s), Forename(s)</p>
+ <dd>Defines the <i class="Em">author</i> of the publication. You can use
+ <b class="Sy">Ra</b> more than once in order to define multiple authors.
+ <p class="Pp">Format: Surname, Forename/Initial</p>
</dd>
<dt><b class="Sy">Rc</b></dt>
<dd>Defines the <i class="Em">city</i> of publication.</dd>
@@ -141,49 +155,57 @@ In the reference list, each entry is defined by a <b class="Sy">contiguous</b>
<dd>Defines the <i class="Em">year</i> of publication.</dd>
</dl>
<p class="Pp">In the final output, <code class="Nm">rf</code> prints a formatted
- version of each reference entry in place of its definition.
- <code class="Nm">rf</code> does not change the order of reference entries.
- This means that you can arrange your references freely.</p>
+ version of each reference in place of its definition.
+ <code class="Nm">rf</code> does not change the order of reference. This
+ means that you can arrange your references freely.</p>
</section>
<section class="Ss">
-<h3 class="Ss" id="Inline_reference_macros"><a class="permalink" style="color: black; text-decoration: none;" href="#Inline_reference_macros">Inline
- reference macros</a></h3>
-To insert an inline reference to an entry in the reference list, you can use one
- of two macros:
+<h3 class="Ss" id="Citation_macros"><a class="permalink" style="color: black; text-decoration: none;" href="#Citation_macros">Citation
+ macros</a></h3>
+To insert a citation, you can use one of two macros:
<dl class="Bl-tag">
<dt><b class="Sy">Rf</b></dt>
- <dd>Inserts a &#x201C;full&#x201D; inline reference, which usually contains
- both author and year.</dd>
+ <dd>Inserts a &#x201C;full&#x201D; citation, which usually contains both
+ author and year.</dd>
<dt><b class="Sy">Rx</b></dt>
- <dd>Inserts an &#x201C;alternate&#x201D; inline reference, which usually
- contains only the year.</dd>
+ <dd>Inserts an &#x201C;alternate&#x201D; citation, which usually contains only
+ the year.</dd>
</dl>
-<p class="Pp">What reference to refer to is specified by the rest of the line.
- Each word of it is matched against the author, year and title of all
- references to find a match. If only a weak match is found, a warning is
- printed on standard error.</p>
-<p class="Pp">To include some punctuation character immediately after the inline
- reference, add a space before it:</p>
+<p class="Pp"><b class="Sy">Reference identification.</b> &#x00A0;After the
+ macro name, you should provide one or more keywords to identify the
+ reference to which the citation is to refer. Each word is matched
+ case-insensitively against the author, year and title of all references. For
+ example:</p>
+<div class="Bd Pp Bd-indent">
+<pre>
+.Rf Trubetzkoy 1969
+</pre>
+</div>
+<p class="Pp">If only a weak match is found, a helpful warning is printed on
+ standard error.</p>
+<p class="Pp"><b class="Sy">Adjacent punctuation.</b> &#x00A0;To include some
+ punctuation character immediately after the inline reference, use the
+ following syntax:</p>
<div class="Bd Pp Bd-indent">
<pre>
-.Rf Johnson 92 .
+.Rf Grot 1873 .
</pre>
</div>
<p class="Pp">To wrap the inline reference in parentheses, use the following
syntax:</p>
<div class="Bd Pp Bd-indent">
<pre>
-.Rf Johnson 92 ) (
+.Rf Courtenay 1972 ) (
</pre>
</div>
-<p class="Pp">Additionally, any instance of <code class="Li">''</code> is
- replaced with the last word on the preceding line. This allows the following
- shortcut:</p>
+<p class="Pp"><b class="Sy">Shortcuts.</b> &#x00A0;Any instance of
+ <code class="Li">''</code> is replaced with the last word on the preceding
+ line. This allows the following shortcut:</p>
<div class="Bd Pp Bd-indent">
<pre>
-According to Johnson
-.Rx '' 92 ,
-there has been a gradual change in attitudes towards ...
+According to Brandt
+.Rx '' 1892 ,
+Russian differs from other European languages in its [...]
</pre>
</div>
</section>
@@ -193,10 +215,10 @@ there has been a gradual change in attitudes towards ...
SYNTAX</a></h2>
<section class="Ss">
<h3 class="Ss" id="Interpolation"><a class="permalink" style="color: black; text-decoration: none;" href="#Interpolation">Interpolation</a></h3>
-In a format definition, use a percent (%) sigil followed by a single letter to
- interpolate any given field of the reference. The letter following the percent
- sign corresponds to the second letter of the reference list macros described
- above. For example:
+In a format specification, use a percent (%) sigil followed by a single letter
+ to interpolate any given field of the reference. The letter following the
+ percent sign corresponds to the second letter of the reference list macros
+ described above. For example:
<div class="Bd Pp Bd-indent">
<pre>
.Ff (%A, %y) \&quot; (Author, Year)
@@ -220,13 +242,13 @@ In a format definition, use a percent (%) sigil followed by a single letter to
<ol class="Bl-enum">
<li>A backslash at the end of a format line acts as a line continuation
marker. The newline after the backslash is preserved.</li>
- <li>For format macros describing inline references, a backslash immediately
- following the macro name will cause the reference be joined to the
- preceding line.</li>
+ <li>For format macros describing citations, a backslash immediately following
+ the macro name will cause the reference be joined to the preceding
+ line.</li>
</ol>
<p class="Pp">Anywhere else in the line, backslashes are preserved
literally.</p>
-<p class="Pp">By using backslashes, you can implement footnote-based references.
+<p class="Pp">By using backslashes, you can implement footnote-based citations.
For example, using the ms macro package:</p>
<div class="Bd Pp Bd-indent">
<pre>
@@ -328,7 +350,7 @@ Smith, P. (2007). \fIModern Society\fR. Athens: Logos.
</div>
<table class="foot" style="width: 100%;">
<tr>
- <td class="foot-date">November 11, 2020</td>
+ <td class="foot-date">November 12, 2020</td>
<td class="foot-os" style="text-align: right;">Linux 5.4.72-0-lts</td>
</tr>
</table>