A minimal DocBook setup on Unix

using docbook-xml-4.2 and xsltproc

Simon Strandgaard


Table of Contents

About this document
Install
Installing xsltproc
Installing DTD+stylesheet
A Skeleton Project
Makefile
catalog.xml
main.xml
Setup
XML_CATALOG_FILES
Adjusting the Skeleton
Validate that things works
Trobleshooting
Failed to load external entity "xhtml_onechunk"
Failed to load external entity "http://.../docbookx.dtd"

About this document

DocBook can output to a wide range of formats, by only focusing on XHTML I hope to spare you for much confusion.

Install

Little is necessary, thus it should take 15 minutes max to complete installation.

Installing xsltproc

There exists many DocBook™ applications, which can output many more formats than what xsltproc is capable of. But in this text we will only focus on using xsltproc.

xsltproc is the application which takes your docbook files as input and outputs xhtml.

Installing DTD+stylesheet

place your downloaded files in the ~/docbook/ directory:

shell% mkdir ~/docbook
shell% cd ~/docbook
shell% 

Table 1. Download these files

docbook-xml-4.2.zip (78428 bytes)DTD
docbook-xsl-1.61.3.tar.gz (1267005 bytes)Stylesheet

Your ~/docbook/ should contain this:

shell% cd ~/docbook
shell% ls -la
-rw-r--r--  1 neoneye  neoneye    78428 22 Aug 11:49 docbook-xml-4.2.zip
-rw-r--r--  1 neoneye  neoneye  1267005 22 Aug 11:51 docbook-xsl-1.61.3.tar.gz
shell%

Extract docbook-xml-4.2.zip into ~/docbook/xml/

shell% cd ~/docbook
shell% mkdir xml
shell% cp docbook-xml-4.2.zip xml/.
shell% unzip xml/docbook-xml-4.2.zip

Extract docbook-xsl-1.61.3.tar.gz into ~/docbook/xsl/

shell% cd ~/docbook
shell% tar xzvf docbook-xsl-1.61.3.tar.gz
shell% mv docbook-xsl-1.61.3 xsl

Validate that you extracted things correct.

shell% cd ~/docbook
shell% ls xml/docbookx.dtd
xml/docbookx.dtd
shell% ls xsl/xhtml/docbook.xsl
xsl/xhtml/docbook.xsl
shell% 

Installation is successfully completed.

A Skeleton Project

Place these 3 files in the same directory.

Makefile

onechunk:
	xsltproc \
	--output index.html \
	xhtml_onechunk \
	main.xml

chunks:
	xsltproc \
	--output index.html \
	xhtml_chunks \
	main.xml

catalog:
	xmllint --valid --noout catalog.xml

main:
	xmllint --valid --noout main.xml

catalog.xml

<?xml version="1.0"?>
<!DOCTYPE catalog
   PUBLIC "-//OASIS/DTD Entity Resolution XML Catalog V1.0//EN"
   "http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd">
<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">
  <rewriteSystem
    systemIdStartString="http://www.oasis-open.org/docbook/xml/4.2/"
    rewritePrefix="file:///home/neoneye/docbook/xml/" />
  <group  prefer="public"  xml:base="file:///home/neoneye/docbook/xsl/" >  
    <rewriteURI
      uriStartString="http://docbook.sourceforge.net/release/xsl/current/"
      rewritePrefix="" />
    <uri
      name="xhtml_onechunk"
      uri="xhtml/docbook.xsl" />
    <uri
      name="xhtml_chunks"
      uri="xhtml/chunk.xsl" />
  </group>
</catalog>

main.xml

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
	"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<article>
<section><title>Title</title>
<para>placeholder</para>
</section>
</article>

Setup

placeholder.

XML_CATALOG_FILES

To tells xsltproc that it should look for a catalog.xml in current directory. Your should add this line to your .tcshrc config-file:

setenv XML_CATALOG_FILES catalog.xml 

Leaving it out, then xsltproc will use the /etc/xml/catalog as its catalogfile.

Validate that the environment variable is set correct.

shell% env | grep XML_CATALOG_FILES
XML_CATALOG_FILES=catalog.xml
shell%

Adjusting the Skeleton

The file catalog.xml is specialized to my machine, pointing to things in my homedir. Just change the name of my homedir (neoneye) into your own.

"file:///home/neoneye/docbook/xml/"
"file:///home/neoneye/docbook/xsl/"

Validate that things works

Lets go for the big, and see if everything works. Type make (on my pentium350 it takes about 9 seconds)

shell% make
xsltproc \
--output index.html \
xhtml_onechunk \
main.xml
shell%

If you got no errors nor warnings, then a index.html file has been outputted.

Trobleshooting

What if things doesn't work? If none of these hints can help you, then you are welcome to mail me and I will look into your problem.

Failed to load external entity "xhtml_onechunk"

shell% make
xsltproc \
--output index.html \
xhtml_onechunk \
main.xml
warning: failed to load external entity "xhtml_onechunk"
cannot parse xhtml_onechunk
make: *** [onechunk] Error 4
shell%

We got an errorcode 4 from xsltproc. The man-page says 4: failed to parse the stylesheet.

  • Make sure that the XML_CATALOG_FILES environment variable is setup correct.

    shell% env | grep XML_CATALOG_FILES
    XML_CATALOG_FILES=catalog.xml
    shell%
    

  • Make sure that the catalog.xml is valid xml.

    shell% make catalog
    xmllint --valid --noout catalog.xml
    shell%
    

    If no output, then its valid xml.

  • In catalog.xml, Make sure that the the stylesheet path points correct into your homedir (/home/myhomedir/docbook/xsl/).

If it still doesn't work you are welcome mail me.

Failed to load external entity "http://.../docbookx.dtd"

shell% make
xsltproc \
--output index.html \
xhtml_onechunk \
main.xml
main.xml:11: warning: failed to load external entity "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
]>
 ^
shell%

No error code, apparently this went well.

  • In catalog.xml, Make sure that the the DTD path points correct into your homedir (/home/myhomedir/docbook/xml/).

If it still doesn't work you are welcome mail me.