Installing and using SGMLtools-Lite

The key to DocBook

Joe Brockmeier (jbrockmeier@earthlink.net), Freelance author

Joe "Zonker" Brockmeier is a contributing editor for Linux Magazine and has written Install, Configure and Customize Slackware Linux for Prima Publishing. His second book, DocBook Publishing, will be published by Prima in early 2001. Joe welcomes your questions, comments, or ideas for future articles on DocBook and can be reached at jbrockmeier@earthlink.net.

Summary: Readers getting started with DocBook for documentation projects will need a guide to using SGMLtools-Lite to produce useful output. This article will walk you through installation and use of SGMLtools-Lite. You'll also get tips on troubleshooting and customizing output for online and print media.

Tag this!

Date: 01 Oct 2000
Level: Introductory
Activity: 617 views

In my previous article on DocBook, I covered the basics of using DocBook markup for your documentation projects. Marking up a document in DocBook is only half of the process, however. At some point you'll probably want to share the document with other folks, which means you'll need to convert DocBook to another format. The second step of the process is to run the document files through a parser that will output readable file formats like HTML, PostScript, or RTF. This article will walk you through using the SGMLtools-Lite package to this end.

SGMLtools-Lite is the Python front-end to SGML processing software. Basically, SGMLtools-Lite simplifies the process of turning DocBook documents into the format, or formats, that you want to distribute.

If you're a Linux user, depending on your distribution and the options you chose during installation, you may already have the original SGMLtools packages installed on your system. The original SGMLtools project, however, was not maintained for a long period of time, and the SGMLtools-Lite project is the successor to that project.

Installation of SGMLtools-Lite

The SGMLtools-Lite project is hosted on Sourceforge (see Resources later in this article). There, you can download RPMs or tar-gzipped source, depending on your preference. The RPMs are built against Red Hat 6.2, and have also been tested with SuSE Linux. They may or may not work correctly with other distributions, so be careful.

Before you install SGMLtools-Lite
Unfortunately, SGMLtools-Lite does not include all of the files you'll need. There are three other packages that need to be installed -- the SGML ISO entity declarations, and both the DocBook DTD and DSSSL stylesheets. Most distributions have packages of these files available; see Resources for the links.

Installing from source

To install SGMLtools-Lite from source, copy the sgmltools-lite-3.0.0.tar.gz file to an empty directory and expand it there, then change directories to the new sgmltools-lite-3.0.0 directory:

tar -zxvf sgmltools-lite-3.0.0.tar.gz
cd sgmltools-lite-3.0.0/

Before doing anything else, check to see if there is a "config.cache" file in the sgmltools-lite-3.0.0 directory. If so, remove it before running configure. If the file is present when configuring make, it could cause problems.

rm config.cache
../configure
make
make install

That should be all there is to it. To see if SGMLtools-Lite is installed, run this command:

sgmltools --help

If SGMLtools-Lite is properly installed and configured, you should get the following:

SGMLtools version 3.0.0
Usage:
  sgmltools [OPTION...] [INPUT-FILE...]
Convert SGML files into various output formats.

Options:
  -v  --verbose         Print verbose output
  -d  --debug           Do not remove temporary files
  -b: --backend=        Backend to use
  -j: --jade-opt=       Options passed on to jade
  -s: --dsssl-spec=     DSSSL spec to use
  -V  --version         Print version number and exit
  -h  --help            Print usage and exit
  -l  --license         Print license information

For help on a specific backend, use "--backend xyz --help".

Installing from RPMs

If you're using an RPM-based system, you can install SGMLtools-Lite using RPMs instead. You'll want to download the latest sgmltools-lite package and the support files. Once you've downloaded both RPMs, go ahead and install them using the -i option. Again, you can test the installation by running the sgmltools -- help command to be sure that everything is installed.

Troubleshooting the installation

One thing you may need to do for SGMLtools-Lite to work properly is to set an SGML_CATALOG_FILES environment variable so that SGMLtools-Lite knows where to look for catalog files. You can do this manually by issuing a command that sets the proper environment variable. This is what works on my system (yes, it is a pretty hefty bit of typing):

export SGML_CATALOG_FILES=/usr/local/share/sgml/stylesheets/docbook/catalog:
/usr/local/share/sgml/entities/iso-entities-8879.1986/iso-entities.cat:
/usr/local/share/sgml/dtd/jade/dsssl.cat:
/usr/local/share/sgml/stylesheets/sgmltools/sgmltools.cat:
/usr/local/share/sgml/dtd/sgmltools/catalog:
/usr/local/share/sgml/dtd/docbook/3.1/docbook.cat

To avoid having to do this each time you log in, you might want to go ahead and set the SGML_CATALOG_FILES environment variable in your .bash_profile. Note that if you set your environment variable in an x-term, it may not carry over to your other x-terms, so if you get errors you may want to check and make sure your environment is set correctly.

Using SGMLtools-Lite to produce output files

Using SGMLtools-Lite is fairly easy, once you've got it installed. The primary use for SGMLtools-Lite is to produce either HTML, PostScript, RTF, or plain-text files from DocBook files. You can also use SGMLtools to convert Linuxdoc files to the DocBook format.

Producing HTML files

Here's how to produce HTML output with SGMLtools-Lite. If you're producing documents with images, you'll want to refer to the image names without the file extension. For instance, instead of this:

      <screenshot>
        <graphic fileref="../images/datebook1.gif"><graphic>
      <screenshot>

You'll want to use this:

      <screenshot>
        <graphic fileref="../images/datebook1"><graphic>
      <screenshot>

When processing DocBook files, SGMLtools-Lite expects gifs when producing HTML files, and EPS files when producing PostScript files. SGMLtools-Lite automatically tacks on the .gif extension when producing HTML, so the HTML documents will work correctly.

To produce HTML output from a DocBook file named book.sgml, type the following:

sgmltools -b html book.sgml

The "-b" (backend) argument tells SGMLtools-Lite to produce HTML output.

This will create a directory named "book" with the HTML files in it. If your DocBook document calls other files, SGMLtools-Lite will also process them and automatically create an index and navigation between "pages."

The HTML markup produced by SGMLtools-Lite is a little on the homely side. You may want to run "HTML Tidy" (see Resources) on the files before uploading them to a server. Not only will HTML Tidy clean up your code, it will replace presentational markup like <font> and <center> with CSS rules.

Producing PostScript files

To produce PostScript output, use the following command:

sgmltools -b ps book.sgml

The PostScript output produced by SGMLtools-Lite is very professional looking, and is suitable for use for many documents, like software manuals or company reports, that you would normally produce with a typesetting program. SGMLtools-Lite even produces a cover page and table of content on the fly.

Producing RTF files

If you need to share a document with someone using Word, you may want to output files in Rich Text Format, or RTF. This is as simple as producing any other type of output with SGMLtools-Lite:

sgmltools -b rtf book.sgml

Unfortunately, Microsoft Word doesn't have an option to export to DocBook that I'm aware of.

Producing plain text files

Finally, you can create plain-text files with DocBook if you need to. To produce plain-text with SGMLtools-Lite use the "-b txt" argument.

Converting Linuxdoc to DocBook

In some cases, you may be responsible for maintaining documents in the Linuxdoc format. Perhaps your company was using Linuxdoc to write documentation, or perhaps you've come across some older documentation written in Linuxdoc. Luckily, one of the features of SGMLtools-Lite is the ability to convert documents from the Linuxdoc DTD to the DocBook DTD.

To convert a Linuxdoc file named Howto.sgml to DocBook format, use the following command:

sgmltools -b ld2db Howto.sgml

This will create a DocBook SGML file from the Linuxdoc file. You can then use the new DocBook file to produce the other various types of files. SGMLtools-Lite will not produce output other than DocBook from Linuxdoc files.

This has been a brief look at installing and using SGMLtools-Lite. Publishing with DocBook can get pretty complicated, but you should now have the basics you need to get your feet wet.

Resources

Visit DocBook.org, the official DocBook site.
See the SGML ISO Entity Declarations in RPM format.
Refer to the DocBook DTD RPMs.
Check out the DocBook DSSSL Stylesheet RPMs.
The Linux Documentation Project contains many documents written in DocBook. The LDP Author Guide has some tips on getting started with DocBook.
Download either the source or RPMs at SGML-tools Lite and follow the instructions to install them. This site has the tools you need to convert DocBook documents to HTML, PDF, PostScript, RTF, or plain text.
At the OASIS DocBook Pages, you'll find the DocBook Technical Committee home page.
For help getting started with any SGML DTD, see the W3C Overview of SGML Resources.
For more details, see the General SGML/XML Applications, OASIS' guide to SGML/XML apps.
Try using HTML Tidy to clean up your HTML output and replace presentational markup with CSS rules.

About the author

Comments (Undergoing maintenance)

Trademarks | My developerWorks terms and conditions

Close [x]

Help: Update or add to My dW interests

What's this?

This little timesaver lets you update your My developerWorks profile with just one click! The general subject of this content (AIX and UNIX, Information Management, Lotus, Rational, Tivoli, WebSphere, Java, Linux, Open source, SOA and Web services, Web development, or XML) will be added to the interests section of your profile, if it's not there already. You only need to be logged in to My developerWorks.

And what's the point of adding your interests to your profile? That's how you find other users with the same interests as yours, and see what they're reading and contributing to the community. Your interests also help us recommend relevant developerWorks content to you.

View your My developerWorks profile

Return from help

Close [x]

Help: Remove from My dW interests

What's this?

Removing this interest does not alter your profile, but rather removes this piece of content from a list of all content for which you've indicated interest. In a future enhancement to My developerWorks, you'll be able to see a record of that content.

View your My developerWorks profile

Return from help

static.content.url=http://www.ibm.com/developerworks/js/artrating/

SITE_ID=1

Zone=Linux

ArticleID=11050

ArticleTitle=Installing and using SGMLtools-Lite

publish-date=10012000

author1-email=jbrockmeier@earthlink.net

author1-email-cc=