Aligning EPUB terminology on outdated features with HTML5?

[iherman]

This question came up on the call of Nov. 19: "we’ve said “deprecate” in the past, but HTML spec uses various flavors of “obsolete”."

Here are the terms as they are used today in EPUB and HTML:

EPUB 3.3 terminology

The terms are formally defined in §A. of the EPUB 3.3 draft:

• A deprecated feature is one the Working Group no longer recommends for use in this version of the specification. […]

  • EPUB Creators SHOULD NOT not to use the feature in their EPUB Publications.
  • Reading Systems MAY support the feature.

  Validation tools SHOULD alert EPUB Creators to the presence of deprecated features when encountered in EPUB Publications.

• A legacy feature is one that the Working Group has retained only for authoring content that is compatible with versions of EPUB prior to 3.0.[…]

  • EPUB Creators MAY include the legacy feature for compatibility purposes.
  • Reading Systems MUST NOT support the legacy feature in content that conforms to this version of EPUB.

  Validation tools SHOULD NOT alert EPUB Creators about the presence of legacy features in an EPUB Publication, as their inclusion is valid for backwards compatibility. Validation tools MUST alert EPUB Creators if a legacy feature does not conform to its definition or otherwise breaks a usage requirement.

HTML5 Terminology

Alas!, I haven't found any formal description of the terms (see §16 Obsolete features) but the following can be filtered out of the text:

• Obsolete (but conforming): feature will trigger warnings in conformance checkers. For the listed features the statements are usually that "Authors should not specify…" and nothing is said on whether browsers would support a feature (however, in terms of backward compatibility, it is safe to believe that they would).

• Non-conforming features: "elements in the following list are entirely obsolete, and must not be used by authors". Nothing is said about RS-s; some features may have been kicked out of browsers, others may not.

---

Cc @dauwhe @wareid @mattgarrish

[iherman]

My personal conclusion:

1. It is possible for us to use "obsolete" or, more exactly, "obsolete (but conforming)" for features that are currently labeled as "deprecated".
2. I do not see the analogy of the EPUB 3.3 "legacy" label, because authors MAY use them in a publication, as opposed to the "must not" for non-conforming features. We should therefore retain the term.

Making a "deprecated"->"obsolete" change is just an editorial step, but may have some importance: an EPUB checker may use an up-to-date HTML checker to check the HTML content, and the error reports coming from that checker and from the EPUB checker itself should really use the same terminology wherever possible...

@rdeltour

[mattgarrish]

I'm not sure following HTML's model is ideal, as their obsolete features are removed from the specification (i.e., they don't exist anymore beyond the limited listing in the appendix). That's generally how they're understood, too, as relics from the past.

We tried doing similar in 3.1 by removing the features and only listing them in the appendix and it didn't go over well, so that's why they're back in the body but deprecated. (For the record, we also tried classes for "superseded" and "superseded and marked for removal" in 3.1, in addition to deprecated, and that didn't stick.)

Do we want to signal that we're removing the deprecated features, even if you can still author them, as that's the likely signal we send by changing names? I worry it's a hornet's nest that isn't worth revisiting.

I'm more curious to understand what happens to features that aren't "dead" -- in the sense we want to retain them -- but are discovered to not have two implementations. Do they become informative, are they thrown in the deprecated/obsolete dustbin, do we get hung up waiting for implementations, or something else?

[iherman]

I'm not sure following HTML's model is ideal, as their obsolete features are removed from the specification (i.e., they don't exist anymore beyond the limited listing in the appendix). That's generally how they're understood, too, as relics from the past.

We tried doing similar in 3.1 by removing the features and only listing them in the appendix and it didn't go over well, so that's why they're back in the body but deprecated. (For the record, we also tried classes for "superseded" and "superseded and marked for removal" in 3.1, in addition to deprecated, and that didn't stick.)

I think that is really an editorial issue. I do not think we should follow the HTML spec approach, and I am comfortable with what we have in 3.3. Furthermore, I do not think that HTML's "obsolete" features necessarily require that we adopt the editorial option they took. The question is really only naming, I would not propose to do anything else.

Do we want to signal that we're removing the deprecated features, even if you can still author them, as that's the likely signal we send by changing names? I worry it's a hornet's nest that isn't worth revisiting.

At some point in the future we will have to face this issue: what does really happen with deprecated features? Will we still carry them with us for eternity?

But I am not sure that this is something we have to decide now.

I'm more curious to understand what happens to features that aren't "dead" -- in the sense we want to retain them -- but are discovered to not have two implementations. Do they become informative, are they thrown in the deprecated/obsolete dustbin, do we get hung up waiting for implementations, or something else?

That is the main issue indeed, and I deliberately did not want to address it in this issue. We must answer this asap before going to CR, but I do not think we should mix this question with the issue of terminology.

[iherman]

I'm more curious to understand what happens to features that aren't "dead" -- in the sense we want to retain them -- but are discovered to not have two implementations. Do they become informative, are they thrown in the deprecated/obsolete dustbin, do we get hung up waiting for implementations, or something else?

That is the main issue indeed, and I deliberately did not want to address it in this issue. We must answer this asap before going to CR, but I do not think we should mix this question with the issue of terminology.

I have raised a separate issue for that (#1944).

[mattgarrish]

we will have to face this issue: what does really happen with deprecated features? Will we still carry them with us for eternity?

For all intents and purposes, the stuff we've "deprecated" are "obsolete" features of 3.1; we established that when we queried their use and support in 3.1.

Obsolete just says something a little stronger than deprecated, so I wouldn't make the change unless we're ready to stand by these features being effectively dead and really should not be authored anymore regardless of what support you may find in reading systems.

HTML's obsolete features are also described like a compromise for bringing forward HTML4 content. We don't have the same problem because we version EPUB at the package document level.

I do not think we should mix this question with the issue of terminology

Sure, I wasn't sure what the scope of this issue was. It sort of sounded in the last meeting like we were going to establish a single bucket to throw everything into.

[dauwhe]

Current status: NCX, guide, and OPF2 meta are legacy. bindings, switch, trigger, rendition:spread=portrait, and rendition:viewport are deprecated.

I think we should keep our current system. HTML is in a very different position, where the parsing and rendering of unknown or removed elements is well-defined. They also do not have an ecosystem that is entirely dependent on one validation tool.

[iherman]

The issue was discussed in a meeting on 2021-12-03

List of resolutions:

• Resolution No. 4: We will not be adopting the HTML terminology for risky features, close issue 1942.

View the transcript

#### 2.2. Aligning EPUB terminology on outdated features with HTML5? (issue epub-specs#1942) _See github issue [epub-specs#1942](https://github.com/w3c/epub-specs/issues/1942)._ > **Proposed resolution: We will not be adopting the HTML terminology for risky features, close issue 1942.** *(Wendy Reid)* > *Dave Cramer:* +1. > *Ivan Herman:* +1. > *Matt Garrish:* +1. > *Matthew Chan:* +1. > *Ben Schroeter:* +1. > *Brady Duga:* +1. > *Wendy Reid:* +1. > *Toshiaki Koike:* +1. > *Masakazu Kitahara:* +1. > *Bill Kasdorf:* +1. > *Avneesh Singh:* +1. > ***Resolution #4: We will not be adopting the HTML terminology for risky features, close issue 1942.***