A minimal DocBook setup on Unix

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.