Updates to the PDF processor in DITA-OT 1.5

This page contains updates specific to PDF output in version 1.5 of the DITA Open Toolkit. For other updates in version 1.5, see Plans for DITA-OT 1.5

The final build of DITA-OT 1.5 contains all of the fixes listed below for previous milestones, as well as many new items related to the PDF transform. Many of the updates to the PDF transform were not recorded at the time of release; those updates are listed here, but most initially appeared earlier in a milestone build:

XSLT Improvements

• Task elements are handled in separate XSL files.  This makes them a little easier to find, and more importantly it corrects a slew of priority bugs
• attr-set-reflection.xsl now actually works.  It used to be that some attribute sets were "fakes" - topic.topic.title for example couldn't have <xsl:if> or <xsl:variable> in it.  Now all attributes sets are "real" - they all support normal xsl behavior
• Most topics are generated via a common template: <xsl:apply-templates select="." mode="commonTopicProcessing"/>, which allows more sophisticated template matching if warranted.
• layout-masters.xsl replaces layout-masters.xml, allowing xsl templates and variables for simpler coding of layout masters
• <xref> text is done with a mode pattern match, which means that you don't have to override the whole huge template to change one type of xref.
• Spacing was improved at the cost of a little fragility:  The <indexterm>s in <prolog> now actually generate their anchors inside the title text, which prevents some strange spacing problems.  However, this means that customizations that override the template that generates the title need to be updated.
• The TOC text is generated via pattern matches, so you can overwrite TOC text for one type of entry without changing the whole template.
• Duplicate id values error fixed
• Convert named PDF templates to mode templates

Toolkit files

• basic-settings.xsl - there's a new file that allows you to set margins and page size and default font size and the side-column width (i.e. the indent of normal body text) without making tons of changes all over the place.
• Organizing of dtd files

Content

• The @scale attribute on images is supported as per the spec.
• The @pgwide attribute is supported on tables

Localization

• xml:lang is supported.  The first xml:lang sets the language for the whole document, unless the document.locale parameter is set.  Additionally, xml:lang works on an element by element level for variable substitutions, which can be useful for example for a multilingual warnings section.
• Some letters from the French index are fixed

Ant

• Ant parameter args.chapter.layout or $chapterLayout='BASIC' removes the whole Mini-TOC at the start of each chapter.
• Ant parameter retain.topic.fo set to any value will retain topic.fo for debugging.

Output

• Notices now appear before the TOC.  (However, the bookmarks still appear after the TOC; this is a bug.)
• The > character is now the default in a menucascade instead of that arrow character that wasn't in anyone's fonts.
• Short Description and abstract appear even in the first topic of a chapter, fixing an old bug.
• A step with importance="optional" now generates an Optional label on that step.
• Bookmarks default to collapsed, and there are both Ant and stylesheet parameters to change that.
• Suppress data and data-about in PDF output

PDF Formatters

• FOP support somewhat improved, but there's still no index until FOP starts supporting the necessary elements.
• Out of the box Antenna House support - you only have to set the Ant parameter pdf.formatter=ah.  You might want to check that the environment variable AXF_DIR is set to point to your Antenna House directory, but it's only necessary if it's in a non-standard place or it's newer than AH Formatter 5.1.
• RenderX is still supported, as before, with pdf.formatter=xep.  It's no longer the default, though.  pdf.formatter=fop is the default.

XSLT Engine

• Saxon 9 is the default, which means XSLT2 is supported.

Backwards incompatibilities

• There is a backwards incompatibility in the next release if you have customized processTopicTitle·        
• Munging is backwards incompatible if you use the IDs elsewhere.

Older items, sorted by availability date

• Automatic Antenna House Support
  • No separate setup is necessary
  • Must pass pdf.formatter=AH parameter
• Automatic Language Detection 
  • Checks xml:lang for current language
  • Not necessary to pass in document.locale parameter
  • Locale is taken from the first xml:lang attribute in a map or a topic
  • If the document.locale ANT parameter is provided, its value will override the value in xml:lang
  • If neither document.locale nor xml:lang provides a locale, the locale will default to en_US
  • The new fo.jar provides a <detect-lang> task that sets document.locale. This task is accessed in demo/fo/build.xml

• FOP is supported by default
  • Doesn't support automatic table layout
  • Doesn't support indexing
• ANT version 1.7 is required
  • ANT version 1.7 is included in the full installation package
  • PLEASE NOTE: Version 1.4.3 of the plug-in will crash if earlier versions of ANT are used

• Implement print=no 
• By default, plug-in can be located either in the demo directory or in the plugins directory 
• Fixed bugs in demo/fo/build.xml
  • Relative paths in dita.temp.dir are now supported
  • The user's classpath is now properly referenced - the plug-in will now find Saxon even if it is not in dita-ot/demo/fo/saxon.jar
• Improved ditaot/demo/fo/xsl/common/attr-set-reflection.xsl
  • Hardcoded paths are no longer required for built-in attribute sets
  • All functionality of standard attribute sets is now supported, including XSL code within an attribute set
• Created new file called demo/fo/cfg/fo/attrs/basic-settings.xsl which allows the user to easily change basic document settings such as font-size, page-size, and margins
• Changed demo/fo/cfg/fo/layout-masters.xml to layout-masters.xsl
  • Layout-masters.xml has been retained for backwards compatibility
  • Making layout-masters into an XSL file enables the usage of variables for information such as page size
• Supported later versions of DITA by checking if the version is 1.1 or 1.2
• Resolved Bug: 1733878 Idiom plugin requires units to be specified for SVG images by commenting out problematic code in commons.xsl
• **Transtypes for PDF processing have been changed within the DITA-OT**
  • PDF transtype now references FO plug-in code
  • PDF2 transtype still references FO plug-in code but is now deprecated
  • legacypdf transtype references old PDF processing code that was included with the toolkit
  • A notice in the processing output reminds the user that the PDF transtype is now calling the FO plug-in code

• Improve glossary support
  • Grouping of glossary topics
  • Sorting of glossary topics
• Support xml:lang attribute
  • Multiple languages in a document
  • Enable user to specify default font based on value of xml:lang attribute
• Improve ID generation
  • Provide correct ids in the opentopic section for topicrefs/chapters that don’t have hrefs to a .dita document
  • Implement working ids that appear within more than one topic
  • Related bug: 1814935  Duplicate id value in topic.fo
  • Related bug: 2020317   Many duplicated id in xxx_MERGED.xml in PDF2 output.
  • Related bug: 1927400  Valid xrefs, "unresolved internal destination" errors
• Implement unsupported features
  • args.draft
  • flagging based on ditavals
  • toc=no
  • char attribute of an entry element
  • copy-to attribute on related links
• Improved reltable support
  • Document how to enable reltables
  • Ensure that duplicate links don’t appear in the same related links section
  • 1708977  No link titles for related links in PDF  
• Table borders
  • Retain border conditionality by default for tables that break across pages
  • Ensure that the border lines are complete when the table includes merged cells
  • Ensure that cell content is displayed when char attribute is used
• Chunking issues
  • 1897497 chunking to-content reprocesses maps and duplicates content
  • 1897542  Chunk to-content may need to rewrite topic IDs
• Improve customization process
  • Reference customized index files from build.xml
  • Allow customization of a base class which doesn’t override a class specialized from that base class
  • Improve customization process for small changes
  • Remove hardcoded links to out of the box style sheets
  • Improve attribute set reflection calls
• Improve built-in formatting
  • Add labels for prerequisites and post-requisites
  • Move notices to before the TOC
  • Improve chapter numbering
  • Improve spacing
  • Provide default header and footer
• Improve handling of index terms
  • Use hanging indent on index entries that wrap
  • Put “See” and “See also” in italics in see and see also references
• Improve handling for EPS graphics
• FOP specific issues
  • Index does not generate
  • Improve table layout for basic table
• Improve internationalization post-process
  • Add locale parameter to make fonts locale specific
  • Expand override size functionality
  • Provide documentation of the font post-processing functionality
• Display short description in first topic of each chapter in a bookmap

• New elements
  • Text element
  • Navtitle element for topicref
  • Bodydiv
  • Sectiondiv
  • New task type
    • Support new elements in tasks
    • Add titles for each task section
• Existing elements in new places
  • draft-comment