Docbook

Tango-document-new.png

Tango-document-new.png

This article is a stub.

Notes: please use the first argument of the template to provide more detailed indications. (Discuss)

We will assume that our docbook document is in File.xml

Setting up Docbook in Arch

To set up docbook running on arch:

$ pacman -S docbook-xml docbook-xsl libxslt libxml2

Validating XML file

To validate the XML file use:

$ xmllint --valid --noout File.xml

This will generate no output if the file is proper XML.

Converting into XHTML

Single file

To convert into a XHTML file (single file) use:

xsltproc /usr/share/xml/docbook/`pacman -Q docbook-xsl | cut -d ' ' -f 2 | cut -d '-' -f 1`/xhtml/docbook.xsl File.xml > Output.html

Segmented

To convert into a a segmented XHTML file (each section in its own file) use:

xsltproc /usr/share/xml/docbook/`pacman -Q docbook-xsl | cut -d ' ' -f 2 | cut -d '-' -f 1`/xhtml/chunk.xsl File.xml

Automating

You can add these to ~/.bashrc(or similar shell startup file):

alias doc2html1="xsltproc /usr/share/xml/docbook/xhtml/docbook.xsl"
alias doc2multihtml="xsltproc /usr/share/xml/docbook/xhtml/chunk.xsl"
alias docvalidate="xmllint --valid --noout"

Troubleshooting

Compilation errors

If you have already installed the packages above, but begin to see compilation errors such as:

GEN    appdata-validate.1
I/O errorĀ : Attempt to load network entity http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl
warning: failed to load external entity "http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl"
cannot parse http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl

Then reinstall docbook-xml and docbook-xsl. If something has corrupted the catalog file, this will run xmlcatalog and rebuild /etc/xml/catalog, which may resolve these compile errors.