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.
Writings, books on DocBook
- DocBook v5.0: The Definitive Guide
- DocBook XSL: The Complete Guide
- Dave Pawson's DocBook site, may be slightly out-of-date
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.
At bare minimum, your source file will look like so:
<?xml version="1.0" encoding="UTF-8"?> <article xmlns="http://docbook.org/ns/docbook" xmlns:xl="http://www.w3.org/1999/xlink" version="5.0"> <info> <title>Importing and Exporting Data with OJS</title> <author> <orgname>The Public Knowledge Project</orgname> <address> <city>Burnaby</city> <street>8888 University Drive</street> <postcode>V5A 1S6</postcode> <country>Canada</country> </address> <email>firstname.lastname@example.org</email> </author> </info> <sect1 xml:id="preface"><info><title>Preface</title></info> <para>...</para> </sect1> </article>
Writing a Book
Info will come as I convert the OxS in an Hour docs as well as the Technical Reference. But mostly it's about using the following as your root element/namespace identifier:
<?xml version="1.0" encoding="UTF-8"?> <book xmlns="http://docbook.org/ns/docbook" xmlns:xl="http://www.w3.org/1999/xlink" version="5.0">
Common DocBook Elements You Should be Using
You can find a list of all elements for DocBook 5.0 here.
- Use <filename>/plugins/importExport/native/native.dtd</filename> when you are referring to file names and locations.
- Use <command>php importExport.php</command> when you reference commands.
- Use <userinput>User Home</userinput> for referencing ... user ... input.
<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.
- 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
- DocBook XSL Stylesheets
- XSLT Processor
- XSL-FO Processor
To install most of what you need 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, but I'll reference that location below. You can also download them separately if you're not running Ubuntu from here.
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.
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.