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

["Damon Chaplin" <DAChaplin email msn com>]

> What about having them regenerated forever?  I mean, any additions
> must go though some means.  If we had an examples section, we can
> put that in a seperate file which gets read in when the file is 
> created.  If we want to comment on a function, we will add it in
> the source too.

Yes, I suppose that is the ideal solution.
But do we want to consider translation to different languages?
We can't put them all in the source code.

It also depends on the main GTK programmers agreeing to a common format
for function/macro/enum etc. comments. And it also means people who are
documenting GTK will be making lots of changes to the source files for
the next few months at least, which programmers may not like.

Also, with documentation within source files, there is pressure to
be a bit too terse, whereas some functions need quite long descriptions
and several examples (which would need to be marked-up in DocBook).

I'm not too sure if it's best to write the documentation within the source
files or outside it.


> The next and last release of 1.0.x will be within the next few days, or
> maybe even a day.  If we can get any documentation in there, that 
> would be 
> cool.  Otherwise, we can focus on 1.1.x and 1.2.x.
> 
> So, optimally we could get something for 1.0.x soon, and the next best
> thing is to ignore 1.0.x all together.  This is up to you, I don't mind
> just working on 1.1.x for this either.

I don't think it could be done before the 1.0.x release.
I'd rather we took our time and focused on 1.1.

But I don't think it matters too much if we release HTML & man pages
separately from GTK. I doubt many people would actually want to build
these from the SGML files anyway. And if we add the SGML, HTML and
man pages to the GTK distribution it will be quite a bit bigger.



> I think I advocated the run-once idea before, but now that I see
> the results I have a firmer belief that having that section auto-generated
> would be a good idea.
> 
> What do you think?  Is it practical?  

Yes, but of course it needs a lot of work. The current scripts aren't
designed to be very robust.

Also, not everything is auto-generated at present. I had to split the
GDK and GLIB stuff into sections and rearrange it by hand, since it is
all in one or two header files. I also edited some of the signal
handler prototype parameter names, since these are not available from
within GTK.

I'll put all my scripts etc. up on the web this evening so you can get
an idea of how it currently fits together.

Damon