Re: Changes to "authors.html" for developer.gnome.org

[Aaron Weber <aaron ximian com>]

On Tue, 2003-11-18 at 17:21, Malcolm Tredinnick wrote:
> - authors.html seems like an odd name. Is this a holdover from what it
Yes, that's what they called it previously. We can certainly change the
name, although I'm inclined to leave the whole thing to Jeff Waugh since
he's the web person.

> - Please differentiate between API documentation 
Good point. Clarified more.
> - You might want to point to libglade
Fixed.
> - The templates are based on DocBook XML, but they are not well-formed
Fixed..
> - The href for the elisp macro is broken, but I guess you know that.
Yes. It's not broken in my CVS tree. :)
> - The type designators in the docstrings (@, %, #) are not shortcuts.
Fixed.
> - The <SECTION> and <SUBSECTION> tags need to have 
Doh. Fixed.

> - You should mention the special meaning of <SUBSECTION Private>, since
> that is often misunderstood and under-appreciated.
Can you explain how that works? I'm not entirely clear on it myself.

> - Including docbook tags in comment strings is not hard, but you do have
> to be consistent. The --sgml-mode argument to gtkdoc-mkdb controls
> whether tag-like items in comment strings are treated as tags or
> converted to &lt;...&gt; combinations (with the parameter, anything that
> looks like a tag *is* a tag). The decision the author has to make here
> is whether to use this or not: if they choose to use it, it is on for
> *all* the comment strings (hence the need to be consistent).
The thing is, most people don't run gtkdoc-mkdb themselves; where does
this flag get added? in the autogen files somewhere? as an argument to
make/make install?

a.