Epub-specs: Editorial organization of the package document

[iherman]

(My apologies not to have said that earlier; it is only through a more systematic reading of the spec that this stroke me.)

For a reader the current section organization of the package document is a bit difficult to follow. There are a number of attributes that are shared; these are collected and defined towards the end of the document and I have not seen (did I miss it) any forward reference to that section while reading the element definitions. I have therefore hit attributes that are not defined. I believe either (a) the shared attribute section should be moved ahead of the others or (b) there should be a clear statement in the element definitions when an attribute is defined elsewhere. Yes, I know, each attribute is a hyperlink, but when just reading the text it is a bit strange to see some attributes being defined, while others are not even mention in the explanation.

In general, I think the elements should be put into sections following the logical order, namely the way they are used in the package. Something like

shared attributes
package element
    metadata element
        dublin core elements
            required
                ...
            optional
                ...
        meta
        link
    manifest
        item
    spine
        itemref
    collection

[mattgarrish]

The shared attributes were originally first, but people were confused that it meant that the attributes were allowed on every element. I added the backlinks and moved to the end to try and address that. I'm fine with adding a note at the start of the section that shared attribute definitions are defined later.

I've seen in HTML 5.1 they don't link if the definition is in the same section, but I find that really irritating as I still like to have a link to the definition wherever it occurs.

And we had the elements in an early (probably never published) draft of 3.0, but it was pushing the heading limits of html so we flattened. It's also a nuisance to nest because if we do it we need to define a new section for the definition of the parent element to avoid ambiguous references (e.g., if a reference points you to the metadata element definition, does it just mean the metadata element or every subsection under it, too?). I recall having to clean up the sectioning in 3.0.1 as part of the ISO feedback for this reason, although there probably are some instances left.

(But if left to my own devices, I'd change in a heartbeat.)

[iherman]

On 12 Aug 2016, at 14:14, Matt Garrish [email protected] wrote:

The shared attributes were originally first, but people were confused that it meant that the attributes were allowed on every element. I added the backlinks and moved to the end to try and address that. I'm fine with adding a note at the start of the section that shared attribute definitions are defined later.

And, maybe, add a not or a sign or something in the individual element definition that a specific shared attribute is defined elsewhere. Or just a single line after the element definition boxes making that clear. It is a bit of a pain editorially, but it is helpful for the reader imho.
I've seen in HTML 5.1 they don't link if the definition is in the same section, but I find that really irritating as I still like to have a link to the definition wherever it occurs.

And we had the elements in an early (probably never published) draft of 3.0, but it was pushing the heading limits of html so we flattened. It's also a nuisance to nest because if we do it we need to define a new section for the definition of the parent element to avoid ambiguous references (e.g., if a reference points you to the metadata element definition, does it just mean the metadata element or every subsection under it, too?). I recall having to clean up the sectioning in 3.0.1 as part of the ISO feedback for this reason, although there probably are some instances left.

It is a bit of individual taste issue; the current nesting is a bit messy to me. Why are dc elements listed one level deeper and, say, itemref on the same level as metadata? It is confusing for me.

But, well, as I said, tastes differ.

(But if left to my own devices, I'd change in a heartbeat.)

[mattgarrish]

The DC elements are a particular pain. They were flattened in 3.0.1, but it made a mess of the optional elements. The optional elements we define a purpose for got buried in a big "DCMES Optional Elements" section using bridgeheads, but that made it harder to locate the definitions because the headings wouldn't get generated in the table of contents.

The nesting in the 3.1 specification isn't intended to reflect a particular content model, but we need nesting for the optional elements to address them better (IMHO). We could strip 3.4.3 and 3.4.3.1 if you think the nesting is too much, which would leave:

3.4.1. The package Element
3.4.2. The metadata Element
3.4.3. The DCMES identifier Element
3.4.4. The DCMES title Element
3.4.5. The DCMES language Element
3.4.6. DCMES Optional Elements
3.4.6.1. General Definition
3.4.6.2. The DCMES contributor Element
3.4.6.3. The DCMES creator Element
3.4.6.4. The DCMES date Element
3.4.6.5. The DCMES subject Element
3.4.6.6. The DCMES type Element
3.4.7. The meta Element
3.4.8. The link Element
...

I was looking around and I can't find examples of specifications that nest sections to reflect the content model. I don't think the benefits are big enough to change in that direction.

[iherman]

The point is not the XML content model. It so happens that the main elements that can appear as children of package constitute the main functionalities of the package as a whole, and I find it more readable if those functionalities are clearly reflected in the sectioning. itemref happens to be a refinement of the functionality of spine, etc. Flattening everything reduces readability for me.

But, as I said, it is a matter of taste.

[mattgarrish]

Sure, I understand, but what it starts to look like is the content model since there's typically tight binding between functionality and hierarchy.

Instead of merging element definitions into element definitions, and the resultant deep nesting, what about grouping the three major sections?

3.4.1. The package Element
3.4.2 Package Metadata
3.4.2.1. The metadata Element
3.4.2.2. The DCMES identifier Element
3.4.2.3. The DCMES title Element
3.4.2.4. The DCMES language Element
3.4.2.5. DCMES Optional Elements
3.4.2.5.1. General Definition
3.4.2.5.2. The DCMES contributor Element
3.4.2.5.3. The DCMES creator Element
3.4.2.5.4. The DCMES date Element
3.4.2.5.5. The DCMES subject Element
3.4.2.5.6. The DCMES type Element
3.4.2.6. The meta Element
3.4.2.7. The link Element
3.4.3. Package Manifest
3.4.3.1. The manifest Element
3.4.3.2. The item Element
3.4.4. Package Spine
3.4.4.1. The spine Element
3.4.4.2. The itemref Element
3.4.5. The collection Element
3.4.6 Shared Attributes

[iherman]

Yep, I definitely prefer that to what is there now. Looks like a good compromise to me.

Ivan

On 12 Aug 2016, at 16:29, Matt Garrish [email protected] wrote:

Sure, I understand, but what it starts to look like is the content model since there's typically tight binding between functionality and hierarchy.

Instead of merging element definitions into element definitions, and the resultant deep nesting, what about grouping the three major sections?

3.4.1. The package Element
3.4.2 Package Metadata
3.4.2.1. The metadata Element
3.4.2.2. The DCMES identifier Element
3.4.2.3. The DCMES title Element
3.4.2.4. The DCMES language Element
3.4.2.5. DCMES Optional Elements
3.4.2.5.1. General Definition
3.4.2.5.2. The DCMES contributor Element
3.4.2.5.3. The DCMES creator Element
3.4.2.5.4. The DCMES date Element
3.4.2.5.5. The DCMES subject Element
3.4.2.5.6. The DCMES type Element
3.4.2.6. The meta Element
3.4.2.7. The link Element
3.4.3. Package Manifest
3.4.3.1. The manifest Element
3.4.3.2. The item Element
3.4.4. Package Spine
3.4.4.1. The spine Element
3.4.4.2. The itemref Element
3.4.5. The collection Element
3.4.6 Shared Attributes

[mattgarrish]

To retain a bit of symmetry to the DCMES elements, and avoid repeating "DCMES" over and over, this might be a bit better:

3.4.1. The package Element
3.4.2. Shared Attributes
3.4.3. Metadata
    3.4.3.1. The metadata Element
    3.4.3.2. DCMES Required Elements
        3.4.3.2.1. The identifier Element
        3.4.3.2.2. The title Element
        3.4.3.2.3. The language Element
    3.4.3.3. DCMES Optional Elements
        3.4.3.3.1. General Definition
        3.4.3.3.2. The contributor Element
        3.4.3.3.3. The creator Element
        3.4.3.3.4. The date Element
        3.4.3.3.5. The subject Element
        3.4.3.3.6. The type Element
    3.4.3.4. The meta Element
    3.4.3.5. The link Element
3.4.4. Manifest
    3.4.4.1. The manifest Element
    3.4.4.2. The item Element
3.4.5. Spine
    3.4.5.1. The spine Element
    3.4.5.2. The itemref Element
3.4.6 Collections
    3.4.6.1. The collection Element

It moves the shared attribute definitions back up to the top. That's still my preference, and the added "allowed on" list really should be enough to dispel the idea they're global attributes for people who don't read the definition. Moving them down was just added emphasis.

I'm not sure a section for the collection element is really needed, but it stops it from dangling alone at the end.

[iherman]

Looks really good to me! Thx

On 13 Aug 2016, at 00:56, Matt Garrish [email protected] wrote:

To retain a bit of symmetry to the DCMES elements, and avoid repeating "DCMES" over and over, this might be a bit better:

3.4.1. The package Element
3.4.2. Shared Attributes
3.4.3. Metadata
3.4.3.1. The metadata Element
3.4.3.2. DCMES Required Elements
3.4.3.2.1. The identifier Element
3.4.3.2.2. The title Element
3.4.3.2.3. The language Element
3.4.3.3. DCMES Optional Elements
3.4.3.3.1. General Definition
3.4.3.3.2. The contributor Element
3.4.3.3.3. The creator Element
3.4.3.3.4. The date Element
3.4.3.3.5. The subject Element
3.4.3.3.6. The type Element
3.4.3.4. The meta Element
3.4.3.5. The link Element
3.4.4. Manifest
3.4.4.1. The manifest Element
3.4.4.2. The item Element
3.4.5. Spine
3.4.5.1. The spine Element
3.4.5.2. The itemref Element
3.4.6 Collections
3.4.6.1. The collection Element
It moves the shared attribute definitions back up to the top. That's still my preference, and the added "allowed on" list really should be enough to dispel the idea they're global attributes for people who don't read the definition. Moving them down was just added emphasis.

I'm not sure a section for the collection element is really needed, but it stops it from dangling alone at the end.

[mattgarrish]

Proposed Solution:

Restructure the package document definition as described in my previous comment.

[mattgarrish]

Another late thought, but in this new model we could also move the manifest fallbacks section up to the Manifest section. It's currently located after all the element definitions.

[iherman]

It does look more logical indeed. Works for me.