From e83e380930aaa7c258e1b31d65bff25bac1d0178 Mon Sep 17 00:00:00 2001 From: Guido van Rossum Date: Fri, 17 Mar 1995 16:01:35 +0000 Subject: [PATCH] added lots of comments --- Doc/Makefile | 108 ++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 99 insertions(+), 9 deletions(-) diff --git a/Doc/Makefile b/Doc/Makefile index a17dc77289c..85bcda20a8c 100644 --- a/Doc/Makefile +++ b/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 +# . +# (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]*