diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..241b5c1 --- /dev/null +++ b/.gitignore @@ -0,0 +1,4 @@ +/target +test.epub +nb-configuration.xml +nbactions.xml diff --git a/pom.xml b/pom.xml new file mode 100644 index 0000000..2699634 --- /dev/null +++ b/pom.xml @@ -0,0 +1,55 @@ + + + 4.0.0 + coza.opencollab + epub-creator + 1.0.0-SNAPSHOT + jar + + + junit + junit + 4.10 + test + + + net.sourceforge.htmlcleaner + htmlcleaner + 2.8 + + + commons-io + commons-io + 2.4 + + + commons-collections + commons-collections + 3.2.1 + + + + + UTF-8 + 1.7 + 1.7 + + + + + oc-nexus-releases + OpenCollab Nexus Release Repo + + http://nexus.opencollab.co.za/nexus/content/repositories/releases + + + + oc-nexus-snapshot + OpenCollab Nexus Snapshot Repo + + http://nexus.opencollab.co.za/nexus/content/repositories/snapshots + + + + + \ No newline at end of file diff --git a/src/main/java/coza/opencollab/epub/creator/EpubConstants.java b/src/main/java/coza/opencollab/epub/creator/EpubConstants.java new file mode 100644 index 0000000..bb5a5dc --- /dev/null +++ b/src/main/java/coza/opencollab/epub/creator/EpubConstants.java @@ -0,0 +1,100 @@ +/* Copyright 2014 OpenCollab. + * + * Permission is hereby granted, free of charge, to any person obtaining a copy + * of this software and associated documentation files (the "Software"), to deal + * in the Software without restriction, including without limitation the rights + * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell + * copies of the Software, and to permit persons to whom the Software is + * furnished to do so, subject to the following conditions: + * + * The above copyright notice and this permission notice shall be included in + * all copies or substantial portions of the Software. + * + * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE + * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, + * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN + * THE SOFTWARE. + */ +package coza.opencollab.epub.creator; + +/** + * Constants used as default values in the EpubCreator and EpubBook. This is set + * according to the EPUB 3 standards. + * + * @author OpenCollab + */ +public class EpubConstants { + + private EpubConstants() { + } + + /** + * Used to wrap plain text in a valid XHTML document + */ + public static final String HTML_WRAPPER = "{0}{1}"; + + /** + * Template of the OPF file + */ + public static final String OPF_XML = "\n" + + "\n" + + " \n" + + " \n" + + " \n" + + " \n" + + " " + + " \n" + + " \n" + + " \n" + + " \n" + + " \n" + + ""; + + /** + * Template of a valid table of contents navigation(TOC) XHTML document + */ + public static final String TOC_XML = "\n" + + "\n" + + " \n" + + " \n" + + " {0} \n" + + " \n" + + " \n" + + " \n" + + " \n" + + " \n" + + ""; + + /** + * Template of a valid EPUB3 container XML + */ + public static final String CONTAINER_XML = "\n" + + "\n" + + " \n" + + " \n" + + " \n" + + ""; + + /** + * Default folder used to save content in + */ + public static final String CONTENT_FOLDER = "content"; + + /** + * The default href of the toc file + */ + public static final String TOC_FILE_NAME = "toc.xhtml"; + + /** + * The default href of the opf file + */ + public static final String OPF_FILE_NAME = "book.opf"; + +} diff --git a/src/main/java/coza/opencollab/epub/creator/api/OpfCreator.java b/src/main/java/coza/opencollab/epub/creator/api/OpfCreator.java new file mode 100644 index 0000000..c9bf84a --- /dev/null +++ b/src/main/java/coza/opencollab/epub/creator/api/OpfCreator.java @@ -0,0 +1,41 @@ +/* Copyright 2014 OpenCollab. + * + * Permission is hereby granted, free of charge, to any person obtaining a copy + * of this software and associated documentation files (the "Software"), to deal + * in the Software without restriction, including without limitation the rights + * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell + * copies of the Software, and to permit persons to whom the Software is + * furnished to do so, subject to the following conditions: + * + * The above copyright notice and this permission notice shall be included in + * all copies or substantial portions of the Software. + * + * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE + * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, + * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN + * THE SOFTWARE. + */ +package coza.opencollab.epub.creator.api; + +import coza.opencollab.epub.creator.model.EpubBook; + +/** + * Service to create the Package Document that carries bibliographic and + * structural meta data about an EPUB Publication + * + * @author OpenCollab + */ +public interface OpfCreator { + + /** + * Creates the OPF file text from the EpubBook data + * + * @param book the ePub book to generate the OPF for + * @return the generated OPF markup + */ + public String createOpfString(EpubBook book); + +} diff --git a/src/main/java/coza/opencollab/epub/creator/api/TocCreator.java b/src/main/java/coza/opencollab/epub/creator/api/TocCreator.java new file mode 100644 index 0000000..fb298a3 --- /dev/null +++ b/src/main/java/coza/opencollab/epub/creator/api/TocCreator.java @@ -0,0 +1,41 @@ +/* Copyright 2014 OpenCollab. + * + * Permission is hereby granted, free of charge, to any person obtaining a copy + * of this software and associated documentation files (the "Software"), to deal + * in the Software without restriction, including without limitation the rights + * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell + * copies of the Software, and to permit persons to whom the Software is + * furnished to do so, subject to the following conditions: + * + * The above copyright notice and this permission notice shall be included in + * all copies or substantial portions of the Software. + * + * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE + * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, + * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN + * THE SOFTWARE. + */ +package coza.opencollab.epub.creator.api; + +import coza.opencollab.epub.creator.model.Content; +import coza.opencollab.epub.creator.model.EpubBook; + +/** + * Service to create the EPUB navigation document + * + * @author OpenCollab + */ +public interface TocCreator { + + /** + * Creates the EPUB TOC navigation document Content object + * + * @param book the EpubBook to create the TOC for + * @return the TOC Content object + */ + public Content createTocFromBook(EpubBook book); + +} diff --git a/src/main/java/coza/opencollab/epub/creator/impl/OpfCreatorDefault.java b/src/main/java/coza/opencollab/epub/creator/impl/OpfCreatorDefault.java new file mode 100644 index 0000000..239baa6 --- /dev/null +++ b/src/main/java/coza/opencollab/epub/creator/impl/OpfCreatorDefault.java @@ -0,0 +1,202 @@ +/* Copyright 2014 OpenCollab. + * + * Permission is hereby granted, free of charge, to any person obtaining a copy + * of this software and associated documentation files (the "Software"), to deal + * in the Software without restriction, including without limitation the rights + * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell + * copies of the Software, and to permit persons to whom the Software is + * furnished to do so, subject to the following conditions: + * + * The above copyright notice and this permission notice shall be included in + * all copies or substantial portions of the Software. + * + * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE + * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, + * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN + * THE SOFTWARE. + */ +package coza.opencollab.epub.creator.impl; + +import coza.opencollab.epub.creator.EpubConstants; +import coza.opencollab.epub.creator.api.OpfCreator; +import coza.opencollab.epub.creator.model.Content; +import coza.opencollab.epub.creator.model.EpubBook; +import java.text.SimpleDateFormat; +import java.util.Date; +import org.htmlcleaner.CleanerProperties; +import org.htmlcleaner.ContentNode; +import org.htmlcleaner.HtmlCleaner; +import org.htmlcleaner.PrettyXmlSerializer; +import org.htmlcleaner.Serializer; +import org.htmlcleaner.TagNode; + +/** + * Default implementation of the OpfCreator. This follows EPUB3 standards to + * create the OPF file content. + * + * @author OpenCollab + */ +public class OpfCreatorDefault implements OpfCreator { + + /** + * The template XML used to create the OPF file. This is settable if a + * different template needs to be used. + */ + private String opfXML = EpubConstants.OPF_XML; + + /** + * HtmlCleaner used to clean the XHTML document + */ + private final HtmlCleaner cleaner; + + /** + * XmlSerializer used to format to XML String output + */ + private final Serializer htmlSetdown; + + public OpfCreatorDefault() { + cleaner = new HtmlCleaner(); + CleanerProperties htmlProperties = cleaner.getProperties(); + htmlProperties.setOmitHtmlEnvelope(true); + htmlProperties.setAdvancedXmlEscape(false); + htmlProperties.setUseEmptyElementTags(true); + htmlSetdown = new PrettyXmlSerializer(htmlProperties); + } + + /** + * {@inheritDoc} + */ + @Override + public String createOpfString(EpubBook book) { + TagNode tagNode = cleaner.clean(opfXML); + addMetaDataTags(tagNode, book); + addManifestTags(tagNode, book); + addSpineTags(tagNode, book); + return htmlSetdown.getAsString(tagNode); + } + + /** + * Add the required meta data + * + * @param tagNode the HTML tagNode of the OPF template + * @param book the EpubBook + */ + private void addMetaDataTags(TagNode tagNode, EpubBook book) { + TagNode metaNode = tagNode.findElementByName("metadata", true); + addNodeData(metaNode, "dc:identifier", book.getId()); + addNodeData(metaNode, "dc:title", book.getTitle()); + addNodeData(metaNode, "dc:language", book.getLanguage()); + addNodeData(metaNode, "meta", new SimpleDateFormat("yyyy-MM-dd'T'hh:mm:ss'Z'").format(new Date())); + if (book.getAuthor() != null) { + TagNode creatorNode = new TagNode("dc:creator"); + creatorNode.addChild(new ContentNode(book.getAuthor())); + metaNode.addChild(creatorNode); + } + } + + /** + * Adds a item tag to the manifest for each Content object. + * + * The manifest contains all Content that will be added to the EPUB as files + * + * @param tagNode the HTML tagNode of the OPF template + * @param book the EpubBook + */ + private void addManifestTags(TagNode tagNode, EpubBook book) { + TagNode manifestNode = tagNode.findElementByName("manifest", true); + for (Content content : book.getContents()) { + manifestNode.addChild(buildItemNode(content)); + } + } + + /** + * Builds an item tag from the Content object + * + * @param content + * @return + */ + private TagNode buildItemNode(Content content) { + TagNode itemNode = new TagNode("item"); + itemNode.addAttribute("href", content.getHref()); + itemNode.addAttribute("id", content.getId()); + itemNode.addAttribute("media-type", content.getMediaType()); + if (content.getProperties() != null) { + itemNode.addAttribute("properties", content.getProperties()); + } + if (content.hasFallBack()) { + itemNode.addAttribute("fallback", content.getFallBack().getId()); + } + return itemNode; + } + + /** + * Adds item ref tags for all Content objects that must be added to the + * spine. + * + * The spine contains all the resources that will be shown when reading the + * book from start to end + * + * @param tagNode the HTML tagNode of the OPF template + * @param book the EpubBook + */ + private void addSpineTags(TagNode tagNode, EpubBook book) { + TagNode spineNode = tagNode.findElementByName("spine", true); + for (Content content : book.getContents()) { + if (content.isSpine()) { + spineNode.addChild(buildItemrefNode(content)); + } + } + } + + /** + * Builds an item ref tag from the Content object + * + * @param content + * @return + */ + private TagNode buildItemrefNode(Content content) { + TagNode itemNode = new TagNode("itemref"); + itemNode.addAttribute("idref", content.getId()); + if (!content.isLinear()) { + itemNode.addAttribute("linear", "no"); + } + return itemNode; + } + + /** + * Adds a ContentNode (value) with to a child element of the TagNode + * + * {value} + * + * @param tagNode + * @param elementName + * @param value + */ + private void addNodeData(TagNode tagNode, String elementName, String value) { + TagNode editNode = tagNode.findElementByName(elementName, true); + editNode.addChild(new ContentNode(value)); + } + + /** + * The base XML used for the OPF file. + * + * @return the OPF XML text + */ + public String getOpfXML() { + return opfXML; + } + + /** + * The base XML used for the OPF file. This is optional as there is a EPUB3 + * standard default but it can be overridden. + * + * @param opfXML the OPF XML to set + */ + public void setOpfXML(String opfXML) { + this.opfXML = opfXML; + } + +} diff --git a/src/main/java/coza/opencollab/epub/creator/impl/TocCreatorDefault.java b/src/main/java/coza/opencollab/epub/creator/impl/TocCreatorDefault.java new file mode 100644 index 0000000..c4182ed --- /dev/null +++ b/src/main/java/coza/opencollab/epub/creator/impl/TocCreatorDefault.java @@ -0,0 +1,220 @@ +/* Copyright 2014 OpenCollab. + * + * Permission is hereby granted, free of charge, to any person obtaining a copy + * of this software and associated documentation files (the "Software"), to deal + * in the Software without restriction, including without limitation the rights + * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell + * copies of the Software, and to permit persons to whom the Software is + * furnished to do so, subject to the following conditions: + * + * The above copyright notice and this permission notice shall be included in + * all copies or substantial portions of the Software. + * + * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE + * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, + * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN + * THE SOFTWARE. + */ +package coza.opencollab.epub.creator.impl; + +import coza.opencollab.epub.creator.EpubConstants; +import coza.opencollab.epub.creator.api.TocCreator; +import coza.opencollab.epub.creator.model.Content; +import coza.opencollab.epub.creator.model.EpubBook; +import coza.opencollab.epub.creator.model.Landmark; +import coza.opencollab.epub.creator.model.TocLink; +import java.util.ArrayList; +import java.util.List; +import org.apache.commons.collections.CollectionUtils; +import org.htmlcleaner.CleanerProperties; +import org.htmlcleaner.ContentNode; +import org.htmlcleaner.HtmlCleaner; +import org.htmlcleaner.PrettyXmlSerializer; +import org.htmlcleaner.Serializer; +import org.htmlcleaner.TagNode; + +/** + * Default implementation of the TocCreator. This follows EPUB3 standards to + * create the Navigation Document file content. + * + * @author OpenCollab + */ +public class TocCreatorDefault implements TocCreator { + + /** + * HtmlCleaner used to alter the XHTML document + */ + private final HtmlCleaner cleaner; + + private String href = EpubConstants.TOC_FILE_NAME; + + private String tocHtml = EpubConstants.TOC_XML; + + /** + * XmlSerializer used to format to XML String output + */ + private final Serializer htmlSetdown; + + public TocCreatorDefault() { + cleaner = new HtmlCleaner(); + CleanerProperties htmlProperties = cleaner.getProperties(); + htmlProperties.setOmitHtmlEnvelope(false); + htmlProperties.setAdvancedXmlEscape(false); + htmlProperties.setUseEmptyElementTags(true); + htmlSetdown = new PrettyXmlSerializer(htmlProperties); + } + + /** + * {@inheritDoc} + */ + @Override + public Content createTocFromBook(EpubBook book) { + List links = book.getTocLinks(); + if (book.isAutoToc()) { + links = generateAutoLinks(book); + } + List landmarks = book.getLandmarks(); + String tocString = createTocHtml(links, landmarks, getTocHtml()); + Content toc = new Content("application/xhtml+xml", getHref(), tocString.getBytes()); + toc.setProperties("nav"); + toc.setId("toc"); + toc.setLinear(false); + return toc; + } + + /** + * Builds the TOC HTML content from the EpubBook TocLinks + * + * @param book the EpubBook + * @return the TOC HTML String + */ + private String createTocHtml(List links, List landmarks, String tocHtml) { + TagNode tagNode = cleaner.clean(tocHtml); + if (!CollectionUtils.isEmpty(links)) { + addTocLinks(tagNode, links); + } + if (!CollectionUtils.isEmpty(landmarks)) { + addLandmarks(tagNode, landmarks); + } + return htmlSetdown.getAsString(tagNode); + } + + /** + * Recursive method adding links and sub links to the TOC Navigation + * Document + * + * @param tagNode + * @param links + */ + private void addTocLinks(TagNode tagNode, List links) { + TagNode navNode = tagNode.findElementByAttValue("epub:type", "toc", true, false); + TagNode parentNode = navNode.findElementByName("ol", true); + for (TocLink toc : links) { + TagNode linkNode = buildLinkNode(toc); + if (!CollectionUtils.isEmpty(toc.getTocChildLinks())) { + TagNode olNode = new TagNode("ol"); + addTocLinks(olNode, toc.getTocChildLinks()); + linkNode.addChild(olNode); + } + parentNode.addChild(linkNode); + } + } + + /** + * Adds landmarks to the Navigation Document + * + * @param tagNode + * @param links + */ + private void addLandmarks(TagNode tagNode, List landmarks) { + TagNode navNode = tagNode.findElementByAttValue("epub:type", "landmarks", true, false); + TagNode parentNode = navNode.findElementByName("ol", true); + for (Landmark landmark : landmarks) { + TagNode landmarkNode = buildLandMarkNode(landmark); + parentNode.addChild(landmarkNode); + } + } + + /** + * Builds an link tag for the TOC + * + * @param content + * @return + */ + private TagNode buildLinkNode(TocLink link) { + TagNode linkNode = new TagNode("li"); + TagNode aNode = new TagNode("a"); + aNode.addAttribute("href", link.getHref()); + aNode.addChild(new ContentNode(link.getTitle())); + if (link.getAltTitle() != null) { + aNode.addAttribute("title", link.getHref()); + } + linkNode.addChild(aNode); + return linkNode; + } + + /** + * Builds an link tag for the TOC landmarks + * + * @param content + * @return + */ + private TagNode buildLandMarkNode(Landmark landmark) { + TagNode linkNode = new TagNode("li"); + TagNode aNode = new TagNode("a"); + aNode.addAttribute("href", landmark.getHref()); + aNode.addAttribute("epub:type", landmark.getType()); + aNode.addChild(new ContentNode(landmark.getTitle())); + linkNode.addChild(aNode); + return linkNode; + } + + /** + * Generates a list of TocLinks for all Content that should be included in + * the Navigation Document. This will only be used when auto TOC is set + * + * @param book + * @return + */ + private List generateAutoLinks(EpubBook book) { + List links = new ArrayList(); + for (Content content : book.getContents()) { + if (content.isToc()) { + links.add(new TocLink(content.getHref(), content.getId(), null)); + } + } + return links; + } + + /** + * @return the HREF + */ + public String getHref() { + return href; + } + + /** + * @param href the HREF to set + */ + public void setHref(String href) { + this.href = href; + } + + /** + * @return the tocHtml + */ + public String getTocHtml() { + return tocHtml; + } + + /** + * @param tocHtml the tocHtml to set + */ + public void setTocHtml(String tocHtml) { + this.tocHtml = tocHtml; + } + +} diff --git a/src/main/java/coza/opencollab/epub/creator/model/Content.java b/src/main/java/coza/opencollab/epub/creator/model/Content.java new file mode 100644 index 0000000..6c77a5b --- /dev/null +++ b/src/main/java/coza/opencollab/epub/creator/model/Content.java @@ -0,0 +1,336 @@ +/* Copyright 2014 OpenCollab. + * + * Permission is hereby granted, free of charge, to any person obtaining a copy + * of this software and associated documentation files (the "Software"), to deal + * in the Software without restriction, including without limitation the rights + * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell + * copies of the Software, and to permit persons to whom the Software is + * furnished to do so, subject to the following conditions: + * + * The above copyright notice and this permission notice shall be included in + * all copies or substantial portions of the Software. + * + * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE + * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, + * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN + * THE SOFTWARE. + */ +package coza.opencollab.epub.creator.model; + +import coza.opencollab.epub.creator.util.MediaTypeUtil; +import java.io.IOException; +import java.io.InputStream; +import org.apache.commons.io.IOUtils; + +/** + * Representation of content in the book + * + * @author OpenCollab + */ +public class Content { + + /** + * The MediaType get set as the media-type attribute value in the OPF + * manifest items + */ + private String mediaType; + + /** + * The HREF get set as the HREF attribute value in the OPF manifest items + */ + private String href; + + /** + * The id get set as the id attribute value in the OPF manifest items and + * the id ref in the spine. This must be unique + */ + private String id; + + /** + * The properties get set as the properties attribute value in the OPF + * manifest items. This is used for the TOC and cover-image content objects + */ + private String properties; + + /** + * The file content + */ + private byte[] content; + + /** + * Specifies if it is a linear item in the spine + */ + private boolean linear = true; + + /** + * Specifies if it must be added to the spine + */ + private boolean spine = true; + + /** + * Specifies if it must be added to the TOC (Navigation Document) + */ + private boolean toc = false; + + /** + * The fallback content + */ + private Content fallBack; + + /** + * Creates new instance of Content + * + * @param mediaType the mime type + * @param href the link to the content item + * @param content the file byte array + */ + public Content(String mediaType, String href, byte[] content) { + if (mediaType == null) { + this.mediaType = MediaTypeUtil.getMediaTypeFromFilename(href); + } else { + this.mediaType = mediaType; + } + this.href = href; + this.content = content; + } + + /** + * Creates new instance of Content + * + * @param href the link to the content item + * @param content the file byte array + */ + public Content(String href, byte[] content) { + this(MediaTypeUtil.getMediaTypeFromFilename(href), href, content); + } + + /** + * Creates a new instance of Content + * + * @param mediaType the mime type + * @param href the link to the content item + * @param id used as the id attribute value in the OPF manifest items and + * the id ref in the spine + * @param properties the properties attribute value in the OPF + * @param content the file byte array + */ + public Content(String mediaType, String href, String id, String properties, byte[] content) { + this(mediaType, href, content); + this.id = id; + this.properties = properties; + this.content = content; + } + + /** + * Creates a new instance of Content + * + * @param href the link to the content item + * @param id used as the id attribute value in the OPF manifest items and + * the id ref in the spine + * @param properties the properties attribute value in the OPF + * @param content the file byte array + */ + public Content(String href, String id, String properties, byte[] content) { + this(MediaTypeUtil.getMediaTypeFromFilename(href), href, id, properties, content); + } + + /** + * Creates new instance of Content + * + * @param mediaType the mime type + * @param href the link to the content item + * @param content the file byte array + * @throws java.io.IOException if content could not be converted to byte + * array + */ + public Content(String mediaType, String href, InputStream content) throws IOException { + this(mediaType, href, IOUtils.toByteArray(content)); + } + + /** + * Creates new instance of Content + * + * @param href the link to the content item + * @param content the file byte array + * @throws java.io.IOException if content could not be converted to byte + * array + */ + public Content(String href, InputStream content) throws IOException { + this(MediaTypeUtil.getMediaTypeFromFilename(href), href, IOUtils.toByteArray(content)); + } + + /** + * Creates a new instance of Content + * + * @param mediaType the mime type + * @param href the link to the content item + * @param id used as the id attribute value in the OPF manifest items and + * the id ref in the spine + * @param properties the properties attribute value in the OPF + * @param content the file byte array + * @throws java.io.IOException if content could not be converted to byte + * array + */ + public Content(String mediaType, String href, String id, String properties, InputStream content) throws IOException { + this(mediaType, href, id, properties, IOUtils.toByteArray(content)); + } + + /** + * Creates a new instance of Content + * + * @param href the link to the content item + * @param id used as the id attribute value in the OPF manifest items and + * the id ref in the spine + * @param properties the properties attribute value in the OPF + * @param content the file byte array + * @throws java.io.IOException if content could not be converted to byte + * array + */ + public Content(String href, String id, String properties, InputStream content) throws IOException { + this(MediaTypeUtil.getMediaTypeFromFilename(href), href, id, properties, IOUtils.toByteArray(content)); + } + + /** + * Indicates whether a fallback content has been set + * + * @return the fallback flag + */ + public boolean hasFallBack() { + return fallBack != null; + } + + /** + * @return the mediaType + */ + public String getMediaType() { + return mediaType; + } + + /** + * @param mediaType the mediaType to set + */ + public void setMediaType(String mediaType) { + this.mediaType = mediaType; + } + + /** + * @return the HREF + */ + public String getHref() { + return href; + } + + /** + * @param href the HREF to set + */ + public void setHref(String href) { + this.href = href; + } + + /** + * @return the id + */ + public String getId() { + return id; + } + + /** + * @param id the id to set + */ + public void setId(String id) { + this.id = id; + } + + /** + * @return the properties + */ + public String getProperties() { + return properties; + } + + /** + * @param properties the properties to set + */ + public void setProperties(String properties) { + this.properties = properties; + } + + /** + * @return the content + */ + public byte[] getContent() { + return content; + } + + /** + * @param content the content to set + */ + public void setContent(byte[] content) { + this.content = content; + } + + /** + * @return the linear + */ + public boolean isLinear() { + return linear; + } + + /** + * @param linear the linear to set + */ + public void setLinear(boolean linear) { + this.linear = linear; + } + + /** + * @return the spine + */ + public boolean isSpine() { + return spine; + } + + /** + * @param spine the spine to set + */ + public void setSpine(boolean spine) { + this.spine = spine; + } + + /** + * @return the TOC + */ + public boolean isToc() { + return toc; + } + + /** + * @param toc the TOC to set + */ + public void setToc(boolean toc) { + this.toc = toc; + } + + /** + * @return the fallBack + */ + public Content getFallBack() { + return fallBack; + } + + /** + * The spine parameter will be set to false as we do not want to add the + * fallback content to the spine. To override default behavior call + * getFallBack to set spine property. + * + * @param fallBack the fallBack to set + */ + public void setFallBack(Content fallBack) { + fallBack.setSpine(false); + this.fallBack = fallBack; + } + +} diff --git a/src/main/java/coza/opencollab/epub/creator/model/EpubBook.java b/src/main/java/coza/opencollab/epub/creator/model/EpubBook.java new file mode 100644 index 0000000..0a06d8b --- /dev/null +++ b/src/main/java/coza/opencollab/epub/creator/model/EpubBook.java @@ -0,0 +1,429 @@ +/* Copyright 2014 OpenCollab. + * + * Permission is hereby granted, free of charge, to any person obtaining a copy + * of this software and associated documentation files (the "Software"), to deal + * in the Software without restriction, including without limitation the rights + * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell + * copies of the Software, and to permit persons to whom the Software is + * furnished to do so, subject to the following conditions: + * + * The above copyright notice and this permission notice shall be included in + * all copies or substantial portions of the Software. + * + * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE + * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, + * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN + * THE SOFTWARE. + */ +package coza.opencollab.epub.creator.model; + +import coza.opencollab.epub.creator.EpubConstants; +import coza.opencollab.epub.creator.util.EpubWriter; +import java.io.IOException; +import java.io.InputStream; +import java.io.OutputStream; +import java.text.MessageFormat; +import java.util.ArrayList; +import java.util.HashSet; +import java.util.List; +import java.util.Set; + +/** + * Representation of an EPUB book + * + * @author OpenCollab + */ +public class EpubBook { + + /** + * A list of the the content files, this includes the cover, HTML pages, CSS + * JavaScript or any other resource + */ + private List contents; + /** + * Indicates whether the TOC must be created automatically. If this is false + * the tocLinks must be set + */ + private boolean autoToc = true; + /** + * The 2 letter language code set in the dc:language meta data + */ + private String language; + /** + * The id used as the meta data dc:identifier + */ + private String id; + /** + * The title of the book + */ + private String title; + /** + * The author, this is set as the meta data dc:creator value + */ + private String author; + /** + * Unique content id that is incremental set on content with no id + */ + private int contentId = 1; + /** + * List of the links that must be added to the TOC, they can be nested + */ + private List tocLinks; + /** + * List of the landmarks to be added to the TOC + */ + private List landmarks; + /** + * Instance of the EpubWriter to write the book to file or stream + */ + private final EpubWriter epubCreator; + + /** + * Unique set of href's used to make sure we do not add duplicates + */ + private final Set uniqueHrefs; + + /** + * The href can not be repeated in the OPF, thus is we want to add the same + * content in more than one place we have to create duplicate Content + * objects but with different href's + */ + private int hrefUniquePostfix = 1; + + /** + * Constructs EPUBBook + */ + public EpubBook() { + this.epubCreator = new EpubWriter(); + this.contents = new ArrayList<>(); + this.tocLinks = new ArrayList<>(); + this.uniqueHrefs = new HashSet(); + } + + /** + * Constructs EPUBBook + * + * @param language the 2 letter language code set in the dc:language meta + * data + * @param id the id used as the meta data dc:identifier + * @param title the title of the book + * @param author the author, this is set as the meta data dc:creator value + */ + public EpubBook(String language, String id, String title, String author) { + this(); + this.language = language; + this.id = id; + this.title = title; + this.author = author; + } + + /** + * Checks if href unique, adds postfix if not + * + * @param content + */ + private void checkHref(Content content) { + content.setHref(removeLeadingFileSeparator(content.getHref())); + if (uniqueHrefs.contains(content.getHref())) { + content.setHref(incrementHref(content.getHref())); + } + uniqueHrefs.add(content.getHref()); + } + + /** + * Checks if href unique, adds postfix if not + * + * @param href + */ + private String checkHref(String href) { + href = removeLeadingFileSeparator(href); + if (uniqueHrefs.contains(href)) { + return incrementHref(href); + } + return href; + } + + /** + * Increment href. Checks for file extensions + * + * @param href + * @return + */ + private String incrementHref(String href) { + if (href.contains(".")) { + return href.replace(".", "_" + hrefUniquePostfix++ + "."); + } + return href + "_" + hrefUniquePostfix++; + } + + /** + * Remove the leading file separator + * + * @param href + * @return + */ + private String removeLeadingFileSeparator(String href) { + if (href.startsWith("/") || href.startsWith("\\")) { + return href.substring(1); + } + return href; + } + + /** + * Adds content to the content list and checks the id. Only adds unique + * href's + * + * @param content the EpubBook content - TOC, pages, files + * @return boolean indicating if the content has been added + */ + public boolean addContent(Content content) { + checkContentId(content); + checkHref(content); + contents.add(content); + return true; + } + + /** + * Inserts content at a specific index. Only adds unique href's + * + * @param content the EpubBook content - TOC, pages, files + * @param index index where the content will be inserted + * @return boolean indicating if the content has been added + */ + public boolean insertContent(Content content, int index) { + checkContentId(content); + checkHref(content); + contents.add(index, content); + return true; + } + + /** + * Wraps a String in the HTML wrapper and adds create a content object that + * is added to the content list. Returns null if the href is not unique + * + * @param title the title of the page + * @param href used as unique link + * @param content text content to be added + * @return the Content object generated from the text + */ + public Content addTextContent(String title, String href, String content) { + href = checkHref(href); + String contentString = MessageFormat.format(EpubConstants.HTML_WRAPPER, title, content); + Content textContent = new Content("application/xhtml+xml", href, contentString.getBytes()); + addContent(textContent); + return textContent; + } + + /** + * Creates and adds file Content to the book + * + * @param contents the byte array content + * @param mediaType the mime type + * @param href used as unique link + * @param toc flag whether it must be added to the TOC + * @param spine flag whether it must be added to the spine + * @return a reference to the newly created Content object + */ + public Content addContent(byte[] contents, String mediaType, String href, boolean toc, boolean spine) { + Content content = new Content(mediaType, href, contents); + content.setToc(toc); + content.setSpine(spine); + addContent(content); + return content; + } + + /** + * Creates and adds an InputStream to the book + * + * @param contents the InputStream to the content + * @param mediaType the mime type + * @param href used as unique link + * @param toc flag whether it must be added to the TOC + * @param spine flag whether it must be added to the spine + * @return a reference to the newly created Content object + * @throws java.io.IOException if the InputStream can not be converted to + * byte[] + */ + public Content addContent(InputStream contents, String mediaType, String href, boolean toc, boolean spine) throws IOException { + Content content = new Content(mediaType, href, contents); + content.setToc(toc); + content.setSpine(spine); + addContent(content); + return content; + } + + /** + * Checks if Content object has an id and adds an unique if not + * + * @param content + */ + private void checkContentId(Content content) { + if (content.getId() == null) { + content.setId(id.replaceAll("[^a-zA-Z0-9\\-]", "_") + "_" + (contentId++)); + } + } + + /** + * Adds an file as the cover image + * + * @param coverImage the cover image + * @param mediaType the mime type of the cover image + * @param href used to name the cover image + */ + public void addCoverImage(byte[] coverImage, String mediaType, String href) { + Content cover = new Content(mediaType, href, coverImage); + cover.setProperties("cover-image"); + cover.setSpine(false); + addContent(cover); + } + + /** + * Creates the EPUB zip container and writes it to the OutputStream + * + * @param out the OutputStream + * @throws Exception if the content can not be zipped and written + */ + public void writeToStream(OutputStream out) throws Exception { + epubCreator.writeEpubToStream(this, out); + } + + /** + * Creates the EPUB zip container and writes it to the File + * + * @param fileName to store as + * @throws Exception if the content can not be zipped and stored + */ + public void writeToFile(String fileName) throws Exception { + epubCreator.writeEpubToFile(this, fileName); + } + + /** + * @return the contents + */ + public List getContents() { + return contents; + } + + /** + * @param contents the content to set + */ + public void setContents(List contents) { + this.contents = contents; + } + + /** + * @return the autoToc + */ + public boolean isAutoToc() { + return autoToc; + } + + /** + * @param autoToc the autoToc to set + */ + public void setAutoToc(boolean autoToc) { + this.autoToc = autoToc; + } + + /** + * @return the language + */ + public String getLanguage() { + return language; + } + + /** + * @param language the language to set + */ + public void setLanguage(String language) { + this.language = language; + } + + /** + * @return the id + */ + public String getId() { + return id; + } + + /** + * @param id the id to set + */ + public void setId(String id) { + this.id = id; + } + + /** + * @return the title + */ + public String getTitle() { + return title; + } + + /** + * @param title the title to set + */ + public void setTitle(String title) { + this.title = title; + } + + /** + * @return the tocLinks + */ + public List getTocLinks() { + return tocLinks; + } + + /** + * @param tocLinks the tocLinks to set + */ + public void setTocLinks(List tocLinks) { + this.tocLinks = tocLinks; + } + + /** + * @return the landmarks + */ + public List getLandmarks() { + return landmarks; + } + + /** + * @param landmarks the landmarks to set + */ + public void setLandmarks(List landmarks) { + this.landmarks = landmarks; + } + + /** + * @return the author + */ + public String getAuthor() { + return author; + } + + /** + * @param author the author to set + */ + public void setAuthor(String author) { + this.author = author; + } + + /** + * @return the epubCreator + */ + public EpubWriter getEpubCreator() { + return epubCreator; + } + + /** + * @return the uniqueHrefs + */ + public Set getUniqueHrefs() { + return uniqueHrefs; + } + +} diff --git a/src/main/java/coza/opencollab/epub/creator/model/Landmark.java b/src/main/java/coza/opencollab/epub/creator/model/Landmark.java new file mode 100644 index 0000000..e6e495a --- /dev/null +++ b/src/main/java/coza/opencollab/epub/creator/model/Landmark.java @@ -0,0 +1,86 @@ +/* Copyright 2014 OpenCollab. + * + * Permission is hereby granted, free of charge, to any person obtaining a copy + * of this software and associated documentation files (the "Software"), to deal + * in the Software without restriction, including without limitation the rights + * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell + * copies of the Software, and to permit persons to whom the Software is + * furnished to do so, subject to the following conditions: + * + * The above copyright notice and this permission notice shall be included in + * all copies or substantial portions of the Software. + * + * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE + * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, + * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN + * THE SOFTWARE. + */ +package coza.opencollab.epub.creator.model; + +/** + * Represents a landmark object in the Navigation document landmarks section + * + * @author OpenCollab + */ +public class Landmark { + + /** + * The href of the referenced landmark + */ + private String href; + /** + * The title to display + */ + private String title; + /** + * The type (cover,title-page,frontmatter,bodymatter,backmatter,toc, loi,lot + * (list of tables),preface,bibliography,index,glossary,acknowledgments + */ + private String type; + + /** + * @return the href + */ + public String getHref() { + return href; + } + + /** + * @param href the href to set + */ + public void setHref(String href) { + this.href = href; + } + + /** + * @return the title + */ + public String getTitle() { + return title; + } + + /** + * @param title the title to set + */ + public void setTitle(String title) { + this.title = title; + } + + /** + * @return the type + */ + public String getType() { + return type; + } + + /** + * @param type the type to set + */ + public void setType(String type) { + this.type = type; + } + +} diff --git a/src/main/java/coza/opencollab/epub/creator/model/TocLink.java b/src/main/java/coza/opencollab/epub/creator/model/TocLink.java new file mode 100644 index 0000000..46c62c6 --- /dev/null +++ b/src/main/java/coza/opencollab/epub/creator/model/TocLink.java @@ -0,0 +1,116 @@ +/* Copyright 2014 OpenCollab. + * + * Permission is hereby granted, free of charge, to any person obtaining a copy + * of this software and associated documentation files (the "Software"), to deal + * in the Software without restriction, including without limitation the rights + * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell + * copies of the Software, and to permit persons to whom the Software is + * furnished to do so, subject to the following conditions: + * + * The above copyright notice and this permission notice shall be included in + * all copies or substantial portions of the Software. + * + * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE + * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, + * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN + * THE SOFTWARE. + */ +package coza.opencollab.epub.creator.model; + +import java.util.List; + +/** + * Represents a link in the table of contents, this object can have nested child + * links + * + * @author OpenCollab + */ +public class TocLink { + + /** + * The href + */ + private String href; + + /** + * The displayed text + */ + private String title; + + /** + * Can be set for accessibility if the pronunciation of a link heading may + * be ambiguous due to embedded images, math content, or other content + * without intrinsic text. Will be included as an 'title' attribute + */ + private String altTitle; + + /** + * Any nested links + */ + private List tocChildLinks; + + public TocLink(String href, String title, String altTitle) { + this.href = href; + this.title = title; + this.altTitle = altTitle; + } + + /** + * @return the href + */ + public String getHref() { + return href; + } + + /** + * @param href the href to set + */ + public void setHref(String href) { + this.href = href; + } + + /** + * @return the title + */ + public String getTitle() { + return title; + } + + /** + * @param title the title to set + */ + public void setTitle(String title) { + this.title = title; + } + + /** + * @return the altTitle + */ + public String getAltTitle() { + return altTitle; + } + + /** + * @param altTitle the altTitle to set + */ + public void setAltTitle(String altTitle) { + this.altTitle = altTitle; + } + + /** + * @return the tocChildLinks + */ + public List getTocChildLinks() { + return tocChildLinks; + } + + /** + * @param tocChildLinks the tocChildLinks to set + */ + public void setTocChildLinks(List tocChildLinks) { + this.tocChildLinks = tocChildLinks; + } +} diff --git a/src/main/java/coza/opencollab/epub/creator/util/EpubWriter.java b/src/main/java/coza/opencollab/epub/creator/util/EpubWriter.java new file mode 100644 index 0000000..2fb25ca --- /dev/null +++ b/src/main/java/coza/opencollab/epub/creator/util/EpubWriter.java @@ -0,0 +1,217 @@ +/* Copyright 2014 OpenCollab. + * + * Permission is hereby granted, free of charge, to any person obtaining a copy + * of this software and associated documentation files (the "Software"), to deal + * in the Software without restriction, including without limitation the rights + * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell + * copies of the Software, and to permit persons to whom the Software is + * furnished to do so, subject to the following conditions: + * + * The above copyright notice and this permission notice shall be included in + * all copies or substantial portions of the Software. + * + * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE + * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, + * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN + * THE SOFTWARE. + */ +package coza.opencollab.epub.creator.util; + +import coza.opencollab.epub.creator.EpubConstants; +import java.io.File; +import java.io.FileOutputStream; +import java.io.IOException; +import java.io.OutputStream; +import java.io.OutputStreamWriter; +import java.io.Writer; +import java.text.MessageFormat; +import java.util.zip.CRC32; +import java.util.zip.ZipEntry; +import java.util.zip.ZipOutputStream; +import coza.opencollab.epub.creator.api.OpfCreator; +import coza.opencollab.epub.creator.api.TocCreator; +import coza.opencollab.epub.creator.impl.OpfCreatorDefault; +import coza.opencollab.epub.creator.impl.TocCreatorDefault; +import coza.opencollab.epub.creator.model.Content; +import coza.opencollab.epub.creator.model.EpubBook; +import java.util.List; + +/** + * The EpubWriter creates the EPUB zip bundle. + * + * @author OpenCollab + */ +public class EpubWriter { + + private String containerXML = EpubConstants.CONTAINER_XML; + + private String contentFolder = EpubConstants.CONTENT_FOLDER; + + private String opfFileName = EpubConstants.OPF_FILE_NAME; + + private OpfCreator opfCreator = new OpfCreatorDefault(); + + private TocCreator tocCreator = new TocCreatorDefault(); + + /** + * Writes the EPUB book zip container and contents to a file + * + * @param book the EpubBook + * @param fileName name of the file to be written + * @throws IOException if file could not be written + */ + public void writeEpubToFile(EpubBook book, String fileName) throws IOException { + try (FileOutputStream file = new FileOutputStream(new File(fileName))) { + writeEpubToStream(book, file); + } + } + + /** + * Writes the EPUB book zip container and contents to an OutputStream + * + * @param book the EpubBook + * @param out the OutputStream to write to + * @throws IOException if file could not be written + */ + public void writeEpubToStream(EpubBook book, OutputStream out) throws IOException { + try (ZipOutputStream resultStream = new ZipOutputStream(out)) { + List contents = book.getContents(); + addMimeType(resultStream); + contents.add(0, getTocCreator().createTocFromBook(book)); + addStringToZip(resultStream, "META-INF/container.xml", MessageFormat.format(containerXML, contentFolder)); + addStringToZip(resultStream, contentFolder + "/" + getOpfFileName(), getOpfCreator().createOpfString(book)); + addContent(resultStream, contents); + } + } + + /** + * Adds the zip/EPUB mime type to the EPUB zip file + * + * @param resultStream + * @throws IOException + */ + private void addMimeType(ZipOutputStream resultStream) throws IOException { + ZipEntry mimetypeZipEntry = new ZipEntry("mimetype"); + mimetypeZipEntry.setMethod(ZipEntry.STORED); + byte[] mimetypeBytes = "application/epub+zip".getBytes("UTF-8"); + mimetypeZipEntry.setSize(mimetypeBytes.length); + mimetypeZipEntry.setCrc(calculateCrc(mimetypeBytes)); + resultStream.putNextEntry(mimetypeZipEntry); + resultStream.write(mimetypeBytes); + } + + /** + * Calculates the CRC32 of data for the zip entry + * + * @param data + * @return + */ + private long calculateCrc(byte[] data) { + CRC32 crc = new CRC32(); + crc.update(data); + return crc.getValue(); + } + + /** + * Adds string content as an zip entry with the specified file name + * + * @param resultStream + * @param fileName + * @param content + * @throws IOException + */ + private void addStringToZip(ZipOutputStream resultStream, String fileName, String content) throws IOException { + resultStream.putNextEntry(new ZipEntry(fileName)); + Writer out = new OutputStreamWriter(resultStream, "UTF-8"); + out.write(content); + out.flush(); + } + + /** + * Adds the content objects zip entries + * + * @param resultStream + * @param contents + * @throws IOException + */ + private void addContent(ZipOutputStream resultStream, List contents) throws IOException { + for (Content content : contents) { + resultStream.putNextEntry(new ZipEntry(contentFolder + "/" + content.getHref())); + resultStream.write(content.getContent()); + } + } + + /** + * @return the CONTAINER_XML + */ + public String getContainerXML() { + return containerXML; + } + + /** + * @param containerXML the CONTAINER_XML to set + */ + public void setContainerXML(String containerXML) { + this.containerXML = containerXML; + } + + /** + * @return the CONTENT_FOLDER + */ + public String getContentFolder() { + return contentFolder; + } + + /** + * @param contentFolder the CONTENT_FOLDER to set + */ + public void setContentFolder(String contentFolder) { + this.contentFolder = contentFolder; + } + + /** + * @return the OPF_FILE_NAME + */ + public String getOpfFileName() { + return opfFileName; + } + + /** + * @param opfFileName the OPF_FILE_NAME to set + */ + public void setOpfFileName(String opfFileName) { + this.opfFileName = opfFileName; + } + + /** + * @return the opfCreator + */ + public OpfCreator getOpfCreator() { + return opfCreator; + } + + /** + * @param opfCreator the opfCreator to set + */ + public void setOpfCreator(OpfCreator opfCreator) { + this.opfCreator = opfCreator; + } + + /** + * @return the tocCreator + */ + public TocCreator getTocCreator() { + return tocCreator; + } + + /** + * @param tocCreator the tocCreator to set + */ + public void setTocCreator(TocCreator tocCreator) { + this.tocCreator = tocCreator; + } + +} diff --git a/src/main/java/coza/opencollab/epub/creator/util/MediaTypeUtil.java b/src/main/java/coza/opencollab/epub/creator/util/MediaTypeUtil.java new file mode 100644 index 0000000..914c8ba --- /dev/null +++ b/src/main/java/coza/opencollab/epub/creator/util/MediaTypeUtil.java @@ -0,0 +1,101 @@ +/* + * The MIT License + * + * Copyright 2014 OpenCollab. + * + * Permission is hereby granted, free of charge, to any person obtaining a copy + * of this software and associated documentation files (the "Software"), to deal + * in the Software without restriction, including without limitation the rights + * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell + * copies of the Software, and to permit persons to whom the Software is + * furnished to do so, subject to the following conditions: + * + * The above copyright notice and this permission notice shall be included in + * all copies or substantial portions of the Software. + * + * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE + * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, + * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN + * THE SOFTWARE. + */ +package coza.opencollab.epub.creator.util; + +import java.io.IOException; +import java.util.Enumeration; +import java.util.HashMap; +import java.util.Map; +import java.util.Properties; +import java.util.logging.Level; +import java.util.logging.Logger; + +/** + * Used to map file extensions to Mime types from a properties file + * + * @author OpenCollab + */ +public class MediaTypeUtil { + + private static Map mediaTypeMap = setMediaFromProperties(); + + /** + * Created a map of media types for specific file extensions, read from the + * epub-mediatypes.properties file + * + * @return a map of all the media types in the properties file + */ + private static Map setMediaFromProperties() { + Properties properties = new Properties(); + try { + properties.load(MediaTypeUtil.class.getClassLoader().getResourceAsStream("epub-mediatypes.properties")); + } catch (IOException ex) { + Logger.getLogger(MediaTypeUtil.class.getName()).log(Level.SEVERE, + "Could not read the 'epub-mediatypes.properties' file to populate the media types. " + + "Please use MediaTypeUtil.setMediaTypeMap(Map aMediaTypeMap) to set the map.", ex); + return new HashMap<>(); + } + + Map mappings = new HashMap<>(); + + Enumeration elements = properties.propertyNames(); + while (elements.hasMoreElements()) { + String keyProps = (String) elements.nextElement(); + String valProps = properties.getProperty(keyProps); + mappings.put(keyProps, valProps); + } + return mappings; + } + + /** + * Returns the correct media type for a specific file extension + * + * @param ext the file extension + * @return the mime type + */ + public static String getMediaTypeFromExt(String ext) { + return mediaTypeMap.get(ext.toLowerCase()); + } + + /** + * Returns the correct media type for a specific file name + * + * @param fileName the full filename + * @return the mime type + */ + public static String getMediaTypeFromFilename(String fileName) { + String ext = fileName.substring(fileName.lastIndexOf(".") + 1); + return getMediaTypeFromExt(ext); + } + + /** + * Allows you to override the media type map + * + * @param aMediaTypeMap the mediaTypeMap to set + */ + public static void setMediaTypeMap(Map aMediaTypeMap) { + mediaTypeMap = aMediaTypeMap; + } + +} diff --git a/src/main/resources/epub-mediatypes.properties b/src/main/resources/epub-mediatypes.properties new file mode 100644 index 0000000..7bc9785 --- /dev/null +++ b/src/main/resources/epub-mediatypes.properties @@ -0,0 +1,51 @@ +# The MIT License +# +# Copyright 2014 OpenCollab. +# +# Permission is hereby granted, free of charge, to any person obtaining a copy +# of this software and associated documentation files (the "Software"), to deal +# in the Software without restriction, including without limitation the rights +# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +# copies of the Software, and to permit persons to whom the Software is +# furnished to do so, subject to the following conditions: +# +# The above copyright notice and this permission notice shall be included in +# all copies or substantial portions of the Software. +# +# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN +# THE SOFTWARE. + +# Mapping of file extensions to the correct media type, this file will be used +# in MediaTypeUtil + +xhtml=application/xhtml+xml +html=application/xhtml+xml +htm=application/xhtml+xml +jpg=image/jpeg +jpeg=image/jpeg +gif=image/gif +png=image/png +svg=image/svg+xml +ncx=application/x-dtbncx+xml +otf=application/vnd.ms-opentype +woff=application/font-woff +smil=application/smil+xml +pls=application/pls+xml +mp3=audio/mpeg +mp4=audio/mp4 +css=text/css +js=text/javascript +epub=application/epub+zip +tff=application/x-truetype-font +ogg=audio/ogg +xpgt=application/adobe-page-template+xml +pdf=application/pdf +docx=application/vnd.openxmlformats-officedocument.wordprocessingml.document +doc=application/msword +xls=application/vnd.ms-excel +xlsx=application/vnd.openxmlformats-officedocument.spreadsheetml.sheet \ No newline at end of file diff --git a/src/test/java/coza/opencollab/epub/creator/EpubCreatorTest.java b/src/test/java/coza/opencollab/epub/creator/EpubCreatorTest.java new file mode 100644 index 0000000..b121530 --- /dev/null +++ b/src/test/java/coza/opencollab/epub/creator/EpubCreatorTest.java @@ -0,0 +1,41 @@ +package coza.opencollab.epub.creator; + +import coza.opencollab.epub.creator.model.EpubBook; +import java.io.File; +import java.io.FileOutputStream; +import junit.framework.Assert; +import org.apache.commons.io.IOUtils; +import org.junit.Test; + +/** + * + * @author OpenCollab + */ +public class EpubCreatorTest { + + @Test + public void testEpubCreate() { + try (FileOutputStream file = new FileOutputStream(new File("test.epub"))) { + EpubBook book = new EpubBook("en", "Samuel .-__Id1", "Samuel Test Book", "Samuel Holtzkampf"); + + book.addContent(this.getClass().getResourceAsStream("/epub30-overview.xhtml"), + "application/xhtml+xml", "xhtml/epub30-overview.xhtml", true, true).setId("Overview"); + book.addContent(this.getClass().getResourceAsStream("/idpflogo_web_125.jpg"), + "image/jpeg", "img/idpflogo_web_125.jpg", false, false); + book.addContent(this.getClass().getResourceAsStream("/epub-spec.css"), + "text/css", "css/epub-spec.css", false, false); + book.addTextContent("TestHtml", "xhtml/samuelTest2.xhtml", "Samuel test one two four!!!!!\nTesting two").setToc(true); + book.addTextContent("TestHtml", "xhtml/samuelTest.xhtml", "Samuel test one two three\nTesting two").setToc(true); + book.addCoverImage(IOUtils.toByteArray(this.getClass().getResourceAsStream("/P1010832.jpg")), + "image/jpeg", "images/P1010832.jpg"); + + + book.writeToStream(file); + // TODO : real tests to see if document correct, this is just to test that creation is succesfull + Assert.assertEquals("test", "test"); + } catch (Exception ex) { + System.out.println(ex); + Assert.assertEquals("test", "test1"); + } + } +} diff --git a/src/test/resources/P1010832.jpg b/src/test/resources/P1010832.jpg new file mode 100644 index 0000000..e2e26ef Binary files /dev/null and b/src/test/resources/P1010832.jpg differ diff --git a/src/test/resources/epub-spec.css b/src/test/resources/epub-spec.css new file mode 100644 index 0000000..15af5a9 --- /dev/null +++ b/src/test/resources/epub-spec.css @@ -0,0 +1,581 @@ +@charset "utf-8"; + +body { + margin-top: 2em; + margin-left: 6em; + margin-right: 15em; + margin-bottom: 2em; + font-family: arial, helvetica, sans-serif; + color: black; + background: white; +} + +/***************************************************************************/ +/* dl **************************************************************/ +/***************************************************************************/ + +dl dt { + font-weight: bold; +} + +dt span.term { + color: #005A9C; + font-weight: normal; +} + +dd > dl { + margin-top: 1px; + padding-top: 0px; + margin-bottom: 1px; + padding-bottom: 0px; +} + +/***************************************************************************/ +/* ul **************************************************************/ +/***************************************************************************/ + +ul.conformance-list li { + list-style-type: none; +} + +/***************************************************************************/ +/* glosslist *********************************************************/ +/***************************************************************************/ + +*.glosslist dl { + margin-left: 2em +} +*.glosslist dl dt { + color: #005A9C +} + +*.glossentry { + font-size: .9em; +} + +/***************************************************************************/ +/* misc block ********************************************************/ +/***************************************************************************/ + +p.informative, p.normative { + font-weight: bold; + font-size: 100%; + color: #8B0000; + padding: 5px 0px 10px; +} + +.biblioentry:target { + border: 1px dashed rgb(200,200,225); +} + + +/***************************************************************************/ +/* misc inline *******************************************************/ +/***************************************************************************/ + +code, span.property, a.codelink { + color: #660099; + font-family: monospace; + font-weight: bold +} +*.RFC2119 { + font-style: italic; + font-size: 80%; +} + +*.todo, *.TODO { + background-color: yellow +} + +/* vocab */ +*.subproplabel, *.subpropref { + font-style: italic; + font-size: 90%; +} + +/***************************************************************************/ +/* elem-synopsis ****************************************************/ +/***************************************************************************/ + +*.elem-synopsis { + border: 1px solid rgb(200,200,225); + border-top: 1px solid rgb(210,210,245); + border-left: 1px solid rgb(210,210,245); + background: rgb(240,240,255); + padding-left: 1em; + padding-right: 1em; + margin-bottom: 2em; + -moz-box-shadow: 5px 5px 5px #888; + -webkit-box-shadow: 5px 5px 5px #888; +} + +/* special case for the code.option fields in elem-synopsis */ +code.option { + color: black; + font-family: arial, helvetica, sans-serif; + font-weight: normal +} +/* for the special case when an attlist occurs outside of an elem-synopsis*/ +div.section > div.elem-synopsis-attlist { + border: 2px solid rgb(200,200,225); + background: rgb(230,230,255); + padding: 1em +} + + +/***************************************************************************/ +/* toc ***************************************************************/ +/***************************************************************************/ + +div.toc dl dt { + font-weight: normal +} + +*.toc p, div.list-of-examples p { + font: small-caps 105% sans-serif; + color: #005A9C; +} + +*.toc { + margin-top: 3em +} + +nav#toc li { + list-style-type:none; +} + +nav#toc > ol > li > span > a { + color: #0000ff +} +nav#toc > ol > li > ol > li > a { + color: #0033ff +} +nav#toc > ol > li > ol > li > ol > li > a { + font-size: .9em; + color: #0066ff; +} +nav#toc > ol > li > ol > li > ol > li > ol > li > a { + font-size: .9em; + color: #0099ff +} +nav#toc > ol > li > ol > li > ol > li > ol > li > ol > li > a { + font-size: .9em; + color: #0099ff +} +nav#toc > ol > li > ol > li > ol > li > ol > li > ol > li > ol > li > a { + font-size: .9em; + color: #0099ff +} + +nav#toc > ol > li > ol > li > ol > li > ol > li > ol > li > ol > li > ol > li > a { + font-size: .9em; + color: #0099ff +} + +/***************************************************************************/ +/* examples **********************************************************/ +/***************************************************************************/ + +div.informalexample { + margin: 1.5em auto 2em auto; +} + +div.informalexample > p { + margin: 0px 20px; + font-style: italic; + font-size: .8em +} + +div.informalexample > p code { + color: black; +} + +pre { + font-family: "Courier New", Courier, Monospace; + color: #000; + background-color: #eee; + margin: 0; + border: 1px solid #ddd; + padding: 9px; + overflow: auto; + white-space: pre-wrap; + white-space: -moz-pre-wrap !important; + white-space: -pre-wrap; + white-space: -o-pre-wrap; + word-wrap: break-word; + +} + +pre.synopsis, p.syntax { + background-color:rgb(253,253,253); + border: 1px solid rgb(220,220,220); + border-left: 1px solid rgb(230,230,230); + border-top: 1px solid rgb(230,230,230); + margin-bottom: 1em; + -moz-box-shadow: 5px 5px 5px #888; + -webkit-box-shadow: 5px 5px 5px #888; + -box-shadow: 5px 5px 5px #888; +} + +p.syntax { + font-family: courier, fixed, monospace; + padding: 9px; +} + +/***************************************************************************/ +/* note, caution *****************************************************/ +/***************************************************************************/ + +.caution .note { + font-style : italic; + font-size : .9em; +} + +div.note, div.caution { + margin: 2em 1em; + border: solid gray 1px; + background-color: rgb(255,255,224); + padding: .5em +} + + +div.caution { + background-color: rgb(255,235,205) +} + +div.note > *, div.caution > * { + /* margin: .25em 0em; + padding: 0em; */ +} + +div.note > h2, div.note > h3, div.note > h4, div.note > h5, +div.caution > h2, div.caution > h3, div.caution > h4, div.caution > h5 { + font-size: 1em; + font-style: italic; + font-variant: small-caps; + float: left; + padding: .18em .6em .18em .5em; + margin: -1em -0.5em -0.5em auto; + width: auto; + border: solid 1px; + background: white; +} + +/***************************************************************************/ +/* headings ************************************************************/ +/***************************************************************************/ + +h1, h2, h3, h4, h5, h6 { + text-align: left; + color: #005A9C; +} +h1 { + font: 170% sans-serif; + padding-bottom: 1em; +} +h2 { + font: 140% sans-serif; + padding-top: 2em; + border-bottom: 1px solid #005A9C +} +h3 { + font: 120% sans-serif; + padding-top: 1.5em; +} +h4 { + font: bold 110% sans-serif; + padding-top: 1.2em; +} +h5 { + font: italic 105% sans-serif +} +h6 { + font: italic 100% sans-serif +} +p.bridgehead { + font: 110% sans-serif; + padding-top: 0.7em; + color: #005A9C; +} + + +/***************************************************************************/ +/* links *******************************************************************/ +/***************************************************************************/ + +a.glossterm { + color: black; + text-decoration: none; + border-bottom : 1px dotted rgb(210,210,210); +} +a.biblioref { + color: #0000FF; + text-decoration: none; +} +a.glossterm:hover, a.biblioref:hover { + text-decoration: underline; + background-color: white; + color: #0000FF; +} + +/***************************************************************************/ +/* "link here" anchor *****************************************************/ +/***************************************************************************/ + +a.hidden-reveal { + color: #005A9C; +} +a.hidden-reveal:link { + text-decoration: none; + color: #005A9C; +} +a.hidden-reveal:visited { + text-decoration: none; + color: #005A9C; +} +a.hidden-reveal:hover { + text-decoration: underline; + background-color: #005A9C; + color: #FFFFFF; +} +a.hidden-reveal:active { + text-decoration: none; + color: #005A9C; +} + +/***************************************************************************/ +/* frontmatter ********************************************************/ +/***************************************************************************/ + +*.releaseinfo { + font-size: 140%; + color: #005A9C; + margin-right: 0.4em +} +*.pubdate { + font-size: 140%; + color: #005A9C +} +*.legalnotice { + font-size: 90% +} +dl.printhistory { + margin-top: 2em; + margin-bottom: 2em +} +dl.printhistory dt { + font: small-caps 105% sans-serif; + color: #005A9C; + margin-top: 0.4em; + margin-bottom: 0.4em +} +div.authorgroup p.editor { + margin-left: 2em; + font-size: 90% +} + +/***************************************************************************/ +/* table *************************************************************/ +/***************************************************************************/ + +table { + border: 1px solid #005A9C; + border-spacing: 0px; + padding: 1em; + margin-top: 1.5em; + margin-bottom: 2em; + -moz-box-shadow: 2px 2px 2px rgb(240,240,240); + -webkit-box-shadow: 2px 2px 2px rgb(190,190,190); + -box-shadow: 2px 2px 2px rgb(190,190,190); +} +th { + border: 1px solid #005A9C; + font-weight: bold; + padding: 0.5em; + font-weight: bold; + color: #005A9C; + font-size: 90% +} +td { + border: 1px solid #005A9C; + padding: 0.5em; + text-align: left +} +td *, td > * { + text-align: left; +} +table, tbody { + padding: 0; +} + +caption { + text-align: left; + font-size: 90% +} +/* the xsl renders db:simplelist as single-column tables */ +table.simplelist, table.simplelist th, table.simplelist td, table.simplelist tr { + border-style: none; + -moz-box-shadow: none; + -webkit-box-shadow: none; + -box-shadow: none; +} + +/* ensure confomity of width for property tables */ +div.informaltable > table { + border-spacing: 0px; + border: 1px solid rgb(210,210,225); + font-size: 1em; + width: 100% +} + +div.informaltable > table td, div.informaltable > table th { + border: none; +} + +div.informaltable > table td.rdfa-property { + padding: 3px; + text-indent: 15px; + color: rgb(0,90,156); + background-color: rgb(240,240,255); + border-bottom: 1px solid rgb(210,210,225); +} +td.rdfa-property > code { + color: rgb(0,50,116); + font-weight: bold; + font-size: 1.1em +} +div.informaltable > table td.rdfa-property-header { + width: 150px; + text-align: center; + padding: 3px; + border-right: 1px solid rgb(210,210,225); + color: rgb(0,90,156); + background-color: rgb(240,240,255); +} +td.rdfa-property-desc { + padding: 3px +} + +td.rdfa-cardinality > p { + padding: 0em; + margin: 0em +} + +/* the core media types table */ +table#tbl-core-media-types > thead > tr > th, +table#tbl-epubReadingSystem-properties > thead > tr > th, +table#tbl-epubReadingSystem-features > thead > tr > th { + background-color: rgb(240,240,255); + text-align: left; + white-space:nowrap; +} + +table#tbl-core-media-types > tbody > tr > th { + text-align: left; + font-weight: normal; + font-style: italic; + padding: 3px; +} + +table#tbl-core-media-types td, table#tbl-core-media-types th, table#tbl-core-media-types tr { + border-color: #005A9C; + margin: 0em; +} + +table#tbl-core-media-types td code, table#tbl-core-media-types td a { + white-space:nowrap; +} + +table.productionset, table.productionset td { + border : none; + background-color : #EEE; +} + +td[headers="tbl-cmt-appl"] { + font-size: .9em; +} + +/* ns prefix table in contentdocs */ +table#tbl-nspfx { + border:none; + border-spacing: 0px; + margin-left: 1em; +} + +span.italic { + font-style: italic; +} + +span.link-marker { + float: left; +} + +/* display prop examples as block */ + +code.prop-example { + display: block; +} + +/* participant listings */ +ul.personlist { + list-style-type: none; + padding-left: 1em; + margin-bottom: 2em; +} + +*.personlist span.affiliation { + color: rgb(75,75,75); +} + +*.personlist span.wg-role { + font-style: italic; +} + +/* +span.surname { + text-transform: uppercase; +} +*/ + +table.productionset tbody tr { + border: none; +} + +table.productionset tbody tr td { + border: none; + border-bottom: 1px solid #CCC; +} + +table.productionset tbody tr td a { + text-decoration: none; + border-bottom: 1px dotted #0000ff; +} + +table.productionset tbody tr td a:hover { + text-decoration: underline; +} + +table.productionset tbody tr td a:visited, +table.productionset tbody tr td a:active, +table.productionset tbody tr td a:hover { + color: #0000ff; +} + + +p.diff, p.errata { + font-size: 0.9em; + font-style: italic +} + +code { + font-style: normal; +} + +div.informalexample > p code { + font-size: 1.2em; +} + +/* vocab experimental term labels */ +strong.experimental { + color: rgb(255,0,0) +} \ No newline at end of file diff --git a/src/test/resources/epub30-overview.xhtml b/src/test/resources/epub30-overview.xhtml new file mode 100644 index 0000000..b98ce6c --- /dev/null +++ b/src/test/resources/epub30-overview.xhtml @@ -0,0 +1,11 @@ + +EPUB 3 Overview +
+ IDPF Logo +
+

EPUB 3 Overview

Recommended Specification 11 October 2011

This version
http://www.idpf.org/epub/30/spec/epub30-overview-20111011.html
Latest version
http://www.idpf.org/epub/30/spec/epub30-overview.html
Previous version
http://www.idpf.org/epub/30/spec/epub30-overview-20110908.html

A diff of changes from the previous draft is available at this link.

Copyright © 2010, 2011 International Digital Publishing Forum™

All rights reserved. This work is protected under Title 17 of the United States Code. Reproduction and dissemination of this work with changes is prohibited except with the written permission of the International Digital Publishing Forum (IDPF).

EPUB is a registered trademark of the International Digital Publishing Forum.

Editors

Garth Conboy, Google Inc.

Matt Garrish, Invited Expert

Markus Gylling, DAISY Consortium

William McCoy, International Digital Publishing Forum (IDPF)

MURATA Makoto, JEPA EPUB Study Group

Daniel Weck, DAISY Consortium

› 1 Introduction

› 1.1 Overview

The EPUB® specification is a distribution and interchange format standard for digital publications and documents. EPUB defines a means of representing, packaging and encoding structured and semantically enhanced Web content — including HTML5, CSS, SVG, images, and other resources — for distribution in a single-file format.

EPUB 3, the third major release of the standard, consists of a set of four specifications, each defining an important component of an overall EPUB Publication:

  • EPUB Publications 3.0 [Publications30], which defines publication-level semantics and overarching conformance requirements for EPUB Publications.

  • EPUB Content Documents 3.0 [ContentDocs30], which defines profiles of XHTML, SVG and CSS for use in the context of EPUB Publications.

  • EPUB Open Container Format (OCF) 3.0 [OCF3], which defines a file format and processing model for encapsulating a set of related resources into a single-file (ZIP) EPUB Container.

  • EPUB Media Overlays 3.0 [MediaOverlays30], which defines a format and a processing model for synchronization of text and audio.

EPUB has been widely adopted as the format for digital books (eBooks), and these new specifications significantly increase the format's capabilities in order to better support a wider range of publication requirements, including complex layouts, rich media and interactivity, and global typography features. The expectation is that EPUB 3 will be utilized for a broad range of content, including books, magazines and educational, professional and scientific publications.

This document provides a starting point for content authors and software developers wishing to understand these specifications. It consists of non-normative overview material, including a roadmap to the four building-block specification documents that compose EPUB 3.

Another non-normative document, EPUB 3 Changes from EPUB 2.0.1 [EPUB3Changes], describes changes in EPUB 3 from the previous version, but is intended primarily for Authors and EPUB Reading System vendors migrating from EPUB 2.0.1 to EPUB 3 and for those who anticipate supporting both versions.

› 1.2 Roadmap

This section provides an overview of the EPUB 3 specifications by explaining in brief the components of a Publication. Links to additional information within this document and to the specifications are included.

An EPUB Publication, at its most basic level, is a bundled collection of resources that can be reliably and predictably ingested by an EPUB Reading System in order to render its contents to a User. Some of these resources facilitate the discovery and processing of the EPUB Publication, while others make up the content of the source publication. The latter, EPUB Content Documents, are described in Content Documents and are fully defined in [ContentDocs30].

A Publication's resources are typically bundled for distribution as a ZIP-based archive with the file extension .epub. As conformant ZIP archives, Publications can be unzipped by many software programs, simplifying both their production and consumption. The container format is introduced in Container and defined in [OCF3].

The container format not only provides a means of determining that the zipped content represents an EPUB Publication (the mimetype file), but also provides a universally-named directory of informative resources (/META-INF). Key among these is the container.xml file, which directs Reading Systems to the root file of the Publication, the Package Document.

The Package Document is itself a kind of information warehouse for the Publication, storing metadata about the specific work contained in the Publication, providing an exhaustive list of resources and defining a default reading order. The Package Document is introduced in Package Document and defined in [Publications30].

The preceding components of an EPUB Publication are not new to EPUB 3, and will be familiar to anyone who has worked with Publications before, although they have been changed and enhanced in this version. A new core addition to EPUB 3, however, is the Media Overlay Document, which defines a means of synchronizing text and audio playback. The Overlay Document is introduced in Multimedia and defined in [MediaOverlays30].

The following example shows the resources a minimal "Hello World" Publication might contain:

+mimetype
+META-INF/container.xml
+Content/HelloWorld.opf
+Content/HelloWorld.xhtml
+

While conceptually simple, an EPUB Publication is more than just a collection of HTML pages and dependent assets in a ZIP package as represented in this example. The following sections of this document delve into more detail about the primary features and functionality that Publications provide to enhance the reading experience.

› 2 Features

This section covers the major features of EPUB, including important components and topics that apply to the process of authoring EPUB Publications as a whole.

› 2.1 Package Document

Every EPUB Publication includes a single Package Document, which specifies all the Publication's constituent content documents and their required resources, defines a reading order for linear consumption, and associates Publication-level metadata and navigation information.

The Package Document represents a significant improvement on a typical Web site. A Web site, for example, embeds references to its resources within its content, which, while a simple and flexible means of identifying resources, makes it difficult to enumerate all the resources required to render it. In addition, there is no standard way for a Web site to define that a sequence of pages make up a larger publication, which is precisely what EPUB's spine element does (i.e., it provides an external declarative means to explicitly specify navigation through a collection of documents). Finally, the Package Document defines a standard way to represent metadata globally applicable to a collection of pages.

The Package Document and other Publication-level constructs are specified in [Publications30].

› 2.2 Navigation

› 2.2.1 Reading Order

A key concept of EPUB is that a Publication consists of multiple resources that may be completely navigated and consumed by a person or program in some specific order.

Many publications have an obvious reading order, or logical progression through their content. A novel is an example of a highly sequential document — it typically has a beginning, middle and end — but not all publications are so ordered: a cookbook or collection of photographic images might be considered to be more like a database. All documents do, however, have at least one logical ordering of all their top-level content items, whether by date, topic, location or some other criteria (e.g., a cookbook is typically ordered by type of recipe).

Every EPUB Publication defines at least one such logical ordering of all its top-level content (the spine [Publications30]), as well as a declarative table of contents (the EPUB Navigation Document [ContentDocs30]). Publications make these data structures available in a machine-readable way external to the content, simplifying their discovery and use.

EPUB Publications are not limited to the linear ordering of their contents, nor do they preclude linking in arbitrary ways — just like the Web, EPUB Publications are built on hypertext — but the basic consumption and navigation can be reliably accomplished in a way that is not true for a set of HTML pages.

› 2.2.2 Navigation Document

Every EPUB Publication contains a special XHTML Content Document called the EPUB Navigation Document, which uses the HTML5 nav element to define human- and machine-readable navigation information.

The Navigation Document supersedes the NCX document [OPS2], and the inclusion of NCX documents is only recommended for forward compatibility in older Reading Systems. The Navigation Document, while maintaining the baseline accessibility and navigation support and features of the NCX, introduces new functionality and rendering features to enhance navigation for all Users. Prime among these are better support for internationalization (as an XHTML5 document itself, the Navigation Document natively supports ruby annotations) and support for embedded grammars (MathML and SVG can be included within navigation links).

As XHTML Content Documents, Navigation Documents also provide a flexible means of tailoring the navigation display using CSS and the hidden attribute [ContentDocs30] while not impacting access to information for accessible Reading Systems.

The structure and semantics of Navigation Documents are defined in EPUB Navigation Documents [ContentDocs30].

› 2.3 Linking

The new EPUB Canonical Fragment Identifier (epubcfi) Specification [EPUBCFI] defines a standardized method for linking into a Publication.

Required support for this scheme in Reading Systems means that EPUB now has an interoperable linking mechanism, one that can, for example, facilitate the sharing of bookmarks and reading locations across devices.

› 2.4 Metadata

EPUB Publications provide a rich array of options for adding Publication metadata. The Package Document includes a dedicated metadata section [Publications30] for general information about the Publication, allowing titles, authors, identifiers and other information about the Publication to be easily accessed. It also provides the means to attach complete bibliographic records to a Publication using the link element [Publications30].

The Package Document also allows a Unique Identifier to be established for a Publication using the unique-identifier attribute [Publications30]. The required last-modified date in the Package metadata section can be joined with this identifier to define a Package Identifier, which provides a means of distinguishing EPUB Publications that represent different versions of the same Manifestation (see Publication Identifiers [Publications30]). The Package Identifier addresses the issue of how to release a Publication without changing its Unique Identifier while still identifying it as a new version.

XHTML Content Documents also include the means of annotating document markup with rich metadata, making them more semantically meaningful and useful both for processing and accessibility purposes (Semantic Inflection [ContentDocs30]).

› 2.5 Content Documents

Every EPUB Publication contains one or more EPUB Content Documents, as defined in [ContentDocs30]. These are XHTML or SVG documents that describe the readable content of a Publication and reference associated media resources (e.g., images, audio and video clips).

XHTML Content Documents are defined by a profile of HTML5 that requires the use of XML serialization [HTML5] in order to ensure that content can be reliably manipulated and rendered. This profile also adds two additional EPUB-specific language constructs: the epub:type attribute [ContentDocs30] for element-level metadata and the epub:trigger element [ContentDocs30] for declaratively associating controls with multimedia elements.

These additions do not affect the ability of an HTML5 User Agent [HTML5] to render EPUB XHTML Content Documents, but Publications might not render identically in all User Agents depending on their support.

› 2.6 Rendering and CSS

A key concept of EPUB is that content presentation should adapt to the User rather than the User having to adapt to a particular presentation of content. HTML was originally designed to support dynamic rendering of structured content, but over time HTML as supported in Web browsers has become focused on the needs of Web applications, and most popular Web sites now have fixed-format layouts.

EPUB Publications, however, are designed to maximize accessibility for the visually impaired, and Reading Systems typically perform text line layout and pagination on the fly, adapting to the size of the display area, the User's preferred font size, and other environmental factors. This behavior is not guaranteed in EPUB; images, vector graphics, video and other non-reflowable content may be included, and some Reading Systems might not paginate on the fly, or at all. Nevertheless, supporting dynamic adaptive layout and accessibility has been a primary design consideration throughout the evolution of the EPUB standard.

EPUB Content Documents may optionally reference EPUB Style Sheets, allowing Authors to define the desired rendering properties. EPUB 3 defines a profile of CSS based on CSS 2.1 [CSS2.1] for this purpose, together with capabilities defined by various CSS3 Modules and several additional properties specific to EPUB.

CSS3 properties were selected based on their current level of support in Web browsers, but support for them in Reading Systems and User Agents is not guaranteed (EPUB-defined properties may similarly be ignored).

EPUB 3 also supports CSS styles that enable both horizontal and vertical layout and both left-to-right and right-to-left writing, but Reading Systems might not support all of these capabilities. Reading Systems may also support different rendering options than the Author intended. Refer to CSS in the Global Language Support section for more information.

EPUB 3 also supports the ability to include multiple style sheets that allow users, for example, to select between day/night reading modes or to change the rendering direction of the text. Refer to Alternate Style Tags [ContentDocs30] for more information.

› 2.7 Multimedia

EPUB 3 supports audio and video embedded in [content documents] via the new [HTML5] audio and video elements, inheriting all the functionality and features these elements provide. (For information on supported audio formats, please refer to Core Media Types [Publications30]. For recommendations on embedding video, refer to Reading System Conformance [Publications30].)

Another key new multimedia feature in EPUB 3 is the inclusion of Media Overlay Documents [MediaOverlays30]. When pre-recorded narration is available for a Publication, Media Overlays provide the ability to synchronize that audio with the text of a Content Document (see also Aural Renditions and Media Overlays).

› 2.8 Fonts

EPUB 3 supports two closely-related font formats — OpenType [OpenType] and WOFF [WOFF] — to accommodate both traditional publishing workflows and emerging Web-based workflows. Word processing programs used to create Publications are likely to have access only to a collection of installed OpenType fonts, for example, whereas Web-archival EPUB generators will likely only have access to WOFF resources (which cannot be converted to OpenType without undesirable, and potentially unlicensed, stripping of WOFF metadata).

EPUB 3 also supports both obfuscated and regular font resources for both OpenType and WOFF font formats. Support for obfuscated font resources is required to accommodate font licensing restrictions for many commercially-available fonts.

› 2.9 Scripting

EPUB strives to treat content declaratively — as data that can be manipulated, not programs that must be executed — but does support scripting as defined in HTML5 and SVG (refer to Scripted Content Documents [ContentDocs30] for more information).

It is important to note, however, that scripting support is optional for Reading Systems and may be disabled for security reasons.

Authors should also note that scripting in an EPUB Publication can create security considerations that are different from scripting within a Web browser. For example, typical same-origin policies are not applicable to content that has been downloaded to a User's local system. Therefore, it is strongly encouraged that scripting be limited to container constrained contexts, as further described in Scripted Content Documents — Content Conformance [ContentDocs30].

Scripting consequently should be used only when essential to the User experience, since it greatly increases the likelihood that content will not be portable across all Reading Systems and creates barriers to accessibility and content reusability.

› 2.10 Text-to-speech

EPUB 3 provides the following text-to-speech (TTS) facilities for controlling aspects of speech synthesis, such as pronunciation, prosody and voice characteristics:

Pronunciation Lexicons

The inclusion of generic pronunciation lexicons using the W3C PLS format [PLS] enables Authors to provide pronunciation rules that apply to the entire EPUB Publication. Refer to PLS Documents [ContentDocs30] for more information.

Inline SSML Phonemes

The incorporation of SSML phonemes functionality [SSML] directly into a EPUB Content Document [ContentDocs30] enables fine-grained pronunciation control, taking precedence over default pronunciation rules and/or referenced pronunciation lexicons (as provided by the PLS format mentioned above). Refer to SSML Attributes [ContentDocs30] for more information.

CSS Speech Features

The inclusion of a select set of features from the CSS 3 Speech Module [CSS3Speech] (previously known as CSS 2.1 Aural Stylesheets [CSS2.1]) enables Authors to control further speech synthesis characteristics. Refer to CSS 3.0 Speech [ContentDocs30] for more information.

› 2.11 Container

An EPUB Publication is transported and interchanged as a single file (a "portable document") that contains the Package Document, all Content Documents and all other required resources for processing the Publication. The single-file container format for EPUB is based on the widely adopted ZIP format. An XML manifest that specifies the location in the ZIP archive of the Package Document must be found at a well-defined location within the archive.

This approach provides a clear contract between any creator of an EPUB Publication and any system which consumes such Publications, as well as a reliable representation that is independent of network transport or file system specifics.

An EPUB Publication's representation as a container file is specified in [OCF3].

› 3 Global Language Support

› 3.1 Metadata

EPUB 3 supports alternate representations of all text metadata items in the package metadata section to improve global distribution of Publications. The alternate-script property can be combined with the xml:lang attribute to include and identify alternate script renditions of language-specific metadata.

Using this property, a Japanese Publication could, for example, include an alternate Roman-script representation of the author's name and/or one or more representations of the title in Romance languages. Refer to the alternate-script property [Publications30] for more information.

The page-progression-direction attribute also allows the content flow direction to be globally specified for all Content Documents to facilitate rendering (see the page-progression-direction [Publications30]).

› 3.2 Content Documents

XHTML Content Documents leverage the new HTML5 directionality features to improve support for bidirectional content rendering: the bdi element allows an instance of directional text to be isolated from the surrounding content, the bdo element allows directionality to be overridden for its child content and the dir attribute allows the directionality of any element to be explicitly set.

XHTML Content Documents also support ruby annotations for pronunciation support (which makes them supported in Navigation Document links, as well).

SVG Content Documents support the rendering of bidirectional text, but do not include support for ruby.

› 3.3 CSS

EPUB 3's support for new CSS3 modules enables typography for many different languages and cultures. Some specific enhancements include:

  • support for vertical writing, which also provides Reading Systems the ability to allow users to toggle direction;

  • better handling of emphasis, such as the inclusion of bōten;

  • better control over line breaking, so that breaks can occur at the character level for languages that do not use spaces to delimit new words; and

  • better control over hyphenation, to further facilitate line breaking.

› 3.4 Fonts

EPUB 3 does not require that Reading Systems come with any particular set of built-in system fonts. As occurs in Web contexts, Users in a particular locale may have installed fonts that omit characters required for other locales, and Reading Systems may utilize intrinsic fonts or font engines that do not utilize operating system installed fonts. As a result, the text content of a Publication might not natively render as intended on all Reading Systems.

To address this problem, EPUB 3 supports the embedding of fonts to facilitate the rendering of text content, and this practice is recommended in order to ensure content is rendered as intended.

Support for embedded fonts also ensures that Publication-specific characters and glyphs can be embedded for proper display.

› 3.5 Text-to-speech

EPUB 3's support for PLS documents and SSML attributes increases the pronunciation control that Authors have over the rendering of any natural language in text-to-speech-enabled Reading Systems. Refer to Text-to-speech in the Features section for more information on these capabilities.

The combination of CSS Speech and inline SSML phonemes also allows fine control over ruby.

› 3.6 Container

The OCF container format supports UTF-8, allowing for internationalized file and directory naming of content resources.

› 4 Accessibility

A major goal of EPUB is to facilitate content accessibility, and a variety of features in EPUB 3 support this requirement. This section reviews these features, detailing some established best practices for ensuring that EPUB Publications are accessible where applicable.

It is important to note that while accessibility is important in its own right, accessible content is also more valuable content: an accessible Publication will be adaptable to more devices and be easier to reuse, in whole or in part, via human and automated workflows. The EPUB Working Group strongly recommends that Authors use EPUB tools that generate accessible content.

› 4.1 Navigation

EPUB 3 improves on NCX documents with the addition of EPUB Navigation Documents. As noted in Content Documents above, the new features these provide represent a more universal and flexible navigation system.

The need to navigate a document is not exclusively an accessibility issue, but a complete Navigation Document is key for all Users to be able to easily and fully access the contents of a document. The primary toc nav element (as defined in The toc nav Element [ContentDocs30]) should fully reflect the structure of the Publication, as a result.

For highly structured documents where it might not be desirable to display the complete table of contents to Users, the display level can be modified using the [HTML5] hidden attribute without minimizing the information that is available for accessible Reading Systems.

Authors are also encouraged to supply additional nav elements if their Publications contain non-structural points of interest, such as figures, tables, etc. in order to further enhance access to the content.

› 4.2 Semantic Markup

HTML5 supports a number of new elements intended to make markup more semantically meaningful (e.g., section, nav, aside) and introduces more clearly defined semantics for some HTML4 elements. These elements, in conjunction with best practices for authoring well-structured Web content, should be utilized when creating EPUB XHTML Content Documents. These additions allow content to be better grouped and defined, both for representing the structure of documents and to facilitate their logical navigation. XHTML Content Documents also natively support the inclusion of ARIA role and state attributes and events, enhancing the ability of Assistive Technologies to interact with the content.

EPUB 3 further introduces the epub:type [ContentDocs30] attribute, which is meant to be functionally equivalent to the W3C Role Attribute [Role]. This attribute allows any element in an XHTML Content Document to include additional information about its purpose and meaning within the work, using controlled vocabularies and terms. Refer to Semantic Inflection [ContentDocs30] for more information.

› 4.3 Dynamic Layouts

The design center of EPUB is dynamic layout: content is typically intended to be formatted on the fly rather than being typeset in a paginated manner in advance (i.e., expecting a particular sized "page"). This core capability is useful, for example, for optimizing rendering onto different sized device screens or window sizes, and it facilitates and simplifies content accessibility.

While it is possible to incorporate more highly formatted content in EPUB — for example via bitmap images or SVG graphics, or even use of CSS explicit positioning and/or table elements to achieve particular visual layouts — Authors are strongly discouraged from utilizing such techniques. They are not reliable in EPUB since many Reading Systems render content in a paginated manner rather than creating a single scrolling Viewport and since each Reading System may define its own pagination algorithm. If these techniques are required to convey the content of the publication (for example, for graphic novels), fallbacks [Publications30] should always be included.

In general, it is preferable to achieve visual richness by using EPUB Style Sheets without absolute sizing or positioning.

› 4.4 Aural Renditions and Media Overlays

Aural renditions of content are important for accessibility and are a desirable feature for many other Users. A baseline to facilitate aural rendering is to utilize semantic HTML designed for dynamic layout. Refer to Text-to-speech for more information on how to use the native facilities that EPUB XHTML Documents include.

Media Overlays provide the ability to synchronize the text and audio content of a Publication, a feature already familiar to readers of DAISY Digital Talking Books. Overlays transcend the accessibility domain in their usefulness: the synchronization of text and audio as a tool for learning to read, for example, being of benefit in many circumstances.

› 4.5 Fallbacks

Not all formats are accessible in their native format, and not all Users prefer to read in the default format provided. EPUB defines a variety of means for providing fallbacks so that alternate renditions of a Publication can be made available in these cases.

Publication and content-level fallbacks are defined in Restrictions and Fallbacks [Publications30]. These allow for the alternate rendition of specific resources within a Publication, such as SVG images or video clips.

In addition, multiple instances of a complete work can be delivered in a single Publication by defining multiple rootfile elements in the OCF container file (as described in Container – META-INF/container.xml [OCF3]). This kind of fallback may be used, for example, so that a formatted graphic novel defined via a sequence of SVG pages can be accompanied by an accessible text version defined via XHTML.

› 4.6 Scripting

EPUB 3 adopts a progressive enhancement approach for scripted content, whereby scripting must not interfere with the integrity of the document (i.e., must not result in information loss when scripting is not available). Consequently, although documents that do employ scripting may provide fallbacks [ContentDocs30] to further facilitate access to their contents, the documents must be accessible without them.

Several mechanisms in EPUB can further minimize and constrain scripting within Publications to improve accessibility:

  • The declarative trigger element [ContentDocs30] added to the EPUB HTML5 profile enables image or textual elements to act as controls for audio and video playback (for example, to start, stop and pause playback). This element eliminates the common use of scripting to include similar functionality.

  • The mediaType element [Publications30] provides a means of encapsulating script-based support for rendering custom XML vocabularies or other custom content types, as well as future-proofs Publications in case such content types are natively supported in future Reading Systems.

  • The semantic inflection capability provided by the type attribute [ContentDocs30] enables Authors to provide hints to Reading Systems about content properties. One use case is to define elements such as images and video as having a zoomable property value, in which case a Reading System may provide a means for Users to access an expanded view that is out-of-line with the normal layout. Such rollover effects are typically implemented via scripting in Web contexts, but scripting cannot be readily implemented given the wide variety of layouts that a Reading System may generate.

  • The switch element [ContentDocs30] provides a declaractive means for Authors to tailor the content displayed to Users without having to resort to scripted solutions.

Best practices for accessible scripting in Web documents, such as provided in [WAI-ARIA], should always be consulted, and use of scripting should be reserved for situations in which interactivity is critical to the User experience.

diff --git a/src/test/resources/epub30-publications.xhtml b/src/test/resources/epub30-publications.xhtml new file mode 100644 index 0000000..24af9b2 --- /dev/null +++ b/src/test/resources/epub30-publications.xhtml @@ -0,0 +1,333 @@ + +EPUB Publications 3.0 +
+ IDPF Logo +
+

EPUB Publications 3.0

Recommended Specification 11 October 2011

This version
http://www.idpf.org/epub/30/spec/epub30-publications-20111011.html
Latest version
http://www.idpf.org/epub/30/spec/epub30-publications.html
Previous version
http://www.idpf.org/epub/30/spec/epub30-publications-20110908.html

A diff of changes from the previous draft is available at this link.

Please refer to the errata for this document, which may include some normative corrections.

Copyright © 2010, 2011 International Digital Publishing Forum™

All rights reserved. This work is protected under Title 17 of the United States Code. Reproduction and dissemination of this work with changes is prohibited except with the written permission of the International Digital Publishing Forum (IDPF).

EPUB is a registered trademark of the International Digital Publishing Forum.

Editors

Markus Gylling, DAISY Consortium

William McCoy, International Digital Publishing Forum (IDPF)

Matt Garrish, Invited Expert

› 1 Overview

› 1.1 Purpose and Scope

This section is informative

This specification, EPUB Publications 3.0, defines publication-level semantics and conformance requirements for EPUB® 3, including the format of the Package Document and rules for how this document and other Publication Resources are associated to create a conforming EPUB Publication.

This specification is one of a family of related specifications that compose EPUB 3, the third major revision of an interchange and delivery format for digital publications based on XML and Web Standards. It is meant to be read and understood in concert with the other specifications that make up EPUB 3:

  • The EPUB 3 Overview [EPUB3Overview], which provides an informative overview of EPUB and a roadmap to the rest of the EPUB 3 documents. The Overview should be read first.

  • EPUB Content Documents 3.0 [ContentDocs30], which defines profiles of XHTML, SVG and CSS for use in the context of EPUB Publications.

  • EPUB Open Container Format (OCF) 3.0 [OCF3], which defines a file format and processing model for encapsulating a set of related resources into a single-file (ZIP) EPUB Container.

  • EPUB Media Overlays 3.0 [MediaOverlays30], which defines a format and a processing model for synchronization of text and audio.

This specification supersedes Open Package Format 2.0.1 [OPF2]. Refer to [EPUB3Changes] for information on differences between this specification and its predecessor.

› 1.3 Conformance Statements

The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119].

All sections of this specification are normative except where identified by the informative status label "This section is informative". The application of informative status to sections and appendices applies to all child content and subsections they may contain.

All examples in this specification are informative.

› 2 EPUB Publications

This section defines conformance requirements for EPUB Publications and EPUB Reading Systems at the Publication level. Conformance requirements particular to specific Publication Resources and processing contexts are located in the specifications referenced herein.

› 2.1 Content Conformance

An EPUB Publication must meet all of the following criteria:

All Publication Resources

› All Publication Resources it contains must be represented in the Package Document (as defined in manifest), adhere to the constraints for Core Media Types and Fallback and be located as per Publication Resource Locations.

The Package Document

› It must contain exactly one Package Document, which must conform to the content requirements defined in Package Document — Content Conformance.

Content Documents

› It must contain at least one EPUB Content Document conformant to the content requirements defined in EPUB Content Documents [ContentDocs30].

The EPUB Navigation Document

› It must contain exactly one EPUB Navigation Document conformant to the content requirements defined in EPUB Navigation Documents — Content Conformance [ContentDocs30].

EPUB Style Sheets

› It may contain zero or more EPUB Style Sheets conformant to the content requirements defined in EPUB Style Sheets — Content Conformance [ContentDocs30].

EPUB Pronunciation Lexicons

› It may contain zero or more PLS Documents conformant to the content requirements defined in PLS Documents — Content Conformance [ContentDocs30].

Media Overlay Documents

› It may contain zero or more Media Overlay Documents conformant to the content requirements defined in [MediaOverlays30].

Additional Publication Resources

› It may contain zero or more Publication Resources in addition to those listed above, each of which must adhere to the requirements in All Publication Resources.

Container

› It must be packaged in a EPUB Container as defined in [OCF3].

› 2.2 Reading System Conformance

An EPUB Reading System must meet all of the following criteria:

EPUB 3 Processing

› It must process the EPUB Container as defined in [OCF3].

› It must process the Package Document as defined in Package Document — Reading System Conformance, and honor all presentation logic expressed through the Package Document (e.g., the reading order, fallback chains and bindings).

› It must not fail catastrophically if it encounters two distinct EPUB Publications with the same Unique Identifier.

› Unless specified as conditional behavior in this section, it must support all Core Media Type Resources.

› It may support an arbitrary set of Foreign Resource types, and must process fallbacks for unsupported Foreign Resources as defined in Restrictions and Fallbacks if not.

› It must process XHTML Content Documents as defined in XHTML Content Documents — Reading System Conformance [ContentDocs30].

› It must process SVG Content Documents as defined in SVG Content Documents — Reading System Conformance [ContentDocs30].

› If it has a CSS Viewport, it must support visual rendering of XHTML Content Documents as defined in EPUB Style Sheets — Reading System Conformance [ContentDocs30].

› If it has the capability to render raster images, it must support the raster image Core Media Types.

› If it has the capability to render vector images, it must support the vector image Core Media Types.

› If it has the capability to render pre-recorded audio, it must support the MP3 audio Core Media Type, should support the MP4 audio Core Media Type and should support Media Overlays [MediaOverlays30].

› If it supports Text-to-Speech (TTS) rendering, it should support PLS Documents [ContentDocs30], the CSS3 Speech features of the EPUB CSS Profile [ContentDocs30] and SSML attributes [ContentDocs30] in XHTML Content Documents.

› It must support the EPUB Canonical Fragment Identifiers scheme [EPUBCFI] for linking, and may support additional linking schemes as defined in the EPUB Linking Scheme Registry.

note

It is recommended that Reading Systems support at least one of the [H.264] and [VP8] video codecs, but this is not a conformance requirement; a Reading System may support no video codecs at all. Content creators and Reading System developers should take into consideration factors such as breadth of adoption, video playback quality, and technology usage royalty requirements when making a choice to include or implement video in either (or potentially, both) formats.

Backward Compatibility

› It should process EPUB version 2 Publications as defined in [OPF2], [OPS2] and [OCF2].

› It must attempt to process any Publication whose Package Document version attribute designates a version lower than 3.0 or which omits the version attribute.

Forward Compatibility

› It should attempt to process any Publication whose Package Document version attribute designates a version higher than 3.0 or which omits the version attribute.

XML Processing

› It must be a conformant non-validating processor [XML].

›  It must be a conformant processor as defined in [XMLNS].

› It must support xml-stylesheet processing instructions [ASSOCSS], and may support additional processing instructions.

› It must be a conformant application as defined by [XML Base].

note

A conforming Reading System is not necessarily a single dedicated program or device, but may exist as a distributed system.

› 3 Package Documents

› 3.1 Introduction

This section is informative

The Package Document carries bibliographic and structural metadata about an EPUB Publication, and is thus the primary source of information about how to process and display it.

The Package Document is an XML document consisting of a set of container elements, each dedicated to housing information about a particular aspect of the Publication. These containers effectively centralize metadata for the Publication, detail the individual resources that compose it and provide reading order and other information for rendering the Publication to a User.

The following list summarizes the information a Package Document contains:

  • Publication metadata — mechanisms for including and/or referencing metadata applicable to the entire Publication and particular resources within it.

  • A Publication manifest — identifies (via IRI) and describes (via MIME media type) the set of resources that collectively compose the Publication.

  • A spine — an ordered sequence of ID references to top-level resources in the manifest from which all other resources in the set can be reached or utilized. The spine defines the default reading order of the Publication.

  • Fallback chains — an optional means for Publications to define an ordered list of top-level resources that can be considered content equivalents that a Reading System can choose between for rendering.

  • Bindings — an optional means of associating script-based implementations with custom media types.

› 3.2 Content Conformance

A Package Document must meet all of the following criteria:

Document Properties

›  It must meet the conformance constraints for XML documents defined in XML Conformance.

› It must be valid to the Package Document schema, as defined in Appendix A, Package Document Schema, and conform to all content conformance constraints expressed in Package Document Definition.

File Properties

› The Package Document filename should use the file extension .opf.

Package Documents have the MIME media type application/oebps-package+xml [RFC4839].

› 3.3 Reading System Conformance

An EPUB Reading System must meet all of the following criteria:

Processing

› It must process the Package Document in conformance with all Reading System conformance constraints expressed in Package Document Definition.

› 3.4 Package Document Definition

All elements [XML] defined in this section are in the http://www.idpf.org/2007/opf namespace [XMLNS] unless otherwise specified.

› 3.4.1 The package Element

The package element is the root container of the Package Document and encapsulates Publication metadata and resource information.

Element Name

package

Usage

The package element is the root element of the Package Document.

Attributes
version [required]

Specifies the EPUB specification version to which the Publication conforms.

The attribute must have the value 3.0 to indicate compliance with this version of the specification.

unique-identifier [required]

An IDREF [XML] that identifies the dc:identifier element that provides the package's preferred, or primary, identifier.

Refer to Publication Identifiers for more information.

prefix [optional]

Declaration mechanism for prefixes not reserved by this specification.

Refer to The prefix Attribute for more information.

xml:lang [optional]

Specifies the language used in the contents and attribute values of the carrying element and its descendants, as defined in section 2.12 Language Identification of [XML].

dir [optional]

Specifies the base text direction of the content and attribute values of the carrying element and its descendants.

Inherent directionality specified using [Unicode] takes precedence over this attribute.

Allowed values are ltr (left-to-right) or rtl (right-to-left).

id [optional]

The ID [XML] of this element, which must be unique within the document scope.

Content Model

In this order: metadata [required], manifest [required], spine [required], guide [optional/deprecated], bindings [optional]

› 3.4.2 The metadata Element

The metadata element encapsulates Publication meta information.

Element Name

metadata

Usage

Required first child of package.

Attributes

The metadata element has no attributes defined in this specification.

Content Model

In any order: dc:identifier [1 or more], dc:title [1 or more], dc:language [1 or more], DCMES Optional Elements [0 or more], meta [1 or more], OPF2 meta [0 or more], link [0 or more]

The minimal required metadata that Publications must include consists of three elements from the Dublin Core Metadata Element Set [DCMES] — title, identifier and language — together with the modified property from DCMI Metadata Terms [DCTERMS]. Refer to the example at the end of this section for an instance of a complete minimal metadata set.

Additional optional metadata is expressed using the DCMES optional elements and the meta element.

Examples

The following example represents the minimal set of metadata that all Publications must contain.

<package … unique-identifier="pub-id">
+    …
+    <metadata xmlns:dc="http://purl.org/dc/elements/1.1/">
+        <dc:identifier id="pub-id">urn:uuid:A1B0D67E-2E81-4DF5-9E67-A64CBE366809</dc:identifier>
+        <dc:title>Norwegian Wood</dc:title>
+        <dc:language>en</dc:language>
+        <meta property="dcterms:modified">2011-01-01T12:00:00Z</meta>
+    </metadata>
+    …
+</package>
+

› 3.4.3 The DCMES identifier Element

The [DCMES] identifier element contains a single identifier associated with the EPUB Publication, such as a UUID, DOI, ISBN or ISSN.

Element Name

dc:identifier

Namespace

http://purl.org/dc/elements/1.1/

Usage

Required child of metadata. Repeatable.

Attributes
id [optional]

The ID [XML] of this element, which must be unique within the document scope.

The id attribute is required on the identifier element containing the unique identifier. See below.

Content Model

Text

Every metadata section must include at least one identifier element containing an unambiguous identifier for the Publication. Multiple identifier elements are permitted, but only one can be marked as the Unique Identifier via the package element unique-identifier attribute.

The following example shows the unique identifier element for a Publication.

<package … unique-identifier="pub-id">
+    <metadata xmlns:dc="http://purl.org/dc/elements/1.1/">
+        <dc:identifier id="pub-id">urn:uuid:A1B0D67E-2E81-4DF5-9E67-A64CBE366809</dc:identifier>
+        …
+    </metadata>
+</package>

This specification makes a distinction between the Unique Identifier for an EPUB Publication and the identifier that uniquely identifies a specific version of it (i.e., to be able to differentiate EPUB Publications containing different versions of the same Manifestation). Two copies of an EPUB that are bit-for-bit identical are the same version and must retain the same last modified date. If they are not bit-for-bit identical, they represent different versions, and must have different last modified dates.

To identify a specific version of a packaged Publication, a Package Identifier can be constructed by combining the Unique Identifier with the last modified date of the Publication. Changes between versions may include minor typographic or markup corrections, without affecting the Unique Identifier. Significant revisions to the content that result in a new edition require a change of the Unique Identifier. For more information on the semantics and requirements of the Package Identifier, refer to Package Identifier.

This specification imposes no additional restrictions or requirements on identifiers except that they must be at least one character in length. It is strongly recommended that all identifiers be fully qualified URIs, however.

Reading Systems must trim all leading and trailing whitespace from the element value, as defined by the XML specification [XML], before processing the value.

To determine whether an identifier conforms to an established system or has been granted by an issuing authority, Reading Systems should parse the value of the property. For additional precision (e.g., if the scheme cannot be determined from the value or could lead to an ambiguous result), Authors may attach an identifier-type property to assist in Reading System identification. When included, the identifier-type property should take precedence over value parsing the identifier.

The following example shows how an identifier can be additionally marked as a DOI using the identifier-type property.

<metadata xmlns:dc="http://purl.org/dc/elements/1.1/">
+    <dc:identifier id="pub-id">urn:doi:10.1016/j.iheduc.2008.03.001</dc:identifier>
+    <meta refines="#pub-id" property="identifier-type" scheme="onix:codelist5">06</meta>
+    …
+</metadata>
+

This specification does not require or endorse the use of any specific scheme for identifiers, and imposes no restrictions or requirements on identifier-type identifiers beyond those specified in the property definition.

When an EPUB Publication is derived from another publication, the identifier for that source publication may be included in the Publication metadata, and must be represented using the DCMES source element.

› 3.4.4 The DCMES title Element

The [DCMES] title element represents an instance of a name given to the EPUB Publication.

Element Name

dc:title

Namespace

http://purl.org/dc/elements/1.1/

Usage

Required child of metadata. Repeatable.

Attributes
id [optional]

The ID [XML] of this element, which must be unique within the document scope.

xml:lang [optional]

Specifies the language used in the contents and attribute values of the carrying element and its descendants, as defined in section 2.12 Language Identification of [XML].

dir [optional]

Specifies the base text direction of the content and attribute values of the carrying element and its descendants.

Inherent directionality specified using [Unicode] takes precedence over this attribute.

Allowed values are ltr (left-to-right) or rtl (right-to-left).

Content Model

Text

Every metadata section must include at least one title element containing the title for the Publication. Multiple title elements are permitted, but the title-type property should be attached to indicate the type of title (e.g., the main title of a work, a subtitle, etc.).

The following example shows how to indicate different title types.

<metadata xmlns:dc="http://purl.org/dc/elements/1.1/">
+    …
+    <dc:title id="t1">A Dictionary of Modern English Usage</dc:title>
+    <meta refines="#t1" property="title-type">main</meta>
+    
+    <dc:title id="t2">First Edition</dc:title>
+    <meta refines="#t2" property="title-type">edition</meta>
+    
+    <dc:title id="t3">Fowler's</dc:title>
+    <meta refines="#t3" property="title-type">short</meta>
+    …
+</metadata>
+

When adding the title-type property, Authors should designate only one title element as containing the main title for the Publication. If no means of determining title types is provided, or understood, Reading Systems must treat the first title element in document order as the main title. This specification does not define how additional title elements should be processed in such situations.

The optional display-seq property may also be attached to each title to indicate their primacy for display and other rendering purposes.

The following example shows how to indicate display sequence.

<metadata xmlns:dc="http://purl.org/dc/elements/1.1/">
+    …
+    <dc:title id="t1">The Red and the Black</dc:title>
+    <meta refines="#t1" property="title-type">main</meta>
+    <meta refines="#t1" property="display-seq">1</meta>
+    
+    <dc:title id="t2">A Chronicle of the Nineteenth Century</dc:title>
+    <meta refines="#t2" property="title-type">subtitle</meta>
+    <meta refines="#t2" property="display-seq">2</meta>
+    
+    <dc:title id="t3">A Chronicle of 1830</dc:title>
+    <meta refines="#t3" property="title-type">subtitle</meta>
+    <meta refines="#t3" property="display-seq">3</meta>
+    …
+</metadata>
+

This specification imposes no additional restrictions or requirements on titles except that they must be at least one character in length.

Reading Systems must trim all leading and trailing whitespace from the element value, as defined by the XML specification [XML], before processing the value.

Examples

The following example shows how the title "THE LORD OF THE RINGS, Part One: The Fellowship of the Ring" could be classified. 

<metadata xmlns:dc="http://purl.org/dc/elements/1.1/">
+    <dc:title id="t1">The Fellowship of the Ring</dc:title>
+    <meta refines="#t1" property="title-type">main</meta>
+    
+    <dc:title id="t2">The Lord of the Rings</dc:title>
+    <meta refines="#t2" property="title-type">collection</meta>
+    <meta refines="#t2" property="group-position">1</meta>
+    
+    <dc:title id="t3">THE LORD OF THE RINGS, Part One: The Fellowship of the Ring</dc:title>
+    <meta refines="#t3" property="title-type">extended</meta> 
+    …
+</metadata>
+

The following example shows how the complex title "The Great Cookbooks of the World: Mon premier guide de cuisson, un Mémoire. The New French Cuisine Masters, Volume Two. Special Anniversary Edition" could be classified. 

<metadata xmlns:dc="http://purl.org/dc/elements/1.1/">
+    <dc:title id="t1" xml:lang="fr">Mon premier guide de cuisson, un Mémoire</dc:title>
+    <meta refines="#t1" property="title-type">main</meta>
+    <meta refines="#t1" property="display-seq">2</meta>
+    
+    <dc:title id="t2">The Great Cookbooks of the World</dc:title>
+    <meta refines="#t2" property="title-type">collection</meta>
+    <meta refines="#t2" property="display-seq">1</meta>
+    
+    <dc:title id="t3">The New French Cuisine Masters</dc:title>
+    <meta refines="#t3" property="title-type">collection</meta>
+    <meta refines="#t3" property="group-position">2</meta>
+    <meta refines="#t3" property="display-seq">3</meta>
+    
+    <dc:title id="t4">Special Anniversary Edition</dc:title>
+    <meta refines="#t4" property="title-type">edition</meta>
+    <meta refines="#t4" property="display-seq">4</meta>
+    
+    <dc:title id="t5">The Great Cookbooks of the World: 
+        Mon premier guide de cuisson, un Mémoire. 
+        The New French Cuisine Masters, Volume Two. 
+        Special Anniversary Edition</dc:title>
+    <meta refines="#t5" property="title-type">extended</meta>
+    …
+</metadata>
+

› 3.4.5 The DCMES language Element

The [DCMES] language element specifies the language of the Publication content.

Element Name

dc:language

Namespace

http://purl.org/dc/elements/1.1/

Usage

Required child of metadata.

Attributes
id [optional]

The ID [XML] of this element, which must be unique within the document scope.

Content Model

Text

Every metadata section must include at least one language element with a value conforming to [RFC5646].

The following example shows a Publication is in U.S. English.

<metadata xmlns:dc="http://purl.org/dc/elements/1.1/">
+    …
+    <dc:language>en-US</dc:language>
+    …
+</metadata>
+

Additional language elements may be included for multilingual Publications, but each element's value must conform to [RFC5646].

Reading Systems must trim all leading and trailing whitespace from the element value, as defined by the XML specification [XML], before processing the value.

› 3.4.6 The DCMES Optional Elements

All elements from the [DCMES] element set — except for identifier, language and title, as defined above — are designated as optional. These elements all conform to the following generalized definition:

Element Name

contributor | coverage | creator | date | description | format | publisher | relation | rights | source | subject | type

Namespace

http://purl.org/dc/elements/1.1/

Usage

Optional child of metadata. Repeatable.

Attributes
id [optional]

The ID [XML] of this element, which must be unique within the document scope.

xml:lang* [optional]

Specifies the language used in the contents and attribute values of the carrying element and its descendants, as defined in section 2.12 Language Identification of [XML].

dir* [optional]

Specifies the base text direction of the content and attribute values of the carrying element and its descendants.

Inherent directionality specified using [Unicode] takes precedence over this attribute.

Allowed values are ltr (left-to-right) or rtl (right-to-left).

Content Model

Text

* The xml:lang and dir attributes are permitted only on the following elements: contributor, coverage, creator, description, publisher, relation, rights and subject.

The value of all optional [DCMES] elements must be at least one character in length.

Reading Systems must trim all leading and trailing whitespace from the element value, as defined by the XML specification [XML], before processing the value.

Except as detailed below, this specification does not modify the [DCMES] definitions for these elements.

The DCMES contributor Element

The contributor element is used to represent the name of a person, organization, etc. that played a secondary role in the creation of the content of a Publication.

The use of the contributor element is identical to the use of the creator element in all other respects, as detailed in the next section.

The DCMES creator Element

The creator element represents the name of a person, organization, etc. responsible for the creation of the content of a Publication. The role property can be attached to the element to indicate the function the creator played in the creation of the content.

The following example shows how to represent a creator as an author using a MARC relators term.

<metadata xmlns:dc="http://purl.org/dc/elements/1.1/">
+    …
+    <dc:creator id="creator">Haruki Murakami</dc:creator>
+    <meta refines="#creator" property="role" scheme="marc:relators" id="role">aut</meta>
+    …
+</metadata>
+

The creator element should contain the name of the creator as a Reading System will present it to a User. The file-as property may be attached to include a normalized form of the name, and the alternate-script property can be used to represent a creator's name in another language or script.

The following example shows the different ways a creator's name can be included to facilitate processing and rendering.

<metadata xmlns:dc="http://purl.org/dc/elements/1.1/">
+    …
+    <dc:creator id="creator">Haruki Murakami</dc:creator>
+    <meta refines="#creator" property="role" scheme="marc:relators" id="role">aut</meta>
+    <meta refines="#creator" property="alternate-script" xml:lang="ja">村上 春樹</meta>
+    <meta refines="#creator" property="file-as">Murakami, Haruki</meta>
+    …
+</metadata>
+

If a Publication has more than one creator, each should be included in a separate creator element. The order in which to render the creator names should be specified using the display-seq property.

The following example shows how to indicate the display order for creator elements.

<metadata xmlns:dc="http://purl.org/dc/elements/1.1/">
+    …
+    <dc:creator id="creator01">Lewis Carroll</dc:creator>
+    <meta refines="#creator01" property="role" scheme="marc:relators">aut</meta>
+    <meta refines="#creator01" property="display-seq">1</meta>
+    
+    <dc:creator id="creator02">John Tenniel</dc:creator>
+    <meta refines="#creator02" property="role" scheme="marc:relators">ill</meta>
+    <meta refines="#creator02" property="display-seq">2</meta>
+    …
+</metadata>
+

If no means of establishing the primacy of creators is included, Reading Systems must use the order of creator elements.

Secondary contributors should be represented using DCMES contributor elements.

The DCMES date Element

The date element must only be used to define the publication date of the EPUB Publication. The publication date is not the same as the last modified date (the last time the content was changed), which must be included using the [DCTERMS] modified property.

For compliance with EPUB 2 Reading Systems, the date string should conform to Date and Time Formats.

The following example shows a publication date.

<metadata xmlns:dc="http://purl.org/dc/elements/1.1/">
+    …
+    <dc:date>2000-01-01T00:00:00Z</dc:date>
+    …
+</metadata>
+

Additional dates should be expressed using the specialized date properties available in the [DCTERMS] vocabulary, or similar.

The publication date may be common to all instances of a Publication or may change from instance to instance (if the Publication gets generated on demand, for example).

Only one date element is allowed.

The DCMES source Element

The source element must only be used to specify the identifier of the source publication from which this EPUB Publication is derived.

The following example shows the ISBN identifier for a Publication together with the source ISBN identifier for the print work it was derived from.

<metadata xmlns:dc="http://purl.org/dc/elements/1.1/">
+    …
+    <dc:identifier id="isbn-id">urn:isbn:9780101010101</dc:identifier>
+    <meta refines="#isbn-id" property="identifier-type" scheme="onix:codelist5">15</meta>
+    
+    <dc:source id="src-id">urn:isbn:9780375704024</dc:source>
+    <meta refines="#src-id" property="identifier-type" scheme="onix:codelist5">15</meta>
+    …
+</metadata>
+

The source element allows the print source of the pagination of a Publication to be determined.

Only one source element is allowed.

The DCMES type Element

The type element is used to indicate that the given Publication is of a specialized type (e.g., annotations packaged in EPUB format or a dictionary).

This specification does not define values for this element, however. The development of specialized Publication types, and the assignment of formal identifiers to represent them, will occur independently of this specification.

Only one type element is allowed.

› 3.4.7 The meta Element

The meta element provides a generic means of including package metadata, allowing the expression of primary metadata about the package or content and refinement of that metadata.

Element Name

meta

Usage

As child of the metadata element. Repeatable.

Attributes
property [required]

A property.

Refer to Vocabulary Association Mechanisms for more information.

refines [context dependent]

Identifies the expression or resource augmented by this element. The value of the attribute must be a relative IRI [RFC3987] pointing to the resource or element it describes.

The refines attribute is optional depending on the type of metadata being expressed. When omitted, the meta element defines a primary expression.

id [optional]

The ID [XML] of this element, which must be unique within the document scope.

scheme [optional]

A property data type value indicating the source the value of the element is drawn from.

Content Model

Text

Each meta element defines a metadata expression, where the property attribute defines the statement being made in the expression and the text content of the element represents the assertion.

This specification defines two types of metadata expressions that can be defined using the meta element:

  • A primary expression is one in which the expression defined in the meta element establishes some aspect of the EPUB Publication. A meta element that omits a refines attribute defines a primary expression.

  • A subexpression is one in which the expression defined in the meta element enhances the meaning of the expression or resource referenced in its refines attribute. A subexpression may refine a media clip, for example, by expressing its duration, or refine a creator or contributor expression by defining the person's role.

    Subexpressions are not limited to refining only primary expressions and resources; they may be used to refine the meaning of other subexpressions, thereby creating chains of information.

note

All of the [DCMES] elements represent primary expressions, and permit refinement by meta element subexpressions.

This specification reserves a set of vocabularies for use in the property attribute, but terms from any vocabulary may be used so long as a prefix is declared for the vocabulary.

The scheme attribute can be used to identify the system or scheme that a meta element's value is drawn from. The value of the scheme attribute is a property data type that resolves to the resource that defines the scheme.

The following example shows how a subexpression can be attached to an creator to indicate it represents an author. The scheme indicates the value is drawn from the MARC relators terms.

<metadata xmlns:dc="http://purl.org/dc/elements/1.1/">
+    …
+    <dc:creator id="creator">Haruki Murakami</dc:creator>
+    <meta refines="#creator" property="role" scheme="marc:relators" id="role">aut</meta>
+    …
+</metadata>
+

If a Reading System does not recognize the scheme attribute value, it should treat the value of the element as a string.

Reading Systems should ignore all meta elements whose property attributes define expressions they do not recognize. A Reading System must not fail when encountering unknown expressions.

In order to ensure that a Package Identifier can be constructed, the metadata element must contain exactly one meta element defining a [DCTERMS] modified property for the Publication. Additional modified properties may be included, but they must have a different subject (i.e., they must include a refines attribute pointing to an element or resource).

Every meta element must express a value that is at least one character in length after whitespace normalization.

Unless an individual property explicitly defines a different whitespace normalization algorithm, Reading Systems must trim all leading and trailing whitespace from the meta element values, as defined by the XML specification [XML], before further processing them.

Examples

The following example represents a more complete set of metadata that typical Publications will contain.

<metadata xmlns:dc="http://purl.org/dc/elements/1.1/">
+    …
+    <dc:identifier id="pub-id">urn:uuid:A1B0D67E-2E81-4DF5-9E67-A64CBE366809</dc:identifier>
+    <meta refines="#pub-id" property="identifier-type" scheme="xsd:string">uuid</meta>
+    
+    <dc:identifier id="isbn-id">urn:isbn:9780101010101</dc:identifier>
+    <meta refines="#isbn-id" property="identifier-type" scheme="onix:codelist5">15</meta>
+    
+    <dc:source id="src-id">urn:isbn:9780375704024</dc:source>
+    <meta refines="#src-id" property="identifier-type" scheme="onix:codelist5">15</meta>
+    
+    <dc:title id="title">Norwegian Wood</dc:title>
+    <meta refines="#title" property="title-type">main</meta>
+    
+    <dc:language>en</dc:language>
+    
+    <dc:creator id="creator">Haruki Murakami</dc:creator>
+    <meta refines="#creator" property="role" scheme="marc:relators" id="role">aut</meta>
+    <meta refines="#creator" property="alternate-script" xml:lang="ja">村上 春樹</meta>
+    <meta refines="#creator" property="file-as">Murakami, Haruki</meta>
+    
+    <meta property="dcterms:modified">2011-01-01T12:00:00Z</meta>
+    
+</metadata>
+

The following example shows an identifier that has been issued by a metadata authority.

<package version="3.0" 
+         unique-identifier="pub-id"
+         xmlns="http://www.idpf.org/2007/opf">
+    <metadata xmlns:dc="http://purl.org/dc/elements/1.1/">
+        <dc:identifier id="pub-id">urn:uuid:1234-5678</dc:identifier>
+        <dc:identifier id="isbn-id">urn:isbn:9780101010101</dc:identifier>
+        
+        <meta refines="#isbn-id" property="meta-auth" id="meta-authority-01">Metadata Authority Inc.</meta>
+        <link refines="#meta-authority-01" rel="xml-signature" href="../META-INF/Signatures.xml#MAI-Signature"/>
+        …
+    </metadata>
+</package>
+
+<!-- in Signatures.xml -->
+<signatures>
+    <Signature Id="MAI-Signature" xmlns="http://www.w3.org/2000/09/xmldsig#">
+        …
+    </Signature>
+</signatures>
+

› 3.4.8 The meta Element (OPF2) [OBSOLETE]

The meta element defined in [OPF2] has been obsoleted and replaced by the new meta element, but may be included as an optional repeatable child of the metadata element for forwards compatibility purposes.

EPUB 3 Reading Systems must ignore this element.

› 3.4.10 The manifest Element

The manifest element provides an exhaustive list of the Publication Resources that constitute the EPUB Publication, each represented by an item element.

Element name

manifest

Usage

Required second child of package, following metadata.

Attributes
id [optional]

The ID [XML] of this element, which must be unique within the document scope.

Content Model

One or more item elements [required]

note

This specification supports internationalized resource naming, so elements and attributes that reference Publication Resources accept IRIs as their value. For compatibility with older Reading Systems that only accept URIs, resource names should be restricted to the ASCII character set.

› 3.4.11 The item Element

The item element represents a Publication Resource.

Element Name

item

Usage

As a child of manifest. Repeatable.

Attributes
id [required]

The ID [XML] of this element, which must be unique within the document scope.

href [required]

An IRI [RFC3987] specifying the location of the Publication Resource described by this item.

media-type [required]

A media type [RFC2046] that specifies the type and format of the Publication Resource described by this item.

fallback [conditionally required]

An IDREF [XML] that identifies the fallback for a non-Core Media Type.

Refer to Manifest Fallbacks for more information.

properties [optional]

A space-separated list of property values.

Refer to Manifest item Properties for a set of properties defined by this specification.

media-overlay [optional]

An IDREF [XML] that identifies the Media Overlay Document for the resource described by this item.

Refer to Packaging [MediaOverlays30] for more information.

Content Model

Empty

Each item element in the manifest identifies a Publication Resource by the IRI provided in its href attribute. The IRI may be absolute or relative. In the case of relative IRIs, Reading Systems must use the IRI of the Package Document as the base when resolving these to absolute IRIs. The resulting absolute IRI must be unique within the manifest scope.

All Publication Resources must be referenced from the manifest, regardless of whether they are included in the EPUB Container or made available remotely. Refer to Publication Resource Locations for media type-specific requirements regarding resource locations.

The Publication Resource identified by an item element must conform to the applicable specification(s) as inferred from the MIME media type provided in the media-type attribute. Core Media Type Resources must use the media type designated in EPUB Core Media Types.

All Foreign Resources must provide a fallback as defined in Restrictions and Fallbacks.

All Publication Resources must declare any applicable descriptive metadata properties as defined in Manifest item Properties via the item element properties attribute. Exactly one item must be declared as the EPUB Navigation Document using the nav property.

Reading Systems must ignore all descriptive metadata properties that they do not recognize.

The manifest is not self-referencing: it must not include an item element that refers to the Package Document itself.

note

The order of item elements in the manifest is not significant. The presentation sequence of content documents is provided in the spine.

Examples

The following example shows a manifest that only contains Core Media Type Resources.

<manifest>
+    <item id="nav" 
+          href="nav.xhtml" 
+          properties="nav"
+          media-type="application/xhtml+xml"/>
+    <item id="intro" 
+          href="intro.xhtml" 
+          media-type="application/xhtml+xml"/>
+    <item id="c1" 
+          href="chap1.xhtml" 
+          media-type="application/xhtml+xml"/>
+    <item id="c1-answerkey" 
+          href="chap1-answerkey.xhtml" 
+          media-type="application/xhtml+xml"/>
+    <item id="c2" 
+          href="chap2.xhtml" 
+          media-type="application/xhtml+xml"/>
+    <item id="c2-answerkey" 
+          href="chap2-answerkey.xhtml" 
+          media-type="application/xhtml+xml"/>
+    <item id="c3" 
+          href="chap3.xhtml" 
+          media-type="application/xhtml+xml"/>
+    <item id="c3-answerkey" 
+          href="chap3-answerkey.xhtml" 
+          media-type="application/xhtml+xml"/>    
+    <item id="notes" 
+          href="notes.xhtml" 
+          media-type="application/xhtml+xml"/>
+    <item id="cover" 
+          href="./images/cover.svg" 
+          properties="cover-image"
+          media-type="image/svg+xml"/>
+    <item id="f1" 
+          href="./images/fig1.jpg" 
+          media-type="image/jpeg"/>
+    <item id="f2" 
+          href="./images/fig2.jpg" 
+          media-type="image/jpeg"/>
+    <item id="css" 
+          href="./style/book.css" 
+          media-type="text/css"/>   
+    <item id="pls" 
+          href="./speech/dict.pls" 
+          media-type="application/pls+xml"/>
+</manifest>
+

The following example shows a manifest that references two Foreign Resources, and therefore uses the fallback chain mechanism to supply content alternatives. The fallback chain terminates with a Core Media Type. 

<manifest>
+    <item id="item1" 
+          href="chap1_docbook.xml" 
+          media-type="application/docbook+xml" 
+          fallback="fall1"/>
+    <item id="fall1" 
+          href="chap1.xml" 
+          media-type="application/z3986-auth+xml" 
+          fallback="fall2" />
+    <item id="fall2" 
+          href="chap1.xhtml" 
+          media-type="application/xhtml+xml"/> 
+    … 
+</manifest>
+

note

Refer also to the Manifest item properties examples for use of the properties attribute.

› 3.4.12 The spine Element

The spine element defines the default reading order of the EPUB Publication content by defining an ordered list of manifest item references.

Element name

spine

Usage

Required third child of package, following manifest.

Attributes
id [optional]

The ID [XML] of this element, which must be unique within the document scope.

toc [optional]

An IDREF [XML] that identifies the manifest item that represents the superseded NCX.

Refer to NCX Superseded for more information.

page-progression-direction [optional]

The global direction in which the Publication content flows.

Allowed values are ltr (left-to-right), rtl (right-to-left) and default.

When the default value is specified, the Author is expressing no preference and the Reading System may chose the rendering direction. This value must be assumed when the attribute is not specified.

Content Model

Multiple itemref elements [required]

The spine represents an ordered subset of the Publication Resources listed in the manifest, with content items not being referenced being ancillary to those that do.

Reading Systems must provide a means of rendering a Publication in the order defined by the spine, which includes: 1) recognizing the first primary (linear='yes') item in the spine as the beginning of the main reading order of the Publication; and, 2) rendering successive primary items in the order given in the spine.

note

Although the page-progression-direction attribute sets the global flow direction for a Publication, individual Content Documents and parts of Content Documents may override this setting (e.g., via the direction and writing-mode CSS properties). Reading Systems may also provide mechanisms to override the default direction (e.g., buttons or settings that allow the application of alternate style sheets).

NCX Superseded

The NCX feature defined in [OPF2] is superseded by the EPUB Navigation Document [ContentDocs30]. EPUB 3 Publications may include an NCX (as defined in OPF 2.0.1) for EPUB 2 Reading System forwards compatibility purposes, but EPUB 3 Reading Systems must ignore the NCX in favor of the EPUB Navigation Document.

note

As the EPUB 2 NCX and the EPUB 3 Navigation Document use different mechanisms for identification in the Package Document (the spine toc attribute and the nav property on the manifest item element, respectively) they can co-exist without conflict in an EPUB 3 Publication.

› 3.4.13 The itemref Element

The child itemref elements of the spine represent a sequential list of Publication Resources (typically EPUB Content Documents). The order of the itemref elements defines the default reading order of the Publication.

Element Name

itemref

Usage

As a child of spine. Repeatable.

Attributes
idref [required]

An IDREF [XML] that identifies a manifest item.

linear [optional]

Specifies whether the referenced content is primary.

The value of the attribute must be yes or no. The default value is yes.

id [optional]

The ID [XML] of this element, which must be unique within the document scope.

properties [optional]

A space-separated list of property values.

Refer to Spine itemref Properties for a set of properties defined by this specification.

Content Model

Empty

Each itemref element must reference an item in the manifest via its idref attribute.

Each referenced manifest item must be either a) an EPUB Content Document or b) another type of Publication Resource which, regardless of whether it is a Core Media Type Resource or a Foreign Resource, must include an EPUB Content Document in its fallback chain.

note

Although the EPUB Navigation Document is required in EPUB Publications, it is optional to include it in the spine.

The itemref element linear attribute indicates whether referenced item is considered primary (yes) or auxiliary (no) in the spine. This attribute may be used to enable Reading Systems to distinguish presentation of body content from supplementary content which might be, for example, presented in a popup window or omitted from an aural rendition.

Any applicable descriptive metadata properties, such as those defined in the Spine itemref Properties, should be declared via the properties attribute.

Reading Systems must ignore all metadata properties expressed in the properties attribute that they do not recognize.

Examples

The following example shows a spine element corresponding to the manifest example above. 

<spine page-progression-direction="ltr">
+    <itemref idref="intro"/>
+    <itemref idref="c1"/>
+    <itemref idref="c1-answerkey" linear="no"/>
+    <itemref idref="c2"/>
+    <itemref idref="c2-answerkey" linear="no"/>
+    <itemref idref="c3"/>
+    <itemref idref="c3-answerkey" linear="no"/>
+    <itemref idref="notes" linear="no"/>
+</spine>
+

› 3.4.14 The guide Element [DEPRECATED]

The guide element [OPF2] is deprecated in favor of the landmarks feature in the EPUB Navigation Document. Refer to The landmarks nav Element [ContentDocs30] for more information.

Authors may include the guide element in the Package Document for EPUB 2 Reading System forwards compatibility purposes. EPUB 3 Reading Systems must ignore the guide element when provided in EPUB 3 Publications whose EPUB Navigation Document includes the landmarks feature.

› 3.4.15 The bindings Element

The bindings element defines a set of custom handlers for media types not supported by this specification.

Element Name

bindings

Usage

Optional fourth or fifth child of package, following spine or guide.

Attributes

None.

Content Model

One or more mediaType elements [required]

The package element may contain at most one bindings element.

The bindings element provides a means for Authors to include more sophisticated fallbacks than would otherwise be possible with the [HTML5] object element's intrinsic fallback mechanisms. When present, Reading Systems that support scripting must utilize the bindings element to handle object elements that reference unsupported media types.

Each of the bindings element's child mediaType elements defines a unique handler for one of the foreign media types referenced in the Publication's XHTML Content Documents.

When an unsupported media type is encountered during processing of a document, the Reading System must look up the handler in the bindings element by checking the media-type attribute of each mediaType element for a match (and before attempting any other type of fallback processing). If a match is found, the XHTML Content Document referenced in the element's handler attribute must be instantiated instead of the referenced resource. If no match is found, the Reading System should continue with normal fallback processing (i.e., check for an intrinsic fallback for the object).

The Reading System must instantiate the designated handler as if it had been referenced from the object element's data attribute with the following parameters:

src

the value of which must be an IRI [RFC3987] to the resource (i.e., the value of the object element's data attribute).

type

the value of which must be the resource media type (i.e., the value of the object element's media-type attribute).

Any additional param children of the object element must be similarly added as parameters using the param's name attribute as the new parameter name and its value attribute as the new value.

For example, the following object element containing a foreign media type:

<object data="horse.ogg" media-type="audio/ogg"/>
+    <param name="autoplay" value="false">
+</object>
+

would result in the following query string being sent to the handler XHTML Content Document after processing:

src=horse.ogg&type=audio/ogg&autoplay=false

All IRI reserved characters, plus the characters <, >, ", space, {, }, |, \, ^ and `, in the generated query string must be encoded and decoded as per [RFC3987].

object elements that reference media types handled by the bindings element are only processed in spine-referenced XHTML Content Documents (i.e., they are ignored in container-constrained scripting contexts).

Example

The following partial example illustrates how bindings can be used to provide a slideshow.

Consider a Publication with the following Package Document:

<package …>
+    …
+    <manifest>
+        <item id="pict1" 
+            href="images/Pict1.jpg" 
+            media-type="image/jpeg"/>
+        …
+        <item id="content" 
+            href="content.xhtml" 
+            media-type="application/xhtml+xml"/>
+        <item id="impl" 
+            href="impl.xhtml" 
+            media-type="application/xhtml+xml" 
+            properties="scripted"/>
+        <item id="slideshow" 
+            href="slideshow.xml" 
+            media-type="application/x-demo-slideshow"/>
+    </manifest>
+    
+    <bindings>
+        <mediaType handler="impl"
+            media-type="application/x-demo-slideshow"/>
+    </bindings>
+    …
+</package>
+

and the following content in the file content.xhtml:

<html …>
+    …
+    <body>
+        …
+        <object data="slideshow.xml" 
+            type="application/x-demo-slideshow">
+            <img src="images/Pict1.jpg"/>
+            <img src="images/Pict2.jpg"/>
+            <img src="images/Pict3.jpg"/>
+            <img src="images/Pict4.jpg"/>
+        </object>
+        …
+    </body>
+</html>
+

and the following content in the file slideshow.xml:

<slides>
+    <slide src="images/Pict1.jpg" dur="3"/>
+    <slide src="images/Pict2.jpg" dur="3"/>
+    <slide src="images/Pict3.jpg" dur="3"/>
+    <slide src="images/Pict4.jpg" dur="3"/>
+</slides>
+

Depending on the capabilities of the User's Reading System, they will see one of the following renditions of the slideshow:

  • If the Reading System supports the native slideshow format, it will render a rotating set of images as specified in slideshow.xml.

  • If the Reading System cannot support the slideshow media type but supports scripting, it can check the bindings element in the Package Document for a scripted fallback. There it will find a reference to the item element containing the handler document (impl.xhtml). The Reading System can now load this document to render a JavaScripted equivalent of the slideshow (source not shown).

  • If the Reading System does not support the slideshow media type and also does not support scripting, it will use the fallback images specified in the object element to show a static set of all the images.

› 3.4.16 The mediaType Element

The mediaType element associates a Foreign Resource media type with a handler XHTML Content Document.

Element Name

mediaType

Usage

As a child of bindings. Repeatable.

Attributes
media-type [required]

A media type [RFC2046] that specifies the type and format of the resource to be handled.

handler [required]

An IDREF [XML] that identifies the manifest XHTML Content Document to be invoked to handle content of the type specified in this element

Content Model

Empty

Each child mediaType of a bindings element must define a unique content type in its media-type attribute, and the media type specified must not be a Core Media Type.

The required handler attribute must reference the ID [XML] of an item in the manifest of the default implementation for this media type. The referenced item must be an XHTML Content Document.

All XHTML Content Documents designated as handlers must have the scripted property set in their manifest item's properties attribute.

› 4 Package Metadata

› 4.1 Publication Identifiers

› 4.1.1 Unique Identifier

The Package Document's author is responsible for including a primary identifier that is unique to one and only one particular EPUB Publication. This Unique Identifier, whether chosen or assigned, must be stored in a dc:identifier element in the Package metadata and be referenced as the Unique Identifier in the package element unique-identifier attribute.

Although not static, changes to the Unique Identifier for a Publication should be made as infrequently as possible. New identifiers should not be issued when updating metadata, fixing errata or making other minor changes to the Publication.

› 4.1.2 Package Identifier

The Unique Identifier of an EPUB Publication typically should not change with each minor revision to the package or its contents, as Unique Identifiers are intended to have maximal persistence both for referencing and distribution purposes. Each release of a Publication normally requires that the new version be uniquely identifiable, however, which results in the contradictory need for reliable Unique Identifiers that are changeable.

To redress this problem of identifying minor modifications and releases without changing the Unique Identifier, this specification defines the semantics for a Package Identifier, or means of distinguishing and sequentially ordering Publications with the same Unique Identifier. The Package Identifier is not an actual property in the package metadata section, but is a value that can be obtained from two required pieces of metadata: the Unique Identifier and the last modification date of the Publication.

When the taken together, the combined value represents a unique identity that can be used to distinguish any particular version of an EPUB Manifestation from another. To ensure that a Package Identifier can be constructed, the Publication must include exactly one [DCTERMS] modified property containing the last modification date (see meta). The value of this property must be an XML Schema [XSD-DATATYPES] dateTime conformant date of the form:

CCYY-MM-DDThh:mm:ssZ

The modification date must be expressed in Coordinated Universal Time (UTC) and must be terminated by the Z time zone indicator.

Although not a part of the package metadata, for referencing and other purposes this specification requires that all string representations of the identifier be constructed using the at sign (@) as the separator (i.e., of the form "id@date"). Whitespace must not be included when concatenating the strings.

The following example shows how a Unique Identifier and modification date are combined to form the Package Identifier.

<metadata xmlns:dc="http://purl.org/dc/elements/1.1/">
+    <dc:identifier id="pub-id">urn:uuid:A1B0D67E-2E81-4DF5-9E67-A64CBE366809</dc:identifier>
+    <meta property="dcterms:modified">2011-01-01T12:00:00Z</meta>
+    …
+</metadata>
+
+results in the Package ID:
+
+urn:uuid:A1B0D67E-2E81-4DF5-9E67-A64CBE366809@2011-01-01T12:00:00Z
+

Note that it is possible that the separator character may occur in the Unique Identifier, as these identifiers may be any string value. The Package Identifier consequently must be split on the last instance of the at sign when decomposing it into its component parts.

The Package Identifier does not supersede the Unique Identifier, but represents the means by which different versions of the same Publication can be distinguished and identified in distribution channels and by Reading Systems. The sequential, chronological order inherent in the required format of the timestamp also places Publications in order without requiring knowledge of the exact identifier that came before.

The Package Identifier consequently allows a set of Publications to be inspected to determine if they represent the same version of the same Publication, different versions of a single Publication, or any combination of differing and similar Publications.

› 4.2 Vocabulary Association Mechanisms

› 4.2.1 Overview

This section is informative

The property, properties, rel and scheme attributes use the property data type to represent terms from metadata vocabularies. Similar to a CURIE [RDFa10], the property data type represents an IRI [RFC3987] in compact form and simplifies the authoring of metadata from standardized vocabularies.

A property value is an expression that consists of a prefix and a reference, where the prefix — whether literal or implied — is a shorthand mapping of an IRI that typically resolves to a term vocabulary. When the prefix is converted to its IRI representation and combined with the reference, the resulting IRI normally resolves to a fragment within that vocabulary that contains human- and/or machine-readable information about the term.

To assist Reading Systems in processing property values, the means of establishing the IRI a prefix maps to is required, and this specification defines three such mechanisms:

  • a default vocabulary — defines the mapping when a property value does not include a prefix;

  • a set of reserved prefixes — these mappings are predefined (i.e., all Reading Systems recognize them) and can be used without having to be declared; and

  • the prefix attribute — a declarative means of creating new prefix mappings on the root package element.

› 4.2.2 Default Vocabulary

The default vocabulary is a vocabulary that does not require a prefix to be declared in order to use its terms in package metadata, and whose terms must always be unprefixed.

To facilitate the inclusion of package metadata, this specification defines the Package Metadata Vocabulary as the default vocabulary for Package Documents.

If a property value does not include a prefix, the IRI [RFC3987] stem http://idpf.org/epub/vocab/package/# must be used to generate the resulting IRI.

The IRI associated with the Package Metadata Vocabulary must not be assigned a prefix using the prefix attribute.

› 4.2.3 Reserved Vocabularies

This specification exclusively defines the following set of prefixes for use in package metadata.

Reserved metadata prefixes
Prefix IRI
dcterms http://purl.org/dc/terms/
marc http://id.loc.gov/vocabulary/
media http://www.idpf.org/epub/vocab/overlays/#
onix http://www.editeur.org/ONIX/book/codelists/current.html#
xsd http://www.w3.org/2001/XMLSchema#

The prefixes listed in the previous table must not be redeclared using the prefix attribute declaration mechanism. Similarly, the IRIs associated with each prefix must not be assigned to another prefix.

› 4.2.4 The prefix Attribute

The prefix attribute defines additional prefix mappings not reserved by the specification.

The value of the prefix attribute is a whitespace-separated list of one or more prefix-to-IRI mappings of the form:

(EBNF productions ISO/IEC 14977)
prefixes=mapping , { whitespace, { whitespace } , mapping } ; 
mapping=prefix , ":" , space , { space } , ? xsd:anyURI ? ; 
prefix=? xsd:NCName ? ; 
space=#x20 ; 
whitespace=(#x20 | #x9 | #xD | #xA) ; 

The following example shows prefixes for the Friend of a Friend (foaf) and DBPedia (dbp) vocabularies being declared using the prefix attribute.

<package … 
+	prefix="foaf: http://xmlns.com/foaf/spec/
+		 dbp: http://dbpedia.org/ontology/">
+	…
+</package>

The prefix attribute must not be used to redefine the default vocabulary or the predefined prefixes.

The prefix '_' is reserved for future compatibility with RDFa [RDFa10] processing, so must not be defined.

› 4.2.5 The property Data Type

› 4.2.5.1 Syntax

The property data type is a compact means of expressing an IRI [RFC3987] and consists of an optional prefix separated from a reference by a colon.

(EBNF productions ISO/IEC 14977)
property=[ prefix , ":" ] , reference; 
prefix=? xsd:NCName ? ; 
reference=? irelative-ref ? ;/* as defined in [RFC3987] */

The property data type is derived from the CURIE data type defined in [RDFa10], and represents a subset of CURIEs.

The following example shows a property value composed of the prefix dcterms and the reference modified.

<meta property="dcterms:modified">2011-01-01T12:00:00Z</meta>

After processing, this property would expand to the following IRI:

http://purl.org/dc/terms/modified

as the dcterms: prefix is a reserved prefix that maps to the IRI http://purl.org/dc/terms/.

When a prefix is omitted from the property value, the expressed reference represents a term from the default vocabulary.

The following example shows a property value taken from the default vocabulary.

<meta … property="role">aut</meta>

This property would expand to:

http://idpf.org/epub/vocab/package/#role

when the IRI for the default vocabulary is concatenated with the reference.

An empty string does not represent a valid property value, even though it is valid to the definition above.

› 4.2.5.2 Processing

A Reading System must use the following rules to create an IRI [RFC3987] from a property:

  • If the property consists only of a reference, the IRI is obtained by concatenating the IRI stem associated with the default vocabulary to the reference.

  • If the property consists of a prefix and reference, the IRI is obtained by concatenating the IRI stem associated with the prefix to the reference. If no matching prefix has been defined, the property is invalid.

The resulting IRI must be valid to [RFC3987]. Reading Systems are not required to resolve this IRI, however.

› 4.3 Package Metadata Vocabulary

› 4.3.1 Overview

This section is informative

The following sections both define a set of properties for use in package metadata and constitute a referenceable vocabulary. This vocabulary is the default vocabulary reserved by this specification for the use of unprefixed terms in package metadata.

The properties defined in this vocabulary are referenceable using the base IRI http://idpf.org/epub/vocab/package/#.

note

Property usage examples in the following sections have been drawn from the metadata and meta examples whenever possible. Refer to those examples for fuller context.

› 4.3.2 Metadata meta Properties

The meta element properties enhance Publication metadata by providing additional level(s) of detail.

These properties must reference the expression or resource they augment in the refines attribute on their parent meta element.

The following tables detail the available properties.

› alternate-script
Description:

The alternate-script property provides an alternate expression of the associated property value in a language and script identified by the xml:lang attribute.

This property is typically attached to creator and title properties for internationalization purposes.

Allowed value(s): xsd:string
Cardinality:

In the metadata section: zero or more

Attached to other metadata: zero or one

Extends:All properties.
Example: <meta refines="#creator" property="alternate-script" xml:lang="ja">村上 春樹</meta>
› display-seq
Description:

The display-seq property indicates the numeric position in which to display the current property relative to identical metadata properties (e.g., to indicate the order in which to render multiple titles).

When the display-seq property is attached to some, but not all, of the members in a set, only the elements identified as having a sequence should be included in any rendering.

Allowed value(s): xsd:unsignedInt
Cardinality:

In the metadata section: zero or more

Attached to other metadata: zero or one

Extends:All properties.
Example: <meta refines="#t2" property="display-seq">1</meta>
› file-as
Description:The file-as property provides the normalized form of the associated property for sorting.
Allowed value(s): xsd:string
Cardinality:

In the metadata section: zero or more

Attached to other metadata: zero or one

Extends:All properties.
Example: <meta refines="#creator" property="file-as">Murakami, Haruki</meta>
› group-position
Description:

The group-position property indicates the numeric position in which the Publication is ordered relative to other works belonging to the same group (whether all EPUBs or not).

The group-position property can be attached to any metadata property that establishes the group (such as a series title).

A Publication can belong to more than one group.

Allowed value(s): A single xsd:unsignedInt or series of decimal-separated numbers (e.g., 1 or 2.2.1).
Cardinality:

In the metadata section: zero or more

Attached to other metadata: zero or one

Extends: All properties.
Example: <meta refines="#t3" property="group-position">2</meta>
› identifier-type
Description:

The identifier-type property indicates the form or nature of an identifier.

When the identifier-type value is drawn from a code list or other formal enumeration, the scheme attribute should be attached to identify its source.

Allowed value(s):xsd:string
Extends:identifier
Cardinality:

In the metadata section: zero or more

Attached to other metadata: zero or one

Example: <meta refines="#src-id" property="identifier-type" scheme="onix:codelist5">15</meta>
› meta-auth
Description:The meta-auth property provides the name of a party or authority responsible for an instance of package metadata.
Allowed value(s): xsd:string
Cardinality:

In the metadata section: zero or more

Attached to other metadata: zero or one

Extends:All properties.
Example: <meta refines="isbn-id" property="meta-auth" id="meta-authority-01">Metadata Authority Inc.</meta>
› role
Description:

The role property describes the nature of work performed by a creator or contributor (e.g., that the person is the author or editor of a work).

When the role value is drawn from a code list or other formal enumeration, the scheme attribute should be attached to identify its source.

Allowed value(s):xsd:string
Cardinality:

In the metadata section: zero or more

Attached to other metadata: zero or one

Extends: contributor, creator
Example: <meta refines="#creator" property="role" scheme="marc:relators">aut</meta>
› title-type
Description:

The title-type property indicates the form or nature of a title.

When the title-type value is drawn from a code list or other formal enumeration, the scheme attribute should be attached to identify its source. When a scheme is not specified, Reading Systems should recognize the following title type values: main, subtitle, short, collection, edition and expanded.

Allowed value(s):xsd:string
Extends:title
Cardinality:

In the metadata section: zero or more

Attached to other metadata: zero or one

Example: <meta refines="#title" property="title-type">main</meta>

› 4.3.4 Manifest item Properties

The following tables define properties for use in the manifest item element properties attribute.

The Applies to field indicates which Publication Resource type(s) the given property may be specified on, the Cardinality field indicates the number of times the property must appear within the Package Document scope, and the Usage field indicates usage conditions.

› cover-image
Description:The cover-image property identifies the described Publication Resource as the cover image for the Publication.
Applies to:All raster and vector image types
Cardinality:Zero or one
Usage:Optional.
› mathml
Description:The mathml property indicates that the described Publication Resource contains one or more instances of MathML markup.
Applies to:EPUB Content Documents
Cardinality:Zero or more
Usage:Must be set if and only if the criterion specified in Description above is met.
› nav
Description:The nav property indicates that the described Publication Resource constitutes the EPUB Navigation Document of the Publication.
Applies to:The EPUB Navigation Document
Cardinality:Exactly one
Usage:Required.
› remote-resources
Description:

The remote-resources property indicates that the described Publication Resource contains one or more internal references to other Publication Resources that are located outside of the EPUB Container.

(refer to Publication Resource Locations for more information).

Applies to:All Publication Resources with the capability of internal referencing (e.g., XHTML Content Documents, SVG Content Documents, EPUB Style Sheets and Media Overlay Documents).
Cardinality:Zero or more
Usage:Must be set if and only if the criterion specified in Description above is met.
› scripted
Description:The scripted property indicates that the described Publication Resource is a Scripted Content Document (i.e., contains scripted content and/or elements from HTML5 forms).
Applies to:EPUB Content Documents
Cardinality:Zero or more
Usage:Must be set if and only if the criterion specified in Description above is met.
› svg
Description:The svg property indicates that the described Publication Resource contains one or more instances of SVG markup.
Applies to:XHTML Content Documents; the value is implied for SVG Content Documents.
Cardinality:Zero or more
Usage:Must be set if and only if the criterion specified in Description above is met.
› switch
Description:The switch property indicates that the described Publication Resource contains one or more instances of the epub:switch element.
Applies to:XHTML Content Documents.
Cardinality:Zero or more
Usage:Must be set if and only if the criterion specified in Description above is met.

The mathml, remote-resources, scripted, svg and switch properties must be specified whenever the resource referenced by an item matches their respective definitions. These properties do not apply recursively to content included into a resource (e.g., via the HTML5 iframe element). For example, if a non-scripted XHTML Content Document embeds a scripted Content Document, only the embedded document's manifest item properties attribute will have the scripted value.

Examples

The following example shows a manifest item element that represents the EPUB Navigation Document of a Publication.

<item properties="nav" id="c1" href="c1.xhtml" media-type="application/xhtml+xml" />
+

The following example shows a manifest item element that represents the cover image of a Publication.

<item properties="cover-image" id="ci" href="cover.svg" media-type="image/svg+xml" />
+

The following example shows a manifest item element representing a Scripted Content Document that also contains embedded MathML. 

<item properties="scripted mathml" id="c2" href="c2.xhtml" media-type="application/xhtml+xml" />
+

› 4.3.5 Spine itemref Properties

The following tables define properties for use in the itemref element properties attribute.

The Cardinality field indicates the number of times the property must appear within the Package Document scope, and the Usage field indicates usage conditions.

› page-spread-left
Description:The page-spread-left property indicates that the first page of the associated item's EPUB Content Document represents the left-hand side of a two-page spread.
Cardinality:Zero or more
Usage:Optional. This property must not be specified on an itemref that also specifies the page-spread-right property.
› page-spread-right
Description:The page-spread-right property indicates that the first page of the associated item's EPUB Content Document represents the right-hand side of a two-page spread.
Cardinality:Zero or more
Usage:Optional. This property must not be specified on an itemref that also specifies the page-spread-left property.

Examples

The following example shows how a two-page spread of a map might be indicated in the spine.

<spine>
+	<itemref idref="title"/>
+	<itemref idref="ps-1-l" properties="page-spread-left"/>
+	<itemref idref="ps-1-r" properties="page-spread-right"/>
+	<itemref idref="toc"/>
+	…
+</spine>

› 5 Publication Resources

› 5.1 Core Media Types

The following table lists the EPUB 3 Core Media Types. When a Publication Resource conforms to a Core Media Type specification, it is a Core Media Type Resource and can be included in the Publication without the provision of fallbacks (refer to Restrictions and Fallbacks for more information).

The columns in the table represent the following information:

Media Type

The MIME media type [RFC2046] used to represent the given Publication Resource in the manifest.

Content Type Definition

The specification to which the given Core Media Type Resource must conform.

Applies to

The Publication Resource type(s) that the Media Type and Content Type Definition applies to.

EPUB Core Media Types
Media Type Content Type Definition Applies to
Image Types
image/gif [GIF] GIF Images
image/jpeg [JPEG] JPEG Images
image/png [PNG] PNG Images
image/svg+xml SVG Content Documents [ContentDocs30] SVG documents
Application Types
application/xhtml+xml XHTML Content Documents [ContentDocs30] XHTML Content Documents and the EPUB Navigation Document.
application/x-dtbncx+xml [OPF2] The superseded NCX
application/vnd.ms-opentype [OpenType] OpenType fonts
application/font-woff [WOFF] WOFF fonts
application/smil+xml [MediaOverlays30] EPUB Media Overlay documents
application/pls+xml [PLS] Text-to-Speech (TTS) Pronunciation lexicons
Audio Types
audio/mpeg [MP3] MP3 audio
audio/mp4 [AAC LC], [MP4] AAC LC audio using MP4 container
Text Types
text/css EPUB Style Sheets [ContentDocs30] EPUB Style Sheets.
text/javascript [RFC4329] Scripts

note

This specification does not define any video codecs as Core Media Types. Refer to the note in EPUB Publications — Reading System Conformance above for informative recommendations on support for video codecs in EPUB Publications.

› 5.2 Restrictions and Fallbacks

› 5.2.1 Foreign Resource Restrictions

All Publication Resources of an EPUB Publication must be Core Media Type Resources or must provide a Core Media Type fallback. The cases in which Foreign Resource may be used, and the requirement and rules for Core Media Type fallback provision in such cases, are detailed below.

Intrinsic Fallback in EPUB Content Documents

› Foreign Resources may be referenced from EPUB Content Document elements that have explicit intrinsic fallback mechanisms (e.g., the [HTML5] object, canvas, audio and video elements). A Core Media Type resource must be provided via the given element's intrinsic fallback mechanism in such cases.

› For the [HTML5] video element, the image referenced by the poster attribute and text content embedded within the video element are also considered valid Core Media Type fallbacks in addition to the video element's intrinsic fallback capabilities. For the purpose of providing a last resort fallback for Reading Systems that do not support video or the given video format(s), at least one of these should be included with each occurrence of the video element.

› For the [HTML5] audio element, text content embedded within the element is also considered a valid Core Media Type fallback in addition to the audio element's intrinsic fallback capabilities. For the purpose of providing a last resort fallback for Reading Systems that do not support audio, embedded text content should be included with each occurrence of the audio element.

›  In this version of this specification, the [HTML5] track element is exempt from the Core Media Type usage rule: Foreign Resources may be referenced from track without the provision of a Core Media Type fallback.

Intrinsic Fallback in EPUB Style Sheets

› Fonts embedded in Content Documents or EPUB Style Sheets using the @font-face mechanism may be Foreign Resources. Reading Systems must use the rules for matching font styles [CSS3Fonts] when identifying a fallback for an unsupported font type.

Spine Resources

› Foreign Resources may be referenced directly from spine itemref elements, and in this case Manifest fallbacks must be provided.

› 5.2.2 Manifest Fallbacks

Fallbacks must be provided for each Publication Resource referenced in a spine itemref element that is not an EPUB Content Document.

Fallbacks are provided using the fallback attribute on the manifest item element that represents the Publication Resource. The fallback attribute's IDREF [XML] value must resolve to another item in the manifest. This fallback item may itself specify another fallback item, and so on.

The ordered list of all the ID references that can be reached starting from a given item's fallback attribute represents the fallback chain for that item. The order of the resources in the fallback chain represents the Authors' preferred fallback order.

A Reading System that does not support the Media Type of a given Publication Resource must traverse the fallback chain until it has identified at least one supported Publication Resource to be used in place of the unsupported resource. If the Reading System supports multiple Publication Resources in the fallback chain, it may select the resource to use based on specific properties of that resource, otherwise it should honor the Authors' preferred fallback order.

A fallback chain must contain at least one EPUB Content Document and must not contain any circular- or self-references to items in the chain.

Fallbacks may also be provided for Top-level Content Documents that are EPUB Content Documents; a Reading System may choose to utilize such fallbacks in order to find the optimal version of a Content Document to render in a given context. An example of when this feature can be utilized is when providing fallbacks for scripted content [ContentDocs30].

› 5.3 Publication Resource Locations

All Publication Resources must be located in the EPUB Container, with the following exceptions:

  • › Audio resources may be located in the Container or remotely.

  • › Video resources may be located in the Container or remotely.

Authors should prefer locating audio and video resources in the Container to allow the user access to the entire presentation regardless of connectivity status.

note

The above rules for Publication Resource locations apply regardless of whether the given resource is a Core Media Type Resource or a Foreign Resource.

note

The inclusion of remote resources in an EPUB Publication is indicated via the remote-resources property on the manifest item element.

› 5.4 XML Conformance

Any Publication Resource that is an XML-Based Media Type must meet the following constraints:

The above constraints apply regardless of whether the given Publication Resource is a Core Media Type Resource or a Foreign Resource.

› Appendix A. Package Document Schema

The schema for Package Documents is available at http://www.idpf.org/epub/30/schema/package-30.nvdl.

This schema is normative.

note

Validation using this schema will require a processor that supports [NVDL], [RelaxNG] and [ISOSchematron].

Note, however, that the NVDL schema layer can be substituted by a multi-pass validation using the embedded RELAX NG and ISO Schematron schemas alone.

› Appendix B. The application/oebps-package+xml Media Type

This appendix registers the media type application/oebps-package+xml for the EPUB Package Document. This registration supersedes [RFC4839].

The Package Document is an XML file that describes an EPUB Publication [Publications30]. It identifies the resources in the Publication and provides metadata information. The Package Document and its related standards are maintained and defined by the International Digital Publishing Forum (IDPF).

MIME media type name:

application

MIME subtype name:

oebps-package+xml

Required parameters:

None.

Optional parameters:

None.

Encoding considerations:

Package Documents are UTF-8 or UTF-16 encoded XML.

Security considerations:

Package Documents contain well-formed XML conforming to the XML 1.0 specification.

Clearly, it is possible to author malicious files which, for example, contain malformed data. Most XML parsers protect themselves from such attacks by rigorously enforcing conformance.

All processors that read Package Documents should rigorously check the size and validity of data retrieved.

There is no current provision in the EPUB Publications 3.0 standard for encryption, signing, or authentication within the Package Document format.

Interoperability considerations:

None.

Published specification:

This media type registration is for the EPUB Package Document, as described by the EPUB Publications 3.0 specification located at http://www.idpf.org/epub/30/spec/epub30-publications.html.

The EPUB Publications 3.0 specification supersedes the Open Packaging Format 2.0.1 specification, which is located at http://idpf.org/epub/20/spec/OPF_2.0.1_draft.htm and which also uses the application/oepbs-package+xml media type.

Applications which use this media type:

This media type is in wide use for the distribution of ebooks in the EPUB format. The following list of applications is not exhaustive.

  • Adobe Digital Editions

  • Aldiko

  • Azardi

  • Apple iBooks

  • Barnes & Noble Nook

  • Calibre

  • Google Books

  • Ibis Reader

  • MobiPocket reader

  • Sony Reader

  • Stanza

Additional information:
Magic number(s):

none

File extension(s):

.opf

Macintosh File Type Code(s):

TEXT

Fragment Identifiers:

The IDPF maintains a registry of linking schemes at http://idpf.org/epub/linking/. Some of these schemes define custom fragment identifiers that resolve to application/oebps-package+xml documents.

Person & email address to contact for further information:

William McCoy, bmccoy@idpf.org

Intended usage:

COMMON

Author/Change controller:

International Digital Publishing Forum (http://www.idpf.org)

diff --git a/src/test/resources/epub30-terminology.xhtml b/src/test/resources/epub30-terminology.xhtml new file mode 100644 index 0000000..1cbe6b8 --- /dev/null +++ b/src/test/resources/epub30-terminology.xhtml @@ -0,0 +1,11 @@ + +Terminology +
+ IDPF Logo +
+

Terminology

+
+ +
Author

The person(s) or organization responsible for the creation of an EPUB Publication, which is not necessarily the creator of the content and resources it contains.

EPUB Container (or Container)

The ZIP-based packaging and distribution format for EPUB Publications defined in [OCF3].

EPUB Content Document

A Publication Resource that conforms to one of the EPUB Content Document definitions (XHTML or SVG).

An EPUB Content Document is a Core Media Type, and may therefore be included in the EPUB Publication without the provision of fallbacks.

EPUB Navigation Document

A specialization of the XHTML Content Document, containing human- and machine-readable global navigation information, conforming to the constraints expressed in EPUB Navigation Documents [ContentDocs30].

Scripted Content Document

An EPUB Content Document that includes scripting or an XHTML Content Document that contains HTML5 forms elements.

Refer to Scripted Content Documents [ContentDocs30] for more information.

SVG Content Document

An EPUB Content Document conforming to the constraints expressed in SVG Content Documents [ContentDocs30].

XHTML Content Document

An EPUB Content Document conforming to the profile of [HTML5] defined in XHTML Content Documents [ContentDocs30].

XHTML Content Documents use the XHTML syntax of [HTML5].

Top-level Content Document

An EPUB Content Document referenced directly from the spine

Core Media Type

A set of Publication Resource types for which no fallback is required. Refer to Publication Resources for more information.

EPUB Publication (or Publication)

A logical document entity consisting of a set of interrelated resources and packaged in an EPUB Container, as defined by this specification and its sibling specifications.

EPUB Reading System (or Reading System)

A system that processes EPUB Publications for presentation to a User in a manner conformant with this specification and its sibling specifications.

Manifest

A list of all Publication Resources that constitute the EPUB Publication.

Refer to manifest for more information.

Manifestation

The digital (or physical) embodiment of a work of intellectual content. Changes to the content such as significant revision, abridgement, translation, or the realization of the content in a different digital or physical form result in a new manifestation. There may be many individual but identical copies of a manifestation, termed 'instances' or 'items'. The ISBN is an example of a manifestation identifier, and is shared by all instances of that manifestation.

All instances of a manifestation need not be bit-for-bit identical, as minor corrections or revisions are not judged to create a new manifestation or work.

Media Overlay Document

An XML document that associates the XHTML Content Document with pre-recorded audio narration in order to provide a synchronized playback experience, as defined in [MediaOverlays30].

OCF Processor

A software application that processes EPUB Containers according to this specification.

Package Document

A Publication Resource carrying bibliographical and structural metadata about the EPUB Publication, as defined in Package Documents.

Package Identifier

The Package Identifier allows any instance of an EPUB Publication to be compared against another to determine if they are identical, different versions of the same Manifestation, or unrelated.

Refer to Package Identifier for more information.

Core Media Type Resource

A Publication Resource that is a Core Media Type and may therefore be included in the EPUB Publication without the provision of fallbacks.

Publication Resource

A resource that contains content or instructions that contribute to the logic and rendering of the EPUB Publication. In the absence of this resource, the Publication might not render as intended by the Author. Examples of Publication Resources include the Package Document, EPUB Content Documents, EPUB Style Sheets, audio, video, images, embedded fonts and scripts.

With the exception of the Package Document itself, Publication Resources must be listed in the manifest and must be bundled in the EPUB container file unless specified otherwise in Publication Resource Locations.

Examples of resources that are not Publication Resources include those identified by the Package Document link element and those identified in outbound hyperlinks that resolve outside the EPUB Container (e.g., referenced from an [HTML5] a element href attribute).

Foreign Resource

A Publication Resource that is not a Core Media Type. A Foreign Resource requires at least one fallback, as defined in Restrictions and Fallbacks.

Spine

An ordered list of Publication Resources, typically EPUB Content Documents, representing the default reading order of the Publication.

Refer to spine for more information.

EPUB Style Sheet (or Style Sheet)

A CSS Style Sheet conforming to the CSS profile defined in EPUB Style Sheets [ContentDocs30].

Text-to-Speech (TTS)

The rendering of the textual content of an EPUB Publication as artificial human speech using a synthesized voice.

Unique Identifier

The Unique Identifier is the primary identifier for an EPUB Publication, as identified by the unique-identifier attribute. The Unique Identifier may be shared by one or many Manifestations of the same work that conform to the EPUB standard and embody the same content, where the differences between the Manifestations are limited to those changes that take account of differences between EPUB Reading Systems (and which themselves may require changes in the ISBN).

The Unique Identifier is less granular than the ISBN. However, significant revision, abridgement, etc. of the content requires a new Unique Identifier.

User

An individual that consumes an EPUB Publication using an EPUB Reading System.

Viewport

The region of an EPUB Reading System in which the content of an EPUB Publication is rendered visually to a User.

CSS Viewport

A Viewport capable of displaying CSS-styled content.

SVG Viewport

A Viewport capable of displaying SVG images.

+ + diff --git a/src/test/resources/epub_logo_color.jpg b/src/test/resources/epub_logo_color.jpg new file mode 100644 index 0000000..41cd08e Binary files /dev/null and b/src/test/resources/epub_logo_color.jpg differ diff --git a/src/test/resources/idpflogo_web_125.jpg b/src/test/resources/idpflogo_web_125.jpg new file mode 100644 index 0000000..023304d Binary files /dev/null and b/src/test/resources/idpflogo_web_125.jpg differ