generate readme from manual

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> &#x2014;
+<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">&lt;</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
+  &#x2018;F&#x2019; (format macros) or an &#x2018;R&#x2019; (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 &#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.
+    <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 &#x201C;alternate&#x201D; 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 &#x201C;full&#x201D; inline reference, 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>
+</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)      \&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">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&#x00F6;m
+  &lt;<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>&gt;.
+</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>