w3c / epub-specs

Shared workspace for EPUB 3 specifications.
Other
303 stars 60 forks source link

clarify what deprecation means for the creation of `collection` roles #2488

Closed rdeltour closed 1 year ago

rdeltour commented 1 year ago

Section "Defining collection types" says:

The creation of new collection element roles is now deprecated.

What does it mean exactly that the creation is deprecated? Does it mean to say that the use of any role not defined either in the registry of role extensions or as a known custom extension role is deprecated? If yes, then I think being explicit would be preferable.

Or would it even make sense to deprecate the collection element altogether? The RS spec says support for collection is OPTIONAL, so if we deprecate the element it won't change a thing (reading systems MAY support deprecated features).

mattgarrish commented 1 year ago

Does it mean to say that the use of any role not defined either in the registry of role extensions or as a known custom extension role is deprecated? If yes, then I think being explicit would be preferable.

That can't be done because we can't normatively refer to those documents.

The collection element on its own is pointless - it's always been a vehicle for creating specialized types. The section contained the rules you had to follow to create new types, which is what we've removed. Part of creating a new type of collection was to register a role, but since we're no longer supporting creation it effectively freezes the registry without having to normatively deal with it (i.e., what exists remains valid, but nothing new can be added).

From a validation perspective, epubcheck should only allow the existing registry values. The element is essentially a dead-end moving forward, so neither registry will be added to anymore.

Or would it even make sense to deprecate the collection element altogether?

We'd potentially invalidate content that uses collections if we did that. There may not be a lot of content that uses them, but there are a lot of specifications that depend on the element (indexes, glossaries, etc.).

rdeltour commented 1 year ago

From a validation perspective, epubcheck should only allow the existing registry values.

EPUBCheck currently allows the tokens in the default role registry and any absolute URLs. So that its behavior does not exactly match what you describe.

That said, I cannot exactly infer that statement from the current spec language?

Does it mean to say that the use of any role not defined either in the registry of role extensions or as a known custom extension role is deprecated? If yes, then I think being explicit would be preferable. That can't be done because we can't normatively refer to those documents.

Oh right.
Still, if we want the spec to enforce the limitation of only allowing the currently-known token and URLs, we could define the explicit list of allowed role values in the specification, and say that a collection with any other role is deprecated.

Like this:

The value of the role attribute MAY be an ASCII case-sensitive match for one of the following keywords:

  • dictionary
  • index
  • previews
  • … (other roles from the registry)
  • http://conets.jp/spec/epub/odp/role/units
  • http://conets.jp/spec/epub/odp/role/pageset
  • http://conets.jp/spec/epub/odp/role/page

Use of a collection element using a role attribute with any other value is deprecated.

mattgarrish commented 1 year ago

EPUBCheck currently allows the tokens in the default role registry and any absolute URLs.

Ya, that's fine. I forgot we allowed full URLs, but honestly I don't think anyone really cares about collections anymore. I don't think we need to worry that someone will get the idea to create their own custom URL against the advice in the spec, but it's up to you if you want to tighten epubcheck to the only registered values. I have a strong suspicion no one will notice whichever way you choose to go.

I don't want to dump a registry into the specification, though, as it could draw unwanted attention (i.e., it could end up requiring us to create a proper registry that we have no interest in maintaining). That's what we were deliberately trying to avoid.

rdeltour commented 1 year ago

ok, fair enough.
I still have a little itch with "the creation (…) is now deprecated" but I can definitely live with it.