Random thoughts about publishing

Site Feed

Labels

Palimpsest has moved. Please visit our blog in its new location for the most recent posts from Scriptorium.

Palimpsest

 

The long and winding roads from DITA XML to PDF output

Thursday, August 20, 2009 — posted by Sheila Loring

DITA XML is of little use to readers unless it's converted to some kind of output. The DITA Open Toolkit (DITA OT) provides transforms and scripts that convert DITA to PDF output and a long list of other formats.

Producing PDF output from DITA content can be challenging. DITA XML is converted to an XSL-FO file, a combination of content and formatting instructions. You must know XSL-FO to customize the PDF, even just to add simple content such as headers and footers, logos, and so on.

To forgo the programming, you can choose a page layout or help authoring tool, but these tools also have pitfalls. Page layout programs have varying degrees of DITA support. Help authoring tools let you style the PDF through CSS, but you can't fine-tune page layout as you can in page layout programs.

These are just a few examples we discuss in our white paper "Creating PDF files from DITA content." Read the white paper online (in HTML or PDF).

Labels: Arbortext, DITA Open Toolkit, ePublisher, flare, FOP, FrameMaker, PDF, quark, robohelp, white papers, XEP, xmetal, XPP, XSL Formatter, xsl-fo

10:00 AM Permalink | |

 

Learn DITA and XML at your desk

Monday, August 10, 2009 — posted by Sarah O'Keefe

Labels: dita, DITA Open Toolkit, PDF, webcasts, xml

9:02 AM Permalink | |

 

Flare 5 DITA feature review (Part 1: Overview and map files)

Friday, June 12, 2009 — posted by Sarah O'Keefe

[Disclosure: Scriptorium is a Certified Flare Instructor.]
[Full disclosure: We're also an Adobe Authorized Training Center, a JustSystems Services Partner, a founding member of TechComm Alliance, a North Carolina corporation, and a woman-owned business. Dog people outnumber cat people in our office. Can I start my post now?]

These days, most of our work uses XML and/or DITA as foundational technologies. As a result, our interest in help authoring tools such as Flare and RoboHelp has been muted. However, with the release of Flare 5, MadCap has added support for DITA. This review looks at the DITA features in the new product. (If you're looking for a discussion of all the new features, I suggest you wander over to Paul Pehrson's review. You might also read the official MadCap press release.)

The initial coverage reminds me a bit of this:



(My web site stats prove that you people are suckers for video. Also, I highly recommend TubeChop for extracting a portion of a YouTube video.)

Let's take a look at the most important Flare/DITA integration pieces.

New output possibilities
After importing DITA content into Flare, you can publish to any of the output formats that Flare supports. Most important, in my opinion, is the option to publish cross-browser, cross-platform HTML-based help ("web help") because the DITA Open Toolkit does not provide this output. We have created web help systems by customizing the Open Toolkit output, and that approach does make sense in certain situations, but the option to publish through Flare is appealing for several reasons:

• Flare provides a default template for web help output (actually, three of them: WebHelp, WebHelp Plus, and WebHelp AIR)
  
• Customizing Flare output is easier than configuring the Open Toolkit
  

I took some DITA files, opened them in Flare, made some minimal formatting changes, and published to WebHelp. The result is shown here:

Not bad at all for 10 minutes' work. I added the owl logo and scriptorium.com in the header, changed the default font to sans-serif, and made the heading purple. Tweaking CSS in Flare's visual editor is straightforward, and changes automatically cascade (sorry) across all the project files.

Ease of configuration
Flare wins. Next topic. (Don't believe me? Read the DITA Open Toolkit User Guide -- actually, just skim the table of contents.)

Language support
The Open Toolkit wins on volume and for right-to-left languages; Flare wins on easy configuration (I'm detecting a theme here.)

Out of the box, both Flare and the Open Toolkit provide strings (that is, localized output for interface elements such as the "Table of Contents" label) for simplified and traditional Chinese, Danish, Dutch, English, Finnish, French, German, Italian, Japanese, Korean, Norwegian, Portugese, Spanish, Swedish, and Thai (I have omitted variations such as Canadian French).

Beyond that, we have the following:

• Right-to-left language support: Only in the Open Toolkit
• Language strings provided by the Open Toolkit but not by Flare: Arabic, Belarusian, Bulgarian, Catalan, Czech, Greek, Estonian, Hebrew, Croatian, Hungarian, Icelandic, Latvian, Lithuanian, Macedonian, Polish, Romanian, Russian, Slovak, Slovenian, Serbian, Turkish, and Ukrainian
• Ease of adding support for a new language: Flare wins. In the Open Toolkit, you modify an XML file; in Flare, you use the Language Skin Editor (although it looks as though you could choose to modify the resource file directory directly if you really wanted to)
  

Thus, if you need Hebrew or Arabic publishing, you can't use Flare. The Open Toolkit also provides default support for more languages.

Map files
I imported a map file into Flare and published. Then, I changed the map file to include a simple nested ditamap. Here is what I found:

• Flare recognized the map file and the nested map file and built TOC files in Flare with the correct relationships.
• Inexplicably, the nested map file was designated the primary TOC. I speculate that this might be because the nested map file was first in alphabetical order. I changed the parent map file to be the primary TOC to fix this. I don't know what would happen for a more complex set of maps, but I am concerned.
• Flare inserted an extra layer into the output TOC where the nested map is found.
• The titles generated in the TOC are different in Flare than they are through the DITA Open Toolkit (see below).
  

I generated the output for my map file (the nested map is the "The decision to implement" section in this screen shot) through the DITA Open Toolkit and got the following XHTML output:
Then, I imported the same map file into Flare, generated WebHelp, and got the following TOC output:

Notice that:

• The TOC text is different (!!). The DITA Open Toolkit uses the text of the topic titles from inside the topic files. Flare uses the text of the @navtitle attribute in the map file. My topic titles and @navtitles don't match because I created the map file, then changed a bunch of topic titles. The map file didn't keep up with the new titles (because it doesn't matter in the Open Toolkit), but it appears to matter for Flare. The entry in the map file for the first item is:

<topicref href="introduction.xml" navtitle="Introduction" type="topic">

Flare picks up the "Introduction" from the navtitle attribute.

Inside the file, you find:


<title>Executive summary</title>

The Open Toolkit uses the content of the title element from inside the file.


• The Implementation section has added an extra layer in the Flare output. It appears that nesting a map file results in an extra level of hierarchy.

The inconsistency between the two implementations is annoying.

In part 2 of this review (coming soon), I'll look at cross-references, reltables, conrefs, specialization, and conditional processing.

Labels: analysis, dita, DITA Open Toolkit, flare, reviews

10:05 AM Permalink | |

 

DocTrain's demise and a challenge to presenters

Monday, May 18, 2009 — posted by Sarah O'Keefe

Unfortunate news in my inbox this morning:

I regret to announce that DocTrain DITA Indianapolis is cancelled. DocTrain/PUBSNET Inc is shutting down.

As a business owner, messages like this strike fear in my heart. If it could happen to them...gulp. (This might be a good time to mention that we are ALWAYS looking for projects, so send them on over, please.) My condolences to the principals at DocTrain.

Meanwhile, I'm also thinking about what we can do in place of the event. I had a couple of presentations scheduled for DocTrain DITA, and Simon Bate was planning a day-long workshop on DITA Open Toolkit configuration.

So, here's the plan. We are going to offer a couple of webinars based on the sessions we were planning to do at DocTrain DITA:

• Demystifying DITA to PDF Publishing, June 2, 11 a.m. Eastern time (Sarah O'Keefe)
  
• Hacking the DITA Open Toolkit, June 4, 11 a.m. Eastern time (Simon Bate)

Each webinar is $20. We may record the webinars and make the recordings available later, but I'm not making any promises. Registration is limited to 50 people.

Here's the challenge part: If you were scheduled to present at DocTrain DITA (or weren't but have something useful to say), please set up a webcast of your presentation. It would be ultra-cool if we could replicate the event online (I know that the first week in June was cleared on your schedule!), but let's get as much of this content as possible available. If you do not have a way to offer a webinar, let me know, and I'll work with you to host it through Scriptorium.

And here's my challenge to those of you who like to attend conferences: Please consider supporting these online events. If $20 is truly more than you can afford, contact me.

Labels: dita, DITA Open Toolkit, doctrain, PDF, presentations

4:13 PM Permalink | |

 

DITA Open Toolkit: Not quite so scary

Friday, January 30, 2009 — posted by Simon Bate

Last October, I wrote about being scared.  Today, I want to talk about something that seems somewhat scary, but it isn't...or shouldn't be.  It may be daunting, but it's not scary. That "thing" is the DITA Open Toolkit (DITA OT).

Labels: DITA Open Toolkit, hacking

3:31 PM Permalink | |

 

Fixing FOP memory errors

Wednesday, December 17, 2008 — posted by Sarah O'Keefe

Our newest white paper describes how to process large documents with XSL-FO and avoid memory errors. Here's the introduction:

Formatting Object (FO) processors (FOP, in particular) often fail with memory errors when processing very large documents for PDF output. Typically in XSL:FO, the body of a document is contained in a single fo:page-sequence element. When FO documents are converted to PDF output, the FO processor holds an entire fo:page-sequence in memory to perform pagination adjustments over the span of the sequence. Very large page counts can result in memory overflows or Java heap space errors. Reducing page count in a document is not usually an option.

The full white paper is Handling XSL-FO's memory issue with large page counts. Many thanks to David Kelly (writing), Simon Bate (reviewing), Alan Pringle (editing), and Ethan Duty (productioning, er, production).

As always, we welcome your comments here or directly in the white paper pages. If you have ideas for topics you'd like us to cover, we're all ears.

Labels: dita, DITA Open Toolkit, white papers, xsl-fo

10:12 PM Permalink | |

 

An incomplete puzzle: DITA OT stylesheets

Friday, September 05, 2008 — posted by Simon Bate

A recent post on the dita-users Yahoo group asked how to customize the DITA OT stylesheets in view of the fact that there isn't much documentation available.

From my work customizing and otherwise perverting the DITA OT, I can sympathize with these frustrations. When I started investigating OT customizations, I found many well-crafted tutorials on how to customize and specialize the OT.  These were a great starting point, but they only got me so far.  In its current state, the documentation is an incomplete jigsaw puzzle; the trees and buildings are filled in nicely, but the sky is still waiting for someone with patience.  (Block that metaphor!)

Because there is no documentation available at the individual template level, you need to reconsider the task at hand.  I look on it as debugging, decoding, or sleuthing. With that in mind, I find the following to be very useful:

• Find a good visual grep-like utility. I use AgentRansack, a free version of FileLocator Pro (it's free and amazing). This enables me to locate all files that contain a particular class identifier. The visual aspect of the tool allows me to see the context quickly.
• Use a programmer's editor that supports XML and XSL. We use Oxygen. Not only does it help check validity and closes tags automatically, but it also provides a handy sidebar that lists the templates and their modes.
  
• Liberally spread <xsl:comment> or <xsl:message> directives through the stylesheets you're examining. That helps figure out where you are. Use <xsl:value-of> or <xsl:copy-of> to figure out what you've got.
• Once you've figured out what happens in one of the OT templates, add comments. Now the next time you come back to it, you won't waste time.
  

Probably the best form of documentation that the OT could provide here is additional comments in the stylesheets, particularly about the order of processing.  I find I add many comments about where to find the template that handles nodes from an  <xsl:apply-templates> directive.

One further note.  On Tuesday, September 23, I'll be presenting the third of our "Best Practices in Structured Authoring and Publishing" joint Webinar series with JustSystems.  In this presentation I'll describe a number of approaches you can use to customize DITA OT output.  For more information, visit the JustSystems web site.

Labels: DITA Open Toolkit, specialization, xsl

10:12 AM Permalink | |

© 2009, Scriptorium Publishing Services. Legal Stuff