HOW TO COMPILE AND USE BIB2XML

                Johannes Henkel (jhenkel@jhenkel.de)
                            10/06/2002
     License: GPL (see http://www.gnu.org/copyleft/gpl.html)
 The files in the pccts subdirectory are not covered by the GPL.
	  See README for licensing details, I'm not a lawyer.


(0) Overview
------------
This package consists of two components. Using both components, one can
convert bibtex into bibtexml (http://bibtexml.sourceforge.net/).

(0.A) bib2xml
-------------
bib2xml: bibtex -> well formed xml

bib2xml is based on Greg Ward's great btparse library. Actually, 99% of
the code in this archive is Greg's code. All I had to do was to
change the output of one of his example programs a little bit.
The output is a well-formed XML file that is almost compatible with
bibtexml (besides the order of elements and elements that are not supported
by bibtexml). It's a flat format, however.

(0.B) unflatten.py
------------------
unflatten.py: output of bib2xml -> bibtexml

Features:
* can drop fields and entries not supported by bibtexml
* can sort fields according to the bibtexml DTD.
* convert <bibtex:author>Donald E. Knuth</bibtex:author>
  into
	<bibtex:authors>
  		<bibtex:person>
	 		<bibtex:first>Donald</bibtex:first>
		 	<bibtex:middle>E.</bibtex:middle>
		 	<bibtex:last>Knuth</bibtex:last>
		</bibtex:person>
	<bibtex:authors>

(1a) How to compile bib2xml
---------------------------

I tried this procedure under Redhat Linux 7.3 and Suse Linux 8.0.
If you are using MS Windows, you may have luck with cygwin
(http://www.cygwin.com/), which is a bunch of free unix tools
for your Windows desktop (I haven't tried that).

Execute the following steps:

	./configure
	cd progs
	make bib2xml
	
After that, you should find the binary bib2xml
in the progs subdirectory.

(1b) How to run unflatten.py
----------------------------
unflatten.py is in the progs subdirectory.
I've been using Python 2.2 for this. I don't know whether it works
with earlier versions. You may have to edit the first line of the python
script so that it points to the python binary on your system.
Python can be found at http://www.python.org/.

(2) How to use bib2xml and unflatten.py
---------------------------------------

You can use the bib2xml binary to convert bibtex to well formed XML.

For example, execute

	bib2xml mybib.bib > output.xml
	
to convert the bibtex file mybib.bib into bibtexml format.

If you want to use the postprocessor unflatten.py, you could
do the following:

	unflatten.py --unflatten --drop output.xml > output2.xml
	
This will convert the file output.xml into a bibtexml compatible
format. Use unflatten.py --help to find out what the options mean.

Actually, what you may want to do is in fact

	bib2xml mybib.bib | unflatten.py --unflatten --drop - > output2.xml

instead...

(3) Changes:
------------

09202002 - initial release

10062002 - this release escapes characters such as & < etc. so that the output
           of bib2xml is now well formed xml. Furthermore, I added unflatten.py,
			  which is a script that postprocesses the xml to make it more
			  compatible with bibtexml