Handling backward compatibility of fragment identifiers

[plehegar]

Element identifiers in the HTML markup can be changed for various reasons:

1. the editing tooling changes its ID conventions
2. the editor change the title of a definition or a section, triggering an ID change in the editing tool
3. the editor changes the id attribute of an element directly

This breaks links on the Web, whether it is from other specifications or from third parties documentation sites (stackoverflow, etc.) and our users/readers get frustrated.

We need:

1. Editing tool should facilitate backward compatibility support for old identifiers (using a data-id-something-something attribute or so?)
2. fixup.js could provide an easy way to help the mapping
3. editors guidelines if an old identifier has to be mapped to several (eg a subsection or definition gets split into 2 new ones)
4. pubrules need to generate warnings when you loose a identifier from one publication to the next.

@tabatkins @marcoscaceres for feedback/comments.

[tabatkins]

Bikeshed has a Required IDs metadata, added at the request of WHATWG, that lets you ensure that referenced IDs don't die over time. (It generates a fatal error if it can't find the specified IDs.)

You can also use the oldids="foo, bar" attribute on an element to mark that it previously went by different IDs (it inserts <a name/> elements into the output element's content).

pubrules need to generate warnings when you loose a identifier from one publication to the next.

This would be nice. I don't yet have a plan on how to maintain build information between Bikeshed invocations, so as to detect these sorts of changes. At minimum, publication is a good checkpoint for these sorts of things, so pubrules would be a nice spot for it.

[plehegar]

when running bikeshed, you could also compare the list of current IDs with the list of IDs coming from the specref database. This would avoid having to maintain a list of required IDs.

[marcoscaceres]

So, adding empty <a name=""></a> or <span id=""></span> elements into the markup seems kinda ugly/1996, but I guess it does have the advantage in not requiring any JS to do the mapping.

I don't mind either solution tbh.

[tabatkins]

when running bikeshed, you could also compare the list of current IDs with the list of IDs coming from the specref database.

SpecRef has no such list of IDs.

[fantasai]

If IDs have changed, that's a problem that should be fixed in the source document, e.g. through Bikeshed's oldids feature. It is not a progressive enhancement. It does not belong in fixup.js.

[fantasai]

Note: Bikeshed requires headings to have explicit IDs rather than generating them from the title text to make it easier to keep those IDs stable over time. This is a best practice, and all editors should be following it.

[marcoscaceres]

Note: Bikeshed requires headings to have explicit IDs rather than generating them from the title text to make it easier to keep those IDs stable over time. This is a best practice, and all editors should be following it.

Agree that's best practice... I guess ReSpec should warn about this. However, it's not just headings, names of algorithms, concepts, etc. that I personally find are the problem... I guess any dfn can be at fault.

[tabatkins]

Definitions don't usually change their text, so auto-gen IDs are a lot more reliable there than in headings.

But when they need to remain present unchanged, that's what Required IDs metadata is for. ^_^

[marcoscaceres]

Filed https://github.com/w3c/respec/issues/1716 on ReSpec.