Re: docbook markup in inline docs

[Damon Chaplin <damon ximian com>]

On Wed, 2001-10-17 at 03:07, Matthias Clasen wrote:
> Damon, any progress with the sgml-mode idea for gtk-doc ?
> I have put a patch in bugzilla which adds an --sgml-mode option
> to gtkdoc-mkdb, any comments on that ? It would be really
> nice to get something like that included. (There are some more 
> outstanding patches in bugzilla, but this one is the most important
> one for me.)

I've applied it. Thanks for the patches. (Keep it up and you can take
over maintainership of gtk-doc ;)

 
> On to new questions: 
> 
> 1) gtk-doc treats "Standard" GObject functions and macros be not 
> documenting them at all. Are there any ideas to change this, eg by
> refering to a section in the GObject docs describing the standard
> definitions ? What are the standard definitions for a GObject type,
> and what do we do if only some of the standard definitions are there ?
> (this question came up when I put a patch in bugzilla which would
>  move all standard defines in Pango in the Standard sections, thereby
>  effectively making them undocumented)

I think we always intended to include a page about standard macros
and functions, and probably link to it from each object.
Maybe we should list the standard macros/funcs somewhere
in the object's docs, and link to the descriptions there.

You can see the standard defs by looking at the $MODULE-section.txt
file, e.g. from glib 2:

<SUBSECTION Standard>
G_TYPE_PLUGIN
G_IS_TYPE_PLUGIN
G_TYPE_TYPE_PLUGIN
g_type_plugin_get_type
G_TYPE_PLUGIN_CLASS
G_IS_TYPE_PLUGIN_CLASS
G_TYPE_PLUGIN_GET_CLASS

If a type doesn't have all the standard defs, I'd guess it is a bug.


> 2) What about images ? I feel that the gtk+ API docs really need
> screenshots of all widgets and stock items. I guess that would mean
> to extend the docbook DTD for pngs. Are there any ideas how to
> organize this ? Where should the images live, in docs/reference/gtk+
> or a new subdirectory docs/reference/gtk+/images ?

Adding support for images to the example Makefile would be handy.
I'd place them in their own subdirectory, e.g.
gtk+/docs/reference/gtk+/images. Though I did spot an image in
glib/docs/reference/glib, but that wouldn't work well with many images.

Damon