NAME¶
hxmkbib - create bibliography from a template
SYNOPSIS¶
hxmkbib [
-s separator ] [
-a auxfile ] [
-n maxauthors ] [
-r moreauthors ]
bibfile
[
templatefile ]
DESCRIPTION¶
The
hxmkbib commands reads a list of bibliographic keys (labels) from
auxfile, finds the corresponding entries in
bibfile and creates
a bibliography, using
templatefile as a model. The
auxfile may,
e.g., have been created by
hxcite(1). It consists of labels, one per
line. The
bibfile is a
refer(1) style database.
hxmkbib
looks for entries with a
%L field equal to a key in the
auxfile.
The
templatefile consists of three parts:
- preamble
- The preamble is the part up to the first occurrence of
%{. The preamble is copied to the output unchanged, except for
occurrences of %. 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.
- template
- The template starts with %{L: and ends with a
matching %}. The text in between is copied as often as there are
bibliographic entries in bibfile that correspond to keys in
auxfile. Variables in the template are replaced by the
corresponding field in the bibliographic entry: all occurrences of
%x will be replaced by the field %x of the
entry. Parts of the text may be enclosed in %{x: and
%}. This means that the text in between should only be output if
the current entry has a field x. Text that is enclosed in
%{!x: and %} will only be output if the entry
does not have a field x. Both kinds of conditional sections
may also be nested.
- postamble
- The text after the %} is copied unchanged to the
output, after all bibliographic entries have been processed.
By default bibliographic entries are copied to the output in the order of the
keys in
auxfile, except that keys that occur more than once are only
used once. If the preamble contains occurrences of
%x (where
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).
Here is an example of template file that creates a bibliography in HTML format:
<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>
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.
From the line
%{L: to the line
%} is the template. E.g., the line
that starts with
<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
%{!A:...%}, meaning that that part will only be effective if there is
no author field (%A).
The final two lines are the postamble and will simply be copied unchanged.
A bibliographic entry that looks like this in
bibfile:
%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
will be printed by the template above as:
<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>
OPTIONS¶
The following options are supported:
- -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 templatefile argument by removing
the last extension and adding .aux. If no templatefile is
given, the default auxfile is aux.aux.
- -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.
- -n maxauthors
- If there are more than maxauthors authors in an
entry, only the first author will be printed and the others will be
replaced by the string moreauthors. The default is 3.
- -r moreauthors
- The string to print if there are more than
maxauthors authors. The default is "et al.".
OPERANDS¶
The following operands are supported:
- bibfile
- The name of a bibliographic database must be given. It must
be a file in refer(1) format and every entry must have at least a
%L field, which is used as key. (Entries without such a field will
be ignored.)
- templatefile
- The name of the input file is optional. If absent,
hxmkbib will read the template from stdin.
DIAGNOSTICS¶
The following exit values are returned:
- 0
- Successful completion.
- > 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:
- missing ':' in pattern
- hxmkbib found a %{ but the second or third letter
after it was not a colon.
- no '%{' in template file
- The template file is unusable, because it contains no
template.
- unbalanced %{..%} in pattern
- There are more %{ than %}.
SEE ALSO¶
asc2xml(1),
hxcite(1),
hxnormalize(1),
hxnum(1),
hxprune(1),
hxtoc(1),
hxunent(1),
xml2asc(1),
UTF-8 (RFC 2279)
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
bibfile as "Camus,
Albert".
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
bibfile. Putting commas between the first
authors and the word "and" before the final one is also not
possible.
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
bibfile as "J. Sartre"
or as "Jean-Paul Sartre" in the output.
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
bibfile or not put periods in the
template.
Entries in the
bibfile can only be used if they have a
%L (label)
field. The program cannot find entries by searching for keywords, like
refer(1).
hxmkbib will replace any ampersands (&) and less-than (<) and
greater-than (>) signs that occur in the
bibfile by their XML
entities & < > on the assumption that the template is
HTML/XML. This may not be appropriate for other formats.