


BIBCLEAN(1)               User Commands               BIBCLEAN(1)



NAME
     bibclean - prettyprint and syntax check  BibTeX  and  Scribe
     bibliography data base files

SYNOPSIS
     bibclean [ -author ] [ -error-log filename ] [ -help ]
              [ '-?' ] [ -init-file filename ] [ -max-width nnn ]
              [ -[no-]align-equals ] [ -[no-]check-values ]
              [ -[no-]delete-empty-values ]
              [ -[no-]file-position ] [ -[no-]fix-font-changes ]
              [ -[no-]fix-initials ] [ -[no-]fix-names ]
              [ -[no-]German-style ] [ -[no-]keep-linebreaks ]
              [ -[no-]keep-parbreaks ]
              [ -[no-]keep-preamble-spaces ]
              [ -[no-]keep-spaces ] [ -[no-]keep-string-spaces ]
              [ -[no-]parbreaks ] [ -[no-]prettyprint ]
              [ -[no-]print-patterns ] [ -[no-]read-init-files ]
              [ -[no-]remove-OPT-prefixes ] [ -[no-]scribe ]
              [ -[no-]trace-file-opening ] [ -[no-]warnings ]
              [ -version ]
              <infile or  bibfile1 bibfile2 bibfile3 ...
              >outfile

     All options can be abbreviated to a unique leading prefix.

     An explicit file name of ``-'' represents standard input; it
     is assumed if no input files are specified.

     On VAX VMS and IBM PC DOS, the leading ``-'' on option names
     may be replaced by a slash, ``/''; however, the ``-'' option
     prefix is always recognized.

DESCRIPTION
     bibclean prettyprints input  BibTeX  files  to  stdout,  and
     checks  the  brace  balance and bibliography entry syntax as
     well.  It can be used to detect  problems  in  BibTeX  files
     that  sometimes confuse even BibTeX itself, and importantly,
     can be used to normalize the appearance  of  collections  of
     BibTeX files.

     Here is a summary of the formatting actions:

     o   BibTeX items are formatted into a  consistent  structure
        with one field = "value" pair per line, and the initial @
        and trailing right brace in column 1.

     o   Tabs are expanded  into  blank  strings;  their  use  is
        discouraged  because  they  inhibit  portability, and can
        suffer corruption in electronic mail.

     o   Long string values are split at a  blank  and  continued
        onto the next line with leading indentation.



Version 2.11.3      Last change: 01 May 1996                    1






BIBCLEAN(1)               User Commands               BIBCLEAN(1)



     o   A single  blank  line  separates  adjacent  bibliography
        entries.

     o   Text outside BibTeX entries is passed through verbatim.

      o   Outer  parentheses  around  entries  are  converted  to
        braces.

     o   Personal names in author and  editor  field  values  are
        normalized  to the form ``P. D. Q.  Bach'', from ``P.D.Q.
        Bach'' and ``Bach, P.D.Q.''.

     o   Hyphen sequences in page numbers are  converted  to  en-
        dashes.

     o   Month values are converted  to  standard  BibTeX  string
        abbreviations.

     o   In titles, sequences of upper-case characters  at  brace
        level  zero  are  braced  to protect them from being con-
        verted to lower-case letters by some bibliography styles.

     o   CODEN, ISBN (International  Standard  Book  Number)  and
        ISSN  (International Standard Serial Number) entry values
        are examined to  verify  the  checksums  of  each  listed
        number,  and  correct  ISBN  hyphenation is automatically
        supplied.

     The standardized format of the output  of  bibclean  facili-
     tates  the  later  application  of  simple  filters, such as
     bibextract(1),    bibindex(1),    biblook(1),    bibsort(1),
     citefind(1),  and citetags(1), to process the text, and also
     is the one expected by the GNU Emacs  BibTeX  support  func-
     tions.

OPTIONS
     Command-line switches may be abbreviated to a unique leading
     prefix, and letter case is not significant.  All options are
     parsed before any input  bibliography  files  are  read,  no
     matter  what  their order on the command line.  Options that
     correspond to a yes/no setting of a flag have a form with  a
     prefix  "no-"  to set the flag to no.  For such options, the
     last setting determines the flag value used.  This is signi-
     ficant  when  options  are  also specified in initialization
     files (see the INITIALIZATION FILES manual section).

     -author                      Display an author credit on the
                                 standard   error  unit,  stderr.
                                 Sometimes an executable  program
                                 is separated from its documenta-
                                 tion  and  source   code;   this
                                 option provides a way to recover



Version 2.11.3      Last change: 01 May 1996                    2






BIBCLEAN(1)               User Commands               BIBCLEAN(1)



                                 from that.

     -error-log filename          Redirect stderr  to  the  indi-
                                 cated file, which will then con-
                                 tain all of the error and  warn-
                                 ing  messages.   This  option is
                                 provided for those systems  that
                                 have    difficulty   redirecting
                                 stderr.

     -help or - ?                   Display  a  help  message  on
                                 stderr,  giving a usage descrip-
                                 tion, similar to this section of
                                 the manual pages.

     -init-file filename          Provide an explicit value  pat-
                                 tern  initialization  file.   It
                                 will  be  processed  after   any
                                 system-wide  and  job-wide  ini-
                                 tialization files found  on  the
                                 PATH  (for  VAX VMS, SYS$SYSTEM)
                                 and  BIBINPUTS   search   paths,
                                 respectively,  and  may override
                                 them.  It in turn may  be  over-
                                 ridden  by  a  subsequent  file-
                                 specific  initialization   file.
                                 The initialization file name can
                                 be changed at compile  time,  or
                                 at run time through a setting of
                                 the  environment  variable  BIB-
                                 CLEANINI,  but defaults to .bib-
                                 cleanrc   on   UNIX,   and    to
                                 bibclean.ini   elsewhere.    For
                                 further details,  see  the  INI-
                                 TIALIZATION  FILES  manual  sec-
                                 tion.

     -max-width nnn               bibclean normally limits output
                                 line  widths  to  72 characters,
                                 and in  the  interests  of  con-
                                 sistency,  that value should not
                                 be    changed.     Occasionally,
                                 special-purpose applications may
                                 require different  maximum  line
                                 widths,  so this option provides
                                 that  capability.   The   number
                                 following the option name can be
                                 specified  in   decimal,   octal
                                 (starting  with  0),  or hexade-
                                 cimal  (starting  with  0x).   A
                                 zero or negative value is inter-
                                 preted to mean unlimited, so   -



Version 2.11.3      Last change: 01 May 1996                    3






BIBCLEAN(1)               User Commands               BIBCLEAN(1)



                                 max-width   0  can  be  used  to
                                 ensure  that  each   field/value
                                 pair appears on a single line.

                                 When  - no-prettyprint  requests
                                 bibclean  to  act  as  a lexical
                                 analyzer, the default line width
                                 is  unlimited, unless overridden
                                 by this option.

                                 When bibclean is prettyprinting,
                                 line  wrapping will be done only
                                 at a space. Consequently, a long
                                 non-blank character sequence may
                                 result in the  output  exceeding
                                 the requested line width.

                                 When bibclean  is  lexing,  line
                                 wrapping  is done by inserting a
                                 backslash-newline pair when  the
                                 specified maximum is reached, so
                                 no line length will ever  exceed
                                 the maximum.

     -[no-]align-equals           With the positive  form,  align
                                 the  equals  sign  in  key/value
                                 assignments at the same  column,
                                 separated by a single space from
                                 the  value  string.   Otherwise,
                                 the equals sign follows the key,
                                 separated  by  a  single  space.
                                 Default: no.

     -[no-]check-values           With the positive  form,  apply
                                 heuristic  pattern  matching  to
                                 field values in order to  detect
                                 possible  errors  (e.g. ``year =
                                 "192"''  instead  of  ``year   =
                                 "1992"''),  and  issue  warnings
                                 when  unexpected  patterns   are
                                 found.

                                 This checking is usually benefi-
                                 cial,  but  if  it  produces too
                                 many bogus warnings for  a  par-
                                 ticular  bibliography  file, you
                                 can disable it with the negative
                                 form  of  this option.  Default:
                                 yes.

     -[no-]delete-empty-values    With the positive form,  remove
                                 all  field/value pairs for which



Version 2.11.3      Last change: 01 May 1996                    4






BIBCLEAN(1)               User Commands               BIBCLEAN(1)



                                 the value is  an  empty  string.
                                 This  is  helpful in cleaning up
                                 bibliographies  generated   from
                                 text  editor  templates. Compare
                                 this option with  - [no-]remove-
                                 OPT-prefixes   described  below.
                                 Default: no.

     -[no-]file-position          With the  positive  form,  give
                                 detailed  file position informa-
                                 tion in warning and  error  mes-
                                 sages.  Default: no.

     -[no-]fix-font-changes       With the positive form,  supply
                                 an additional brace level around
                                 font changes in titles  to  pro-
                                 tect  against downcasing by some
                                 BibTeX  styles.   Font   changes
                                 that  already have more than one
                                 level of braces  are  not  modi-
                                 fied.

                                 For example, if a title contains
                                 the  Latin  phrase {\em Dictyos-
                                 telium   Discoideum}   or   {\em
                                 {D}ictyostelium   {D}iscoideum},
                                 then downcasing will incorrectly
                                 convert the phrase to lower-case
                                 letters.  Most BibTeX users  are
                                 surprised  that bracing the ini-
                                 tial letters  does  not  prevent
                                 the    downcase   action.    The
                                 correct coding is {{\em Dictyos-
                                 telium  Discoideum}}.   However,
                                 there are also legitimate  cases
                                 where  an extra level of bracing
                                 wrongly protects  from  downcas-
                                 ing.    Consequently,   bibclean
                                 will  normally  not  supply   an
                                 extra  level  of  braces, but if
                                 you have  a  bibliography  where
                                 the  extra  braces are routinely
                                 missing, you can use this option
                                 to supply them.

                                 If you think that you need  this
                                 option,  it  is  strongly recom-
                                 mended that you  apply  bibclean
                                 to  your  bibliography file with
                                 and without  - fix-font-changes,
                                 then   compare  the  two  output
                                 files  to  ensure   that   extra



Version 2.11.3      Last change: 01 May 1996                    5






BIBCLEAN(1)               User Commands               BIBCLEAN(1)



                                 braces are not being supplied in
                                 titles where they should not  be
                                 present.    You   will  have  to
                                 decide which of the  two  output
                                 files is the better choice, then
                                 repair the incorrect title brac-
                                 ing by hand.

                                 Since font changes in titles are
                                 uncommon,  except  for  cases of
                                 the type which  this  option  is
                                 designed  to  correct, it should
                                 do   more   good   than    harm.
                                 Default: no.

     -[no-]fix-initials           With the positive form,  insert
                                 a space after a period following
                                 author initials.  Default: yes.

     -[no-]fix-names              With the positive form, reorder
                                 author  and editor name lists to
                                 remove  commas  at  brace  level
                                 zero,  placing  first  names  or
                                 initials  before   last   names.
                                 Default: yes.

     -[no-]German-style           With the positive form,  inter-
                                 pret quote characters ["] inside
                                 braced value  strings  at  brace
                                 level 1 according to the conven-
                                 tions  of  the  TeX  style  file
                                 german.sty,    which   overloads
                                 quote  to  simplify  input   and
                                 representation  of German umlaut
                                 accents, sharp-s (es-zet), liga-
                                 ture    separators,    invisible
                                 hyphens, raised/lowered  quotes,
                                 French  guillemets,  and discre-
                                 tionary   hyphens.    Recognized
                                 character  combinations  will be
                                 braced to  prevent  BibTeX  from
                                 interpreting   the  quote  as  a
                                 string delimiter.

                                 Quoted strings receive  no  spe-
                                 cial  handling from this option,
                                 and since German nouns in titles
                                 must  anyway  be  protected from
                                 the downcasing operation of most
                                 BibTeX bibliography styles, Ger-
                                 man value strings that  use  the
                                 overloaded  quote  character can



Version 2.11.3      Last change: 01 May 1996                    6






BIBCLEAN(1)               User Commands               BIBCLEAN(1)



                                 always be entered  in  the  form
                                 "{...}",  without  the  need  to
                                 specify this option at all.

                                 Default: no.

     -[no-]keep-linebreaks        Normally,  line  breaks  inside
                                 value strings are collapsed into
                                 a single  space,  so  that  long
                                 value  strings can later be bro-
                                 ken to provide lines of  reason-
                                 able length.

                                 With the  positive  form,  line-
                                 breaks  are  preserved  in value
                                 strings.  If -max-width  is  set
                                 to zero, this preserves the ori-
                                 ginal line breaks.  Spacing out-
                                 side value strings remains under
                                 bibclean's control, and  is  not
                                 affected by this option.

                                 Default: no.

      - [no-]keep-parbreaks         With   the   positive   form,
                                 preserve     paragraph    breaks
                                 (either formfeeds, or lines con-
                                 taining  only  spaces)  in value
                                 strings.   Normally,   paragraph
                                 breaks are collapsed into a sin-
                                 gle  space.    Spacing   outside
                                 value   strings   remains  under
                                 bibclean's control, and  is  not
                                 affected    by    this   option.
                                 Default: no.

      - [no-]keep-preamble-spaces   With   the   positive   form,
                                 preserve   all   whitespace   in
                                 @Preamble{...}          entries.
                                 Default: no.

      - [no-]keep-spaces            With   the   positive   form,
                                 preserve  all  spaces  in  value
                                 strings.    Normally,   multiple
                                 spaces are collapsed into a sin-
                                 gle space.  This option  can  be
                                 used   together   with   - keep-
                                 linebreaks, -keep-parbreaks, and
                                  - max-width  0  to preserve the
                                 form  of  value  strings   while
                                 still providing syntax and value
                                 checking.  Spacing outside value



Version 2.11.3      Last change: 01 May 1996                    7






BIBCLEAN(1)               User Commands               BIBCLEAN(1)



                                 strings remains under bibclean's
                                 control, and is not affected  by
                                 this option.  Default: no.

      - [no-]keep-string-spaces     With   the   positive   form,
                                 preserve   all   whitespace   in
                                 @String{...} entries.   Default:
                                 no.

     -[no-]parbreaks              With the negative form, a para-
                                 graph  break (either a formfeed,
                                 or  a   line   containing   only
                                 spaces)   is  not  permitted  in
                                 value   strings,   or    between
                                 field/value  pairs.  This may be
                                 useful to quickly  trap  runaway
                                 strings  arising from mismatched
                                 delimiters.  Default: yes.

     -[no-]prettyprint            Normally, bibclean functions as
                                 a  prettyprinter.  However, with
                                 the  negative   form   of   this
                                 option,  it  acts  as  a lexical
                                 analyzer  instead,  producing  a
                                 stream  of  lexical tokens.  See
                                 the LEXICAL ANALYSIS manual sec-
                                 tion    for   further   details.
                                 Default: yes.

     -[no-]print-patterns         With the positive  form,  print
                                 the  value  patterns  read  from
                                 initialization files as they are
                                 added  to  internal tables.  Use
                                 this option to check newly-added
                                 patterns,  or  to  see what pat-
                                 terns are being used.

                                 When bibclean is  compiled  with
                                 native   pattern-matching   code
                                 (the  default),  these  patterns
                                 are  the  ones that will be used
                                 in checking  value  strings  for
                                 valid  syntax,  and  all of them
                                 are specified in  initialization
                                 files,  rather  than  hard-coded
                                 into the program.   For  further
                                 details,  see the INITIALIZATION
                                 FILES manual section.   Default:
                                 no.

      - [no-]read-init-files        With   the   negative   form,
                                 suppress   loading  of  system-,



Version 2.11.3      Last change: 01 May 1996                    8






BIBCLEAN(1)               User Commands               BIBCLEAN(1)



                                 user-,  and  file-specific  ini-
                                 tialization  files.  Initializa-
                                 tions will come only from  those
                                 files  explicitly  given  by   -
                                 init-file   filename    options.
                                 Default: yes.

     -[no-]remove-OPT-prefixes    With the positive form,  remove
                                 the  ``OPT''  prefix  from  each
                                 field name where the correspond-
                                 ing   value   is  not  an  empty
                                 string.  The prefix ``OPT'' must
                                 be  entirely in upper-case to be
                                 recognized.

                                 This option  is  for  bibliogra-
                                 phies generated with the help of
                                 the  GNU  Emacs  BibTeX  editing
                                 support,  which  generates  tem-
                                 plates  with   optional   fields
                                 identified  by  the ``OPT'' pre-
                                 fix.  Although the function  M-x
                                 bibtex-remove-OPT normally bound
                                 to the keystrokes C-c  C-o  does
                                 the  job,  users  often  forget,
                                 with the result that BibTeX does
                                 not  recognize  the  field name,
                                 and ignores  the  value  string.
                                 Compare  this  option with -[no-
                                 ]delete-empty-values   described
                                 above.  Default: no.

     -[no-]scribe                 With the positive form,  accept
                                 input  syntax  conforming to the
                                 Scribe  document  system.    The
                                 output will be converted to con-
                                 form to BibTeX syntax.  See  the
                                 SCRIBE    BIBLIOGRAPHY    FORMAT
                                 manual   section   for   further
                                 details.  Default: no.

     -[no-]trace-file-opening     With the positive form,  record
                                 in  the error log file the names
                                 of  all  files  which   bibclean
                                 attempts   to  open.   Use  this
                                 option to  identify  where  ini-
                                 tialization  files  are located.
                                 Default: no.

     -[no-]warnings               With the positive  form,  allow
                                 all warning messages.  The nega-
                                 tive  form  is  not  recommended



Version 2.11.3      Last change: 01 May 1996                    9






BIBCLEAN(1)               User Commands               BIBCLEAN(1)



                                 since  it may mask problems that
                                 should  be  repaired.   Default:
                                 yes.

     - version                     Display  the  program  version
                                 number  on  stderr.   This  will
                                 also include  an  indication  of
                                 who  compiled  the  program, the
                                 host name on which it  was  com-
                                 piled,  the time of compilation,
                                 and  the  type  of  string-value
                                 matching   code  selected,  when
                                 that information is available to
                                 the compiler.

ERROR RECOVERY AND WARNINGS
     When bibclean detects an error, it issues an  error  message
     to  both  stderr  and stdout.  That way, the user is clearly
     notified, and the output bibliography also contains the mes-
     sage at the point of error.

     Error messages begin with a distinctive pair of queries, ??,
     beginning  in  column 1, followed by the input file name and
     line number.  If the -file-position  option  was  specified,
     they  also  contain  the  input  and output positions of the
     current file, entry, and value.  Each position includes  the
     file  byte  number,  the line number, and the column number.
     In the event of a runaway string  argument,  the  entry  and
     value  positions  should  precisely  pinpoint  the erroneous
     bibliography entry, and the  file  positions  will  indicate
     where  it  was  detected,  which  may be rather later in the
     files.

     Warning messages identify possible problems, and are  there-
     fore  sent  only to stderr, and not to stdout, so they never
     appear in the output file.  They are identified  by  a  dis-
     tinctive pair of percents, %%, beginning in column 1, and as
     with error messages, may be followed by file  position  mes-
     sages if the -file-position option was specified.

     For convenience, the first line of each  error  and  warning
     message  sent to stderr is formatted according to the expec-
     tations of the GNU Emacs next-error command.  You can invoke
     bibclean    with    the   Emacs   M-x   compile<RET>bibclean
     filename.bib >filename.new command, then use the  next-error
     command,  normally  bound to C-x ` (that's a grave, or back,
     accent), to move to the location of the error in  the  input
     file.

     If error messages  are  ignored,  and  left  in  the  output
     bibliography  file,  they will precipitate an error when the
     bibliography is next processed with BibTeX.



Version 2.11.3      Last change: 01 May 1996                   10






BIBCLEAN(1)               User Commands               BIBCLEAN(1)



     After issuing an error message, bibclean then resynchronizes
     its  input  by  copying  it  verbatim  to stdout until a new
     bibliography entry is recognized on  a  line  in  which  the
     first  non-blank  character is an at-sign (@).  This ensures
     that nothing  is  lost  from  the  input  file(s),  allowing
     corrections  to  be  made  in either the input or the output
     files.  However, if bibclean detects an  internal  error  in
     its  data  structures,  it  will  terminate abruptly without
     further input or  output  processing;  this  kind  of  error
     should  never  happen, and if it does, it should be reported
     immediately to the author of the program.   Errors  in  ini-
     tialization  files,  and running out of dynamic memory, will
     also immediately terminate bibclean.

INITIALIZATION FILES
     bibclean can be compiled with one of three  different  types
     of  pattern matching; the choice is made by the installer at
     compile time:

          o   The original version uses explicit hand-coded tests
             of value-string syntax.

           o   The   second   version   uses   regular-expression
             pattern-matching host library routines together with
             regular-expression patterns that come entirely  from
             initialization files.

          o   The third version uses special patterns  that  come
             entirely from initialization files.

     The second and third versions are the ones of most  interest
     here, because they allow the user to control what values are
     considered acceptable.  However,  command-line  options  can
     also  be  specified in initialization files, no matter which
     pattern matching choice was selected.

     When bibclean starts, it searches for initialization  files,
     finding  the  first  one  in  the  system executable program
     search path (on UNIX and IBM PC DOS, PATH) and the first one
     in  the  BIBINPUTS  search path, and processes them in turn.
     Then, when command-line arguments are processed,  any  addi-
     tional  files  specified  by  -init-filefilename options are
     also processed.   Finally,  immediately  before  each  named
     bibliography  file  is processed, an attempt is made to pro-
     cess an initialization file with the same name, but with the
     extension  changed  to  .ini.   The default extension can be
     changed by  a  setting  of  the  environment  variable  BIB-
     CLEANEXT.    This  scheme  permits  system-wide,  user-wide,
     session-wide, and file-specific initialization files  to  be
     supported.





Version 2.11.3      Last change: 01 May 1996                   11






BIBCLEAN(1)               User Commands               BIBCLEAN(1)



     When input is taken from stdin, there  is  no  file-specific
     initialization.

     For  precise  control,  the   -  no-read-init-files   option
     suppresses  all initialization files except those explicitly
     named by -init-filefilename options, either on  the  command
     line, or in requested initialization files.

     Recursive execution of initialization files with  nested   -
     init-file  options  is permitted; if the recursion is circu-
     lar, bibclean will finally get  a  non-fatal  initialization
     file  open  failure after opening too many files.  This ter-
     minates further  initialization  file  processing.   As  the
     recursion  unwinds, the files are all closed, then execution
     proceeds normally.

     An initialization file may  contain  empty  lines,  comments
     from  percent  to  end  of  line  (just  like  TeX),  option
     switches, and field/pattern or field/pattern/message assign-
     ments.   Leading  and  trailing spaces are ignored.  This is
     best illustrated by a short example:

     % This is a small bibclean initialization file

     -init-file /u/math/bib/.bibcleanrc %% departmental patterns

     chapter = "\"D\""                 %% 23

     pages   = "\"D--D\""              %% 23--27

     volume  = "\"D \\an\\d D\""       %% 11 and 12

     year    = \
        "\"dddd, dddd, dddd\"" \
        "Multiple years specified."      %% 1989, 1990, 1991

     -no-fix-names   %% do not modify author/editor lists

     Long logical lines can be split into multiple physical lines
     by  breaking  at  a  backslash-newline  pair; the backslash-
     newline pair is discarded.  This  processing  happens  while
     characters are being read, before any further interpretation
     of the input stream.

     Each logical line must contain a complete  option  (and  its
     value,  if  any),  or  a  complete  field/pattern pair, or a
     field/pattern/message triple.

     Comments are stripped during the parsing of the field,  pat-
     tern,  and  message values.  The comment start symbol is not
     recognized inside quoted strings, so it can be  freely  used
     in such strings.



Version 2.11.3      Last change: 01 May 1996                   12






BIBCLEAN(1)               User Commands               BIBCLEAN(1)



     Comments on logical lines that were input as multiple physi-
     cal  lines  via the backslash-newline convention must appear
     on the last physical line; otherwise, the remaining physical
     lines will become part of the comment.

     Pattern strings must be enclosed in quotation marks;  within
     such strings, a backslash starts an escape mechanism that is
     commonly used  in  UNIX  software.   The  recognized  escape
     sequences are:

          \a   alarm bell (octal 007)

          \b   backspace (octal 010)

          \f   formfeed (octal 014)

          \n   newline (octal 012)

          \r   carriage return (octal 015)

          \t   horizontal tab (octal 011)

          \v   vertical tab (octal 013)

          \ooo character number octal ooo (e.g \012 is linefeed).
               Up to 3 octal digits may be used.

          \0xhh
               character number hexadecimal hh  (e.g.   \0x0a  is
               linefeed).  xhh may be in either letter case.  Any
               number of hexadecimal digits may be used.

     Backslash followed by any other character produces just that
     character.   Thus,  \%  gets a literal percent into a string
     (preventing its interpretation as a comment), \" produces  a
     quotation mark, and \\ produces a single backslash.

     An ASCII NUL (\0) in a string will terminate it; this  is  a
     feature  of  the C programming language in which bibclean is
     implemented.

     Field/pattern pairs can be separated by arbitrary space, and
     optionally, either an equals sign or colon functioning as an
     assignment operator.  Thus, the following are equivalent:

     pages="\"D--D\""
     pages:"\"D--D\""
     pages "\"D--D\""
       pages = "\"D--D\""
       pages : "\"D--D\""
     pages   "\"D--D\""




Version 2.11.3      Last change: 01 May 1996                   13






BIBCLEAN(1)               User Commands               BIBCLEAN(1)



     Each field name can have an  arbitrary  number  of  patterns
     associated  with  it;  however,  they  must  be specified in
     separate field/pattern assignments.

     An empty pattern string  causes  previously-loaded  patterns
     for  that  field name to be forgotten.  This feature permits
     an initialization file to completely discard  patterns  from
     earlier initialization files.

     Patterns  for  value  strings  are  represented  in  a  tiny
     special-purpose  language  that is both convenient and suit-
     able for bibliography value-string syntax  checking.   While
     not  as  powerful as the language of regular-expression pat-
     terns, its parsing can be portably implemented in less  than
     3%  of  the  code in a widely-used regular-expression parser
     (the GNU regexp package).

     The patterns are represented by the following special  char-
     acters:

          <space>  one or more spaces

          a        exactly one letter

          A        one or more letters

          d        exactly one digit

          D        one or more digits

          r        exactly one Roman numeral

          R        one or  more  Roman  numerals  (i.e.  a  Roman
                   number)

          w        exactly one word  (one  or  more  letters  and
                   digits)

          W        one or more space-separated  words,  beginning
                   and ending with a word

          .        one `special' character, one of the characters
                   <space>!#()*+,-./:;?[]~,  a subset of punctua-
                   tion characters that  are  typically  used  in
                   string values

          :        one or more `special' characters

          X        one or more `special'-separated words,  begin-
                   ning and ending with a word

          \x       exactly one x (x is any  character),  possibly



Version 2.11.3      Last change: 01 May 1996                   14






BIBCLEAN(1)               User Commands               BIBCLEAN(1)



                   with  an  escape sequence interpretation given
                   earlier

          x        exactly the character x (x is anything but one
                   of       these       pattern       characters:
                   aAdDrRwW.:<space>\)

     The X pattern character  is  very  powerful,  but  generally
     inadvisable,  since  it will match almost anything likely to
     be found in a BibTeX value string.  The reason for providing
     pattern matching on the value strings is to uncover possible
     errors, not mask them.

     There is no provision for specifying ranges  or  repetitions
     of  characters,  but  this can usually be done with separate
     patterns.  It is a good idea to accompany the pattern with a
     comment  showing  the kind of thing it is expected to match.
     Here is a portion of an initialization file giving a few  of
     the patterns used to match number value strings:

     number  =       "\"D\""         %% 23
     number  =       "\"A AD\""      %% PN LPS5001
     number  =       "\"A D(D)\""    %% RJ 34(49)
     number  =       "\"A D\""       %% XNSS 288811
     number  =       "\"A D\\.D\""   %% Version 3.20
     number  =       "\"A-A-D-D\""   %% UMIAC-TR-89-11
     number  =       "\"A-A-D\""     %% CS-TR-2189
     number  =       "\"A-A-D\\.D\"" %% CS-TR-21.7

     For a bibliography that contains only article entries,  this
     list  should  probably be reduced to just the first pattern,
     so that  anything  other  than  a  digit  string  fails  the
     pattern-match   test.    This  is  easily  done  by  keeping
     bibliography-specific patterns in a corresponding file  with
     extension .ini, since that file is read automatically.

     You should be sure to use empty pattern strings in this pat-
     tern  file  to  discard patterns from earlier initialization
     files.

     The value strings passed to the pattern matcher contain sur-
     rounding  quotes, so the patterns should also.  However, you
     could use a pattern specification like  "\"D"  to  match  an
     initial digit string followed by anything else; the omission
     of the final quotation mark \" in  the  pattern  allows  the
     match to succeed without checking that the next character in
     the value string is a quotation mark.

     Because the value strings are intended to  be  processed  by
     TeX,  the  pattern  matching ignores braces, and TeX control
     sequences, together with any space following  those  control
     sequences.    Spaces  around  braces  are  preserved.   This



Version 2.11.3      Last change: 01 May 1996                   15






BIBCLEAN(1)               User Commands               BIBCLEAN(1)



     convention allows the pattern fragment A-AD-D to  match  the
     value  string  TN-K\slash 27-70, because the value is impli-
     citly collapsed to TN-K27-70 during the matching operation.

     bibclean's normal action when a string value fails to  match
     any of the corresponding patterns is to issue a warning mes-
     sage something like this:  "Unexpected  value  in  ``year  =
     "192"''.   In  most  cases,  that is sufficient to alert the
     user to a problem.  In some cases, however, it may be desir-
     able to associate a different message with a particular pat-
     tern.  This can be done by supplying a message  string  fol-
     lowing  the  pattern  string.   Format items %% (single per-
     cent), %e (entry name), %f (field name), %k (citation  key),
     and  %v  (string  value) are available to get current values
     expanded in the messages.  Here is an example:

     chapter = "\"D:D\"" "Colon found in ``%f = %v''" %% 23:2

     To be consistent with other messages output by bibclean, the
     message string should not end with punctuation.

     If you wish to make the message an error, rather than just a
     warning, begin it with a query (?), like this:

     chapter = "\"D:D\"" "?Colon found in ``%f = %v''" %% 23:2

     The query will not be included in the output message.

     Escape sequences are supported in message strings,  just  as
     they  are in pattern strings.  You can use this to advantage
     for fancy things, such as terminal display mode control.  If
     you rewrite the previous example as

     chapter = "\"D:D\"" \
               "?\033[7mColon found in ``%f = %v''\033[0m" %% 23:2

     the error message will appear in inverse  video  on  display
     screens  that support ANSI terminal control sequences.  Such
     practice is not normally  recommended,  since  it  may  have
     undesirable  effects  on some output devices.  Nevertheless,
     you may find it useful for restricted applications.

     For some types of  bibliography  fields,  bibclean  contains
     special-purpose  code  to  supplement or replace the pattern
     matching:

          o   CODEN, ISBN and ISSN field values are handled  this
             way  because their validation requires evaluation of
             checksums that cannot be expressed  by  simple  pat-
             terns;  no  patterns  are  even  used in these three
             cases.




Version 2.11.3      Last change: 01 May 1996                   16






BIBCLEAN(1)               User Commands               BIBCLEAN(1)



          o   When bibclean  is  compiled  with  pattern-matching
             code  support,  chapter,  number,  pages, and volume
             values are checked only by pattern matching.

          o   month values are first checked against the standard
             BibTeX  month abbreviations, and only if no match is
             found are patterns then used.

          o   year values are  first  checked  against  patterns,
             then  if  no  match  is  found, the year numbers are
             found and converted to integer  values  for  testing
             against reasonable bounds.

     Values for other fields are checked only  against  patterns.
     You  can  provide patterns for any field you like, even ones
     bibclean does not already know about.  New ones  are  simply
     added  to an internal table that is searched for each string
     to be validated.

     The special field, key, represents the  bibliographic  cita-
     tion  key.   It can be given patterns, like any other field.
     Here is an initialization file pattern assignment that  will
     match  an  author name, a colon, an alphabetic string, and a
     two-digit year:

     key = "A:Add"                     %% Knuth:TB86

     Notice that no quotation marks are included in the  pattern,
     because  the citation keys are not quoted.  You can use such
     patterns to help  enforce  uniform  naming  conventions  for
     citation  keys,  which  is  increasingly  important  as your
     bibliography data base grows.

LEXICAL ANALYSIS
     When -no-prettyprint is specified, bibclean acts as a  lexi-
     cal analyzer instead of a prettyprinter, producing output in
     lines of the form

          <token-number><tab><token-name><tab>"<token-value>"

     Each output line contains a single complete  token,  identi-
     fied  by  a  small integer number for use by a computer pro-
     gram, a token type name for  human  readers,  and  a  string
     value in quotes.

     Special characters in the token value string are represented
     with ANSI/ISO Standard C escape sequences, so all characters
     other than NUL are representable, and multi-line values  can
     be represented in a single line.

     Here are the token numbers and token  type  names  that  can
     appear in the output when -prettyprint is specified:



Version 2.11.3      Last change: 01 May 1996                   17






BIBCLEAN(1)               User Commands               BIBCLEAN(1)



           0   UNKNOWN
           1   ABBREV
           2   AT
           3   COMMA
           4   COMMENT
           5   ENTRY
           6   EQUALS
           7   FIELD
           8   INCLUDE
           9   INLINE
          10   KEY
          11   LBRACE
          12   LITERAL
          13   NEWLINE
          14   PREAMBLE
          15   RBRACE
          16   SHARP
          17   SPACE
          18   STRING
          19   VALUE

     Programs that parse such output should also be prepared  for
     lines  beginning  with  the warning prefix, %%, or the error
     prefix, ??, and for ANSI/ISO Standard C line  number  direc-
     tives of the form
          # line 273 "texbook1.bib"
     which record the line number and file name  of  the  current
     input file.

     If a -max-width nnn command-line option was specified,  long
     output  lines  will  be wrapped at a backslash-newline pair,
     and consequently, software that processes the lexical  token
     stream  should  be  prepared  to collapse such wrapped lines
     back into single lines.

     As an example of the use of -no-prettyprint, the  UNIX  com-
     mand pipeline
          bibclean -no-prettyprint mylib.bib | \
              awk '$2 == "KEY" {print $3}' | \
              sed -e 's/"//g' | \
              sort
     will extract a sorted list of all citation keys in the  file
     mylib.bib.

     A certain amount of processing will have been  done  on  the
     tokens.  In particular, delimiters equivalent to braces will
     have been replaced by braces, and braced strings  will  have
     become quoted strings.

     The LITERAL token type is used for arbitrary text that  bib-
     clean  does  not  examine further, such as the contents of a
     @Preamble{...} or a @Comment{...}.



Version 2.11.3      Last change: 01 May 1996                   18






BIBCLEAN(1)               User Commands               BIBCLEAN(1)



     The UNKNOWN token type should never  appear  in  the  output
     stream.   It  is  used  internally  to initialize token type
     variables.

SCRIBE BIBLIOGRAPHY FORMAT
     bibclean's support for the  Scribe  bibliography  format  is
     based  on  the syntax description in the Scribe Introductory
     User's Manual, 3rd Edition, May 1980.  Scribe was originally
     developed  by  Brian Reid at Carnegie-Mellon University, and
     is now marketed by Unilogic, Ltd.

     The BibTeX bibliography format was  strongly  influenced  by
     Scribe,  and  indeed,  with  care,  it  is possible to share
     bibliography files between the two  systems.   Nevertheless,
     there are some differences, so here is a summary of features
     of the Scribe bibliography file format:

     (1)   Letter case is not  significant  in  field  names  and
           entry names, but case is preserved in value strings.

     (2)   In field/value pairs,  the  field  and  value  may  be
           separated  by one of three characters: =, /, or space.
           Space may optionally surround these separators.

     (3)   Value delimiters are any of these seven pairs: { }   [
           ]   ( )   < >   ' '   " "   ` `

     (4)   Value delimiters may not be nested, even  though  with
           the first four delimiter pairs, nested balanced delim-
           iters would be unambiguous.

     (5)   Delimiters can be omitted around values  that  contain
           only letters, digits, sharp (#), ampersand (&), period
           (.), and percent (%).

     (6)   Outside of delimited values, a literal at-sign (@)  is
           represented by doubled at-signs (@@).

     (7)   Bibliography entries begin with @name, as for  BibTeX,
           but  any of the seven Scribe value delimiter pairs may
           be used to surround the values in  field/value  pairs.
           As in (4), nested delimiters are forbidden.

     (8)   Arbitrary space may separate entry names from the fol-
           lowing delimiters.

     (9)   @Comment is a special command whose delimited value is
           discarded.   As  in (4), nested delimiters are forbid-
           den.

     (10)  The special form




Version 2.11.3      Last change: 01 May 1996                   19






BIBCLEAN(1)               User Commands               BIBCLEAN(1)




           @Begin{comment}
            ...
           @End{comment}

           permits encapsulating arbitrary  text  containing  any
           characters      or      delimiters,     other     than
           ``@End{comment}''.  Any of the seven  delimiter  pairs
           may  be used around the word ``comment'' following the
           ``@Begin'' or ``@End'';  the  delimiters  in  the  two
           cases   need   not  be  the  same,  and  consequently,
           ``@Begin{comment}''/``@End{comment}'' pairs may not be
           nested.

     (11)  The key field is required in each bibliography entry.

     (12)  A backslashed quote in a string will be assumed to  be
           a  TeX  accent,  and braced appropriately.  While such
           accents do not conform to Scribe syntax, Scribe-format
           bibliographies  have  been  found  that  appear  to be
           intended for TeX processing.

     Because of this loose syntax, bibclean's normal error detec-
     tion heuristics are less effective, and consequently, Scribe
     mode input  is  not  the  default;  it  must  be  explicitly
     requested.

ENVIRONMENT VARIABLES
     BIBCLEANEXT  File extension  of  bibliography-specific  ini-
                  tialization files.  Default:  .ini.

     BIBCLEANINI  Name   of   bibclean   initialization    files.
                  Default:    .bibcleanrc   (UNIX),  bibclean.ini
                  (non-UNIX).

     BIBINPUTS    Search  path  for  bibclean  and  BibTeX  input
                  files.  On UNIX, this is a colon-separated list
                  of directories that are searched in order  from
                  first to last.  It is not an error for a speci-
                  fied directory to not exist.

                  On other operating systems, the directory names
                  should  be  separated  by whatever character is
                  used in system search path specifications, such
                  as a semicolon on IBM PC DOS.

     PATH         On Atari TOS, IBM PC DOS, IBM PC  OS/2,  Micro-
                  soft  NT, and UNIX, search path for system exe-
                  cutable files.  The system-wide  bibclean  ini-
                  tialization file is searched for in this path.

     SYS$SYSTEM   On VAX VMS, search path for  system  executable



Version 2.11.3      Last change: 01 May 1996                   20






BIBCLEAN(1)               User Commands               BIBCLEAN(1)



                  files  and the system-wide bibclean initializa-
                  tion file.

FILES
     *.bib          BibTeX  and  Scribe  bibliography  data  base
                    files.

     *.ini          File-specific initialization files.

     .bibcleanrc    UNIX system-wide and user-specific  initiali-
                    zation files.

     bibclean.ini   Non-UNIX system-wide and  user-specific  ini-
                    tialization files.

SEE ALSO
     bibcheck(1),  bibdup(1),  bibextract(1),  bibindex(1),  bib-
     join(1),  biblabel(1),  biblex(1),  biblook(1), biborder(1),
     bibparse(1),     bibsort(1),     bibtex(1),     bibunlex(1),
     citefind(1),  citesub(1),  citetags(1), latex(1), scribe(1),
     tex(1).

AUTHOR
     Nelson H. F. Beebe
     Center for Scientific Computing
     Department of Mathematics
     University of Utah
     Salt Lake City, UT 84112
     USA
     Tel: +1 801 581 5254
     FAX: +1 801 581 4148
     Email: <beebe@math.utah.edu>
     URL: http://www.math.utah.edu/~beebe






















Version 2.11.3      Last change: 01 May 1996                   21



