Re: gobject API docs and tutorial merge : stage 1

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:

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.


Attachment: signature.asc
Description: This is a digitally signed message part

[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]