aboutsummaryrefslogtreecommitdiff
path: root/rf.1
diff options
context:
space:
mode:
Diffstat (limited to 'rf.1')
-rw-r--r--rf.1146
1 files changed, 80 insertions, 66 deletions
diff --git a/rf.1 b/rf.1
index 680bd4b..fe69186 100644
--- a/rf.1
+++ b/rf.1
@@ -11,6 +11,7 @@
.Ar file
.
.Sh DESCIPTION
+.Pp
.Nm
is a reference system for troff and other roff derivatives.
It differs from
@@ -26,73 +27,74 @@ This means that you can move, copy and share your troff document without needing
Furthermore, you never run the risk of accidentally losing the references attached to a document.
.It
.Nm
-is around 150 lines of Perl.
+consists of circa 200 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
+is much simpler, much less opaque and offers much more basic functionality than
.Xr refer 1 .
-This means that you can learn all of it in five minutes.
+You can learn all of it in five minutes.
.El
.Pp
The performance of
.Nm
-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:
+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:
.Bl -column "EntriesXXXX" "TimeX" -offset indent
.It Em "Entries\ \ \ \ " Ta Em Time
-.It 3 Ta 0.03s
-.It 50 Ta 0.09s
-.It 107 Ta 0.15s
-.It 182 Ta 0.24s
+.It 3 Ta 0.01s
+.It 50 Ta 0.07s
+.It 100 Ta 0.14s
+.It 200 Ta 0.26s
+.It 500 Ta 0.65s
+.It 2,000 Ta 2.59s
+.It 10,000 Ta 12.94s
.El
.Pp
-I would deem it rare to have more than a couple of hundred unique references in a troff document.
+Luckily, I would deem it extremely rare to have more than a couple of hundred unique references in a troff document.
.
.Sh USAGE
+.Pp
.Nm
-is controlled by several macros, all consisting of one uppercase and one lowercase letter, beginning with either an
-.Sq F
-or an
-.Sq R .
-Macros beginning with
-.Sq R
-control the two primary
-.Dq units
-of
-.Nm :
-.Bl -enum
-.It
-.Em entries
-in the reference list, and
-.It
-.Em inline references
-to these entries.
+provides two features, which it calls
+.Em references
+and
+.Em citations :
+.Bl -tag
+.It Em reference
+a bibliographic entry written at the end of the document
+.It Em citation
+an inline reference to a bibliographic entry
.El
.Pp
-Macros beginning with
-.Sq F ,
-in turn, control the appearance of these two units.
+.Nm
+is controlled by several macros, all consisting of one uppercase and one lowercase letter, beginning with either an
+.Sq R
+\(en macros controlling references and citations \(en
+or an
+.Sq F
+\(en macros controlling the appearance of references and citations.
+.
.Ss Format macros
-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.
.Bl -tag
-.It Sy \&Fe
-Defines the format for reference list entries.
+.It Sy \&Fr
+Defines the format for references in the bibliography.
.Pp
Default: %a (%y). {\\fI%t\\fR}. {\\*Q%q\\*U}. %n, %d. %c: %p. {Available: %w.}
.It Sy \&Ff
Defines the format for
.Dq full
-inline references, which by default contain both author and year.
+citations, which by default contain both author and year.
.Pp
Default: (%A %y)
.It Sy \&Fx
Defines the format for
.Dq alternate
-inline references, which by default contain only the year.
+citations, which by default contain only the year.
.Pp
Default: (%y)
.El
@@ -100,23 +102,23 @@ Default: (%y)
For a description of the format syntax, see
.Sx FORMAT SYNTAX .
.
-.Ss Entry definition macros
-In the reference list, each entry is defined by a
+.Ss Reference definition macros
+In the reference list or bibliography, a single reference is defined by a
.Sy contiguous
-block of lines containing definition macros, describing various
-.Em fields
-belonging to the reference,
-such as author and year.
+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,
.Sy including
-text lines and empty lines.
+text lines, empty lines and lines containing other macros than the ones listed below.
.Bl -tag
.It Sy \&Ra
-Adds to the list of
-.Em authors
-of the current reference.
+Defines the
+.Em author
+of the publication.
+You can use
+.Sy \&Ra
+more than once in order to define multiple authors.
.Pp
-Format: Surname(s), Forename(s)
+Format: Surname, Forename/Initial
.It Sy \&Rc
Defines the
.Em city
@@ -156,52 +158,62 @@ of publication.
.Pp
In the final output,
.Nm
-prints a formatted version of each reference entry in place of its definition.
+prints a formatted version of each reference in place of its definition.
.Nm
-does not change the order of reference entries.
+does not change the order of reference.
This means that you can arrange your references freely.
.
-.Ss Inline reference macros
-To insert an inline reference to an entry in the reference list, you can use one of two macros:
+.Ss Citation macros
+To insert a citation, you can use one of two macros:
.Bl -tag
.It Sy \&Rf
Inserts a
.Dq full
-inline reference, which usually contains both author and year.
+citation, which usually contains both author and year.
.It Sy \&Rx
Inserts an
.Dq alternate
-inline reference, which usually contains only the year.
+citation, which usually contains only the year.
.El
+.
.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.
+.Sy Reference identification.
+\ 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:
+.Bd -literal -offset indent
+\&.Rf Trubetzkoy 1969
+.Ed
+.Pp
+If only a weak match is found, a helpful warning is printed on standard error.
.Pp
-To include some punctuation character immediately after the inline reference, add a space before it:
+.Sy Adjacent punctuation.
+\ To include some punctuation character immediately after the inline reference, use the following syntax:
.Bd -literal -offset indent
-\&.Rf Johnson 92 .
+\&.Rf Grot 1873 .
.Ed
.Pp
To wrap the inline reference in parentheses, use the following syntax:
.Bd -literal -offset indent
-\&.Rf Johnson 92 ) (
+\&.Rf Courtenay 1972 ) (
.Ed
+.
.Pp
-Additionally, any instance of
+.Sy Shortcuts.
+\ 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 ...
+According to Brandt
+\&.Rx '' 1892 ,
+Russian differs from other European languages in its [...]
.Ed
.
.Sh FORMAT SYNTAX
+.Pp
.Ss Interpolation
-In a format definition, use a percent (%)
-sigil followed by a single letter to interpolate any given field of the reference.
+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:
.Bd -literal -offset indent
@@ -227,12 +239,12 @@ syntax, with an uppercase instead of lowercase
A backslash at the end of a format line acts as a line continuation marker.
The newline after the backslash is preserved.
.It
-For format macros describing inline references, a backslash immediately following the macro name will cause the reference be joined to the preceding line.
+For format macros describing citations, a backslash immediately following the macro name will cause the reference be joined to the preceding line.
.El
.Pp
Anywhere else in the line, backslashes are preserved literally.
.Pp
-By using backslashes, you can implement footnote-based references.
+By using backslashes, you can implement footnote-based citations.
For example, using the ms macro package:
.Bd -literal -offset indent
\&.Fx\\ \\**\\
@@ -249,6 +261,7 @@ removes common punctuation immediately preceding and following an unsuccessful i
Excessive spaces are also removed, unless they follow a period, marking the end of a sentence.
.
.Sh EXAMPLE
+.Pp
Below is an example of an ms-based troff document using
.Nm rf
references.
@@ -319,6 +332,7 @@ Smith, P. (2007). \\fIModern Society\\fR. Athens: Logos.
.Ed
.
.Sh AUTHORS
+.Pp
.Nm
was written by John Ankarström
.Aq Mt john (at) ankarstrom.se .