Tag: DITA-OT

Meeting: Introduction to XSL-FO and the DITA-OT

Simon Bate, Senior Technical Consultant at Scriptorium was in town teaching a class on DITA and we were lucky to have him come and share tips and information on XSL-FO and the DITA-OT. The large crowd in house as well as a good number of remote attendees kept him busy with questions. Based on the feedback I’ve received, everyone left with some good information.

Simon started with an overview of XSL-FO, discussing the basic concepts as well as its strengths and weaknesses. He then explained how to develop a “plugin for the plugin” to allow you to easily (well, that may depend) create customizations to the DITA-OT PDF2 plugin.

If you took notes or have some comments, please feel free to add them to this page!

2012-08-FO-for-SVDIG.pdf – Simon’s presentation slides.

Thanks Simon!

Meeting: Roundtable discussion – Using the DITA-OT

As is frequently the case, our round table discussions are often the best meetings! This one was well attended with local and remote participants.

We had a lively discussion about how the DITA-OT is used in various companies and under different conditions. Lots of questions and clarifications about what the OT is and how it can be used.

Meeting: Round table discussion – importing DITA into InDesign

We had an interesting discussion dealing with how to best import DITA files into InDesign (specifically CS4 and CS5). It was a very hands-on meeting, with a real-world project as the test bed.

Like most DITA-type projects the important thing is the preparation. Importing the actual DITA files is as simple as File > Import XML, and then dragging and dropping elements onto the artboard.

Create Paragraph tags to match your DITA tags and use Structure’s Map Tags to Styles to create a table that brings in the formatting easily. To modify the text, just edit the paragraph style.

When adding multiple DITA files, use Append when adding to an existing flow (good for columnar text) and use Merge when creating a new flow (good for individual text boxes).

Notes provided by Joanne Grey

Meeting: Round table discussions — conversions, output, and authoring

We had a very lively and energetic discussion of various topics. I’ve organized them into three main groups below.

TOPIC 1: Converting unstructured content into DITA

Before conversion:

  • Perform document analysis; better to spend more time on this than not enough
  • FM – look into using the Remove All Overrides command to clean up files
  • Prototype project should not be the first book you want to convert. This should contain bits that represent all possible structures and components in your documentation set. Test and perfect the conversion, then test and prototype the various output options you plan to use.

Conversion processes/tips:

  • Use Mif2Go convert to DITA – export to Mif, then set up mif2Go config file to set up elements, wrapping syntax for Mif2Go, etc.
  • Use FM Conversion table to map styles to elements, wrap elements into other elements, etc.
  • Create a base topic for each section (Parse on Heading 2 or Chapter) to get files into DITA
  • Conditional text boundaries need to map to to element boundaries. This is applied as attributes on those elements. It’s often better to rewrite heavily conditionalized content into multiple paragraphs so you can apply conditions at the paragraph level.
  • Frame’s conversion tables don’t map conditions. Any tools that do?
  • Variables can become conrefs or just make them into plain text.
  • Remove inline cross-refs and create relationship tables.
  • The DITA 1.1 bookmap provides nodes for book-like structures like chapters, appendixes, and lists (TOC, index, etc.).
  • If using Frame for PDF output, your TOC and index can be FM generated, otherwise they are generated by the tool (OT, or ?).
  • If in doubt, shred your content to be more granular. It’s easier to merge multiple topics together than break them apart later. Don’t use “sections” if you can help it, they can probably be topics.

Best practices?

  1. Think about why you want to convert – based on current content, maybe only convert tasks, or other topics that are truly concepts or reference.
  2. How much material – manual or automated conversion
  3. How often you will convert – 1 time, or often
  4. Source material is in-house or external, both?
  5. How well or poorly structured
  6. Do a good doc analysis – go through doc set and see how well formed they are try to capture all use cases, what is in the docs? What do the styles mean?
  7. Too few or too many steps in conversion process – a step may have too much transformation , try small steps with iontermediate results to try out
  8. Prepare documents for DITA (to be good DITA) before conversion.

TOPIC 2: Options for generating output from DITA

  • The OT provides scripts for generating, CHM, HTML, Eclipse Help, Java Help, PDF, and more.
  • Basic output is not too hard, but styling/formatting can be very difficult for non-techie people.
  • Suite Solutions offers great training for the OT if you want to learn how to maintain things yourself.
  • CSS can be a simple way to customize OT output.

Options other than the OT:

  • DITA2Go can be a replacement for the OT; from makers of Mif2Go
  • RoboHelp
  • Flare
  • XMetaL comes with OT bundled so it may be easier
  • CHM to Web – generate HTML HELP from the OT and then use a template to convert to WebHelp
  • FrameMaker can be the easiest way to generate PDFs from DITA even if you’re not using FM for authoring.
  • DITA-FMx provides extended PDF/book publishing features.

TOPIC 3: Authoring tips and ideas

  • Author Assistant from SDL – Grammar Checker requires tweaking (free download for FrameMaker 9)
  • Capture “what do I do now” moments – what do you do when something does not fit the model. Good to review later and share with others.
  • See Megan’s SVDIG presentation on creating Supertasks (tasks with links to subtasks)
  • Indexterms in prolog, become meta keywords; this is good for HTML. Indexterms inline are good for PDF/print. Decide which is more important. Once you move indexterms into prolog it’s hard to get them back inline; investigate tweaking XSL to copy inline indexterms to prolog for both purposes.
  • DITA-FMx and Oxygen provide element sensitive online Help for DITA documents. Makes it easy to learn how things fit together.

» Thanks to Lauren Katzive for taking notes!

Meeting: Implementing DITA: Production Notes from a Real-World DITA Open Toolkit Project

Topic: Implementing DITA: Production Notes from a Real-World DITA Open Toolkit Project

Speakers: Anna van Raaphorst, Content Specialist and Richard (Dick) Johnson, Technology Specialist at VR Communications, Inc., consultancy for multichannel communications solutions.

Presentation materials: ImplementingDITA.pdf [139KB]