Re: GTK+ documentation

[Owen Taylor <otaylor redhat com>]

[ Cc'ing and setting reply-to to gtk-doc-list, since that's the more
  appropriate forum for ths ]

On Mon, 2003-09-15 at 10:48, Chris Moller wrote:
> I'm in the process of writing a CDT "hover help" extension to Eclipse, 
> the mechanism that pops up a brief description of a function when you 
> park the cursor over the function name in the Eclipse C/C++ editor.  To 
> do this, I need to store API info in a retrievable form.
> 
> So, the question is: Is there a "tagged text" version of the GTK docs I 
> could use to extract the relevant info?  Something that identifies 
> function names as such, associated arg lists, etc. with SGML or Docbook 
> semantic tags, or something similar.

Hmm, well, not exactly. The .devhelp files that come with the GTK+
docs have things like:

    <function name="gtk_label_set_text ()"
link="GtkLabel.html#gtk-label-set-text"/>

So, you can use that to find the right place in the HTML file for
a function, which you could heuristically extract and display if
you had a HTML engine, or even otherwise, if you were willing to
make assumptions. But that could be quite long, and isn't easy to 
figure out the semantics from.

(It would be a bit easier if we were emitting xmhtml rather than html)

The XML would be considerably easier and more reliable to deal with --
there is no real guarantee that it will stay stable, but you could
at least look for things like:

<variablelist role="params">
<varlistentry><term><parameter>label</parameter>&nbsp;:</term>
<listitem><simpara> a <link
linkend="GtkLabel"><type>GtkLabel</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>str</parameter>&nbsp;:</term>
<listitem><simpara> The text you want to set.
</simpara></listitem></varlistentry>

However:

 A) We don't install the XML currently 
 B) The .devhelp doesn't point to it usefully ... the anchor is the
    same, but the filename is different in an unpredictable way

So, that won't really be useful. If you have a suggestion of what you
would like to see, it's probably not too hard to implement. The
hard part of gtk-doc is collecting the information, not spewing
it back out.

Regards,
						Owen