diff options
Diffstat (limited to 'index.html')
| -rw-r--r-- | index.html | 176 |
1 files changed, 99 insertions, 77 deletions
@@ -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    </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 - ‘F’ or an ‘R’. Macros beginning with - ‘R’ control the two primary “units” 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 ‘F’, 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 ‘R’ – macros controlling references and citations + – or an ‘F’ – 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 “full” inline references, which by - default contain both author and year. + <dd>Defines the format for “full” 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 “alternate” inline references, which - by default contain only the year. + <dd>Defines the format for “alternate” 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 “full” inline reference, which usually contains - both author and year.</dd> + <dd>Inserts a “full” citation, which usually contains both + author and year.</dd> <dt><b class="Sy">Rx</b></dt> - <dd>Inserts an “alternate” inline reference, which usually - contains only the year.</dd> + <dd>Inserts an “alternate” 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>  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>  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>  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) \" (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> |