1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310
|
.de d \" begin display
.sp
.in +4
.nf
..
.de e \" end display
.in -4
.fi
.sp
..
.TH "HXCITE\-MKBIB" "1" "10 Jul 2011" "7.x" "HTML-XML-utils"
.SH NAME
hxcite-mkbib \- expand references and create bibliography
.SH SYNOPSIS
.B hxcite\-mkbib
.RB "[\| " \-b
.IR base " \|]"
.RB "[\| " \-p
.IR pattern " \|]"
.RB "[\| " \-s
.IR separator " \|]"
.IR bibfile " [\| " file " \|]"
.SH DESCRIPTION
.LP
The
.B hxcite\-mkbib
commands copies
.I file
to standard output, looking for strings of the form "[[\fIlabel\fP]]"
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
.B hxcite\-mkbib
finds the label in the
.IR bibfile ","
the string is replaced by the
.IR pattern "."
The pattern can include certain variables. If the label is not found
in
.IR bibfile ","
it is left unchanged.
.PP
The default pattern replaces the string with a hyperlink, but if the
.B \-p
option is used, the replacement can be any pattern. The input doesn't
even have to be HTML.
.PP
The
.I file
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 once (with bracketed labels
("[[\fIlabel\fP]]") expanded). The character
.B %
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.
.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 bracketed labels in
.IR file .
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 labels in
.IR file ,
except that labels 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 a file that creates a bibliography in HTML
format:
.d
<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>
.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 <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
.BR %{!A:...%} ,
meaning that that part will only be effective if there is no author
field (%A).
.PP
The final two lines are the postamble and will simply be copied
unchanged.
.PP
A bibliographic entry that looks like this in
.IR bibfile :
.d
%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
.e
will be printed by the template above as:
.d
<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>
.e
.SH OPTIONS
The following options are supported:
.TP 10
.BI \-p " pattern"
Specifies the pattern by which the string [[\fIlabel\fP]] is replaced.
The pattern may include the variables
.B %b
(which will be replaced by the value of the
.B \-b
option) and
.B %L
(which will be replaced by the
.IR label ")."
The default pattern is
.d
<a href="%b#%L" rel="biblioentry">[%L]</a>
.e
.TP
.BI \-b " base"
Sets the value for the
.B %b
variable in the pattern. Typically this is set to a relative or
absolute URL. By default this value is an empty string.
.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.
.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 compared to the bracketed labels. (Entries without
such a field will be ignored.)
.TP
.I file
The name of the input file is optional. If absent,
.BR hxmkbib (1)
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 hxmkbib (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.
.PP
.B hxcite\-mkbib
is a (bash) shell script that calls
.BR hxcite (1)
and
.BR hxmkbib (1),
and is therefore not portable to all platforms.
|