Update fref.t

2 files changed, 96 insertions, 48 deletions

diff --git a/fref.pdf b/fref.pdf
index 152f89a..4dce886 100644
--- a/fref.pdf
+++ b/fref.pdf
diff --git a/fref.t b/fref.t
index 0765dec..7a5e426 100644
--- a/fref.t
+++ b/fref.t
@@ -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.