# Docbook

This article or section needs expansion.

Reason: missing introduction (Discuss in Talk:Docbook#)

## Installation

Install docbook-xml and docbook-xsl.

## Validating XML file

To validate the XML file use:

    $ xmllint --valid --noout /path/to/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 /path/to/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 /path/to/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.

Category:

- Office

Hidden category:

- Pages or sections flagged with Template:Expansion