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: