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

[Carlos A M dos Santos <casantos inf ufrgs br>]

On Wed, 16 Sep 1998, Damon Chaplin wrote:

> > 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.

I vote for a reference into the source code to an external file base
name, like this:

/*
**	<gtkbook>
**	  <function name="gtk_blah_blah_blah">
**	    <parameters>
**	      <parameter name="blih" type="bloh">
**	      :
**	    </parameters>
**	    <description>
**		This function zag zeg zig zog zug
**	    </description>
**	    <doc file="gtk_blah_blah_blah">
**	  </function>
**	</gtkbook>
*/

To generate the documetation, the user should isso a command like

	$ gtkdoc --lang=pt source.c

to generate portuguese versions of the documentation. The gtkdoc utility
should look for files like gtk_blah_blah_blah-{en,fr,es,pt}.sgml according
to the "--lang=" parameter.

> 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.

Yes, I think it is inevitable...

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

For *good* documentation it is impossible, because this would lead to
montruous source files. Also you can not insert figure, tables or math
symbols into the source file. I believe that the function declaration +
brief description + true documentation reference is better.

I hope this helps.

-----
Windows: How much data do you want to lose today?