sgml-id / xml-id and namespaces

[Stefan Kost <ensonic hora-obscura de>]

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?

Stefan