diff options
Diffstat (limited to 'fref.t')
| -rw-r--r-- | fref.t | 178 |
1 files changed, 178 insertions, 0 deletions
@@ -0,0 +1,178 @@ +.\" +.\" Use the following commands to build this document: +.\" $ export LC_ALL=en_US.UTF-8 +.\" $ <fref.t ./fref | troff -ms | dpost | ps2pdf - >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\fR (\(lqformat reference\(rq) +is a troff preprocessor that formats reference lists +embedded in the \fItroff\fR 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 +unsatisfactorily met by previous solutions. +It differs from the much beloved \fIrefer\fR +in the following ways: +.in +2n +.IP 1. 3 +\fIfref\fR is a reference \fIformatter\fP, +not a reference \fIresolver\fR 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 +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 +and is thus easier for the user to extend +according to his own preferences. +.in +.PP +Because \fIfref\fR 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 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\fR 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 +depend on the macro package one uses, +the output of \fIfref\fR is completely independent +of any macro package. +Furthermore, \fIfref\fR supports a richer variety of reference fields, +such as translator and hypertext reference. +.SH +Operation +.PP +The \fIfref\fR 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 ...\fR +.PP +\fIfref\fR 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 +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, +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. +.PP +The hard-coded reference style includes some language-specific words. +The language (English by default) is controlled with the \fI-l\fR flag: +.IP +.nf +.ta 10m +\&$ <example.t fref -lsv \fI# Swedish\fR +\&$ <example.t fref -lru \fI# Russian\fR +.SH +Reference fields +.PP +\fIfref\fR supports a large number of fields. +All have two-letter names, much like \fItroff\fR requests: +.IP %au +\fIAuthor\fR. +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. +This field is output after a hypertext reference. +.IP %bo +\fIBook\fR. +.IP %ci +\fICity\fR. +.IP %da +\fIDate (year)\fR. +.IP %ed +\fIEditor\fR. +.IP %hr +\fIHypertext reference\fR. +.IP %jo +\fIJournal\fR. +.IP %la +\fILabel\fR. +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 +and the default language of English +for a single reference. +.IP %no +\fITODO: Issue number\fR. +.IP %pp +\fIPages\fR. +.IP %pu +\fIPublisher\fR. +.IP %se +\fITODO: Series\fR. +.IP %ti +\fITitle\fR. +.IP %tr +\fITranslator\fR. +.IP %vo +\fIVolume\fR. +.IP %xx +\fIExtra information\fR. +The text is output at the end of the reference, +but before any hypertext reference and access date. +.SH +Source code +.PP +Users of \fIfref\fR are encouraged to modify +the source code according to their own requirements. +\fIfref\fR is written in C using \fIlex\fR +and contains circa 330 lines of code. |