Re: [gtk-list] Experimental GTK DocBook documentation

[Aaron Digulla <digulla wi-pc44 fh-konstanz de>]

Quoting Damon Chaplin (DAChaplin@email.msn.com):

> I've been trying to automaticaly generate DocBook documentation for GTK,
> GDK and GLIB. I've put my latest attempt at:
>
>     http://www.comp.lancs.ac.uk/~damon/docs/index.html
>
>
> I'd like some comments on this, i.e. should I carry on with it?

Yes.

Comments:

- Signal prototypes are formatted too wide. It would be better like
this:

select_row (GtkCList       *clist,
	    gint	    row,
	    gint	    column,
	    GdkEventButton *event,
	    gpointer	    user_data);

The idea behind this is that the user doesn't need to scroll left/right.

- Can you use a different format for the keywords (like #define,
enum, etc.) ?

- IMHO, indenting the different parts would help the reader to
orient himself (like in man pages).

> I know that Shawn Admundson has been using perldoc to produce man pages
> for a few widgets. We need to decide which way to go. With DocBook you
> can produce man pages and also HTML, including cross-reference links.
> But there is a lot to learn.
>
> Also comments on what needs to be added and what the structure should be are
> welcome. I think that I need to add descriptions of widget 'Args' and also
> descriptions of some of the fields in widget structs, i.e. those which
> aren't
> available using functions.

How about an example section with one or more examples (maybe with
screenshots) ?

--
Dipl. Inf. (FH) Aaron "Optimizer" Digulla     Assistent im BIKS Labor, FB WI
"(to) optimize: Make a program faster by      FH Konstanz, Brauneggerstr. 55
improving the algorithms rather than by       Tel:+49-7531-206-514
buying a faster machine."                     EMail: digulla@fh-konstanz.de