1HXMKBIB(1) HTML-XML-utils HXMKBIB(1)
2
6 hxmkbib - create bibliography from a template
7
9 hxmkbib [ -s separator ] [ -a auxfile ] [ -n maxauthors ] [ -r moreau‐
10 thors ] bibfile [ templatefile ]
11
13 The hxmkbib commands reads a list of bibliographic keys (labels) from
14 auxfile, finds the corresponding entries in bibfile and creates a bib‐
15 liography, using templatefile as a model. The auxfile may, e.g., have
16 been created by hxcite(1). It consists of labels, one per line. The
17 bibfile is a refer(1) style database. hxmkbib looks for entries with a
18 %L field equal to a key in the auxfile.
19 The templatefile consists of three parts:
21 preamble The preamble is the part up to the first occurrence of %{.
23 The preamble is copied to the output unchanged, except for
24 occurrences of %. To create a single % in the output, there
25 must be two in the preamble (%%). All other occurrences of %
26 followed by another letter are not copied, but are collected
27 into a string called the "sort order." and use to sort the
28 entries, as explained below.
29 template The template starts with %{L: and ends with a matching %}.
31 The text in between is copied as often as there are biblio‐
32 graphic entries in bibfile that correspond to keys in aux‐
33 file. Variables in the template are replaced by the corre‐
34 sponding field in the bibliographic entry: all occurrences of
35 %x will be replaced by the field %x of the entry. Parts of
36 the text may be enclosed in %{x: and %}. This means that the
37 text in between should only be output if the current entry
38 has a field x. Text that is enclosed in %{!x: and %} will
39 only be output if the entry does not have a field x. Both
40 kinds of conditional sections may also be nested.
41 postamble The text after the %} is copied unchanged to the output,
43 after all bibliographic entries have been processed.
44 By default bibliographic entries are copied to the output in the order
46 of the keys in auxfile, except that keys that occur more than once are
47 only used once. If the preamble contains occurrences of %x (where x is
48 neither "%" nor "{") then these together determine the sort order.
49 E.g., if the preamble contains %A%D then the entries will be sorted
50 first on field A (author) and then on field D (date).
51 Here is an example of template file that creates a bibliography in HTML
53 format:
54 <html>
56 <title>Bibliography</title>
57 <!--%A%D sorted on author, then date -->
58 <dl>
59 %{L:
60 <dt id="%L">%{A:A%}%{!A:%{E:E%}%{!E:%{Q:Q%}%{!Q:-%}%}%}</dt>
61 <dd>%{B:"%T"
62 in: %{E:%E (eds)
63 %}<cite>%B.</cite>%{V: %V.%}
64 %}%{J:"%T"
65 in: %{E:%E (eds)
66 %}<cite>%J.</cite>%{V: %V.%}%{N: %N.%}%{P: pp. %P.%}
67 %}%{!B:%{!J:<cite>%T.</cite>
68 %}%}%{I:%I.
69 %}%{D:%D.
70 %}%{C:%C.
71 %}%{R:%R.
72 %}%{S:%S.
73 %}%{O:%O
74 %}%{U:<a href="%U">%U</a>
75 %}</dd>
76 %}
77 </dl>
78 </html>
79 This template starts with four lines of preamble, including the sort
81 string %A%D on line 3. The sort string itself will not be output, but
82 the rest of the comment will.
83 From the line %{L: to the line %} is the template. E.g., the line that
85 starts with <dt id=... contains a complex conditional text that prints
86 the authors (%A) if there are any, otherwise the editors (%E) if there
87 are any, otherwise the institution that is the author (%Q), if any, and
88 a dash otherwise. Note how the parts are nested, Most of the text is
89 inside %{!A:...%}, meaning that that part will only be effective if
90 there is no author field (%A).
91 The final two lines are the postamble and will simply be copied
93 unchanged.
94 A bibliographic entry that looks like this in bibfile:
96 %L Java
98 %A Gosling, James
99 %A Joy, Bill
100 %A Steele, Guy
101 %T The Java language specification
102 %D 1998
103 %I Addison-Wesley
104 %U http://java.sun.com/docs/books/jls/index.html
105 will be printed by the template above as:
107 <dt id="Java">Gosling, James; Joy, Bill; Steele, Guy</dt>
109 <dd><cite>The Java language specification.</cite>
110 Addison-Wesley.
111 1998.
112 <a href="http://java.sun.com/docs/books/jls/index.html">http://java.sun.com/docs/books/jls/index.html</a>
113 </dd>
114
117 The following options are supported:
118 -a auxfile
120 The file that contains the list of keys (labels) for which
121 bibliographic entries should be printed. If the option is
122 absent, the name of this file is formed from the templatefile
123 argument by removing the last extension and adding .aux. If
124 no templatefile is given, the default auxfile is aux.aux.
125 -s separator
127 If there are multiple authors or editors in an entry, their
128 names will be listed with a separator in between. By default
129 the separator is "; " (i.e., a semicolon and a space). With
130 this option the separator can be changed.
131 -n maxauthors
133 If there are more than maxauthors authors in an entry, only
134 the first author will be printed and the others will be
135 replaced by the string moreauthors. The default is 3.
136 -r moreauthors
138 The string to print if there are more than maxauthors
139 authors. The default is "et al.".
140
142 The following operands are supported:
143 bibfile The name of a bibliographic database must be given. It must
145 be a file in refer(1) format and every entry must have at
146 least a %L field, which is used as key. (Entries without such
147 a field will be ignored.)
148 templatefile
150 The name of the input file is optional. If absent, hxmkbib
151 will read the template from stdin.
152
154 The following exit values are returned:
155 0 Successful completion.
157 > 0 An error occurred. Usually this is because a file could not
159 be opened or because the %{ and %} pairs are not properly
160 nested. Very rarely it may also be an out of memory error.
161 Some of the possible error messages:
162 missing ':' in pattern
164 hxmkbib found a %{ but the second or third letter after it
165 was not a colon.
166 no '%{' in template file
168 The template file is unusable, because it contains no tem‐
169 plate.
170 unbalanced %{..%} in pattern
172 There are more %{ than %}.
173
175 asc2xml(1), hxcite(1), hxnormalize(1), hxnum(1), hxprune(1), hxtoc(1),
176 hxunent(1), xml2asc(1), UTF-8 (RFC 2279)
177
179 Sorting is primitive: the program doesn't parse dates or names and sim‐
180 ply sorts "Jan 2000" under the letter "J" and "Albert Camus" under the
181 letter "A". For the moment the only work-around is to put names in the
182 bibfile as "Camus, Albert".
183 The program simply lists all authors or editors. There is no way to
185 generate an "et. al." after the third one. The work-around is to put
186 the "et. al." in the bibfile. Putting commas between the first authors
187 and the word "and" before the final one is also not possible.
188 The program doesn't try to interpret names of authors or editors and
190 they cannot be reformatted. It is impossible to write a name that is
191 specified as "Sartre, Jean-Paul" in the bibfile as "J. Sartre" or as
192 "Jean-Paul Sartre" in the output.
193 There is no way to suppress a period after a field if the field already
195 ends with a period. E.g., the template "%{A:A.%}" may generate "A. Per‐
196 son Jr.." if the author is "A. Person Jr." The only option is to either
197 not put periods in the bibfile or not put periods in the template.
198 Entries in the bibfile can only be used if they have a %L (label)
200 field. The program cannot find entries by searching for keywords, like
201 refer(1).
202 hxmkbib will replace any ampersands (&) and less-than (<) and greater-
204 than (>) signs that occur in the bibfile by their XML entities &
205 < > on the assumption that the template is HTML/XML. This may not
206 be appropriate for other formats.
2075.x 21 Nov 2008 HXMKBIB(1)