Re: Man pages, etc?

[Damon Chaplin <damon karuna uklinux net>]

On Fri, 2003-11-14 at 19:25, Aaron Weber wrote:
> Yeah, it'd be nice to have docbook docs for them, but really, we need
> at the very least a summary man page that says where to look, since
> they're commandline tools, and people will expect man pages to exist
> in some form or other.
> 
> Also --help output would be good. :)
> 
> Now, as I understand it, the process is as follows:
> 
> Check out the module you wish to document and go to a directory with a
> lot of .h files. 
> Run the command gtkdoc-scan --module=[name-of-module] * to generate a
> list of function declarations. 
> Edit the list of function declarations, moving the SECTION tags as you
> see fit to organize them. 
> Run the command gtkdoc-mktmpl --module=[name-of-module] to create a
> directory called tmpl full of template SGML files. These files are the
> autogenerated documentation, which is basically comments and function
> arguments stripped from the code. 
> Edit the SGML files to improve the docs. 
> Run the command gtkdoc-mkdb to convert the template files into
> finalized SGML. 
> Submit your patches to the maintainer.
> 
> Is that correct? 

Not quite. See doc/setting-up.txt, which tries to explain how to set up
documentation for a module. I'm not sure it has been updated to cover
James' new Makefile stuff though.

Basically you edit your project's configure.in and Makefile.am and it
then builds all the docs automatically for you. You don't really need to
run gtkdoc-scan or the other scripts by hand.

You do edit the, <MODULE>-sections.txt and tmpl/* files as you say
though.

Damon