Multiple Renditions
An EPUB publication(file) may have multiple renditions, how reading system renders contents. It is expressed as multiple EPUB::Publication::Package object.
Usually, you don't need to care about it.
epub = EPUB::Parser.parse('path/to/book')
epub.package # => #<EPUB::Publication::Package...>
This is enough in most cases.
Getting multiple renditions
If your book has multiple renditions, you can get them by EPUB::Book::Features#packages, aliased as #renditoins.
epub.packages # => [#<EPUB::Publication::Package...>, #<EPUB::Publication::Package...>, ...]
epub.package is shortcut to epub.packages.first(called default rendition).
epub.package == epub.packages.first # => true
epub.default_rendition == epub.packages.first # => true
Metadata of renditions
Sometimes, the situation about metadata is more complicated.
A publication may have multiple rendition(package)s. A rendition has a metadata. So, A publication has as many metadata objects as renditions...
epub.packages.all? {|package| package.respond_to? :metadata} # => true
... at least.
In addition, a publication may have a metadata that is not related to any rendition but to EPUB file itself. You can access to it by:
epub.ocf. # => #<EPUB::Metadata...>
This kind of metadata is introduced by EPUB Multiple-Rendition Publications spec and most EPUB files don't have that for now. So, you need to note that epub.ocf.metadata might be nil.
Identifiers
You can identify any metadata by identifers called release identifier. If your book has metadata for publication and packages, they might not have the same identifier to any identifiers of renditions. By this difference, publishers or authors can represent the situation "all renditions are changed but the book itself is not." To do so, publishers or authors will change all identifiers of renditions(epub.packages.collect(&:metadata).collect(&:release_identifier)) but keep epub.ocf.metadata.release_identifier.
Known issues
Currently, at least on v0.2.6, EPUB Parser provides limited support for Multiple-Rendition spec.