Bookstuff package

The bookstuff package is used to make a book out of a collection of
standalone LaTeX documents.  It was designed for conference proceedings.
In particular, it has been used for several volumes in the Astronomical
Data Analysis Software and Systems (ADASS) conference series.

The package consists of two parts:

     1) Tools for producing the printed volume, and

     2) Tools for producing an HTML version with the latex2html
	program.

REQUIREMENTS

The requirement for part 1) is a working Perl installation, since the
tools are written in Perl.  A working make program is desirable, but
not strictly necessary.  I have used these tools on a UNIX platform,
but they may work on a Win32 platform.

The requirement for part 2) is a working Perl installation, and a
working latex2html program -- that combination may restrict you to a
UNIX platform.


HOW IT WORKS

The basic plan is to put all of the contributed papers into one directory.
A Perl script scans all of the papers for \title and \author tags,
and builds a book.tex file which, among other things, will \input a
processed version of each paper.  Running LaTeX on the book.tex file
will produce the printed version of the book.  The book.tex file is
built from a template that you should first edit for your volume.
After running the script, you must edit the book.tex file to put the
papers in the order you desire.  

Each paper is processed for inclusion in the book by commenting out
\documentstyle, \begin{document}, and \end{document} commands, and
converting \title commands into \chapter commands.  The script can
process all of the papers at once, or can do individual papers.  If used
with the UNIX make program, papers will be processed into chapters only
if they have changed.  (A separate script will build a Makefile (make
command file) for you, starting from a template file.)  Once you have
the book.tex file and all of the chapters, process with LaTeX to produce
the printed version of the book.  The only enhancements over the normal
LaTeX features are facilities for producing an author index, for
creating cross-references between papers, and for adding a copyright
notice to each paper for a version of the book that can be used to
create reprints.

To make the HTML version of the book, run the latex2html program on
book.tex.  The tools in this package consist of 1) modifications to the
latex2html program, and 2) a number of scripts for processing the output
from latex2html.  The items under 1) include a latex2html style file,
written in perl, and, unfortunately, a slightly modified version of
latex2html version 98.1p1.  A patch file for modifying latex2html is
also included, which may help when newer versions of latex2html are
released.  Items under 2) are basically tools to put the output into the
format desired for ADASS proceedings.  They rename the HTML files for
the authors into a version that may be easier to remember and then fix
all of the cross-links.  Other scripts can be used to create an index
where page numbers from the printed volume, rather than titles, are
shown, and to create PostScript reprints of the articles.

The process is broken into a number of steps, so that you can make
corrections by hand if the scripts do something wrong.  This also means
that you may lose work if you have to back up and run the scripts again.
So be careful, and check your results as you go along.

GETTING STARTED

You will need a directory in which all of the contributed papers and
their associated PostScript figures reside.  You also need a directory
where all of the tools will reside and where the book.tex and chapter
files will reside.  They can be the same directory, but need not be.

Put all of the .pl and .pm files into the directory for the book.
You may have to edit the first line of each file to refer to the
location of your perl program.  A number of configuration parameters
are in the BOOKSTUFF.pm file, which you should edit, following the
instructions in the comments.  The only one that really matters is
the value of $pathsep, which is different depending on whether you are
working under UNIX or Windows.

THE PAPERS

You want to have all of the papers before you start working on the
book.  Late papers can be added by hand, though.  You do not have to be
finished editing the papers -- it is easy enough to automatically update
the book if you edit one of the papers, especially if you are using
make.

There are some good reasons to assemble the book early in the editing
process, though:

     1)	If you are making an index, it is impossible to do a good job
	without seeing the entire index and refining it by iteration.
	Since the \index commands go in the papers, this will involve
	going back to edit the papers.

     2)	Creating an author index is more of a mechanical exercise than
	a subject index, but the entire index is required to eliminate
	multiple entries due to variations in the way a name is listed
	in multiple papers.

     3)	PostScript figure problems.  It is nice to be able to preview,
	at least, the entire book to see that all of the figures are
	properly oriented, positioned, and scaled.  Many problems
	can be fixed by editing the PostScript to supply an accurate
	BoundingBox.  Checking that all of the figures print on your
	printer is also nice.

To add an author index, add \aindex commands to the papers.  Example:
if the authorlist is

	M. A. Albrecht, A. Brighton, T. Herlin, P. Biereichel
 
Then add these lines to the paper, below the \title:

	\aindex{Albrecht, M.~A.|bb}
	\aindex{Brighton, A.}
	\aindex{Herlin, T.}
	\aindex{Biereichel, P.}
 


ONCE YOU HAVE ALL OF THE PAPERS

You are ready to work on the book.  My scheme expects all of the source
files for the papers to be in one directory.  You can build the book
in the same directory or in a different directory.  Move all of the
bookstuff files into the directory you have chosen.  

At this point, the basic plan is to edit the book.template file and run
the arts2book.pl Perl script to build a book.tex file which serves as
the skeleton for the book.  For each paper, the script scans the source
file for a title and authors (it's looking for \title and \author tags -- 
I hope your macro package uses them) and builds an entry like

\paper{ L.~A. Higgs, A.~P. Hoffmann, and A.~G. Willis}{ Higgs, Hoffmann, and Willis}{The DRAO Export Software Package}\input higgsl.ltx

where the three arguments of the paper macro are the authorlist for the
table of contents, a short authorlist for page headings, and a short
title for page headings (the full title is given, but you can edit it
down if the full title is too long).  Rearrange the entries so that that
they are in the order in which you wish the papers to appear.

If you are on a UNIX machine and can use the make utility, edit the
Makefile.template file and run the arts2make.pl Perl script to build the
Makefile.  Once you have a Makefile,

	make book.dvi

should prepare the modified versions of each paper, where the paper has
been turned into a chapter, and run LaTeX on book.tex.  Now you can see
where you are.  With luck, you will be close to the end.  Edit the
papers and book.tex as required and "make book.dvi" again.  When you are
happy with the result, "make book.ps" will make the PostScript file for
you to print or send to the publisher.

If you do not have the make utility, then you will have to convert each
paper into a chapter by running the art2chap.pl Perl script.  If all of
the papers are in this directory you can

	art2chap.pl *.tex

if all of the files are in another directory, you can tell art2chap.pl
where that is and it will do all of the .tex files there.  For example:

	art2chap.pl -paperdir ../papers

Then "latex book" to create the book.dvi file.  If you need to edit any
of the papers, you will need to recreate their chapter file and then run
latex again.