| 1 |
%% :0:Unrecognized option switch: -bogus-option. |
| 2 |
bibclean Version 3.07 [26-Dec-2021] |
| 3 |
|
| 4 |
with native pattern matching |
| 5 |
E-mail bug reports to Nelson H. F. Beebe <[email protected]> |
| 6 |
|
| 7 |
Copyright (C) 1990--2021 by Nelson H. F. Beebe and the Free Software Foundation, Inc. |
| 8 |
This is free software; see the source for copying conditions. There is NO |
| 9 |
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. |
| 10 |
|
| 11 |
Usage: ../bibclean [ -author ] [ -copyleft ] [ -copyright ] |
| 12 |
[ -error-log filename ] [ -help ] [ '-?' ] |
| 13 |
[ -init-file filename ] [ -ISBN-file filename ] |
| 14 |
[ -keyword-file filename ] [ -max-width nnn ] |
| 15 |
[ -[no-]align-equals ] [ -[no-]brace-protect ] |
| 16 |
[ -[no-]check-values ] [ -[no-]debug-match-failures ] |
| 17 |
[ -[no-]delete-empty-values ] [ -[no-]file-position ] |
| 18 |
[ -[no-]fix-accents ] [ -[no-]fix-braces ] [ -[no-]fix-degrees ] |
| 19 |
[ -[no-]fix-font-changes ] [ -[no-]fix-initials ] |
| 20 |
[ -[no-]fix-math ] [ -[no-]fix-names ] [ -[no-]German-style ] |
| 21 |
[ -[no-]keep-linebreaks ] [ -[no-]keep-parbreaks ] |
| 22 |
[ -[no-]keep-preamble-spaces ] [ -[no-]keep-spaces ] |
| 23 |
[ -[no-]keep-string-spaces ] [ -[no-]parbreaks ] |
| 24 |
[ -[no-]prettyprint ] [ -[no-]print-ISBN-table ] |
| 25 |
[ -[no-]print-keyword-table ] [ -[no-]print-patterns ] |
| 26 |
[ -[no-]quiet ] [ -[no-]read-init-files ] |
| 27 |
[ -[no-]remove-OPT-prefixes ] [ -[no-]scribe ] |
| 28 |
[ -[no-]trace-file-opening ] [ -[no-]warnings ] |
| 29 |
[ -output-file filename ] [ -version ] |
| 30 |
[ <infile or bibfile1 bibfile2 bibfile3 ...] >outfile |
| 31 |
|
| 32 |
Command-line switches may be abbreviated to a unique leading prefix, |
| 33 |
and letter case is not significant. All options are parsed before any |
| 34 |
input bibliography files are read, no matter what their order on the |
| 35 |
command line. Options that correspond to a yes/no setting of a flag |
| 36 |
have a form with a prefix "no-" to set the flag to no. For such |
| 37 |
options, the last setting determines the flag value used. That is |
| 38 |
significant when options are also specified in initialization files |
| 39 |
(see the INITIALIZATION FILES manual section). |
| 40 |
|
| 41 |
The leading hyphen that distinguishes an option from a filename may be |
| 42 |
doubled, for compatibility with GNU and POSIX conventions. Thus, |
| 43 |
-author and --author are equivalent. |
| 44 |
|
| 45 |
To avoid confusion with options, if a filename begins with a hyphen, it |
| 46 |
must be disguised by a leading absolute or relative directory path, |
| 47 |
e.g., /tmp/-foo.bib or ./-foo.bib. |
| 48 |
|
| 49 |
-author Display an author credit on the standard error unit, stderr, |
| 50 |
and then terminate with a success return code. Sometimes an |
| 51 |
executable program is separated from its documentation and |
| 52 |
source code; this option provides a way to recover from that. |
| 53 |
|
| 54 |
-copyleft Display copyright information on the standard error unit, |
| 55 |
stderr, and then terminate with a success return code. |
| 56 |
|
| 57 |
-copyright |
| 58 |
Display copyright information on the standard error unit, |
| 59 |
stderr, and then terminate with a success return code. |
| 60 |
|
| 61 |
-error-log filename |
| 62 |
Redirect stderr to the indicated file, which then contains |
| 63 |
all of the error and warning messages. This option is |
| 64 |
provided for those systems that have difficulty redirecting |
| 65 |
stderr. |
| 66 |
|
| 67 |
-help or -? |
| 68 |
Display a help message on stderr, giving a usage description, |
| 69 |
similar to this section of the manual pages, and then |
| 70 |
terminate with a success return code. |
| 71 |
|
| 72 |
-ISBN-file filename |
| 73 |
Provide an explicit ISBN-range initialization file. It is |
| 74 |
processed after any system-wide and job-wide ISBN |
| 75 |
initialization files found on the PATH (for VAX VMS, |
| 76 |
SYS$SYSTEM) and BIBINPUTS search paths, respectively, and may |
| 77 |
override them. The ISBN initialization file name can be |
| 78 |
changed at compile time, or at run time through a setting of |
| 79 |
the environment variable BIBCLEANISBN, but defaults to |
| 80 |
.bibclean.isbn on UNIX, and bibclean.isb elsewhere. For |
| 81 |
further details, see the ISBN INITIALIZATION FILES manual |
| 82 |
section. |
| 83 |
|
| 84 |
-init-file filename |
| 85 |
Provide an explicit value pattern initialization file. It is |
| 86 |
processed after any system-wide and job-wide initialization |
| 87 |
files found on the PATH (for VAX VMS, SYS$SYSTEM) and |
| 88 |
BIBINPUTS search paths, respectively, and may override them. |
| 89 |
It in turn may be overridden by a subsequent file-specific |
| 90 |
initialization file. The initialization file name can be |
| 91 |
changed at compile time, or at run time through a setting of |
| 92 |
the environment variable BIBCLEANINI, but defaults to |
| 93 |
.bibcleanrc on UNIX, and to bibclean.ini elsewhere. For |
| 94 |
further details, see the INITIALIZATION FILES manual section. |
| 95 |
|
| 96 |
-keyword-file filename |
| 97 |
Provide an explicit keyword initialization file. It is |
| 98 |
processed after any system-wide and job-wide keyword |
| 99 |
initialization files found on the PATH (for VAX VMS, |
| 100 |
SYS$SYSTEM) and BIBINPUTS search paths, respectively, and may |
| 101 |
override them. The keyword initialization file name can be |
| 102 |
changed at compile time, or at run time through a setting of |
| 103 |
the environment variable BIBCLEANKEY, but defaults to |
| 104 |
.bibclean.key on UNIX, and bibclean.key elsewhere. For |
| 105 |
further details, see the KEYWORD INITIALIZATION FILES manual |
| 106 |
section. |
| 107 |
|
| 108 |
-max-width nnn |
| 109 |
bibclean normally limits output line widths to 72 characters, |
| 110 |
and in the interests of consistency, that value should not be |
| 111 |
changed. Occasionally, special-purpose applications may |
| 112 |
require different maximum line widths, so this option |
| 113 |
provides that capability. The number following the option |
| 114 |
name can be specified in decimal, octal (starting with 0), or |
| 115 |
hexadecimal (starting with 0x). A zero or negative value is |
| 116 |
interpreted to mean unlimited, so -max-width 0 can be used to |
| 117 |
ensure that each field/value pair appears on a single line. |
| 118 |
|
| 119 |
When -no-prettyprint requests bibclean to act as a lexical |
| 120 |
analyzer, the default line width is unlimited, unless |
| 121 |
overridden by this option. |
| 122 |
|
| 123 |
When bibclean is prettyprinting, line wrapping is done only |
| 124 |
at a space. Consequently, a long non-blank character sequence |
| 125 |
may result in the output exceeding the requested line width. |
| 126 |
|
| 127 |
When bibclean is lexing, line wrapping is done by inserting a |
| 128 |
backslash-newline pair when the specified maximum is reached, |
| 129 |
so no line length ever exceeds the maximum. |
| 130 |
|
| 131 |
-[no-]align-equals |
| 132 |
With the positive form, align the equals sign in key/value |
| 133 |
assignments at the same column, separated by a single space |
| 134 |
from the value string. Otherwise, the equals sign follows |
| 135 |
the key, separated by a single space. Default: no. |
| 136 |
|
| 137 |
-[no-]brace-protect |
| 138 |
Protect uppercase and mixedcase words at brace-level zero |
| 139 |
with braces to prevent downcasing by some BibTeX styles. |
| 140 |
Default: yes. |
| 141 |
|
| 142 |
-[no-]check-values |
| 143 |
With the positive form, apply heuristic pattern matching to |
| 144 |
field values in order to detect possible errors (e.g., ``year |
| 145 |
= "192"'' instead of ``year = "1992"''), and issue warnings |
| 146 |
when unexpected patterns are found. |
| 147 |
|
| 148 |
That checking is usually beneficial, but if it produces too |
| 149 |
many bogus warnings for a particular bibliography file, you |
| 150 |
can disable it with the negative form of this option. |
| 151 |
Default: yes. |
| 152 |
|
| 153 |
-[no-]debug-match-failures |
| 154 |
With the positive form, print out a warning when a value |
| 155 |
pattern fails to match a value string. |
| 156 |
|
| 157 |
That is helpful in debugging new patterns, but because the |
| 158 |
output can be voluminous, you should use this option only |
| 159 |
with small test files, and initialization files that |
| 160 |
eliminate all patterns apart from the ones that you are |
| 161 |
testing. Default: no. |
| 162 |
|
| 163 |
-[no-]delete-empty-values |
| 164 |
With the positive form, remove all field/value pairs for |
| 165 |
which the value is an empty string. That is helpful in |
| 166 |
cleaning up bibliographies generated from text editor |
| 167 |
templates. Compare this option with -[no-]remove-OPT-prefixes |
| 168 |
described below. Default: no. |
| 169 |
|
| 170 |
-[no-]file-position |
| 171 |
With the positive form, give detailed file position |
| 172 |
information in warning and error messages. Default: no. |
| 173 |
|
| 174 |
-[no-]fix-accents |
| 175 |
With the positive form, normalize TeX accents in annotes, |
| 176 |
authors, booktitles, editors, notes, remarks, and titles. |
| 177 |
Default: no. |
| 178 |
|
| 179 |
-[no-]fix-braces |
| 180 |
With the positive form, normalize bracing in annotes, |
| 181 |
authors, booktitles, editors, notes, remarks, and titles, by |
| 182 |
removing unnecessary levels of braces. Default: no. |
| 183 |
|
| 184 |
-[no-]fix-degrees |
| 185 |
With the positive form, remove spaces in author/editor fields |
| 186 |
inside braces after letter-ending periods. That makes |
| 187 |
reductions from J. J. {Thomson, M. A., F. R. S.}, Frederick |
| 188 |
{Soddy, B. A. (Oxon.)}, and John A. {Cable, M. A., M. Ed., |
| 189 |
Dipl. Deutsch (Marburg), A. L. C. M.} to J. J. {Thomson, |
| 190 |
M.A., F.R.S.}, Frederick {Soddy, B.A. (Oxon.)}, and John A. |
| 191 |
{Cable, M.A., M.Ed., Dipl.Deutsch (Marburg), A.L.C.M.}, |
| 192 |
respectively. |
| 193 |
|
| 194 |
In journals in the humanities and history of science, as well |
| 195 |
as in some scientific journals until well into the 20th |
| 196 |
Century, academic, honorary, and professional titles and |
| 197 |
degrees are commonly attached to personal names. Even though |
| 198 |
modern publishing practice avoids such decorations, for |
| 199 |
accuracy, bibliography entries should preferably retain them. |
| 200 |
Journal typographical practice generally follows the |
| 201 |
reductions described here. |
| 202 |
|
| 203 |
-[no-]fix-font-changes |
| 204 |
With the positive form, supply an additional brace level |
| 205 |
around font changes in titles to protect against downcasing |
| 206 |
by some BibTeX styles. Font changes that already have more |
| 207 |
than one level of braces are not modified. |
| 208 |
|
| 209 |
For example, if a title contains the Latin phrase {\em |
| 210 |
Dictyostelium discoideum} or {\em {D}ictyostelium |
| 211 |
discoideum}, then downcasing incorrectly converts the phrase |
| 212 |
to lower-case letters. Most BibTeX users are surprised that |
| 213 |
bracing the initial letters does not prevent the downcase |
| 214 |
action. The correct coding is {{\em Dictyostelium |
| 215 |
discoideum}}. However, there are also legitimate cases where |
| 216 |
an extra level of bracing wrongly protects from downcasing. |
| 217 |
Consequently, bibclean normally does not supply an extra |
| 218 |
level of braces, but if you have a bibliography where the |
| 219 |
extra braces are routinely missing, you can use this option |
| 220 |
to supply them. |
| 221 |
|
| 222 |
If you think that you need this option, it is strongly |
| 223 |
recommended that you apply bibclean to your bibliography file |
| 224 |
with and without -fix-font-changes, then compare the two |
| 225 |
output files to ensure that extra braces are not being |
| 226 |
supplied in titles where they should not be present. You |
| 227 |
must decide which of the two output files is the better |
| 228 |
choice, then repair the incorrect title bracing by hand. |
| 229 |
|
| 230 |
Because font changes in titles are uncommon, except for cases |
| 231 |
of the type that this option is designed to correct, it |
| 232 |
should do more good than harm. Default: no. |
| 233 |
|
| 234 |
-[no-]fix-initials |
| 235 |
With the positive form, insert a space after a period |
| 236 |
following author initials. Default: yes. |
| 237 |
|
| 238 |
-[no-]fix-math |
| 239 |
With the positive form, improve readability of math mode in |
| 240 |
titles by inserting spaces around operators, deleting other |
| 241 |
unnecessary space, and removing braces around single- |
| 242 |
character subscripts and superscripts. Default: no. |
| 243 |
|
| 244 |
-[no-]fix-names |
| 245 |
With the positive form, reorder author and editor name lists |
| 246 |
to remove commas at brace level zero, placing first names or |
| 247 |
initials before last names. Default: yes. |
| 248 |
|
| 249 |
-[no-]German-style |
| 250 |
With the positive form, interpret quote characters ["] inside |
| 251 |
braced value strings at brace level 1 according to the |
| 252 |
conventions of the TeX style file german.sty, which overloads |
| 253 |
quote to simplify input and representation of German umlaut |
| 254 |
accents, sharp-s (es-zet), ligature separators, invisible |
| 255 |
hyphens, raised/lowered quotes, French guillemets, and |
| 256 |
discretionary hyphens. Recognized character combinations are |
| 257 |
braced to prevent BibTeX from interpreting the quote as a |
| 258 |
string delimiter. |
| 259 |
|
| 260 |
Quoted strings receive no special handling from this option, |
| 261 |
and because German nouns in titles must anyway be protected |
| 262 |
from the downcasing operation of most BibTeX bibliography |
| 263 |
styles, German value strings that use the overloaded quote |
| 264 |
character can always be entered in the form "{...}", without |
| 265 |
the need to specify this option at all. |
| 266 |
|
| 267 |
Default: no. |
| 268 |
|
| 269 |
-[no-]keep-linebreaks |
| 270 |
Normally, line breaks inside value strings are collapsed into |
| 271 |
a single space, so that long value strings can later be |
| 272 |
broken to provide lines of reasonable length. |
| 273 |
|
| 274 |
With the positive form, linebreaks are preserved in value |
| 275 |
strings. If -max-width is set to zero, this preserves the |
| 276 |
original line breaks. Spacing outside value strings remains |
| 277 |
under bibclean's control, and is not affected by this option. |
| 278 |
|
| 279 |
Default: no. |
| 280 |
|
| 281 |
-[no-]keep-parbreaks |
| 282 |
With the positive form, preserve paragraph breaks (either |
| 283 |
formfeeds, or lines containing only spaces) in value strings. |
| 284 |
Normally, paragraph breaks are collapsed into a single space. |
| 285 |
Spacing outside value strings remains under bibclean's |
| 286 |
control, and is not affected by this option. Default: no. |
| 287 |
|
| 288 |
-[no-]keep-preamble-spaces |
| 289 |
With the positive form, preserve all whitespace in |
| 290 |
@Preamble{...} entries. Default: no. |
| 291 |
|
| 292 |
-[no-]keep-spaces |
| 293 |
With the positive form, preserve all spaces in value strings. |
| 294 |
Normally, multiple spaces are collapsed into a single space. |
| 295 |
This option can be used together with -keep-linebreaks, |
| 296 |
-keep-parbreaks, and -max-width 0 to preserve the form of |
| 297 |
value strings while still providing syntax and value |
| 298 |
checking. Spacing outside value strings remains under |
| 299 |
bibclean's control, and is not affected by this option. |
| 300 |
Default: no. |
| 301 |
|
| 302 |
-[no-]keep-string-spaces |
| 303 |
With the positive form, preserve all whitespace in |
| 304 |
@String{...} entries. Default: no. |
| 305 |
|
| 306 |
-[no-]parbreaks |
| 307 |
With the negative form, a paragraph break (either a formfeed, |
| 308 |
or a line containing only spaces) is not permitted in value |
| 309 |
strings, or between field/value pairs. That may be useful to |
| 310 |
quickly trap runaway strings arising from mismatched |
| 311 |
delimiters. Default: yes. |
| 312 |
|
| 313 |
-[no-]prettyprint |
| 314 |
Normally, bibclean functions as a prettyprinter. However, |
| 315 |
with the negative form of this option, it acts as a lexical |
| 316 |
analyzer instead, producing a stream of lexical tokens. See |
| 317 |
the LEXICAL ANALYSIS manual section for further details. |
| 318 |
Default: yes. |
| 319 |
|
| 320 |
-[no-]print-ISBN-table |
| 321 |
With the positive form, print the ISBN-range table on stderr, |
| 322 |
then terminate with a success return code. |
| 323 |
|
| 324 |
That action is taken after all command-line options are |
| 325 |
processed, and before any input files are read (other than |
| 326 |
those that are values of command-line options). |
| 327 |
|
| 328 |
The format of the output ISBN-range table is acceptable for |
| 329 |
input as an ISBN initialization file (see the ISBN |
| 330 |
INITIALIZATION FILES manual section). Default: no. |
| 331 |
|
| 332 |
-[no-]print-keyword-table |
| 333 |
With the positive form, print the keyword initialization |
| 334 |
table on stderr, then terminate with a success return code. |
| 335 |
|
| 336 |
That action is taken after all command-line options are |
| 337 |
processed, and before any input files are read (other than |
| 338 |
those that are values of command-line options). |
| 339 |
|
| 340 |
The format of the output table is acceptable for input as a |
| 341 |
keyword initialization file (see the KEYWORD INITIALIZATION |
| 342 |
FILES manual section). Default: no. |
| 343 |
|
| 344 |
-[no-]print-patterns |
| 345 |
With the positive form, print the value patterns read from |
| 346 |
initialization files as they are added to internal tables. |
| 347 |
Use this option to check newly-added patterns, or to see what |
| 348 |
patterns are being used. |
| 349 |
|
| 350 |
When bibclean is compiled with native pattern-matching code |
| 351 |
(the default), those patterns are the ones that are used in |
| 352 |
checking value strings for valid syntax, and all of them are |
| 353 |
specified in initialization files, rather than hard-coded |
| 354 |
into the program. For further details, see the |
| 355 |
INITIALIZATION FILES manual section. Default: no. |
| 356 |
|
| 357 |
-[no-]quiet |
| 358 |
This option is the opposite of -[no-]warning; it exists for |
| 359 |
user convenience, and for compatibility with other programs |
| 360 |
that use -q for quiet operation, without warning messages. |
| 361 |
|
| 362 |
-[no-]read-init-files |
| 363 |
With the negative form, suppress loading of system-, user-, |
| 364 |
and file-specific initialization files. Initializations then |
| 365 |
come only from those files explicitly given by -init-file |
| 366 |
filename options. Default: yes. |
| 367 |
|
| 368 |
-[no-]remove-OPT-prefixes |
| 369 |
With the positive form, remove the ``OPT'' prefix from each |
| 370 |
field name where the corresponding value is not an empty |
| 371 |
string. The prefix ``OPT'' must be entirely in upper-case to |
| 372 |
be recognized. |
| 373 |
|
| 374 |
This option is for bibliographies generated with the help of |
| 375 |
the GNU Emacs BibTeX editing support, which generates |
| 376 |
templates with optional fields identified by the ``OPT'' |
| 377 |
prefix. Although the function M-x bibtex-remove-OPT normally |
| 378 |
bound to the keystrokes C-c C-o does the job, users often |
| 379 |
forget, with the result that BibTeX does not recognize the |
| 380 |
field name, and ignores the value string. Compare this |
| 381 |
option with -[no-]delete-empty-values described above. |
| 382 |
Default: no. |
| 383 |
|
| 384 |
-[no-]scribe |
| 385 |
With the positive form, accept input syntax conforming to the |
| 386 |
Scribe document system. The output is converted to conform |
| 387 |
to BibTeX syntax. See the SCRIBE BIBLIOGRAPHY FORMAT manual |
| 388 |
section for further details. Default: no. |
| 389 |
|
| 390 |
-[no-]trace-file-opening |
| 391 |
With the positive form, record in the error log file the |
| 392 |
names of all files that bibclean attempts to open. Use this |
| 393 |
option to identify where initialization files are located. |
| 394 |
Default: no. |
| 395 |
|
| 396 |
-[no-]warnings |
| 397 |
With the positive form, allow all warning messages. The |
| 398 |
negative form is not recommended because it may mask problems |
| 399 |
that should be repaired. Default: yes. |
| 400 |
|
| 401 |
-output-file filename |
| 402 |
Supply an alternate output file to replace stdout. If the |
| 403 |
filename cannot be opened for output, execution terminates |
| 404 |
immediately with a nonzero exit code. |
| 405 |
|
| 406 |
-version Display the program version number on stderr, and then |
| 407 |
terminate with a success return code. That includes an |
| 408 |
indication of who compiled the program, the host name on |
| 409 |
which it was compiled, the time of compilation, and the type |
| 410 |
of string-value matching code selected, when that information |
| 411 |
is available to the compiler. |
| 412 |
|