Provided by: html-xml-utils_6.5-1_amd64 bug

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 &amp; &lt; &gt;  on  the  assumption  that  the
       template is HTML/XML. This may not be appropriate for other formats.