Release Notes: Version 1.0.0RC28

Version 1.0.0RC28

Theme for the Release

  • Resolve a number of lingering issues with the Word2DITA framework.
  • Update the D4P document type shells to use DITA 1.3 modules, including the new MathML, SVG, and equation domains.
  • Update all D4P Open Toolkit plug-ins to work with OT 3.x (3.6.1 is the latest version as of this release).
  • Update all XSLT modules to use XSLT 3. This mostly means that you must use Saxon 9.9 or newer to run the transforms and that you can use XSLT 3 features in the transforms. Except where a transform was already being modified, the transforms have not otherwise been updated to take advantage of XSLT 3 features (i.e., contains-token() in place of contains() for checking DITA @class values, <xsl:mode>, text value templates, etc.).

Document Type Changes

The D4P shells have been updated to reflect DITA 1.3:
  • All references to specific DITA versions in references to standard DITA modules have been removed from shells.
  • Use of the D4P Math domain has been replaced by use of the DITA 1.3 math domain. The main change to documents is to replace the <d4p_math> element with the DITA 1.3 <math> element. Existing MathML markup should continue to be valid as is.
  • Use of the D4P SVG domain has been replaced by the use of the DITA 1.3 SVG domain.
  • Use of the D4P equation domain has been replaced by use of the DITA 1.3 equation domain. Documents will need to replace the D4P elements for equations with the equivalent DITA 1.3 elements.
  • Use of the D4P @@renditionTarget attribute domains has been replaced by use of the DITA 1.3 @@deliveryTarget attribute domain.

These changes are only to the D4P-provided document type shells. Custom shells are not affected. If you do not want to adopt these changes and you have been using the D4P-provided shells you will need to create your own shells by copying the pre-RC28 shells to your environment and associating them with public IDs or URNs that reflect your ownership (i.e., create a new DITA Open Toolkit plug-in that provides your shells with your public IDs) and update your documents to use the new shells.

Word2DITA Changes

This release resolves a number of lingering issues:
  • Issue 46: Enable styling of direct character formatting. Manual inline formats (bold, italic, underline, strikeout, subscript, and superscript) are now automatically styled by default. The style names reflect the DITA tag names for the natural target elements ("b", "i", "u", "line-through", "sub", and "sup"). Where multiple formats are applied to the same run, the style name reflects each style name separated by "-", i.e., "b-i", "b-i-u", etc. These styles can then be mapped using normal <characterStyle> entries in the style-to-tag map. The built-in style2tagmap.xml file has a set of such mappings.

    The built-in final-fixup mode includes processing to convert runs that reflect multiple styles into the corresponding nested elements. I.e., a run with the style "b-i" becomes <b><i>...</i></b> in the final DITA.

    The auto-styling is handled by a new mode defined in the office-open-utils.xsl module. Converting multi-format <ph> elements to nested elements is handled in the built-in final-fixup.xsl module.

  • Issue 48: Hyperlink @outputclass value not preserved. Use any @@outputclass value specified for xref in style-to-tag map that maps to cross reference created from a complex ref field.
  • Issue 49: Table cell namest/nameend values not correctly calculated in the face of row spans. The calculation of @@namest and @@nameend is now correct when horizontal spans occur to the right of a vertical span into the horizontal cells' row.
  • Issue 50: Capture table cell shading. Table cell shading in Word tables is now captured using values in the @@base attribute of the generated <entry> element. Will capture either or both of the shading color (as the value specified in the Word data, normally a hex RGB value) and the shading pattern (as the pattern keyword specified in the Word data): 
    <entry base="shade(#FFFF00)"><p><b>Yellow shade header</b></p></entry>
<entry base="shade(#4BACC6) shadePattern(diagCross)"><p><b>Pattern
  cell</b></p></entry>
  • Issue 51: topicZone for titlealts seems to be ignored. Corrected generation of title alts to put them in the appropriate titlealts element. Added new processing in built-in final-fixup mode to handle correct output of title alts. Added new option "generateTitleAlts" on paragraphs that generate titles. When @@generateTitleAlts is specified, the title content will be used to generate the specified elements within the configured <titlealts> element. Title alts will only be generated when the same-named title alt is not generated from a separate paragraph using a @@topicZone of "titlealts".
  • Issue 52: Runs between fnrefs/endnote refs in same para may be lost. Refined how runs are handled to correct this behavior.
  • Issue 53: cross-references lost in DITA files. Implemented general support for complex fields. REF fields to targets in the same document now result in working cross references.

EPUB Generation Changes

  • Issue 80: SVG documents must not have DOCTYPE declarations, org.dita4publishers.common.xslt issue 19: Remove DOCTYPE declarations from SVG graphics copied by the graphic copy mechanism. This resolves a potential EPUB conformance issue as the EPUB specification does not allow DOCTYPE declarations for embedded SVG documents.
  • Issue 89: Update for OT 3.6+: A number of small changes to various supporting modules, including restoring copying of graphic files and correcting generation of the NDX file ID so that epubcheck passes (or can pass). The D4P User Guide EPUB passes latest epubcheck with no errors or warnings and kindlepreviewer generates a good Kindle book from the EPUB.
  • Issue 87: Errors reported with latest Epub Checker: Added missing <title> element to <head> in nav.xhtml.

Kindle Generation Changes

Amazon has replaced the older kindlegen tool with the kindlepreviewer tool, which provides both a command-line EPUB-to-MOBI conversion facility as well as an interactive tool for working with and previewing Kindle books.

The D4P org.dita4publishers.kindle Open Toolkit plug-in has been updated to support the new kindlepreviewer tool as well as the older kindlegen tool.

Other Plugin Changes

  • Updated all XSLT modules to XSLT 3. For most modules this is just a change the @@version value on <xsl:stylesheet> with no further change to the module. Where modules were modified in the course of addressing other issues XSLT 3-specific features may have been used (i.e., using contains-token() in place of df:isClass() or contains(@class, '…'), <xsl:mode> elements, text value templates, etc.). There should be no functional change as a result of specifying XSLT version 3 as long as you are using an appropriately-modern version of Saxon, i.e., 9.9+.
  • org.dita4publishers.common.xslt Issue 13: map-to-graphic-map does not ignore topicrefs within chunking topicrefs. Added check for being within a chunk.
  • org.dita4publishers.common.mapdriven pull request 4, org.dita-community.common.mapdriven: Removed use of Java Date object to capture timing for debugging. Removed use of Java Date object, which fails using Saxon HE as HE does not support Java reflection-based XSLT extensions. This time capturing was dubious at best and data collection now appears to run quite quickly, probably due to improvements in Saxon.

Repository Organization Changes

  • Renamed the dita4publishers repository "master" branch to "main" to reflect current best practice. If you have a local clone or fork of the repository you will need to do the same rename locally:
    git branch -m master main
git fetch origin
git branch -u origin/main main