.\" .\" Use the following commands to build this document: .\" $ export LC_ALL=en_US.UTF-8 .\" $ fref.pdf .\" .do mediasize letter .nr LL 6.5i .ss 12 0 .TL \f(BIfref\fP, reference list formatter for \f(BItroff\fP .AU John Ankarström .DA .PP .2C .SH Introduction .PP \fIfref\fP (\(lqformat reference\(rq) is a troff preprocessor that formats reference lists embedded in the \fItroff\fP source code according to the Harvard system. It supports multiple languages and is macro package-independent. .PP \fIfref\fP has been developed to address concerns unsatisfactorily met by previous solutions. It differs from the much beloved \fIrefer\fP in the following ways: .in +2n .IP 1. 3 \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\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\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\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\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. 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\fP to be a very fitting solution. .PP If you do use the Harvard system, \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\fP is completely independent of any macro package. Furthermore, \fIfref\fP supports a richer variety of reference fields, such as translator and hypertext reference. .br .ne 2i .SH Operation .PP 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. For example: .IP .nf \&.SH References \&.XP \&%au Baudouin de Courtenay, J. \&%da 1972 \&%ti The Difference between Phonetics and ... \&%bo A Baudouin de Courtenay Anthology \&%ed T. A. Sebeok et al. \&%tr Edward Stankiewicz \&%ci Bloomington \&%pu Indiana University Press \&.XP \&\fI... another reference ...\fP .PP \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\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\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\fP dies. .PP The hard-coded reference style includes some language-specific words. The language (English by default) is controlled with the \fI-l\fP flag: .IP .nf .ta 10m \&$ 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\fP supports a large number of fields. All have two-letter names, much like \fItroff\fP requests: .IP %au \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\fP. This field is output after a hypertext reference. .IP %bo \fIBook\fP. .IP %ci \fICity\fP. .IP %da \fIDate (year)\fP. .IP %ed \fIEditor\fP. .IP %hr \fIHypertext reference\fP. .IP %jo \fIJournal\fP. .IP %la \fILabel\fP. This field is output at the beginning of the reference, followed by an equals sign. .IP %lg \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\fP. .IP %pp \fIPages\fP. .IP %pu \fIPublisher\fP. .IP %se \fITODO: Series\fP. .IP %ti \fITitle\fP. .IP %tr \fITranslator\fP. .IP %vo \fIVolume\fP. .IP %xx \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\fP are encouraged to modify the source code according to their own requirements. \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.