Working out the manifest life cycle

[iherman]

This is a spin-off of #119: working out the details should help finalizing the relationship between the PW Manifest (a.k.a. PWM), the Readium Web Publication Manifest (a.k.a. RWPM, see #119) and, the Web Application Manifest (a.k.a. WAM).

[iherman]

Copying the comment of @HadrienGardeur:

I started a new document for the lifecycle at: https://github.com/readium/readium-2/blob/master/misc/W3C/lifecycle.md

This is based on the WAM lifecycle but the WebIDL and processing steps are going to be much simpler based on our current infoset.

[iherman]

@HadrienGardeur, first of all, thanks!

Some comments while reading through the draft

Obtaining a manifest

• The text refers to a "publication" context. I am not sure what that exactly means and, to be honest, I am also not sure what the "manifest" context means in the corresponding part of the WAM. However, the reference seems to go to the Fetch spec and that may lead to a problem: the Fetch spec includes already references to "manifest", as an "initiator", whereas, of course, there is nothing like that for "publication". If we go down that route, we may have to see/convince the WHATWG that we need an extra term.

• The WAM makes it clear (section 2) that the "installation" instantiates a new top-level browsing context. I wonder whether something similar should not be said, ie, that processing a WP means a new top-level browssing context. This is referred to in this section without further ado. I presume the idea is that the context is of the html-page-whose-name-is-disputed?

  Although... wouldn't that makes it impossible to display a book in an iframe? (I am on slippery grounds here, to be honest about it).

• The (separate) issue Do we consider a (JSON) manifest to be part of a <script> element #122 may have an influence on this section, obviously (if accepted, that is)

Processing the manifest

• I was a bit bothered by the term "spine", which is a term we (hitherto) did not use in the WP draft. I understand what is in this draft, but we may have to clean up the terminology usage.
• I know the language processing is just a placeholder and we will have to add it; however, note that the WAM equivalent is probably not good enough for the purpose of I18N because it does not talk about direction. Something to be cleaned up (later).

Processing the default reading order

• I guess this is an issue related to the RWPM but, for the purposes of the WPM the differentiation between the links and resources does not really exist. Ie, I am not sure the separation of entries (2) and (3) are relevant for WPM
• There should be a branch that terminates the algorithm in case both (2) and (3) fails to lead to a link
• Something that we may not have discussed but may be a valid question: do we allow for that <nav> element to be part of the html-page-whose-name-is-disputed that we are processing? If so, that should be accounted for in the processing step. (The WP document is not really clear on that subject.)

Conclusion

Quoting from the draft

• Obtaining a manifest for WP/RWPM is almost identical to the WAM

Indeed

• The life-cycle of a Web Publication requires a lot less processing than the WAM

We have to be fair. The WAM goes into all kinds of details about how to extract, say, "background color" and, if we followed that same style, we would have to do the same with some of the infoset elements (I am not sure we want to do that, I just say the comparison may not be fair). Ie, the complexity level is not really different. What is probably true is that the WAM includes a bunch of elements that are not really relevant for us (like that background color entry).

I think what is true is that the life-cycles are different.

• It also has very little in common with the processing requirements of the WAM (only language is similar)

I presume you mean issues like "applying the manifest" from the WAM, etc, that are not relevant. Or do you refer to other issues?

• The most complex part (by far) is the default reading order, since we allow its definition outside of the WP Manifest in a separate document

True. But the complexity of the user agent has a lower priority, in my view, than the complexity of the WP structure for authors. If the creation of the WP can be simplified even if this complicates the UA, then this should be of a higher priority (and the draft shows that this can be solved, albeit with some complexity).

I also wonder whether there are not some other entries in the WP that would not be relevant. From a cursory look, what about:

• Content security policy
• Navigation scope. I am not sure how that relates to our current information items like resource lists

[HadrienGardeur]

The text refers to a "publication" context. I am not sure what that exactly means and, to be honest, I am also not sure what the "manifest" context means in the corresponding part of the WAM. However, the reference seems to go to the Fetch spec and that may lead to a problem: the Fetch spec includes already references to "manifest", as an "initiator", whereas, of course, there is nothing like that for "publication". If we go down that route, we may have to see/convince the WHATWG that we need an extra term.

Right, and I included a note about this.

The WAM makes it clear (section 2) that the "installation" instantiates a new top-level browsing context. I wonder whether something similar should not be said, ie, that processing a WP means a new top-level browssing context.

There's a separate issue to discuss this (#104) but this is tricky indeed for multiple reasons.

I was a bit bothered by the term "spine", which is a term we (hitherto) did not use in the WP draft. I understand what is in this draft, but we may have to clean up the terminology usage.

This is not really terminology, I only use spine here because the WebIDL is ported from the RWPM. This references directly a member of the WebPublicationManifest dictionary.

I know the language processing is just a placeholder and we will have to add it; however, note that the WAM equivalent is probably not good enough for the purpose of I18N because it does not talk about direction. Something to be cleaned up (later).

There's another problem as well:

• in RWPM, language is meant to express the language(s) of the publication
• in WP and WAM, it's for the language of the metadata properties
• in RWPM, the language of specific properties is expressed at a property-level and is not limited to a single language

Here's an example in RWPM for the title that illustrates that difference:

"title": {
  "fr": "Vingt mille lieues sous les mers",
  "en": "Twenty Thousand Leagues Under the Sea",
  "ja": "海底二万里"
}

The Japanese publishing industry has pointed out several times that being able to express the same metadata in multiple scripts (kanji, katakana and hiragana) is quite important for them.

RWPM allows that, but that's not the case of the WAM or the current WP infoset.

I guess this is an issue related to the RWPM but, for the purposes of the WPM the differentiation between the links and resources does not really exist. Ie, I am not sure the separation of entries (2) and (3) are relevant for WPM

In the context of RWPM:

• links contains references to resources that are not necessarily part of the publication
• resources contains references to resources that are part of the publication but not in the default reading order

I think that we'll still need these two separate concepts in the WP infoset as well, but the list of resources is probably good enough for processing the default reading order.

There should be a branch that terminates the algorithm in case both (2) and (3) fails to lead to a link

Fixed.

We have to be fair. The WAM goes into all kinds of details about how to extract, say, "background color" and, if we followed that same style, we would have to do the same with some of the infoset elements (I am not sure we want to do that, I just say the comparison may not be fair). Ie, the complexity level is not really different. What is probably true is that the WAM includes a bunch of elements that are not really relevant for us (like that background color entry).

That's true but not all members of the WAM require specific processing, a large number of them are obtained from the fourth step (Let manifest be the result of converting json to a WebAppManifest dictionary).

Most members of the WAM are indeed irrelevant for us, and our life-cycle might require some additional processing compared to this draft (for example when processing publishing and modification dates).

Overall, I still believe that if we didn't had an external reading order (outside of the manifest), we would truly have way less processing than the WAM.

True. But the complexity of the user agent has a lower priority, in my view, than the complexity of the WP structure for authors. If the creation of the WP can be simplified even if this complicates the UA, then this should be of a higher priority (and the draft shows that this can be solved, albeit with some complexity).

It only applies to a very specific case where:

• the publication contains a nav where all resources from the default reading order are present and listed in the right order
• the resource containing such a nav is clearly identified in the manifest (listed in the list of resources)

Even in EPUB3 where we force the publication to always include a nav, not all navigation documents contain the default reading order.

My issue is not just with the additional processing that this requires (it doubles the complexity in the current draft), but also from a design perspective. It makes very little sense to have a Web Publication Manifest that either contains:

• just metadata
• or metadata + a list of (secondary) resources

Metadata and the default reading order are by far the two most important piece of information of our infoset. A publication is essentially a collection of resources, where the default reading order tells us the boundaries of the collection while metadata provide information about the collection.

IMO, it makes a lot more sense to always have both info in the same document (JSON or HTML). The current consensus (where the reading order can be expressed in the manifest or somehow vaguely through an HTML resource that's part of the publication) feels very inconsistent to me.

[BigBlueHat]

What is the result of going through this lifecycle? In the case of WAM, it's creating an icon in a launcher that opens a stripped down browser that (probably) opens the start_url.

When something goes through these lifecycle steps, what is made, where, to what end?

[mattgarrish]

What is the result of going through this lifecycle?

This is where I crashed and burned on section 5 before the holidays. We are carrying along at least three or four models for how a user interacts with a web publication and what sort of reading experience would be created (browser, reading app, inlined app), and is there any commonality in how they interplay?

We still need to define how to parse the manifest into the infoset, but that's still only the beginning. We're missing something similar to the "installable applications" section, of which the manifest lifecycle is one part.

[HadrienGardeur]

Well @mattgarrish is completely right that this is entirely tied to the category of application that we're describing.

For RWPM, we have a pretty good idea for native reading apps and web apps, but we haven't explored browsers.

Do you want me to sketch some of these options as well? cc @iherman

[iherman]

@HadrienGardeur I think that would be a good idea.

[rdeltour]

I finally got up to date with this thread. First things first, kudos to @HadrienGardeur for rolling up his sleeves and analyzing the details, it's very useful! 👍

That said, to be honest at this point I still fail to see how our needs are incompatible with the Web App Manifest.

To simplify, what I could gather from the experiment is:

1. WPM has additional processing requirements, mostly coming from computing the reading order
2. WAM has members that are not very relevant in a publication context
3. Some WAM members have semantics that conflict with the envisioned semantics of the equivalent terms in WPM (e.g. lang, dir)
4. our use case for the manifest is not very well defined yet, as we don't know yet what we mean by "applying a manifest"

My take on these conclusions is that (each item relates to the respective item in the previous list):

1. I don't think it's an argument for rejecting the WAM, especially given that WAM has an extension point for that.
2. IMO many of these members are relevant for publications, but even then they are optional so it's not a big deal
3. This is more annoying, but are mostly details for which can likely find workarounds (or push for changes in the WAM spec)
4. this is the core of the issue IMO, which @BigBlueHat raised in What is the Browsing Context of a Web Publication? #104. I believe that only when What is the Browsing Context of a Web Publication? #104 is resolved we can further discuss whether to reject/approve/adapt WAM.

By the way, seeing WAM as just a way to "install apps" or "create an icon in an app launcher" is a red herring. It's clearly the primary and original use case behind the spec, but it's just that, a use case, as said in Section 2 of WAM:

A common use case of a manifest is for a user agent to install a web application;

WAM is really about defining the manifest, how to obtain, process, and apply it to a top-level browsing context. This is very applicable to our use case as far as I can see, pending decision on #104 of course.

Maybe I'm missing something obvious, in which case I'm sure Hadrien or Benjamin will chime in 😉

[HadrienGardeur]

@rdeltour I think the WAM discussion should be handled in #118 rather than on this issue.

I've never said that we're incompatible with the WAM by the way, but IMO:

• we share very little with it (infoset, use cases, syntax, processing are all quite different)
• I don't think that's it's truly designed with extensibility in mind (compared to the RWPM)

[HadrienGardeur]

I added a new section to the life-cycle draft called "Processing a Web Publication".

For now it's divided into three sub-sections:

• browsers and their extensions
• dedicated native reading applications
• displaying a Web Publication

There's no specific section yet for Web Apps, but they're mostly a mix of the browser and dedicated app use cases.

Once again, this is a super early draft, feel free to suggest any addition or modification that you'd like (we'll most likely need a much longer list of requirements in "Displaying a Web Publication").

cc @iherman @BigBlueHat @mattgarrish

[iherman]

(Purely admin/practical comment.)

We should try to put that whole section into the WP draft as soon as possible, even if it is a sketch. Remember that we have now the possibility to publish a new draft, ie, a new snapshot, very quickly, and it does not have to be final and complete. (Essentially, pushing a version onto a specific branch on github would make it published on www.w3.org/TR/ automatically.) On the other hand, it is easier to get feedbacks (which we need) if there is one place where people can find out in which direction the WG is going.

Cc @mattgarrish @HadrienGardeur

[HadrienGardeur]

@iherman I've been working on this mostly as an extension of my holidays experiments, but I'm happy to plan a call with @mattgarrish as well if you think it's worth integrating some of this work in a new WP draft as well.

[BigBlueHat]

I'd like to publicly thank @HadrienGardeur for exploring #52 😁 All our lives could be made much easier, if we pinned some of these things down (as Hadrien has endeavored to do in https://github.com/readium/readium-2/blob/master/misc/W3C/lifecycle.md#3-processing-a-web-publication).

@HadrienGardeur perhaps we should work together on closing #52 with a proper list of affordances--beginning with what you've defined here. I know that'd make @TzviyaSiegman happy at least. 😸

Laslty, @rdeltour there may be situations when you don't want a WP to be "installed." However, anything extending WAM will also trigger an installation request (in supporting browsers...obviously). If that's not what you (ever) want, then don't put content into a WAM and link to it as they describe. Use something else. However...we should have that chat on #118 😉

[HadrienGardeur]

@BigBlueHat ping me by email and we can plan a call together to figure something out for #52.

My take on this:

• it's easy enough for dedicated reading apps, we know how they work
• for browsers and extensions, this takes a little more work (but I'd rather look in the direction of reader modes than WAM installs)

[iherman]

I played with a diagram creation program today, and I made some rough flowcharts for the processing steps in the draft:

• https://www.w3.org/2018/01/wp_lifecycle_diagrams/obtain_manifest.svg
• https://www.w3.org/2018/01/wp_lifecycle_diagrams/process_manifest.svg
• https://www.w3.org/2018/01/wp_lifecycle_diagrams/default_reading_order.svg
• https://www.w3.org/2018/01/wp_lifecycle_diagrams/process_nav.svg

they are rough, stylistically, but they also revealed some minor awkwardnesses in the draft in terms of naming, what a processing step needs as input and what exactly it produces, etc (nothing major, just minor things). I did not mostly as an exercise, but it may be useful for others to gain a better oversight on what we are talking about. We may consider adding them in the draft (as an appendix).

Enjoy...

@RachelComerford , you inspired me:-)

[HadrienGardeur]

@iherman This looks good overall!

For https://www.w3.org/2018/01/wp_lifecycle_diagrams/process_manifest.svg, we don't need manifest.spine + manifest.reading_order.

In RWPM, the spine property contains the default reading order (like in EPUB).

Since manifest.reading_order covers the spine as well, you can remove a step from the second diagram.

[iherman]

@iherman <https://github.com/iherman> This looks good overall! For https://www.w3.org/2018/01/wp_lifecycle_diagrams/process_manifest.svg <https://www.w3.org/2018/01/wp_lifecycle_diagrams/process_manifest.svg>, we don't need manifest.spine + manifest.reading_order. In RWPM, the spine property contains the default reading order (like in EPUB). Since manifest.reading_order covers the spine as well, you can remove a step from the second diagram.

I am not sure I understand all what you say but… I guess it is better if we finalize the details of the steps in the document before changing the diagram. The diagram are only illustrations...

[HadrienGardeur]

I've tweaked it slightly, but there are only two steps in the document (default reading order + language), while the diagram has three (spine + language + default reading order).

[iherman]

On 24 Jan 2018, at 16:39, Hadrien Gardeur ***@***.*** ***@***.***>> wrote: I've tweaked it slightly, but there are only two steps in the document (default reading order + language), while the diagram has three (spine + language + default reading order).

Ah yes, I remember. What isn't that a mistake in the draft? My understanding is that the processing of the manifest creates an internal representation of the information items, of which the default reading order is part of. (But I may be wrong, not sure…)

[HadrienGardeur]

If the JSON contains a default reading order (spine), the default reading order processing is almost immediately terminated. Otherwise, it goes through all the steps of figuring out which HTML document to use, then extracting info from that document.

This is all handled in a single step, not two.

[iherman]

That is all part of the separate default_reading_order.svg. But that is a process (say, a function) that must be called from somewhere, so to say, and caller is the process handling the manifest. Much like, in fact, there should be a different, albeit much simpler, procedure to get the language information (the multiple language question put aside for the moment).

[HadrienGardeur]

Sure, but you only need to call it once in the main processing, not twice. Anyway, it's a minor tweak.

[triblondon]

I posted some TAG comments here that may be useful to this thread as well.

[iherman]

Propose closing: this is now part of the latest draft (per #130)

[iherman]

Closing per https://www.w3.org/publishing/groups/publ-wg/Meetings/Minutes/2018/2018-03-12-minutes.html#resolution12