Re: gobject API docs and tutorial merge : stage 1

["Rajeev Jain" <rajeev clovissolutions com>]

Hi Stefan and Methaieu

I noticed that th detailed description of argument is missing from few APIs.
Is it something that you missed or due to some other reasons.

Also, how about adding some example, related APIs , calling sequence of the
APIs, and providing information whether the argument is mandatory or
optional.

I am ready to contribute on this.

Rgds

Rajeev Jain
----- Original Message ----- 
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>
Sent: Wednesday, April 06, 2005 2:10 PM
Subject: Re: gobject API docs and tutorial merge : stage 1


> Hi all,
>
> the question now is which way to go?
> I've a gnome cvs account, thus I can check files in CVS, but I have no
shell
> account to do it.
> Who could do the CVS merge?
>
> @Mathieu: do you think a lot will change in the doc? If not would it be
okay if
> I convert the links to the API docs for once and then go over it from time
to
> time. By using jedit it is really easy to fix new ones.
>
> Ciao
>    Stefan
>
> > 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()</funct
ion></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
> >
>
> _______________________________________________
> gtk-doc-list mailing list
> gtk-doc-list gnome org
> http://mail.gnome.org/mailman/listinfo/gtk-doc-list