Writing documentation with DocBook-XML 4.3

If you are using a Makefile as described in Section 3.2, “The DocBook workflow cycle”, you can add rules to it that automate the procedure described in Section 12.3, “Processing your math files for inclusion”.

Here is an annotated Makefile for this example file, illustrating how to automate the procedures for converting TeX equations to the forms needed by DocBook.

First, we define a few variables. TARGET is the base name of the document and its product files. SOURCE is the document's XML source file. In this example, the DocBook source file is example.xml.

TARGET          =  example
SOURCE          =  $(TARGET).xml

The next lines are a part of the stock TCC DocBook Makefile template, defining the path to the style sheets, and options for the HTML and PDF conversion routes.

TCC_XSL         =  /u/www/docs/tcc/doc/docbook43
XSLT_HTML_OPT   =  
XSLT_FO_OPT     =  
XEP_OPT         =  -quiet

The variable EQUATIONS enumerates the individual TeX source files for each displayed equation. The variables PDF_EQUATIONS and JPG_EQUATIONS are the names of the product files required by DocBook for print and Web, respectively. In this example, there are three equations, residing in files eq1.tex, eq2.tex, and eq3.tex.

EQUATIONS       =  eq1.tex eq2.tex eq3.tex
PDF_EQUATIONS   =  ${EQUATIONS:.tex=.pdf}
JPG_EQUATIONS   =  ${EQUATIONS:.tex=.jpg}

The make application won't work properly unless the .SUFFIXES variable is set to a list of all the file name suffixes used in its rules.

.SUFFIXES: .xml .html .fo .ps .eps .pdf .tex .dvi .pgm .jpg

The next section is the suffix rules used to convert one file format into another. The first three are the normal rules for building HTML and PDF, from the TCC's stock DocBook Makefile.

.xml.html:
     xsltproc -o $@ $(XSLT_HTML_OPT) $(TCC_XSL)/tcc_html.xsl $<

.xml.fo:
     xsltproc -o $@ $(XSLT_FO_OPT) $(TCC_XSL)/tcc_fo.xsl $<

.fo.pdf:
     xep $(XEP_OPT) $< $@ 

The next sequence of rules exactly reflects the steps described in the procedure above for converting the LaTeX source files to PDF and JPG form.

.tex.dvi:
     latex $<

.dvi.eps:
     dvips -E $< -o $*.eps

.eps.pdf:
     epstopdf $<

.pdf.pgm:
     pdftoppm -gray $< $*; \
     mv $*-000001.pgm $*.pgm

.pgm.jpg:
     pnmtojpeg $< >$@

If you are using TeX instead of LaTeX, change the first rule above to:

.tex.dvi:
     tex $<

The first, and therefore default, make target is all. It depends on web, which builds the Web side, and pdf, which builds the PDF. These first rules are from the stock Makefile, except that we note that the HTML route depends on the JPG forms of the equations, and the PDF route depends on the Encapsulated PDF equations.

all: web pdf

web: $(TARGET).html

$(TARGET).html: $(SOURCE) $(JPG_EQUATIONS)

pdf: $(TARGET).pdf $(PDF_EQUATIONS)

$(TARGET).pdf: $(SOURCE) $(PDF_EQUATIONS)

Finally, the clean target removes the HTML and PDF product files, as well as the included equations.

clean:
     rm -f $(TARGET).fo $(TARGET).pdf *.html $(JPG_EQUATIONS) $(PDF_EQUATIONS)