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

[Malcolm Tredinnick <malcolm commsecure com au>]

On Tue, 2003-11-18 at 19:53, Aaron Weber wrote:
> Here are my changes to authors.html for developer.gnome.org.  Don't
> worry about the style-- theoretically this will look right once on
> gnome.org; I'll discuss those details with jdub. 
> 
> It should be viewable with any old browser. My only question is:
>         
>         * How do I resolve conflicts between the configure.in and
>         Makefile.am files from gtk+ and gtk-doc? 

See previous mail.
[...]

> What we need to figure out (assuming that there are canonical and
> correct versions of these files (or file sections)) is how often those
> files changes.

> If the files change much (or at all) we might as well just tell people
> "Use the ones from gtk+, check it out and copy." If they don't change,
> then we can copy them to the gtk-doc module and the web pages.

That has already been happening for quite some time now. When you run
autogen.sh, the current versions of things like gtk-doc.make are pulled
in from the gtk-doc installation. Your document should just recommend
that people use it like this (running gtkdocize as part of autogen.sh if
they are writing their own autogen.sh). It is really a waste of time to
try and explain the older way of doing things since it was a bit too
fragile. The only reason there are packages around which still do it is
because there is no huge emergency to upgrade if things still work. But
over time, all modules will slowly upgrade.

A few comments on the document you attached:

- authors.html seems like an odd name. Is this a holdover from what it
is currently called?

- Please differentiate between API documentation (which gtk-doc is used
for) and general developer documentation (things like porting guides,
the GTK+ FAQ and tutorials and more general documents like that). You
are talking about API documentation in that document.

- You might want to point to libglade as another example of clean use of
this module (it should be, since JamesH was the key driver behind the
big cleanups). It is a bit simpler than the GTK+ example, so they
complement each other well.

- The templates are based on DocBook XML, but they are not well-formed
XML documents.

- The href for the elisp macro is broken, but I guess you know that.

- The type designators in the docstrings (@, %, #) are not shortcuts.
They are necessary syntax if you want to mark things up correctly. So
the heading on the "shortcuts and syntax" section is really just
"syntax". Although you could add a note saying that leaving out off
these specifiers will cause no harm -- it will just result in the word
not being marked up quite correctly.

- The <SECTION> and <SUBSECTION> tags need to have there '<' symbols
replaced with &lt; entities. Otherwise they are interpreted as HTML
tags.

- You should mention the special meaning of <SUBSECTION Private>, since
that is often misunderstood and under-appreciated.

- 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).

Cheers,
Malcolm