RE: PWP draft to be discussed on tomorrow's (Dec-11) call

With respect to WP, we separated off property requirements from compilation, so there are specific UA details in the descriptions. 3.2 was only designed to give an overview of requirements.

Not all the properties are fully defined at this time (e.g., we called a truce on address before getting into fallback processing), but there are a number that we have defined defaults/fallbacks for.

I've done a quick sweep through the document to look for passive voice uses that we can tie more explicitly to user agent/author, without changing any of the requirements of the specification. I'm also going to suggest that we drop 3.2 for now. Its future probably hinges on how we integrate with web app manifest, and we may want to review issues of criticality in terms of what a user agent has to do when required information isn't present, rather than simply list what is required.

I'm going to open a PR shortly, so if anyone has additional opinions, please feel free to comment there.

Matt

> -----Original Message-----
> From: Florian Rivoal [mailto:florian@rivoal.net]
> Sent: December 11, 2017 5:01 AM
> To: Ivan Herman <ivan@w3.org>
> Cc: W3C Publishing Working Group <public-publ-wg@w3.org>
> Subject: Re: PWP draft to be discussed on tomorrow's (Dec-11) call
> 
> Hi,
> 
> I will not be able to attend, but I'd like to share a comment about this
> document.
> 
> The few normative statements that we have so far are of the form:
> 
>   "A Packaged Web Publication MUST ..."
>   "A Packaged Web Publication MAY ..."
> 
> I think we need to be careful about how we write things. MUST, MAY and
> other RFC2119 keywords are most useful when their subject is an active
> agent rather than a passive object. For example, “User Agents MUST ...”,
> “Validators SHOULD...”, “Authoring tools MAY...”. And out of these, the
> requirements on the User Agent are the most useful. This is how we establish
> interoperability, even in the face of poorly authored documents, or of
> documents using a future revision of the spec being loaded in an old User
> Agent...
> 
> While there are exceptions and occasional mistakes, this is something that
> HTML and CSS specifications do well, and as a result, there is very good
> interoperability, including in error handling.
> 
> Instead of saying “FOO Documents MUST match such and such criteria”,
> which leaves the reader of the specification wondering about what is
> supposed to happen when the criteria are not met, a better way to establish
> taxonomies is to phrase things like this: “A Document is a FOO if it matches
> such and such criteria”. Then we're clear that we're just naming or
> categorizing things, not imposing behavior without defining what that
> behavior and related error handling is.
> 
> A related point is that conformance criteria on documents (or publications,
> or other passive objects) are generally of limited value. There are a lot of
> documents on the market that claim to be EPUB documents, sold as EPUB
> documents, accepted by Reading Systems without error or even warning,
> and even sometimes validated by epubcheck that fail to conform to the spec
> one way or another. What matters is that tools are interoperable. Features
> of EPUB (or HTML, or CSS..) that have interoperable implementations get
> wide usage; those that don't, don't.
> 
> Which brings me back to my original statement: normative text with RFC2119
> keywords or equivalent formulation is most useful when the subject is the
> User Agent, or some other software that can be tested against the
> requirement: this is what leads to interoperability.
> 
> Concretely, I suggest rewriting the 2.1 and 2.2 sections of PWP to read like a
> taxonomy rather than RFC2119 statements (and later use that taxonomy to
> describe what UAs are supposed to do).
> 
> —Florian
> 
> PS: I re-read the Web Pub spec, and we've been doing a lot of the same
> there. I think we should try to rework all (most?) instances of RFC2119
> sentences where the subject of the sentence is not a piece of software. For
> instance:
> * 3.2 section would be much more effective if instead of saying "infosets
> must have the FOO property", it was rephrased as "UAs encountering an
> infoset without the FOO property must do BAR", possibly together with
> "Validators MUST emit an error when encountering an infoset without the
> FOO property" (but the requirement on UAs matter more than those on
> validators).
> * In 3.2, there are more statements like that: "This URL MUST resolve to an
> [html] document". What happens if it doesn't?
> 
> 
> > On Dec 10, 2017, at 17:37, Ivan Herman <ivan@w3.org> wrote:
> >
> > Dear all,
> >
> > The document
> >
> > https://w3c.github.io/pwpub/
> >
> > is ready for discussion for tomorrow's call. Please, if you have time, read
> through it.
> >
> > Thanks to David for having done this in a relatively short amount of time
> >
> > Ivan
> >
> >
> >
> > ----
> > Ivan Herman, W3C
> > Publishing@W3C Technical Lead
> > Home: http://www.w3.org/People/Ivan/
> > mobile: +31-641044153
> > ORCID ID: http://orcid.org/0000-0003-0782-2704
> >
>

Received on Monday, 11 December 2017 15:20:14 UTC