Re: docbook markup in inline docs

["Matthias Clasen" <matthiasc poet de>]

----- Original Message -----
From: "Damon Chaplin" <damon ximian com>
To: "Matthias Clasen" <matthiasc poet de>
Cc: <gtk-doc-list gnome org>
Sent: Thursday, October 18, 2001 12:38 AM
Subject: Re: docbook markup in inline docs


> 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 ;)
>

No thanks. But speaking about mainership, wouldn't it be a nice idea
to relase a 0.8 with the sgml mode stuff (of course, I should have included
at least a tiny piece of documentation for it). Or is it ok for gtk+ and
glib
API docs to depend on CVS gtk-doc for proper processing ?

>
> > 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.
>

The enums in Pango often only have G_TYPE_FOO.

>
> > 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.

I'll take a look.

Matthias