dita4publishers/org.dita4publishers.epub

DITA-to-EPUB transformation type

DITA for Publishers

Version 1.1.0 Under development

Master project for the DITA for Publishers activity. This project includes the toolkit plugins and samples as git submodules. See the wiki for details on how to set up new clones of this project.

NOTE: Issues for specific transformation types (EPUB, HTML5, etc.) are maintained in the project each transformation type. If you're not sure which project an issue applies to, feel free to submit the issue against the dita4publishers project.

News

5 Aug 2021 Release 1.0.0RC28

Many updates. Tested against OT 3.6.1 (see release notes in user guide). Many Word2DITA issues resolved.

24 April 2016: EPUB3 implementation essentially complete with the addition of font embedding and obfuscation.

7 Oct 2014: EPUB3 implementation is under way. See the org.dita4publishers.epub project for details.

Publishing the User Guide

The D4P User Guide is published via GitHub Pages through the separate repo dita4publishers.github.io.

To update the user guide do the following:

1. Using InDesign, update the cover graphic to reflect the latest release and copyright date (docs/D4P Logo and User Guide Cover/D4P_UserGuide_cover Folder/D4P_UserGuide_cover.indd)
2. Export new copies of cover-graphic.png (300PPI) and epub-cover-graphic.png (72PPI) to the user_docs/d4p-users-guide/images directory
3. Run the html5-d4p-user-guide ant target
4. Copy the generated HTML (d4p-users-guide from the build/docs/html5 directory) to the dita4publishers.github.io repo on branch main.
5. Commit updates to dita4publishers.github.io repo and push

org.dita4publishers.epub's Issues

EPUB3: Add extension point for generating a signatures.xml section in the EPUB3 package

See http://www.idpf.org/epub/301/spec/epub-ocf.html#sec-container-metainf-signatures.xml

Should topicheads expanded by map-driven processing retain the topichead's node URI?

In map2epubContentImpl.xsl, topicheads are "expanded" to be their own DITA topics (c.f., <xsl:template match="*[df:isTopicHead(.)]" mode="generate-content">). The creation of their topic and title elements means their node URIs are that of the XSLT file rather than the context's (i.e., the topichead). It seems to me that the topic and title elements being created should retain the topichead's node URI in case someone wants to use those elements' URIs. I can't readily imagine typical use cases where that would actually occur. It would of course be easy to implement. (This decision will also apply to the HTML2 [which is going end of life soon] and Kindle plugins, which have identical code.)

epub3/dual nav file has unncessary namespace declarations

EPUB3: Provide an extension point for contributing to the rights.xml file

See http://www.idpf.org/epub/301/spec/epub-ocf.html#sec-container-metainf-rights.xml

EPUB3: Add extension point for generating a bindings section in the EPUB3 package

See http://www.idpf.org/epub/301/spec/epub-publications.html#sec-bindings-elem

This is an optional component of the EPUB3 package. There is no useful default but it might be necessary to generate when an EPUB includes non-standard media types.

Implement automated regression test on travis-ci

Need one or more regression tests to verify that the EPUB transform works for OT 1.8 and 2.0.

Ideally should run epubcheck after building the EPUB.

Would be possible to unzip the EPUB and verify specific structures, but that might be too hard to maintain.

Need to provide option for omitting the DITA-OT default CSS files (retain including them as the default)

Provide option of using OEPBS/-style file organization

Provide option of organizing EPUB contents using the OEBPS/ convention per examples in EPUB spec and test documents. Note that this organization is not mandated by the EPUB2 or EPUB3 standards.

epub2 files cannot have @doctype-system="about:legacy:compat"

EPUB3: Provide extension point for generating or contributing to encryption.xml file

See http://www.idpf.org/epub/301/spec/epub-ocf.html#sec-container-metainf-encryption.xml

This file is required when obfuscated fonts are included. It is also required when any resource is itself encrypted.

EPUB3: Generate appropriate HTML5 navigation structures

For EPUB3, need a normal HTML5 navigation structure, as for the HTML5 transform.

The navigation generation should be an extension point that is easy to configure and customize.

EPUB3: Generate EPUB3-conforming HTML5

EPUB3 mandates a restricted set of HTML5 files. Ensure that the HTML5 generated for EPUB3 conforms to the EPUB3 constraints.

EPUB3: Landmarks. Design and implement extension point to create flat list of links to major components of book

Design and implement extension point to create flat list of links to major components of book

Topic ref with @processing-role = 'resource-only' are processed

Is it normal behaviour for pub ?

Should I replace the xpath expression for the template mode="generate-content"?

match="*[df:class(., 'map/topicref')]">

by

match="*[df:class(., 'map/topicref')][not(@processing-role = 'resource-only')]

Guide elements not being included in opf element due to an incorrect xsl:if test

EPUB3: Design mechanism for convenient inclusion of fonts in the generated output

Need a way to specify and include embedded fonts in the generated EPUB file. Probably need a runtime parameter and maybe a conventional place to put fonts to be embedded. Since fonts need to be coordinated with the CSS it might make sense to just expect fonts to be in the same directory as the CSS file.

EPUB3: Implement default (and optional) landmarks navigation generation

See http://www.idpf.org/epub/301/spec/epub-contentdocs.html#sec-xhtml-nav-def-types-landmarks

container.xml has unnecessary namespace declarations

Remove dependency on HTML2 plugin

Refactor code as necessary to put any HTML2-specific required by the EPUB transforms into a more generic plugin.

directly-nested topics get enumeration from parent topicrefs

EPUB3: Implement general EPUB3 package (OPF) support

Update generation of OPF package document to reflect EPUB3 requirements.

EPUB3: Implement appropriate output for d4pPageNumber and d4pPageNumberRange elements

See http://www.idpf.org/epub/301/spec/epub-contentdocs.html#sec-xhtml-nav-def-types-pagelist

EPUB3: Provide extension point for contributing to the metadata.xml file

See http://www.idpf.org/epub/301/spec/epub-ocf.html#sec-container-metainf-metadata.xml

Implement conditional use of zip64Mode attribute for EPUB zipping

Check Ant version and warn when version is < 1.9.1

EPUB3: Add extension point for setting the value of the @prefix attribute

See http://www.idpf.org/epub/301/spec/epub-publications.html#sec-prefix-attr

Provide option to generate links from top-level topic titles back to TOC entries

Common practice for published EPUBs (at least for fiction) is to make part and chapter titles link back to their TOC entries. Since this is common publishing practice need to provide option to do this automatically.

EPUB3: Implement general support for @epub:type attribute (semantic inflection)

See http://www.idpf.org/epub/301/spec/epub-contentdocs.html#sec-xhtml-semantic-markup

See also http://www.idpf.org/epub/vocab/structure/#

Provide option to collect chapter footnotes at the end of the EPUB, organized by chapter

Some publications collect chapter footnotes at the end of the book, e.g., No Greater Valor

$d4p.epubType property is not being set in build file

EPUB3: Add extension point for generating a collections section in the EPUB3 package

See http://www.idpf.org/epub/301/spec/epub-publications.html#sec-collection-elem

This is an optional component of an EPUB3 package.

Map references result in inappropriate entries in OPF manifest

These keydefs:

  <keydefs>
    <mapref
      href="content/keydefs-content.ditamap"/>
    <mapref
      href="media/keydefs-media-pdf.ditamap"/>
    <mapref
      href="media/keydefs-media-epub.ditamap"/>
  </keydefs>

Result in these OPF entries:

      <item id="d70e17"
            href="content/keydefs-content.xhtml"
            media-type="application/xhtml+xml"/>
      <item id="d70e19"
            href="media/keydefs-media-pdf.xhtml"
            media-type="application/xhtml+xml"/>
      <item id="d70e21"
            href="media/keydefs-media-epub.xhtml"
            media-type="application/xhtml+xml"/>

opf modification date needs to be a meta element in epub3 and dual but a dc:data element in epub2

Topicref that refers to its own key locks up map-to-graphic-map processing

Need to detect this case:

<front-cover keyref="coverpage" keys="coverpage"/>

EPUB Zip does not pass epubcheck

Getting this failure:

The mimetype file has an extension of length 20. No filename extensions are permitted for the mimetype file.

From epubcheck for the EPUB Zip file generated by the Ant task. Have asked Radu and Jean Kaplansky for guidance. Using Oxygen's archive browser to open and save the EPUB file resolves the issue, so it must be something with how Ant's Zip implementation works.

Would like to avoid having custom Java code just to make the Zip file.

CSS files are not going into EPUB correct, references are not correct

@properties not allowed on <item> in OPF in epub2

Handle missing graphics

Detect missing graphics and use the "missing graphics" images in the plugin's resources/ dir for any missing graphic.

This should be an optional behavior, with the option to continue to fail if any graphic cannot be found.

Do not included EPUB-3-only constructs in EPUB2-only EPUBs

epub-cover-graphic topicref type does not seem to work for setting the epub cover

This does not work.

EPUB3: Need way to generate arbitrary EPUB3 meta elements

For EPUB3, the meta element uses the @Property attribute rather than @name, where @Property is a prefix-qualified name. See http://www.idpf.org/epub/301/spec/epub-publications.html#sec-meta-elem and http://www.idpf.org/epub/301/spec/epub-publications.html#sec-property-datatype

It's not yet clear what to do for DITA data elements with names that are not prefixed. Unprefixed names are inherently in the default vocabulary, which means you can't just put in any unprefixed name you want.

EPUB3: Generate required fallback references for foreign media types

See http://www.idpf.org/epub/301/spec/epub-publications.html#sec-publication-resources

When a referenced resource is not a core resource type, there must be a fallback. System needs to report lack of a fallback and/or generate appropriate fallbacks when possible.

Add CSS references to the NAV XHTML document.

In the module map2epubNavImpl.xsl, there is no CSS references in the xsl:result-document instruction that generates the NAV XHTML document. Actually there is a "FIXME" comment there.

Code:

<xsl:result-document href="{$resultUri}" format="html5">
      <html 
        xmlns:epub="http://www.idpf.org/2007/ops" 
        >
        <head>
            <meta charset="utf-8" />
            <!-- FIXME: May need to generate appropriate CSS references here -->
        </head>
        <body>
          <xsl:for-each select="$navTypes">
            <xsl:variable name="navType" as="xs:string" select="."/>
            <xsl:message> + [INFO]   Generating nav structure for type "<xsl:value-of select="$navType"/>"...</xsl:message>
            <xsl:for-each select="$map">
                <xsl:call-template name="generate-nav-structure">
                  <xsl:with-param name="doDebug" as="xs:boolean" tunnel="yes" select="$doDebug"/>
                  <xsl:with-param name="navType" select="$navType" as="xs:string" tunnel="yes"/>
                </xsl:call-template>
            </xsl:for-each>
          </xsl:for-each>
        </body>
      </html>
    </xsl:result-document>  

Generate unique HTML files for each navigation reference to a topic

EPUB requires that each navigation reference to a file be the only reference to that file. Thus, each navigation reference must be to a separate HTML file or equivalent resource.

The process should behave as follows:

1. If the navigation topicref has a @keys value, use the first or only key as the base filename, if the key is the first effective definition of the key in the map.
2. If no @keys value, use the base filename of the source topic (possibly as set by @copy-to) as the base for the result filename. Count the number of preceding references in order to generate a filename of the form {basename}-{nn}.

This processing could be implemented during the base chunk processing or during final map-driven HTML processing.

Automatic Chunking: Provide facilities for automatically chunking e.g., chapters

Users have the requirement to chunk output at the chapter level for EPUB where the same map would not be chunked for other HTML outputs (e.g., Web help).

Need to provide a way to automatically trigger chunking, e.g., a pre-process extension to add @chunk values to the map in advance of chunk processing.

epubcheck does not allow @scheme on <meta>

Video and audio files are not in epub archive

Should set "Generated by html2xhtml mode ..." comment to only be output when $doDebug is true

The "Generated by html2xhtml mode..." comment in html2xhtml.xsl writes the timestamp to the generated ePub file. This means two executions of the plugin will produce different files. Setting this comment to only be executed when $doDebug is true.

epub2 does not allow @xml:lang on <package> in opf file

Localize all generated strings

Use the OT's "get string" facility to get localized versions of all generated strings.

Map to Graphic Map: Relative path constructed incorrectly

See file sample_data/epub-test/chapters/reusable-resources/common-figures.xml

The relative path with a go-up is not being handled correctly: the absolute path is one level too low so copy instruction in copy-graphics.xml is wrong.