NAME
hxcite-mkbib - expand references and create bibliography
SYNOPSIS
hxcite-mkbib [ -b base ] [ -p pattern ] [ -s separator ] bibfile [ file
]
DESCRIPTION
The hxcite-mkbib commands copies file to standard output, looking for
strings of the form "[[label]]" and for a template for a bibliography.
The label may not include white space and the double pair of square
brackets must enclose the label without any spaces in between. If
hxcite-mkbib finds the label in the bibfile, the string is replaced by
the pattern. The pattern can include certain variables. If the label
is not found in bibfile, it is left unchanged.
The default pattern replaces the string with a hyperlink, but if the -p
option is used, the replacement can be any pattern. The input doesn’t
even have to be HTML.
The file consists of three parts:
preamble The preamble is the part up to the first occurrence of %{.
The preamble is copied to the output once (with bracketed
labels ("[[label]]") expanded). The character % is treated
specially. 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 used 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 bracketed
labels in file. 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 labels in file, except that labels 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 a file that creates a bibliography in HTML
format:
<html>
<title>Bibliography</title>
... text with [[references]] here...
<!--%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:
-p pattern
Specifies the pattern by which the string [[label]] is
replaced. The pattern may include the variables %b (which
will be replaced by the value of the -b option) and %L (which
will be replaced by the label). The default pattern is
<a href="%b#%L" rel="biblioentry">[%L]</a>
-b base Sets the value for the %b variable in the pattern. Typically
this is set to a relative or absolute URL. By default this
value is an empty string.
-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.
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 compared to the bracketed labels.
(Entries without such a field will be ignored.)
file The name of the input file is optional. If absent, hxmkbib(1)
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), hxmkbib(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.
hxcite-mkbib is a (bash) shell script that calls hxcite(1) and
hxmkbib(1), and is therefore not portable to all platforms.