# DocBook

From ArchWiki
Jump to navigation Jump to search
The printable version is no longer supported and may have rendering errors. Please update your browser bookmarks and please use the default browser print function instead.

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 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.

## Tips and tricks

### Comments

Comments are somewhat problematic within an xml file. One possibility is to use a non-existing processing-instruction, e.g.:

    <?ignore
    comment line 1: can be a valid xml line
    comment line 2: can be a valid xml line
    ?>

More details at https://stackoverflow.com/a/14650451.

## See also

- https://www.w3schools.com/xml/

Category:

- File formats

Hidden category:

- Pages or sections flagged with Template:Expansion