Getting Started with DocBook

Manual using jade/OpenJade

This is the quick and dirty way that should work for all distributions, no matter what distribution you're using.

1. Create a base directory to store everything such as /usr/local/sgml/. We'll call this $_toolroot from here on.

2. Install Jade, DocBook DTD, and DSSSL such that the base of each is under $_toolroot (creating $_toolroot/jade-1.2.1, $_toolroot/dtd, $_toolroot/dssl)

3. You'll need to set the SGML_CATALOG_FILES environment variable to the catalogs that you have under$_toolroot. You can do this with the command:bash$ export SGML_CATALOG_FILES = $_toolroot/dtd/docbook.cat:$_toolroot/dsssl/docbook/catalog:$_toolroot/jade-1.2.1/dsssl/catalog

4. Now you can start using Jade. To create individual HTML files:

   $_toolroot/jade-1.2.1/jade/jade -t sgml -i html -d $_toolroot/dsssl/docbook/html/docbook.dsl howto.sgml

5. To create one large HTML file, add -V nochunks to the jade command.

sgmltools

Unlike previous versions of sgmltools, you will require sgmltools version 2.x for use with DocBook. Since some major distributions ship with sgmltools 1.x, you'll need to remove the sgmltools 1.x package and install either a 2.0 version, or a CVS version. To get the latest CVS source code version, you can use the following set of commands:

bash$ CVSROOT=:pserver:cvs@cvs.sgmltools.org:/home/cvs
bash$ export CVSROOT
bash$ cvs login
bash$ cvs -z6 get sgmltools

The CVS password is 'cvs'. Once downloaded, You can just use

bash$ ./compile
bash$ make
bash# make install

to install sgmltools. For Red Hat-based systems (using RPM) you can use the rpmfind command to get the latest sgmltools. The rpmfind program is available at http://www.rpmfind.net/. Make sure you get sgmltools and not sgml-tools, as the latter is sgml-tools 1.0.9 and only works with LinuxDoc documents. For Debian-based systems, running 2.2 "Potato" and above, apt-get will retrieve the right package for you:

bash# apt-get install sgmltools-2   

As with Red Hat Linux, the sgml-tools package is outdated. Be sure to get sgmltools-2.

Cygnus DocBook Tools

These tools are provided with Red Hat 6.2. Make sure the following packages are installed:

• sgml-common

• docbook

• stylesheets

Red Hat has the latest version on their web site: http://www.redhat.com/support/errata/RHBA-2000022-01.html.

Download/get/sneakernet the RPMs to your machine and install in the usual manner (become root, then rpm -Uvh filename). Once the RPMs are installed, you can use the following commands to render DocBook:

bash$ db2html filename   

Renders DocBook into HTML. A subdirectory with the filename (minus the .sgml extension) is created and the HTML files are placed there.

bash$ db2pdf filename   

Renders DocBook into a PDF file.

New documents

You can easily start a new HOWTO using LyX. Use the File->New From Template... menu command to bring up the template listings. Select Templates on the right side of the screen, then select docbook_template.lyx in the file listing. Select OK, and you'll have a new document. Fill in the items, such as title, abstract, and author name, then start writing.

Existing documents

If you have an already-existing LyX, TeX, or text document, you can import it into LyX with the File->import command. Once the file is imported, go to Layout->Document... In the popup window, under Style, select SGML (DocBook Article). You'll be asked if you want to convert all text over, and say Yes. You will need to re-apply most tags, but it's a fairly simple matter of selecting text and changing the style. Many LyX functions have a keyboard shortcut to assist you.

Exporting documents to SGML

Once your document is written or converted, save it in LyX format. This will allow you to edit future versions easily. Then, go to File->Export->as DocBook... and the file will be exported in DocBook.

Introduction

If you have installed a recent distribution, you may already have PSGML installed for use with Emacs. To check, start Emacs and look for the PSGML documentation (C-himpsgml).

From here on, we assume you have PSGML installed for use with a recent version of GNU Emacs. If that all went by too fast for you, see the free chapter from Bob Ducharme's SGML CD book: http://www.snee.com/bob/sgmlfree/.

Updating your .emacs to use PSGML

If you want GNU Emacs to enter PSGML mode when you open a .sgml file and be ready for SGML editing, make sure PSGML can find the DocBook DTD. If your distribution already had PSGML set up for use with GNU Emacs, you probably do not have to do anything to get this to work. Otherwise, you may need to set an environment variable that tells PSGML where to look for the SGML catalog (the list of DTDs).

For example:

bash$ export SGML_CATALOG_FILES=/usr/lib/sgml/catalog

Then add something like the following to your .emacs file:

;; *******************************************************************
;; set up psgml mode...
;; use psgml-mode instead of emacs native sgml-mode
;;

(autoload 'sgml-mode "psgml" "Major mode to edit SGML files." t )
(setq auto-mode-alist
  (append
  (list
    '("\\.sgm$" . sgml-mode)
    '("\\.sgml$" . sgml-mode)
    )
  auto-mode-alist))

;; set some psgml variables

(setq sgml-auto-activate-dtd t)
(setq sgml-omittag-transparent t)
(setq sgml-balanced-tag-edit t)
(setq sgml-auto-insert-required-elements t)
(setq sgml-live-element-indicator t)
(setq sgml-indent-step nil)

;; create faces to assign to markup categories

(make-face 'sgml-comment-face)
(make-face 'sgml-start-tag-face)
(make-face 'sgml-end-tag-face)
(make-face 'sgml-entity-face)
(make-face 'sgml-doctype-face) ; DOCTYPE data
(make-face 'sgml-ignored-face) ; data ignored by PSGML
(make-face 'sgml-ms-start-face) ; marked sections start
(make-face 'sgml-ms-end-face) ; end of marked section
(make-face 'sgml-pi-face) ; processing instructions
(make-face 'sgml-sgml-face) ; the SGML declaration
(make-face 'sgml-shortref-face) ; short references

;; view a list of available colors with the emacs-lisp command:
;;
;; list-colors-display
;;
;; please assign your own groovy colors, because these are pretty bad
(set-face-foreground 'sgml-comment-face "coral"
;(set-face-background 'sgml-comment-face "cornflowerblue")
(set-face-foreground 'sgml-start-tag-face "slateblue")
;(set-face-background 'sgml-start-tag-face "cornflowerblue")
(set-face-foreground 'sgml-end-tag-face "slateblue")
;(set-face-background 'sgml-end-tag-face "cornflowerblue")
(set-face-foreground 'sgml-entity-face "lavender")
;(set-face-background 'sgml-entity-face "cornflowerblue")
(set-face-foreground 'sgml-doctype-face "lavender")
;(set-face-background 'sgml-doctype-face "cornflowerblue")
(set-face-foreground 'sgml-ignored-face "cornflowerblue")
;(set-face-background 'sgml-ignored-face "cornflowerblue")
(set-face-foreground 'sgml-ms-start-face "coral")
;(set-face-background 'sgml-ms-start-face "cornflowerblue")
(set-face-foreground 'sgml-ms-end-face "coral")
;(set-face-background 'sgml-ms-end-face "cornflowerblue")
(set-face-foreground 'sgml-pi-face "coral")
;(set-face-background 'sgml-pi-face "cornflowerblue")
(set-face-foreground 'sgml-sgml-face "coral")
;(set-face-background 'sgml-sgml-face "cornflowerblue")
(set-face-foreground 'sgml-shortref-face "coral")
;(set-face-background 'sgml-shortref-face "cornflowerblue")

;; assign faces to markup categories

(setq sgml-markup-faces '
  (
  (comment . sgml-comment-face)
  (start-tag . sgml-start-tag-face)
  (end-tag . sgml-end-tag-face)
  (entity . sgml-entity-face)
  (doctype . sgml-doctype-face)
  (ignored . sgml-ignored-face)
  (ms-start . sgml-ms-start-face)
  (ms-end . sgml-ms-end-face)
  (pi . sgml-pi-face)
  (sgml . sgml-sgml-face)
  (shortref . sgml-shortref-face)
  ))

;; tell PSGML to pay attention to face settings
(setq sgml-set-face t)
;; ...done setting up psgml-mode.
;; *******************************************************************

Then restart Emacs

SGML Smoke Test

Try the following smoke test. Start a new file, /tmp/test.sgml for example, and enter the following:

<!DOCTYPE test [
<!ELEMENT test - - (#PCDATA)>
]>

Enter C-cC-p. If Emacs manages to parse your DTD, you will see Parsing prolog...done in the minibuffer. Try C-c C-e RETURN to insert a <test> element. If things are working correctly, you should see the following in Emacs:

<!DOCTYPE test [
<!ELEMENT test - - (#PCDATA)>
]>
<test></test>

Writing a New HOWTO in DocBook

Start a new file for your HOWTO and enter the following:

<!DOCTYPE ARTICLE PUBLIC "-//OASIS//DTD DocBook V3.1//EN">

EnterC-cC-pand hold your breath. If everything goes as planned, you will see Emacs chewing for a few seconds and then Parsing prolog...done in the minibuffer.

At this point, enterC-cC-eRETURN to insert an <article> element and proceed to write your HOWTO.

Quick Reference for Emacs with PSGML

See Nik Clayton's primer for FreeBSD documentation: http://www.freebsd.org/tutorials/docproj-primer/psgml-mode.html