Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

update to replace "abstract manifest" with infoset plus various cleanup #43

Merged
merged 18 commits into from
Aug 22, 2017
Merged

update to replace "abstract manifest" with infoset plus various cleanup #43

merged 18 commits into from
Aug 22, 2017

Conversation

mattgarrish
Copy link
Member

@mattgarrish mattgarrish commented Aug 20, 2017

After discussing with chairs and Ivan, this PR changes what was called the "abstract manifest" to the WP "infoset" and separates the information required in the infoset from the manifest.

"abstract manifest", in my opinion, sounds too much like it only identifies information in the manifest for various serializations, when the work so far is establishing that some information may be obtained outside the manifest.

Of course, the name "infoset" has its own connotations for xml, and there may be a better name lurking somewhere, so it can change and a note has been added to this effect.

The manifest section will instead deal with issues like how it declares it describes the web publication, what the serialization requirements are, etc.

Some of the other key issues addressed in this PR since the last consolidation are:

  • changing title/language requirements to "musts" because they are required in the infoset but optional in the manifest
  • moving the declaration requirement to the manifest, as it's already clear a web publication is being described by the time the infoset is collected
  • cleanup of the title and language algorithms - they should be technically the same as before, though
  • making address and canonical identifier sections under the infoset because they are requirements and not simple definitions
  • primary resource definition has been tweaked so it is not circular with default reading order

Comments are welcome, and I believe this will be noted/discussed on tomorrow's call.


Preview | Diff

@iherman
Copy link
Member

iherman commented Aug 21, 2017

@mattgarrish if we want to make the Terminology section normative (which I am fine with) then the section heading should be followed by something like

<p><em>This section is normative</em></p>

The reason is that this section is part of the introduction, and that whole section has been marked as "non normative" (for good reasons).

@mattgarrish
Copy link
Member Author

that whole section has been marked as "non normative"

Yes, you're right, of course. I missed that we'd put the informative label on the parent section.

Like HTML and others, it would probably be better to move the informative status down to the specific sections. I'll update the PR to make this change.

@llemeurfr
Copy link
Contributor

I really like the new "preview/diff" feature.

In the list of "infoset" bullet points, I would be in favor of moving all MUST items on the top, followed by the SHOULD items. I would also put together (as sibling) Primary resources and reading order.

In the Overview, sentence "It is primarily compiled from a Web Publication's manifest, whose serialization requirements are defined in the next section", I don't understand why this limitation to "requirements" where a serialization section is present (currently empty) as 4.4.

@mattgarrish
Copy link
Member Author

@llemeurfr Thanks, what I've done is separate the infoset requirements into two lists: one for musts and one for shoulds. It also means we tidy up having must/should at the start of every bullet.

The serialization is supposed to be referencing the next major section (Manifest), not subsection (Requirements). I've updated the linking and removed "next section" to avoid confusion.

The reading order and relationship to primary and secondary resources undoubtedly needs further discussion, but at this time there seems to be consensus that not every primary resource is necessarily in the default reading order. If that changes we can continue to adjust the definitions, but we should probably wait until the resource and reading order sections are more fully fleshed out.

@llemeurfr
Copy link
Contributor

llemeurfr commented Aug 21, 2017

I'm not fan of the new definitions for default reading order and primary resource. I'm in favor of definitions more compatible with the previous ones (but avoiding circular definitions), like:

Default Reading Order
The default reading order is a specific sequential progression through a subset of the resources of a Web Publication. It will be used by User Agents as a fallback in the absence of a Table of Contents.

Primary Resource
A primary resource is one that is listed in the default reading order of a Web Publication. As such it is required for the processing or rendering of a Web Publication.

Secondary Resource
A secondary resource is one that is required for the processing or rendering of a Web Publication, but is not listed in the default reading order of a Web Publication.

@mattgarrish
Copy link
Member Author

mattgarrish commented Aug 21, 2017

Your proposal architects a solution, IMO, so terminology is the wrong place. How the toc and default reading order interplay needs to be resolved and described in their respective sections. I haven't seen consensus on this yet.

The current wording only attempts to establish that there is a thing called a default reading order that is a progression through some or all resources. Primary resources are "top-level" resources, and secondary are ones used by primary. There should be enough flexibility in these to use them however we need to talk about the kinds of issues you're raising. That's all the terminology should do.

@iherman iherman added this to the Abstract Manifest milestone Aug 22, 2017
@mattgarrish mattgarrish merged commit 14bb787 into w3c:master Aug 22, 2017
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants