From dc6de7e4c07d4f7fb7827b4a9a156c2b8f643feb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?John=20Ankarstr=C3=B6m?= Date: Tue, 20 Jul 2021 20:54:13 +0200 Subject: Add fref.t document --- fref.pdf | Bin 0 -> 27169 bytes fref.t | 178 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 178 insertions(+) create mode 100644 fref.pdf create mode 100644 fref.t diff --git a/fref.pdf b/fref.pdf new file mode 100644 index 0000000..152f89a Binary files /dev/null and b/fref.pdf differ diff --git a/fref.t b/fref.t new file mode 100644 index 0000000..0765dec --- /dev/null +++ b/fref.t @@ -0,0 +1,178 @@ +.\" +.\" 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\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 +\&$