Man Linux: Main Page and Category List

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.