===================
Balsa Documentation
===================

September 10, 2000 by Matthew Guenther.

Updated 2001.05.16 by Pawel Salek <pawsa@theochem.kth.se>. If you find
some information outdated, please report it to Balsa Team.

Building SGML:
=============

In order to properly build the balsa.sgml into the html, ps, or pdf
files, the GNOME Documentation Project DTD and stylesheets must be
available and properly set up.  If they are not there the images will
not work correctly. For instructions on doing this, see the GDP
handbook:

http://developer.gnome.org/projects/gdp/handbook.html

In particular, you will need gnome-doc-tools package downloadable from

http://people.redhat.com/dcm/software.html

Also, in order to succesfully build the postscript or pdf versions of
the manual, the images must be converted into Encapsulated Post Script
(eps) files.  The makefile expects a script, img2eps to be present to
do this conversion.  It uses the ImageMagick library and is also
available from the GDP website:

http://people.redhat.com/dcm/img2eps

On RH 7.1, it may be necessary to supply following -c options to db2html:

-c /usr/share/sgml/docbook/sgml-dtd-3.1/catalog
-c /usr/share/sgml/docbook/png-support-3.1/catalog

It may be simpler though to add these directories to
/etc/sgml/sgml-docbook.cat (the system wide SGML catalog; the location
may be different on other distributions).
Basically, it depends on your configuration. If you get plenty of errors
transforming balsa.sgml, it often means that there is a mistake in
the system settings.

Writing SGML:
============

Before contributing to the manual it is a genuinely good idea to read
the GDP handbook mentioned above, it details the standards and
procedures by which all GNOME documentation is governed.  

Of particular importance is how to mark up images, the filename(s)
should not be given extentions in the tag.  This is because the
stylesheet will add the appropriate extension depending on whether it
is being built for html or postscript.  

Also, if you need help you can try the discussion forum at
https://discourse.gnome.org/tag/documentation , or on in the #gnome-docs
IRC channel on irc.libera.chat.
