Re: gobject API docs and tutorial merge : stage 1

[Stefan Kost <ensonic hora-obscura de>]

Hi Owen,

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

For me writing the above is okay. Thats the major reason I used the 
semi-automatic approch to turn the marked-up symbols into references.
Mathieu preferes a different approach.

Stefan