This section covers the new method of writing LDP documentation, using the DocBook 3.1 DTD. We'll cover getting, installing, and using tools, along with an introduction to DocBook tags. Since there are over 300 DocBook tags, we won't cover them all here. Really interested readers can go to http://www.docbook.org for more information.
If you are a new to the LDP and want to pick up an unmaintained HOWTO or write a new HOWTO or mini-HOWTO document, contact the HOWTO coordinator at ldp-discuss@lists.linuxdoc.org. This is to make sure the HOWTO coordinator can know who is working on what documentation. Also note that all HOWTO submissions must be in SGML format using the DocBook 3.1 DTD. The mini-HOWTO submissions may be made in either SGML or HTML formats, but only SGML-formatted submissions will be included in printed versions of the HOWTOs.
There are a few mailing lists to subscribe to so you can take part in how the LDP works. First is ldp-discuss@lists.linuxdoc.org, which is the main discussion group of the LDP. To subscribe, send a message with the subject reading "subscribe" to ldp-discuss-request@lists.linuxdoc.org. To unsubscribe, send an e-mail with the subject of "unsubscribe" to ldp-discuss-request@lists.linuxdoc.org.
This is the quick and dirty way that should work for all distributions, no matter what distribution you're using.
Create a base directory to store everything such as /usr/local/sgml. We'll call this $_toolroot form here on.
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)
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: $ENV{'SGML_CATALOG_FILES'} = “$_toolroot/dtd/docbook.cat;$_toolroot/dsssl/docbook/catalog;$_toolroot/jade-1.2.1/dsssl/catalog”
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
To create one large HTML file, add -V nochunks to the jade command.
Unlike previous versions of sgmltools, you will require sgmltools version 2.x for use with DocBook. Since the backend programs have all changed, you'll also need to forget the sgml2xxx style of programs (sorry). Since most major distributions ship with sgml 1.x, you'll need to remove the sgml 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:
CVSROOT=:pserver:cvs@cvs.sgmltools.org:/home/cvs export CVSROOT cvs login cvs -z6 get sgmltools |
The CVS password is 'cvs'. Once downloaded, You can just use
./compile make 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. For Debian-based systems, apt-get will retrieve the right package for you:
# apt-get install sgmltools |
As with the RedHat, be sure to get sgmltools and not sgml-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:
db2html filename |
Renders DocBook into HTML. A subdirectory with the filename (minus the .sgml extension) is created and the HTML files are placed there.
db2pdf filename |
Renders DocBook into a PDF file.
Must of this is covered by Jorge Godoy's Using DocBook document. Those interested can read it at http://metalab.unc.edu/godoy/using-docbook/using-docbook.html for writing DocBook using your favorite text editor.
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.
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 reapply 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.
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.
Unfortunately, I don't use Emacs. If you use PSGML for writing/validating SGML, please e-mail the author your directions and I'll be happy to add them here as a service for other users.