search

w3c / wpub

W3C Web Publications
https://w3c.github.io/wpub/
Other
78 stars 19 forks source link

linking to multiple manifests #189

Closed dauwhe closed 5 years ago

dauwhe commented 6 years ago

In our section on linking to manifests, we say that a resource might link to several manifests.

When a resource links to multiple manifests, a user agent MAY choose to present one or more alternatives to the end user, or choose a single alternative on its own. The user agent MAY choose to present any manifest based upon information that it possesses, even one that is not explicitly listed as a parent (e.g., based upon information it calculates or acquires out of band). In the absence of a preference by user agent implementers, selection of the first manifest listed is suggested as a default.

In our steps to obtain a manifest, we say that we always use the first manifest link.

From the Document of the top-level browsing context, let origin be the Document's origin, and manifest link be the first link element in tree order whose rel attribute contains the token publication.

Is this a problem?

danielweck commented 6 years ago

wording issue?

a user agent MAY choose to present one or more alternatives to the end user, or choose a single alternative on its own.

"one or more" already includes "or ... a single"?

iherman commented 6 years ago

Is this a problem?

It is:-) Part of the draft defines a unique choice for the manifest, whereas the general text leaves it to the UA which one to choose among, possibly, several.

What was the reason of allowing several manifests? I do not remember...

HadrienGardeur commented 6 years ago

We'll need to balance things out between two requirements:

The current steps for obtaining a manifest are inherited from the WAM, which is designed to work with a single manifest.

BigBlueHat commented 6 years ago

We'll need to balance things out between two requirements

Where were these defined as requirements? If they're not defined, maybe they should be. Regardless, they also shouldn't be stated as requirements unless they are indeed requirements that the WG has agreed to. If they have been agreed to, and are indeed requirements, then they need to be specified as such.

If these are not requirements, then please consider saying "balance things out between [these] two [assumptions]" (or similar).

It's becoming confusing what we've agreed to as requirements and what's being stated as opinion or assumption, but with requirement-grade language.

Thanks.

HadrienGardeur commented 6 years ago

We've discussed this in the past multiple times, they were beyond "assumptions".

deborahgu commented 6 years ago

Well, I see we do say

While this specification will provide implementation flexibility for user agents, there are still a number of areas that have been identified as potentially needing to be detailed. These include [...] resources that belong to more than one Web Publication.

Which I take as a tacit acknowledgement that we know it's a requirement and we know we haven't specced it out yet.

deborahgu commented 6 years ago

And the other appears to be phrased as SHOULD right now:

Resources SHOULD provide a link to the manifest of the Web Publication to which they belong to enable discovery.

deborahgu commented 6 years ago

For what it's worth, this seems like a sensible breakdown. Not all resources should link to the manifest of the web publication to which they belong because they could belong to many, possibly including some that aren't under control of the resource's owner (eg. course packs). But:

if a resource is a component of a canonical parent (eg. a single chapter of Middlemarch), and if the owner of the resource wants readers of the resource to know about the canonical parent (as with a chapter of a novel or an article in an issue of a periodical), then the resource should enable discovery of the publication.

BigBlueHat commented 6 years ago

@deborahgu however, I think the question here is around what happens when that chapter of Middlemarch MAY also reference multiple editions' manifests (or publication addresses or whatever). And, if/when it does, what happens when the UA finds that information out?

deborahgu commented 6 years ago

That is the key question in this issue, true, @BigBlueHat. Though it makes me think there should be a separate issue that the 'SHOULD' in

Resources SHOULD provide a link to the manifest of the Web Publication to which they belong to enable discovery

Definitely needs to become a MAY.

TzviyaSiegman commented 6 years ago

I was recently reminded of the specific definition of SHOULD:

This word, or the adjective "RECOMMENDED", mean that there may exist valid reasons in particular circumstances to ignore a particular item, but the full implications must be understood and carefully weighed before choosing a different course.

See https://tools.ietf.org/html/rfc2119.

If this remains a SHOULD, we need to explain the exceptions to the rule.

mattgarrish commented 6 years ago

I'd just note that our desire for multiple manifest links and WAM's exclusion of all manifests in preference to the first one found (regardless of whether it actually points to a manifest) was noted here last fall: https://github.com/w3c/wpub/wiki/Options-for-Processing-a-Manifest

If this remains a SHOULD, we need to explain the exceptions to the rule.

I'd recommend not taking this approach. The "should" needs to be clear what it facilitates. The reasons anyone would ignore the recommendation are too varied to try and pin down. In this case, the statement says you should provide the link for discovery. If that's not important to you, or possible, for whatever reason, you already know what you're giving up.

mattgarrish commented 6 years ago

And for the record, I have no issue with a "may" here. We require a link from the entry page, which generally makes the "should" here unnecessary. It probably should have been bumped down another notch when we made that decision, as I recall at one time this was a "must".

iherman commented 5 years ago

This issue was discussed in a meeting.