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

Nice catch, Florian. I’ll be happy to make the changes you suggest.

On Mon, 11 Dec 2017 at 20:03, Florian Rivoal <florian@rivoal.net> wrote:

> 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
> >
>
>
> --
Regards,
Dave