some questions about gtk-doc

classic Classic list List threaded Threaded
5 messages Options
Reply | Threaded
Open this post in threaded view
|

some questions about gtk-doc

thomas (Bugzilla)-25
Hi everyone,

I've been delving a bit deeper into gtk-doc recently because I wanted to
add documentation for plugins and elements in GStreamer.

While doing so I've come across a few things I wanted to ask:

a) it looks to me like enums that are registered with glib aren't
extracted; only the C-level enums are.  In GStreamer, a tool called
gst-inspect extracts the extra information from registered enums when
describing signals and properties, which looks like this:

  recover-policy      : How to recover when client reaches the soft max
                        Enum "GstTCPRecoverPolicy" (default 0, "Do not
try to recover")
                           (0):         Do not try to recover
                           (1):         Resync client to most recent
buffer
                           (2):         Resync client to soft limit
                           (3):         Resync client to most recent
keyframe

Any reason why gtk-doc doesn't have this ? What would be the best way to
add this - have the scanner write a .enums file, and then incorporate
this ?

b) There is some extra information I would like to plug into the
generated xml.  I've tried doing an xi:include in my tmpl/*.sgml files,
but there's no xmlns: directive generated for XInclude as part of
the .xml files build.  Would it make sense to add this ?

c) I have a hard time hacking on gtk-doc because I tend to have to copy
the tools from /usr to my local dir, tweak my build setup, and remove a
bunch of commented prints to see what's going on.  Would it make sense
to do this more nicely by checking an env var and outputting this debug
info if the env var is set ?

d) It'd be nice if there were ways to hook into various parts of the
gtk-doc tools at certain steps.  For example, for doing the scan step I
really only needed to override the way types were scanned for; instead
of doing a .types file with all _get_type methods, I had to examine
GStreamer's registry and instantiate element factories that have the
GTypes.  So I had to change maybe 50 lines in gtkdoc-scangobj, which
would've been nice to put in through a hook instead of copying and
changing locally.  Has anyone ever thought of making these
customizations more easy ?

That's it for now, I appreciate any pointers to help me further on.

Thanks,
Thomas

P.S.: anyone ever considered redoing gtk-doc in, say, python ?


Dave/Dina : future TV today ! - http://www.davedina.org/
<-*- thomas (dot) apestaart (dot) org -*->
I have these hands teeming with love for you
But you're not here to touch
You said you'd wait but it's killing me
When I need something that much
<-*- thomas (at) apestaart (dot) org -*->
URGent, best radio on the net - 24/7 ! - http://urgent.fm/



_______________________________________________
gtk-doc-list mailing list
[hidden email]
http://mail.gnome.org/mailman/listinfo/gtk-doc-list
Reply | Threaded
Open this post in threaded view
|

Re: some questions about gtk-doc

James Henstridge
Thomas Vander Stichele wrote:

>b) There is some extra information I would like to plug into the
>generated xml.  I've tried doing an xi:include in my tmpl/*.sgml files,
>but there's no xmlns: directive generated for XInclude as part of
>the .xml files build.  Would it make sense to add this ?
>  
>
Why not define the namespace directly, if you need it?  Something like:

  <include xmlns="http://www.w3.org/2003/XInclude" href="foo.html" />

Not as pretty, but it should work.  XML namespaces can be defined at any
level in the document.

James.
_______________________________________________
gtk-doc-list mailing list
[hidden email]
http://mail.gnome.org/mailman/listinfo/gtk-doc-list
Reply | Threaded
Open this post in threaded view
|

Re: some questions about gtk-doc

Stefan Sauer-4
In reply to this post by thomas (Bugzilla)-25
Hi Thomas,
> Hi everyone,
>
> I've been delving a bit deeper into gtk-doc recently because I wanted to
> add documentation for plugins and elements in GStreamer.
>
> While doing so I've come across a few things I wanted to ask:
>
...
> c) I have a hard time hacking on gtk-doc because I tend to have to copy
> the tools from /usr to my local dir, tweak my build setup, and remove a
> bunch of commented prints to see what's going on.  Would it make sense
> to do this more nicely by checking an env var and outputting this debug
> info if the env var is set ?
 >
I don't know how much it hurts the preformance of gtk-doc, if we leave all the
trace prints in there in for realeses. Apart this sounds good. I do it the same way.
The doc utile are generatet at configure time (inserts the path to the perl
binary). I don't know if we can use this step to toggle between a nop-debug-log
and a working one.
>
...
>
> Thanks,
> Thomas
>
> P.S.: anyone ever considered redoing gtk-doc in, say, python ?

What would we gain? IMHO the 'ugliness' of gtk-doc is not tha facts is written
in perl. Its more that the developer needs to maintain several files which have
redundant information. But hey, that what we are addressing step-by-step ;)

Stefan
_______________________________________________
gtk-doc-list mailing list
[hidden email]
http://mail.gnome.org/mailman/listinfo/gtk-doc-list
Reply | Threaded
Open this post in threaded view
|

Re: some questions about gtk-doc

Matthias Clasen
In reply to this post by thomas (Bugzilla)-25
On Fri, 2005-08-05 at 23:47 +0200, Thomas Vander Stichele wrote:

> Hi everyone,
>
> I've been delving a bit deeper into gtk-doc recently because I wanted to
> add documentation for plugins and elements in GStreamer.
>
> While doing so I've come across a few things I wanted to ask:
>
> a) it looks to me like enums that are registered with glib aren't
> extracted; only the C-level enums are.  In GStreamer, a tool called
> gst-inspect extracts the extra information from registered enums when
> describing signals and properties, which looks like this:
>
>   recover-policy      : How to recover when client reaches the soft max
>                         Enum "GstTCPRecoverPolicy" (default 0, "Do not
> try to recover")
>                            (0):         Do not try to recover
>                            (1):         Resync client to most recent
> buffer
>                            (2):         Resync client to soft limit
>                            (3):         Resync client to most recent
> keyframe
>
> Any reason why gtk-doc doesn't have this ? What would be the best way to
> add this - have the scanner write a .enums file, and then incorporate
> this ?

Sounds reasonable. You need to be careful to merge this information in
a sensible way with stuff found in templates or inline, though. But
registered enumerations only have nicks and names for their values, not
the short blurbs your example shows...

>
> P.S.: anyone ever considered redoing gtk-doc in, say, python ?
>

No why ?

Matthias

_______________________________________________
gtk-doc-list mailing list
[hidden email]
http://mail.gnome.org/mailman/listinfo/gtk-doc-list
Reply | Threaded
Open this post in threaded view
|

Re: some questions about gtk-doc

Damon Chaplin
In reply to this post by thomas (Bugzilla)-25
On Fri, 2005-08-05 at 23:47 +0200, Thomas Vander Stichele wrote:

> c) I have a hard time hacking on gtk-doc because I tend to have to copy
> the tools from /usr to my local dir, tweak my build setup, and remove a
> bunch of commented prints to see what's going on.  Would it make sense
> to do this more nicely by checking an env var and outputting this debug
> info if the env var is set ?

The trouble with this is that you only typically want a few of the
debugging messages at any one time. If the uncomment all of them you may
get lost in too much output.

But I'd be OK with basic output about which symbol is being worked on.


> d) It'd be nice if there were ways to hook into various parts of the
> gtk-doc tools at certain steps.  For example, for doing the scan step I
> really only needed to override the way types were scanned for; instead
> of doing a .types file with all _get_type methods, I had to examine
> GStreamer's registry and instantiate element factories that have the
> GTypes.  So I had to change maybe 50 lines in gtkdoc-scangobj, which
> would've been nice to put in through a hook instead of copying and
> changing locally.  Has anyone ever thought of making these
> customizations more easy ?

There is a --type-init-func option that you could use to initialize all
the types in GStreamer.

Alternatively we could allow the .types file to contain a chunk of
initialization code. That would be fairly easy to do. i.e. anything
after <!--INITIALIZATION--> is copied directly to the C output.


> P.S.: anyone ever considered redoing gtk-doc in, say, python ?

That's a step backwards, isn't it ;)

Damon


_______________________________________________
gtk-doc-list mailing list
[hidden email]
http://mail.gnome.org/mailman/listinfo/gtk-doc-list