generate (improvements)

1 files changed, 103 insertions, 74 deletions

diff --git a/index.html b/index.html
index 4c3db0d..23462fd 100644
--- a/index.html
+++ b/index.html
@@ -27,7 +27,7 @@
   reference system, in a couple important ways:
 <ol class="Bl-enum">
   <li>References are not stored in a separate file. They are defined via macros
-      in the troff document itself, usually at the end.
+      at the end of the troff document itself.
     <p class="Pp">This means that you can move, copy and share your troff
         document without needing to worry about an additional reference file.
         Furthermore, you never run the risk of accidentally losing the
@@ -73,26 +73,34 @@
 <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; (format macros) or an &#x2018;R&#x2019; (inline reference
-  and reference list macros). These are listed below in alphabetical order.
+  &#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>
 <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.
 <dl class="Bl-tag">
-  <dt><b class="Sy">Ff</b></dt>
-  <dd>Defines the format for &#x201C;full&#x201D; inline references, which
-      usually contain both author and year.
-    <p class="Pp">Default: (%a %y)</p>
-  </dd>
-  <dt><b class="Sy">Fl</b></dt>
-  <dd>Defines the format for the reference list, which is usually located at the
-      end of the document.
+  <dt><b class="Sy">Fe</b></dt>
+  <dd>Defines the format for reference list entries.
     <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.
+    <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
-      usually contain only the year.
+      by default contain only the year.
     <p class="Pp">Default: (%y)</p>
   </dd>
 </dl>
@@ -100,8 +108,48 @@
     <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
+  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.
+<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>
+  <dt><b class="Sy">Rc</b></dt>
+  <dd>Defines the <i class="Em">city</i> of publication.</dd>
+  <dt><b class="Sy">Rd</b></dt>
+  <dd>Defines the (detailed) <i class="Em">date</i> of publication, not as a
+      substitute for <b class="Sy">Ry</b>, but as a further specification. For
+      example, the day and month a newspaper article was published.</dd>
+  <dt><b class="Sy">Rn</b></dt>
+  <dd>Defines the <i class="Em">newspaper</i> in which an article was
+    published.</dd>
+  <dt><b class="Sy">Rp</b></dt>
+  <dd>Defines the <i class="Em">publisher</i> of a book.</dd>
+  <dt><b class="Sy">Rq</b></dt>
+  <dd>Defines the (quoted) <i class="Em">title</i> of an article.</dd>
+  <dt><b class="Sy">Rt</b></dt>
+  <dd>Defines the <i class="Em">title</i> of a book.</dd>
+  <dt><b class="Sy">Rw</b></dt>
+  <dd>Defines the (web) <i class="Em">address</i> of an online resource.</dd>
+  <dt><b class="Sy">Ry</b></dt>
+  <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>
+</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:
 <dl class="Bl-tag">
   <dt><b class="Sy">Rf</b></dt>
   <dd>Inserts a &#x201C;full&#x201D; inline reference, which usually contains
@@ -111,9 +159,9 @@
       contains only the year.</dd>
 </dl>
 <p class="Pp">What reference to refer to is specified by the rest of the line.
-    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>
+    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>
 <div class="Bd Pp Bd-indent">
@@ -139,50 +187,19 @@ there has been a gradual change in attitudes towards ...
 </pre>
 </div>
 </section>
-<section class="Ss">
-<h3 class="Ss" id="Reference_list_macros"><a class="permalink" style="color: black; text-decoration: none;" href="#Reference_list_macros">Reference
-  list macros</a></h3>
-<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.
-      Additionally, <b class="Sy">Ra</b> marks the beginning of a new reference.
-    <p class="Pp">Format: Surname(s), Forename(s)</p>
-  </dd>
-  <dt><b class="Sy">Rc</b></dt>
-  <dd>Defines the <i class="Em">city</i> of publication.</dd>
-  <dt><b class="Sy">Rd</b></dt>
-  <dd>Defines the (detailed) <i class="Em">date</i> of publication, not as a
-      substitute for <b class="Sy">Ry</b>, but as a further specification. For
-      example, the day and month a newspaper article was published.</dd>
-  <dt><b class="Sy">Rn</b></dt>
-  <dd>Defines the <i class="Em">newspaper</i> in which an article was
-    published.</dd>
-  <dt><b class="Sy">Rp</b></dt>
-  <dd>Defines the <i class="Em">publisher</i> of a book.</dd>
-  <dt><b class="Sy">Rq</b></dt>
-  <dd>Defines the (quoted) <i class="Em">title</i> of an article.</dd>
-  <dt><b class="Sy">Rt</b></dt>
-  <dd>Defines the <i class="Em">title</i> of a book. Defines the (web)
-      <i class="Em">address</i> of an online resource.</dd>
-  <dt><b class="Sy">Ry</b></dt>
-  <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>
-</section>
 </section>
 <section class="Sh">
 <h2 class="Sh" id="FORMAT_SYNTAX"><a class="permalink" style="color: black; text-decoration: none;" href="#FORMAT_SYNTAX">FORMAT
   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:
 <div class="Bd Pp Bd-indent">
 <pre>
-.Ff (%a, %y)      \&quot; (Author, Year)
+.Ff (%A, %y)      \&quot; (Author, Year)
 </pre>
 </div>
 <p class="Pp">By wrapping an interpolation in braces, you can specify a prefix
@@ -190,33 +207,44 @@ In a format definition, use a percent (%) sigil followed by a single letter to
     successful. For example:</p>
 <div class="Bd Pp Bd-indent">
 <pre>
-.Ff (%a{, %y}).   \&quot; Here, ', ' is removed if there is no year.
+.Ff (%A{, %y}).   \&quot; Here, ', ' is removed if there is no year.
 </pre>
 </div>
-<p class="Pp">You can include a newline in your format by ending the line with a
-    backslash and continuing on the next line. If you add a backslash
-    immediately following the macro name, the interpolated format will be joined
-    to the preceding line. By using backslashes, you can implement
-    footnote-based references. For example, using the ms macro package:</p>
+<p class="Pp">To interpolate only the <b class="Sy">surnames</b> of the authors,
+    you can use the special <i class="Em">%A</i> syntax, with an uppercase
+    instead of lowercase &#x2018;a&#x2019;.</p>
+</section>
+<section class="Ss">
+<h3 class="Ss" id="Special_backslash_behavior"><a class="permalink" style="color: black; text-decoration: none;" href="#Special_backslash_behavior">Special
+  backslash behavior</a></h3>
+<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>
+</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.
+    For example, using the ms macro package:</p>
 <div class="Bd Pp Bd-indent">
 <pre>
 .Fx\ \**\
 .FS\
-%A, {\fI%t\fR}, {\*Q%q\*U}, %y.\
+%a, {\fI%t\fR}, {\*Q%q\*U}, %y.\
 .FE
 </pre>
 </div>
-<p class="Pp">As you can see above, you can use troff requests and other macros
-    in your format. This will expand to a valid request/macro in the output of
-    <code class="Nm">rf</code>.</p>
-<p class="Pp">Note that all fields are inserted literally, with one exception:
-    when <i class="Em">%a</i> is used in an inline reference format, the
-    forenames of the authors are automatically removed. To include the
-    forenames, use <i class="Em">%A</i> instead.</p>
-<p class="Pp">Finally, you usually don't need to worry about excessive spaces
-    and stray punctuation marks. <code class="Nm">rf</code> removes common
-    punctuation immediately preceding and following an unsuccessful
-    interpolation.</p>
+</section>
+<section class="Ss">
+<h3 class="Ss" id="Automatic_cleanup"><a class="permalink" style="color: black; text-decoration: none;" href="#Automatic_cleanup">Automatic
+  cleanup</a></h3>
+You usually don't need to worry about excessive spaces and stray punctuation
+  marks. <code class="Nm">rf</code> removes common punctuation immediately
+  preceding and following an unsuccessful interpolation. Excessive spaces are
+  also removed, unless they follow a period, marking the end of a sentence.
+</section>
 </section>
 <section class="Sh">
 <h2 class="Sh" id="EXAMPLE"><a class="permalink" style="color: black; text-decoration: none;" href="#EXAMPLE">EXAMPLE</a></h2>
@@ -247,19 +275,19 @@ Literature
 .Ra Davidson, H.
 .Ry 1991
 .Rt Seminal Work
-.Rc London
-.Rp Another Press
+.Rc Athens
+.Rp Logos
 
 .XP
 .Ra Smith, P.
 .Ry 2007
 .Rt Modern Society
-.Rc New York
-.Rp Some Press
+.Rc Athens
+.Rp Logos
 </pre>
 </div>
 <p class="Pp">When given the above file, <code class="Nm">rf</code> will output
-    the following code:</p>
+    the following source code:</p>
 <div class="Bd Pp Bd-indent">
 <pre>
 .de noop
@@ -269,6 +297,7 @@ Literature
 .SH
 Previous work
 
+
 .LP
 Davidson
 (1991)
@@ -282,10 +311,10 @@ has performed a study [...]
 Literature
 
 .XP
-Davidson, H. (1991). \fISeminal Work\fR. London: Another Press.
+Davidson, H. (1991).  \fISeminal Work\fR.  Athens: Logos.
 
 .XP
-Smith, P. (2007). \fIModern Society\fR. New York: Some Press.
+Smith, P. (2007).  \fIModern Society\fR.  Athens: Logos.
 </pre>
 </div>
 </section>