Rename some fields

1 files changed, 54 insertions, 22 deletions

diff --git a/fref.t b/fref.t
index 7a5e426..269176c 100644
--- a/fref.t
+++ b/fref.t
@@ -8,7 +8,7 @@
 .ss 12 0
 .TL
 \f(BIfref\fP,
-reference list formatter for \f(BItroff\fP
+reference formatter for \f(BItroff\fP
 .AU
 John Ankarström
 .DA
@@ -19,8 +19,7 @@ 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.
+embedded in \fItroff\fP source code.
 It supports multiple languages
 and is macro package-independent.
 .PP
@@ -47,10 +46,10 @@ 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
+it is not a good fit for reference styles that require
+elaborate or numbered inline citations.
+.PP
+Instead, \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.
@@ -64,10 +63,16 @@ 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.
+the output of \fIfref\fP is the same
+regardless of which macros are used.
 Furthermore, \fIfref\fP supports a richer variety of reference fields,
 such as translator and hypertext reference.
+.PP
+In summary,
+\fIfref\fP is a solution to the problem of reference list formatting,
+independent of the macro package used.
+It does not address the problem of inline reference resolution,
+which is largely a non-problem for users of the Harvard system.
 .br
 .ne 2i
 .SH
@@ -77,7 +82,7 @@ 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:
+For example, using the \fI-ms\fP macros:
 .IP
 .nf
 \&.SH
@@ -90,7 +95,7 @@ References
 \&%ed	T. A. Sebeok et al.
 \&%tr	Edward Stankiewicz
 \&%ci	Bloomington
-\&%pu	Indiana University Press
+\&%is	Indiana University Press
 \&.XP
 \&\fI... another reference ...\fP
 .PP
@@ -136,7 +141,7 @@ The reference listed earlier is rendered thus:
 %ed	T. A. Sebeok et al.
 %tr	Edward Stankiewicz
 %ci	Bloomington
-%pu	Indiana University Press
+%is	Indiana University Press
 .B2
 .po
 .PP
@@ -150,6 +155,32 @@ arranging the references alphabetically
 to the document author.
 The benefit is that the author is free to put arbitrary troff requests
 between references.
+.PP
+It is also possible to the reference in a separate file,
+similarly to what is done with \fIrefer\fP,
+and process the file separately from the main document:
+.IP
+$ <refs.f fref >refs.t
+.PP
+The resulting file refs.t might be included in the main document like so:
+.IP
+.nf
+\&.SH
+References
+\&.so refs.t
+.PP
+If you do this, you may want to consider using the .blm request
+to automatically start a new extended paragraph before every reference:
+.IP
+.nf
+\&.SH
+Reference
+\&.blm XP
+\&.XP
+\&.so refs.t
+\&.blm
+.PP
+This way, you can store your references in refs.f separated by a blank space.
 .br
 .ne 2i
 .SH
@@ -164,9 +195,10 @@ 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.
+Printed after a hypertext reference.
 .IP %bo
 \fIBook\fP.
+Used for the book in which an article is published.
 .IP %ci
 \fICity\fP.
 .IP %da
@@ -179,19 +211,19 @@ This field is output after a hypertext reference.
 \fIJournal\fP.
 .IP %la
 \fILabel\fP.
-This field is output at the beginning of the reference,
+Printed 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
+.IP %lc
+\fIReference-specific language\fP (\(lqlocale\(rq).
+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 %is
+\fIIssuer, publisher\fP.
+.IP %pg
+\fIPage number(s)\fP.
 .IP %se
 \fITODO: Series\fP.
 .IP %ti
@@ -202,7 +234,7 @@ for a single reference.
 \fIVolume\fP.
 .IP %xx
 \fIExtra information\fP.
-The text is output at the end of the reference,
+Printed at the end of the reference,
 but before any hypertext reference and access date.
 .br
 .ne 2i