diff options
| -rw-r--r-- | Makefile | 2 | ||||
| -rw-r--r-- | index.html | 186 |
2 files changed, 188 insertions, 0 deletions
diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..f68fd2c --- /dev/null +++ b/Makefile @@ -0,0 +1,2 @@ +index.html: ../master/rf.1 + man -T html -O fragment $< > $@ diff --git a/index.html b/index.html new file mode 100644 index 0000000..6f5e32d --- /dev/null +++ b/index.html @@ -0,0 +1,186 @@ +<table class="head"> + <tr> + <td class="head-ltitle">rf(1)</td> + <td class="head-vol">General Commands Manual</td> + <td class="head-rtitle">rf(1)</td> + </tr> +</table> +<div class="manual-text"> +<section class="Sh"> +<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1> +<code class="Nm">rf</code> — +<div class="Nd">alternative reference system for (t)roff</div> +</section> +<section class="Sh"> +<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1> +<table class="Nm"> + <tr> + <td><code class="Nm">rf</code></td> + <td><code class="Li"><</code> <var class="Ar">file</var></td> + </tr> +</table> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCIPTION"><a class="permalink" href="#DESCIPTION">DESCIPTION</a></h1> +<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 + in 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> is around 150 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> +</ol> +</section> +<section class="Sh"> +<h1 class="Sh" id="USAGE"><a class="permalink" href="#USAGE">USAGE</a></h1> +<code class="Nm">rf</code> is controlled by several macros, all consisting of + one uppercase and one lowercase letter, beginning with either an + ‘F’ (format macros) or an ‘R’ (inline reference + and reference list macros). These are listed below in alphabetical order. +<section class="Ss"> +<h2 class="Ss" id="Format_macros"><a class="permalink" href="#Format_macros">Format + macros</a></h2> +<dl class="Bl-tag"> + <dt><b class="Sy">Ff</b></dt> + <dd>Defines the format for “full” 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. + <p class="Pp">Default: %a (%y). {\fI%t\fR}. {\*Q%q\*U}. %n, %d. %c: %p. + {Available: %w.}</p> + </dd> + <dt><b class="Sy">Fx</b></dt> + <dd>Defines the format for “alternate” inline references, which + usually 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"> +<h2 class="Ss" id="Inline_reference_macros"><a class="permalink" href="#Inline_reference_macros">Inline + reference macros</a></h2> +<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> + <dt><b class="Sy">Rx</b></dt> + <dd>Inserts an “alternate” inline reference, which usually + 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> +<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"> +<pre> +.Rf Johnson 92 . +</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 ) ( +</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> +<div class="Bd Pp Bd-indent"> +<pre> +According to Johnson +.Rx '' 92 , +there has been a gradual change in attitudes towards ... +</pre> +</div> +</section> +<section class="Ss"> +<h2 class="Ss" id="Reference_list_macros"><a class="permalink" href="#Reference_list_macros">Reference + list macros</a></h2> +<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">Of these macros, <b class="Sy">Ra</b> and <b class="Sy">Ry</b> are + the most important.</p> +</section> +</section> +<section class="Sh"> +<h1 class="Sh" id="FORMAT_SYNTAX"><a class="permalink" href="#FORMAT_SYNTAX">FORMAT + SYNTAX</a></h1> +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) \" (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}). \" Here, ', ' is removed if there is no year. +</pre> +</div> +<p class="Pp">Note that all fields are inserted literally, except + <i class="Em">%a</i>, from which the forenames of the authors are + removed.</p> +<p class="Pp">Finally, you usually don't need to worry about excessive spaces + and stray punctuation marks, as <code class="Nm">rf</code> removes many of + these these automatically.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1> +<code class="Nm">rf</code> was written by John Ankarström + <<a class="Mt" href="mailto:john">john</a> + <a class="Mt" href="mailto:(on)">(on)</a> + <a class="Mt" href="mailto:ankarstrom.se">ankarstrom.se</a>>. +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">November 11, 2020</td> + <td class="foot-os">Linux 5.4.72-0-lts</td> + </tr> +</table> |