Separate collection authoring from specialization requirements

[mattgarrish]

The collection element definition is hard to read because it mixes authoring requirements with requirements on how to write types of collections (which are largely all untestable by a validator).

This PR splits out the requirements on defining new types into a separate section so it's less of a jumble.

It's kind of weird to define so many requirements on how to write specializations in the core spec, as these have nothing to do with authoring, but short of a note on how to write specializations to move these out of the core, I don't what else to do with this prose.

---

Preview | Diff

[mattgarrish]

One thing I forgot is that I added "w3.org" to the ban on host components for the identifier URLs. Same thing we did for custom attributes.

[iherman]

I agree that this is much more readable.

However... to make the long story short, shouldn't we declare § 2.3.8.2 as non-normative?

There are indeed a bunch of things there that are weird if I look at this as a standard text:

• it talks about 'EPUB sub-specifications' but we have not defined what they are
• the introductory note talks about non-maintained registries, but the text say that this specification reserves the use of NMTOKEN values. What is "this specification" in this context? What about the sub-specifications? Shouldn't the NMTOKEN be reserved for, say, specifications defined by W3C then?
• We have a bunch of MUST and MUST NOT statement that must be formally tested in case this section is normative
• How to I test the last paragraph's MUST statements? Are those enforceable?

I believe all this go away if we define this as non-normative, and we turn all the statements into plain English instead of BCP14...

[mattgarrish]

• it talks about 'EPUB sub-specifications' but we have not defined what they are

It's referring to all these things: https://idpf.github.io/epub-registries/roles/

The restriction was that they had to be developed by IDPF.

• What is "this specification" in this context? What about the sub-specifications?

Ya, that's the connection. The registry used to be a normative part of the specification, so if they weren't defined in the registry you couldn't use them.

I believe all this go away if we define this as non-normative, and we turn all the statements into plain English instead of BCP14...

That's what I was thinking of doing at first, but if the statements aren't normative then how are they rules on making collection types? Can you ignore the section and make a new collection with idpf.org in its URL, since it's not a hard requirement? That's what's weird about having this section in the core spec.

I'd like to go further than a note that collections are no longer being maintained to deprecating the creation of new ones. It doesn't quite fit with our definition of deprecation, but it would allow us to drop all the prose and simply refer people back to 3.2 for the rules on how to make them. Would that work?

I hate spending time on mostly dead features... 😒

[mattgarrish]

For the record, deprecating the creation of new types wouldn't deprecate the collection element or existing types, so we'd sidestep any epubcheck reporting issues.

[mattgarrish]

I've just pushed a major strip down of the sections to show what I mean. It deprecates creation of new types and removes all the generic authoring requirements and refers authors to the specifications that define collections (the note acts as a guide to those).

[iherman]

(This is a comment on the latest, radically stripped version.)

• The collection element, itself, is not deprecated, only the process of defining collection types. I think that, therefore, it is worth salvaging the Example 41 which used to be at the very end of the section.
• (This may be a general thing for the document) the reference to the EPUB3.2 goes to the full EPUB 3.2 document; to save some extra steps, maybe it is worth linking to the relevant section directly, too, ie, to https://www.w3.org/publishing/epub32/epub-packages.html#sec-pkg-collections

None of these are critical; I am fine with the change proposal either way.

[mattgarrish]

• I think that, therefore, it is worth salvaging the Example 41 which used to be at the very end of the section.

What bothers me about it is it doesn't define a real collection, as the element obviously had to precede the specs that implement it. If we need an example, it might be worth bringing one in from one of the specs that became an IDPF recommendation, like previews or indexes, with a reference across to the one we choose.

• the reference to the EPUB3.2 goes to the full EPUB 3.2 document; to save some extra steps, maybe it is worth linking to the relevant section directly

Ya, I was about to do that and then checked to see how the other deprecated elements were done and saw that none go to specific locations. I wasn't sure if we did that intentionally to make it even harder for authors to stumble on deprecated practices. I'm fine linking them to specific sections, though.

[iherman]

• I think that, therefore, it is worth salvaging the Example 41 which used to be at the very end of the section.

What bothers me about it is it doesn't define a real collection, as the element obviously had to precede the specs that implement it. If we need an example, it might be worth bringing one in from one of the specs that became an IDPF recommendation, like previews or indexes, with a reference across to the one we choose.

I trust you an that (as well:-)

• the reference to the EPUB3.2 goes to the full EPUB 3.2 document; to save some extra steps, maybe it is worth linking to the relevant section directly

Ya, I was about to do that and then checked to see how the other deprecated elements were done and saw that none go to specific locations. I wasn't sure if we did that intentionally to make it even harder for authors to stumble on deprecated practices. I'm fine linking them to specific sections, though.

Are there many of those? If it is a lot of work, it may not be worth it. I let you decide, but if you need some extra hands, I can help (next week)

[mattgarrish]

I let you decide, but if you need some extra hands, I can help (next week)

I've fixed the one section for this PR. Will open an issue to find and fix the others. Feel free to take it on whenever you have time. March break here this week, so will have less time to get to issues.

[mattgarrish]

We should probably get a WG resolution before merging this one, as formally deprecating the creation of more collections isn't something we've discussed.

[iherman]

The issue was discussed in a meeting on 2022-03-25

List of resolutions:

• Resolution No. 3: Merge PR 2060, deprecate collections.

View the transcript

3. Separate collection authoring from specialization requirements (pr epub-specs#2060)

See github pull request epub-specs#2060.

Ivan Herman: See Diff file for the PR.

Matt Garrish: in reviewing this part of authoring spec, found that this was defining how to create collections.
… initially what I did was take user requirements about how to create these collections and moved them into a separate subsection.
… from there ivan and I discussed, and the question was that if we're not using collections anymore (and even the ones that have been authors have not met with huge uptake) can we deprecate the authoring of new collection elements?.
… then we wouldn't need to have all these weird requirements about authoring new collections.
… we already had a note saying that we had no intention of continuing these, so is it okay to officially deprecate the authoring of new collections?.

Dave Cramer: but we keep the existing ones.

Matt Garrish: yes, anything already created stay valid, there will not be issues with epubcheck.
… but you should not be creating new collection roles.

Tzviya Siegman: reading back into history of collections, I'm very much in agreement that this should be removed.
… we were optimistic, but real world implementation was never a certain thing.

Matt Garrish: the whole collection element was complicated, cases of collections within collections, complications to spine, etc..
… i just want to make it clearer than the note that we're not moving towards this in the future.

Wendy Reid: i don't think i've ever seen this in the real world.

Dave Cramer: did the index spec refer to this?.

Matt Garrish: there are a lot of specs that refer to collections, but they were just never really authored.

Proposed resolution: Merge PR 2060, deprecate collections. (Wendy Reid)

Matt Garrish: and anything that did rely on this would still be valid.

Matt Garrish: +1111111111111111.

Charles LaPierre: +1.

Ivan Herman: +1.

Wendy Reid: +1.

Rick Johnson: +1.

Tzviya Siegman: +1.

Dan Lazin: +1.

Ben Schroeter: +1.

Masakazu Kitahara: +1.

Matthew Chan: +1.

Laura Brady: +1.

Bill Kasdorf: +1.

Dave Cramer: +1.

Zheng Xu (徐征): +1.

Resolution #3: Merge PR 2060, deprecate collections.