.de d \" begin display .sp .in +4 .nf .. .de e \" end display .in -4 .fi .sp .. .TH "HXMKBIB" "1" "10 Jul 2011" "7.x" "HTML-XML-utils" .SH NAME hxmkbib \- create bibliography from a template .SH SYNOPSIS .B hxmkbib .RB "[\| " \-s .IR separator " \|]" .RB "[\| " \-a .IR auxfile " \|]" .RB "[\| " \-n .IR maxauthors " \|]" .RB "[\| " \-r .IR moreauthors " \|]" .IR bibfile " [\| " templatefile " \|]" .SH DESCRIPTION .LP The .B hxmkbib commands reads a list of bibliographic keys (labels) from .IR auxfile , finds the corresponding entries in .I bibfile and creates a bibliography, using .I templatefile as a model. The .I auxfile may, e.g., have been created by .BR hxcite (1). It consists of labels, one per line. The .I bibfile is a .BR refer (1) style database. .B hxmkbib looks for entries with a .B %L field equal to a key in the .IR auxfile . .PP The .I templatefile consists of three parts: .TP 10 .B preamble The preamble is the part up to the first occurrence of .BR %{ . The preamble is copied to the output unchanged, except for occurrences of .BR % . 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. .TP .B template The template starts with .B %{L: and ends with a matching .BR %} . The text in between is copied as often as there are bibliographic entries in .I bibfile that correspond to keys in .IR auxfile . Variables in the template are replaced by the corresponding field in the bibliographic entry: all occurrences of .BI % x will be replaced by the field .BI % x of the entry. Parts of the text may be enclosed in .BI %{ x : and .BR %} . This means that the text in between should only be output if the current entry has a field .IR x . Text that is enclosed in .BI %{! x : and .B %} will only be output if the entry does .B not have a field .IR x . Both kinds of conditional sections may also be nested. .TP .B postamble The text after the .B %} is copied unchanged to the output, after all bibliographic entries have been processed. .PP By default bibliographic entries are copied to the output in the order of the keys in .IR auxfile , except that keys that occur more than once are only used once. If the preamble contains occurrences of .BI % x (where .I 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). .PP Here is an example of template file that creates a bibliography in HTML format: .d Bibliography
%{L:
%{A:%A%}%{!A:%{E:%E%}%{!E:%{Q:%Q%}%{!Q:-%}%}%}
%{B:"%T" in: %{E:%E (eds) %}%B.%{V: %V.%} %}%{J:"%T" in: %{E:%E (eds) %}%J.%{V: %V.%}%{N: %N.%}%{P: pp. %P.%} %}%{!B:%{!J:%T. %}%}%{I:%I. %}%{D:%D. %}%{C:%C. %}%{R:%R. %}%{S:%S. %}%{O:%O %}%{U:%U %}
%}
.e 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. .PP From the line .B %{L: to the line .B %} is the template. E.g., the line that starts with .B
Gosling, James; Joy, Bill; Steele, Guy
The Java language specification. Addison-Wesley. 1998. http://java.sun.com/docs/books/jls/index.html
.e .SH OPTIONS The following options are supported: .TP 10 .BI \-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 .I templatefile argument by removing the last extension and adding .BR .aux . If no .I templatefile is given, the default .I auxfile is .BR aux.aux . .TP .BI \-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. .TP .BI \-n " maxauthors" If there are more than .I maxauthors authors in an entry, only the first author will be printed and the others will be replaced by the string .IR moreauthors . The default is 3. .TP .BI \-r " moreauthors" The string to print if there are more than .I maxauthors authors. The default is "et al.". .SH OPERANDS The following operands are supported: .TP 10 .I bibfile The name of a bibliographic database must be given. It must be a file in .BR refer (1) format and every entry must have at least a .B %L field, which is used as key. (Entries without such a field will be ignored.) .TP .I templatefile The name of the input file is optional. If absent, .B hxmkbib will read the template from stdin. .SH "DIAGNOSTICS" The following exit values are returned: .TP 10 .B 0 Successful completion. .TP .B > 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: .TP .I missing ':' in pattern .B hxmkbib found a %{ but the second or third letter after it was not a colon. .TP .I no '%{' in template file The template file is unusable, because it contains no template. .TP .I unbalanced %{..%} in pattern There are more %{ than %}. .SH "SEE ALSO" .BR asc2xml (1), .BR hxcite (1), .BR hxnormalize (1), .BR hxnum (1), .BR hxprune (1), .BR hxtoc (1), .BR hxunent (1), .BR xml2asc (1), .BR UTF-8 " (RFC 2279)" .SH 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 .I bibfile as "Camus, Albert". .PP 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 .IR bibfile . Putting commas between the first authors and the word "and" before the final one is also not possible. .PP 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 .I bibfile as "J. Sartre" or as "Jean-Paul Sartre" in the output. .PP 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 .IR bibfile or not put periods in the template. .PP Entries in the .I bibfile can only be used if they have a .B %L (label) field. The program cannot find entries by searching for keywords, like .BR refer (1). .PP .B hxmkbib will replace any ampersands (&) and less-than (<) and greater-than (>) signs that occur in the .I bibfile by their XML entities & < > on the assumption that the template is HTML/XML. This may not be appropriate for other formats.