Re: docbook markup in inline docs

[Owen Taylor <otaylor redhat com>]

"Matthias Clasen" <matthiasc poet de> writes:

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

This has typically been the case. I have some intention (never got around
to actually doing it) of making the default --disable-gtk-doc
except when you run autogen.sh.

A new release wouldn't hurt, but I wouldn't bother waiting for 
a release to depend on new gtk-doc features.

The most important place for the docs to keep working is the
autobuild on developer.gnome.org and that pulls the latest gtk-doc
every time.

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

Should be noted that the get_type() is really "private" not
standard - people shouldn't be using it directly in almost
any case and a few types do have non-standard TYPE macros.

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

None of the above "standard macros" apply to an enumeration type.
My original comment to Matthias was that I thought that enumeration
type macros should be with the macro, since I suspect people 
will have trouble grasping the rule: "For PangoWeight,
there will be a macro PANGO_TYPE_WEIGHT"

I would imagine having immediately after the enumeration docs, something 
like:

 PANGO_TYPE_WEIGHT - the GObject type for PangoWeight

I don't think a lot of detail is necessary. If it is, we could
have a small description and then link to a longer documentation
section on type macros.

Regards,
                                        Owen