18 Matching Annotations
  1. Sep 2018
    1. The epub:type attribute [ContentDocs32] is REQUIRED

      Discerning the available values of epub:type is a tangle... The referenced epub: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 available epub: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.

    2. 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?

    3. 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.

    4. 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.

    5. it MUST resolve

      Link resolve to any defined algorithms for resolving resources within an EPUB.

    6. 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 surrounding a or span? or the contained "embedded content" element?

    7. 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?

    8. 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?

    9. while a span element

      Rephrase "while a child span element" and perhaps move to it's own sentence parallel to the "A child a element"

    10. Each list item

      Reference the li element here for consistency.

    11. current reading position

      Link to this, if defined.

    12. 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.

    13. 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.

    14. 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.

    15. which has no effect outside of spine rendering

      But it does have effect on "spine rendering"? Perhaps add a link for spine rendering.

    16. represents a data island

      Is "data island" a specific, defined thing from a previous EPUB spec or another adjacent spec?

    17. custom control

      Link to a definition of "custom control" if one exists.

    18. 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.