Debian Codegraph @

bibclean.html

raw
1 <!-- -*-html-*- -->
2 <!-- bibclean.html -->
3 <!-- Prettyprinted by html-pretty flex version 1.02 [11-May-2002] -->
4 <!-- on Tue May 19 17:28:07 2020 -->
5 <!-- for Nelson H F Beebe ([email protected]) -->
6
7 <!-- Warning: Do NOT edit this file. -->
8 <!-- It was created automatically by man2html.awk Version 2.07 [13-Mar-2006] on Tue May 19 17:28:07 MDT 2020 -->
9 <!-- from the file at eta.math.utah.edu -->
10
11 <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML Level 2//EN">
12 <!-- ===================================================================== -->
13 <!-- @Troff_man_file{ -->
14 <!-- author = "Nelson H. F. Beebe", -->
15 <!-- version = "3.05", -->
16 <!-- date = "18 May 2020", -->
17 <!-- time = "08:38:23 MDT", -->
18 <!-- filename = "bibclean.man", -->
19 <!-- address = "University of Utah -->
20 <!-- Department of Mathematics, 110 LCB -->
21 <!-- 155 S 1400 E RM 233 -->
22 <!-- Salt Lake City, UT 84112_0090 -->
23 <!-- USA -->
24 <!-- telephone = "+1 801 581 5254", -->
25 <!-- FAX = "+1 801 581 4148", -->
26 <!-- URL = "http://www.math.utah.edu/~beebe", -->
27 <!-- checksum = "53118 2647 9662 108927", -->
28 <!-- email = "[email protected], [email protected], -->
29 <!-- [email protected] (Internet)", -->
30 <!-- codetable = "ISO/ASCII", -->
31 <!-- keywords = "bibliography, BibTeX, prettyprint", -->
32 <!-- license = "GNU General Public License, version 2 or -->
33 <!-- later", -->
34 <!-- supported = "yes", -->
35 <!-- docstring = "This file is the UNIX nroff/troff manual page -->
36 <!-- documentation for bibclean, a prettyprinter -->
37 <!-- and syntax checker for BibTeX bibliography -->
38 <!-- data base files. -->
39 <!-- -->
40 <!-- The checksum field above contains a CRC_16 -->
41 <!-- checksum as the first value, followed by the -->
42 <!-- equivalent of the standard UNIX wc (word -->
43 <!-- count) utility output of lines, words, and -->
44 <!-- characters. This is produced by Robert -->
45 <!-- Solovay's checksum utility.", -->
46 <!-- } -->
47 <!-- ===================================================================== -->
48 <!-- -->
49 <!-- .if t .ds Bi B\s_2IB\s+2T\\h'_0.1667m'\\v'0.20v'E\\v'_0.20v'\\h'_0.125m'X -->
50 <!-- -->
51 <!-- .if t .ds Sc S\s_2CRIBE\s+2 -->
52 <!-- -->
53 <!-- .if t .ds Te T\\h'_0.1667m'\\v'0.20v'E\\v'_0.20v'\\h'_0.125m'X -->
54 <!-- -->
55 <!-- ===================================================================== -->
56 <HTML>
57 <HEAD>
58 <TITLE>
59 BIBCLEAN 1 &quot;18 May 2020&quot; &quot;Version 3.05&quot;
60 </TITLE>
61 <LINK REV="made" HREF="mailto:[email protected]">
62 </HEAD>
63 <BODY>
64 <P>
65 <!-- ===================================================================== -->
66 </P>
67 <H1>
68 BIBCLEAN 1 &quot;18 May 2020&quot; &quot;Version 3.05&quot;
69 </H1>
70 <H2>
71 Table of contents
72 </H2>
73 <UL>
74 <LI>
75 <A HREF="#HDR.1">
76 NAME
77 </A>
78 </LI>
79 <LI>
80 <A HREF="#HDR.2">
81 SYNOPSIS
82 </A>
83 </LI>
84 <LI>
85 <A HREF="#HDR.3">
86 DESCRIPTION
87 </A>
88 </LI>
89 <LI>
90 <A HREF="#HDR.4">
91 OPTIONS
92 </A>
93 <UL>
94 <LI>
95 <A HREF="#OPT.4.1">
96 -author
97 </A>
98 </LI>
99 <LI>
100 <A HREF="#OPT.4.2">
101 -copyleft
102 </A>
103 </LI>
104 <LI>
105 <A HREF="#OPT.4.3">
106 -copyright
107 </A>
108 </LI>
109 <LI>
110 <A HREF="#OPT.4.4">
111 -error-log
112 </A>
113 </LI>
114 <LI>
115 <A HREF="#OPT.4.5">
116 -help
117 </A>
118 </LI>
119 <LI>
120 <A HREF="#OPT.4.6">
121 -ISBN-file
122 </A>
123 </LI>
124 <LI>
125 <A HREF="#OPT.4.7">
126 -init-file
127 </A>
128 </LI>
129 <LI>
130 <A HREF="#OPT.4.8">
131 -keyword-file
132 </A>
133 </LI>
134 <LI>
135 <A HREF="#OPT.4.9">
136 -max-width
137 </A>
138 </LI>
139 <LI>
140 <A HREF="#OPT.4.10">
141 -[no-]align-equals
142 </A>
143 </LI>
144 <LI>
145 <A HREF="#OPT.4.11">
146 -[no-]brace-protect
147 </A>
148 </LI>
149 <LI>
150 <A HREF="#OPT.4.12">
151 -[no-]check-values
152 </A>
153 </LI>
154 <LI>
155 <A HREF="#OPT.4.13">
156 -[no-]debug-match-failures
157 </A>
158 </LI>
159 <LI>
160 <A HREF="#OPT.4.14">
161 -[no-]delete-empty-values
162 </A>
163 </LI>
164 <LI>
165 <A HREF="#OPT.4.15">
166 -[no-]file-position
167 </A>
168 </LI>
169 <LI>
170 <A HREF="#OPT.4.16">
171 -[no-]fix-accents
172 </A>
173 </LI>
174 <LI>
175 <A HREF="#OPT.4.17">
176 -[no-]fix-braces
177 </A>
178 </LI>
179 <LI>
180 <A HREF="#OPT.4.18">
181 -[no-]fix-degrees
182 </A>
183 </LI>
184 <LI>
185 <A HREF="#OPT.4.19">
186 -[no-]fix-font-changes
187 </A>
188 </LI>
189 <LI>
190 <A HREF="#OPT.4.20">
191 -[no-]fix-initials
192 </A>
193 </LI>
194 <LI>
195 <A HREF="#OPT.4.21">
196 -[no-]fix-math
197 </A>
198 </LI>
199 <LI>
200 <A HREF="#OPT.4.22">
201 -[no-]fix-names
202 </A>
203 </LI>
204 <LI>
205 <A HREF="#OPT.4.23">
206 -[no-]German-style
207 </A>
208 </LI>
209 <LI>
210 <A HREF="#OPT.4.24">
211 -[no-]keep-linebreaks
212 </A>
213 </LI>
214 <LI>
215 <A HREF="#OPT.4.25">
216 -[no-]keep-parbreaks
217 </A>
218 </LI>
219 <LI>
220 <A HREF="#OPT.4.26">
221 -[no-]keep-preamble-spaces
222 </A>
223 </LI>
224 <LI>
225 <A HREF="#OPT.4.27">
226 -[no-]keep-spaces
227 </A>
228 </LI>
229 <LI>
230 <A HREF="#OPT.4.28">
231 -[no-]keep-string-spaces
232 </A>
233 </LI>
234 <LI>
235 <A HREF="#OPT.4.29">
236 -[no-]parbreaks
237 </A>
238 </LI>
239 <LI>
240 <A HREF="#OPT.4.30">
241 -[no-]prettyprint
242 </A>
243 </LI>
244 <LI>
245 <A HREF="#OPT.4.31">
246 -[no-]print-ISBN-table
247 </A>
248 </LI>
249 <LI>
250 <A HREF="#OPT.4.32">
251 -[no-]print-keyword-table
252 </A>
253 </LI>
254 <LI>
255 <A HREF="#OPT.4.33">
256 -[no-]print-patterns
257 </A>
258 </LI>
259 <LI>
260 <A HREF="#OPT.4.34">
261 -[no-]quiet
262 </A>
263 </LI>
264 <LI>
265 <A HREF="#OPT.4.35">
266 -[no-]read-init-files
267 </A>
268 </LI>
269 <LI>
270 <A HREF="#OPT.4.36">
271 -[no-]remove-OPT-prefixes
272 </A>
273 </LI>
274 <LI>
275 <A HREF="#OPT.4.37">
276 -[no-]scribe
277 </A>
278 </LI>
279 <LI>
280 <A HREF="#OPT.4.38">
281 -[no-]trace-file-opening
282 </A>
283 </LI>
284 <LI>
285 <A HREF="#OPT.4.39">
286 -[no-]warnings
287 </A>
288 </LI>
289 <LI>
290 <A HREF="#OPT.4.40">
291 -output-file
292 </A>
293 </LI>
294 <LI>
295 <A HREF="#OPT.4.41">
296 -version
297 </A>
298 </LI>
299 </UL>
300 </LI>
301 <LI>
302 <A HREF="#HDR.5">
303 ERROR RECOVERY AND WARNINGS
304 </A>
305 </LI>
306 <LI>
307 <A HREF="#HDR.6">
308 SEARCH PATHS
309 </A>
310 </LI>
311 <LI>
312 <A HREF="#HDR.7">
313 INITIALIZATION FILES
314 </A>
315 </LI>
316 <LI>
317 <A HREF="#HDR.8">
318 ISBN INITIALIZATION FILES
319 </A>
320 </LI>
321 <LI>
322 <A HREF="#HDR.9">
323 KEYWORD INITIALIZATION FILES
324 </A>
325 </LI>
326 <LI>
327 <A HREF="#HDR.10">
328 LEXICAL ANALYSIS
329 </A>
330 </LI>
331 <LI>
332 <A HREF="#HDR.11">
333 SCRIBE BIBLIOGRAPHY FORMAT
334 </A>
335 </LI>
336 <LI>
337 <A HREF="#HDR.12">
338 ENVIRONMENT VARIABLES
339 </A>
340 </LI>
341 <LI>
342 <A HREF="#HDR.13">
343 FILES
344 </A>
345 </LI>
346 <LI>
347 <A HREF="#HDR.14">
348 SEE ALSO
349 </A>
350 </LI>
351 <LI>
352 <A HREF="#HDR.15">
353 AUTHOR
354 </A>
355 </LI>
356 <LI>
357 <A HREF="#HDR.16">
358 COPYRIGHT
359 </A>
360 </LI>
361 </UL>
362 <HR>
363 <H1>
364 <A NAME="HDR.1">
365 NAME
366 </A>
367 </H1>
368 <P>
369 bibclean - prettyprint and syntax check BibTeX and Scribe
370 bibliography data base files
371 <!-- ===================================================================== -->
372 </P>
373 <HR>
374 <H1>
375 <A NAME="HDR.2">
376 SYNOPSIS
377 </A>
378 </H1>
379 <P>
380 <STRONG>bibclean</STRONG> [ <STRONG>-author</STRONG> ] [
381 <STRONG>-copyleft</STRONG> ] [ <STRONG>-copyright</STRONG> ]
382 <!-- .if n .ti +9n -->
383 [ <STRONG>-error-log</STRONG> <EM> filename</EM> ] [
384 <STRONG>-help</STRONG> ] [ <STRONG>'-?'</STRONG> ]
385 <!-- .if n .ti +9n -->
386 <!-- .if t .ti +\w'\fBbibclean\fP\ 'u -->
387 [ <STRONG>-init-file</STRONG> <EM> filename</EM> ] [
388 <STRONG>-ISBN-file</STRONG> <EM> filename</EM> ]
389 <!-- .if n .ti +9n -->
390 [ <STRONG>-keyword-file</STRONG> <EM> filename</EM> ]
391 <!-- .if t .ti +\w'\fBbibclean\fP\ 'u -->
392 [ <STRONG>-max-width</STRONG> <EM> nnn</EM> ]
393 <!-- .if n .ti +9n -->
394 [ <STRONG>-[no-]align-equals</STRONG> ] [ <STRONG>
395 -[no-]brace-protect</STRONG> ] <!-- .if n .ti +9n -->
396 [ <STRONG>-[no-]check-values</STRONG> ]
397 <!-- .if t .ti +\w'\fBbibclean\fP\ 'u -->
398 [ <STRONG>-[no-]debug-match-failures</STRONG> ]
399 <!-- .if n .ti +9n -->
400 [ <STRONG>-[no-]delete-empty-values</STRONG> ] [ <STRONG>
401 -[no-]file-position</STRONG> ]
402 <!-- .if t .ti +\w'\fBbibclean\fP\ 'u -->
403 <!-- .if n .ti +9n -->
404 [ <STRONG>-[no-]fix-accents</STRONG> ] [ <STRONG>
405 -[no-]fix-braces</STRONG> ] <!-- .if n .ti +9n -->
406 [ <STRONG>-[no-]fix-degrees</STRONG> ] [ <STRONG>
407 -[no-]fix-font-changes</STRONG> ] <!-- .if n .ti +9n -->
408 <!-- .if t .ti +\w'\fBbibclean\fP\ 'u -->
409 [ <STRONG>-[no-]fix-initials</STRONG> ] [ <STRONG>
410 -[no-]fix-math</STRONG> ] [ <STRONG>-[no-]fix-names</STRONG>
411 ] <!-- .if n .ti +9n -->
412 [ <STRONG>-[no-]German-style</STRONG> ]
413 <!-- .if t .ti +\w'\fBbibclean\fP\ 'u -->
414 [ <STRONG>-[no-]keep-linebreaks</STRONG> ]
415 <!-- .if n .ti +9n -->
416 [ <STRONG>-[no-]keep-parbreaks</STRONG> ] [ <STRONG>
417 -[no-]keep-preamble-spaces</STRONG> ] <!-- .if n .ti +9n -->
418 <!-- .if t .ti +\w'\fBbibclean\fP\ 'u -->
419 [ <STRONG>-[no-]keep-spaces</STRONG> ] [ <STRONG>
420 -[no-]keep-string-spaces</STRONG> ] <!-- .if n .ti +9n -->
421 [ <STRONG>-[no-]parbreaks</STRONG> ] [ <STRONG>
422 -[no-]prettyprint</STRONG> ] <!-- .if n .ti +9n -->
423 <!-- .if t .ti +\w'\fBbibclean\fP\ 'u -->
424 [ <STRONG>-[no-]print-ISBN-table</STRONG> ] [ <STRONG>
425 -[no-]print-keyword-table</STRONG> ] <!-- .if n .ti +9n -->
426 [ <STRONG>-[no-]print-patterns</STRONG> ]
427 <!-- .if t .ti +\w'\fBbibclean\fP\ 'u -->
428 [ <STRONG>-[no-]quiet</STRONG> ] <!-- .if n .ti +9n -->
429 [ <STRONG>-[no-]read-init-files</STRONG> ] [ <STRONG>
430 -[no-]remove-OPT-prefixes</STRONG> ] <!-- .if n .ti +9n -->
431 [ <STRONG>-[no-]scribe</STRONG> ]
432 <!-- .if t .ti +\w'\fBbibclean\fP\ 'u -->
433 [ <STRONG>-[no-]trace-file-opening</STRONG> ]
434 <!-- .if n .ti +9n -->
435 [ <STRONG>-[no-]warnings</STRONG> ] [ <STRONG>-output-file
436 </STRONG> <EM> filename</EM> ] [ <STRONG>-version</STRONG> ]
437 <!-- .if n .ti +9n -->
438 <!-- .if t .ti +.5i -->
439 <EM>&lt;infile</EM> or <EM> bibfile1 bibfile2 bibfile3 ...
440 </EM> <!-- .if n .ti +9n -->
441 <!-- .if t .ti +.5i -->
442 <EM>&gt;outfile</EM>
443 </P>
444 <P>
445 All options can be abbreviated to a unique leading prefix.
446 </P>
447 <P>
448 An explicit file name of ``-'' represents standard input; it
449 is assumed if no input files are specified.
450 </P>
451 <P>
452 On VAX VMS and IBM PC DOS, the leading ``-'' on option names
453 may be replaced by a slash, ``/''; however, the ``-'' option
454 prefix is always recognized.
455 <!-- ===================================================================== -->
456 </P>
457 <HR>
458 <H1>
459 <A NAME="HDR.3">
460 DESCRIPTION
461 </A>
462 </H1>
463 <P>
464 <STRONG>bibclean</STRONG> prettyprints input BibTeX files to
465 <EM>stdout</EM>, or to a user-specified file, and checks the
466 brace balance and bibliography entry syntax as well. It can
467 be used to detect problems in BibTeX files that sometimes
468 confuse even BibTeX itself, and importantly, can be used to
469 normalize the appearance of collections of BibTeX files.
470 </P>
471 <P>
472 Here is a summary of the formatting actions:
473 </P>
474 <UL>
475 <LI>
476 BibTeX items are formatted into a consistent structure
477 with one <EM>field = &quot;value&quot;</EM> pair per
478 line, and the initial @ and trailing right brace in
479 column 1.
480 </LI>
481 <LI>
482 Tabs are expanded into blank strings; their use is
483 discouraged because they inhibit portability, and can
484 suffer corruption in electronic mail.
485 </LI>
486 <LI>
487 Long string values are split at a blank and continued
488 onto the next line with leading indentation.
489 </LI>
490 <LI>
491 A single blank line separates adjacent bibliography
492 entries.
493 </LI>
494 <LI>
495 Text outside BibTeX entries is passed through verbatim.
496 </LI>
497 <LI>
498 Outer parentheses around entries are converted to
499 braces.
500 </LI>
501 <LI>
502 Personal names in <EM>author</EM> and <EM>editor</EM>
503 field values are normalized to the form ``P. D. Q.
504 Bach'', from ``P.D.Q. Bach'' and ``Bach, P.D.Q.''.
505 </LI>
506 <LI>
507 Hyphen sequences in page numbers are converted to
508 en-dashes.
509 </LI>
510 <LI>
511 Month values are converted to standard BibTeX string
512 abbreviations.
513 </LI>
514 <LI>
515 In titles, sequences of upper-case characters at brace
516 level zero are braced to protect them from being
517 converted to lower-case letters by some bibliography
518 styles.
519 </LI>
520 <LI>
521 CODEN, ISBN (International Standard Book Number) and
522 ISSN (International Standard Serial Number) entry values
523 are examined to verify the checksums of each listed
524 number, and correct ISBN hyphenation is automatically
525 supplied.
526 </LI>
527 </UL>
528 The standardized format of the output of <STRONG>bibclean
529 </STRONG> facilitates the later application of simple filters,
530 such as
531 <A HREF="../man1/bibcheck.html">
532 <STRONG>bibcheck</STRONG>
533 </A>
534 (1),
535 <A HREF="../man1/bibdup.html">
536 <STRONG>bibdup</STRONG>
537 </A>
538 (1),
539 <A HREF="../man1/bibextract.html">
540 <STRONG>bibextract</STRONG>
541 </A>
542 (1),
543 <A HREF="../man1/bibindex.html">
544 <STRONG>bibindex</STRONG>
545 </A>
546 (1),
547 <A HREF="../man1/bibjoin.html">
548 <STRONG>bibjoin</STRONG>
549 </A>
550 (1),
551 <A HREF="../man1/biblabel.html">
552 <STRONG>biblabel</STRONG>
553 </A>
554 (1),
555 <A HREF="../man1/biblook.html">
556 <STRONG>biblook</STRONG>
557 </A>
558 (1),
559 <A HREF="../man1/biborder.html">
560 <STRONG>biborder</STRONG>
561 </A>
562 (1),
563 <A HREF="../man1/bibsort.html">
564 <STRONG>bibsort</STRONG>
565 </A>
566 (1),
567 <A HREF="../man1/citefind.html">
568 <STRONG>citefind</STRONG>
569 </A>
570 (1), and
571 <A HREF="../man1/citetags.html">
572 <STRONG>citetags</STRONG>
573 </A>
574 (1), to process the text, and also is the one expected by the
575 GNU Emacs BibTeX support functions.
576 <!-- ===================================================================== -->
577 <HR>
578 <H1>
579 <A NAME="HDR.4">
580 OPTIONS
581 </A>
582 </H1>
583 <P>
584 Command-line switches may be abbreviated to a unique leading
585 prefix, and letter case is <EM>not</EM> significant. All
586 options are parsed before any input bibliography files are
587 read, no matter what their order on the command line.
588 Options that correspond to a yes/no setting of a flag have a
589 form with a prefix &quot;no-&quot; to set the flag to <EM>no
590 </EM>. For such options, the last setting determines the
591 flag value used. That is significant when options are also
592 specified in initialization files (see the <STRONG>
593 INITIALIZATION FILES</STRONG> manual section).
594 </P>
595 <P>
596 The leading hyphen that distinguishes an option from a
597 filename may be doubled, for compatibility with GNU and
598 POSIX conventions. Thus, <STRONG>-author</STRONG> and
599 <STRONG>--author</STRONG> are equivalent.
600 </P>
601 <P>
602 To avoid confusion with options, if a filename begins with a
603 hyphen, it must be disguised by a leading absolute or
604 relative directory path, e.g., <EM>/tmp/-foo.bib</EM> or
605 <EM>./-foo.bib</EM>.
606 <!-- _______________________________________________ -->
607 </P>
608 <DL>
609 <DT>
610 <A NAME="OPT.4.1">
611 <STRONG>-author</STRONG>
612 </A>
613 </DT>
614 <DD>
615 Display an author credit on the standard error unit,
616 <EM>stderr</EM>, and then terminate with a success
617 return code. Sometimes an executable program is
618 separated from its documentation and source code; this
619 option provides a way to recover from that.
620 <!-- _______________________________________________ -->
621 </DD>
622 <DT>
623 <A NAME="OPT.4.2">
624 <STRONG>-copyleft</STRONG>
625 </A>
626 </DT>
627 <DD>
628 Display copyright information on the standard error
629 unit, <EM>stderr</EM>, and then terminate with a success
630 return code.
631 <!-- _______________________________________________ -->
632 </DD>
633 <DT>
634 <A NAME="OPT.4.3">
635 <STRONG>-copyright</STRONG>
636 </A>
637 </DT>
638 <DD>
639 Display copyright information on the standard error
640 unit, <EM>stderr</EM>, and then terminate with a success
641 return code.
642 <!-- _______________________________________________ -->
643 </DD>
644 <DT>
645 <A NAME="OPT.4.4">
646 <STRONG>-error-log</STRONG> <EM> filename</EM>
647 </A>
648 </DT>
649 <DD>
650 Redirect <EM>stderr</EM> to the indicated file, which
651 then contains all of the error and warning messages.
652 This option is provided for those systems that have
653 difficulty redirecting <EM>stderr</EM>.
654 <!-- _______________________________________________ -->
655 </DD>
656 <DT>
657 <A NAME="OPT.4.5">
658 <STRONG>-help</STRONG> or <STRONG>-?</STRONG>
659 </A>
660 </DT>
661 <DD>
662 Display a help message on <EM>stderr</EM>, giving a
663 usage description, similar to this section of the manual
664 pages, and then terminate with a success return code.
665 <!-- _______________________________________________ -->
666 </DD>
667 <DT>
668 <A NAME="OPT.4.6">
669 <STRONG>-ISBN-file</STRONG> <EM> filename</EM>
670 </A>
671 </DT>
672 <DD>
673 Provide an explicit ISBN-range initialization file. It
674 is processed <EM>after</EM> any system-wide and job-wide
675 ISBN initialization files found on the <STRONG>PATH
676 </STRONG> (for VAX VMS, <STRONG>SYS$SYSTEM</STRONG> )
677 and <STRONG>BIBINPUTS</STRONG> search paths,
678 respectively, and may override them. The ISBN
679 initialization file name can be changed at compile time,
680 or at run time through a setting of the environment
681 variable <STRONG>BIBCLEANISBN</STRONG>, but defaults to
682 <EM>.bibclean.isbn</EM> on UNIX, and <EM>bibclean.isb
683 </EM> elsewhere. For further details, see the <STRONG>
684 ISBN INITIALIZATION FILES</STRONG> manual section.
685 <!-- _______________________________________________ -->
686 </DD>
687 <DT>
688 <A NAME="OPT.4.7">
689 <STRONG>-init-file</STRONG> <EM> filename</EM>
690 </A>
691 </DT>
692 <DD>
693 Provide an explicit value pattern initialization file.
694 It is processed <EM>after</EM> any system-wide and
695 job-wide initialization files found on the <STRONG>PATH
696 </STRONG> (for VAX VMS, <STRONG>SYS$SYSTEM</STRONG> )
697 and <STRONG>BIBINPUTS</STRONG> search paths,
698 respectively, and may override them. It in turn may be
699 overridden by a subsequent file-specific initialization
700 file. The initialization file name can be changed at
701 compile time, or at run time through a setting of the
702 environment variable <STRONG>BIBCLEANINI</STRONG>, but
703 defaults to <EM>.bibcleanrc</EM> on UNIX, and to <EM>
704 bibclean.ini</EM> elsewhere. For further details, see
705 the <STRONG>INITIALIZATION FILES</STRONG> manual
706 section.
707 <!-- _______________________________________________ -->
708 </DD>
709 <DT>
710 <A NAME="OPT.4.8">
711 <STRONG>-keyword-file</STRONG> <EM> filename</EM>
712 </A>
713 </DT>
714 <DD>
715 Provide an explicit keyword initialization file. It is
716 processed <EM>after</EM> any system-wide and job-wide
717 keyword initialization files found on the <STRONG>PATH
718 </STRONG> (for VAX VMS, <STRONG>SYS$SYSTEM</STRONG> )
719 and <STRONG>BIBINPUTS</STRONG> search paths,
720 respectively, and may override them. The keyword
721 initialization file name can be changed at compile time,
722 or at run time through a setting of the environment
723 variable <STRONG>BIBCLEANKEY</STRONG>, but defaults to
724 <EM>.bibclean.key</EM> on UNIX, and <EM>bibclean.key
725 </EM> elsewhere. For further details, see the <STRONG>
726 KEYWORD INITIALIZATION FILES</STRONG> manual section.
727 <!-- _______________________________________________ -->
728 </DD>
729 <DT>
730 <A NAME="OPT.4.9">
731 <STRONG>-max-width</STRONG> <EM> nnn</EM>
732 </A>
733 </DT>
734 <DD>
735 <STRONG>bibclean</STRONG> normally limits output line
736 widths to 72 characters, and in the interests of
737 consistency, that value should not be changed.
738 Occasionally, special-purpose applications may require
739 different maximum line widths, so this option provides
740 that capability. The number following the option name
741 can be specified in decimal, octal (starting with 0), or
742 hexadecimal (starting with 0x). A zero or negative value
743 is interpreted to mean unlimited, so <STRONG>-max-width
744 </STRONG> <EM> 0</EM> can be used to ensure that each
745 field/value pair appears on a single line.
746 <P>
747 When <STRONG>-no-prettyprint</STRONG> requests
748 <STRONG>bibclean</STRONG> to act as a lexical
749 analyzer, the default line width is unlimited,
750 unless overridden by this option.
751 </P>
752 <P>
753 When <STRONG>bibclean</STRONG> is prettyprinting,
754 line wrapping is done only at a space.
755 Consequently, a long non-blank character sequence
756 may result in the output exceeding the requested
757 line width.
758 </P>
759 <P>
760 When <STRONG>bibclean</STRONG> is lexing, line
761 wrapping is done by inserting a backslash-newline
762 pair when the specified maximum is reached, so no
763 line length ever exceeds the maximum.
764 <!-- _______________________________________________ -->
765 </P>
766 </DD>
767 <DT>
768 <A NAME="OPT.4.10">
769 <STRONG>-[no-]align-equals</STRONG>
770 </A>
771 </DT>
772 <DD>
773 With the positive form, align the equals sign in
774 key/value assignments at the same column, separated by a
775 single space from the value string. Otherwise, the
776 equals sign follows the key, separated by a single
777 space. Default: <EM>no</EM>.
778 <!-- _______________________________________________ -->
779 </DD>
780 <DT>
781 <A NAME="OPT.4.11">
782 <STRONG>-[no-]brace-protect</STRONG>
783 </A>
784 </DT>
785 <DD>
786 Protect uppercase and mixedcase words at brace-level
787 zero with braces to prevent downcasing by some BibTeX
788 styles. Default: <EM>yes</EM>.
789 <!-- _______________________________________________ -->
790 </DD>
791 <DT>
792 <A NAME="OPT.4.12">
793 <STRONG>-[no-]check-values</STRONG>
794 </A>
795 </DT>
796 <DD>
797 With the positive form, apply heuristic pattern matching
798 to field values in order to detect possible errors
799 (e.g., `` <EM>year = &quot;192&quot;</EM> '' instead of
800 `` <EM>year = &quot;1992&quot;</EM> ''), and issue
801 warnings when unexpected patterns are found.
802 <P>
803 That checking is usually beneficial, but if it
804 produces too many bogus warnings for a particular
805 bibliography file, you can disable it with the
806 negative form of this option. Default: <EM>yes</EM>.
807 <!-- _______________________________________________ -->
808 </P>
809 </DD>
810 <DT>
811 <A NAME="OPT.4.13">
812 <STRONG>-[no-]debug-match-failures</STRONG>
813 </A>
814 </DT>
815 <DD>
816 With the positive form, print out a warning when a value
817 pattern fails to match a value string.
818 <P>
819 That is helpful in debugging new patterns, but
820 because the output can be voluminous, you should use
821 this option only with small test files, and
822 initialization files that eliminate all patterns
823 apart from the ones that you are testing. Default:
824 <EM>no</EM>.
825 <!-- _______________________________________________ -->
826 </P>
827 </DD>
828 <DT>
829 <A NAME="OPT.4.14">
830 <STRONG>-[no-]delete-empty-values</STRONG>
831 </A>
832 </DT>
833 <DD>
834 With the positive form, remove all field/value pairs for
835 which the value is an empty string. That is helpful in
836 cleaning up bibliographies generated from text editor
837 templates. Compare this option with <STRONG>
838 -[no-]remove-OPT-prefixes</STRONG> described below.
839 Default: <EM>no</EM>.
840 <!-- _______________________________________________ -->
841 </DD>
842 <DT>
843 <A NAME="OPT.4.15">
844 <STRONG>-[no-]file-position</STRONG>
845 </A>
846 </DT>
847 <DD>
848 With the positive form, give detailed file position
849 information in warning and error messages. Default: <EM>
850 no</EM>.
851 <!-- _______________________________________________ -->
852 </DD>
853 <DT>
854 <A NAME="OPT.4.16">
855 <STRONG>-[no-]fix-accents</STRONG>
856 </A>
857 </DT>
858 <DD>
859 With the positive form, normalize TeX accents in
860 annotes, authors, booktitles, editors, notes, remarks,
861 and titles. Default: <EM>no</EM>.
862 <!-- _______________________________________________ -->
863 </DD>
864 <DT>
865 <A NAME="OPT.4.17">
866 <STRONG>-[no-]fix-braces</STRONG>
867 </A>
868 </DT>
869 <DD>
870 With the positive form, normalize bracing in annotes,
871 authors, booktitles, editors, notes, remarks, and
872 titles, by removing unnecessary levels of braces.
873 Default: <EM>no</EM>.
874 <!-- _______________________________________________ -->
875 </DD>
876 <DT>
877 <A NAME="OPT.4.18">
878 <STRONG>-[no-]fix-degrees</STRONG>
879 </A>
880 </DT>
881 <DD>
882 With the positive form, remove spaces in author/editor
883 fields inside braces after letter-ending periods. That
884 makes reductions from <EM>J. J. {Thomson, M. A., F. R.
885 S.}</EM>, <EM>Frederick {Soddy, B. A. (Oxon.)}</EM>, and
886 <EM>John A. {Cable, M. A., M. Ed., Dipl. Deutsch
887 (Marburg), A. L. C. M.}</EM> to <STRONG>J. J. {Thomson,
888 M.A., F.R.S.}</STRONG>, <STRONG>Frederick {Soddy, B.A.
889 (Oxon.)}</STRONG>, and <STRONG>John A. {Cable, M.A.,
890 M.Ed., Dipl.Deutsch (Marburg), A.L.C.M.}</STRONG>,
891 respectively.
892 <P>
893 In journals in the humanities and history of
894 science, as well as in some scientific journals
895 until well into the 20th Century, academic,
896 honorary, and professional titles and degrees are
897 commonly attached to personal names. Even though
898 modern publishing practice avoids such decorations,
899 for accuracy, bibliography entries should preferably
900 retain them. Journal typographical practice
901 generally follows the reductions described here.
902 <!-- _______________________________________________ -->
903 </P>
904 </DD>
905 <DT>
906 <A NAME="OPT.4.19">
907 <STRONG>-[no-]fix-font-changes</STRONG>
908 </A>
909 </DT>
910 <DD>
911 With the positive form, supply an additional brace level
912 around font changes in titles to protect against
913 downcasing by some BibTeX styles. Font changes that
914 already have more than one level of braces are not
915 modified.
916 <P>
917 For example, if a title contains the Latin phrase
918 <EM>{\em Dictyostelium discoideum}</EM> or <EM>{\em
919 {D}ictyostelium discoideum}</EM>, then downcasing
920 incorrectly converts the phrase to lower-case
921 letters. Most BibTeX users are surprised that
922 bracing the initial letters does not prevent the
923 downcase action. The correct coding is <EM>{{\em
924 Dictyostelium discoideum}}</EM>. However, there are
925 also legitimate cases where an extra level of
926 bracing wrongly protects from downcasing.
927 Consequently, <STRONG>bibclean</STRONG> normally
928 does <EM>not</EM> supply an extra level of braces,
929 but if you have a bibliography where the extra
930 braces are routinely missing, you can use this
931 option to supply them.
932 </P>
933 <P>
934 If you think that you need this option, it is <EM>
935 strongly</EM> recommended that you apply <STRONG>
936 bibclean</STRONG> to your bibliography file with and
937 without <STRONG>-fix-font-changes</STRONG>, then
938 compare the two output files to ensure that extra
939 braces are not being supplied in titles where they
940 should not be present. You must decide which of the
941 two output files is the better choice, then repair
942 the incorrect title bracing by hand.
943 </P>
944 <P>
945 Because font changes in titles are uncommon, except
946 for cases of the type that this option is designed
947 to correct, it should do more good than harm.
948 Default: <EM>no</EM>.
949 <!-- _______________________________________________ -->
950 </P>
951 </DD>
952 <DT>
953 <A NAME="OPT.4.20">
954 <STRONG>-[no-]fix-initials</STRONG>
955 </A>
956 </DT>
957 <DD>
958 With the positive form, insert a space after a period
959 following author initials. Default: <EM>yes</EM>.
960 <!-- _______________________________________________ -->
961 </DD>
962 <DT>
963 <A NAME="OPT.4.21">
964 <STRONG>-[no-]fix-math</STRONG>
965 </A>
966 </DT>
967 <DD>
968 With the positive form, improve readability of math mode
969 in titles by inserting spaces around operators, deleting
970 other unnecessary space, and removing braces around
971 single-character subscripts and superscripts. Default:
972 <EM>no</EM>.
973 <!-- _______________________________________________ -->
974 </DD>
975 <DT>
976 <A NAME="OPT.4.22">
977 <STRONG>-[no-]fix-names</STRONG>
978 </A>
979 </DT>
980 <DD>
981 With the positive form, reorder <EM>author</EM> and <EM>
982 editor</EM> name lists to remove commas at brace level
983 zero, placing first names or initials before last names.
984 Default: <EM>yes</EM>.
985 <!-- _______________________________________________ -->
986 </DD>
987 <DT>
988 <A NAME="OPT.4.23">
989 <STRONG>-[no-]German-style</STRONG>
990 </A>
991 </DT>
992 <DD>
993 With the positive form, interpret quote characters [
994 &quot;] inside <EM>braced</EM> value strings at brace
995 level 1 according to the conventions of the TeX style
996 file <EM>german.sty</EM>, which overloads quote to
997 simplify input and representation of German umlaut
998 accents, sharp-s (es-zet), ligature separators,
999 invisible hyphens, raised/lowered quotes, French
1000 guillemets, and discretionary hyphens. Recognized
1001 character combinations are braced to prevent BibTeX from
1002 interpreting the quote as a string delimiter.
1003 <P>
1004 Quoted strings receive no special handling from this
1005 option, and because German nouns in titles must
1006 anyway be protected from the downcasing operation of
1007 most BibTeX bibliography styles, German value
1008 strings that use the overloaded quote character can
1009 always be entered in the form &quot;{...}&quot;,
1010 without the need to specify this option at all.
1011 </P>
1012 <P>
1013 Default: <EM>no</EM>.
1014 <!-- _______________________________________________ -->
1015 </P>
1016 </DD>
1017 <DT>
1018 <A NAME="OPT.4.24">
1019 <STRONG>-[no-]keep-linebreaks</STRONG>
1020 </A>
1021 </DT>
1022 <DD>
1023 Normally, line breaks inside value strings are collapsed
1024 into a single space, so that long value strings can
1025 later be broken to provide lines of reasonable length.
1026 <P>
1027 With the positive form, linebreaks are preserved in
1028 value strings. If <STRONG>-max-width</STRONG> is
1029 set to zero, this preserves the original line
1030 breaks. Spacing <EM>outside</EM> value strings
1031 remains under <STRONG>bibclean</STRONG> 's control,
1032 and is not affected by this option.
1033 </P>
1034 <P>
1035 Default: <EM>no</EM>.
1036 <!-- _______________________________________________ -->
1037 </P>
1038 </DD>
1039 <DT>
1040 <A NAME="OPT.4.25">
1041 <STRONG>-[no-]keep-parbreaks</STRONG>
1042 </A>
1043 </DT>
1044 <DD>
1045 With the positive form, preserve paragraph breaks
1046 (either formfeeds, or lines containing only spaces) in
1047 value strings. Normally, paragraph breaks are collapsed
1048 into a single space. Spacing <EM>outside</EM> value
1049 strings remains under <STRONG>bibclean</STRONG> 's
1050 control, and is not affected by this option. Default:
1051 <EM>no</EM>.
1052 <!-- _______________________________________________ -->
1053 </DD>
1054 <DT>
1055 <A NAME="OPT.4.26">
1056 <STRONG>-[no-]keep-preamble-spaces</STRONG>
1057 </A>
1058 </DT>
1059 <DD>
1060 With the positive form, preserve all whitespace in
1061 @Preamble{...} entries. Default: <EM>no</EM>.
1062 <!-- _______________________________________________ -->
1063 </DD>
1064 <DT>
1065 <A NAME="OPT.4.27">
1066 <STRONG>-[no-]keep-spaces</STRONG>
1067 </A>
1068 </DT>
1069 <DD>
1070 With the positive form, preserve all spaces in value
1071 strings. Normally, multiple spaces are collapsed into a
1072 single space. This option can be used together with
1073 <STRONG>-keep-linebreaks</STRONG>, <STRONG>
1074 -keep-parbreaks</STRONG>, and <STRONG>-max-width
1075 </STRONG> <EM> 0</EM> to preserve the form of value
1076 strings while still providing syntax and value checking.
1077 Spacing <EM>outside</EM> value strings remains under
1078 <STRONG>bibclean</STRONG> 's control, and is not
1079 affected by this option. Default: <EM>no</EM>.
1080 <!-- _______________________________________________ -->
1081 </DD>
1082 <DT>
1083 <A NAME="OPT.4.28">
1084 <STRONG>-[no-]keep-string-spaces</STRONG>
1085 </A>
1086 </DT>
1087 <DD>
1088 With the positive form, preserve all whitespace in
1089 @String{...} entries. Default: <EM>no</EM>.
1090 <!-- _______________________________________________ -->
1091 </DD>
1092 <DT>
1093 <A NAME="OPT.4.29">
1094 <STRONG>-[no-]parbreaks</STRONG>
1095 </A>
1096 </DT>
1097 <DD>
1098 With the negative form, a paragraph break (either a
1099 formfeed, or a line containing only spaces) is not
1100 permitted in value strings, or between field/value
1101 pairs. That may be useful to quickly trap runaway
1102 strings arising from mismatched delimiters. Default:
1103 <EM>yes</EM>.
1104 <!-- _______________________________________________ -->
1105 </DD>
1106 <DT>
1107 <A NAME="OPT.4.30">
1108 <STRONG>-[no-]prettyprint</STRONG>
1109 </A>
1110 </DT>
1111 <DD>
1112 Normally, <STRONG>bibclean</STRONG> functions as a
1113 prettyprinter. However, with the negative form of this
1114 option, it acts as a lexical analyzer instead, producing
1115 a stream of lexical tokens. See the <STRONG>LEXICAL
1116 ANALYSIS</STRONG> manual section for further details.
1117 Default: <EM>yes</EM>.
1118 <!-- _______________________________________________ -->
1119 </DD>
1120 <DT>
1121 <A NAME="OPT.4.31">
1122 <STRONG>-[no-]print-ISBN-table</STRONG>
1123 </A>
1124 </DT>
1125 <DD>
1126 With the positive form, print the ISBN-range table on
1127 <EM>stderr</EM>, then terminate with a success return
1128 code.
1129 <P>
1130 That action is taken after all command-line options
1131 are processed, and before any input files are read
1132 (other than those that are values of command-line
1133 options).
1134 </P>
1135 <P>
1136 The format of the output ISBN-range table is
1137 acceptable for input as an ISBN initialization file
1138 (see the <STRONG>ISBN INITIALIZATION FILES</STRONG>
1139 manual section). Default: <EM>no</EM>.
1140 <!-- _______________________________________________ -->
1141 </P>
1142 </DD>
1143 <DT>
1144 <A NAME="OPT.4.32">
1145 <STRONG>-[no-]print-keyword-table</STRONG>
1146 </A>
1147 </DT>
1148 <DD>
1149 With the positive form, print the keyword initialization
1150 table on <EM>stderr</EM>, then terminate with a success
1151 return code.
1152 <P>
1153 That action is taken after all command-line options
1154 are processed, and before any input files are read
1155 (other than those that are values of command-line
1156 options).
1157 </P>
1158 <P>
1159 The format of the output table is acceptable for
1160 input as a keyword initialization file (see the
1161 <STRONG>KEYWORD INITIALIZATION FILES</STRONG> manual
1162 section). Default: <EM>no</EM>.
1163 <!-- _______________________________________________ -->
1164 </P>
1165 </DD>
1166 <DT>
1167 <A NAME="OPT.4.33">
1168 <STRONG>-[no-]print-patterns</STRONG>
1169 </A>
1170 </DT>
1171 <DD>
1172 With the positive form, print the value patterns read
1173 from initialization files as they are added to internal
1174 tables. Use this option to check newly-added patterns,
1175 or to see what patterns are being used.
1176 <P>
1177 When <STRONG>bibclean</STRONG> is compiled with
1178 native pattern-matching code (the default), those
1179 patterns are the ones that are used in checking
1180 value strings for valid syntax, and all of them are
1181 specified in initialization files, rather than
1182 hard-coded into the program. For further details,
1183 see the <STRONG>INITIALIZATION FILES</STRONG> manual
1184 section. Default: <EM>no</EM>.
1185 <!-- _______________________________________________ -->
1186 </P>
1187 </DD>
1188 <DT>
1189 <A NAME="OPT.4.34">
1190 <STRONG>-[no-]quiet</STRONG>
1191 </A>
1192 </DT>
1193 <DD>
1194 This option is the opposite of <STRONG>-[no-]warning
1195 </STRONG>; it exists for user convenience, and for
1196 compatibility with other programs that use <STRONG>-q
1197 </STRONG> &nbsp; for quiet operation, without warning
1198 messages.
1199 <!-- _______________________________________________ -->
1200 </DD>
1201 <DT>
1202 <A NAME="OPT.4.35">
1203 <STRONG>-[no-]read-init-files</STRONG>
1204 </A>
1205 </DT>
1206 <DD>
1207 With the negative form, suppress loading of system-,
1208 user-, and file-specific initialization files.
1209 Initializations then come <EM>only</EM> from those files
1210 explicitly given by <STRONG>-init-file</STRONG> <EM>
1211 filename</EM> options. Default: <EM>yes</EM>.
1212 <!-- _______________________________________________ -->
1213 </DD>
1214 <DT>
1215 <A NAME="OPT.4.36">
1216 <STRONG>-[no-]remove-OPT-prefixes</STRONG>
1217 </A>
1218 </DT>
1219 <DD>
1220 With the positive form, remove the ``OPT'' prefix from
1221 each field name where the corresponding value is <EM>not
1222 </EM> an empty string. The prefix ``OPT'' must be
1223 entirely in upper-case to be recognized.
1224 <P>
1225 This option is for bibliographies generated with the
1226 help of the GNU Emacs BibTeX editing support, which
1227 generates templates with optional fields identified
1228 by the ``OPT'' prefix. Although the function <EM>
1229 M-x</EM> normally bound to the keystrokes <EM>C-c
1230 </EM> does the job, users often forget, with the
1231 result that BibTeX does not recognize the field
1232 name, and ignores the value string. Compare this
1233 option with <STRONG>-[no-]delete-empty-values
1234 </STRONG> described above. Default: <EM>no</EM>.
1235 <!-- _______________________________________________ -->
1236 </P>
1237 </DD>
1238 <DT>
1239 <A NAME="OPT.4.37">
1240 <STRONG>-[no-]scribe</STRONG>
1241 </A>
1242 </DT>
1243 <DD>
1244 With the positive form, accept input syntax conforming
1245 to the Scribe document system. The output is converted
1246 to conform to BibTeX syntax. See the <STRONG>SCRIBE
1247 BIBLIOGRAPHY FORMAT</STRONG> manual section for further
1248 details. Default: <EM>no</EM>.
1249 <!-- _______________________________________________ -->
1250 </DD>
1251 <DT>
1252 <A NAME="OPT.4.38">
1253 <STRONG>-[no-]trace-file-opening</STRONG>
1254 </A>
1255 </DT>
1256 <DD>
1257 With the positive form, record in the error log file the
1258 names of all files that <STRONG>bibclean</STRONG>
1259 attempts to open. Use this option to identify where
1260 initialization files are located. Default: <EM>no</EM>.
1261 <!-- _______________________________________________ -->
1262 </DD>
1263 <DT>
1264 <A NAME="OPT.4.39">
1265 <STRONG>-[no-]warnings</STRONG>
1266 </A>
1267 </DT>
1268 <DD>
1269 With the positive form, allow all warning messages. The
1270 negative form is <EM>not</EM> recommended because it may
1271 mask problems that should be repaired. Default: <EM>yes
1272 </EM>.
1273 <!-- _______________________________________________ -->
1274 </DD>
1275 <DT>
1276 <A NAME="OPT.4.40">
1277 <STRONG>-output-file</STRONG> <EM> filename</EM>
1278 </A>
1279 </DT>
1280 <DD>
1281 Supply an alternate output file to replace <EM>stdout
1282 </EM>. If the filename cannot be opened for output,
1283 execution terminates immediately with a nonzero exit
1284 code.
1285 <!-- _______________________________________________ -->
1286 </DD>
1287 <DT>
1288 <A NAME="OPT.4.41">
1289 <STRONG>-version</STRONG>
1290 </A>
1291 </DT>
1292 <DD>
1293 Display the program version number on <EM>stderr</EM>,
1294 and then terminate with a success return code. That
1295 includes an indication of who compiled the program, the
1296 host name on which it was compiled, the time of
1297 compilation, and the type of string-value matching code
1298 selected, when that information is available to the
1299 compiler.
1300 <!-- ===================================================================== -->
1301 </DD>
1302 </DL>
1303 <HR>
1304 <H1>
1305 <A NAME="HDR.5">
1306 ERROR RECOVERY AND WARNINGS
1307 </A>
1308 </H1>
1309 <P>
1310 When <STRONG>bibclean</STRONG> detects an error, it issues
1311 an error message to both <EM>stderr</EM> and <EM>stdout</EM>
1312 .
1313 That way, the user is clearly notified, and the output
1314 bibliography also contains the message at the point of
1315 error.
1316 </P>
1317 <P>
1318 Error messages begin with a distinctive pair of queries, ??,
1319 beginning in column 1, followed by the input file name and
1320 line number. If the <STRONG>-file-position</STRONG> option
1321 was specified, they also contain the input and output
1322 positions of the current file, entry, and value. Each
1323 position includes the file byte number, the line number, and
1324 the column number. In the event of a runaway string
1325 argument, the entry and value positions should precisely
1326 pinpoint the erroneous bibliography entry, and the file
1327 positions indicate where it was detected, which may be
1328 rather later in the files.
1329 </P>
1330 <P>
1331 Warning messages identify possible problems, and are
1332 therefore sent only to <EM>stderr</EM>, and not to <EM>
1333 stdout</EM>, so they never appear in the output file. They
1334 are identified by a distinctive pair of percents, %%,
1335 beginning in column 1, and as with error messages, may be
1336 followed by file position messages if the <STRONG>
1337 -file-position</STRONG> option was specified.
1338 </P>
1339 <P>
1340 For convenience, the first line of each error and warning
1341 message sent to <EM>stderr</EM> is formatted according to
1342 the expectations of the GNU Emacs <EM>next-error</EM>
1343 command. You can invoke <STRONG>bibclean</STRONG> with the
1344 Emacs <EM>M-x compile&lt;RET&gt;bibclean filename.bib &gt;
1345 filename.new</EM> command, then use the <EM>next-error</EM>
1346 command, normally bound to <EM>C-x `</EM> (that's a grave,
1347 or back, accent), to move to the location of the error in
1348 the input file.
1349 </P>
1350 <P>
1351 If error messages are ignored, and left in the output
1352 bibliography file, they precipitates an error when the
1353 bibliography is next processed with BibTeX.
1354 </P>
1355 <P>
1356 After issuing an error message, <STRONG>bibclean</STRONG>
1357 then resynchronizes its input by copying it verbatim to <EM>
1358 stdout</EM> until a new bibliography entry is recognized on
1359 a line in which the first non-blank character is an at-sign
1360 (@). That ensures that nothing is lost from the input
1361 file(s), allowing corrections to be made in either the input
1362 or the output files. However, if <STRONG>bibclean</STRONG>
1363 detects an internal error in its data structures, it
1364 terminates abruptly without further input or output
1365 processing; that kind of error should never happen, and if
1366 it does, it should be reported immediately to the author of
1367 the program. Errors in initialization files, and running out
1368 of dynamic memory, also immediately terminate <STRONG>
1369 bibclean</STRONG>.
1370 <!-- ===================================================================== -->
1371 </P>
1372 <HR>
1373 <H1>
1374 <A NAME="HDR.6">
1375 SEARCH PATHS
1376 </A>
1377 </H1>
1378 <P>
1379 Versions of <STRONG>bibclean</STRONG> before 3.00 found some
1380 of their initialization files in the same directory as the
1381 executable program. That design choice means that those
1382 files can be copied anywhere in the file system, and still
1383 be found at run time. Some software distributions, however,
1384 prefer to follow the model where initialization and other
1385 related files are instead stored in a directory whose name
1386 is related to that of the executable by a conventional
1387 difference in filepath. For example, a program might be
1388 installed in <EM>/opt/bin</EM> and its associated files in
1389 <EM>/opt/share/lib/PROGRAMNAME/</EM> or <EM>
1390 /opt/share/lib/PROGRAMNAME/PROGRAMVERSION/</EM>. The second
1391 form is preferable, because it permits multiple versions of
1392 the same program to be installed, as long as the executable
1393 program names carry a version suffix. Thus, a site might
1394 have installed programs named <EM>bibclean-1.00</EM>, <EM>
1395 bibclean-2.00</EM>, <EM>bibclean-2.15</EM>, and <EM>
1396 bibclean-3.00</EM>, with the versionless name <EM>bibclean
1397 </EM> being a symbolic link to whichever version is the
1398 desired local default.
1399 </P>
1400 <P>
1401 With most software packages, the absolute path to the
1402 directory containing associated files is compiled into the
1403 program, making it impossible to change the installation
1404 locations after the program has been built from source code.
1405 </P>
1406 <P>
1407 Some packages, however, instead use the location of the
1408 executable program to find files by relative path at
1409 runtime. In the above example, the program would determine
1410 its filesystem location at runtime, say <EM>/opt/bin</EM>,
1411 then find its associated files relative to that location in
1412 <EM>../share/lib/PROGRAMNAME/PROGRAMVERSION/</EM>.
1413 </P>
1414 <P>
1415 From version 3.00, <EM>bibclean</EM> uses that second
1416 approach, with an associated directory like <EM>
1417 ../share/lib/bibclean/3.00</EM>. That allows an installation
1418 directory tree to be distributed to other systems and
1419 unbundled <EM>anywhere</EM> in the file system, as long as
1420 the relative paths are not changed. <EM>bibclean</EM> tests
1421 whether its compiled-in library path is a directory on the
1422 local system, and if so, uses it. Otherwise, it replaces
1423 that path by a reconstructed one based on the location of
1424 the executable program. If the reconstructed path for the
1425 library directory does not exist, it uses a warning. In
1426 either case, it continues normally.
1427 </P>
1428 <P>
1429 With the old approach, initialization files on Unix systems
1430 were named with a leading period, making them `hidden' files
1431 for the <EM>ls</EM> command. With the new practice,
1432 initialization files are no longer named as hidden files.
1433 <!-- ===================================================================== -->
1434 </P>
1435 <HR>
1436 <H1>
1437 <A NAME="HDR.7">
1438 INITIALIZATION FILES
1439 </A>
1440 </H1>
1441 <P>
1442 <STRONG>bibclean</STRONG> can be compiled with one of three
1443 different types of pattern matching; the choice is made by
1444 the installer at compile time:
1445 </P>
1446 <BLOCKQUOTE>
1447 <UL>
1448 <LI>
1449 The original version uses explicit hand-coded tests
1450 of value-string syntax.
1451 </LI>
1452 <LI>
1453 The second version uses regular-expression
1454 pattern-matching host library routines together with
1455 regular-expression patterns that come entirely from
1456 initialization files.
1457 </LI>
1458 <LI>
1459 The third version uses special patterns that come
1460 entirely from initialization files.
1461 </LI>
1462 </UL>
1463 </BLOCKQUOTE>
1464 <P>
1465 The second and third versions are the ones of most interest
1466 here, because they allow the user to control what values are
1467 considered acceptable. However, command-line options can
1468 also be specified in initialization files, no matter which
1469 pattern matching choice was selected.
1470 </P>
1471 <P>
1472 When <STRONG>bibclean</STRONG> starts, it searches for
1473 initialization files, finding the first one in the system
1474 executable program search path (on UNIX and IBM PC DOS,
1475 <STRONG>PATH</STRONG> ) and the first one in the <STRONG>
1476 BIBINPUTS</STRONG> search path, and processes them in turn.
1477 Then, when command-line arguments are processed, any
1478 additional files specified by <STRONG>-init-file</STRONG>
1479 <EM> filename</EM> options are also processed. Finally,
1480 immediately before each <EM>named</EM> bibliography file is
1481 processed, an attempt is made to process an initialization
1482 file with the same name, but with the extension changed to
1483 <EM>.ini</EM>. The default extension can be changed by a
1484 setting of the environment variable <STRONG>BIBCLEANEXT
1485 </STRONG>. That scheme permits system-wide, user-wide,
1486 session-wide, and file-specific initialization files to be
1487 supported.
1488 </P>
1489 <P>
1490 When input is taken from <EM>stdin</EM>, there is no
1491 file-specific initialization.
1492 </P>
1493 <P>
1494 For precise control, the <STRONG>-no-read-init-files
1495 </STRONG> option suppresses all initialization files except
1496 those explicitly named by <STRONG>-init-file</STRONG> <EM>
1497 filename</EM> options, either on the command line, or in
1498 requested initialization files.
1499 </P>
1500 <P>
1501 Recursive execution of initialization files with nested
1502 <STRONG>-init-file</STRONG> options is permitted; if the
1503 recursion is circular, <STRONG>bibclean</STRONG> finally
1504 gets a non-fatal initialization file open failure after
1505 opening too many files. That terminates further
1506 initialization file processing. As the recursion unwinds,
1507 the files are all closed, then execution proceeds normally.
1508 </P>
1509 <P>
1510 An initialization file may contain empty lines, comments
1511 from percent to end of line (just like TeX), option
1512 switches, and field/pattern or field/pattern/message
1513 assignments. Leading and trailing spaces are ignored. That
1514 is best illustrated by a short example:
1515 </P>
1516 <PRE>
1517 % This is a small bibclean initialization file
1518
1519 -init-file /u/math/bib/.bibcleanrc %% departmental patterns
1520
1521 chapter = &quot;\&quot;D\&quot;&quot; %% 23
1522
1523 pages = &quot;\&quot;D--D\&quot;&quot; %% 23--27
1524
1525 volume = &quot;\&quot;D \an\d D\&quot;&quot; %% 11 and 12
1526
1527 year = \
1528 &quot;\&quot;dddd, dddd, dddd\&quot;&quot; \
1529 &quot;Multiple years specified.&quot; %% 1989, 1990, 1991
1530
1531 -no-fix-names %% do not modify author/editor lists
1532 </PRE>
1533 <P>
1534 Long logical lines can be split into multiple physical lines
1535 by breaking at a backslash-newline pair; the
1536 backslash-newline pair is discarded. That processing happens
1537 while characters are being read, before any further
1538 interpretation of the input stream.
1539 </P>
1540 <P>
1541 Each logical line must contain a complete option (and its
1542 value, if any), or a complete field/pattern pair, or a
1543 field/pattern/message triple.
1544 </P>
1545 <P>
1546 Comments are stripped during the parsing of the field,
1547 pattern, and message values. The comment start symbol is
1548 not recognized inside quoted strings, so it can be freely
1549 used in such strings.
1550 </P>
1551 <P>
1552 Comments on logical lines that were input as multiple
1553 physical lines via the backslash-newline convention must
1554 appear on the <EM>last</EM> physical line; otherwise, the
1555 remaining physical lines become part of the comment.
1556 </P>
1557 <P>
1558 Pattern strings must be enclosed in quotation marks; within
1559 such strings, a backslash starts an escape mechanism that is
1560 commonly used in UNIX software. The recognized escape
1561 sequences are:
1562 </P>
1563 <BLOCKQUOTE>
1564 <DL>
1565 <DT>
1566 <STRONG>\a</STRONG>
1567 </DT>
1568 <DD>
1569 alarm bell (octal 007)
1570 </DD>
1571 <DT>
1572 <STRONG>\b</STRONG>
1573 </DT>
1574 <DD>
1575 backspace (octal 010)
1576 </DD>
1577 <DT>
1578 <STRONG>\f</STRONG>
1579 </DT>
1580 <DD>
1581 formfeed (octal 014)
1582 </DD>
1583 <DT>
1584 <STRONG>\n</STRONG>
1585 </DT>
1586 <DD>
1587 newline (octal 012)
1588 </DD>
1589 <DT>
1590 <STRONG>\r</STRONG>
1591 </DT>
1592 <DD>
1593 carriage return (octal 015)
1594 </DD>
1595 <DT>
1596 <STRONG>\t</STRONG>
1597 </DT>
1598 <DD>
1599 horizontal tab (octal 011)
1600 </DD>
1601 <DT>
1602 <STRONG>\v</STRONG>
1603 </DT>
1604 <DD>
1605 vertical tab (octal 013)
1606 </DD>
1607 <DT>
1608 <STRONG>\ooo</STRONG>
1609 </DT>
1610 <DD>
1611 character number octal <EM>ooo</EM> (e.g <STRONG>
1612 \012</STRONG> is linefeed). Up to 3 octal digits
1613 may be used.
1614 </DD>
1615 <DT>
1616 <STRONG>\0xhh</STRONG>
1617 </DT>
1618 <DD>
1619 character number hexadecimal <EM>hh</EM> (e.g.,
1620 <STRONG>\0x0a</STRONG> is linefeed). <EM>xhh</EM>
1621 may be in either letter case. Any number of
1622 hexadecimal digits may be used.
1623 </DD>
1624 </DL>
1625 </BLOCKQUOTE>
1626 <P>
1627 Backslash followed by any other character produces just that
1628 character. Thus, \% gets a literal percent into a string
1629 (preventing its interpretation as a comment), \&quot;
1630 produces a quotation mark, and \ produces a single
1631 backslash.
1632 </P>
1633 <P>
1634 An ASCII NUL <EM>(\0)</EM> in a string terminates it; that
1635 is a feature of the C programming language in which <STRONG>
1636 bibclean</STRONG> is implemented.
1637 </P>
1638 <P>
1639 Field/pattern pairs can be separated by arbitrary space, and
1640 optionally, either an equals sign or colon functioning as an
1641 assignment operator. Thus, the following are equivalent:
1642 </P>
1643 <PRE>
1644 pages=&quot;\&quot;D--D\&quot;&quot;
1645 pages:&quot;\&quot;D--D\&quot;&quot;
1646 pages &quot;\&quot;D--D\&quot;&quot;
1647 pages = &quot;\&quot;D--D\&quot;&quot;
1648 pages : &quot;\&quot;D--D\&quot;&quot;
1649 pages &quot;\&quot;D--D\&quot;&quot;
1650 </PRE>
1651 <P>
1652 Each field name can have an arbitrary number of patterns
1653 associated with it; however, they must be specified in
1654 separate field/pattern assignments.
1655 </P>
1656 <P>
1657 An empty pattern string causes previously-loaded patterns
1658 for that field name to be forgotten. That feature permits an
1659 initialization file to completely discard patterns from
1660 earlier initialization files.
1661 </P>
1662 <P>
1663 Patterns for value strings are represented in a tiny
1664 special-purpose language that is both convenient and
1665 suitable for bibliography value-string syntax checking.
1666 While not as powerful as the language of regular-expression
1667 patterns, its parsing can be portably implemented in less
1668 than 3% of the code in a widely-used regular-expression
1669 parser (the GNU <STRONG>regexp</STRONG> package).
1670 </P>
1671 <P>
1672 The patterns are represented by the following special
1673 characters:
1674 </P>
1675 <BLOCKQUOTE>
1676 <DL>
1677 <DT>
1678 <STRONG>&lt;space&gt;</STRONG>
1679 </DT>
1680 <DD>
1681 one or more spaces
1682 </DD>
1683 <DT>
1684 <STRONG>a</STRONG>
1685 </DT>
1686 <DD>
1687 exactly one letter
1688 </DD>
1689 <DT>
1690 <STRONG>A</STRONG>
1691 </DT>
1692 <DD>
1693 one or more letters
1694 </DD>
1695 <DT>
1696 <STRONG>d</STRONG>
1697 </DT>
1698 <DD>
1699 exactly one digit
1700 </DD>
1701 <DT>
1702 <STRONG>D</STRONG>
1703 </DT>
1704 <DD>
1705 one or more digits
1706 </DD>
1707 <DT>
1708 <STRONG>r</STRONG>
1709 </DT>
1710 <DD>
1711 exactly one Roman numeral
1712 </DD>
1713 <DT>
1714 <STRONG>R</STRONG>
1715 </DT>
1716 <DD>
1717 one or more Roman numerals (i.e. a Roman number)
1718 </DD>
1719 <DT>
1720 <STRONG>w</STRONG>
1721 </DT>
1722 <DD>
1723 exactly one word (one or more letters and digits)
1724 </DD>
1725 <DT>
1726 <STRONG>W</STRONG>
1727 </DT>
1728 <DD>
1729 one or more space-separated words, beginning and
1730 ending with a word
1731 </DD>
1732 <DT>
1733 <STRONG>.</STRONG>
1734 </DT>
1735 <DD>
1736 one `special' character, one of the characters &lt;
1737 space&gt;!#()*+,-./:;?[]~, a subset of punctuation
1738 characters that are typically used in string values
1739 </DD>
1740 <DT>
1741 <STRONG>:</STRONG>
1742 </DT>
1743 <DD>
1744 one or more `special' characters
1745 </DD>
1746 <DT>
1747 <STRONG>X</STRONG>
1748 </DT>
1749 <DD>
1750 one or more `special'-separated words, beginning and
1751 ending with a word
1752 </DD>
1753 <DT>
1754 <STRONG>\x</STRONG>
1755 </DT>
1756 <DD>
1757 exactly one x (x is any character), possibly with an
1758 escape sequence interpretation given earlier
1759 </DD>
1760 <DT>
1761 <STRONG>x</STRONG>
1762 </DT>
1763 <DD>
1764 exactly the character x (x is anything but one of
1765 these pattern characters: aAdDrRwW.:&lt;space&gt;\)
1766 </DD>
1767 </DL>
1768 </BLOCKQUOTE>
1769 <P>
1770 The <STRONG>X</STRONG> pattern character is very powerful,
1771 but generally inadvisable, because it matches almost
1772 anything likely to be found in a BibTeX value string. The
1773 reason for providing pattern matching on the value strings
1774 is to uncover possible errors, not mask them.
1775 </P>
1776 <P>
1777 There is no provision for specifying ranges or repetitions
1778 of characters, but that can usually be done with separate
1779 patterns. It is a good idea to accompany the pattern with a
1780 comment showing the kind of thing it is expected to match.
1781 Here is a portion of an initialization file giving a few of
1782 the patterns used to match <EM>number</EM> value strings:
1783 </P>
1784 <PRE>
1785 number = &quot;\&quot;D\&quot;&quot; %% 23
1786 number = &quot;\&quot;A AD\&quot;&quot; %% PN LPS5001
1787 number = &quot;\&quot;A D(D)\&quot;&quot; %% RJ 34(49)
1788 number = &quot;\&quot;A D\&quot;&quot; %% XNSS 288811
1789 number = &quot;\&quot;A D\.D\&quot;&quot; %% Version 3.20
1790 number = &quot;\&quot;A-A-D-D\&quot;&quot; %% UMIAC-TR-89-11
1791 number = &quot;\&quot;A-A-D\&quot;&quot; %% CS-TR-2189
1792 number = &quot;\&quot;A-A-D\.D\&quot;&quot; %% CS-TR-21.7
1793 </PRE>
1794 <P>
1795 For a bibliography that contains only <EM>article</EM>
1796 entries, that list should probably be reduced to just the
1797 first pattern, so that anything other than a digit string
1798 fails the pattern-match test. That is easily done by keeping
1799 bibliography-specific patterns in a corresponding file with
1800 extension <EM>.ini</EM>, because that file is read
1801 automatically.
1802 </P>
1803 <P>
1804 You should be sure to use empty pattern strings in the
1805 pattern file to discard patterns from earlier initialization
1806 files.
1807 </P>
1808 <P>
1809 The value strings passed to the pattern matcher contain
1810 surrounding quotes, so the patterns should also. However,
1811 you could use a pattern specification like &quot;\&quot;D
1812 &quot; to match an initial digit string followed by anything
1813 else; the omission of the final quotation mark \&quot; in
1814 the pattern allows the match to succeed without checking
1815 that the next character in the value string is a quotation
1816 mark.
1817 </P>
1818 <P>
1819 Because the value strings are intended to be processed by
1820 TeX, the pattern matching ignores braces, and TeX control
1821 sequences, together with any space following those control
1822 sequences. Spaces around braces are preserved. That
1823 convention allows the pattern fragment <EM>A-AD-D</EM> to
1824 match the value string <EM>TN-K\slash</EM> 27-70 <EM>,</EM>
1825 because the value is implicitly collapsed to <EM>TN-K27-70
1826 </EM> during the matching operation.
1827 </P>
1828 <P>
1829 <STRONG>bibclean</STRONG> 's normal action when a string
1830 value fails to match any of the corresponding patterns is to
1831 issue a <EM>warning</EM> message something like this: <EM>
1832 &quot;Unexpected value in ``year = &quot;192&quot;''</EM>.
1833 In most cases, that is sufficient to alert the user to a
1834 problem. In some cases, however, it may be desirable to
1835 associate a different message with a particular pattern.
1836 That can be done by supplying a message string following the
1837 pattern string. Format items <EM>%%</EM> (single percent),
1838 <EM>%e</EM> (entry name), <EM>%f</EM> (field name), <EM>%k
1839 </EM> (citation key), and <EM>%v</EM> (string value) are
1840 available to get current values expanded in the messages.
1841 Here is an example:
1842 </P>
1843 <PRE>
1844 chapter = &quot;\&quot;D:D\&quot;&quot; &quot;Colon found in ``%f = %v''&quot; %% 23:2
1845 </PRE>
1846 <P>
1847 To be consistent with other messages output by <STRONG>
1848 bibclean</STRONG>, the message string should <EM>not</EM>
1849 end with punctuation.
1850 </P>
1851 <P>
1852 If you wish to make the message an error, rather than just a
1853 warning, begin it with a query (?), like this:
1854 </P>
1855 <PRE>
1856 chapter = &quot;\&quot;D:D\&quot;&quot; &quot;?Colon found in ``%f = %v''&quot; %% 23:2
1857 </PRE>
1858 <P>
1859 The query is be included in the output message.
1860 </P>
1861 <P>
1862 Escape sequences are supported in message strings, just as
1863 they are in pattern strings. You can use that to advantage
1864 for fancy things, such as terminal display mode control. If
1865 you rewrite the previous example as
1866 </P>
1867 <PRE>
1868 chapter = &quot;\&quot;D:D\&quot;&quot; \
1869 &quot;?\033[7mColon found in ``%f = %v''\033[0m&quot; %% 23:2
1870 </PRE>
1871 <P>
1872 the error message appears in inverse video on display
1873 screens that support ANSI terminal control sequences. Such
1874 practice is not normally recommended, because it may have
1875 undesirable effects on some output devices. Nevertheless,
1876 you may find it useful for restricted applications.
1877 </P>
1878 <P>
1879 For some types of bibliography fields, <STRONG>bibclean
1880 </STRONG> contains special-purpose code to supplement or
1881 replace the pattern matching:
1882 </P>
1883 <BLOCKQUOTE>
1884 <UL>
1885 <LI>
1886 <EM>CODEN</EM>, <EM>ISBN</EM> and <EM>ISSN</EM>
1887 field values are handled that way because their
1888 validation requires evaluation of checksums that
1889 cannot be expressed by simple patterns; no patterns
1890 are even used in these three cases.
1891 </LI>
1892 <LI>
1893 When <STRONG>bibclean</STRONG> is compiled with
1894 pattern-matching code support, <EM>chapter</EM>,
1895 <EM>number</EM>, <EM>pages</EM>, and <EM>volume</EM>
1896 values are checked only by pattern matching.
1897 </LI>
1898 <LI>
1899 <EM>month</EM> values are first checked against the
1900 standard BibTeX month abbreviations, and only if no
1901 match is found are patterns then used.
1902 </LI>
1903 <LI>
1904 <EM>year</EM> values are first checked against
1905 patterns, then if no match is found, the year
1906 numbers are found and converted to integer values
1907 for testing against reasonable bounds.
1908 </LI>
1909 </UL>
1910 </BLOCKQUOTE>
1911 <P>
1912 Values for other fields are checked only against patterns.
1913 You can provide patterns for <EM>any</EM> field you like,
1914 even ones <STRONG>bibclean</STRONG> does not already know
1915 about. New ones are simply added to an internal table that
1916 is searched for each string to be validated.
1917 </P>
1918 <P>
1919 The special field, <EM>key</EM>, represents the
1920 bibliographic citation key. It can be given patterns, like
1921 any other field. Here is an initialization file pattern
1922 assignment that matches an author name, a colon, a
1923 four-digit year, a colon, and an alphabetic string, in the
1924 BibNet Project style:
1925 </P>
1926 <PRE>
1927 key = &quot;A:dddd:A&quot; %% Knuth:1986:TB
1928 </PRE>
1929 <P>
1930 Notice that no quotation marks are included in the pattern,
1931 because the citation keys are not quoted. You can use such
1932 patterns to help enforce uniform naming conventions for
1933 citation keys, which is increasingly important as your
1934 bibliography data base grows.
1935 <!-- ===================================================================== -->
1936 </P>
1937 <HR>
1938 <H1>
1939 <A NAME="HDR.8">
1940 ISBN INITIALIZATION FILES
1941 </A>
1942 </H1>
1943 <P>
1944 <STRONG>bibclean</STRONG> contains a compiled-in table of
1945 ISBN ranges and country/language settings that is suitable
1946 for most applications.
1947 </P>
1948 <P>
1949 However, ISBN data change yearly, as new countries adopt
1950 ISBNs, and as publishers are granted new, or additional,
1951 ISBN prefixes.
1952 </P>
1953 <P>
1954 Thus, from version 2.12, <STRONG>bibclean</STRONG> supports
1955 reading of run-time ISBN initialization files found on the
1956 <STRONG>PATH</STRONG> (for VAX VMS, <STRONG>SYS$SYSTEM
1957 </STRONG> ) and <STRONG>BIBINPUTS</STRONG> search paths, and
1958 then any specified by <STRONG>-ISBN-file</STRONG> <EM>
1959 filename</EM> options.
1960 </P>
1961 <P>
1962 That feature makes it possible to incorporate new ISBN data
1963 without having to produce a new <STRONG>bibclean</STRONG>
1964 release and reinstall the software at end-user sites.
1965 </P>
1966 <P>
1967 The format of an ISBN initialization file is similar to that
1968 of the <STRONG>bibclean</STRONG> initialization files
1969 described in the preceding section: comments begin with
1970 percent and continue to end of line, blank and empty lines
1971 are ignored, backslash-newline joins adjacent lines, and
1972 otherwise, lines are expected to contain a required pair of
1973 ISBN country/language-publisher prefixes forming a
1974 non-decreasing range, optionally followed by one or more
1975 words of text that are treated as the country/language group
1976 value. The latter value plays no part in ISBN validation,
1977 but its presence is strongly recommended, in order to make
1978 the ISBN table more understandable for humans.
1979 </P>
1980 <P>
1981 Here is a short example:
1982 </P>
1983 <BLOCKQUOTE>
1984 <PRE>
1985 %% The Faeroes got ISBN assignments between 1993 and 1998
1986 99918-0 99918-3 Faeroes
1987 99918-40 99918-61
1988 99918-900 99918-938
1989 </PRE>
1990 </BLOCKQUOTE>
1991 It is not necessary to repeat the country names on succeeding
1992 entries with the same initial number (99918 in that example);
1993 that is handled internally.
1994 <P>
1995 Data from ISBN files normally augment the compiled-in data.
1996 However, if the first prefix begins with a hyphen, then
1997 <STRONG>bibclean</STRONG> deletes the first entry in the
1998 table matching that first prefix (ignoring the leading
1999 hyphen):
2000 </P>
2001 <BLOCKQUOTE>
2002 <PRE>
2003 %% Latvia got ISBN ranges between 1993 and 1998
2004 %% so we remove the old placeholder, then add the
2005 %% new ranges.
2006 -9984-0 9984-9 This one is no longer valid
2007
2008 9984-00 9984-20 Latvia
2009 9984-500 9984-770
2010 9984-9000 9984-9984
2011 </PRE>
2012 </BLOCKQUOTE>
2013 <!-- ===================================================================== -->
2014 <HR>
2015 <H1>
2016 <A NAME="HDR.9">
2017 KEYWORD INITIALIZATION FILES
2018 </A>
2019 </H1>
2020 <P>
2021 <STRONG>bibclean</STRONG> contains a compiled-in table of
2022 keyword mappings that is suitable for most applications.
2023 The default settings merely adjust lettercase in certain
2024 keyword names, so that, for example, <EM>isbn</EM> is output
2025 as <EM>ISBN</EM>.
2026 </P>
2027 <P>
2028 From version 2.12, <STRONG>bibclean</STRONG> supports
2029 reading of run-time keyword initialization files found on
2030 the <STRONG>PATH</STRONG> (for VAX VMS, <STRONG>SYS$SYSTEM
2031 </STRONG> ) and <STRONG>BIBINPUTS</STRONG> search paths, and
2032 then any specified by <STRONG>-keyword-file</STRONG> <EM>
2033 filename</EM> options.
2034 </P>
2035 <P>
2036 That feature makes it possible to incorporate special
2037 spellings of new keywords without having to produce a new
2038 <STRONG>bibclean</STRONG> release and reinstall the software
2039 at end-user sites.
2040 </P>
2041 <P>
2042 The format of a keyword initialization file is similar to
2043 that of the other <STRONG>bibclean</STRONG> initialization
2044 files described in the preceding sections: comments begin
2045 with percent and continue to end of line, blank and empty
2046 lines are ignored, backslash-newline joins adjacent lines,
2047 and otherwise, lines are expected to contain a required pair
2048 of old and new keyword names.
2049 </P>
2050 <P>
2051 Here is a short example:
2052 </P>
2053 <BLOCKQUOTE>
2054 <PRE>
2055 %% We want special handling of MathReviews keywords
2056 mrclass MRclass
2057 mrnumber MRnumber
2058 mrreviewer MRreviewer
2059 </PRE>
2060 </BLOCKQUOTE>
2061 <P>
2062 Data from keywords files normally augment the compiled-in
2063 data. However, if the first keyword begins with a hyphen,
2064 then <STRONG>bibclean</STRONG> deletes the first entry in
2065 the table matching that keyword (ignoring the leading
2066 hyphen):
2067 </P>
2068 <BLOCKQUOTE>
2069 <PRE>
2070 %% Remove special handling of ISBN, ISSN, and LCCN values.
2071 -issn ISSN
2072 -isbn ISBN
2073 -lccn LCCN
2074 </PRE>
2075 </BLOCKQUOTE>
2076 Even though the second keyword in each deletion pair is not
2077 used, it still must be specified.
2078 <P>
2079 Notice that this feature can be used to regularize keyword
2080 names, but use it with care, in order to avoid producing
2081 duplicate key names in output BibTeX entries:
2082 </P>
2083 <BLOCKQUOTE>
2084 <PRE>
2085 %% Map variations of keywords into a common name:
2086 keys keywords
2087 keywds keywords
2088 keyword keywords
2089 keywrd keywords
2090 keywrds keywords
2091 searchkey keywords
2092 </PRE>
2093 </BLOCKQUOTE>
2094 <!-- ===================================================================== -->
2095 <HR>
2096 <H1>
2097 <A NAME="HDR.10">
2098 LEXICAL ANALYSIS
2099 </A>
2100 </H1>
2101 <P>
2102 When <STRONG>-no-prettyprint</STRONG> is specified, <STRONG>
2103 bibclean</STRONG> acts as a lexical analyzer instead of a
2104 prettyprinter, producing output in lines of the form
2105 </P>
2106 <BLOCKQUOTE>
2107 <PRE>
2108 &lt;token-number&gt;&lt;tab&gt;&lt;token-name&gt;&lt;tab&gt;&quot;&lt;token-value&gt;&quot;
2109 </PRE>
2110 </BLOCKQUOTE>
2111 <P>
2112 Each output line contains a single complete token,
2113 identified by a small integer number for use by a computer
2114 program, a token type name for human readers, and a string
2115 value in quotes.
2116 </P>
2117 <P>
2118 Special characters in the token value string are represented
2119 with ANSI/ISO Standard C escape sequences, so all characters
2120 other than NUL are representable, and multi-line values can
2121 be represented in a single line.
2122 </P>
2123 <P>
2124 Here are the token numbers and token type names that can
2125 appear in the output when <STRONG>-prettyprint</STRONG> is
2126 specified:
2127 </P>
2128 <BLOCKQUOTE>
2129 <PRE>
2130 0 UNKNOWN
2131 1 ABBREV
2132 2 AT
2133 3 COMMA
2134 4 COMMENT
2135 5 ENTRY
2136 6 EQUALS
2137 7 FIELD
2138 8 INCLUDE
2139 9 INLINE
2140 10 KEY
2141 11 LBRACE
2142 12 LITERAL
2143 13 NEWLINE
2144 14 PREAMBLE
2145 15 RBRACE
2146 16 SHARP
2147 17 SPACE
2148 18 STRING
2149 19 VALUE
2150 </PRE>
2151 </BLOCKQUOTE>
2152 <P>
2153 Programs that parse such output should also be prepared for
2154 lines beginning with the warning prefix, %%, or the error
2155 prefix, ??, and for ANSI/ISO Standard C line-number
2156 directives of the form
2157 </P>
2158 <BLOCKQUOTE>
2159 # line 273 &quot;texbook1.bib&quot;
2160 </BLOCKQUOTE>
2161 that record the line number and file name of the current input
2162 file.
2163 <P>
2164 If a <STRONG>-max-width</STRONG> <EM> nnn</EM> command-line
2165 option was specified, long output lines are wrapped at a
2166 backslash-newline pair, and consequently, software that
2167 processes the lexical token stream should be prepared to
2168 collapse such wrapped lines back into single lines.
2169 </P>
2170 <P>
2171 As an example of the use of <STRONG>-no-prettyprint</STRONG>
2172 ,
2173 the UNIX command pipeline
2174 </P>
2175 <BLOCKQUOTE>
2176 <PRE>
2177 <STRONG>bibclean -no-prettyprint</STRONG> <EM>mylib.bib</EM> | \
2178 <STRONG>awk</STRONG> '$2 == &quot;KEY&quot; {print $3}' | \
2179 <STRONG>sed</STRONG> -e 's/&quot;//g' | \
2180 <STRONG>sort</STRONG>
2181 </PRE>
2182 </BLOCKQUOTE>
2183 extracts a sorted list of all citation keys in the file <EM>
2184 mylib.bib</EM>.
2185 <P>
2186 A certain amount of processing has been done on the tokens.
2187 In particular, delimiters equivalent to braces have been
2188 replaced by braces, and braced strings have become quoted
2189 strings.
2190 </P>
2191 <P>
2192 The LITERAL token type is used for arbitrary text that
2193 <STRONG>bibclean</STRONG> does not examine further, such as
2194 the contents of a @Preamble{...} or a @Comment{...}.
2195 </P>
2196 <P>
2197 The UNKNOWN token type should never appear in the output
2198 stream. It is used internally to initialize token type
2199 variables.
2200 <!-- ===================================================================== -->
2201 </P>
2202 <HR>
2203 <H1>
2204 <A NAME="HDR.11">
2205 SCRIBE BIBLIOGRAPHY FORMAT
2206 </A>
2207 </H1>
2208 <P>
2209 <STRONG>bibclean</STRONG> 's support for the Scribe
2210 bibliography format is based on the syntax description in
2211 the Scribe Introductory User's Manual, 3rd Edition, May
2212 1980. Scribe was originally developed by Brian Reid at
2213 Carnegie-Mellon University, and was marketed by Unilogic,
2214 Ltd., later renamed to Scribe Systems, and apparently now
2215 long defunct.
2216 </P>
2217 <P>
2218 The BibTeX bibliography format was strongly influenced by
2219 Scribe, and indeed, with care, it is possible to share
2220 bibliography files between the two systems. Nevertheless,
2221 there are some differences, so here is a summary of features
2222 of the Scribe bibliography file format:
2223 </P>
2224 <DL>
2225 <DT>
2226 (1)
2227 </DT>
2228 <DD>
2229 Letter case is not significant in field names and entry
2230 names, but case is preserved in value strings.
2231 </DD>
2232 <DT>
2233 (2)
2234 </DT>
2235 <DD>
2236 In field/value pairs, the field and value may be
2237 separated by one of three characters: =, /, or space.
2238 Space may optionally surround these separators.
2239 </DD>
2240 <DT>
2241 (3)
2242 </DT>
2243 <DD>
2244 Value delimiters are any of these seven pairs: { } [ ]
2245 ( ) &lt; &gt; ' ' &quot; &quot; ` `
2246 </DD>
2247 <DT>
2248 (4)
2249 </DT>
2250 <DD>
2251 Value delimiters may not be nested, even though with the
2252 first four delimiter pairs, nested balanced delimiters
2253 would be unambiguous.
2254 </DD>
2255 <DT>
2256 (5)
2257 </DT>
2258 <DD>
2259 Delimiters can be omitted around values that contain
2260 only letters, digits, sharp (#), ampersand (&amp;),
2261 period (.), and percent (%).
2262 </DD>
2263 <DT>
2264 (6)
2265 </DT>
2266 <DD>
2267 Outside of delimited values, a literal at-sign (@) is
2268 represented by doubled at-signs (@@).
2269 </DD>
2270 <DT>
2271 (7)
2272 </DT>
2273 <DD>
2274 Bibliography entries begin with @name, as for BibTeX,
2275 but any of the seven Scribe value delimiter pairs may be
2276 used to surround the values in field/value pairs. As in
2277 (4), nested delimiters are forbidden.
2278 </DD>
2279 <DT>
2280 (8)
2281 </DT>
2282 <DD>
2283 Arbitrary space may separate entry names from the
2284 following delimiters.
2285 </DD>
2286 <DT>
2287 (9)
2288 </DT>
2289 <DD>
2290 @Comment is a special command whose delimited value is
2291 discarded. As in (4), nested delimiters are forbidden.
2292 </DD>
2293 <DT>
2294 (10)
2295 </DT>
2296 <DD>
2297 The special form
2298 <PRE>
2299 @Begin{comment}
2300 ...
2301 @End{comment}
2302 </PRE>
2303 <P>
2304 permits encapsulating arbitrary text containing any
2305 characters or delimiters, other than
2306 ``@End{comment}''. Any of the seven delimiter pairs
2307 may be used around the word ``comment'' following
2308 the ``@Begin'' or ``@End''; the delimiters in the
2309 two cases need not be the same, and consequently,
2310 ``@Begin{comment}''/``@End{comment}'' pairs may <EM>
2311 not</EM> be nested.
2312 </P>
2313 </DD>
2314 <DT>
2315 (11)
2316 </DT>
2317 <DD>
2318 The <EM>key</EM> field is required in each bibliography
2319 entry.
2320 </DD>
2321 <DT>
2322 (12)
2323 </DT>
2324 <DD>
2325 A backslashed quote in a string is assumed to be a TeX
2326 accent, and braced appropriately. While such accents do
2327 not conform to Scribe syntax, Scribe-format
2328 bibliographies have been found that appear to be
2329 intended for TeX processing.
2330 </DD>
2331 </DL>
2332 Because of that loose syntax, <STRONG>bibclean</STRONG> 's
2333 normal error detection heuristics are less effective, and
2334 consequently, Scribe mode input is not the default; it must be
2335 explicitly requested.
2336 <!-- ===================================================================== -->
2337 <HR>
2338 <H1>
2339 <A NAME="HDR.12">
2340 ENVIRONMENT VARIABLES
2341 </A>
2342 </H1>
2343 <P>
2344 <!-- _______________________________________________ -->
2345 </P>
2346 <DL>
2347 <DT>
2348 <STRONG>BIBCLEANEXT</STRONG>
2349 </DT>
2350 <DD>
2351 File extension of bibliography-specific initialization
2352 files. Default: <EM>.ini</EM>.
2353 <!-- _______________________________________________ -->
2354 </DD>
2355 <DT>
2356 <STRONG>BIBCLEANINI</STRONG>
2357 </DT>
2358 <DD>
2359 Name of <STRONG>bibclean</STRONG> initialization files.
2360 Default: <EM>.bibcleanrc</EM> (UNIX), <EM>bibclean.ini
2361 </EM> (non-UNIX).
2362 <!-- _______________________________________________ -->
2363 </DD>
2364 <DT>
2365 <STRONG>BIBCLEANISBN</STRONG>
2366 </DT>
2367 <DD>
2368 Name of <STRONG>bibclean</STRONG> ISBN initialization
2369 files. Default: <EM>.bibclean.isbn</EM> (UNIX), <EM>
2370 bibclean.isb</EM> (non-UNIX).
2371 <!-- _______________________________________________ -->
2372 </DD>
2373 <DT>
2374 <STRONG>BIBCLEANKEY</STRONG>
2375 </DT>
2376 <DD>
2377 Name of <STRONG>bibclean</STRONG> keyword initialization
2378 files. Default: <EM>.bibclean.key</EM> (UNIX), <EM>
2379 bibclean.key</EM> (non-UNIX).
2380 <!-- _______________________________________________ -->
2381 </DD>
2382 <DT>
2383 <STRONG>BIBINPUTS</STRONG>
2384 </DT>
2385 <DD>
2386 Search path for <STRONG>bibclean</STRONG> and BibTeX
2387 input files. On UNIX, it is a colon-separated list of
2388 directories that are searched in order from first to
2389 last. It is not an error for a specified directory to
2390 not exist.
2391 <P>
2392 On other operating systems, the directory names
2393 should be separated by whatever character is used in
2394 system search path specifications, such as a
2395 semicolon on IBM PC DOS.
2396 <!-- _______________________________________________ -->
2397 </P>
2398 </DD>
2399 <DT>
2400 <STRONG>PATH</STRONG>
2401 </DT>
2402 <DD>
2403 On Atari TOS, IBM PC DOS, IBM PC OS/2, Microsoft NT, and
2404 UNIX, search path for system executable files. The
2405 system-wide <STRONG>bibclean</STRONG> initialization
2406 file is searched for in that path.
2407 <!-- _______________________________________________ -->
2408 </DD>
2409 <DT>
2410 <STRONG>SYS$SYSTEM</STRONG>
2411 </DT>
2412 <DD>
2413 On VAX VMS, search path for system executable files and
2414 the system-wide <STRONG>bibclean</STRONG> initialization
2415 file.
2416 <!-- ===================================================================== -->
2417 </DD>
2418 </DL>
2419 <HR>
2420 <H1>
2421 <A NAME="HDR.13">
2422 FILES
2423 </A>
2424 </H1>
2425 <P>
2426 <!-- _______________________________________________ -->
2427 </P>
2428 <DL>
2429 <DT>
2430 <EM>*.bib</EM>
2431 </DT>
2432 <DD>
2433 BibTeX and Scribe bibliography data base files.
2434 <!-- _______________________________________________ -->
2435 </DD>
2436 <DT>
2437 <EM>*.ini</EM>
2438 </DT>
2439 <DD>
2440 File-specific initialization files.
2441 <!-- _______________________________________________ -->
2442 </DD>
2443 <DT>
2444 <EM>.bibclean.isbn</EM>
2445 </DT>
2446 <DD>
2447 UNIX system-wide and user-specific ISBN initialization
2448 files.
2449 <!-- _______________________________________________ -->
2450 </DD>
2451 <DT>
2452 <EM>.bibclean.key</EM>
2453 </DT>
2454 <DD>
2455 UNIX system-wide and user-specific keyword
2456 initialization files.
2457 <!-- _______________________________________________ -->
2458 </DD>
2459 <DT>
2460 <EM>.bibcleanrc</EM>
2461 </DT>
2462 <DD>
2463 UNIX system-wide and user-specific initialization files.
2464 <!-- _______________________________________________ -->
2465 </DD>
2466 <DT>
2467 <EM>bibclean.ini</EM>
2468 </DT>
2469 <DD>
2470 Non-UNIX system-wide and user-specific initialization
2471 files.
2472 <!-- _______________________________________________ -->
2473 </DD>
2474 <DT>
2475 <EM>bibclean.isb</EM>
2476 </DT>
2477 <DD>
2478 Non-UNIX system-wide and user-specific ISBN
2479 initialization files.
2480 <!-- _______________________________________________ -->
2481 </DD>
2482 <DT>
2483 <EM>bibclean.key</EM>
2484 </DT>
2485 <DD>
2486 Non-UNIX system-wide and user-specific keyword
2487 initialization files.
2488 <!-- ===================================================================== -->
2489 </DD>
2490 </DL>
2491 <HR>
2492 <H1>
2493 <A NAME="HDR.14">
2494 SEE ALSO
2495 </A>
2496 </H1>
2497 <P>
2498 <A HREF="../man1/bibcheck.html">
2499 <STRONG>bibcheck</STRONG>
2500 </A>
2501 (1),
2502 <A HREF="../man1/bibdup.html">
2503 <STRONG>bibdup</STRONG>
2504 </A>
2505 (1),
2506 <A HREF="../man1/bibextract.html">
2507 <STRONG>bibextract</STRONG>
2508 </A>
2509 (1),
2510 <A HREF="../man1/bibindex.html">
2511 <STRONG>bibindex</STRONG>
2512 </A>
2513 (1),
2514 <A HREF="../man1/bibjoin.html">
2515 <STRONG>bibjoin</STRONG>
2516 </A>
2517 (1),
2518 <A HREF="../man1/biblabel.html">
2519 <STRONG>biblabel</STRONG>
2520 </A>
2521 (1),
2522 <A HREF="../man1/biblex.html">
2523 <STRONG>biblex</STRONG>
2524 </A>
2525 (1),
2526 <A HREF="../man1/biblook.html">
2527 <STRONG>biblook</STRONG>
2528 </A>
2529 (1),
2530 <A HREF="../man1/biborder.html">
2531 <STRONG>biborder</STRONG>
2532 </A>
2533 (1),
2534 <A HREF="../man1/bibparse.html">
2535 <STRONG>bibparse</STRONG>
2536 </A>
2537 (1),
2538 <A HREF="../man1/bibsearch.html">
2539 <STRONG>bibsearch</STRONG>
2540 </A>
2541 (1),
2542 <A HREF="../man1/bibsort.html">
2543 <STRONG>bibsort</STRONG>
2544 </A>
2545 (1),
2546 <A HREF="../man1/bibtex.html">
2547 <STRONG>bibtex</STRONG>
2548 </A>
2549 (1),
2550 <A HREF="../man1/bibunlex.html">
2551 <STRONG>bibunlex</STRONG>
2552 </A>
2553 (1),
2554 <A HREF="../man1/citefind.html">
2555 <STRONG>citefind</STRONG>
2556 </A>
2557 (1),
2558 <A HREF="../man1/citesub.html">
2559 <STRONG>citesub</STRONG>
2560 </A>
2561 (1),
2562 <A HREF="../man1/citetags.html">
2563 <STRONG>citetags</STRONG>
2564 </A>
2565 (1),
2566 <A HREF="../man1/latex.html">
2567 <STRONG>latex</STRONG>
2568 </A>
2569 (1),
2570 <A HREF="../man1/scribe.html">
2571 <STRONG>scribe</STRONG>
2572 </A>
2573 (1),
2574 <A HREF="../man1/tex.html">
2575 <STRONG>tex</STRONG>
2576 </A>
2577 (1).
2578 <!-- ===================================================================== -->
2579 </P>
2580 <HR>
2581 <H1>
2582 <A NAME="HDR.15">
2583 AUTHOR
2584 </A>
2585 </H1>
2586 <PRE>
2587 Nelson H. F. Beebe
2588 University of Utah
2589 Department of Mathematics, 110 LCB
2590 155 S 1400 E RM 233
2591 Salt Lake City, UT 84112-0090
2592 USA
2593 Tel: +1 801 581 5254
2594 FAX: +1 801 581 4148
2595 Email: <A HREF="mailto:[email protected]">[email protected]</A>, <A HREF="mailto:[email protected]">[email protected]</A>, <A HREF="mailto:[email protected]">[email protected]</A> (Internet)
2596 URL: <A HREF="http://www.math.utah.edu/~beebe">http://www.math.utah.edu/~beebe</A>
2597 </PRE>
2598 <!-- ===================================================================== -->
2599 <HR>
2600 <H1>
2601 <A NAME="HDR.16">
2602 COPYRIGHT
2603 </A>
2604 </H1>
2605 <PRE>
2606 <TT>########################################################################
2607 ########################################################################
2608 ########################################################################
2609 ### ###
2610 ### bibclean: prettyprint and syntax check BibTeX and Scribe ###
2611 ### bibliography data base files ###
2612 ### ###
2613 ### Copyright (C) 1990--2016 Nelson H. F. Beebe ###
2614 ### ###
2615 ### This program is covered by the GNU General Public License (GPL), ###
2616 ### version 2 or later, available as the file COPYING in the program ###
2617 ### source distribution, and on the Internet at ###
2618 ### ###
2619 ### <A HREF="ftp://ftp.gnu.org/gnu/GPL">ftp://ftp.gnu.org/gnu/GPL</A> ###
2620 ### ###
2621 ### <A HREF="http://www.gnu.org/copyleft/gpl.html">http://www.gnu.org/copyleft/gpl.html</A> ###
2622 ### ###
2623 ### This program is free software; you can redistribute it and/or ###
2624 ### modify it under the terms of the GNU General Public License as ###
2625 ### published by the Free Software Foundation; either version 2 of ###
2626 ### the License, or (at your option) any later version. ###
2627 ### ###
2628 ### This program is distributed in the hope that it will be useful, ###
2629 ### but WITHOUT ANY WARRANTY; without even the implied warranty of ###
2630 ### MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the ###
2631 ### GNU General Public License for more details. ###
2632 ### ###
2633 ### You should have received a copy of the GNU General Public ###
2634 ### License along with this program; if not, write to the Free ###
2635 ### Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, ###
2636 ### MA 02111-1307 USA ###
2637 ########################################################################
2638 ########################################################################
2639 ########################################################################</TT>
2640 </PRE>
2641 <!-- ===================================================================== -->
2642 <!-- This is for GNU Emacs file_specific customization: -->
2643 <!-- Local Variables: -->
2644 <!-- fill_column: 50 -->
2645 <!-- End: -->
2646 </BODY>
2647 </HTML>