aboutsummaryrefslogtreecommitdiff
path: root/fref.t
blob: 15708df26f3a2b2a2f1f0f096fc67b1753e154b5 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
.\"
.\" 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 formatter for \f(BItroff\fP
.AU
John Ankarström
.DA
.PP
.2C
.SH
Introduction
.PP
\fIfref\fP (\(lqformat reference\(rq)
is a troff preprocessor that formats reference lists
embedded in \fItroff\fP source code.
It supports multiple languages
and is macro package-independent.
.PP
\fIfref\fP has been developed to address concerns
unsatisfactorily met by previous solutions.
It differs from the much beloved \fIrefer\fP
in the following ways:
.in +2n
.IP 1. 3
\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\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\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\fP does not resolve references,
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.
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\fP to be a very fitting solution.
.PP
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 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
Operation
.PP
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, using the \fI-ms\fP macros:
.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
\&%is	Indiana University Press
\&.XP
\&\fI... another reference ...\fP
.PP
\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\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\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\fP dies.
.PP
The hard-coded reference style includes some language-specific words.
The language (English by default) is controlled with the \fI-l\fP flag:
.IP
.nf
.ta 10m
\&$ <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
%is	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.
.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
Reference fields
.PP
\fIfref\fP supports a large number of fields.
All have two-letter names, much like \fItroff\fP requests:
.IP %au
\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\fP.
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
\fIDate (year)\fP.
.IP %ed
\fIEditor\fP.
.IP %hr
\fIHypertext reference\fP.
.IP %jo
\fIJournal\fP.
.IP %la
\fILabel\fP.
Printed at the beginning of the reference,
followed by an equals sign.
.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 %is
\fIIssuer, publisher\fP.
.IP %pg
\fIPage number(s)\fP.
.IP %se
\fITODO: Series\fP.
.IP %ti
\fITitle\fP.
.IP %tr
\fITranslator\fP.
.IP %vo
\fIVolume\fP.
.IP %xx
\fIExtra information\fP.
Printed at the end of the reference,
but before any hypertext reference and access date.
.br
.ne 2i
.SH
Source code
.PP
Users of \fIfref\fP are encouraged to modify
the source code according to their own requirements.
\fIfref\fP is written in C using \fIlex\fP
and contains circa 300 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.