Text Colophon

The text is being authored in DocBook, using TextPad on Windows XP. The text is validated with xmllint, converted to a formatted output (fo) file by xlstproc, and then rendered as a PDF using Apache FOP. All three steps (validation, preprocessing, and rendering) are run from TextPad from the Tools menu.

• Validate -xmllint --postvalid --noout --xinclude book.dbk.xml
• Format chapter - xsltproc --output book.fo --xinclude --stringparam fox.extensions 1 fo-docbook.xsl $File
• Format book -xsltproc --output book.fo --xinclude --stringparam fox.extensions 1 fo-book.xsl $File
• Render PDF - fop.bat -fo book.fo -pdf book.pdf

All of the text source, including the templates, are kept under Subversion. The text is committed to repository as soon as it is written. Nothing is held back longer than a few hours.

How the textbook is made

• Create DocBook text using TextPad 4
• sdoc clip library
• docbook syn

• Name files .dbk.xml to identify as docbook files
• Configure TextPad to apply syntax to .dbk.xml
• Add tools to call xlstproc and fop

• Render to HTML/PDF/PS using xlstproc and fop

• Submit PS to LuLu for typesetting (when the time comes)

Chapter draft mode

While a chapter is being written or revised, it can be convenient to add an enclosing <book> tag. In this way, the chapter can be validated as a complete book. When the draft is complete, change the <book> tags into comments (<!-- book -->), so that the chapter can be included by the master "book" file.

Style Guide

Content and markup conventions

• Don't abut sections to one another. Include some intervening text.
• Try to separate text from markup by putting block tags on separate lines.
• Do abut markup and try to keep block tags on adjoining lines.
• Cite URIs as footnotes.

TextPad

• Configuration
• Maintain indention
• Strip trailing spaces from lines when saved
• Save with no breaks line in lines
• Wrap lines at column 78

Before committing

• Turn Word-Wrap On (Ctrl+Q,W)
• Split wrapped lines on selection or file
• DO NOT REFORMAT (Ctrl+Shift_J) the entire file, as that will wrap markup too! Select a block within the markup first.

Installing under Windows

Unzip sq1-docbooktools.zip to create or extend etc, opt, and usr folders on C:\

• c:\etc\xml\catalog.xml
• c:\opt\Apache\fop-0.93
• c:\usr\share\xml\docbook-xml-4.5, docbook-xsl-1.72.0

Set Environment Variables

FOP_HOME = C:\opt\Apache\fop-0.93 LIBXML_BIN=C:\opt\libxml\bin

PATH= ... ;%FOP_HOME%;%LIBXML_BIN%

FP_NO_HOST_CHECK = NO XML_CATALOG = c:\etc\xml\catalog.xml

In TextPad, setup DocBook utilities

DocBook Validate 
xmllint --postvalid --noout --xinclude $File
$FileDir

DocBook format chapter
xsltproc --output book.fo --xinclude --stringparam fox.extensions 1 fo-docbook.xsl $File
$FileDir

DocBook format book 
xsltproc --output book.fo --xinclude --stringparam fox.extensions 1 fo-book.xsl $File
$FileDir

DocBook render PDF 
fop.bat -fo book.fo -pdf book.pdf
$FileDir

DocBook Single HTML File
C:\opt\libxml\bin\xsltproc.exe
--nonet --xinclude --stringparam fox.extensions 1 docbook.xsl $File > $File.html
$FileDir