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.

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

Added text on the behavior of RS when the same item is referenced multiple times in the spine. #1889

Merged
merged 4 commits into from Nov 12, 2021

Conversation

iherman
Copy link
Member

@iherman iherman commented Oct 31, 2021

See issue #1686, in particular the text
proposed by @bduga in #1686 (comment).

I have also made a bit more explicit in the core text that multiple references MUST NOT occur (semantically it is already in the text, but a little bit between the lines...)

See:

See:


Preview | Diff

Copy link
Member

@rdeltour rdeltour left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks OK to me, with the caveat that it only solves one aspect of #1686 (see my comment to #1686).

@@ -548,6 +548,15 @@ <h3>Spine</h3>
<p id="confreq-rs-pkg-spine-unknown" data-tests="#confreq-rs-pkg-spine-unknown">Reading Systems MUST
ignore all values expressed in spine <code>itemref</code>
<code>properties</code> attributes that they do not recognize.</p>

<p>
When presented with a single manifest item that is repeated multiple times in the linear flow of the spine,
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe replace When presented with a single manifest item [...] with When presented with a single <a href="https://www.w3.org/TR/epub-33/#dfn-publication-resource">Publication Resource</a> [...]

That should resolve the concern of @rdeltour since it won't limit this to duplicate spine references to a single item, and instead broadens the scope to resources. So it should implicitly cover two spine items with the same itemref, and two items (with different itemrefs) that resolve to the same resource.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I like that, @bduga, I have made the change.

epub33/core/index.html Outdated Show resolved Hide resolved

<p>
When presented with a single <a>Publication Resource</a> that is repeated multiple times in the linear flow
of the spine, Reading Systems SHOULD do their best to display that content in the correct location of that linear flow.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"do their best" isn't a testable assertion, so perhaps this could be removed so it reads "Reading Systems MUST display content in the correction location".

Progressing linearly through the spine shouldn't present a challenge to a reading system - it's only when trying to locate the document to render when linked into - so I would make this a "must" not a "should".

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I didn't like MUST since it seems to mandate UI. For instance, what if a RS allows for reordering of spine items by the end user (for instance, a cookbook where you could create your own recipe order). But the term "correct location" is so vague maybe it is ok to make this a must, I just don't want to make RS authors think they are not allowed to reshuffle content.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's kind of confusing, as we don't ever mention reordering the spine. It also talks about the linear flow of the spine and then refers back to "that linear flow".

I agree with you in principle about reordering, but I'm not sure the current wording is clear how the "should" relates to the default spine ordering.

Could we maybe flesh this out more like: "When presented with a single Publication Resource that is repeated multiple times in the spine, Reading Systems MUST render that content in each instance where it is referenced when presenting the default linear flow. If the Reading System allows reordering of the spine, it SHOULD attempt to retain a logical ordering of the repeated items relative to their default positions."

I'm not sure that last sentence makes a lot of sense, but maybe it doesn't need to?

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't really want to mention reordering, that was just an example of what we might be making unintentionally illegal. Maybe the problem is we are mandating how this particular content must be displayed, but instead we should be making it clear this content is no different from any other linear content. So something like:

For rendering purposes when presented with a single Publication Resource that is repeated multiple times in the linear flow of the spine, Reading Systems MUST treat those items as though they were unique item references.

Hmm... that's terrible. But I think we are getting in trouble trying to explain what to do with these, and instead should make clear that whatever a RS does, it should be the same as what they do for correct references.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

But I think we are getting in trouble trying to explain what to do with these

Right. Could we maybe generalize it to:

Reading Systems MUST NOT skip spine references to duplicate manifest items when presenting the linear flow, unless such references are marked as non-linear.

Is that the gist of what we're after?

(No discussion is ever complete without bringing in non-linear content!)

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That looks good to me! But I am not sure we need to specify the exception for non-linear since it says linear flow, so just Reading Systems MUST NOT skip spine references to duplicate manifest items when presenting the linear flow. Unless you want to bring up the fact that "linear flow" is never defined.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Unless you want to bring up the fact that "linear flow" is never defined.

True, and flow gets confusing with the rendering property. It'd be more precise to say "when rendering the linear reading order."

There are a number of other "linear flows" in this PR that should probably be fixed, then, too.

<p>
When presented with a single <a>Publication Resource</a> that is repeated multiple times in the linear flow
of the spine, Reading Systems SHOULD do their best to display that content in the correct location of that linear flow.
The Reading System SHOULD treat these as distinct pages for UI purposes (for example, each occurrence
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"distinct pages" sounds like it's referring to fixed layout pages / spreads. Maybe "items" or "instances" would be more appropriate, given that we're talking about spine items?

Isn't this also a "must" requirement, though? Why wouldn't it treat them as distinct items? The problem is that the user may not be at the document they expect, but the RS can't control that.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed, pages is a bad word here (assumes pagination, etc). Also fine with making this a MUST.

When presented with a single <a>Publication Resource</a> that is repeated multiple times in the linear flow
of the spine, Reading Systems SHOULD do their best to display that content in the correct location of that linear flow.
The Reading System SHOULD treat these as distinct pages for UI purposes (for example, each occurrence
could be independently bookmarked or annotated), but when following an internal link to that
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"internal link" is a ambiguous when talking about the reading system. Maybe make this clearer by adding the user action: "When a user activates a hyperlink to a resource that is referenced multiple times in the spine, the Reading System SHOULD ..."

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed "internal link" is not a great choice, but this is less about hyperlink activation and more about resolving the destination of a hyperlink (a RS may not allow following a hyperlink). Maybe:

When a Reading System follows a hyperlink to a resource referenced multiple times in the spine, the Reading System MUST [...]

That also lets us turn the SHOULD into a MUST.

@iherman
Copy link
Member Author

iherman commented Nov 9, 2021

@bduga @mattgarrish I believe I have incorporated all the changes you discussed in the latest commit (202058d). Just to be on the safe side, could you look at the changes again?

(I have also added <span> elements with ID-s around the three statements in the RS which are now all MUST-s and, therefore, will require three tests at least.)

@mattgarrish
Copy link
Member

Generally looks fine to me now. Only last thing is the RS spec should probably have a change log entry since we're adding new requirements.

@iherman
Copy link
Member Author

iherman commented Nov 11, 2021

Generally looks fine to me now. Only last thing is the RS spec should probably have a change log entry since we're adding new requirements.

It is there; have been added with the date of the 1st of November (when the PR was created).

@mattgarrish
Copy link
Member

Ah, so it is! I must have still had the core spec open when I looked for it. 😄

@iherman
Copy link
Member Author

iherman commented Nov 12, 2021

The issue was discussed in a meeting on 2021-11-11

List of resolutions:

View the transcript

4. Approve PRs.

See github pull request epub-specs#1889.

Dave Cramer: this is writing language for when should happen when same item is referenced multiple times in the spine.
… there are a bunch of approvals from reviewers over in github.

Matt Garrish: okay with me.

Proposed resolution: merge 1889. (Dave Cramer)

Dave Cramer: +1.

Matt Garrish: +1.

Brady Duga: +1.

Shinya Takami (高見真也): +1.

Victoria Lee: +1.

Matthew Chan: +1.

Toshiaki Koike: +1.

Masakazu Kitahara: +1.

Resolution #3: merge 1889.

@iherman iherman merged commit 682ac6f into main Nov 12, 2021
@mattgarrish mattgarrish deleted the multiple-item-1686 branch November 21, 2021 15:49
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Define what RS should do when the manifest has duplicate entries
6 participants