Docbook SGML Quick Start

Docbook SGML Quick Start
Jim Weller
jim atat jimweller dot net
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.
Table of Contents
1. Legal Notice	000
2. Introduction	000
3. Requirements	000
3.1. Basics	000
3.2. OpenJade	000
3.3. DocBook DTD	000
3.4. ISO8879 Entities	000
3.5. DocBook Style Sheets	000
4. Installation and Configuration	000
4.1. Ground work	000
4.2. OpenJade	000
4.3. DocBook DTDs and Entities	000
4.4. Norm Walsh's and LDP's Style Sheets	000
4.5. Configuration	000
5. Using the Tools	000
5.1. A Simple docbook sgml document	000
5.2. Generating HTML and RTF	000
6. References	000

1. Legal Notice
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License (http://www.fsf.org/copyleft/fdl.html), Version 1.1 or any later version published by the Free Software Foundation with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. You may obtain a copy of the GNU Free Documentation License from the Free Software Foundation by visiting their Web site (http://www.fsf.org/) or by writing to: Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
This manual contains short example programs (“the Software”). Permission is hereby granted, free of charge, to any person obtaining a copy of the Software, to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following condition:
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
2. 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.
3. 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.
3.1. 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.
3.2. 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. 
3.3. 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).
 
3.4. 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 (http://www.oasis-open.org/cover/topics.html#entities) site. If you understand all that, you probably don't need this guide ;-)
3.5. 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.
 
4. 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
4.1. Ground work
 First setup some handy environmental variables. 
export DBARCHIVE=/where/you/put/your/downloads
export SGMLHOME=/where/you/want/to/install/everything
      
4.2. 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
    
4.3. 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
    
4.4. 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/

4.5. 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
      
5. 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 (http://docbook.org/tdg/en/html/docbook.html) for complete information on writing DocBook markup.
5.1. 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 (sample/test.sgml) [text (sample/test.sgml.txt)]

<!DOCTYPE book PUBLIC "-//OASIS//DTD docbook sgml V4.2//EN" 
                         "http://www.oasis-open.org/docbook/sgml/4.2/docbook.dtd" 
[
 <!ENTITY version "0.01">
]>

<!-- 
Comments just like html
-->

<book>

  <bookinfo>
    <title>Simple XML Sample</title>
    <author>
      <firstname>John</firstname>
      <surname>Doe</surname>
    </author>
    <copyright><year>2002</year><holder>John Doe</holder></copyright>
    <legalnotice>
      <para>This legal mumbo jumbo will stop evil.</para>
    </legalnotice>
    <abstract>
      <para>This is Simple XML Sample version &version;. It is good for nothing but processing.</para>
    </abstract>
  </bookinfo>

  <chapter>
    <title>About this book</title> 
    <para>
      This book was not hard.
    </para>
    
    <section>
    <title>Copyrights and Trademarks</title>
    <para>Copyright &copy; 2002 John Doe</para>
    </section>

    <section><title>Purpose/Scope</title> 
    <para>This guide is tightly scoped with one purpose; to process.</para>
    </section>
  </chapter>

  <appendix><title>References</title>
    <para>Some Hoity Toity Person</para>
  </appendix>

</book>

5.2. 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 (sample/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 (sample/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. 
6. References
I glommed all this together from mailing lists and documents listed below.
•	Linux Documentation Project (http://www.tldp.org/)
•	Godoy's Docbook Page (http://docbook.godoy.homeip.net:81/)
•	DocBook Install mini-HOWTO (http://www.linuxdoc.org/HOWTO/mini/DocBook-Install/)
•	DocBook: The Definitive Guide by Norman Walsh (http://docbook.org/tdg/en/html/docbook.html)
•	Setup Instructions For A Coherent SGML/DocBook Environment (http://adl.opengroup.org/exgr/papers/sgml_setup.html)
•	Standard Deviations from Norm: If You Can Name It, You Can Claim It! (Norm Walsh article) (http://www.oasis-open.org/cover/walshSystemsIDsNewURL.html)
•	A gentle guide to DocBook (IBM article) (http://www-106.ibm.com/developerworks/library/l-docbk.html?dwzone=linux)
•	Making PDF documents with DocBook (An incredibly helpful article) (http://linuxfocus.saneg.itu.edu.tr/English/May2000/article152.shtml)
•	OpenJade home (http://openjade.sourceforge.net)
•	DocBook Technical Commitee (http://www.oasis-open.org/docbook/)
•	DocBook Home at Sourceforge (http://docbook.sourceforge.net)
•	Jim Weller's sleepless notes (http://www.jimweller.net) 
•	Title Bout: Jim v. Doctools (http://www.jimweller.net/article.php?sid=26)
•	Using Doctools sgml (http://www.jimweller.net/article.php?sid=27)