You should now have a set of HTML files, an FO file that you can pitch, and a PDF file.

You should now have a set of HTML files, an FO file that you can pitch, and a PDF file.

+

+

I've created a PKP-specific customization layer that works around some of the more common PDF transformation issues, available [http://deadcancon.org/docbook/pkpfo.xsl here]. You'll have to add it to the fo stylesheet directory, as it references docbook.xsl, and then point xsltproc to it instead of docbook.xsl. This customization layer is still under development.

Writing Docbook Documentation for the PKP

This document is currently extremely incomplete, and undergoing revisions as I switch from DocBook4.5 to 5.0.

Creating a Docbook XML sourcefile is mainly a matter of identifying what kind of document you are working on, what kinds of tags you should be using to describe your document. This meta-document details the steps I use to create book- and article-level source documentation for the Public Knowledge Project. It will also describe the steps I take to transform XML source files to HTML and PDF.

XML Editors

Validators

Writing an Article

First, choose whether you are writing a book or an article. This identifies the root element you'll start with: <book> or <article>. For the rest of this document, we'll assume we're writing an article.

<para>To import a file, you can use
<userinput><embed></userinput> to place a file directly
within your XML document, or use
<userinput><href></userinput> to link to one.</para>

Use <![CDATA[[<p>all this text up in here</p>]]> for tags that should be ignored. This example would tell the parser to ignore those

tags. (Let me know if you come up with a clever way to ignore <![CDATA[]]> itself.)

Use <element xl:href="http://pkp.sfu.ca">Public Knowledge Project</element> to hyperlink to an external page. "element" can be any inline element. You can also use "link" as a generic element I think.

Use <element linkend="sectionId">link text</element> for linking within the document itself. "element" can be any inline element. You can also use "link" as a generic element I think.

Block Elements

Use <programlisting>/multiple lines of code/</programlisting> for large, multiline code blocks.

Use <tip><para>this is a tip</para></tip> for notes, suggestions, tips, etc.

Transforming DocBook into Other Formats

DocBook XSL: The Complete Guide has a very good chapter on setting up all the tools you'll need to transform DocBook XML into HTML and PDF. You can download OS/platform-specific packages here, or at a minimum you can make sure you have the following installed:

DocBook DTD (you can always point to an online DTD, of course)

DocBook XSL Stylesheets

XSLT Processor (to transform to HTML and FO)

XSL-FO Processor (to transform from FO to PDF)

Installing this stuff on Ubuntu

I'm currently handling all of my transformations on Ubuntu using xsltproc for HTML and FO, and FOP for FO->PDF. The following instructions will assume you are using the same tools in the same general environment.

To install the first three items in Ubuntu, install the following packages through apt-get or Synaptic: docbook-xml (installs the DTD), docbook-xsl (the stylesheets), xsltproc (the tool to transform to HTML and FO). Ubuntu installs the stylesheets to /usr/share/xml/docbook/stylesheet/nwalsh/. You can put them anywhere you want because you'll just be pointing to particular ones with xsltproc, but I'll reference that location below. You can also download them separately if you're not running Ubuntu from here.

You can't use Synaptic or apt-get to install FOP on Ubuntu, but the DocBook XSL guide has a page on installing it here. I had some minor difficulty in getting it to work, but if memory serves that was a Java problem that got fixed by paying attention to the guide.

DocBook to HTML

If you have a valid DocBook XML file by the name of example.xml, you should now be able to run the command

I've created a PKP-specific customization layer that adds header image links and a link to the PKP documentation stylesheet, available here. You'll have to add it to the xhtml stylesheet directory, as it references chunk.xsl, and then point xsltproc to it instead of chunk.xsl. This customization layer is still under development.

PDF

This command has xsltproc take example.xml and transform it to example.fo. Using FOP, you can then transform example.fo to example.pdf:

/path/to/fop -fo myfile.fo myfile.pdf

You should now have a set of HTML files, an FO file that you can pitch, and a PDF file.

I've created a PKP-specific customization layer that works around some of the more common PDF transformation issues, available here. You'll have to add it to the fo stylesheet directory, as it references docbook.xsl, and then point xsltproc to it instead of docbook.xsl. This customization layer is still under development.