RE: Documentation for GNOME API

["Damon Chaplin" <DAChaplin email msn com>]

> Furthermore, let me add that the raw generated html pages I obtained 
> with d2html remind me of the greatest stallinist artwork.
> 
> I think Damon had obtained much prettier results with the gtk/gdk docs.
> Damon, How did you do it?
> 
> 	Bertrand.

I agree about the DocBook output being pretty horrible. I tried quite
hard to make the docs look OK, but I'm still not very happy with them.

I'm afraid I gave up on all the DocBook tags - '<funcsynopsis>' etc.,
and used <programlisting> to layout all the function prototypes just
as simple text. Otherwise it was impossible to line everything up neatly
and used up far too much space.

I now understand DSSSL enough to do a few customizations. This means that
I may now be able to use the proper tags, and alter the DSSSL if needed.

It seems that for the Gnome docs you are going to place each function
on a separate page (i.e. with its own RefSect). Is that correct?
For the GTK docs I've placed all functions in each module/widget on one
page. Though some of them are pretty long. I'm not sure which way is best.

If you do use one page per function, you don't have to worry so much about
the spacing between items (or lining up prototypes nicely).
But if you're not careful the user will have to step through every page
just to see what each function does. And for GTK there'll be hundreds of
html/man pages!

I had a few more thoughts:

1) should we also be considering the possibility of
   translating these documents at some point. (We can't put all the
   translations in the source code as well!)

2) Someone mentioned producing 'reference cards' for GTK. This would list
   all functions with their prototype and a short description, and could
   be printed out so you can look things up easily. (I use the Perl one
   quite often).
   I think we should possibly copy Javadoc by specifying that the first
   line of the function description should be a short (< 1 line) summary
   of what the function does. Then we can use that line for the
   'reference cards'. 


Damon
  My GTK/GDK/GLib docs are at:
  http://www.comp.lancs.ac.uk/~damon/docs/index.html