diff options
| -rwxr-xr-x | rf | 12 | ||||
| -rw-r--r-- | rf.1 | 146 |
2 files changed, 86 insertions, 72 deletions
@@ -6,7 +6,7 @@ use warnings; # Default configuration my %fmt; -$fmt{e} = '%a (%y). {\fI%t\fR}. {\*Q%q\*U}. %n, %d. %c: %p. {Available: %w.}'; +$fmt{r} = '%a (%y). {\fI%t\fR}. {\*Q%q\*U}. %n, %d. %c: %p. {Available: %w.}'; $fmt{f} = "\n(%A %y)"; $fmt{x} = "\n(%y)"; @@ -21,7 +21,7 @@ while (<>) { chomp; # Format specification - if (/^\.F([efx])(\\?) +(.*)/) { + if (/^\.F([rfx])(\\?) +(.*)/) { my ($type, $join, $rest) = ($1, $2, $3); $rest = "\n$rest" if not $join; while (not eof()) { @@ -37,7 +37,7 @@ while (<>) { push @lines, $_; } -# Second pass (process reference definitions and inline references) +# Second (backwards) pass (process reference definitions and inline citations) my $inlref = 0; my @r = (); @@ -47,7 +47,7 @@ for (my $i = $#lines; $i >= 0; $i--) { $_ = $lines[$i]; chomp; - # Entry definition + # Reference definition if (/^\.R([acdnpqtwy]) +(.*)/) { my ($fld, $rest) = ($1, $2); @@ -62,10 +62,10 @@ for (my $i = $#lines; $i >= 0; $i--) { next; } elsif ($refblock) { # print formatted reference definition - push @r, fmt($fmt{e}, $refi) . "\n"; + push @r, fmt($fmt{r}, $refi) . "\n"; } - # Inline reference + # Inline citation if (/^\.R([fx]) +(.*)/) { my ($fld, $rest) = ($1, $2, $3); @@ -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 . |