diff options
Diffstat (limited to 'fref.t')
| -rw-r--r-- | fref.t | 144 |
1 files changed, 96 insertions, 48 deletions
@@ -17,40 +17,40 @@ John Ankarström .SH Introduction .PP -\fIfref\fR (\(lqformat reference\(rq) +\fIfref\fP (\(lqformat reference\(rq) is a troff preprocessor that formats reference lists -embedded in the \fItroff\fR source code +embedded in the \fItroff\fP source code according to the Harvard system. It supports multiple languages and is macro package-independent. .PP -\fIfref\fR has been developed to address concerns +\fIfref\fP has been developed to address concerns unsatisfactorily met by previous solutions. -It differs from the much beloved \fIrefer\fR +It differs from the much beloved \fIrefer\fP in the following ways: .in +2n .IP 1. 3 -\fIfref\fR is a reference \fIformatter\fP, -not a reference \fIresolver\fR like \fIrefer\fP. +\fIfref\fP is a reference \fIformatter\fP, +not a reference \fIresolver\fP like \fIrefer\fP. It formats references specified in the troff source, not in an external database. .IP 2. 3 As a result of the first point, -\fIfref\fR requires no macro package support, -unlike \fIrefer\fR, which relies on macro packages +\fIfref\fP requires no macro package support, +unlike \fIrefer\fP, which relies on macro packages to do the formatting. .IP 3. 3 As a further result of the first point, -\fIfref\fR is a much simpler program than \fIrefer\fP +\fIfref\fP is a much simpler program than \fIrefer\fP and is thus easier for the user to extend according to his own preferences. .in .PP -Because \fIfref\fR does not resolve references, +Because \fIfref\fP does not resolve references, it is limited in its functionality. It is not a good fit for reference styles that require elaborate inline citations. -For this reason, \fIfref\fR is primarily designed +For this reason, \fIfref\fP is primarily designed for reference styles with simple inline citations, such as the Harvard system, that the user can type himself without much trouble. @@ -58,20 +58,22 @@ Indeed, for parenthetical citations, it is likely quicker to manually type the citation than to instruct the computer to generate it. In such cases, I hope you will find -\fIfref\fR to be a very fitting solution. +\fIfref\fP to be a very fitting solution. .PP If you do use the Harvard system, -\fIfref\fR offers many benefits over \fIrefer\fP. -While the format of \fIrefer\fR references +\fIfref\fP offers many benefits over \fIrefer\fP. +While the format of \fIrefer\fP references depend on the macro package one uses, -the output of \fIfref\fR is completely independent +the output of \fIfref\fP is completely independent of any macro package. -Furthermore, \fIfref\fR supports a richer variety of reference fields, +Furthermore, \fIfref\fP supports a richer variety of reference fields, such as translator and hypertext reference. +.br +.ne 2i .SH Operation .PP -The \fIfref\fR program takes \fItroff\fP source code on standard input +The \fIfref\fP program takes \fItroff\fP source code on standard input and emits the same on standard output. Lines beginning with `%' (percent) are processed specially. Each such line denotes a field in a reference. @@ -90,89 +92,135 @@ References \&%ci Bloomington \&%pu Indiana University Press \&.XP -\&\fI... another reference ...\fR +\&\fI... another reference ...\fP .PP -\fIfref\fR collects all percent lines +\fIfref\fP collects all percent lines until the next non-percent line, at which point a formatted reference is generated from the information specified in the fields. In the example above, -the second .XP line will trigger \fIfref\fR +the second .XP line will trigger \fIfref\fP to print a reference containing all the fields gathered thus far. .PP If, for some reason, a specified field -is left out by \fIfref\fR, +is left out by \fIfref\fP, a warning is emitted on standard error. This might happen if an %ed (editor) field has been specified without a corresponding %bo (book) or %jo (journal) field. .PP If an unknown field is specified, -\fIfref\fR dies. +\fIfref\fP dies. .PP The hard-coded reference style includes some language-specific words. -The language (English by default) is controlled with the \fI-l\fR flag: +The language (English by default) is controlled with the \fI-l\fP flag: .IP .nf .ta 10m -\&$ <example.t fref -lsv \fI# Swedish\fR -\&$ <example.t fref -lru \fI# Russian\fR +\&$ <example.t fref -lsv \fI# Swedish\fP +\&$ <example.t fref -lru \fI# Russian\fP +.br +.ne 2i +.SH +Example +.PP +The reference listed earlier is rendered thus: +.br +.po -5n+5p +.B1 +.XP +%au Baudouin de Courtenay, J. +%da 1972 +%ti The Difference between Phonetics and Psychophonetics +%bo A Baudouin de Courtenay Anthology +%ed T. A. Sebeok et al. +%tr Edward Stankiewicz +%ci Bloomington +%pu Indiana University Press +.B2 +.po +.PP +The above reference was generated by processing the document's +source code with \fIfref\fP before passing it to \fItroff\fP: +.IP +$ <fref.t fref | troff | dpost | ps2pdf - >fref.pdf +.PP +Note that \fIfref\fP leaves the job of +arranging the references alphabetically +to the document author. +The benefit is that the author is free to put arbitrary troff requests +between references. +.br +.ne 2i .SH Reference fields .PP -\fIfref\fR supports a large number of fields. -All have two-letter names, much like \fItroff\fR requests: +\fIfref\fP supports a large number of fields. +All have two-letter names, much like \fItroff\fP requests: .IP %au -\fIAuthor\fR. +\fIAuthor\fP. This is the only field of which more than one instance is allowed. Note that the author name is output as is. .IP %ad -\fIAccess date\fR. +\fIAccess date\fP. This field is output after a hypertext reference. .IP %bo -\fIBook\fR. +\fIBook\fP. .IP %ci -\fICity\fR. +\fICity\fP. .IP %da -\fIDate (year)\fR. +\fIDate (year)\fP. .IP %ed -\fIEditor\fR. +\fIEditor\fP. .IP %hr -\fIHypertext reference\fR. +\fIHypertext reference\fP. .IP %jo -\fIJournal\fR. +\fIJournal\fP. .IP %la -\fILabel\fR. +\fILabel\fP. This field is output at the beginning of the reference, followed by an equals sign. .IP %lg -\fIReference-specific language\fR. -This field temporarily overrides the \fI-l\fR flag +\fIReference-specific language\fP. +This field temporarily overrides the \fI-l\fP flag and the default language of English for a single reference. .IP %no -\fITODO: Issue number\fR. +\fITODO: Issue number\fP. .IP %pp -\fIPages\fR. +\fIPages\fP. .IP %pu -\fIPublisher\fR. +\fIPublisher\fP. .IP %se -\fITODO: Series\fR. +\fITODO: Series\fP. .IP %ti -\fITitle\fR. +\fITitle\fP. .IP %tr -\fITranslator\fR. +\fITranslator\fP. .IP %vo -\fIVolume\fR. +\fIVolume\fP. .IP %xx -\fIExtra information\fR. +\fIExtra information\fP. The text is output at the end of the reference, but before any hypertext reference and access date. +.br +.ne 2i .SH Source code .PP -Users of \fIfref\fR are encouraged to modify +Users of \fIfref\fP are encouraged to modify the source code according to their own requirements. -\fIfref\fR is written in C using \fIlex\fR +\fIfref\fP is written in C using \fIlex\fP and contains circa 330 lines of code. +Modification of the source code is required +by endeavors such as +changing the reference format, +defining additional fields and +adding support for additional languages. +.PP +The benefit of writing the formatting code in C +is that the programmer has a full-fledged +programming language at his disposal. +For the string-based operations required by reference formatting, +\fItroff\fP requests tend to fall short. |