Re: sgml-id / xml-id and namespaces

[Nicola Fontana <ntd entidi it>]

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

> hi,
> 
> I have done a bit of research on the way gtk-doc generates ids. The
> git tree has now two new files - design-{1,2}.x.txt.
> 
> If we cleanup the id-generation to properly namespace doc-structure
> ids and symbol ids we will break existing links. What can we do:
> 
> 1) we break the links. As soon as a distro releases and update, they
> hopefully build everything with the same gtk-doc version and most
> links would work again.
> 
> 2) we add a commandline option as proposed in
> https://bugzilla.gnome.org/show_bug.cgi?id=593282 to use a new
> id-generation scheme. Personally I don't think it will work, as
> people would need to know about it when setting up their docs. If
> they change it later, the break eventually existing xrefs.
> 
> 3) We can wait for a hypothetical gtk-doc-2.x and break the links
> then. This is imho not much different from 1) from the users
> perspective.
> 
> In my opinion we should
> - design a better id-scheme with minimal breakage in mind. for that
> I'd suggest to prefix document structure ids. the rational is that
> those where not officially documented and I don't believe people
> explicitly link to them a lot.
> 
> - if possible have a quirks mode, that could catch link which got
> broken, rewrite and warn about them
> 
> - once we know about the potential impact, propose the change on
> desktop-devel list
> 
> How does that sound?

I agree the doc structure ids are the ones to be mangled. gtk-doc has
multiple backends so I'd like to know if with "id" the HTML4 should be
taken as reference [1] or there is some additional restriction.

Care must be taken: simply prefixing the docs id with "DOC:" will
likely give troubles in the tag side, where the properties are
specified with #GObject:property (and so an object named DOC will break
everything). Of course this is a corner case, but it can be easily
avoided (using "DOC-:" or "DOC:::", for example).

I'd choose the option 3) and go for a later breakage, following the
rule "if you need to break something, do it badly or don't do it".
GTK+3 is on the road and maybe some incompatible change could be
useful. Furthermore, I'd like to have a completely new tag to link to
documentation sections: doxygen has \ref [2] while PhpDocumentor has
@tutorial [3] with his baggage of conventions. This would have the
great advantage the doc prefix (or whatever choosed) can be hidden as
implementation detail, leaving the option to change/improve it in a
later time without breaking anything.

Ciao.
-- 
Nicola

[1] http://www.w3.org/TR/html4/types.html#type-name
[2] http://www.stack.nl/~dimitri/doxygen/commands.html#cmdref
[3] http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.tutorial.pkg.html