Comments (9)
This might also solve some of my concern with properties and relationships having different naming conventions. IANA mixes all kinds of naming conventions, but so far we only adopt "privacy-policy" and "contents" from the relations. Perhaps properties can remain camelcased and we can hyphenate relationships for consistency?
This would mean only "pagelist" might potentially need to change to "page-list" (which would match EPUB but not DPUB-ARIA, though that hardly matters in this context). But leaving it as-is would fit just as well within the relations, too.
from wpub.
Yes, I think separating those relationships to a different "thing" (table, list, or whatever) is a good idea. The quick reference may include property terms that come either from schema.org or from our own vocabulary, and it is unnecessary to refer to them as URL-s because they are only used as terms by the author. The relationship, alas!, is different.
(Unfortunately, I am not sure we can get around using URL-s for those at least for now...)
from wpub.
(We should probably merge #425 before doing any change...)
from wpub.
Ya, this is a confusing one to piece apart. What we've done for some of these is define properties based on the relations, so we're not actually realizing that there is a property until the canonicalization step (although even that isn't clear for all).
In other words, what starts off as:
{
"url": "toc.html",
"rel": "contents"
}
after processing becomes:
{
...
"contents": "html markup here",
...
}
since there are rules for compiling the table of contents, but they're not in canonicalization section.
But what about a resource that identifies itself as a privacy policy, does it become:
{
...
"privacy-policy": "https://example.com/privacy.html",
...
}
If so, we're effectively minting new properties for every link relation that we compile up. But processing of privacy policy, cover and accessibility report is not detailed in the canonicalization steps, either, so when and where does it occur? Or are these supposed to be separate entities that a user agent might make itself aware of?
At any rate, this changes the dynamic of what I was proposing.
We can (maybe?) keep the current groupings, since we (maybe?) need properties eventually, but it raises a number of questions:
- do all these properties spring into existence through canonicalization if they aren't set manually, or only page list and toc? If not, we should detail why only some do and move the others out of the properties section. We should figure out a better place to define the steps for compiling the toc and page list during canonicalization.
- how does canonicalization work for other relations we haven't listed? I assume we need a method for compiling only certain relations into properties?
- do we have to keep the link relation names as the property names to avoid having to maintain a map of what goes to what? This would have the unfortunate consequence of leaving our mixed-bag property naming intact.
from wpub.
I do not understand what you mean by:
{ "url": "toc.html", "rel": "contents" }
after processing becomes:
{ ... "contents": "html markup here", ... }
Canonicalization does not involve generating HTML markup...
As for
If so, we're effectively minting new properties for every link relation that we compile up. But processing of privacy policy, cover and accessibility report is not detailed in the canonicalization steps, either, so when and where does it occur? Or are these supposed to be separate entities that a user agent might make itself aware of?
yes, I think that is how the processing of rel
is supposed to be, but that is a general way the Web does things: you get (via HTTP or otherwise) the content (or the URL thereof) and the separate rel
value which tells the user agent how to display/process that stuff. We are no different...
So the overall answer is that canonicalization has nothing to do with these. A canonical version of the manifest is a bona fide 'authored' manifest, with all the shortcuts resolved. A full and automatic authoring system for WPUB could bypass canonicalization altogether; the canonicalization is only there because some manifests will be produced by human, and we make their life easier.
from wpub.
Canonicalization does not involve generating HTML markup...
That's what I was expecting, but that's not what the specification currently seems to say.
We have a table of contents relationship defined here: https://w3c.github.io/wpub/#pub-table-of-contents
And a process for creating contents
and toc
properties (conflicting names) that involves extracting the HTML toc without exactly explaining when this process happens: https://w3c.github.io/wpub/#wp-table-of-contents
To add to the confusion, the process to extract the toc nav ends by saying:
If this process does not result in a link to the table of contents, the publication does not have a table of contents and this property MUST NOT be included in the canonical manifest.
Which makes no sense, as the process results in the toc markup.
The only interpretation I could make is that the HTML has to be added to the manifest property and this either happens before or during canonicalization. The same is true of page-list.
My expectation before reading the spec was that the rel values were intended to do nothing more than identify resources that could be used after canonicalization, but it's not what I found.
Assuming I was right to begin with, though, and that the rel values just allow a user agent to identify resources and do things independent of canonicalization (i.e., there is no property computation), then I can continue what I was originally intending.
But, if that's true, I also need to go through and rewrite the toc and pagelist sections, as they're confusing the hell out of me.
from wpub.
Hah! I think the confusion in the TOC section comes from this thing:
The table of contents property identifies the digital publication's table of contents. It MAY be used either to embed a table of contents within the manifest or to identify a resource that contains the table of contents. How the table of contents has to be represented is determined by the digital publication format.
That was left pending due to an open issue (whose number I do not remember) but is now out, because we agreed that the only way a TOC is represented is in HTML, and the Manifest simply refers to the TOC via a URL. The paragraph is simply wrong; only the first sentence is true. It is up to the user agent what it does with the extracted TOC.
from wpub.
because we agreed that the only way a TOC is represented is in HTML, and the Manifest simply refers to the TOC via a URL
Okay, that makes more sense; it is just a rel
identifier.
I'll keep pushing ahead with what I think needs changing and then see if you agree with the PR.
from wpub.
Closing as this was addressed in #428.
from wpub.
Related Issues (20)
- Optional HTML TOC HOT 4
- Why list resources for links? HOT 2
- Should there be a TOC if supplemental materials are provided in an audio book? HOT 10
- Manifest files need their own MIME Media Type (because canonicalization) HOT 8
- allow toc link markup to be preserved? HOT 6
- HTML <input type="time"> missing attributes HOT 1
- Is duration required for audiobooks? HOT 21
- Normative references to expected values of "accessibility" properties are unclear. HOT 5
- Bookish nature of recommended resources? HOT 8
- Change rel URLs to tokens HOT 3
- There are 2 lines of "datePublished" at "F. Properties Index" HOT 1
- Wording for application of base direction HOT 7
- Wording for D. Examples for bidirectional texts HOT 2
- Different relations for linking to manifest and primary entry page? HOT 11
- Remove accessibilityControl and accessibilityAPI HOT 1
- PEP is canonical identifier? HOT 1
- ua conformance criteria should link to manifest processing HOT 3
- Differentiating the primary entry page URL from the publication address HOT 1
- Web publications / Publication manifest / other forks difference and status confusion HOT 9
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from wpub.