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 10:03:00 UTC