Re: sgml-id / xml-id and namespaces

[Stefan Kost <ensonic hora-obscura de>]

Am 24.12.2009 00:33, schrieb Nicola Fontana:
> 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.

Yes, the way gtk-doc makes section links was never officially documented and
could be treated as internal, means we could just change it. On the other hands
I just added the possibility to link to members in 1.12. So I could grep
existing docs if they actually use links like #GtkWidget.<anything> to get an
idea how likely changing this will break things.

Stefan

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