FFFF
Skip to content

Fix requirements on authoring semantics in MO documents - #2089

Merged
mattgarrish merged 8 commits into
mainfrom
fix/issue-2066
Mar 25, 2022
Merged

Fix requirements on authoring semantics in MO documents#2089
mattgarrish merged 8 commits into
mainfrom
fix/issue-2066

Conversation

@mattgarrish
@mattgarrish mattgarrish commented Mar 17, 2022 •
edited by pr-preview Bot
Loading
Copy link
Copy Markdown
Member

This is my best attempt to solve #2066 as minimally as possible. The PR:

  • removes the bullet about adding semantics from the requirements section because the first bullet already allows semantics to be added since the method of adding them is part of the schema definition (specifying things twice is how these mismatches always arise). Section 7.3.3 also already covers adding semantics with the correct normative requirements.
  • adds "MAY" statements for using the lists of semantics we previously called out for skippability and escapability. This improves our eventually raising support of skippability and escapability to recommendations in the accessibility specification
  • moves the lists of semantics up above the examples in the skippability and escapability sections. It's odd to reach an example of implementing the features before knowing what the semantics to use are.
  • adds a paragraph to the RS specification for skippability to require that reading systems suppress playback of par/seq elements with matching semantics. All we were requiring was that reading systems should look and see if there are semantics to determine whether to enable skippability. I'm not sure if I have the best wording for this, though, so feedback welcome.

I also had to make some fixes to the markup of the RS spec, as I was getting errors. There was a missing end tag and part of an opening tag was missing, so we were getting an attribute in the source. (Fixed these in main.)

Anyway, let me know if I've got this right or if there's more that needs fixing.

Fixes #2066

Preview | Diff

@mattgarrish
fix requirements on authoring semantics in MO documents;
b05afcf 
add requirement to skip structures to RS spec
@marisademeglio
marisademeglio commented Mar 17, 2022
Copy link
Copy Markdown
Contributor

So overall, using structural semantics to enable RS behaviors is a MAY, but in MO it's a SHOULD. Do these need to align?

Typo in the core spec in 2 places (skip note and escape note):
" to support for skippability" => "to support skippability"

All in all, though, it looks much better!

10000

@mattgarrish
mattgarrish commented Mar 17, 2022
Copy link
Copy Markdown
Member Author

So overall, using structural semantics to enable RS behaviors is a MAY, but in MO it's a SHOULD.

I guess the argument is we don't define anything for reading systems to do with structural semantics in the content, so that can't change without standardizing something.

But for MO we do define at least two features (with table mode in a note), but it's optional to author the semantics. There's a usual argument there for making the RS requirement match the authoring.

Then again, the difference between a MAY and SHOULD is pretty small. You're just supposed to have a good reason not to implement a SHOULD, but who's checking?

There may be implications for the Accessibility spec in the future if authoring of the semantics increases to a recommendation, but presumably we'd could update both documents.

I can live with either, in other words, so I'll let others weigh in on preferences.

@iherman
iherman commented Mar 18, 2022
Copy link
Copy Markdown
Member

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

  • no resolutions were taken
View the transcript

1. Media overlay semantics (issue epub-specs#2066)

See github issue epub-specs#2066.

Wendy Reid: you may have noticed a flurry of new issues logged due to people reviewing spec.
… we have a normative statement that MO SHOULD use semantics when appropriate, and we do not clarify what we mean by semantics, or what semantics to use.

See github pull request epub-specs#2089.

Wendy Reid: mgarrish has discussed with danielwreck and marissa, and put together a PR.
… to clean up the language in that section, particularly dropping SHOULD to MAY.
… we can't drop the statement altogether, but SHOULD is a little strong in this case.
… and to specify that we are talking about footnote, endnote, page break.
… now we have something that could technically be tested (although it is not a required feature, we are discouraging use of epub:type).
… there is also a small addition to the RS spec to make similar clarifications there.
… questions?.

Murata Makoto: this changes both Core and RS, right?.

Wendy Reid: yes.
… the change to RS is barely a change, it keeps the normative statements but offers a little more information about what the RS should be doing.

Murata Makoto: mgarrish dropped one bullet in EPUB 33 core?.

Wendy Reid: he changed one SHOULD to MAY, and both escapability and skippability are better defined. It should be in the PR.

Murata Makoto: seems sensible, but I haven't reviewed the details.

Wendy Reid: to clarify, he dropped the SHOULD, and made the following statement a MAY.

Murata Makoto: no objections, but 4 reviewers have proof read the proposed change?.

Wendy Reid: yes.
… I didn't know there was a going to be a PR in time for the meeting today, mgarrish was ahead of schedule.
… we will have to close this issue soon (within the next week or so) so if you have an interest in this please review the PR.

@iherman iherman mentioned this pull request Mar 18, 2022
Closed
@avneeshsingh
avneeshsingh commented Mar 18, 2022
Copy link
Copy Markdown

I am concerned with the following note, because we have still not completely moved Media Overlays from epub:type to DPUB ARIA roles. Plus EPUB accessibility provides recommendation to implement skippability and escapability.
"Reading System are not required to support for skippability based on epub:type values."

In this statement, which is present in both skippability and Escapability section, we should also direct people to section in EPUB accessibility, which provides additional recommendations for Skippability and Escapability.

@mattgarrish
mattgarrish commented Mar 18, 2022
Copy link
Copy Markdown
Member Author

I am concerned with the following note, because we have still not completely moved Media Overlays from epub:type to DPUB ARIA roles.

I wasn't sure why we had the note for escapability but not for skippability, so included with both. Can we drop it entirely?

I don't think it's about how we support the features, but just seems to be a caution that even if you do add semantics it's not required RSes do anything. But that's true for lots of things.

@avneeshsingh
avneeshsingh commented Mar 19, 2022
Copy link
Copy Markdown

+1 to removing the notes. No need to add text for EPUB Accessibility if notes are removed.

@mattgarrish
mattgarrish commented Mar 20, 2022
Copy link
Copy Markdown
Member Author

No need to add text for EPUB Accessibility if notes are removed.

No, this PR better sets up the recommendations of the accessibility spec. We don't need to change anything in that document.

@mattgarrish
mattgarrish commented Mar 25, 2022
Copy link
Copy Markdown
Member Author

Are you okay with the changes in this pull request now @avneeshsingh ?

@mattgarrish
mattgarrish merged commit e841576 into main Mar 25, 2022
@mattgarrish
mattgarrish deleted the fix/issue-2066 branch March 25, 2022 11:15
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@danielweck danielweck Awaiting requested review from danielweck
@marisademeglio marisademeglio Awaiting requested review from marisademeglio
@GeorgeKerscher GeorgeKerscher Awaiting requested review from GeorgeKerscher
@avneeshsingh avneeshsingh Awaiting requested review from avneeshsingh

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Media overlay semantics

4 participants

@mattgarrish @marisademeglio @iherman @avneeshsingh
0