Re: gobject API docs and tutorial merge : stage 1
- From: Stefan Kost <ensonic hora-obscura de>
- To: Owen Taylor <otaylor redhat com>
- Cc: gtk-doc-list gnome org, gtk-devel-list gnome org, Mathieu Lacage <Mathieu Lacage sophia inria fr>
- Subject: Re: gobject API docs and tutorial merge : stage 1
- Date: Mon, 04 Apr 2005 21:17:52 +0200
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
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]