Re: GNOME API Documentation Format issues

[Mark Galassi <rosalia cygnus com>]

Hi Scott,

I had a bit of trouble understanding the first part of the message.
For example, what's with the HTML?  You say "you will use HTML for
this explanation", but I don't see any HTML.

I might understand that first part better if you had some concrete
examples.

> Function 1
>  Function Name
>  Function Description
>  Return Values description
>  Parameter List
>   Parameter Type
>   Parameter Description
>  -Link to Table of Contents-

This looks reasonable to me, except that you should let the
stylesheets handle the link to the TOC (and they already do).

    Scott> This model of documentation has one difficulty though.
    Scott> That is, some sort of dB needs to track all the Functions
    Scott> for a particular program or library.  This is to make
    Scott> searching for documentation on a particular function name
    Scott> easier.  This shouldn't be too difficult, but it would need
    Scott> to exist.

If you mean using some kind of web search engine, then I strongly
disagree on this issue.  The model for searching a document should be
that of the emacs info reader (ahh, the pleasure of typine 's' in
emacs's info browser).

You see: we are not using the whole world wide web with all of its
spaghetti.  This document's HTML files will all be in a single
directory and its subdirectories, so the GNOME help browser can be
enhanced to do a tree search of the hierarchy.  It can also use some
of the meta information that's placed in the HTML output by the
stylesheets, although if it does that we might want to freeze that
format.