Writing documentation with DocBook-XML 4.3

This example Makefile implements the literate programming technique described in Lightweight literate programming. The basic idea is that rather than trying to embed documentation in your program, instead you embed the source code for your program within a DocBook document.

You will need to install litlxml, which is described (in literate form, of course) in A source extractor for lightweight literate programming.

The beginning section is similar to Section 19.1, “make-basic: A basic Makefile”.

# Makefile for DocBook projects: Literate version
#   This file is extracted automatically from:
#     http://www.nmt.edu/tcc/help/pubs/docbook43/
#================================================================
# Definitions
#----------------------------------------------------------------
# BASENAME:        The base file name of the DocBook file.
# SOURCE:          The .xml file containing the document.
# WEB_TARGET:      Top-level generated HTML page name.
# FO_TARGET:       Intermediate file for generated PDF.
# PDF_TARGET:      Generated PDF file name.
# INDEX_BASE:      Base name for index of section id values.
# INDEX_FO:        Intermediate file for section index.
# INDEX_PDF:       Section index PDF file name.
# TCC_XSL:         Where the local customization layer lives.
# HTML_TRANSFORM:  XSLT to build the HTML rendering.
# PDF_TRANSFORM:   XSLT to build the PDF rendering.
# XSLT_HTML_OPT passes options to xsltproc to build the HTML form.
#     To push chunking down to subsections:
#        --stringparam chunk.section.depth 2 
#     To move the first subsection to its own chunk:
#        --stringparam chunk.first.sections 1
#     To show subsubsections in the table of contents:
#        --stringparam toc.section.depth 3
# XSLT_FO_OPT:  Options for hardcopy.
#     To show subsubsections in the table of contents:
#        --stringparam toc.section.depth 3
# XEP_OPT:  Options to xep
#     To suppress most output:
#        -quiet
#----------------------------------------------------------------
BASENAME        =  your-project-name-here
SOURCE          =  $(BASENAME).xml
WEB_TARGET      =  $(WEB_DIR)index.html
FO_TARGET       =  $(BASENAME).fo
PDF_TARGET      =  $(BASENAME).pdf
INDEX_BASE      =  toc
INDEX_FO        =  $(INDEX_BASE).fo
INDEX_PDF       =  $(INDEX_BASE).pdf
TCC_XSL         =  /u/www/docs/tcc/doc/docbook43/
HTML_TRANSFORM  =  $(TCC_XSL)lit_html.xsl
FO_TRANSFORM    =  $(TCC_XSL)lit_fo.xsl
XSLT_HTML_OPT   =  --stringparam chunk.section.depth 2 \
                   --stringparam chunk.first.sections 1
XSLT_FO_OPT     =  
XEP_OPT         =  -quiet

In the EXECUTABLES define, enumerate any files that are to be extracted and then made executable (we are assuming a Unix-based system here). Additionally, if there are any files that are to be extracted but do not need to be made executable, enumerate them in the MODULES define.

#----------------------------------------------------------------
# EXECUTABLES:  Files to be extracted and then made executable.
# MODULES:      Files to be extracted from the DocBook source.
#----------------------------------------------------------------
MODULES         =
EXECUTABLES     =
CODE_TARGETS    =  $(MODULES) $(EXECUTABLES)

The next section is the same as in make-basic.

#--
# Add the suffixes that we are interested in
#--
# .fo       XSL-FO output
# .html     HTML web pages                 
# .pdf      Page Description Format (Abode)
# .xml      Input files in DocBook XML format
#--
.SUFFIXES: .fo .html .pdf .xml

#================================================================
# Default suffix rules
#----------------------------------------------------------------
.xml.html:
	xsltproc -o $@ $(XSLT_HTML_OPT) $(HTML_TRANSFORM) $<

.xml.fo:
	xsltproc -o $@ $(XSLT_FO_OPT) $(FO_TRANSFORM) $<

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

In the target section, we define a new target named code. The rule for this target runs litlxml. We also define a target named index that runs docbookindex to build a toc.pdf file enumerating all the section ID values.

#================================================================
# Targets
#----------------------------------------------------------------
all: web pdf index code

web: $(WEB_TARGET)

$(WEB_TARGET): $(SOURCE)
	xsltproc -o $@ $(XSLT_HTML_OPT) $(HTML_TRANSFORM) $<

pdf: $(PDF_TARGET)

$(PDF_TARGET): $(SOURCE)

index: $(INDEX_PDF)

$(INDEX_PDF): $(INDEX_FO)

$(INDEX_FO): $(SOURCE)
	rm -f $(INDEX_FO); \
	docbookindex $(SOURCE)

code: $(CODE_TARGETS)

#--
# If there are any executables, change this rule to:
#   $(CODE_TARGETS): $(SOURCE)
#       litxlml $<; \
#       chmod +x $(EXECUTABLES)
#--
$(CODE_TARGETS): $(SOURCE)
	litlxml $<

clean:
	rm -f *.fo *.html *.pdf $(CODE_TARGETS)