Added text on the behavior of RS when the same item is referenced multiple times in the spine. #1889
Conversation
iherman
requested review from
bduga,
dauwhe,
HadrienGardeur,
mattgarrish and
wareid
There was a problem hiding this comment.
Looks OK to me, with the caveat that it only solves one aspect of #1686 (see my comment to #1686).
epub33/rs/index.html
Outdated
| @@ -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, | |||
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
I like that, @bduga, I have made the change.
epub33/rs/index.html
Outdated
|
|
||
| <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. |
There was a problem hiding this comment.
"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".
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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!)
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
epub33/rs/index.html
Outdated
| <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 |
There was a problem hiding this comment.
"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.
There was a problem hiding this comment.
Agreed, pages is a bad word here (assumes pagination, etc). Also fine with making this a MUST.
epub33/rs/index.html
Outdated
| 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 |
There was a problem hiding this comment.
"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 ..."
There was a problem hiding this comment.
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.
|
@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 |
|
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). |
|
Ah, so it is! I must have still had the core spec open when I looked for it. 😄 |
|
The issue was discussed in a meeting on 2021-11-11 List of resolutions:
View the transcript4. 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. Matt Garrish: okay with me.
|
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