1man(1) General Commands Manual man(1)
2
6 cite-mkbib - expand references and create bibliography
7
9 cite-mkbib [ -b base ] [ -p pattern ] [ -s separator ] bibfile [ file ]
10
12 The cite-mkbib commands copies file to standard output, looking for
13 strings of the form "[[label]]" and for a template for a bibliography.
14 The label may not include white space and the double pair of square
15 brackets must enclose the label without any spaces in between. If
16 cite-mkbib finds the label in the bibfile, the string is replaced by
17 the pattern. The pattern can include certain variables. If the label
18 is not found in bibfile, it is left unchanged.
19 The default pattern replaces the string with a hyperlink, but if the -p
21 option is used, the replacement can be any pattern. The input doesn't
22 even have to be HTML.
23 The file consists of three parts:
25 preamble The preamble is the part up to the first occurrence of %{.
27 The preamble is copied to the output once (with bracketed
28 labels ("[[label]]") expanded). The character % is treated
29 specially. To create a single % in the output, there must be
30 two in the preamble (%%). All other occurrences of % followed
31 by another letter are not copied, but are collected into a
32 string called the "sort order." and used to sort the entries,
33 as explained below.
34 template The template starts with %{L: and ends with a matching %}.
36 The text in between is copied as often as there are biblio‐
37 graphic entries in bibfile that correspond to bracketed
38 labels in file. Variables in the template are replaced by
39 the corresponding field in the bibliographic entry: all
40 occurrences of %x will be replaced by the field %x of the
41 entry. Parts of the text may be enclosed in %{x: and %}.
42 This means that the text in between should only be output if
43 the current entry has a field x. Text that is enclosed in
44 %{!x: and %} will only be output if the entry does not have a
45 field x. Both kinds of conditional sections may also be
46 nested.
47 postamble The text after the %} is copied unchanged to the output,
49 after all bibliographic entries have been processed.
50 By default bibliographic entries are copied to the output in the order
52 of the labels in file, except that labels that occur more than once are
53 only used once. If the preamble contains occurrences of %x (where x is
54 neither "%" nor "{") then these together determine the sort order.
55 E.g., if the preamble contains %A%D then the entries will be sorted
56 first on field A (author) and then on field D (date).
57 Here is an example of a file that creates a bibliography in HTML for‐
59 mat:
60 <html>
62 <title>Bibliography</title>
63 ... text with [[references]] here...
64 <!--%A%D sorted on author, then date -->
65 <dl>
66 %{L:
67 <dt id="%L">%{A:A%}%{!A:%{E:E%}%{!E:%{Q:Q%}%{!Q:-%}%}%}</dt>
68 <dd>%{B:"%T"
69 in: %{E:%E (eds)
70 %}<cite>%B.</cite>%{V: %V.%}
71 %}%{J:"%T"
72 in: %{E:%E (eds)
73 %}<cite>%J.</cite>%{V: %V.%}%{N: %N.%}%{P: pp. %P.%}
74 %}%{!B:%{!J:<cite>%T.</cite>
75 %}%}%{I:%I.
76 %}%{D:%D.
77 %}%{C:%C.
78 %}%{R:%R.
79 %}%{S:%S.
80 %}%{O:%O
81 %}%{U:<a href="%U">%U</a>
82 %}</dd>
83 %}
84 </dl>
85 </html>
86 This template starts with four lines of preample, including the sort
88 string %A%D on line 3. The sort string itself will not be output, but
89 the rest of the comment will.
90 From the line %{L: to the line %} is the template. E.g., the line that
92 starts with <dt id=... contains a complex conditional text that prints
93 the authors (%A) if there are any, otherwise the editors (%E) if there
94 are any, otherwise the institution that is the author (%Q), if any, and
95 a dash otherwise. Note how the parts are nested, Most of the text is
96 inside %{!A:...%}, meaning that that part will only be effective if
97 there is no author field (%A).
98 The final two lines are the postamble and will simply be copied
100 unchanged.
101 A bibliographic entry that looks like this in bibfile:
103 %L Java
105 %A Gosling, James
106 %A Joy, Bill
107 %A Steele, Guy
108 %T The Java language specification
109 %D 1998
110 %I Addison-Wesley
111 %U http://java.sun.com/docs/books/jls/index.html
112 will be printed by the template above as:
114 <dt id="Java">Gosling, James; Joy, Bill; Steele, Guy</dt>
116 <dd><cite>The Java language specification.</cite>
117 Addison-Wesley.
118 1998.
119 <a href="http://java.sun.com/docs/books/jls/index.html">http://java.sun.com/docs/books/jls/index.html</a>
120 </dd>
121
124 The following options are supported:
125 -p pattern
127 Specifies the pattern by which the string [[label]] is
128 replaced. The pattern may include the variables %b (which
129 will be replaced by the value of the -b option) and %L (which
130 will be replaced by the label). The default pattern is
131 <a href="%b#%L" rel="biblioentry">[%L]</a>
133 -b base Sets the value for the %b variable in the pattern. Typically
136 this is set to a relative or absolute URL. By default this
137 value is an empty string.
138 -s separator
140 If there are multiple authors or editors in an entry, their
141 names will be listed with a separator in between. By default
142 the separator is "; " (i.e., a semicolon and a space). With
143 this option the separator can be changed.
144
146 The following operands are supported:
147 bibfile The name of a bibliographic database must be given. It must
149 be a file in refer(1) format and every entry must have at
150 least a %L field, which is compared to the bracketed labels.
151 (Entries without such a field will be ignored.)
152 file The name of the input file is optional. If absent, mkbib will
154 read the template from stdin.
155
157 The following exit values are returned:
158 0 Successful completion.
160 > 0 An error occurred. Usually this is because a file could not
162 be opened or because the %{ and %} pairs are not properly
163 nested. Very rarely it may also be an out of memory error.
164 Some of the possible error messages:
165 missing ':' in pattern
167 mkbib found a %{ but the second or third letter after it was
168 not a colon.
169 no '%{' in template file
171 The template file is unusable, because it contains no tem‐
172 plate.
173 unbalanced %{..%} in pattern
175 There are more %{ than %}.
176
178 cite(1), mkbib(1), xml2asc(1), UTF-8 (RFC 2279), normalize(1), num(1),
179 toc(1), htmlprune(1). unent(1) asc2xml(1)
180
182 Sorting is primitive: the program doesn't parse dates or names and sim‐
183 ply sorts "Jan 2000" under the letter "J" and "Albert Camus" under the
184 lettr "A". For the moment the only work-around is to put names in the
185 bibfile as "Camus, Albert".
186 The program simply lists all authors or editors. There is no way to
188 generate an "et. al." after the third one. The work-around is to put
189 the "et. al." in the bibfile. Putting commas between the first authors
190 and the word "and" before the final one is also not possible.
191 The program doesn't try to interpret names of authors or editors and
193 they cannot be reformatted. It is impossible to write a name that is
194 specified as "Sartre, Jean-Paul" in the bibfile as "J. Sartre" or as
195 "Jean-Paul Sartre" in the output.
196 There is no way to suppress a period after a field if the field already
198 ends with a period. E.g., the template "%{A:A.%}" may generate "A. Per‐
199 son Jr.." if the author is "A. Person Jr." The only option is to either
200 not put periods in the bibfile or not put periods in the template.
201 Entries in the bibfile can only be used if they have a %L (label)
203 field. The program cannot find entries by searching for keywords, like
204 refer(1).
205 mkbib will replace any ampersands (&) and less-than (<) and greater-
207 than (>) signs that occur in the bibfile by their XML entities &
208 < > on the assumption that the template is HTML/XML. This may not
209 be appropriate for other formats.
210 cite-mkbib is a (bash) shell script that calls cite(1) and mkbib(1),
212 and is therefore not portable to all platforms.
213 20 Mar 2000 man(1)