39
Extracting deliverables from DITA Sarah O'Keefe Scriptorium Publishing

Extracting deliverables from DITA

Embed Size (px)

Citation preview

Page 1: Extracting deliverables from DITA

Extracting deliverablesfrom DITA

Sarah O'KeefeScriptorium Publishing

Page 2: Extracting deliverables from DITA

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.

Page 3: Extracting deliverables from DITA

Poll: What is your DITA status?

Page 4: Extracting deliverables from DITA

DITA deliverable categories

HTMLPDFCustom output

Flickr: freewine

Page 5: Extracting deliverables from DITA

HTML output options

DITA Open ToolkitVarious help authoring/conversion tools

FlareRoboHelpePublisher ProDITA2GO

Page 6: Extracting deliverables from DITA

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

Page 7: Extracting deliverables from DITA

Help authoring tools

Set up template/configurationImport DITA content(optionally) Make changes in the help authoring toolPublish to HTML

Page 8: Extracting deliverables from DITA

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?

Page 9: Extracting deliverables from DITA

The DITA Open Toolkit is the best choice for HTML.

Light customization with CSSIn-depth customization with XSLNo arbitrary formattingComplete automation

Flickr: bobistraveling

Page 10: Extracting deliverables from DITA

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

Page 11: Extracting deliverables from DITA

PDF options

DITA Open ToolkitPage layout applicationsOthers

Flickr: freewine

Page 12: Extracting deliverables from DITA

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.

Page 13: Extracting deliverables from DITA

Poll: The five stages of DITA-based PDF publishing

What's your stage?

Page 14: Extracting deliverables from DITA

Please choose one of the following terrifying options:

DITA Open ToolkitPage-based layout tool

FrameMakerInDesignQuark

Help authoring/conversion toolRoboHelpePublisher ProFlare

Page 15: Extracting deliverables from DITA

PDF through the DITA Open Toolkit

Very difficult to configureNo “tweaking” to fix copyfitting problemsAlmost certainly the long-term winner

Page 16: Extracting deliverables from DITA

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

Page 17: Extracting deliverables from DITA

DITA Open Toolkit challenges

FontsFormattingFoggy FOFOP foibles

Page 18: Extracting deliverables from DITA

PDF via FrameMaker

Configuration, at a minimum, requires modifying a formatting templateNice PDFCan tweak to adjust pagination

Page 19: Extracting deliverables from DITA

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

Page 20: Extracting deliverables from DITA

FrameMaker pitfalls

Sensitive to whitespaceDITA specializationsRound-trippingAuthoring

Page 21: Extracting deliverables from DITA

FrameMaker recommendations

Use DITA-FMx plug-in

Page 22: Extracting deliverables from DITA

PDF via InDesign

Beautiful typographyCan tweak to adjust paginationNo default support for DITAExtensive configuration requiredWhitespace in XML results in anaphylactic shock for InDesign

Page 23: Extracting deliverables from DITA

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

Page 24: Extracting deliverables from DITA

DITA to InDesign challenges

Extensive preprocessingRound-trippingAuthoringWhite space

Page 25: Extracting deliverables from DITA

What about the help authoring tools?

Yes, if you need cross-browser, cross-platform help.Not the best choice for PDF only.

Page 26: Extracting deliverables from DITA

What are your PDF priorities?

For typography, choose InDesign or similar.For automation, choose the DITA Open Toolkit.For a middle ground, choose FrameMaker.

Page 27: Extracting deliverables from DITA

Lower your standards.

Does your audience care about fine typography?Less copyfitting = greater automation

Page 28: Extracting deliverables from DITA

Factors to consider for PDF output

Platform requirementsTechnical resourcesTypography requirementsVelocityVolumeVersioning

Page 29: Extracting deliverables from DITA

Poll: How are you creating (or planning to create) PDF output?

Page 30: Extracting deliverables from DITA
Page 31: Extracting deliverables from DITA

DITA Open Toolkit PDF is not necessarily ugly.

It just starts out that way.Making it pretty is a lot of work.

Page 32: Extracting deliverables from DITA

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

Page 33: Extracting deliverables from DITA

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

Page 34: Extracting deliverables from DITA

Automation has advantages

Incremental builds (nightly updates)Zero manual formattingExcellent localization support in DITA Open Toolkit

Page 35: Extracting deliverables from DITA

Automation has disadvantages

Initial configuration effortNo intermediate file for last-ditch copyfitting or content changesNo book-by-book customization

Page 36: Extracting deliverables from DITA

Overall recommendation for HTML

Use the DITA Open ToolkitAutomation is more valuable than ability to finagle

Page 37: Extracting deliverables from DITA

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?

Page 38: Extracting deliverables from DITA

Questions? Comments?

Page 39: Extracting deliverables from DITA

Contact information

Sarah O'[email protected]: +919 459 5362Twitter: @sarahokeefe