regen (change terminology)readme

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>