dauwhe / epub31-bff Goto Github PK

Should we really create a dedicated element for media-overlay? Can we design something more generic instead that could also handle other use cases? EPUB 3.1 introduces duration, do we need other media specific attributes?

As Element

{
        "href": "xhtml/chapter01.xhtml",
        "type": "application/xhtml+xml",
        "media-overlay": "chapter1_audio.smil"
      }

As nested link element

{
        "href": "xhtml/chapter03.xhtml",
        "type": "application/xhtml+xml",
        "links": {
            "type:": "application/smil+xml",
            "href": "chapter3_audio.smil",
            "rel": "media-overlay"
         }
      }

The proposal currently states:

All extensions would have to use full IRIs since additional context definition won't be allowed

Hadrien has said (in an email thread):

I strongly believe that we should disallow the use of @context for anything else than defining our own external context.

Ivan Herman replied (in an email thread):

Well… while disallowing the usage of @vocab might indeed be acceptable (if it can be reinforced), centralizing the @context the way you propose may backfire. The advantage of using JSON-LD is to provide flexibility to users or, let us say, user communities in terms of what vocabularies they would prefer to use. The bibliography terms used by the scholarly community are different than, say, the ONIX terms that trade publishers may want to use (or the schema version thereof); why not letting the respective communities use what they want (beyond some universally required terms that EPUB may define, of course)

Hi
Why not consider my 5doc.org approach which works right now - today?
To clarify, in a 5DOC all bundled stuff - CSS Javascript, media, SVG, fonts - are in one HTML file.
User simply downloads the file and double clicks on it to open it in a browser.

Cheers
Mike

Mailing list thread:

https://groups.google.com/forum/#!searchin/epub-working-group/Encryption$20in$20BFF$20land/epub-working-group/tU1c0e5z54k/DpGyAEgmBwAJ

If a JSON package is used, should it be a standalone file, or embedded in an HTML document (such as nav)?

We should pay close attention to the web application manifest spec. I'd propose that we use their format for many basic things; I believe we can extend without making the files invalid as web app manifests. Quick example:

{
    "name": "Moby-Dick",
    "short_name": "Moby-Dick",
    "icons": [{
        "src": "apple-touch-icon.png",
        "sizes": "64x64",
        "type": "image/png"
    }],
    "start_url": "index.html",
    "display": "fullscreen",

    "@context": {
        "title": "http://schema.org/name",
        "language": "http://schema.org/inLanguage",
        "version": "http://schema.org/version",
        "modified": "http://schema.org/dateModified",
        "mediaType": "http://schema.org/fileFormat",
        "href": "http://schema.org/url"
    },

    "@type": "http://schema.org/Book",
    "@id": "https://dauwhe.github.io/epub-zero/acme-publishing/MobyDick/",
    "specVersion": "4.0",

    "metadata": {
        "title": "Moby-Dick",
        "language": "en-US",
        "modified": "2015-09-29T17:00:00Z",
        "version": "1.0",
        "identifier": "9780000000000"
    },

    "spine": [{
        "href": "html/title-page.html",
        "type": "text/html"
    }, {
        "href": "html/copyright.html",
        "type": "text/html"
    }, {
        "href": "html/introduction.html",
        "type": "text/html"
    }]
}

The proposal currently says that the JSON package document must be called package.json and located at the top level of the file system container. I've heard some general objections to defined names. Are there other suggestions here?

Assuming we made it straightforward and all, of course :)

cc @sballesteros

How will rendition mapping work in EPUB BFF? Is it still based on the Navigation Document like in AHL? Can we introduce a new collection role instead and represent it as a collection? Can we inline that info in the rendition itself?

Mailing list thread:

https://groups.google.com/forum/#!searchin/epub-working-group/container%5D$20publication$20identifier/epub-working-group/-mHgOTK0Kik/J3T2jL6yBQAJ

The vast majority of EPUBs contain a single rendition. Given that, what are the advantages and disadvantages of requiring a rendition object or array in the JSON package? Would it be desireable to omit the rendition object when not required?

{
    "metadata": {
        "title": "hello, world"
    },
    "links": [{
        "href": "index.html"
    }],
    "manifest": {
        "links": [{
            "href": "style.css"
        }]
    }
}

Advantages:

1. Simplicity for authors
2. Less nesting
3. Covers 99%+ of publications

Disadvantages

1. data model is less consistent
2. doesn't provide separation of bibliographic and rendition metadata for single renditions

While a previous version of the specification used SMIL clock for this value, the current version is based on seconds.

Should we keep it in seconds or use ISO8601 duration for example?

video/audio in HTML5 use seconds, and duration in Media RSS too.

The role attribute is "to annotate markup languages with machine-extractable semantic information about the purpose of an element." (https://www.w3.org/TR/role-attribute/). This means that it provides specific information about the element to which it is applied. In the collections example

 <ol role="doc-index">

is in fact the index. role="doc-index" should be applied to the index itself, not something that links to the index. The authors of the DPUB-ARIA spec might want to consider nesting doc-toc or allowing something akin to the EPUB 2 element with a title or label. Would this suffice?

Transferring from issue #13 comment as a separate issue.

@HadrienGardeur wrote:

We need to be more crisp than that. Is it possible to say that the metadata part of the model is the set of RDF metadata terms that are relevant for the publication (or a rendition)?

It's actually a set of RDF metadata terms that are relevant for the current collection.
At a top-level metadata will be about publication, while inside renditions it'll be about the rendition it's part of.

If we say that, does that also means that, in the JSON representation of the model, that part of the information SHOULD (or MUST) be considered as a JSON-LD section, with all possibly syntactical consequences thereof? Or do we intend to consider the whole thing as one big JSON-LD (I would be a bit concerned about this)?

I previously proposed the use of a JSON-LD fragment but after discussions with you and others, dropped the idea and focused on creating a context that works for the whole document instead: https://gist.github.com/HadrienGardeur/03ab96f5770b0512233a
That said, it doesn't cover all of the keys defined in the manifest, just a subset of them.

if we have a JSON-LD 'fragment', this means we have to have a special processing model/procedure to extract that part and hand it over to a bona fide JSON-LD processor

Agree, that's part of the reason why I would rather avoid this.

if the whole thing is JSON-LD, then we may have to pay a price in terms of additional complexity in term of syntax (e.g., the usage of @graph)

That's why I would like to have additional restrictions and not allow full JSON-LD.

Should we try to create a JSON-LD context for the document structure? Initial attempts to map this to schema.org have not faired well, due to both the limited vocabulary in schema.org, and the difficulty of handling wrapper elements.

Mailing list thread:

https://groups.google.com/forum/#!searchin/epub-working-group/Does$20BFF$20deprecate$20CFI$20use$3F/epub-working-group/HqY8EYguiBw/XNA3PSydBQAJ

Ivan Herman wrote (in an email thread):

Per the JSON-LD expansion rules if one uses the (perfectly valid!) @vocab rule in the @context, the situation changes radically. Essentially, this means that, with @vocab, all properties get a possibly fake value. In other words, we should disallow the usage of a specific JSON-LD feature in our format. This is doable, but we should be aware of that.

In the proposal, a rendition object (see issue #13 ) contains a links array which contains objects describing the files, unless they are not spine items, in which case they're one level deeper in a manifest object. Might a simpler structure contain the same information?

{
    "metadata": {
        "title": "hello, world"
    },

    "manifest": [{
        "href": "index.html"
    }, {
        "href": "style.css"
    }]

}

One could determine which files are spine items by file extension and/or attribute. Again, in the common cases HTML files are spine items, and everything else isn't.

Advantages:

1. Simplicity of authoring and structure
2. Can easily handle current EPUB 3.0.1 linear=no behavior

Disadvantages:

1. Processing required to extract "spine"
2. Depending on details, it may be more work to create image-only publications
3. Imposes an ordering on non-spine files

See example 5, which is essentially Example 40 from the indexing spec.

This seems insanely complex. Do we want to support this? Note that nesting collections in JSON becomes even less readable than in XML, and one can spend many unhappy hours at jsonlint.com :)

EPUB BFF supports a title on each element of the "spine". Should that be a requirement? Should we require it strictly on some links? If we allow images in spine, should they be required to have a title?

{
        "href": "notes.html",
        "media-type": "text/html",
        "title": "Notes from the editor"
      }

Since EPUB BFF can provide the equivalent of a table of contents with a single level of depth (no nesting), is it still a requirement to have a Navigation Document? Should the Navigation Document become optional, for example to provide a more complex structure or provide things that only an HTML text node can do?

"links": [{
"href": "c001.html",
"media-type": "text/html",
"title": "Loomings"
}]