On Mon, 2005-04-04 at 09:04 +0200, Stefan Kost wrote:
Hi Mathieu,
[snip]
3) links from description [extra doxbook xml files] to API docs
As I already pointed out in an old private mail to you on function
links, I would like to see you use a small script to generate the links
on each data marked with <function> and <macro> tags. If you want to, I
can write the trivial perl code required to do this. I would resist any
sort of change to the xml which would require more markup than just
marking function names with <function> tags.
I did that in jEdit with regexp search and bean-shel replace ;). I thing this
would be a good convinience utillity for gtk-doc. When doing the CVS merge of
the gobject-tutorial files to the gobject repository, they could be commited to
the tmpl directory and a new target rule for the documentation could try to
extend all such links and created modified files in the xml directory.
Problem: links against functions that refer to example code would cause dead
links. Thats why I did it half-automatic.
Actually, no you won't get dead links. The resolution of references to
html links is done by gtkdoc-fixref and it knows to not make links for
function references it can't resolve. See, e.g., the reference to
strtod() in:
http://developer.gnome.org/doc/API/2.0/glib/glib-String-Utility-Functions.html#g-ascii-strtod
But the problem you'd have with putting the files in the tmpl/ directory
is that only the specially formatted reference sections for GObject can
be put in there.
I think the question is whether advantages of the use of custom
tools ... whether specialized or extensions to gtk-doc ... is worth the
hassle of maintaining those tools, compared to just writing straight-up
docbook. Sure, it's painful to write:
<link linkend="pango-fc-font-lock-face"><function>pango_fc_font_lock_face()</function></link>
But if the tutorial is mostly already written, then it can be done automated
once and then just updated from there.
Another possibility would be to extend gtk-doc.dtd and gtk-doc.xsl to allow
<gtkdocfunction function="pango_fc_lock_face"/>
Or maybe
<gtkdoclink target="#PangoFcFont"/>
and then expand that out in the xsl. Though it means that we no longer have
standard docbook that can be processed by standard docbook tools. And doing
the function->id conversion in xsl might be hard.
Regards,
Owen