- Sep 2018
-
w3c.github.io w3c.github.io
-
The epub:type attribute [ContentDocs32] is REQUIRED
Discerning the available values of
epub:type
is a tangle... The referencedepub:type
related section in the ContentDocs32 document references the Vocabulary Association paragraph which in turn references the Vocabulary Association Mechanisms section within this current document. From that section the default vocabulary can/may be found, but there is no reference there (or in any of these other sections) to the availableepub:type
values nor to their "meaning"/value to the author or implementer.However, just below this in the example (and above in relation to
pagebreak
there is a link directly to the defining defaults in the EPUB-SSV.It would be helpful for authors and implementers to know first about the SSV list, and then about the ability to extend the vocabulary.
-
The page-list nav element SHOULD contain only a single ol descendant (i.e., no nested sublists).
If this SHOULD is not heeded...what happens? How is the page list calculated if there is a hierarchy present?
-
The toc nav element
This makes it sound like there is an HTML element with a tag name of
<toc nav>
rather than<nav epub:type="toc">
(which seems to be what's intended).The
landmarks
example farther down is clearer--though the wording there of "the landmark nav element" is equally confusing.There remains only a
nav
element, but of varying types. -
In the context of this specification, the default display style of list items within nav elements MUST be equivalent to the list-style: none property [CSSSnapshot].
This line is confusing because the actor (author or reading system) is unclear. The following two lines are much clearer on what actor is being restricted by this specification.
This line feels specific to the Reading System requirements. Consequently, perhaps it's best to integrate it into the sentence just following.
-
it MUST resolve
Link
resolve
to any defined algorithms for resolving resources within an EPUB. -
If an a or span element contains instances of HTML embedded content that do not provide intrinsic text alternatives, the element MUST also include a title attribute with an alternate text rendering of the link label.
This requirement is clearer than the one just previous and also seems to obviate the earlier one.
However, this one is confusing limiting the textual expression to just the
title
attribute, and also being vague of which element is associated to the MUST--is it this surroundinga
orspan
? or the contained "embedded content" element? -
after concatenation of all child content and application of white space normalization rules.
Implied requirement? When is this necessary and what does the concatenation and normalization?
-
visual display of components
Where is this "visual display" taking place? Is this when the document is viewed as a spine element? or is this when the content is extracted and presented by the Reading System?
-
while a span element
Rephrase "while a child
span
element" and perhaps move to it's own sentence parallel to the "A childa
element" -
Each list item
Reference the
li
element here for consistency. -
current reading position
Link to this, if defined.
-
when rendered in a non-browser context.
Is "non-browser context" defined? or its inverse?
It's not clear if "browser" here is equivalent to "Reading System" or to a Web browser or something else.
-
If such formatting and functionality is used
Used by? It's not clear who the actor is here, the author/developer of the EPUB or the Reading System.
-
a custom control, such as the table of contents
Is the "table of contents" a specific type of custom control? If so, a link would help here.
-
which has no effect outside of spine rendering
But it does have effect on "spine rendering"? Perhaps add a link for spine rendering.
-
represents a data island
Is "data island" a specific, defined thing from a previous EPUB spec or another adjacent spec?
-
custom control
Link to a definition of "custom control" if one exists.
-
Unlike typical XML data islands
Not sure what a "typical XML data island" is either...so some links or even rewording (or removing?) might help others unfamiliar with the phrase.
-