Container, publication, package, package document, and rendition

[murata2makoto]

I am reading definitions of container, package, publication, rendition, package document,

What we have is very strange. Here is my understanding.

1. container: publication = 1:1

2. package: package document : rendition = 1:1:1

3. container:package = 1:n

The last point is very unintuitive. People will certainly assume that "package" and "container" are synonyms, but they are not. A (ZIP) container may contain multiple packages.

I know that our hands are tied: some terms were introduced before multiple renditions were
introduced. But we should at least provide notes (and even diagrams) for explaining peculiarities of our terminology.

[iherman]

+1 to some informal description or, even better, a diagram with practical examples

On 13 Aug 2016, at 07:37, MURATA Makoto notifications@github.com wrote:

I am reading definitions of container, package, publication, rendition, package document,

What we have is very strange. Here is my understanding.

1. container: publication = 1:1

2. package: package document : rendition = 1:1:1

3. container:package = 1:n

The last point is very unintuitive. People will certainly assume that "package" and "container" are synonyms, but they are not. A (ZIP) container may contain multiple packages.

I know that our hands are tied: some terms were introduced before multiple renditions were
introduced. But we should at least provide notes (and even diagrams) for explaining peculiarities of our terminology.

[mattgarrish]

For the record, I had this in mind and decided not to pursue because we aren't integrating multiple renditions (and for time reasons):
#614

Conceptually a Publication contains 1..n Renditions.
Practically a Container contains 1..n Packages

The package document is one resource in a Package, so it's at a level below these models.

[murata2makoto]

We might want to deprecate multiple renditions?

[mattgarrish]

Why?

I see the question as how many issues do we try to solve without trying to formalize the mechanism.

Since we don't have selection in OCF, I think it's just going to cause more confusion to promote these concepts too heavily. An epub is still generally considered one publication, which is one package.

I've probably said this before, but my preference would be to get some reading systems to start supporting multiple renditions and then do a 3.1.1 that just focuses on integration and fixing the problems we had to work around in the MR spec., plus any bugs found in real-world implementation of the functionality.

[GarthConboy]

As much as I might like to deprecate multiple renditions, as they have not yet gotten much traction, I think it's too late (and too major) for 3.1 -- and they may well get traction in the future. I'd tend to stay the course for 3.1.

[mattgarrish]

Closing this without action. This is an issue we can deal with if/when multiple renditions are added and complete details are available.

[murata2makoto]

At the very least, some notes should be introduced. For example:

Note: Containers and packages can be different. A container typically contains one and only one package, but it can contain multiple packages.

[GarthConboy]

This is an awkward horse beat in that Multiple Renditions aren't in our main Spec (yet).

Matt, do you think it's viable to add in Makoto's "Note: Containers and packages can be different. A container typically contains one and only one package, but it can contain multiple packages." without pulling in multiple renditions, or just reference it?

[mattgarrish]

How do you not figure this out from the conformance requirements for a publication?

3.1 EPUB Publications
An EPUB Publication must meet all of the following criteria:

Packages
It must include one or more EPUB Packages, each of which must conform to the requirements defined in [Packages 3.1].
...
Container
It must be packaged in a EPUB Container as defined in [OCF 3.1].

[mattgarrish]

And as I said above, I already tried to elaborate and gave up on the idea. You can still see the prose I drafted commented out at [1] if you're curious.

To do properly requires resolving multiple renditions (or removing), as drawing it out only highlights the parts that are incomplete. There's enough information now between the definitions and the content conformance requirements to cover the meanings.

[1] https://github.com/IDPF/epub-revision/blob/master/src/spec/epub-packages.xml#L148

[mattgarrish]

If dropping a diagram into the roadmap section will make this issue go away, that's about as far as I see we should go (i.e., a bunch of wrapper blocks for container, publication, 1..n packages, 1 package document, 1 navigation document plus a blob of "resources").

[mattgarrish]

For example...

[mattgarrish]

And here's a potential readjustment of the roadmap section to fit:
https://docs.google.com/document/d/1WEmh-llfky8eq9qS3timYNHQeQdz4eYmdlxGCYTkYZY/edit?usp=sharing

[iherman]

This works for me. Having this in the roadmap document is, in my view, really helpful; go for it!

[iherman]

Actually, I may want to use this in presentations; do you have it in SVG that you can share?

[mattgarrish]

Proposed Solution:

Rewrite the roadmap section and add the image as described above.

[GarthConboy]

God, I hate to comment on this long running issue... but, in the image, I'd remove "EPUB Package" -- I don't ever think of a Package as containing multiple Package Documents.

Am I missing something?

[mattgarrish]

It's the same question we were trying to hash out earlier as part of the thread that weaved into spec naming (#778).

If we allow multiple renditions, then a package cannot be just one package document plus resources. A package is the set of resources that define one rendition, so we have to allow multiple packages.

Should we replace EPUB Package with Rendtion except when talking about all the resources that make up a publication?

In other words, a publication consists of one package, as defined in EPUB Package 3.1 (no plural on the spec name).

And then in Package 3.1 we state that a package consists of one or more renditions, and keep the rules for a package as the rules for a rendition?

[GarthConboy]

I completely misread the picture (I was seeing the inner dark-blue items as multiple package documents, but it's really Package, Nav, Resources).

Sorry! Perfect as is! Duh.