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
Attachment:
signature.asc
Description: This is a digitally signed message part