diff options
Diffstat (limited to 'rf.1')
| -rw-r--r-- | rf.1 | 189 |
1 files changed, 189 insertions, 0 deletions
@@ -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 . |