Re: sgml-id / xml-id and namespaces

[Nicola Fontana <ntd entidi it>]

Il giorno Wed, 23 Dec 2009 19:34:23 +0200
Stefan Kost <ensonic hora-obscura de> ha scritto:

> Am 23.12.2009 14:23, schrieb David Nečas:
> > On Wed, Dec 23, 2009 at 12:54:54PM +0100, Nicola Fontana wrote:
> >>> But this does not solve the type/section clash, does it?
> >>
> >> Yes, it will: the section is nothing more than a root subsection.
> >> The problem is the final file name should be treated specially (as
> >> I think nobody would like "DOC:::GtkWidget.html" or something
> >> similar), but I guess the file name is yet handled apart.
> > 
> > I thought most people expect #GtkWidget to lead to the section, not
> > to the struct definition (that usually does not contain anything
> > useful). That is if a type has a section on its own, #type should
> > lead to the section; it should lead to the struct definition only
> > if it's an auxiliary type without a top-level section.
> > 
> > So you suggest to write #GtkWidget to link to the section and
> > #GtkWidget-with-some-suffix-or-prefix to the struct, but the XML ids
> > being exactly opposite, i.e GtkWidget-compilicated for sections and
> > GtkWidget for the struct?  Does it makes sense?
> > 
> > Yeti
> > 
> 
> We can easily make it so that:
> - #Gtkwidget -> DOC--GtkWidget
> - #Gtkwidget.foo -> GtkWidget.foo
> 
> and there should be the fallback to do
> - #Gtkwidget -> GtkWidget
> if there is no DOC--GtkWidget. This would handle the case where one
> has multiple structs in one section (the section-id would be more
> generic).

This will prevent direct linking to type definition if there is a
section with the same id. Not a big deal, but also direct links to
subsections should be explicitely forbidden to avoid confusion. In
other terms, given the above rules, #GtkWidget.description MUST specify
a link to an hypothetical `description' field of the GtkWidget struct,
not to the "Description" subsection of the GtkWidget section.

I personally prefer different tags, using for example #GtkWidget to
refer to the type definition and !GtkWidget for section ids
(fallbacking to the type if not found) but I find this solution a good
compromise.

I don't use section links and I don't know how the others use gtk-doc,
so if section linking is not spread avoiding a new tag could be better.

Ciao.
-- 
Nicola