Performance improvements

DITA-OT 1.6 contains several updates that combine for significant performance improvements for large documents. For example, building the DITA 1.2 Language Specification to XHTML takes just over 1/3 of the time as with the previous release (tests show an improvement of 288%).

Error message overhaul

In the recent DITA-OT usage survey, we asked for specific problems encountered when running the DITA-OT. The most frequent response was difficulty understanding and responding to error messages. The latest release addresses this in two ways:

1. Every message has been reviewed, and nearly every message has been revised for clarification.
2. Messages are now documented in the DITA-OT User Guide. The new documentation contains additional details about nearly every message, including potential remedies and links to helpful information.

Code cleanup

Of particular interest to developers, much of the deprecated code in the toolkit (some of it unused for 5+ years) has been removed. As a result, much of the code is cleaner, faster, and easier to customize. For example, the cleanup of PDF code allowed us to remove the alternate *_1.0.xsl stylesheets.

New arguments have been added:

• args.rellinks controls which related links will be output.
• args.filter defines the filter file to be used.

New configuration options have been added:

• generate-debug-attributes controls debug attribute generation and can be used to reduce memory consumption.
• processing-mode controls error recovery behavior.

Support for the old DITAVAL format (used before OASIS added DITAVAL to the standard in 2007) has been removed.

Source distribution package has been removed in favor or Git and GitHub source downloads.

The demo folder has been deprecated and the following plug-ins have been moved to plugins folder:

The following plug-ins in the demo folder have been moved to a separate plug-ins Git repository:

• FrameMaker_adapter
• apiref
• authorinfo
• book
• elementref
• enote
• faq
• java
• javaapiref
• music
• thesaurus
• tutorial
• video

The following bundled libraries have been updated:

• Ant
• ICU4J
• Apache Xerces

The following deprecated items are no longer supported in the PDF transform:

• Support for the beta version of DITA, available from IBM before the OASIS standard was created in 2005.
• Support for the "bkinfo" demo plug-in, used to support book metadata before OASIS created the BookMap format in 2007.
• Support for layout-masters.xml configuration.

The following extension-points have been added:

• dita.conductor.pdf2.param to add XSLT parameters to XSL FO transformation.

The deprecated property dita.input.valfile should be replaced with the new argument property args.filter.

Target dita-preprocess has been removed and dependencies should be replaced with a target sequence build-init, preprocess.

Support for argument args.message.file has been removed as message configuration has become static configuration.

Processing instruction workdir has been deprecated in favor of processing instruction workdir-uri. The only difference between the two processing instructions is that workdir-uri contains a URI instead of a system path.

The following deprecated templates and modes have been removed in topic pull stylesheets:

• inherit
• get-stuff
• verify-type-attribute
• classval
• getshortdesc
• getlinktext
• blocktext
• figtext
• tabletext
• litext
• fntext
• dlentrytext
• firstclass
• invalid-list-item
• xref

The following named templates have been deprecated:

• make-index-ref

The following deprecated templates have been removed:

• revblock-deprecated
• revstyle-deprecated
• start-revision-flag-deprecated
• end-revision-flag-deprecated
• concept-links
• task-links
• reference-links
• relinfo-links
• sort-links-by-role
• create-links
• add-linking-attributes
• add-link-target-attribute
• add-user-link-attributes

The removed templates have been replaced by other templates in earlier releases and plug-ins should be changed to use the new templates.

The following deprecated templates have been removed:

• revblock-deprecated
• revstyle-deprecated
• start-revision-flag-deprecated
• end-revision-flag-deprecated

The removed templates have been replaced by other templates in earlier releases and plug-ins should be changed to use the new templates.

Custom PDF2 shell stylesheets need to be revised to not include separate IBM and OASIS DITA stylesheets. The *_1.0.xsl stylesheets have been removed and their imports must be removed from shell stylesheets.

The following template modes have been deprecated:

• toc-prefix-text
• toc-topic-text

The following named templates have been removed:

• processTopic
• createMiniToc
• processTopicTitle
• createTopicAttrsName
• processConcept
• processReference
• getTitle
• placeNoteContent
• placeImage
• processUnknowType
• insertReferenceTitle
• buildRelationships
• processTask

Main FO generation now relies on merging process to rewrite duplicate IDs. The default merging has done this already in previous releses, but now also custom merging needs to fulfill the duplicate ID rewrite requirement.

Support for layout-masters.xml configuration has been removed, plug-ins should use createDefaultLayoutMasters template instead.

• #1057 Deprecate logException and add logError(String, Throwable) (milestone 1)
• #1059 PDF2 should fully support core default language (milestone 1)
• #1058 Add switch to ignore links in XHTML (milestone 1)
• #1158 Refactor log messages and tasks (milestone 1)
• #1060 Reduce topic merge memory consumption (milestone 1)
• #1062 Remove IBM DITA and BookMap demo support from PDF2 (milestone 1)
• #1063 Move OT version number to configuration (milestone 2)
• #1061 Remove obsolete dita-preprocess target (milestone 2)
• #1065 Add index file to PDF2 variables (milestone 3)
• #1067 Move Ant scripts to plug-in folders (milestone 3)
• #1066 Run XSLT with Ant task in PDF2 (milestone 3)
• #762 bookmap.dtd and map.dtd are out of sync with OASIS (milestone 3)
• #1068 Add XSLT param extension point to PDF2 (milestone 4)
• #948 For PDF output, xml:lang does not work at the element level (milestone 4)
• #1064 Support localization of quotation marks in quote (milestone 4)
• #1070 Remove support for args.message.file (milestone 4)
• #1071 Add automatic font detection to PDF2 (milestone 4)
• #1182 Need extension for determining topic level (milestone 4)
• #1236 <span> tags added around step when DRAFT on (milestone 4)
• #1262 css support for codeph in HTML output (milestone 4)
• #1198 Generate PDF metadata from bookmeta (milestone 5)
• #1273 Remove source distribution builds (milestone 5)
• #1203 ditaval flag action screws strow rendering (milestone 5)
• #1104 DitaWriter workdir PI not a URL (milestone 5)
• #1252 Document error messages in user guide (milestone 5)
• #1278 Separate core and extra plug-ins (milestone 5)
• #1249 Add Files from Distribution Packages to Git Repo (milestone 5)
• #1283 xref with desc and no href not handled in XHTML (milestone 5)
• #1137 Consistent coding conventions for Java code (final release)
• #1153 Remove deprecated Ant files (final release)
• #1300 Add a hook to set @summary on table in XHTML (final release)
• #1302 Add a way for cross-references to pick up generated text for sections (final release)
• #1266 Honor the map top level processing instruction (final release)
• #1156 Refactor preprocessing to use SAX filters (final release)
• #1159 Remove Content object (final release)
• #1155 Use Job to read/write job configuration files (final release)
• #1160 Improve filtering (final release)
• #1124 Make Java code thread-safe (final release)
• #1157 Clean Ant scripts (final release)
• #1149 Consistent Ant property names (final release)
• #1161 Remove deprecated code (final release)
• #1162 Improve title numbering in PDF2 (final release)
• #1163 Clean PDF2 ID processing (final release)
• #1165 Improve PDF2 table customization (final release)
• #1166 Improve pipeline module processing (final release)
• #1164 Avoid strings where other types are more appropriate (final release)
• #1168 Add ability to disable debug attribute generation (final release)
• #1249 Add Files from Distribution Packages to Git Repo (final release)
• #1243 Support for some kind of die_on_error property (final release)
• #1257 Simplify common XHTML code for flag/revision (final release)

• #849 Map references with root fragment are not processed (milestone 1)
• #743 Key-based mapref results in preprocessing error (milestone 1)

• #732 Temp dir with non-ASCII character crashes (milestone 1)
• #729 v 1.5.4 fails to create PDF with external topic ref (milestone 1)
• #747 [1.5.4]Glosslist no longer visible in Bookmarks (PDF output) (milestone 1)
• #733 Incorrect image reference does not checked (milestone 1)
• #725 Deprecated property breaks Plus plugins (milestone 1)
• #740 Info message about inline flagging not displayed (milestone 1)
• #738 NullPointerException when absolute path to image (milestone 1)
• #739 PDF2 image references broken with uplevels (milestone 1)
• #734 1.5.4 looks for lib dir at current dir instead a ${dita.dir} (milestone 1)
• #735 Apache FOP: TOCs with uneven right margin (milestone 1)
• #744 Possible collision in File Extension detection mechanism (milestone 1)
• #743 Key-based mapref results in preprocessing error (milestone 1)
• #753 Choicetable headings not localized in PDF (milestone 2)
• #754 Check all places where output streams are used in dost.jar (milestone 2)
• #755 Property noCoderef not declared (milestone 2)
• #745 HTML handling of *div does not generate @outputclass (milestone 2)
• #750 Stylesheet imported multiple times in the hierarchy (milestone 2)
• #752 Warning when using @copy-to in reltable (milestone 2)
• #722 Revisions on <plentry> use wrong image for nested <pd> (milestone 2)
• #721 Bug in handling of longdescref (milestone 2)
• #709 Image files not copied or referenced correctly for eclipse (milestone 2)
• #758 Keydefs in non-base folder fails (milestone 3)
• #757 Deprecated metadata PICS-Label in XHTML output (milestone 3)
• #719 Glossentry makes FO file invalid in PDF output (milestone 3)
• #677 Warning given by Saxon EE when processing flag-rules.xsl (milestone 3)
• #759 PDF2: preface titles does not pull indexterms. (milestone 3)
• #760 startcmd.bat adds dost.jar twice to the CLASSPATH (milestone 3)
• #765 XSL for Warning uses wrong attribute set (milestone 4)
• #764 steps-unordered doesn't generate heading (milestone 4)
• #763 choicetable/@product value output in fo:table (milestone 4)
• #1229 Typos in domains_(un)classed.css (in progress)
• #1284 Fix broken references in catalog file for PDF publishing (milestone 5)
• #1216 Customizing PDF layout-masters in 1.5.3 (milestone 5)
• #1177 Extension Point @behavior Not Documented (milestone 5)
• #1207 Table colwidth attribute always treated as proportional (milestone 5)
• #1101 zh-CN file for PDF puts English strings in output (final release)
• #1289 Improve error messages (final release)
• #1295 Various errors when using term with keyref in XHTML (final release)
• #1294 Use dita.ext instead of dita.extname (final release)
• #1297 Mappull doesn't recognize <navtitle> when checking for navtitle for non-DITA resources (final release)
• #1191 Text only mode outputs desc content in links (final release)
• #1303 Add Java properties file DTD to catalog (final release)
• #1308 XHTML flag support missing for linklist, linkinfo, linklist/desc (final release)
• #1307 M5 reports "illegal character" for xref that uses space in directory name (final release)
• #1152 UNC paths are not supported in input argument (final release)
• #1072 URLs not decoded by dost.jar (final release)
• #1306 Typo in XSLT mode results in extra fallthrough text for step (final release)
• #1321 Fix path2project separator clean-up (maintenance 1)
• #1322 Xref to table cell does not properly navigate to it (maintenance 1)
• #1323 @relcolwidth attribute not taken into account when transforming <choicetable> to PDF using Apache FOP (maintenance 1)
• #1325 Variable "Index See Also String" missing from Hebrew (maintenance 1)
• #1329 PDF2 indexing fails for ranges (maintenance 1)
• #1330 Spaces in Filenames in 1.6 (maintenance 1)
• #1335 Link to see/see also in index is broken (maintenance 2)
• #1340 The "DitaWriter" class does not properly resolve entities when catalogs are referenced with <nextCatalog> in the catalog-dita.xml (maintenance 2)
• #1343 Topics with spaces in file name appear twice (maintenance 2)
• #1346 Cannot determine the title of a xreffed topic (maintenance 2)
• #1348 Topics copied using "copy-to" become not wellformed (DITA OT 1.6.1) (maintenance 2)
• #1351 'Unexpected Text' root-processing_axf.xsl bug (maintenance 2)
• #1353 dita2htmlImpl.xsl/add-br-for-empty-cmd ... content match (maintenance 2)
• #1354 xml comment not being stripped correctly in preprocessing (maintenance 2)
• #1357 NPE when image is incorrectly referenced when publishing to HTML (maintenance 2)
• #1358 Cannot cross reference definition list items (dlentry, dt, dd) in PDF (maintenance 2)
• #1365 pdf duplicate see-also entries in Index (maintenance 3)
• #1369 prodinfo seems to lead to "(file) does not exist", where file has spaces in name (maintenance 3)
• #1370 Links to files with spaces in name broken (maintenance 3)
• #1371 build_demo uses deprecated Ant property (maintenance 3)
• #1377 htmlhelp ampersand (&amp;) entity in indexterm does not convert (maintenance 3)
• #1378 dita.out.map.htmlhelp.hhk: target doesn't allow topic with empty indexterm (maintenance 3)
• #1382 Merging uses system path separator when rewriting URIs (maintenance 3)