1 DVI
bibsort - sort a BibTeX bibliography file
2 SYNOPSIS
SYNOPSIS
bibsort [optional sort(1) switches] < infile >outfile
2 DESCRIPTION
DESCRIPTION
bibsort filters a BibTeX bibliography, or bibliography frag-
ment, on its standard input, printing on standard output a
sorted bibliography.
Sorting is by BibTeX tag name, or by @String macro name, and
letter case is ignored in the sorting.
If no command-line switches are provided for sort(1), then
-f is supplied to cause letter case to be ignored. If you
also want to remove duplicate entries, you could specify the
switches -f -u.
The input stream is conceptually divided into four parts,
any of which may be absent.
2 --1.--Introductory--material--such--as -comments,---file
1. Introductory material such as comments, file
2 ------headers, and-edit-logs-that-are-ignored-by-BibTeX.
headers, and edit logs that are ignored by BibTeX.
2 ------No-line-in-this-part-begins-with-an-at-sign,-``@''.
No line in this part begins with an at-sign, ``@''.
2 --2.--Preamble-material delineated-by-``@Preamble{''--and
2. Preamble material delineated by ``@Preamble{'' and
2 ------a -matching-closing-``}'',-intended-to-be processed
a matching closing ``}'', intended to be processed
2 ------by-TeX.--Normally,-there-is-only-one-such entry--in
by TeX. Normally, there is only one such entry in
2 ------a -bibliography-file,-although-BibTeX,-and-bibsort,
a bibliography file, although BibTeX, and bibsort,
2 ------permit-more-than-one.
permit more than one.
2 --3.--Macro-definitions of-the-form-``@String{...}''. A
3. Macro definitions of the form ``@String{...}''. A
2 ------single--macro--definition -may-span-multiple-lines,
single macro definition may span multiple lines,
2 ------and-there are-usually-several-such-definitions.
and there are usually several such definitions.
2 --4.--Bibliography--entries--such--as--``@Article{...}'',
4. Bibliography entries such as ``@Article{...}'',
2 ------``@Book{...}'',--``@Proceedings{...}'',--and-so-on.
``@Book{...}'', ``@Proceedings{...}'', and so on.
2 ------For-bibsort,-any-line-that--begins--with an--``@''
For bibsort, any line that begins with an ``@''
2 ------immediately--followed--by letters and-digits-and-an
immediately followed by letters and digits and an
2 ------open-brace-is-considered-to-be-such-an-entry.
open brace is considered to be such an entry.
The order of these parts is preserved in the output stream.
Part 1 will be unchanged, but parts 2--4 will be sorted
within themselves.
The sort key of ``@Preamble'' entries is their initial line,
of ``@String'' entries, the macro name, and of all BibTeX
entries, the citation tag between the open curly brace and
the trailing comma.
bibsort will correctly handle UNIX files with LF line termi-
nators, as well as IBM PC DOS files with CR LF line termina-
tors; the essential requirement is that input lines be del-
ineated by LF characters.
2 CAVEATS
CAVEATS
BibTeX has loose syntactical requirements that the current
simple implementation of bibsort does not support. In par-
ticular, outer parentheses may not be used in place of
braces following ``@keyword'' patterns, nor may there be
leading or embedded whitespace.
If you have such a file, you can use bibclean(1) to pretty-
print it into a form that bibsort can handle successfully.
The user must be aware that sorting a bibliography is not
without peril, for at least these reasons:
2 --1.--BibTeX-has-a-requirement-that-entry-tags given--in
1. BibTeX has a requirement that entry tags given in
2 ------crossref =--tag-pairs-in a-bibliography-entry-must
crossref = tag pairs in a bibliography entry must
2 ------refer-to-entries-defined-later,--rather--than--ear-
refer to entries defined later, rather than ear-
2 ------lier,--in -the-bibliography-file. -This-regrettable
lier, in the bibliography file. This regrettable
2 ------implementation-limitation of-the-current (pre-1.0)
implementation limitation of the current (pre-1.0)
2 ------BibTeX--prevents-arbitrary-ordering-of-entries-when
BibTeX prevents arbitrary ordering of entries when
2 ------crossref-values-are-present.
crossref values are present.
2 --2.--If-the-BibTeX-file-contains-interspersed-commentary
2. If the BibTeX file contains interspersed commentary
2 ------between--``@keyword{...}''--entries,--this-material
between ``@keyword{...}'' entries, this material
2 ------will-be-considered-part-of-the-preceding-entry,-and
will be considered part of the preceding entry, and
2 ------will-be-sorted-with-it.--Leading-commentary-is-more
will be sorted with it. Leading commentary is more
2 ------common,-and-will-be-moved elsewhere-in-the-file.
common, and will be moved elsewhere in the file.
2 ------This-is-normally-not--a--problem for--the--part 1
This is normally not a problem for the part 1
2 ------material-before-the-``@Preamble'',-since-it-is-kept
material before the ``@Preamble'', since it is kept
2 ------together-at-the-beginning of-the-output-stream.
together at the beginning of the output stream.
2 --3.--Some-kinds-of-bibliography-files-should-be-kept--in
3. Some kinds of bibliography files should be kept in
2 ------a -different--order-than-alphabetically-by-tags. A
a different order than alphabetically by tags. A
2 ------good-example-is-a bibliography-file-with the--con-
good example is a bibliography file with the con-
2 ------tents--of a-journal,-for-which-publication-order-is
tents of a journal, for which publication order is
2 ------likely-more-suitable.
likely more suitable.
While a much more sophisticated implementation of bibsort
could deal with the first point, solving the second one
requires human intelligence and natural language understand-
ing that computers lack.
bibsort uses ASCII control characters 001 through 007 for
temporary modifications of the input stream. If any of
these are already present in the input, they will be altered
on output. This is unlikely to be a problem, because those
characters have neither a printable representation, nor are
they conventionally used to mark line or page boundaries in
text files.
2 PROGRAMMING-NOTES
PROGRAMMING NOTES
Some text editors permit application of an arbitrary filter
command to a region of text. For example, in GNU emacs(1),
the command C-u M-x shell-command-on-region, or
equivalently, C-u M-|, can be used to run bibsort on a
region of the buffer that is devoid of cross references and
other material that cannot be safely sorted.
Some implementations of BibTeX editing support in GNU
emacs(1) have a sort-bibtex-entries command that is func-
tionally similar to bibsort. However, the file size that
can be processed by emacs(1) is limited, while bibsort can
be used on arbitrarily large files, since it acts as a
filter, processing a small amount of data at a time. The
sort stage needs the entire data stream, but fortunately,
the UNIX sort(1) command is clever enough to deal with very
large inputs.
The current implementation of bibsort follows the UNIX trad-
ition of combining simple already-available tools. A six-
stage pipeline of egrep(1), nawk(1), sort(1), and tr(1)
accomplishes the job in one pass with about 70 lines of
shell script, 60 lines of which is a nawk(1) program for
insertion of sort keys. bibsort was written and tested on
several large bibliographies in a couple of hours. By con-
trast, bibtex(1) is more than 11 000 lines of code and docu-
mentation, and bibclean(1) is about 1500 lines long.
2 BUGS
BUGS
bibsort may fail on some UNIX systems if their sort(1)
implementations cannot handle very long lines, because for
sorting purposes, each complete bibliography entry is tem-
porarily folded into a single line. You may be able to
overcome this problem by adding a -znnnnn switch to the
sort(1) command (passed via the command line to bibsort) to
increase the maximum line size to some larger value of nnnnn
bytes.
2 SEE-ALSO
SEE ALSO
bibclean(1), bibtex(1), egrep(1), emacs(1), nawk(1),
sort(1), tr(1).
2 AUTHOR
AUTHOR
Nelson H. F. Beebe, Ph.D.
Center for Scientific Computing
Department of Mathematics
University of Utah
Salt Lake City, UT 84112
Tel: (801) 581-5254
FAX: (801) 581-4148
Email: <beebe@math.utah.edu>