Hi,
In my adventures on writing the GNOME Best Practises document, I have
found out many things about API documentation.
This can be said about GNOME API documentation in Debian:
* it is sometimes out of date
* it does not cross-reference
* it is installed in different locations
Work Mikael Hallendal is doing on the new DevHelp, along with work James
Hensbridge is doing on gtk-doc, is meaning that the new GNOME developer
documentation system will rule.
Different maintainers are packaging the gtk-doc stuff differently. What
should happen is:
gtk-doc generated documentation is installed in
/usr/share/gtk-doc/html/[package]. I suggest a symlink in
/usr/share/doc/[package]/ pointing to it, to respect policy. Ensure
that the *.devhelp, *.sgml, *.xml files in /usr/share/gtk-doc are not
compressed, tools will want to read these.
This should lead to API documentation which cross-references correctly
(i.e. clicking on "GType" in the libgnomeui docs will take you to the
GLib docs), and then DevHelp2 will Just Work. As you install
documentation, DevHelp will know about them. It Just Works!
When I have written this nicely and sorted out any comments, I'll put it
in the Best Practises (which I really need to get finished).
Note that this would involve filing several bug reports to get all of
the packages doing the same thing.
Regards,
Ross
--
Ross Burton mail: ross@burtonini.com
jabber: ross@jabber.debian.net
www: http://www.burtonini.com./
PGP Fingerprint: 1A21 F5B0 D8D0 CFE3 81D4 E25A 2D09 E447 D0B4 33DF
Attachment:
signature.asc
Description: This is a digitally signed message part