path: root/index.html

<table class="head" style="width: 100%;">
  <tr>
    <td class="head-ltitle">rf(1)</td>
    <td class="head-vol" style="text-align: center;">General Commands Manual</td>
    <td class="head-rtitle" style="text-align: right;">rf(1)</td>
  </tr>
</table>
<div class="manual-text">
<section class="Sh">
<h2 class="Sh" id="NAME"><a class="permalink" style="color: black; text-decoration: none;" href="#NAME">NAME</a></h2>
<code class="Nm">rf</code> &#x2014;
<div class="Nd">alternative reference system for (t)roff</div>
</section>
<section class="Sh">
<h2 class="Sh" id="SYNOPSIS"><a class="permalink" style="color: black; text-decoration: none;" href="#SYNOPSIS">SYNOPSIS</a></h2>
<table class="Nm">
  <tr>
    <td><code class="Nm">rf</code></td>
    <td><var class="Ar">file</var></td>
  </tr>
</table>
</section>
<section class="Sh">
<h2 class="Sh" id="DESCIPTION"><a class="permalink" style="color: black; text-decoration: none;" href="#DESCIPTION">DESCIPTION</a></h2>
<code class="Nm">rf</code> is a reference system for troff and other roff
  derivatives. It differs from <a class="Xr">refer(1)</a>, the traditional troff
  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
      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
        references attached to a document.</p>
  </li>
  <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 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 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>
    <td><i class="Em">Time</i></td>
  </tr>
  <tr>
    <td>3</td>
    <td>0.01s</td>
  </tr>
  <tr>
    <td>50</td>
    <td>0.07s</td>
  </tr>
  <tr>
    <td>100</td>
    <td>0.14s</td>
  </tr>
  <tr>
    <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">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> 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>
These macros control control the appearance of references and citations.
<dl class="Bl-tag">
  <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; 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; citations, which by
      default contain only the year.
    <p class="Pp">Default: (%y)</p>
  </dd>
</dl>
<p class="Pp">For a description of the format syntax, see
    <a class="Sx" href="#FORMAT_SYNTAX">FORMAT SYNTAX</a>.</p>
</section>
<section class="Ss">
<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 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>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>
  <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 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="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; citation, which usually contains both
      author and year.</dd>
  <dt><b class="Sy">Rx</b></dt>
  <dd>Inserts an &#x201C;alternate&#x201D; citation, which usually contains only
      the year.</dd>
</dl>
<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 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 Courtenay 1972 ) (
</pre>
</div>
<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 Brandt
.Rx '' 1892 ,
Russian differs from other European languages in its [...]
</pre>
</div>
</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 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)
</pre>
</div>
<p class="Pp">By wrapping an interpolation in braces, you can specify a prefix
    and/or suffix that should be included only if the interpolation is
    successful. For example:</p>
<div class="Bd Pp Bd-indent">
<pre>
.Ff (%A{, %y}).   \&quot; Here, ', ' is removed if there is no year.
</pre>
</div>
<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 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 citations.
    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.\
.FE
</pre>
</div>
</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>
Below is an example of an ms-based troff document using
  <code class="Nm">rf</code> references.
<div class="Bd Pp Bd-indent">
<pre>
.de noop
..
.blm noop

.SH
Previous work

.LP
Davidson
.Rx '' 1991
has performed a study [...]

.PP
[...] which leads to a higher total cholesterol level
.Rf Smith 2007 .

.SH
Literature

.XP
.Ra Davidson, H.
.Ry 1991
.Rt Seminal Work
.Rc Athens
.Rp Logos

.XP
.Ra Smith, P.
.Ry 2007
.Rt Modern Society
.Rc Athens
.Rp Logos
</pre>
</div>
<p class="Pp">When given the above file, <code class="Nm">rf</code> will output
    the following source code:</p>
<div class="Bd Pp Bd-indent">
<pre>
.de noop
..
.blm noop

.SH
Previous work


.LP
Davidson
(1991)
has performed a study [...]

.PP
[...] which leads to a higher total cholesterol level
(Smith 2007).

.SH
Literature

.XP
Davidson, H. (1991).  \fISeminal Work\fR.  Athens: Logos.

.XP
Smith, P. (2007).  \fIModern Society\fR.  Athens: Logos.
</pre>
</div>
</section>
<section class="Sh">
<h2 class="Sh" id="AUTHORS"><a class="permalink" style="color: black; text-decoration: none;" href="#AUTHORS">AUTHORS</a></h2>
<code class="Nm">rf</code> was written by John Ankarstr&#x00F6;m
  &lt;<a class="Mt" href="mailto:john">john</a>
  <a class="Mt" href="mailto:(at)">(at)</a>
  <a class="Mt" href="mailto:ankarstrom.se">ankarstrom.se</a>&gt;.
</section>
</div>
<table class="foot" style="width: 100%;">
  <tr>
    <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>