RE: Documentation for GNOME API

[Mark Galassi <rosalia cygnus com>]

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

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

In that case you are completely missing the point, and should probably
not be using DocBook.  I'm kidding here, but I mean to make a strong
statement about using the right tags.

You should output the correct markup no matter what, and not care if
it is ugly.

You should have seen how ugly it was a year ago!  It gets better
almost by the week.  I suspect that they will look better long before
GNOME is reasonably documented!

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

You should state which distribution of the stylesheets you are using.
I have made some small improvements in what I distribute, and there is 
a clear improvement which I have already implemented for
FrameMaker+SGML and I plan to add to the DSSSL stylesheets too.

    Damon> It seems that for the Gnome docs you are going to place
    Damon> each function on a separate page (i.e. with its own
    Damon> RefSect). Is that correct?

Eventually I think that's the way things should be done.

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

We could always customize the <ref*> stuff to not output as many
different pages.

    Damon> I had a few more thoughts:

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

I suspect that API documentation is an area where translation is not
as important.  But you are right: if people want to do the translation 
they should be able to, and there should be a good mechanism for it.
You should bring the question up to Ulrich Drepper in case he has some 
insight (I've CC-ed him -- Ulrich: the issue here is that GNOME will
be embedding function API docs in the C code, and ->docbook extractors 
are being written).