gtt documentation now in DocBook

[Mark Galassi <rosalia cygnus com>]

Dear GNOME types,

I have just committed a translation of the gtt documentation into the
DocBook markup language.

For those who weren't following things back then, DocBook is a very
rich SGML-based markup language designed for documenting software.  We
are beginning to use it at Cygnus, and (among others) Sun uses DocBook
for all of its books and manuals.  DocBook provides tags that mark up
the *content* of a document, rather than its appearance.  This is
unlike HTML (where you specify things like boldface and centering),
and is true to the spirit of SGML.

At the beginning of the GNOME project I proposed that DocBook be used
for GNOME documentation.  Miguel and Federico accepted it without
argument:-), but I never got down to actually starting up a GNOME
DocBook documentation effort.  In part I was sitting on my ass; in
part I was working on getting the free DocBook tools ready for use.

Now two things have happened: Eckehard has written docs for gtt in
debiandoc (another markup language; more simplistic than DocBook), so
we have real GNOME docs to play with.  And the free DocBook tools are
now reasonably good, although there will be some serious improvements
in the next month.

I have committed two files: gnome/programs/gtt/gtt-db.sgml (the
DocBook source) and gtt-db.html (the HTML output with a tiny bit of
stylesheet info thrown in by hand).

If you want to get started with DocBook, you can grab the free tool
packages.  I maintain the RedHat packages (intel and source) at
  ftp://ftp.cygnus.com/pub/home/rosalia/docware
and Mark Eichin maintains debian packages in the standard Debian
hierarchy (I think you can find it at http://www.debian.org/).

The list of packages you should get and install is:

jade        (a DSSSL engine; converts SGML to outputs, like HTML and TeX)
psgml       (a very cool mode for emacs -- allows you to edit SGML nicely)
sgml-common (basic SGML files and catalog
docbook     (the DocBook DTD [Document Type Definition])
sgml-demo   (a sample article with a Makefile for processing it; look
             for improvements and a tutorial in the near future)
stylesheets (DSSSL stylesheets for DocBook; jade uses them to convert
             DocBook to HTML and TeX)
jadetex     (a macro package for TeX, needed for jade's output)


docbook-3.0-5.i386.rpm       sgml-common-0.0-4.i386.rpm
jade-1.0_1-3.i386.rpm        sgml-demo-0.0-7.i386.rpm
jadetex-0.51-2.i386.rpm      stylesheets-0.0-8a.i386.rpm
psgml-1.0.1-5.i386.rpm

---------

If you are considering writing documentation for GNOME, please talk to
me about it.  In any case, please install the tools and give them a
whirl.

---------

from programs/gtt/ChangeLog:

1998-01-25  Mark Galassi  <rosalia@cygnus.com>

	* gtt-db.sgml: translated Eckehard's debiandoc SGML into DocBook.
	Checked in gtt-db.sgml and the html output.

-- 
             Mark Galassi --- astrophysicist, hacker, writer
             Cygnus Solutions and Los Alamos National Laboratory
                                 rosalia@cygnus.com or rosalia@nis.lanl.gov
                                 http://nis-www.lanl.gov/~rosalia/