Reorganization of appendixes

[mattgarrish]

This pull request started from the discussion in #2814 (review) about where the obsolete features belong in the list of appendixes but I ended up trying to fix a couple of lost sections buried in the appendixes at the same time:

• The "vocabulary association mechanisms" section was buried under the vocabularies appendix even though it's central to the package document. We did this because it's also applies (to a much lesser extent in practice) to the epub:type attribute, but squirreling it away in an appendix means you end up reading the package document section without really understanding anything up front about prefix attribute, default vocabularies, etc. You have to follow links to make your way back to the appendix.
• The "expressing structural semantics" appendix is similar in that it covers epub:type for content documents, but again, because it can be used in media overlays it ended up in an appendix even though the use is the same for each.

To fix these issues, I moved vocabulary association mechanisms under the package document section and added a note to the introduction to highlight that it also applies to structural semantics. And for the type attribute I moved it under the shared technologies in the section on epub content documents (again adding a note to highlight that applies to media overlays). It's not perfect, but at least it gets the definitions into the body and as close to their primary use cases as possible.

The rest of the pull request is just a minor shuffling of the remaining appendixes:

A. Detailed examples
B. Allowed external identifiers
C. The viewport meta tag
D. Vocabularies
E. Obsolete features
F. Schemas
G. Media type registrations

I moved the examples to the front of the list as they get lost and are out of place when squashed between technical details.

---

Preview | Diff

[iherman]

I could not put this comment directly into the changes, GitHub did not let me. Looking at §5.7.2.1 should probably make it explicit that the properties uses the property data type (or whatever the final name is) as the datatype for its values. It does say in a roundabout way (it talks about the default vocabulary, and it also to the necessary section in the last sentence of the section), but it sounds cleaner if it is explicitly part of the definition of the attributes.

[iherman]

Just wondering... I would think that adding epub:type directly into this list (with a parenthetical note saying that epub:type is not used in the package document) is better than having a separate note at the end of the section. As it is now, it suggests that epub:type usage is, sort of, an afterthought or secondary feature (which is not).

[iherman]

B.t.w., if we go down the HTML lane, then it should probably refer to epub-type as well. Although... it might become a bit awkward to use a mechanism which very much smells xml in a non-xml environment (where would we put the prefix definition, and how would we define it for HTML? Maybe something like epub-prefix).

But, depending on how the HTML discussion goes, this remark may be moot.

[mattgarrish]

it might become a bit awkward to use a mechanism which very much smells xml in a non-xml environment

In other words, we never should have hacked up our own version of RDFa? 😉

We don't have epub-prefix so epub-type is limited to the structural semantics vocabulary. I'd be surprised if more than a few people have ever used vocabulary association for structural semantics. What other vocabulary is there but the slightly more expansive DAISY structural semantics vocabulary that the EPUB version was culled from? It doesn't make a strong case for adding another epub- prefixed html attribute. If anything, the utility of prefixes and additional vocabularies in xhtml could be questioned.

[iherman]

In practice, this means that epub:type making use of vocabulary extension would be restricted to XHTML. I can live with that; as you say, it would concern very few (if any) users. But then this must be made explicit in the spec.

[iherman]

Suggested change

	vocabularies using the <a href="#sec-property-datatype"><var>property</var> data type</a>. The
	vocabularies using the <a href="#sec-property-datatype"><var>property</var> data type</a>. The

Rereading all that tells me that the "property data type" is not the optimal term. We say that a "property data type" is used in the property attribute, but also in other attributes, which makes it confusing to me. Would it be possible to change the "property data type" to something else?

It could be shortened URL, abbreviated URL... The RDF Turtle spec uses the term prefixed name which we could reuse after all, or use prefixed value for what it is. I am sure there are other alternatives.

This is a more complex editorial change if you agree with me... sorry about that!

[mattgarrish]

It was supposed to be a CURIE data type, but that would have been picking sides in the semantic wars between RDFa and microdata. We landed on property because it was primarily for expressing metadata properties in the package document.

Do you think we could just use CURIE now? The ebnf for the syntax was lifted from RDFa core, although we've since changed the reference to IRIs to use the URL spec.

[iherman]

That war will never be over 😀… But both RDFa and microdata are hardly ever used, I am afraid, so it does not matter too much (using json-ld data embedded in the header of the html file won over both). This also means that I do not think people would particularly care, so we could use CURIE without too many problems.

The downside is that I do not believe anybody will ever update the RDFa Core standard, so if some bugs come up, we are stuck. We may be better off by using either the term CURIE or "compact uri" in our spec, but not touching our own ebnf definitions.

[mattgarrish]

We may be better off by using either the term CURIE or "compact uri" in our spec

Is that like generic v brand name? 😄

I'd be fine with just calling it a compact url. (cool kids don't use IRIs!) I think somewhere we mention compatibility with rdfa and curies, so that gives us a little distance to justify our own definition.

[mattgarrish]

To avoid overloading this pull request, I'm going to merge the current rearrange and open separate PRs to rename the property data type and tweak the introduction.

[iherman]

I just wanted to propose that:-)