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

The fragile position of the Primary Entry Page #61

Closed
llemeurfr opened this issue Nov 29, 2019 · 8 comments · Fixed by #90
Closed

The fragile position of the Primary Entry Page #61

llemeurfr opened this issue Nov 29, 2019 · 8 comments · Fixed by #90
Assignees

Comments

@llemeurfr
Copy link
Contributor

llemeurfr commented Nov 29, 2019

Now that the Web Publication spec is "on the side", we have 3 specifications in scope: Publication Manifest, Audiobooks and Lightweight Packaging Format.

Publication Manifest says nothing the concept of Primary Entry Page, which is logical.

LPF introduces the notion of Primary Entry Page and exposes a processing model for extracting the Manifest from the PEP if included. LPF will be a Note, and its use will not be mandatory for distributing Audiobooks, so we also have to write very clear information about the PEP in the Audiobooks spec.

Audiobooks introduces the notion of Primary Entry Page in a specific section but does not specify that it may embed the Manifest. There is only an illustration of that possibility in https://w3c.github.io/audiobooks/#example-16.

The wording of the spec can give the impression that the presence of a PEP is mandatory for audiobooks. The only thing that contradicts this impression is "The primary entry page should instead, if present, ...". The rule is much clearer in the ToC section ("a table of contents SHOULD be included;").

@mattgarrish
Copy link
Member

If it isn't mandatory, doesn't it make the specification dependent on LPF rules to locate the audiobook manifest, even though LPF itself isn't required?

I'm thinking we should change the last paragraph to something like:

The primary entry page is a REQUIRED resource except when an audiobook is packaged in a way that allows alternative discovery of the manifest. The primary entry page MUST be included in the resource list when present.

That makes an unpackaged audiobook consistent with pub manifest and allows a packaged audiobook to be consistent with LPF.

I think we can clarify the embedding issue simply enough by adding a link to the manifest discovery section in pub manifest to the first paragraph:

The primary entry page represents the preferred starting resource for an Audiobook and enables discovery of its manifest [[!pub-manifest]].

Not too late to make changes, is it @iherman @wareid ?

@iherman
Copy link
Member

iherman commented Sep 4, 2020

Not too late to make changes, is it @iherman @wareid ?

The question is whether the changes affects existing implementations. @wareid @marisademeglio @GarthConboy @larscwallin any comments here?

@llemeurfr
Copy link
Contributor Author

That makes an unpackaged audiobook consistent with pub manifest
you mean Web Publications I guess

Making the PEP required for online (I'm not fond on the work unpackaged in this case) audiobooks would be consistent with previous decisions of the WG on Web Publications (in https://www.w3.org/TR/wpub/#wp-resources).
And the access to the audiobook via its PEP is already handled by the different implementations (very soon by Thorium Reader), therefore it should not cause problems.
If this path if chosen, the sentence introducing this rule should be very clear and use the MUST word IMHO, like in the Web Publication spec.

The primary entry page MUST be included in the resource list when present.

This sentence is clearer than the current one in 4.1. But this rule is still making me uncomfortable.

The weirdest use of the Manifest -> PEP backlink is when the manifest is embedded in the PEP (see this sample) .

When you think about the discovery mechanism, the PEP is the entry point (it's the URL you'll give to a packager), the manifest is discovered via the PEP, the TOC is discovered via the manifest. From the manifest, there is no practical need to move back to the PEP. But still, the link to the PEP must be there; there is a loop PEP -> Manifest + Manifest -> PEP; with possible mistakes in this backlink.

ok, the PEP should be included in a generated package, and all resources of an Audiobook must by design be either in the readingOrder or the resources collection. But we could be smart and use the fact the a packager gets the PEP first to include it in a package even if it's not referenced in resources. The manifest would then be much leaner.

@mattgarrish
Copy link
Member

you mean Web Publications I guess

No, with publication manifest, as there still needs to be some established linking mechanism. Pub manifest defines linking and embedding as possible approaches, otherwise the implementation has to define how it's done. That's why I agree adding a link across to those methods is important here.

As written right now, by saying "when present", there's a big hole in terms of how the manifest is located outside of LPF. You can find it through the PEP, but only if the PEP is there. But it's valid (unconditionally) for no PEP to be present, in which case ... ?

But we could be smart and use the fact the a packager gets the PEP first to include it in a package even if it's not referenced in resources.

Right, I agree this is a nuisance. This is essentially what I asked in #75 . But I didn't get the issue in in time for CR and so I've put the postponed label on it as it affects the processing model, etc.

@mattgarrish
Copy link
Member

Perhaps a reformulation like this might be clearer:

The primary entry page is an HTML resource that represents the preferred starting resource of an Audiobook and enables discovery of its manifest. It typically introduces the audiobook and provides access to the content.

The primary entry page MUST either include a link to the manifest or embed the manifest [[!pub-manifest]]. It also SHOULD contain the table of contents.

An Audiobook MUST include a primary entry page except when packaging allows alternative discovery of the manifest. When present, the page MUST be included in the resource list.

@marisademeglio
Copy link
Contributor

Not too late to make changes, is it @iherman @wareid ?

The question is whether the changes affects existing implementations. @wareid @marisademeglio @GarthConboy @larscwallin any comments here?

I haven't implemented LPF support, so I don't think the proposed changes (as I understand them, and as of right now) impact me.

@GarthConboy
Copy link
Contributor

The proposed "changes" are consistent with our reading of the current spec, and our implementation of LPF. I kinda view "publication.json" as the preferred manifest location in LPF, so let's be sure not to push folks toward a PEP in that environment.

@mattgarrish
Copy link
Member

I've opened a PR with the above prose for review. Let's try and close this off quickly as we need to move on to the next stage.

llemeurfr added a commit to readium/readium-lcp-server that referenced this issue Jul 22, 2022
This issue is somewhat related to w3c/audiobooks#61. The Readium manifest converted from a W3C manifest references the W3C Primary Entry Page; it is therefore copied in the new package. No need for a specific treatment.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging a pull request may close this issue.

6 participants