Legal Notice

Docbook SGML Quick Start Docbook SGML 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 docbook sgml 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 sgml tools. It assumes a fair knowledge of building and installing source packages. &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 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. 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 linux. You can use another OS, but you'll have to interpolate as necessary.

OpenJade OpenJade http://openjade.sourceforge.net You'll need to download a recent version of the openjade suite. OpenJade is a program implementing the ISO/IEC 10179:1996 standard DSSSL language.

DocBook DTD sgml 4.2 http://www.oasis-open.org/docbook/sgml/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).

ISO8879 Entities ISOEnts.zip http://www.oasis-open.org/cover/ISOEnts.zip You'll need to get ISOEnts.zip. These are all the symbol entities (e.g. ©,® and lots more). You can read about these at the SGML/sgml Entity Sets and Entity Management site. If you understand all that, you probably don't need this guide ;-)

DocBook Style Sheets DocBook DSSSL Stylesheetshttp://docbook.sourceforge.net/projects/dsssl/ The LDP Customized Stylesheet http://tldp.org/authors/tools/ldp.dsl 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:

DSSSL is a stylesheet language for both print and online rendering. The acronym stands for Document Style Semantics and Specification Language. It is defined by ISO/IEC 10179:1996.

Installation and Configuration Setting up the tools was the hard the first time. The maze of catalogs, programs and acronyms is daunting to the first time (even technically minded) user. I couldn't tell what I needed. Never mind the miles of error message these tools generate by default. But this method is quick and painless

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 to your library search path ($LD_LIBRARY_PATH or ld.so.conf on Linux). Also be sure to add openjade's bin directory to your PATH. Note that you have to manually copy the dsssl subdirectory as openjade's install doesn't do it for you. cd /where/you/compile/source 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

DocBook DTDs and Entities Next, you'll need to unpack all the DocTools DTDs and entities. The entities should be renamed to end in '.gml' . You can rename them by hand or try my one line bash script. cd $SGMLHOME mkdir dtd cd dtd unzip -a $DBARCHIVE/docbook-sgml-4.2.zip 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. 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 Finally, we need to setup our SGML_CATALOG_FILES evironment variable. This variable is a colon seperated list of files that openjade will use to find 'stuff'. Once you get it set and working, I recommend making this a permanent fixture in your environment (.bash_profile,.profile, etc.). export SGML_CATALOG_FILES=$SGMLHOME/openjade-1.3.1/dsssl/catalog:$SGMLHOME/dtd/docbook.cat

Using the Tools This is a terse introduction to using the DocBook tools to compile sgml 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 docbook sgml document Below is an example of a very simple docbook sgml document; a book. Copy it into a text file and we'll compile it into HTML and RTF in a minute. test.sgml [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.sgml into linux doc project style HTML. openjade -t sgml -d $SGMLHOME/dsssl/html/ldp.dsl#html test.sgml After, processing you should have the following (or similar) in the folder with test.sgml. Look at index.html in a web browser. a23.html index.html test.sgml x20.html c14.html ln10.html x17.html Try compiling RTF using the following. Examine test.rtf in your word processor. openjade -t rtf -d $SGMLHOME/dsssl/docbook/print/ldp.dsl#print test.sgml Here's a description of the command line switces: -t the backend to use (fot|rtf|tex|mif|sgml|xml) -d the style sheet to use 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 sgml