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

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 &amp; &lt; &gt;  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.