Am 24.12.2009 00:33, schrieb Nicola Fontana: > Il giorno Wed, 23 Dec 2009 19:34:23 +0200 > Stefan Kost <enso...@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. _______________________________________________ gtk-doc-list mailing list gtk-doc-list@gnome.org http://mail.gnome.org/mailman/listinfo/gtk-doc-list
