Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Report deprecated epub:type values #531

Closed
mattgarrish opened this issue May 4, 2015 · 14 comments
Closed

Report deprecated epub:type values #531

mattgarrish opened this issue May 4, 2015 · 14 comments
Assignees
@rdeltour
Labels
spec: EPUB 3.2 Impacting the support of EPUB 3.2 status: completed Work completed, can be closed type: improvement The issue suggests an improvement of an existing feature
Milestone
4.2.0-beta

Comments

@mattgarrish
Copy link
Member

We should add a sch to warn about the use of marginalia, sidebar, warning, annotation/annoref and note.
@tofi86 tofi86 added the type: improvement The issue suggests an improvement of an existing feature label Jan 2, 2017
@tofi86
Copy link
Collaborator

tofi86 commented Jan 3, 2017

You mean those types marked with [deprecated] at https://idpf.github.io/epub-vocabs/structure/, right? There's two more then:

  • help
  • rearnote

plus the ones you mentioned before:

  • marginalia
  • sidebar
  • warning
  • annotation
  • annoref
  • note

Is this deprecated in EPUB 3.1 only, or already in 3.0.1?

@mattgarrish
Copy link
Member Author

It applies to all versions; the vocabulary isn't specific to revisions to allow it to change.

The changes overlapped with 3.1, but came from separate work we were doing with the W3C's WAI group to clean up the vocabulary (part of creating the Digital Publishing module).

@nekennedy
Copy link

Adding two additional deprecations to this list, to avoid duplication of tickets:
subchapter
rearnotes (plural)

@tofi86 tofi86 added the epub-3.1 label Nov 2, 2017
@mattgarrish
Copy link
Member Author

Noting that some of these are replaced by new semantics that need to be added:

  • help -> tip
  • rearnote -> endnote
  • rearnotes -> endnotes

@mattgarrish mattgarrish mentioned this issue Jan 29, 2018
Closed
@mattgarrish
Copy link
Member Author

Closing this issue as it is no longer valid. Validation of epub:type is removed in 3.2.

This was referenced Nov 12, 2018
Closed
Closed
@mattgarrish
Copy link
Member Author

Re-opening, as we should emit a notification if terms outside of the SSV are used, so we'll still need to update the vocabulary list.

I'm not sure what this means in terms of deprecation of terms within the SSV. Maybe they should be a similar level of notification?

@mattgarrish mattgarrish reopened this Jan 23, 2019
@mattgarrish mattgarrish added spec: EPUB 3.2 Impacting the support of EPUB 3.2 status: accepted Ready to be further processed labels Jan 23, 2019
@laudrain
Copy link
Collaborator

Publishers using extensively SSV vocabulary in epub:type should be warned of deprecation and of values outsides SSV, even if it is allowed in 3.2.

@mattgarrish
Copy link
Member Author

Just to compile up everything noted in this issue.

The following are new:

  • tip
  • endnote
  • endnotes

The following are deprecated (with replacement in parentheses):

  • annoref (open annotations)
  • annotation (open annotations)
  • help (tip)
  • marginalia (aside element)
  • note (footnote or endnote)
  • rearnote (endnote)
  • rearnotes (endnotes)
  • sidebar (aside element)
  • subchapter (-)
  • warning (notice)

@mattgarrish
Copy link
Member Author

And for the record, we will only warn about deprecated terms that are defined in the structural semantics vocabulary.

If a term is not specified in the vocabulary, that will be reported as a usage message because such use is only "discouraged", which carries no normative weight.

@mattgarrish mattgarrish reopened this Jan 23, 2019
@rdeltour
Copy link
Member

Btw, I assume that the SSV terms that are deprecated in Content Documents but allowed in Media Overlays (e.g. table, list, and figure terms) should also be reported as warning?

@mattgarrish
Copy link
Member Author

I would throw errors on them unless they are applied to their matching element, like:

<table epub:type="table">

in which case you could warn that they are deprecated.

They were only created for Media Overlays to identify their corresponding structures in XHTML, and if they are used on any other element they would violate this requirement in the SSV:

Authors may use the properties on HTML markup elements not specifically listed, but must ensure that the semantics they express represent a subset of the carrying element's semantics and do not attach an existing element's meaning to a semantically neutral element.

@rdeltour
Copy link
Member

I would throw errors on them unless they are applied to their matching element

I understand the rationale, however:

  • this would create inconsistencies with how we report other deprecated properties
  • checking this may be more complex than it seems, as we would only need to check the element, but its semantics which can be overridden by ARIA roles. This sound perhaps like getting too far down the rabbit hole for this non-critical check.
  • if we start checking semantics of carrying elements, then we should check it for all the properties, no?
  • are the may/must statements in the SSV intro even covered by RFC2119?

@mattgarrish
Copy link
Member Author

  • this would create inconsistencies with how we report other deprecated properties

Ya, but deprecated doesn't mean what it does for the other properties. Like I mentioned in the other issue, what is really being said is "not allowed". I would personally prefer to throw an error on any usage of them.

@rdeltour
Copy link
Member

deprecated doesn't mean what it does for the other properties. Like I mentioned in the other issue, what is really being said is "not allowed".

Right, I agree (I had replied to this one before seeing your comment in the other issue).

I would personally prefer to throw an error on any usage of them.

Yes, that removes the complexity of checking the semantics of the carrying element, so it's reasonably straightforward to implement. That's also the expected behavior if we change "deprecated" to "not allowed" as a result of w3c/epub-specs#1222, so SGTM!

@rdeltour rdeltour self-assigned this Feb 4, 2019
@rdeltour rdeltour added this to the 4.2.0-beta milestone Feb 4, 2019
@rdeltour rdeltour added status: in progress The issue is being implemented by the development team and removed status: accepted Ready to be further processed labels Feb 4, 2019
@rdeltour rdeltour mentioned this issue Feb 5, 2019
Closed
rdeltour added a commit that referenced this issue Feb 5, 2019
@rdeltour
feat: implement Structure Semantics Vocab changes for EPUB 3.2
3454da5 
Fix #531, Fix #903, Fix #962, Fix #963

New messages:

- `OPF-086` (`WARNING`) is reported when a deprecated property is used
  (e.g. in an `epub:type` attribute).
- `OPF_086_SUG.<property-name>` messages store the suggested replacement
   for deprecated properties.
- `OPF-087` (`ERROR`) is reported when a disallowed property is used
  (e.g. `epub:type` properties disallowed in an XHTML context).
- `OPF-088` (`USAGE`) is reported when an unprefixed property isn't
  recognized as defined in the EPUB Structural Semantics Vocabulary.

EPUB Structural Semantics Vocabulary changes:

- recognize the new properties `endnote`, `endnotes`, and `tip`.
- deprecate the properties `annoref`, `annotation`, `help`, `marginalia`,
 `note`, `rearnote`, `rearnotes`, `sidebar`, `subchapter`, and `warning`.
- disallow on XHTML Content Documents the properties `figure`, `list`,
 `list-item`, table`, `table-cell`, and `table-row`.

Internal Vocabulary changes:

- new unchecked vocab `PRISM_VOCAB` in the `ForeignVocabs` collection
- new vocab `MagazineNavigationVocab`, currently as an unchecked vocab
- new unchecked vocab `UNCHECKED_VOCAB` in `StructureVocab`, associated
  to the SSV URI, to accept properties undefined in the SSV.
- update the `EPUB_TYPES` StructureVocab to set the deprecate/disallowed
  status its properties
- register the reserved prefixes `msv` and `prism` as unchecked vocabs
  in Content Documents
- allow undefined properties in `epub:type` (by adding the SSV unchecked
  vocab to the default aggregated vocab)

Internal API changes:

- in the `Property` class:
  - new method `getVocabURI` to get the URI string of the vocab where
    the property is defined
  - new method `isDeprecated` to get if the property is deprecated.
  - new method `isAllowed(Validation context)` to get if the property
    is allowed in the given validation context.
- new interface `PropertyStatus`
  - holds the deprecated/disallowed status of a property, as getter methods
  - provides static implementations for 'allowed', 'deprecated', and
    'disallowed on Content Documents'.
- in the `VocabUtil` class:
  - the `parseProperty*` methods now use a `ValidationContext` parameter
    instead of a `Report` parameter, to be allowed to query the allowed
    state of properties from the context.
  - the `parserProperty*` methods will now report `OPF_086` and `OPF_087`
    for deprecated and disallowed properties (resp.).
- in the `LocalizedMessages` class:
  - the method `getSuggestion(String id)` is now public
  - a new method `getSuggestion(String id, String key)` is available
    to get a keyed suggestion string for a specific message ID.
- new `ThrowingResourceProvider` class, implementing `GenericResourceProvider`
  to always throw an exception, to be used in tests.

Tests changes:

- renamed and add new tests for `epub:type` attribute values
- remove instances of deprecated `epub:type` properties in other tests
@rdeltour rdeltour mentioned this issue Feb 5, 2019
Merged
@rdeltour rdeltour added status: has PR The issue is being processed in a pull request status: completed Work completed, can be closed and removed status: in progress The issue is being implemented by the development team status: has PR The issue is being processed in a pull request labels Feb 5, 2019
@rdeltour rdeltour closed this as completed Feb 7, 2019
@rdeltour rdeltour mentioned this issue Mar 14, 2019
Closed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@rdeltour rdeltour

Labels
spec: EPUB 3.2 Impacting the support of EPUB 3.2 status: completed Work completed, can be closed type: improvement The issue suggests an improvement of an existing feature
Projects
None yet
Milestone
4.2.0-beta
Development

No branches or pull requests
5 participants
@tofi86 @rdeltour @mattgarrish @laudrain @nekennedy