separate implicit information from failure handling about wpub HOT 18 CLOSED

@mattgarrish I am fine with this type of reformulation of, e.g., title.

The TOC approach of using nav elements is a bit different, though, because the TOC is not a required infoset entry...

from wpub.

from wpub.

But it's still recommended, which in validation parlance is a warning. It's fine to have the UA go looking for one, but it should still be a clear recovery step with a warning.

The wording could be cribbed like this, for example:

The table of contents is recommended in the infoset.

An author MAY omit the table of contents from the manifest if it is included in an HTML nav element identified by the role 'doc-toc'. This nav element MUST be in a file named index.html or in the first resource in the default reading order. In this case, the user agent MUST use this navigation element as the table of contents for the Web Publication.

If a user agent requires a table of contents and one is not specified, it MAY provide one of its own making. This specification does not mandate how such a table of contents is created. The user agent might:

• attempt to locate table of contents nav element in a subsequent primary resource in the default reading order;
• use the titles of the primary resources in the default reading order;
• calculate a table of contents using its own algorithms.

The warning kicks in if the toc isn't specified in the manifest or explicitly found in the first resource.

I didn't go back to your PR, so not sure if this exactly matches what you have. I'm also not yet clear if the table of contents requirement is for a reference to an html element in all cases, a json object in the manifest, a combination, or what, so the above will need reworking.

(Updated proposed text to account for named file.)

from wpub.

Why are we assuming intentional omission vs. simply not having the data (those are two different things)?

Because we're talking about implicit collection of the information from another source than the manifest. There's a distinction between knowing it is being left out to be discovered elsewhere v. accidental omission.

Redundancy avoidance is what we look to be trying to achieve. But that's done with author understanding.

But like I said above, it'll never be perfect because author intent also has to be assumed. But it seems that people want auto-collection of some information without it triggering invalid manifests.

The alternative is to say manifest are invalid/warning-filled if any of these requirements are missing. I'm fine with that, too, but the current wording says the UA has to make up for any deficiencies so no manifest ever has issues. That strikes me as a strange state of affairs.

from wpub.

@mattgarrish your formulation in #48 (comment) if fine with me, except that, at least in the original proposal of @dauwhe and @BigBlueHat, a well-known name (index.html) takes precedence. Which actually makes sense, because the default order's first resource may be, say, the cover page and not the toc...

I will try to reformulate the text, but only later (I am on a call right now...).

from wpub.

a well-known name (index.html) takes precedence

I'm not completely sold on this, but, yes, it was just a quick copy of the above so appreciate the point about it not being the first resource. I suppose between an index.html and first file (for single-resource publications) that's enough implicit harvesting.

My concern is that we not send user agents on fishing expeditions whereby they have to retrieve and parse document after document in the hopes of finding something.

from wpub.

I've made a few tweaks to the proposed wording above, if it helps.

from wpub.

@mattgarrish, I have just pushed a new commit to #47

from wpub.

from wpub.

That's the model of the web today - where the UA is supposed to handle all
error conditions in a graceful manner.

Right, I'm not saying it's wrong to have fallback handling. All I'm suggesting is that we should be careful not to make everything valid with an expectation that the UA handle the problems.

If you validate an HTML file you get a list of everything you did wrong and omitted. If you choose to ignore it, the UA will kick in and correct. That's not the same as what we currently have.

I'm fine with switching title and language back to recommended if we do this, if that's your concern, at least until the debates about their priority are concluded. I put them to required when I refactored the prose because there was no way they weren't part of the infoset under the old rules.

If we only issue warnings when not present or captured by allowed harvesting techniques, the UA can still build a title and the manifest publication isn't invalid.

from wpub.

Here's how it might be revised:

It is recommended that the Web Publication's infoset include a title.

An author MAY omit the title from the manifest when the first resource in the default reading order contains a non-empty title element (e.g., an HTML or SVG document). In this case, the user agent MUST use this title as the title of the Web Publication.

If a user agent requires a title and one is not specified, it MAY provide one of its own making. This specification does not mandate how such a title is created. The user agent might:

• use the non-empty title of a subsequent primary resource in the default reading order;
• provide a language-specific placeholder title (e.g., 'Untitled Publication');
• use the URL of the manifest;
• calculate a title using its own algorithms.

(And, yes, to your comment further up, we can be more specific about what 'non-empty' means. I'll try to clean up items like that in a real PR.)

from wpub.

from wpub.

from wpub.

from wpub.

A Web Publication's infoset SHOULD have a title.

Except that this is already stated in RFC terms in the requirements section. That's what I'm trying to avoid duplicating.

Ideally these repeated conformance statements should be dropped and each section should start with an explanation of the property/structure and only provide requirements for how it is constructed.

I'll put together an actual PR for title/language so we can discuss other wording issues there.

from wpub.

Still catching up with all this, but @iherman it was never the intent of @dauwhe or myself to "mint" a name for the ToC document (re: your comment #48 (comment)).

We used index.html in the examples because GitHub serves those (as do most web servers) as the default resource from a file system directory such as https://dauwhe.github.io/html-first/MobyDickNav/

The confusion may come from this line in the explainer:

Define the URL of a web publication to be the URL of this “index” resource which contains the nav.

The point was that the publication (and it's canonical URL) would serve this "index (ToC) resource"--not that it would be named index or index.html. Additionally, we fully expected things like rel="canonical" (or whatever we explore here) to be used (and useful) for additional identifiers (even the canonical one).

The rules section in the explainer also mentions "index" resource--which again was meant to be conceptually an index/ToC.

Hope that's clearer. 😄

from wpub.

@BigBlueHat it is... but, nevertheless, I am not sure we can live with 'just' the first entry in the default reading order. Alternatively, we can say that the UA takes the "first entry in the default reading order that has a TOC with the right role". Ie, the UA goes through all the entries until it finds the TOC.

from wpub.

Closing this issue as my concerns in opening this issue were satisfactorily addressed in PR #51.

from wpub.