Download - Extracting deliverables from DITA
Extracting deliverablesfrom DITA
Sarah O'KeefeScriptorium Publishing
Preliminary notes
You should be hearing the presenter's audio at this point.All participants are muted.Use the Questions tab in the GoToWebinar control panel to ask questions anytime during the session.The webcast is being recorded. No participant information appears in the recording.The Q&A period at the end of the event will not be recorded.
Poll: What is your DITA status?
DITA deliverable categories
HTMLPDFCustom output
Flickr: freewine
HTML output options
DITA Open ToolkitVarious help authoring/conversion tools
FlareRoboHelpePublisher ProDITA2GO
DITA Open Toolkit process
Install the DITA Open Toolkit (!)JavaAntXSL processorXSL-FO processor (for PDF)Possibly other bits and pieces
Modify component files to get the output you wantGenerate output from the command line
Help authoring tools
Set up template/configurationImport DITA content(optionally) Make changes in the help authoring toolPublish to HTML
About those last-minute changes…
The traditional authoring/publishing model allows them.The automated publishing model eliminates them.The transition to the “no tweaking” mindset can be painful.What are the costs and benefits?
The DITA Open Toolkit is the best choice for HTML.
Light customization with CSSIn-depth customization with XSLNo arbitrary formattingComplete automation
Flickr: bobistraveling
The special case: WebHelp
WebHelp = HTML-based help system with tripane interface (content, index, search)No support in DITA Open Toolkit (custom build of tripane interface required)Commercial support via XMetaL, Flare, Trisoft, ePublisher Pro, DITA2GO, and perhaps othersBalance DITA Open Toolkit customization effort against license costs
PDF options
DITA Open ToolkitPage layout applicationsOthers
Flickr: freewine
PDF publishing is hard because:
Printed page layouts have more options than HTML layouts.Extensible Stylesheet Language Formatting Objects (XSL-FO) needs to support sophisticated page layout options.Pushing XML into page layout tools is challenging.Automation means giving up page-by-page formatting.
Poll: The five stages of DITA-based PDF publishing
What's your stage?
Please choose one of the following terrifying options:
DITA Open ToolkitPage-based layout tool
FrameMakerInDesignQuark
Help authoring/conversion toolRoboHelpePublisher ProFlare
PDF through the DITA Open Toolkit
Very difficult to configureNo “tweaking” to fix copyfitting problemsAlmost certainly the long-term winner
DITA Open Toolkit process
Customize default PDF output to your requirements (once)Make fonts available to FO processor (once)Run Ant command to generate PDF
DITA Open Toolkit challenges
FontsFormattingFoggy FOFOP foibles
PDF via FrameMaker
Configuration, at a minimum, requires modifying a formatting templateNice PDFCan tweak to adjust pagination
FrameMaker process
Modify the template to meet your requirements (once)Manage white space (tabs, newlines) (once)Open the map file(v8 and earlier) Generate intermediate bookSave as PDF
FrameMaker pitfalls
Sensitive to whitespaceDITA specializationsRound-trippingAuthoring
FrameMaker recommendations
Use DITA-FMx plug-in
PDF via InDesign
Beautiful typographyCan tweak to adjust paginationNo default support for DITAExtensive configuration requiredWhitespace in XML results in anaphylactic shock for InDesign
InDesign process
Transform DITA content into “InDesign-friendly” XML via XSLT (once)
Flatten map filesResolve and flatten content references (conrefs)Modify structure of images and tablesControl whitespaceDo something about xrefs with InDesign scripts
Set up template in InDesign (once)Import modified XML into InDesign
DITA to InDesign challenges
Extensive preprocessingRound-trippingAuthoringWhite space
What about the help authoring tools?
Yes, if you need cross-browser, cross-platform help.Not the best choice for PDF only.
What are your PDF priorities?
For typography, choose InDesign or similar.For automation, choose the DITA Open Toolkit.For a middle ground, choose FrameMaker.
Lower your standards.
Does your audience care about fine typography?Less copyfitting = greater automation
Factors to consider for PDF output
Platform requirementsTechnical resourcesTypography requirementsVelocityVolumeVersioning
Poll: How are you creating (or planning to create) PDF output?
DITA Open Toolkit PDF is not necessarily ugly.
It just starts out that way.Making it pretty is a lot of work.
Custom output examples
Your own implementation of web-based helpMan pages and other custom markupBuilding to an existing formatting specificationCustom markup, such as IDML, XPS, or MIF
Flickr: markdevries
XSL programming skill is an issue
In-house resourcesContractors or consultants?Technical skills required are beyond “typical” FrameMaker templates, HTML coding, and CSS
Flickr: jinxmcc
Automation has advantages
Incremental builds (nightly updates)Zero manual formattingExcellent localization support in DITA Open Toolkit
Automation has disadvantages
Initial configuration effortNo intermediate file for last-ditch copyfitting or content changesNo book-by-book customization
Overall recommendation for HTML
Use the DITA Open ToolkitAutomation is more valuable than ability to finagle
Overall recommendation for PDF
Weigh the benefits of automation against the difficulty of implementing XSL-FORemember that localization support in DITA OT is excellent (and extensive)Consider the value of existing assets (FrameMaker or InDesign templates)How strict are your output requirements? How strict do they need to be?
Questions? Comments?
Contact information
Sarah O'[email protected]: +919 459 5362Twitter: @sarahokeefe