Re: Fwd: Kernel-doc^2 (gtkdoc)

[Trevor Curtis <trevor curtis home com>]

Hey all,

I joined the gdp a few weeks ago.  When Dan Mueth and I originally
spoke, we had agreed that I was to continue the gtk-doc
manual.  The problem however, was that I had little experience with
things such as cvs, autoconf, automake, and the like.  So I've
temporarily put the gtk-doc manual on hold, whilst I learn the above
by doing other smaller projects.

All this to say that this lack of documentation for gtk-doc is an
issue that is trying to be addressed.  Unfortunately, until I learn
more about the subject, and the other bits of knowledge that I must
aquire to complete this job, it may be some time before I'm able to
complete the manual.

If anyone has ideas or just wants to look at was is already there, it
is available in cvs.  

regards,

On Mon, Feb 19, 2001 at 10:33:05PM -0500, Owen Taylor wrote:
> To: gnome-doc-list gnome org
> Subject: Re: Fwd: Kernel-doc^2 (gtkdoc)
> From: Owen Taylor <otaylor redhat com>
> Date: 19 Feb 2001 22:33:05 -0500
> 
> 
> Actually, gtk-doc goes a lot beyond simply parsing the 
> function doc comments. (And in fact, it didn't originally
> do that at all!)
> 
> Among other things, it:
> 
>  - Knows about the GTK+ object system - object heirarchies,
>    signals, properties, etc.
> 
>  - Parses header files to find out about typedefs,
>    
>  - Integrates documentation from template files with
>    the parsed header files.
> 
>    (This one of the distinguishing characteristics of gtk-doc - 
>    it doesn't try to put all documentation inline - just
>    the parts that make sense.)
> 
> There is a fair bit of information the doc/ directory
> of gtk-doc/. Trevor Curtis is apparently also doing some
> work on doing GDP-style documentation, though I don't
> know how far he's gotten with that.
> 
> 
> As far as installation, gtk-doc is wonderously easy to install.  There
> is a RPM of it in the RH rawhide tree, though it's a bit out of date,
> but it's also just a simple:
> 
>  ./configure ; make install
> 
> out of CVS. The thing about gtk-doc is:
> 
>  - It's a tool for GTK+/GNOME programmers to do docs for other
>    programmers, so the docs for gtk-doc assume a lot of 
>    knowledge about programming.
> 
>  - It's a real pain to set it up to document a library. I mean, a
>    major pain.  Hard. Involves creating a number of files with magic
>    contents, and then knowing more about make than you ever wanted to
>    know.
> 
>    I've gone out on a limb and made the statement that the reference
>    doc makefiles in the HEAD of GTK+ (docs/reference/gtk/Makefile.am, etc)
>    are just about perfect. They are also meant to be easy to modify
>    without having to change the scary parts.  So, they may be worth
>    copying.
> 
>    But I wish I knew how we could make it easier to set up.
> 
>    More documentation helps, but it there are just too many files to
>    juggle, and it shouldn't take 200 lines of Makefile boilerplate.
> 
> Once it's been set up. It's not bad to use - you just
> either edit the pseudo-sgml files in the tmpl/ directory or
> you edit the inline function headers. But the set up is
> the killer.
> 
> (Perhaps we need to create a gtkdocize script, like libtoolize
> and gettextize.)
> 
> Regards,
>                                         Owen
> 
> 
> Telsa Gwynne <hobbit aloss ukuu org uk> writes:
> 
> > Various people on this list at times have expressed interest in gtkdoc.
> > I have been trying to find info on it. I can't find much. What I have
> > is here, because I keep missing people on IRC. And it gets into the
> > archives here. And I don't know any more than this, so please don't
> > email me Hard Questions!
>  
> > Apparently the major problem is that it's a complete sod to install.
> > If you can't find a nice rpm/deb of it, you're in for pain. Gnome
> > apparently has its own little something-doc which is a script by
> > Michael Zucchi and is in CVS. That is what the kernel folks used
> > as a basis for 'kernel-doc', which is just a script in perl. The
> > only feature that it is missing which gtkdoc has is something to 
> > do with classes.
> > 
> > kernel-doc is apparently found in 2.4 (and 2.3 :)) linux kernels
> > in /linux/scripts. 
> > 
> > On the matter of "how to use the thing once it's installed", it's
> > the same for kernel-doc and gtk-doc, and so here are the instructions
> > for kernel-doc on the basis that it might be a quick-start for
> > gtk-doc: 
> > 
> > From: Alan Cox <alan lxorguk ukuu org uk>
> > Subject: Kernel-do