Re: [gtk-list] Re: Experimental GTK DocBook documentation

[Kevin Handy <kth srv net>]

At 11:23 PM 9/15/98 +0100, you wrote:
>
>
>I'm glad you like it.
>I think it needs quite a bit more work before adding to GTK, though.
>I'd like the generated DocBook files to be perfect before this, since
>once people start editing them, we can't generate them again.
>
>Do you think it is useful to GTK 1.0 in its current state, i.e. with
>no explanations anywhere? If so, I can try to put together collections
>of HTML pages and man pages which we can put on GTK's web site, though
>it will probably take more than 36 hours! (There are still quite a few
>bits to sort out.)
>
>What did you want to integrate into the distribution? The DocBook SGML
>files and scripts to generate the HTML and man pages? I think that
>would be OK (though I doubt many people have the things necessary
>for generating the HTML).
>
>The scripts which scan the GTK+ header files and output the DocBook
>files are more awkward - I'm using several programs and scripts to do
>this at present. These are only intended to be run once anyway.
>Once you start editing the DocBook files, you can't rerun the scripts.
>
>I can put a tarball of all my scripts and stuff on the web, but it
>will be quite difficult for people to use them at present.
>For a start you need the DocBook v3.0 DTD, Jade v1.1, the DocBook Modular
>Stylesheets v1.08, and docbook-to-man installed.
>   	http://www.ora.com/davenport (should have links to 3 of these)
>	http://www.jclark.com/jade
>

What I would find nice, would be to be able to generate new
documentation from the source alone, without having to do
additional changes afterwards. If the comments in the program
were coded in a standard format, then this should be easy.

This would require adding comments to the source code, which
would be a good thing in my opinion. Putting the description of
each function in the source would be a big help to someone
trying to figure out how it works/what it does. Also a change
to a functions interface would automatically change the
documentation. And if we want to change the overall format
of the documentation (bold vs underline function names, etc),
then it would be just a change in the build scripts.

The end user should just be able to type 'make documentation'
to get a usable reference guide built.
-------------------------------------------------------------
Kevin Handy  kth@srv.net         Accounting Software for
Software Solutions. Inc.         VAX/VMS Computer Systems
Idaho Falls, Idaho