by David Kelly
Adoption of DITA involves a fair number of hurdles, not the least of which is getting nicely formatted output. Two kinds of output in particular present problems: tripane web help, because it is not provided in the DITA OT, and PDF, because the plugin is difficult to modify. My esteemed colleague, Simon Bate, has addressed the tripane help issue, so you can look forward to a blog post from him on that subject.
For this post, I am happy to announce that Scriptorium has developed an enhanced version of the DITA OT’s PDF plugin, providing an upgraded baseline for additional development. As I mentioned in a previous post, the PDF plugin is a good place to start, but an ugly place to stop. So we decided the least we could do was to make it a prettier place to start.
That same post also outlined a number of ways to modify the DITA OT. In writing about a few of the simpler things that can be done (and need to be done!) with the PDF plugin, we realized that XSL-FO and the PDF plugin are just difficult to deal with, in general. So we thought an upgraded PDF plugin might reduce the pain of starting with DITA.
Another reason for the makeover is that after helping numerous customers modify the DITA OT’s PDF output so it conformed to their standards, we found that there are many common requirements from customer to customer. Sufficient repetition of custom requirements eventually points to a new set of generic requirements.
We have also learned that the DITA OT “out of the box” contains of number of characteristics that need to be “fixed” every time we modify it. The absence of indexing when using the FOP processor is one such deficiency. (It’s no fault of the PDF plugin developers, however. FOP does not support some of the XSL-FO standard elements for index processing.) Another oddity is that when processing with FOP, table text margins inherit the current context’s left margin setting by default. With a few items like that, the PDF output could use a fair amount of “sprucing up” to be presentable. (Shades of Eliza Doolittle!)
Here are a few of the items that we have modified:
- Added simple indexing support for FOP.
- Modified handling of frontmatter to give the author control over the order of frontmatter sections.
- Enhanced the headers and footers. Various aspects of the content and format can now be controlled with variables in basic-settings.xsl. Chapter and appendix labels and numbers can be added or omitted with a single control.
- Modified the first pages for preface, notice, glossary, and index so their formatting is consistent with chapters and appendices.
- Enhanced the font specification and various other format settings so they can be controlled in basic-settings.xsl. Monospace fonts now have a different font size control than other font types.
- Stacked the MiniTOCs on top of body text rather than presenting it side by side. Side-by-side formatting presented issues when the top-level topic contained a body with text longer than a page.
- Removed rules from titles to make them a more generic starting point for format changes.
- Added support for the “expanse” attribute for figures.
- Modified page-master formatting so offset margins can be controlled with two variables in basic-settings.xsl.
- Added folio numbering for figures and tables when they are numbered on a per-chapter basis.
- Provided system date functions to make it easy to insert a system date into headers, footers, or cover pages, as needed.
- Modified index formatting to provide better control of keeps between primary and secondary entries.
- Added control for the index entry indent size in basic-settings.xsl.
- Enhanced the table of contents to provide formatting control from basic-settings.xsl; also modified alignment of numbers to prevent “wobble” in the stacking of the numbers.
The list includes a fair number of other minor enhancements. We have also developed documentation for the new controls and modified treatments. From what we have seen, publishers of technical documentation usually want some or all of these features when they get ready to publish their DITA source. We hope that this new version of the PDF plugin provides a more manageable entry point to DITA PDF publishing. If you are interested in learning more about the modifications, or have specific requirements that I haven’t mentioned here, give us a shout. (Or, if you aren’t within a couple of hundred yards, an email, comment, or phone call will work just fine.)
And lastly, not to neglect the entertainment tradition of this fine blog, let me illustrate with another successful makeover (and yes, by George, she’s got it!):