Legal Notice

Docbook XML Quick Start Docbook XML Quick Start 2002-11-27 Jim Weller

jim atat jimweller dot net

2001-2002 Jim Weller Describes how to install, configure and use the tools and resources for dcobook XML and dsssl. The purpose of this quick start guide is to get new docbook authors, editors, and contributors up and running fast with the DoocBook tools. It assumes a fair knowledge of building and installing source packages. <<<<<<< dbxmlqs.xml &legal.notice; 0.9.0 2001-11-20 Fixed openjade install note that I forgot to mention. 0.8.2 2001-9-16 Proof reading and organization. 0.8.0 2001-9-15 Major changes to the source tree. Aded system id to xml documents. Added change to DocBook SGML 4.1 catalog that eliminated repeated DTDDECL error. Modified my personal catalog to map the SYSTEM id onto a local copy of the DTD. 0.5.0 2001-5-29 First revision and rewrite in DocBook XML 0.1.0 2001-04-12 First Writing in HTML ======= >>>>>>> 1.12 &legal.section;

Introduction DocBook is a widely used DTD in SGML and XML that is tailored toward technical manuals. It's basically a way that authors can write a document once in markup and then, using processing tools, convert to many common formats (HTML, DOC, RTF, PDF, PostScript etc.). It is used on many projects as the main documentation system. I'm working on a HOWTO/book. These are my notes from my bout with these tools and concepts. I had a difficult and frustrating time setting up these tools at first. Plus, I couldn't find this document's a working equivalent. So, I truly hope this information will be helpful, but it is provided without warranty or gaurantee. If you break anything you get to keep both pieces. This guide tends toward brevity. I assume authors don't need to get mired in a gajillion layers of DocBook complexity just to generate an articulate piece of work. More simply: Get tools, write content and distribute. Please, note that I do not cover the installation or usage of some of the 'fluffy' tools like docbook2X or sgml-tools. Nor do I make mention of backends other than html and text. I leave it as an exercise for the reader to generate different types of output (tex, pdf, etc.). This document is intended to be a short path to writing and evaluating your documents.

Requirements You'll have to download and install a number of packages. Most won't take much to install, but you should be familiar with installing GNU source packages.

Basics You'll need a computer with the GNU development environment :) I used MacOS X. You can use another OS, but you'll have to interpolate as necessary.

libxml2 libxml2 http://xmlsoft.org/downloads.html You'll need to download the libxml2 package to compile. Libxml2 implements a number of xml standards.

libxslt libxslt http://xmlsoft.org/XSLT/downloads.html You'll need to download the libxslt package to compile. Libxslt xslt; an xml language to define transformations of xml.

DocBook DTD XML 4.2 http://www.oasis-open.org/docbook/xml/4.2/index.shtml You'll need to get the zip archive from the site listed above. DTD stands for Document Type Definition. This from Oasis:

DocBook is a DTD maintained by the DocBook Technical Committee of OASIS. It is particularly well suited to books and papers about computer hardware and software (though it is by no means limited to these applications).

DocBook Style Sheets DocBook XSL Stylesheetshttp://docbook.sourceforge.net/projects/xsl/ LDP XSL Stylesheet http://tldp.org/authors/tools/ldp-xsl.zip You'll need to download the nwalsh style sheets. You can get by with just that, but the LDP ones have some nice extensions. From Norman Walsh's docbook site.

Installation and Configuration Setting up the tools was the hardest part for me. The maze of catalogs, programs and acronyms is daunting to the first time (even technically minded) user. Never mind the miles of error message these tools generate by default. I ran into a couple of snags with work arounds that I'll mention.

Ground work First setup some handy environmental variables. export DBARCHIVE=/where/you/put/your/downloads export SGMLHOME=/where/you/want/to/install/everything

OpenJade The only package that requires compiling is openjade. Openjade is a reasonable GNU autotools source build. Be sure to add openjade's lib directory <<<<<<< dbxmlqs.xml to your library search path (ld.so.conf on Linux). Also, note that you have to manually copy ======= to your library search path (ld.so.conf on Linux). Note that you have to manually copy >>>>>>> 1.12 the dsssl subdirectory as the install doesn't do it for you. cd /usr/src tar -xzf $DBARCHIVE/openjade-1.3.1.tar.gz cd openjade-1.3.1 ./configure --prefix=$SGMLHOME/openjade-1.3 --enable-http && make && make install cp -a dsssl $SGMLHOME/openjade-1.3.1 cd $SGMLHOME/openjade-1.3.1

DocBook DTDs and Entities Next, you'll need to unpack all the DocTools DTDs and entities. Some of the XML entities need to be replaced with SGML ones. You can rename by hand or try my one line script in bash. cd $SGMLHOME mkdir dtd cd dtd mkdir 4.2xml cd 4.2xml unzip -a $DBARCHIVE/docbook-xml-4.2.zip cd ent rm * unzip -a $DBARCHIVE/ISOEnts.zip for i in ISO*;do mv $i `echo $i | sed -e 's/ISO/iso-/g'`.gml;done

Norm Walsh's and LDP's Style Sheets Now, we're ready to unpack Norm Walsh's and the LDP's Styles Sheets. These are wonderfully straight forward. cd $SGMLHOME tar -xzf $DBARCHIVE/docbook-dsssl-1.77.tar.gz mv docbook-dsssl-1.77 dsssl cd dsssl cp $DBARCHIVE/ldp.dsl html/ cp $DBARCHIVE/ldp.dsl print/

Configuration Then, well need to setup our SGML_CATALOG_FILES evironment variable. This is a list of files that openjade will use to find 'stuff'. I consolidated them all down to one file shown below. Once you get it set and working, I recommend making this a permanent fixture in your environment (.profile,.bashrc, etc.). Then when you want to change from 4.2 to 3.1 to compile other HOWTOS you just edit 'your' main catalog file. export SGML_CATALOG_FILES=$SGMLHOME/openjade-1.3.1/dsssl/catalog:$SGMLHOME/dtd/4.2xml/docbook.cat Make sure that you add $SGMLHOME/openjade-1.3.1/bin to your path and that you update your environment so that the loader can find the libraries located in $SGMLHOME/openjade-1.3/lib. I edited /etc/profile and /etc/ld.so.conf; YMMV.

Using the Tools This is a terse introduction to using the DocBook tools to compile XML documents. I won't go into the details of DocBook mark up. See DocBook: The Definitive Guide for complete information on writing DocBook markup.

A Simple dcobook xml document Below is an example of a very simple dcobook xml document. Copy it into a text file and we'll compile it into HTML and RTF in a minute. text.xml [as text ] ]> Simple XML Sample John Doe 2002John Doe This legal mumbo jumbo will stop evil. This is Simple XML Sample version &version;. It is good for nothing but processing. About this book This book was not hard.

Purpose/Scope This guide is tightly scoped with one purpose; to process.

References Some Hoity Toity Person ]]>

Generating HTML and RTF You can see that DocBook markup is simple. Now let's compile this test.xml into some real LDP HOWTO style HTML. openjade -t xml -d $SGMLHOME/dsssl/docbook/html/ldp.dsl#html $SGMLHOME/dsssl/docbook/dtds/decls/xml.dcl test.xml You shouldn't get any error messages. After, processing you should have the following (or similar) in the folder with test.xml a23.html index.html test.xml x20.html c14.html ln10.html x17.html To compile an RTF try this openjade -t rtf -d $SGMLHOME/dsssl/docbook/print/ldp.dsl#print $SGMLHOME/dsssl/docbook/dtds/decls/xml.dcl test.xml Description of command line switces: -t backend to use (fot|rtf|tex|mif|sgml|xml) -d style sheet to use I've made my sample outputs available with this guide. Sample HTML output Sample RTF output That's all there is to it. Once you figure out TeX and RTF you can convert to other popular document formats with other tools. You might use TeX, LaTeX, PDF, PDB, or even some unmentioned proprietary formats and tools.

References I glommed all this together from mailing lists and documents listed below. Linux Documentation Project Godoy's Docbook Page DocBook Install mini-HOWTO DocBook: The Definitive Guide by Norman Walsh Setup Instructions For A Coherent SGML/DocBook Environment Standard Deviations from Norm: If You Can Name It, You Can Claim It! (Norm Walsh article) A gentle guide to DocBook (IBM article) Making PDF documents with DocBook (An incredibly helpful article) OpenJade home DocBook Technical Commitee DocBook Home at Sourceforge Jim Weller's sleepless notes Title Bout: Jim v. Doctools Using Doctools XML