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
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
|
.de d \" begin display
.sp
.in +4
.nf
..
.de e \" end display
.in -4
.fi
.sp
..
.TH "HXMKBIB" "1" "10 Jul 2011" "7.x" "HTML-XML-utils"
.SH NAME
hxmkbib \- create bibliography from a template
.SH SYNOPSIS
.B hxmkbib
.RB "[\| " \-s
.IR separator " \|]"
.RB "[\| " \-a
.IR auxfile " \|]"
.RB "[\| " \-n
.IR maxauthors " \|]"
.RB "[\| " \-r
.IR moreauthors " \|]"
.IR bibfile " [\| " templatefile " \|]"
.SH DESCRIPTION
.LP
The
.B hxmkbib
commands reads a list of bibliographic keys (labels) from
.IR auxfile ,
finds the corresponding entries in
.I bibfile
and creates a bibliography, using
.I templatefile
as a model. The
.I auxfile
may, e.g., have been created by
.BR hxcite (1).
It consists of labels, one per line. The
.I bibfile
is a
.BR refer (1)
style database.
.B hxmkbib
looks for entries with a
.B %L
field equal to a key in the
.IR auxfile .
.PP
The
.I templatefile
consists of three parts:
.TP 10
.B preamble
The preamble is the part up to the first occurrence of
.BR %{ .
The preamble is copied to the output unchanged, except for occurrences
of
.BR % .
To create a single % in the output, there must be two in the preamble
(%%). All other occurrences of % followed by another letter are not
copied, but are collected into a string called the "sort order." and
use to sort the entries, as explained below.
.TP
.B template
The template starts with
.B %{L:
and ends with a matching
.BR %} .
The text in between is copied as often as there are bibliographic
entries in
.I bibfile
that correspond to keys in
.IR auxfile .
Variables in the template are replaced by the corresponding field in
the bibliographic entry: all occurrences of
.BI % x
will be replaced by the field
.BI % x
of the entry. Parts of the text may be enclosed in
.BI %{ x :
and
.BR %} .
This means that the text in between should only be output if the
current entry has a field
.IR x .
Text that is enclosed in
.BI %{! x :
and
.B %}
will only be output if the entry does
.B not
have a field
.IR x .
Both kinds of conditional sections may also be nested.
.TP
.B postamble
The text after the
.B %}
is copied unchanged to the output, after all bibliographic entries
have been processed.
.PP
By default bibliographic entries are copied to the output in the order
of the keys in
.IR auxfile ,
except that keys that occur more than once are only used once. If the
preamble contains occurrences of
.BI % x
(where
.I x
is neither "%" nor "{") then these together determine the sort order.
E.g., if the preamble contains %A%D then the entries will be sorted
first on field A (author) and then on field D (date).
.PP
Here is an example of template file that creates a bibliography in
HTML format:
.d
<html>
<title>Bibliography</title>
<!--%A%D sorted on author, then date -->
<dl>
%{L:
<dt id="%L">%{A:%A%}%{!A:%{E:%E%}%{!E:%{Q:%Q%}%{!Q:-%}%}%}</dt>
<dd>%{B:"%T"
in: %{E:%E (eds)
%}<cite>%B.</cite>%{V: %V.%}
%}%{J:"%T"
in: %{E:%E (eds)
%}<cite>%J.</cite>%{V: %V.%}%{N: %N.%}%{P: pp. %P.%}
%}%{!B:%{!J:<cite>%T.</cite>
%}%}%{I:%I.
%}%{D:%D.
%}%{C:%C.
%}%{R:%R.
%}%{S:%S.
%}%{O:%O
%}%{U:<a href="%U">%U</a>
%}</dd>
%}
</dl>
</html>
.e
This template starts with four lines of preamble, including the sort
string %A%D on line 3. The sort string itself will not be output, but
the rest of the comment will.
.PP
From the line
.B %{L:
to the line
.B %}
is the template. E.g., the line that
starts with
.B <dt id=...
contains a complex conditional text that prints the authors (%A) if
there are any, otherwise the editors (%E) if there are any, otherwise
the institution that is the author (%Q), if any, and a dash otherwise.
Note how the parts are nested, Most of the text is inside
.BR %{!A:...%} ,
meaning that that part will only be effective if there is no author
field (%A).
.PP
The final two lines are the postamble and will simply be copied
unchanged.
.PP
A bibliographic entry that looks like this in
.IR bibfile :
.d
%L Java
%A Gosling, James
%A Joy, Bill
%A Steele, Guy
%T The Java language specification
%D 1998
%I Addison-Wesley
%U http://java.sun.com/docs/books/jls/index.html
.e
will be printed by the template above as:
.d
<dt id="Java">Gosling, James; Joy, Bill; Steele, Guy</dt>
<dd><cite>The Java language specification.</cite>
Addison-Wesley.
1998.
<a href="http://java.sun.com/docs/books/jls/index.html">http://java.sun.com/docs/books/jls/index.html</a>
</dd>
.e
.SH OPTIONS
The following options are supported:
.TP 10
.BI \-a " auxfile"
The file that contains the list of keys (labels) for which
bibliographic entries should be printed. If the option is absent, the
name of this file is formed from the
.I templatefile
argument by removing the last extension and adding
.BR .aux .
If no
.I templatefile
is given, the default
.I auxfile
is
.BR aux.aux .
.TP
.BI \-s " separator"
If there are multiple authors or editors in an entry, their names will
be listed with a separator in between. By default the separator is ";
" (i.e., a semicolon and a space). With this option the separator can
be changed.
.TP
.BI \-n " maxauthors"
If there are more than
.I maxauthors
authors in an entry, only the first author will be printed and the
others will be replaced by the string
.IR moreauthors .
The default is 3.
.TP
.BI \-r " moreauthors"
The string to print if there are more than
.I maxauthors
authors. The default is "et al.".
.SH OPERANDS
The following operands are supported:
.TP 10
.I bibfile
The name of a bibliographic database must be given. It must be a file
in
.BR refer (1)
format and every entry must have at least a
.B %L
field, which is used as key. (Entries without such a field will be
ignored.)
.TP
.I templatefile
The name of the input file is optional. If absent,
.B hxmkbib
will read the template from stdin.
.SH "DIAGNOSTICS"
The following exit values are returned:
.TP 10
.B 0
Successful completion.
.TP
.B > 0
An error occurred. Usually this is because a file could not be opened
or because the %{ and %} pairs are not properly nested.
Very rarely it may also be an out of memory error. Some of the
possible error messages:
.TP
.I missing ':' in pattern
.B hxmkbib
found a %{ but the second or third letter after it was not a colon.
.TP
.I no '%{' in template file
The template file is unusable, because it contains no template.
.TP
.I unbalanced %{..%} in pattern
There are more %{ than %}.
.SH "SEE ALSO"
.BR asc2xml (1),
.BR hxcite (1),
.BR hxnormalize (1),
.BR hxnum (1),
.BR hxprune (1),
.BR hxtoc (1),
.BR hxunent (1),
.BR xml2asc (1),
.BR UTF-8 " (RFC 2279)"
.SH BUGS
Sorting is primitive: the program doesn't parse dates or names and
simply sorts "Jan 2000" under the letter "J" and "Albert Camus" under
the letter "A". For the moment the only work-around is to put names in
the
.I bibfile
as "Camus, Albert".
.PP
The program simply lists all authors or editors. There is no way to
generate an "et. al." after the third one. The work-around is to put
the "et. al." in the
.IR bibfile .
Putting commas between the first authors and the word "and" before the
final one is also not possible.
.PP
The program doesn't try to interpret names of authors or editors and
they cannot be reformatted. It is impossible to write a name that is
specified as "Sartre, Jean-Paul" in the
.I bibfile
as "J. Sartre" or as "Jean-Paul Sartre" in the output.
.PP
There is no way to suppress a period after a field if the field
already ends with a period. E.g., the template "%{A:A.%}" may generate
"A. Person Jr.." if the author is "A. Person Jr." The only option is
to either not put periods in the
.IR bibfile
or not put periods in the template.
.PP
Entries in the
.I bibfile
can only be used if they have a
.B %L
(label) field. The program cannot find entries by searching for
keywords, like
.BR refer (1).
.PP
.B hxmkbib
will replace any ampersands (&) and less-than (<) and greater-than (>)
signs that occur in the
.I bibfile
by their XML entities & < > on the assumption that the
template is HTML/XML. This may not be appropriate for other formats.
|
