%% /u/sy/beebe/tex/bibclean/README, Tue Nov 24 08:14:30 1992
%% Edit by Nelson H. F. Beebe <beebe@plot79.math.utah.edu>

========================================================================

============
INTRODUCTION
============

This directory contains bibclean, a BibTeX prettyprinter, portability
verifier, and syntax checker.  It can be used to find errors in .bib
files, as well as to standardize their format for readability and
editing convenience.  It can also be used to convert Scribe-format
bibliographies to BibTeX form.

Because transfer of binary files between systems is often troublesome,
uuencoded binary executables for IBM PC DOS and DEC VAX VMS are
included in the distribution.  Instructions are given below for
acquiring implementations of uudecode for these systems.

The binaries are also present if you got a tar, zip, or zoo
distribution, but are excluded if you got a shar distribution.  If you
do not require either the IBM PC DOS or DEC VAX VMS version, then you
can save about 1.3MB of disk space by deleting the ibmpc and vaxvms
subdirectories.

The default pattern matching in bibclean.c is selected by
HAVE_PATTERNS; with it, no regular-expression library support is
needed.  Should you wish to compile with regular-expression support
instead of the HAVE_PATTERNS code, and your system does not have
compile()/step (HAVE_REGEXP), or re_comp()/re_exec() (HAVE_RECOMP),
you may be able to use the regex-?-??.tar.Z distribution from the Free
Software Foundation, available on prep.ai.mit.edu in ~ftp/pub/gnu.

In most cases, the HAVE_PATTERNS code is recommended, since it will
give identical results across all machines.  I was prompted to write
it after discovering that there was considerable variety in the
regular expression library codes that resulted in different matching
on different machines, a most unsatisfactory situation.

Please report all problems, suggestions, and comments to the 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>


============
UNIX Systems
============

The code can be compiled with either C (K&R or ISO/ANSI Standard C) or
C++ compilers; the Makefile contains several different suitable
settings of the CC macro.

On UNIX systems, the only changes that you are likely to need in the
Makefile are the settings of CC and CFLAGS, and possibly, DEFINES, and
if you wish to do "make install", the settings of BINDIR, MANDIR, and
MANEXT.

If you are installing bibclean on a new system, you should definitely
run "make test" before installing it on your system.  For the target
test-bibtex-2, latex is needed.  For test-bibtex-2 and test-scribe-1,
bibtex is needed.  Sample output of "make test" from a UNIX system
is given below.

The code has been tested under several different C and C++ compilers,
and is in regular use to maintain the TeX User Group bibliography
collection stored on math.utah.edu:~ftp/pub/tex/bib, as well as
several other local bibliographies.  These files total more than 200K
lines and 18K bibliography entries.

If you port it to a new system, please select maximal error and
warning messages in your compiler.  If you find massive numbers of
errors complaining about function and argument type mismatches, it is
likely that this can be remedied by suitable modifications of os.h.
As C implementations move towards conformance with the December 1989
ISO/ANSI C Language Standard, the C language is a moving target that
must be tracked by os.h.  You can safely ignore complaints about
implicit declaration of library functions; they are caused by
deficiencies in the vendor-provided header files.

If you have a C++ compiler, please try that as well.  This code has
been successfully compiled under at least 6 C++ compilers, and the
stricter type checking has uncovered problems that slipped past other
compilers.


==========
IBM PC DOS
==========

The ibmpc subdirectory contains these files for the IBM PC:

	bibclean.exe		bibclean executable program
	bibclean.uue		uuencoded version of bibclean.exe
	makefile.tcc		Makefile for Turbo C/C++ 3.0
	makefile.msc		Makefile for Microsoft C 5.1, 6.0, 7.0
				with Microsoft nmake (available in 6.0
				and 7.0 distributions)
	msc51bld.bat		Build bibclean with Microsoft C 5.1
	msc51pth.bat		Set PATH variable for Microsoft C 5.1
	msc60bld.bat		Build bibclean with Microsoft C 6.0
	msc60pth.bat		Set PATH variable for Microsoft C 6.0
	msc70bld.bat		Build bibclean with Microsoft C 7.0
	msc70pth.bat		Set PATH variable for Microsoft C 7.0
	tcc20bld.bat		Build bibclean with Turbo C 2.0
	tcc20pth.bat		Set PATH variable for Turbo C 2.0
	tcc30bld.bat		Build bibclean with Turbo C++ 3.0
	tcc30pth.bat		Set PATH variable for Turbo C/C++ 3.0
	ibmtest.bat		Test bibclean

The executable program has been compiled with Borland Turbo C and C++
3.0 under MS DOS 4.0 running on a 25MHz Intel 486/DX board in a Sun
SPARCstation 2 with SunPC.  With the 486 board, SunPC provides DOS on
native hardware.  Without it, or under an additional session, it
provides DOS by emulating the Intel instruction set.  bibclean has
also been compiled and successfully tested with Turbo C 2.0, but the C
3.0 compiled version is the one distributed, because it gives the
smallest bibclean.exe file size:

	Turbo C 2.0:	55844
	Turbo C 3.0:	53936
	Turbo C++ 3.0:	97874

[The distribution size may be slightly different; the given sizes are
a snapshot near the end of the 2.05 development.]

bibclean has also been successfully built with Microsoft C 5.1 and
6.0.  Version 5.0 has fatal compiler errors that prevent its use for
this program; I could not find acceptable code workarounds.  I have
been unable to run version 7.0 on my SPARCstation; the compiler dies
with a "runtime error R6018 - unexpected heap error", despite my
having installed the Qualitas 386MAX memory manager that comes with
Microsoft C 7.0.  Thus, although there are .bat files and makefile.msc
for 7.0, they have not been tested, and regrettably, 7.0 C++ cannot be
used.  Each C++ compiler I've tried has exposed new things that need
fixing.  I tried unsuccessfully to install Microsoft C 7.0 on our lab
PCs, but that too failed, because 7.0 needs a 386 with more than 4MB
of memory, and our PCs are old 286 models, sigh...

The bibclean executable sizes from Microsoft C are larger than with
Turbo C, so I'm not distributing them:

	Microsoft C 5.1:	98601
	Microsoft C 6.0:	92499

The Microsoft port gave considerable trouble, because I was unable to
get the stack and data segments to be separated, despite using teh
compiler option (-Asfu) to do so.  Compilation would complete
normally, then the linker would complain that stack + data exceeded
64KB.  Since the Turbo C build had been successful in the compact
memory model, I did not want to go to the large model for Microsoft C.
I finally succeeded by using the -Gt1024 option, which forces objects
larger than 1024 bytes to be placed in a separate section.  This left
room for a stack size of 0xb000 (45056 bytes), which is more than
ample.

A few small code codes changes were needed for the Microsoft C
compilers.  In particular, it would not accept const modifiers in
certain (legal) places.  The workaround is to rewrite them as a macro
CONST which expands to an empty string with M_I86 is defined (the only
symbol that appears to uniquely differentiate between C compilers from
Borland, Microsoft, and TopSpeed), and to const otherwise.

Since bibclean uses no floating-point arithmetic, and PC DOS has no
shared libraries, I expect that the executable will run on any version
of DOS greater than 4.0.  It may also run on earlier versions.  At the
time of writing 5.0 is current, and this bibclean executable works
fine on it.

To rebuild bibclean, you will need to adjust directory paths in
makefile.msc, makefile.tcc, msc*.bat and/or tcc*.bat.  The *bld.bat
files can be used to build bibclean, or if you have Turbo C/C++ 3.0,
you can copy makefile.tcc to makefile and type "make".  With Microsoft
C 5.1 and the 6.0 nmake utility, you can copy makefile.msc to makefile
and do "nmake".  The Microsoft 6.0 compiler is too big to run
underneath nmake; the workaround is fortunately simple:

	nmake -n >foo.bat
	foo

You should definitely run ibmtest to make sure the newly-built program
is working correctly; you'll need to copy bibclean.exe and ibmtest.bat
into the top-level bibclean directory in order for it to find the test
files.  Unlike the UNIX "make test", ibmtest does not require that
latex or bibtex be installed on your system.

If you don't have uuencode/uudecode for IBM PC DOS, you can get it via
e-mail; for details, send a message with the lines

	help
	send index from support
	send index from ftp/ibmpc
	send uuarc.arc from ftp/ibmpc
	send uuencode.arc from ftp/ibmpc

to tuglib@math.utah.edu.  Alternatively, you can use anonymous ftp to
ftp.math.utah.edu and fetch the files uuarc.arc or uuencode.arc from
~ftp/pub/ibmpc.  uuarc.arc contains only .com executables;
uuencode.arc contains sources, makefiles, and .exe files.

If your transfer of these files did not translate UNIX LF line
terminators to PC DOS CR LF terminators, the ux2dos and dos2ux
utilities can be of assistance.  You can find their source code in
~ftp/pub/ibmpc/dos2ux.shar (via e-mail to tuglib@math.utah.edu, "send
dos2ux.shar from support".


===========
DEC VAX VMS
===========

The vaxvms subdirectory contains these files for DEC VAX VMS:

	bibclean.exe		bibclean executable program
	bibclean.uue		uuencoded version of bibclean.exe
	recomp.com		do @recomp foo to recompile foo.c
	vmsclean.com		do @vmsclean to cleanup after a build
	vmsmake.com		do @vmsmake to build bibclean
	vmstest.com		do @vmstest to test bibclean

You will have to change one line in vmstest.com to define the disk
location of bibclean.exe in the foreign command symbol for bibclean.
If you don't have uuencode/uudecode for VAX VMS, you can get it via
e-mail; for details, send a message with the lines

	help
	send index from support

to tuglib@math.utah.edu.

Unlike the UNIX "make test", execution of vmstest.com does not require
that latex or bibtex be installed on your system.  [I didn't have
either on the VAX VMS system that I built bibclean on.]


==================================
SAMPLE "make test" OUTPUT FOR UNIX
==================================

==================== begin BibTeX test 1 =====================


./bibclean -init-file bibclean.ini testbib1.org >testbib1.bib 2>testbib1.err

There should be no differences found:
diff testbib1.bok testbib1.bib

There should be no differences found:
diff testbib1.eok testbib1.err

===================== end BibTeX test 1 ======================


==================== begin BibTeX test 2 =====================


./bibclean -init-file bibclean.ini -no-check-values testbib2.org >testbib2.bib 2>testbib2.err

There should be no differences found:
diff testbib2.bok testbib2.bib

There should be no differences found:
diff testbib2.eok testbib2.err

latex testbib2.ltx >/dev/null

Expect 6 BibTeX warnings:
bibtex testbib2
This is BibTeX, C Version 0.99c
The top-level auxiliary file: testbib2.aux
The style file: alpha.bst
Database file #1: testbib2.bib
Warning--empty year in Bennett
Warning--empty year in Cejchan
Warning--there's a number but no volume in Dubowsky:75
Warning--empty institution in Diver:88a
Warning--empty booktitle in Diver:88
Warning--empty year in Diver
(There were 6 warnings)

latex testbib2.ltx >/dev/null

latex testbib2.ltx
This is TeX, C Version 3.14t3
(testbib2.ltx
LaTeX Version 2.09 <7 Dec 1989>
(/usr/local/lib/tex/inputs/article.sty
Document Style `article' <16 Mar 88>.
(/usr/local/lib/tex/inputs/art10.sty)) (testbib2.aux) (testbib2.bbl [1]
[2] [3]
Underfull \hbox (badness 1024) in paragraph at lines 261--264
[] []\tenrm L. M. Berkovich, V. P. Gerdt, Z. T. Kos-tova, and M. L.
[4] [5] [6] [7] [8] [9] [10] [11] [12] [13] [14] [15] [16]) [17] (testbib2.aux)
 )
(see the transcript file for additional information)
Output written on testbib2.dvi (17 pages, 49032 bytes).
Transcript written on testbib2.log.

===================== end BibTeX test 2 ======================


==================== begin BibTeX test 3 =====================

./bibclean -init-file bibclean.ini testisxn.org >testisxn.bib 2>testisxn.err
*** Error code 1 (ignored)

There should be no differences found:
diff testisxn.bok testisxn.bib

There should be no differences found:
diff testisxn.eok testisxn.err

===================== end BibTeX test 3 ======================


==================== begin Scribe test 1 =====================


----------------------------------------------------

./bibclean -init-file bibclean.ini -scribe -no-check testscr1.org >testscr1.bib

There should be no differences found:
diff testscr1.bok testscr1.bib

There should be no differences found:
diff testscr1.eok testscr1.err

Expect 5 BibTeX warnings
bibtex testscr1
This is BibTeX, C Version 0.99c
The top-level auxiliary file: testscr1.aux
The style file: plain.bst
Database file #1: testscr1.bib
Warning--empty publisher in hanson-67
Warning--can't use both volume and number fields in kendeigh-52
Warning--empty author in singer-portion-chapter
Warning--empty author in singer-portion-volume
Warning--can't use both author and editor fields in wright-63
(There were 5 warnings)

----------------------------------------------------

./bibclean -init-file bibclean.ini -scribe -no-check testscr2.org >testscr2.bib

There should be no differences found:
diff testscr2.bok testscr2.bib

There should be no differences found:
diff testscr2.eok testscr2.err

There should be no BibTeX warnings:
bibtex testscr2
This is BibTeX, C Version 0.99c
The top-level auxiliary file: testscr2.aux
The style file: plain.bst
Database file #1: testscr2.bib
===================== end Scribe test 1 ======================


==================== begin Scribe test 2 =====================

./bibclean -init-file bibclean.ini -scribe -file -no-check -no-par testscr2.org \
	>testscr2.bi2 2>testscr2.er2
*** Error code 1 (ignored)

There should be no differences found:
diff testscr2.bo2 testscr2.bi2

There should be no differences found:
diff testscr2.eo2 testscr2.er2

===================== end Scribe test 2 ======================


==================== begin Scribe test 3 =====================

./bibclean -init-file bibclean.ini -scribe -no-check testscr3.org >testscr3.bib 2>testscr3.err

There should be no differences found:
diff testscr3.bok testscr3.bib

There should be no differences found:
diff testscr3.eok testscr3.err

===================== end Scribe test 3 ======================



===============================[The End]===============================
