Referencing specification series

Hello spec editors,

In short
--------
Thanks to a recent update to Specref, it has become possible to 
reference a W3C specification through its *series* shortname directly. 
For example `[[css-color]]` can now be used to reference the current 
specification in the CSS Color Module series (today, that is level 4).

In detail
---------
Various groups use levels for the specifications they develop. 
Shortnames of these specifications typically end with `-n`, as in 
`hr-time-3`. The W3C publication system automatically creates a 
level-less shortname for such specifications (the same shortname without 
the final `-n`). That shortname can be used to retrieve the *current* 
specification in the series, where *current* is whatever level the 
underlying working group asks to be returned.

Specref did not have any notion of specification series, and it was thus 
not possible to write a reference such as `[[css-fonts]]` to reference 
the current CSS Fonts Module. Various people (including me) have worked 
around this limitation by manually creating the specification series 
shortname as an alias in Specref. For example `[[media-source]]` 
returned `media-source-2` because I maintained an alias in Specref to 
that effect.

On top of requiring manual intervention, such workarounds were clumsy 
because transitions to a new level meant preserving version aliases that 
the initial alias created, requiring to create a lot of artificial 
entries manually. See [1] for a concrete example.

Specref now supports specification series out of the box. No need to 
create manual aliases anymore, and the specification series shortname 
will always return the *current* level (as known by the W3C publication 
system).

Two things worth noting:
1. Automatic updates to a new current level won't work for cases where 
an alias has been manually created as described above (or when the 
specification series shortname already exists in Specref for some 
reason). I'll look into converting these entries into the new automatic 
mechanism over time.
2. There is no way to reference a specific date through the 
specification series shortname. For example, `[[css-backgrounds]]` 
currently targets `css-backgrounds-3`, but 
`[[css-backgrounds-20110215]]` cannot be used to reference the 
`css-backgrounds-3-20110215` version. That is on purpose: if you're 
happy to reference the current specification, you should not need to 
reference a specific version! Use a full reference if you need that, 
such as `[[css-backgrounds-3-20110215]]`.

If you spot anything weird or missing, let me know!

François.

[1] https://github.com/tobie/specref/pull/834#issuecomment-2507632561

Received on Tuesday, 28 January 2025 10:21:23 UTC