Add fref.t document

2 files changed, 178 insertions, 0 deletions

diff --git a/fref.pdf b/fref.pdf
new file mode 100644
index 0000000..152f89a
--- /dev/null
+++ b/fref.pdf
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.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.