This document is an example of RTDS's documentation system intended to be used
with the SGML export feature. It supposes that the following items are
installed on your system:

    * OpenJade version 1.3.2 (http://openjade.sourceforge.net);
    * JadeTeX version 3.13 (http://jadetex.sourceforge.net);
    * A reasonably recent version of TeX (see the TeX users group website:
      http://www.tug.org);
    * Optionally dvipdfm version 0.13.2c (http://gaspra.kettering.edu/dvipdfm).
      This is needed only if the dvipdf utility in the TeX installation does
      not work for you;
    * ghostscript to be able to convert PostScript files to PDF
      (http://www.gnu.org/software/ghostscript).

If you are on Linux, packages are likely to be available for all of these.
Refer to the documentation for your package manager to see how to install them.

Make sure that the SGML catalog file (usually in /etc/sgml/catalog) is up to
date and refers to the actual location for the DSSSL catalog. If you installed
all the tools with a package manager, catalogs are likely to be up to date.

The actual document generation is done by exporting Design.rdo as a SGML file
in the docbuild subdirectory, choosing rtds-doc-template.dsl as stylesheet
template. This should create the files Design.sgml and Design.dsl. After that,
going in this directory in a terminal and running 'make' should produce a
Design.pdf file, including the whole RTDS document contents, plus a title page,
a table of contents and an index, both with working links on page numbers.

Other targets are available in the makefile:
    * 'make clean' will clean up all intermediate files;
    * 'make realclean' will also clean up the files exported by RTDS;
    * 'make mrproper' will clean up everything, including the final PDF file.

Using openjade, you can also convert the produced SGML document into various
other formats, such as RTF or MIF (interchange format for FrameMaker). Please
refer to OpenJade's documentation to see how to do that.


If it doesn't work:
-------------------

Check the requirements, especially the versions of the various tools. If
possible, please get the exact required version: a few of the tools have some
compatibility problems between versions, and only the versions specified above
have been tested.

A problem that seems to happen frequently is during the conversion of the TeX
output (DVI file) to PDF. If you end up with a PDF file with no images, or with
non-working links or weird colors, you can edit the make file to activate the
alternate DVIPDF_COMMAND definition. It might work better under some
circumstances.
