Fit Makefile for the Python doc environment better; this is a step toward

including the howtos in the build process.

	* Put LaTeX output in ../paper-<whatever>/.
	* Put HTML output in ../html/
	* Explain some of the Makefile variables
	* Remove some cruft dating to my environment (e.g. the 'web' target)

This makefile isn't currently invoked by the documentation build process,
so these changes won't destabilize anything.

diff --git a/Doc/howto/Makefile b/Doc/howto/Makefile
index 19701c69eb7d3844cc8b340e6bb32d46653e1422..18110a2d4902550950dcda5a26ad9fbba6ebfbbc 100644 (file)
--- a/Doc/howto/Makefile
+++ b/Doc/howto/Makefile
@@ -1,88 +1,84 @@
+# Makefile for the HOWTO directory
+# LaTeX HOWTOs can be turned into HTML, PDF, PS, DVI or plain text output.
+# reST HOWTOs can only be turned into HTML.
 
-MKHOWTO=../tools/mkhowto
-WEBDIR=.
+# Variables to change
+
+# Paper size for non-HTML formats (letter or a4)
+PAPER=letter
+
+# Arguments to rst2html.py, and location of the script
 RSTARGS = --input-encoding=utf-8
-VPATH=.:dvi:pdf:ps:txt
+RST2HTML = rst2html.py
 
-# List of HOWTOs that aren't to be processed
+# List of HOWTOs that aren't to be processed.  This should contain the
+# base name of the HOWTO without any extension (e.g. 'advocacy',
+# 'unicode').
+REMOVE_HOWTOS =
 
-REMOVE_HOWTO =
+MKHOWTO=../tools/mkhowto
+WEBDIR=.
+PAPERDIR=../paper-$(PAPER)
+HTMLDIR=../html
 
 # Determine list of files to be built
+TEX_SOURCES = $(wildcard *.tex)
+RST_SOURCES = $(wildcard *.rst)
+TEX_NAMES = $(filter-out $(REMOVE_HOWTOS),$(patsubst %.tex,%,$(TEX_SOURCES)))
+
+PAPER_PATHS=$(addprefix $(PAPERDIR)/,$(TEX_NAMES))
+DVI  =$(addsuffix .dvi,$(PAPER_PATHS))
+PDF  =$(addsuffix .pdf,$(PAPER_PATHS))
+PS   =$(addsuffix .ps,$(PAPER_PATHS))
 
-HOWTO=$(filter-out $(REMOVE_HOWTO),$(wildcard *.tex))
-RST_SOURCES =  $(shell echo *.rst)
-DVI  =$(patsubst %.tex,%.dvi,$(HOWTO))
-PDF  =$(patsubst %.tex,%.pdf,$(HOWTO))
-PS   =$(patsubst %.tex,%.ps,$(HOWTO))
-TXT  =$(patsubst %.tex,%.txt,$(HOWTO))
-HTML =$(patsubst %.tex,%,$(HOWTO))
+ALL_HOWTO_NAMES = $(TEX_NAMES) $(patsubst %.rst,%,$(RST_SOURCES))
+HOWTO_NAMES = $(filter-out $(REMOVE_HOWTOS),$(ALL_HOWTO_NAMES))
+HTML = $(addprefix $(HTMLDIR)/,$(HOWTO_NAMES))
 
 # Rules for building various formats
-%.dvi : %.tex
+
+# reST to HTML
+$(HTMLDIR)/%: %.rst
+       if [ ! -d $@ ] ; then mkdir $@ ; fi
+       $(RST2HTML) $(RSTARGS) $< >$@/index.html
+
+# LaTeX to various output formats
+$(PAPERDIR)/%.dvi : %.tex
        $(MKHOWTO) --dvi $<
-       mv $@ dvi
+       mv $*.dvi $@
 
-%.pdf : %.tex
+$(PAPERDIR)/%.pdf : %.tex
        $(MKHOWTO) --pdf $<
-       mv $@ pdf
+       mv $*.pdf $@
 
-%.ps : %.tex
+$(PAPERDIR)/%.ps : %.tex
        $(MKHOWTO) --ps $<
-       mv $@ ps
+       mv $*.ps $@
+
+$(HTMLDIR)/% : %.tex
+       $(MKHOWTO) --html --iconserver="." --dir $@ $<
 
-%.txt : %.tex
+# Rule that isn't actually used -- we no longer support the 'txt' target.
+$(PAPERDIR)/%.txt : %.tex
        $(MKHOWTO) --text $<
        mv $@ txt
 
-% : %.tex
-       $(MKHOWTO) --html --iconserver="." $<
-       tar -zcvf html/$*.tgz $*
-       #zip -r html/$*.zip $*
-
 default:
        @echo "'all'    -- build all files"
-       @echo "'dvi', 'pdf', 'ps', 'txt', 'html' -- build one format"
-
-all: $(HTML)
-
-.PHONY : dvi pdf ps txt html rst
-dvi: $(DVI)
-
-pdf: $(PDF)
-ps:  $(PS)
-txt: $(TXT)
-html:$(HTML)
-
-# Rule to build collected tar files
-dist: #all
-       for i in dvi pdf ps txt ; do \
-           cd $$i ; \
-           tar -zcf All.tgz *.$$i ;\
-           cd .. ;\
-       done
+       @echo "'dvi', 'pdf', 'ps', 'html' -- build one format"
 
-# Rule to copy files to the Web tree on AMK's machine
-web: dist
-       cp dvi/* $(WEBDIR)/dvi
-       cp ps/* $(WEBDIR)/ps
-       cp pdf/* $(WEBDIR)/pdf
-       cp txt/* $(WEBDIR)/txt
-       for dir in $(HTML) ; do cp -rp $$dir $(WEBDIR) ; done
-       for ltx in $(HOWTO) ; do cp -p $$ltx $(WEBDIR)/latex ; done
+all: dvi pdf ps html
 
-rst: unicode.html
-
-%.html: %.rst
-       rst2html $(RSTARGS) $< >$@
+.PHONY : dvi pdf ps html
+dvi:  $(DVI)
+pdf:  $(PDF)
+ps:   $(PS)
+html: $(HTML)
 
 clean:
-       rm -f *~ *.log *.ind *.l2h *.aux *.toc *.how
-       rm -f *.dvi *.ps *.pdf *.bkm
-       rm -f unicode.html
+       rm -f *~ *.log *.ind *.l2h *.aux *.toc *.how *.bkm
+       rm -f *.dvi *.pdf *.ps
 
 clobber:
-       rm dvi/* ps/* pdf/* txt/* html/*
-
-
-
+       rm -rf $(HTML)
+       rm -rf $(DVI) $(PDF) $(PS)