From b0e00f631b1d5004afc483778fdd60bb549fe9a7 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?John=20Ankarstr=C3=B6m?= <john@ankarstrom.se>
Date: Wed, 11 Nov 2020 01:43:52 +0100
Subject: add manual

---
 rf.1 | 189 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 189 insertions(+)
 create mode 100644 rf.1

(limited to 'rf.1')

diff --git a/rf.1 b/rf.1
new file mode 100644
index 0000000..89b5c05
--- /dev/null
+++ b/rf.1
@@ -0,0 +1,189 @@
+.Dd $Mdocdate$
+.Dt rf 1
+.Os
+.
+.Sh NAME
+.Nm rf
+.Nd alternative reference system for (t)roff
+.
+.Sh SYNOPSIS
+.Nm
+.Li <
+.Ar file
+.
+.Sh DESCIPTION
+.Nm
+is a reference system for troff and other roff derivatives.
+It differs from
+.Xr refer 1 ,
+the traditional troff reference system,
+in a couple important ways:
+.Bl -enum
+.It
+References are not stored in a separate file.
+They are defined via macros in the troff document itself.
+.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.
+.It
+.Nm
+is around 150 lines of Perl.
+If you find a bug or an (in your opinion) undesirable behavior in
+.Nm ,
+you can easily patch it.
+.It
+Finally,
+.Nm
+is much more simple and offers much more basic functionality than
+.Xr refer 1 .
+This means that you can learn all of it in five minutes.
+.El
+.
+.Sh USAGE
+.Nm
+is controlled by several macros, all consisting of one uppercase and one lowercase letter, beginning with either an
+.Sq F
+(format macros)
+or an
+.Sq R
+(inline reference and reference list macros).
+These are listed below in alphabetical order.
+.Ss Format macros
+.Bl -tag
+.It Sy \&Ff
+Defines the format for
+.Dq full
+inline references, which usually contain both author and year.
+.Pp
+Default: (%a %y)
+.It Sy \&Fl
+Defines the format for the reference list, which is usually located at the end of the document.
+.Pp
+Default: %a (%y). %t. %q. %n, %d. %c: %p. {Available: %w.}
+.It Sy \&Fx
+Defines the format for
+.Dq alternate
+inline references, which usually contain only the year.
+.Pp
+Default: (%y)
+.El
+.Pp
+For a description of the format syntax, see
+.Sx FORMAT SYNTAX .
+.
+.Ss Inline reference macros
+.Bl -tag
+.It Sy \&Rf
+Inserts a
+.Dq full
+inline reference, which usually contains both author and year.
+.It Sy \&Rx
+Inserts an
+.Dq alternate
+inline reference, which usually contains only the year.
+.El
+.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.
+.Pp
+To include some punctuation character immediately after the inline reference, add a space before it:
+.Bd -literal -offset indent
+\&.Rf Johnson 92 .
+.Ed
+.Pp
+To wrap the inline reference in parentheses, use the following syntax:
+.Bd -literal -offset indent
+\&.Rf Johnson 92 ) (
+.Ed
+.Pp
+Additionally, any instance of
+.Li ''
+is replaced with the last word on the preceding line.
+This allows the following shortcut:
+.Bd -literal -offset indent
+According to Johnson
+\&.Rx '' 92 ,
+there has been a gradual change in attitudes towards ...
+.Ed
+.
+.Ss Reference list macros
+.Bl -tag
+.It Sy \&Ra
+Adds to the list of
+.Em authors
+of the current reference.
+Additionally,
+.Sy \&Ra
+marks the beginning of a new reference.
+.Pp
+Format: Surname(s), Forename(s)
+.It Sy \&Rc
+Defines the
+.Em city
+of publication.
+.It Sy \&Rd
+Defines the (detailed)
+.Em date
+of publication, not as a substitute for
+.Sy \&Ry ,
+but as a further specification.
+For example, the day and month a newspaper article was published.
+.It Sy \&Rn
+Defines the
+.Em newspaper
+in which an article was published.
+.It Sy \&Rp
+Defines the
+.Em publisher
+of a book.
+.It Sy \&Rq
+Defines the (quoted)
+.Em title
+of an article.
+.It Sy \&Rt
+Defines the
+.Em title
+of a book.
+.Ìt Sy \&Rw
+Defines the (web)
+.Em address
+of an online resource.
+.It Sy \&Ry
+Defines the
+.Em year
+of publication.
+.El
+.Pp
+Of these macros,
+.Sy \&Ra
+and
+.Sy \&Ry
+are the most important.
+.Sh FORMAT SYNTAX
+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:
+.Bd -literal -offset indent
+\&.Ff (%a, %y)      \\" (Author, Year)
+.Ed
+.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:
+.Bd -literal -offset indent
+\&.Ff (%a {,%y}).   \\" The comma is removed if there is no year.
+.Ed
+.Pp
+You need not worry about excessive spaces, as
+.Nm
+removes these automatically.
+.Pp
+All fields are inserted literally, except
+.Em %a ,
+from which the forenames of the authors are removed.
+.
+.Sh AUTHORS
+.Nm
+was written by John Ankarström
+.Aq Mt john (on) ankarstrom.se .
-- 
cgit v1.2.3