added lots of comments

Doc/Makefile

@@ -1,24 +1,77 @@
+# Makefile for Python documentation
+# ---------------------------------
+#
+# This is a bit of a mess.  The main documents are:
+#   tut -- Tutorial (file tut.tex)
+#   lib -- Library Reference (file lib.tex, inputs lib*.tex)
+#   ref -- Language Reference (file ref.tex, inputs ref*.tex)
+#   ext -- Extending and Embedding (file ext.tex)
+#
+# The main target "make all" creates DVI and PostScript for these
+# four.  You can also do "make lib" (etc.) to process individual
+# documents.
+#
+# There's also:
+#   qua -- Paper published in the CWI Quarterly (file qua.tex)
+#
+# There's one local style file: myformat.sty.  This defines a number
+# of macros that are similar in name and intent as macros in Texinfo
+# (e.g. \code{...} and \emph{...}), as well as a number of
+# environments for formatting function and data definitions, also in
+# the style of Texinfo.
+#
+# Everything is processed by LaTeX.  The following tools are used:
+#   latex
+#   makeindex
+#   dvips
+#   bibtex (only for formatting qua.tex)
+#
+# There's a problem with generating the index which has been solved by
+# a sed command applied to the index file.  The shell script fix_hack
+# does this (the Makefile takes care of calling it).
+#
+# To preview the dvi files produced by LaTeX it would be useful to
+# have xdvi as well.
+#
+# Additional targets attempt to convert selected LaTeX sources to
+# various other formats.  These are generally site specific because
+# the tools used are all but universal.  These targets are:
+#   l2h -- convert tut, ref, ext (but not lib!) from LaTeX to HTML
+#   lib.texi -- convert lib from LaTeX to Texinfo
+#   lib.info -- convert lib from Texinfo to Emacs INFO
+#   libwww -- convert lib from Texinfo to HTML
+
+# Where's dvips?
+DVIPS=	dvips -f
+
+# Install destination -- actually not used
 DESTDIR=/usr/local
 LIBDESTDIR=$DESTDIR/lib
 LIBDEST=$LIBDESTDIR/python
 DOCDESTDIR=$LIBDEST/doc
-DVIPS=	dvips -f
 
+# Main target
 all:	tut.dvi lib.dvi ref.dvi ext.dvi
 
-ext:	ext.dvi
+# Individual document fake targets
 tut:	tut.dvi
-qua:	qua.dvi
-ref:	ref.dvi
 lib:	lib.dvi
+ref:	ref.dvi
+ext:	ext.dvi
 
+# CWI Quarterly document fake target
+qua:	qua.dvi
+
+# Dependencies
 tut.dvi lib.dvi ref.dvi ext.dvi: myformat.sty fix_hack
 
+# Tutorial document
 tut.dvi: tut.tex 
 	latex tut
 	latex tut
 	$(DVIPS) tut >tut.ps
 
+# Reference document
 ref.dvi: ref.tex ref1.tex ref2.tex ref3.tex ref4.tex ref5.tex ref6.tex \
 						     ref7.tex ref8.tex 
 	touch ref.ind
@@ -58,6 +111,7 @@ libtempfile.tex libthread.tex libtime.tex \
 libunix.tex liburllib.tex liburlparse.tex \
 libwhrandom.tex libwww.tex
 
+# Library document
 lib.dvi: $(LIBFILES)
 	touch lib.ind
 	latex lib
@@ -66,6 +120,7 @@ lib.dvi: $(LIBFILES)
 	latex lib
 	$(DVIPS) lib >lib.ps
 
+# Extensions document
 ext.dvi: ext.tex 
 	touch ext.ind
 	latex ext
@@ -74,6 +129,7 @@ ext.dvi: ext.tex
 	latex ext
 	$(DVIPS) ext >ext.ps
 
+# Quarterly document
 qua.dvi: qua.tex quabib.bib
 	latex qua
 	bibtex qua
@@ -81,6 +137,10 @@ qua.dvi: qua.tex quabib.bib
 	latex qua
 	$(DVIPS) qua >qua.ps
 
+
+# The remaining part of the Makefile is concerned with various
+# conversions, as described above.
+
 lib.texi: lib*.tex texipre.dat texipost.dat partparse.py fix.el
 	python partparse.py -o @lib.texi `./whichlibs`
 	emacs -batch -l fix.el -f save-buffer -kill
@@ -89,18 +149,34 @@ lib.texi: lib*.tex texipre.dat texipost.dat partparse.py fix.el
 .PRECIOUS:	lib.texi
 
 python-lib.info: lib.texi
-	makeinfo --footnote-style end --fill-column 72 --paragraph-indent 0 \
+	-makeinfo --footnote-style end --fill-column 72 --paragraph-indent 0 \
 	         lib.texi
 
 lib.info: python-lib.info
 
 # This target is very local to CWI...
 libwww: lib.texi
-	texi2html -d lib.texi /ufs/guido/www/texinfo/python
+	python texi2html.py -d lib.texi /ufs/guido/public_html/python-lib
 
-# This one too...
-L2H=	/usr/local/LaTeX2html/latex2html
-L2HARGS=-address $$USER@`domainname` -dont_include myformat -nolatex
+# Targets to convert the manuals to HTML using Nikos Drakos' excellent
+# LaTeX to HTML Converter.  For more info on this program, see
+# <URL:http://cbl.leeds.ac.uk/nikos/tex2html/doc/latex2html/latex2html.html>.
+# (I've had some trouble getting this to work with the netpbm version
+# of the pbmplus library; ppmtogif dumped core because giftopnm
+# outputs bitmap (pbm) files.  I've fixed this by changing the source
+# of LaTeX2HTML to insert a call to pnmtoppm, which I wrote myself.
+# You can probably also use "pbmtopgm | pgmtoppm"...
+
+# In order to use these targets, you must edit the definition of L2H
+# in the Makefile to point to the latex2html program.  Note that
+# LaTeX2HTML inserts references to an "icons" directory in each page
+# that it generates.  You can customize where these icons are to be
+# found; I generally make it point to "../icons" and then create a
+# symbolic link to the icons directory in the LaTeX2HTML source at the
+# appropriate place.
+
+L2H=	/ufs/guido/l2h/latex2html
+L2HARGS=-address $$USER@`domainname` -dont_include myformat
 l2h: l2htut l2href l2hext
 
 l2htut: tut
@@ -118,10 +194,24 @@ l2hext: ext
 	@rm -rf python-ext
 	mv ext python-ext
 
+# This target doesn't quite work, since l2h doesn't understand the
+# funcdesc and similar environments, and turns them into GIF images.
+# Use the "libwww" target above instead.
+l2hlib: lib
+	$(L2H) $(L2HARGS) lib.tex
+	@rm -rf python-lib
+	mv lib python-lib
+
+
+# Housekeeping targets
+
+# Remove temporary files
 clean:
 	rm -f @* *~ *.aux *.idx *.ilg *.ind *.log *.toc *.blg *.bbl *.pyc
+	rm -f *.bak *.orig
 	# Sources: .tex, .bib, .sty
 	# Useful results: .dvi, .ps, .texi, .info
 
+# Remove temporaries as well as final products
 clobber: clean
 	 rm -f *.dvi *.ps *.texi *.info *.info-[0-9]*