Your DITA implementation is under way, and promises higher content reusability with shorter time to publication. A key aspect of your implementation is automated multi-channel publishing of your content to a variety of outputs: PDF, HTML, online help, mobile, dynamic web, eLearning and more. In this webinar, expert project manager Yehudit Lindblom and Suite Solutions President Joe Gelb go beyond formatting requirements to review best practices that help you cover all the bases for smooth implementation and easy maintenance of your dynamic publishing customizations. Learn more about DITA Quick Start http://www.suite-sol.com/pages/solutions/dita-quick-start.html Follow us on LinkedIn http://www.linkedin.com/company/527916

1. DITA Quick Start:
Defining Style Sheet Requirements
Yehudit Lindblom & Joe Gelb
January 21, 2014

2. Who are we?
Yehudit Lindblom
• Project Manager and cat herder
Joe Gelb
• Founder and President of Suite Solutions
Suite Solutions
Our Vision: Enable you to engage your customers by providing quick access to
relevant information: DITA provides the foundation
• Help companies get it right the first time
• XML-based Authoring/Publishing Solutions
• Enterprise Intelligent Dynamic Content: SuiteShare Social KB
• Consultancy, Systems Integration, Application Development
• Cross-Industry Expertise
• High Tech, Aerospace & Defense, Discrete Manufacturing
• Healthcare, Government

3. Main Topics
 Goals of this webinar
 The Magic Button: high quality, localized output from DITA
 Common Requirements
 PDF
 HTML
 Online Help
 ePUB
 Mobile
 Localization Considerations

4. Goals of this Webinar
Primary Goal: Empower (not overwhelm) you
• Understand the process, details and dependencies involved
• Understand the possibilities
• Help to avoid making assumptions…
• Manage expectations

5. Key Components of a DITA Solution
1.
2.
3.
4.
5.
Staff
Content
Translation
Publishing
Content and configuration management
Your mission is to develop or acquire each of these

6. The Magic Button
•
•
Common misconceptions about DITA
• DITA publishing can't match the quality and complexity of desktop
publishing
• Loss of control over the final output as with tools like FM and InDesign
[ those last minute tweaks, page-breaks…. ]
The reality
• Anything we’ve seen can be done using DITA publishing
• Style sheets can be customized, parameterized, localized
• CMS + style sheets gives you the Magic Button: any format in any
language for any device
• Well…. Not so easy at first: takes effort
to set it all up

7. Multi-purpose Publishing
•
•
Single-source, many outputs
• PDF: hi-fidelity vs online, manuals, data sheets, fold-outs, labels…
• Help: CHM, Web Help, HTML5, website, KB, man pages …
• Mobile: ePUB, Mobi, Nook, feeding native apps, responsive design…
• InDesign
• Word
• Integrations with other systems: Salesforce, Jive…
Dynamic Web Publishing: content on-demand

8. Content, Structure, Presentation
• Document Type Definition (DTD)
• Schema
Structure
Rules
Document
Instance
• XML
• Media, graphics
Presentation
Rules
(Style Sheet)
Presentation
•
•
•
•
XSL
XSL-FO
CSS
Shakespearean
Templates
•
•
•
•
•
•
•
PDF
HTML
ePUB
DOCX
InDesign
SVG
…

9. Typical DITA Toolset
XML Authoring
SME Review
CMS
Content Management
System
Automated Publishing
- DITA Open Toolkit
- DITA Accelerator
Web Help
Dynamic Web
- SuiteShare
- LiveContent Reach
- DITA Web
- Fluid Topics
Help Manuals
Mobile
On-demand

10. High Level Process
1. Assembling your project team
• Project manager, at least one author, and perhaps a graphic designer
(and they all might be the same person)
2. Building requirements
• Which outputs do you have now? What do you want to add or change?
• Opportunity to implement new formats your customers are asking for
3. Information Architecture
• How are your DITA elements being used?
• What output do you want from them?
4. Solution Architecture: CMS, publishing tools
5. Style sheet development
6. Deployment
7. Support / Tweaks

11. Be Prepared
•
•
•
•
•
Your project team will need to make nitty-gritty detailed decisions about
requirements and priorities
It is important to set as many requirements as possible before the
development starts
• Avoids scheduling or budget surprises, cost overruns
Identify detailed formatting requirements for each output format:
• PDF, HTML, help, mobile, dynamic web, eLearning…
Coordinate with the information architect and conversion team
Communicate clear and detailed formatting requirements to your vendor

12. Be Prepared
•
•
•
Have all the fonts available before start
Test Data
• Invest the time to put together good representative test data
• Should be based on your IA
• Simulate each combination of tagging and structure
• Test data should be representative of actual XML exported from the
CMS during publishing
Build time for review into your schedule
• You need to review your new outputs thoroughly
• Better to be realistic and allot more time than to do a quick review and
miss issues

13. Testing and Revisions
•
•
•
•
Job isn’t finished until you can publish real content from the CMS
• Ideally, even for beta testing, publish converted content from
the CMS
Localized style sheets cannot be completed until tested with real
translated content
Leave room in your budget for tweaking the style sheets
As you migrate more content, you will encounter new patterns in
the tagging
• Style sheets are very sensitive to differences in tagging,
especially for PDF
• Page-break rules are sometimes complex and may be tweaked
over time

14. Basic Requirements for all outputs
•
•
Content-based rules, for example:
• Task steps: if only 1 step, style as a paragraph; if >1, style as
list
• Reordering pre-requisite and context (use general task type
instead)
Basic formatting: fonts, colors, sizes, spacing…
Reality Check:
• Before you start development, the basic formatting should be
decided
• “This is how it will be, mostly, so you can go ahead and get started”
is an invitation for Murphy and a recipe for wasted time and budget
• For many of the requirements we will discuss, details can be
resolved during the development process, but make sure to
account for them in scheduling and budget

15. Common Requirements for PDF
•
•
•
•
High fidelity (for print) and online version
Turn on or off
• TOC, Index, mini-TOC
• Draft comments, crop marks, watermark, change markup…
Variable sized documents and fold-outs
• Letter, A4, custom sizes (fitting it in the box…), base on locale
• Custom sizes meant for folding with exact spacing requirements
Variable page size and orientation
• Displaying a single topic / page / table / figure in landscape or
different page size – e.g. fold-outs, large diagrams

16. Common Requirements for PDF
•
•
Custom cover and back pages
• Custom cover graphic
• Title, alternate titles
• Serial number, publication date, revision number, etc.
• Copyright information
• Contact information, addresses,
• Generally driven using metadata, outputclasses
Automated watermarks
• Example: generate based on metadata combined with current date
• Webinar: Suite Labs: Adding a Watermark to your PDF Output
https://www.youtube.com/watch?v=tL6PFDVItEQ

17. Common Requirements for PDF
•
•
•
•
Page breaks and keep-with-next
• Tends to irritate people the most: folks are used to tweaking manually
• Complexity: elements that span multiple pages
• Can build logic in the style sheets approximating the thought process
of a real person adding manual page breaks
• Can support adding break instructions manually in the source DITA
• Does not work properly in Apache FOP
Table footnotes – appear after the table instead of bottom of page
Flagging – based on conditionalization
Change tracking
• Via the authoring tool
• Via the review tool
• Comparison between 2 document revisions

18. Other PDF Requirements
•
•
•
•
•
Bar codes and QR codes – generate automatically using AH extension
Section 508 compliance
• Enable PDF to be read by a screen reader
• AntennaHouse extension adds attributes to the PDF for elements such
as links
Show tags in the output for review
Links between documents – instructor and participant guides
MathML for equations
• Render in PDF using AntennaHouse extension
• Render into HTML by automatically generating graphics
• Webinar: Implementing MathML with DITA XML
https://www.youtube.com/watch?v=fnlZcIwJeMw

19. PDF Rendering Tool
•
•
•
Choose tool that will support all your requirements
• Antenna House
• RenderX
• Apache FOP
If need basic output: Apache FOP will be OK
• Not supported well: Orphan/widow rules, page breaks
Antenna House
• Support for EPS (with GhostScript)
• Other extensions available (MathML, barcodes, etc.)
• Excellent localization support
• Tools for Japanese index sort, regression testing

20. Considerations for Localization
Support for localized outputs
• Localization is generally supported with the DITA-OT
• Multilingual documents not supported out-of-the-box but can be done
• When done right: use one style sheet for all languages
Customization
• Font usage
• Varies according to the character set
• Automate right-to-left vs left-to-right (header, footer, cover, margins…)
• Formatting
• Use alternatives for emphasizing text in languages that do not use
italics, bold or quotes as used in most other languages, for example:
 「Japanese italicized text」
 «Chinese italicized text »
 “Chinese bolded text ”
• Display Japanese dates in the format: 2013 年 8 月 13 日

21. Considerations for Localization
•
•
•
Variable strings
• Text that is static throughout the content but vary per language
Examples: “Warning” “Table of Contents”
• DITA-OT already defines most commonly used strings
• Often need to add new strings for copyright, address, special
headings, etc.
Index and glossary sort: Chinese and Japanese do not sort
alphabetically – there are 2 options:
• Use <index-sort-as> and <gloss-sort-as> to manually specify sort
and group orders
• Use AntennaHouse sort module which automates the sort
Page size
• Specify based on locale
• Affects placement of headers/footers, margins, front/back covers

22. Considerations for Graphics and Media
•
•
•
•
Support for high-res graphics and EPS
• EPS supported by AntennaHouse + GhostScript
Automated conversion during publishing from EPS to other formats
(e.g. PNG) for use with HTML
Whether to use SVG
• XML format; often used for graphics with call-outs
• Easier to localize – with some caveats…
• Allows you to change the text inside the graphic during publish time
• Can automatically convert to other formats (e.g. PNG)
Embedded links to video

23. Considerations for Graphics and Media
•
•
Sizing for HTML
• Automatically generate smaller graphics OR rely on CSS
• If use CSS, the sizing is controlled by the browser; sometimes less
quality
Display thumbnails
• When clicked, display a large rendition as an overlay
• Good for large figures or charts

24. General Requirements for HTML
•
•
•
•
•
•
Formatting: fonts, sizes, spacing…
Figure and Tables
• Numbering: “for print” scheme is not the default for HTML
Numbering generally makes sense per topic
Generally we recommend to turn off numbering; only display the
title
• Titles: display above or below
• Cells to span
• First row color
Flagging based on conditionalization
Draft comments: format, view on-demand
Embed Google analytics code
“Mark of the web” – still an issue for older Windows and IE

25. General Considerations for HTML
HTML5
•
•
•
•
•
•
Latest buzzword…
Current browsers are not fully supporting HTML5; consider implementing
fallback options where there are differences in support
Decide which HTML5 features you would like, check they are supported in the
required browsers, and TEST!!!
Semantic elements: article, header, footer, section, aside, nav, figure,
figurecaption, details
Video
• not supported by some browsers
• still generally requires support for Javascript APIs for embedding controls
• Consider the video encoding and how supported in browsers
E.g. Chrome, Firefox, Opera all support WebM.
Safari and IE only support h264 (recommended)
Microdata attributes: @itemscope, @itemprop – used for search weighting

26. General Considerations for HTML
Section 508 Compliance
•
•
•
•
•
Accessibility to people with disabilities
Facilitates more effective reading for computerized screen-readers
List of regulations: http://accessibility.psu.edu/section508
Examples
• @alt for images need to be populated – generally, comes from the
source XML content, some automatically populated using style
sheets (e.g. logos, note icons)
• Web pages shall be designed so that all information conveyed with
color is also available without color. Supplement color coding with
other signals such as shape or text
HTML5 compliance with Section 508
• Section 508 has not been updated to correspond with HTML5
• Example: Section 508 requires a <summary> tag, which is
deprecated in HTML5

27. Choosing an Online Help Platform
Platforms available:
• HTML Help (CHM) – not recommended:
• Only works on Windows client, not cross-platform or server-enabled
• Very little customization possible
• No longer supported by Microsoft
• Does not support modern CSS, which means you cannot share
style sheets between help systems
• SuiteHelp
• oXygen
• Webworks
• Flare
• Robohelp
• Eclipse

28. Choosing an Online Help Platform:
Considerations
•
•
•
•
•
Browser support
• Big 4: IE, Firefox, Chrome, Safari
• IE: difficult to support older version without many work-arounds
Support for different operating systems: Windows, Mac, Linux
Should not be based on frames
• Deprecated in HTML5
• Causes security problems on many browsers
• Slow
• Not mobile friendly
Context sensitivity
Quality of search
• Javascript-based vs. server-based
• Server-based can provide true phrase search, morphology/fuzzy, etc.
• Search highlighting, snippets

29. Customizations for Online Help
•
•
•
•
•
TOC images, how to highlight when selected
Index: yes or no
Glossary: yes or no
• Alphabetization can be automated, but grouping is more difficult to
implement
Links: which to generate
• Parent links
• Child links
• Next/previous
• Related links, and whether to group them by topic-type
Breadcrumbs

30. Customizations for Online Help
•
•
•
•
•
•
Print
• Current topic
• Current topic and all child topics
• All topics in help
Email link to the current topic
Link to a PDF version of the manual
Re-sizable navigation pane
Custom Footer
Custom home page

31. General Requirements for ePUB
•
•
•
•
•
Formatting: much more limited than on other formats; many quirks
Challenge: ePUB is generated using HTML, but is presented like a book
Topic chunking: which topics should be rendered and flow together: often
this is different than for HTML-based help
Cover page
Which ePUB readers to support?
• Different readers on different mobile platforms differ widely in their
support for CSS
• Kindle is a different format: mobi
Reality Check
• You must test the output on each of the devices and readers that
you want to support
• There are common readers, such as Aldiko

32. General Requirements for Mobile
•
•
•
•
Responsive vs adaptive design
• Responsive: the help automatically refits itself using CSS media
queries and grids to optimize the usability for different device sizes
• Adaptive: the help is designed for a particular range of sizes
Considerations:
• Which device sizes?
• Which OS?
• HTML5-based vs native app
TOC navigation
• Generally only shows the top level
• Navigate to lower levels through links on the topic pages
jQuery Mobile reponsive UI system is commonly used
• Supports different sizes well without concern for media queries and
grids

33. General Requirements for Mobile
•
•
•
•
Gestures
• swipe, pinch, zoom/pan graphics
Search
• Since the help is commonly hosted on a web server, it is easier to
implement a more powerful search engine such as SuiteHelp+
Embedding videos
• Embedded links to YouTube
Media
• Not all media types supported out of the box
• Some require special processing
e.g. swf needs an HTML <object> element

34. Documenting the Style Sheets
Now that we have all these customizations, how do authors use them?
Document the style sheets
• Outputclasses
• Parameters
• Metadata usage for the publication

35. Pushing the Envelope…
Some advanced use cases
1.
2.
3.
4.
List of Effective Pages
Multilingual foldouts
Modifying graphics during runtime using SVG
Automated re-branding online help based on metadata using SuiteHelp

36. Case Study: Modifying graphics during
runtime using SVG
1. Icon graphic for standards commission needs to have
the serial number embedded depending on the
geographical location of sale
2. During publishing, serial number is inserted into the
SVG from metadata
3. The Catch: Icons need to flow on back cover from
bottom right to left, then up…
4. Solution:
Rotate the entire back page 180 degrees, so can flow
from top left to bottom right…. the graphic file needs
to start upside-down

37. Automated Re-Branding online help using
SuiteHelp

38. Automated Re-Branding online help using
SuiteHelp

39. Next Level: Dynamic Web
•
•
•
•
•
Variety of content: documentation, videos, how-to articles, safety
information, data sheets, marketing material
Context filtering: goal-oriented filtering to contextually relevant content
Personalized docs: allow readers to assemble content on demand and
render to PDF for print and ePub for offline mobile access
Audience Participation: allow your audience to add new content,
comment on existing content, express approval, and easily share
knowledge with others
Modern User Experience: smooth transition between mobile and
desktop
• Activity often starts on mobile,
moves to desktop, returns to mobile
• Internet connection not always available

40. Keep in Touch! Let us know how we can
help you.
For additional information, contact:
Yehudit Lindblom
Joe Gelb
solutions@suite-sol.com
U.S. Office
(609) 360-0650
EMEA Office
+972-2-993-8054
www.suite-sol.com
Follow us on Linked-In
http://www.linkedin.com/company/527916