Re: Man pages, etc?

[Aaron Weber <aaron ximian com>]

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?

I should note at this point that I'm a terrible programmer and don't actually come close to, you know, understanding the code I'm about to face...

a.



On Fri, 2003-11-14 at 13:58, Damon Chaplin wrote:

On Fri, 2003-11-14 at 15:45, Aaron Weber wrote:
> Hello,
> 
>    I'd like to volunteer to write some help for gtk-doc. Who's
> maintaining it at this point, and where should I send man pages? I am
> not 100% sure that I'd be right on the whole process...

Matthias Clasen does some maintenance occasionally and James Henstridge
helps out with the Makefile bits.

I'm still the official maintainer, but I haven't looked at it for ages.

Send man pages here or put them in bugzilla. I'd rather have DocBook
docs though. man pages suck!

Damon


_______________________________________________
gtk-doc-list mailing list
gtk-doc-list gnome org
http://mail.gnome.org/mailman/listinfo/gtk-doc-list

.TH "gtkdoc-mktmpl" "1" "0.1.0" "Damon Chaplin, Owen Taylor" "GTK Documentation Tools"
.SH "NAME"
.LP 
gtkdoc\-mktmpl \- Creates SGML template files from source code and the declaration files output by \fBgtkdoc\-scan\fR. These template files are edited and then converted to the finalized documentation with the command \fBgtkdoc\-mkdb.\fR
.SH "SYNTAX"
.LP 
gtkdoc\-mktmpl  <\fI\-\-module=[module\-name]\fP>
.SH "DESCRIPTION"
.LP 
The declaration, section, and declaration\-list files output from \fBgtkdoc\-scan\fR describe the structure of documentation. The command \fBgtkdoc\-mktmpl\fR takes that structure and creates a set of SGML templates in the <fb>tmpl\fR directory. The templates are outlines of the code, and contain any previously\-written documentation, including some kinds of comments in the code itself. 
.LP 
Once created, these templates can be edited, using standard DocBook markup. Some of the automatically\-generated documentation will not need changes; other portions will need to be filled in with additional detail, explanation, or syntax clarification. 
.LP 
After editing the templates, proceed to use the \fBgtkdoc\-mkdb\fR function to generate the finalized DocBook SGML output.
.SH "OPTIONS"

.LP 
.TP 
\fB\-\-output\-dir=\fR <\fIdirectory\fP>
The directory in which the program will place the output files. If this flag is omitted, the current directory is used.
.TP 
\fB\-\-module=\fR <\fImodulename\fP>
The name of the CVS module or software program you are documenting. This flag is mandatory.
.TP 
\fB\-\-help\fR
Output help information and exit.
.TP 
\fB\-\-version\fR
Output version information and exit.
.SH "EXAMPLES"
.LP 
After editing the modules\-section.txt file, run this program to generate templates:
.LP 
gtkdoc\-mktmpl \-\-module=myprogram 
.SH "AUTHORS"
.LP 
Damon Chaplin <damon gnome org>
Owen Taylor <otaylor redhat com>
.SH "SEE ALSO"
.LP 
gtkdoc\-scanobj(1) gtkdoc\-scangobj(1) gtkdoc\-scan(1) gtkdoc\-mkdb(1)

.TH "gtkdoc-scan" "1" "1.1" "Damon Chaplin, Owen Taylor" "GTK Documentation Tools"
.SH "NAME"
.LP 
gtkdoc\-scan \- Scans header files and previously created gtk\-doc documentation to create declaration and declaration\-list files. This is the first step in the gtk\-doc documentation process.
.SH "SYNTAX"
.LP 
gtkdoc\-scan \-\-module=[module] [\-\-output\-dir=\fIDIR\fR] <\fIfilename\fR>
.SH "DESCRIPTION"
.LP 
Given a code tree or a set of header files, gtkdoc\-scan creates several output files that describe the APIs in the code. The files are named according to the \fI\-\-module\fR flag:

.TP 
module\-decl.txt
Declarations \-\- the functions, objects, and so forth that are laid out in the header files. 

.TP 
module\-decl\-list.txt
A shortened version of the declarations file, this lists the names of the declarations.

.TP 
module\-sections.txt
Defines the sections into which the documentation will be broken. By default, each header file corresponds with a section. To change the organization of the final output, edit this file.
.SH "OPTIONS"
.LP 
.TP 
\fB\-\-output\-dir=\fR <\fIdirectory\fP>
The directory in which the program will place the output files. If this flag is omitted, the current directory is used.
.TP 
\fB\-\-module=\fR <\fImodulename\fP>
The name of the CVS module or software program you are documenting. This flag is mandatory.
.TP 
\fB\-\-help\fR
Output help information and exit.
.TP 
\fB\-\-version\fR
Output version information and exit.
.SH "EXAMPLES"
.LP 
To generate documentation for a project, enter the top\-level project directory and run the command:
.br 
gtkdoc\-scan \-\-module=myproject *
.LP 
Depending on the type of code you are documenting, you may also wish to use the commands \fBgtkdoc\-gobjscan\fR and \fBgtkdoc\-objscan\fR to scan object\-oriented code blocks.
.LP 
Once the scan is complete, edit the myproject\-sections.txt file if you wish to rearrange the documentation. Then, proceed to use the command \fBgtkdoc\-mktmpl\fR.
.SH "AUTHORS"
.LP 
Damon Chaplin <damon gnome org>
Owen Taylor <otaylor redhat com>
.SH "SEE ALSO"
.LP 
gtkdoc\-scanobj(1) gtkdoc\-scangobj(1) gtkdoc\-mktmpl(1)