Slides from DocTrain East 2008 Workshop: Introduction to XMetaL and DITA.

1. Introduction to
DITA and XMetaL
Simon Bate
Scriptorium Publishing
Services

2. Course Agenda
Overview of XMetaL Sections and nested
Elements and topics
structured authoring Cross-references
Generating output Metadata and
Attributes indexes
Images Track changes
Tables DITA maps
Writing topics Reusing content

3. Course purpose
Learn how to author content using XMetaL
Author Enterprise Edition
Understand DITA
Put theory into practice, learn by doing

4. About DITA
Darwin Information Typing Architecture
Created at IBM
Now developed and maintained by OASIS
Standard XML language
Cost-effective way to create, publish, reuse,
and exchange structured content

5. Role of DITA Tools
An authoring tool is a user interface for creating
DITA content

6. DITA documentation
DITA Language Reference
Purpose and content model for each element
Help > DITA Specifications > DITA Language
Reference
DITA Architectural Specification
Describes overall behavior of DITA
Very technical
Help > DITA Specifications > DITA Architectural
Specification

7. Overview of XMetaL

8. XMetaL Author
Standard word-processing environment
Multiple undo (and redo)
Spell checking & thesaurus
Change tracking
Create and edit text
Familiar editing features to create content

9. XMetaL Author Interface: Overview
Menu
Tool bar
Structure
View
View Mode Document Element
buttons Pane List

10. Inserting symbols and special
characters
Insert > Symbols
Insert > Special Characters
Or click View > Toolbars,
Then toggle appropriate checkboxes

11. Typographical elements
Bold
Italic
Underline

12. View modes
Four view modes for the document pane:
Normal
Page Preview
Tags On
Plain Text
Controls in bottom left corner of the pane:
Indicate the current view
Switch between views

13. Normal view
Shows content
No XML element tags
Indicated by this icon:
Use most of the time when writing content

14. Tags On view
Shows content
Shows XML element tags
Indicated by this icon:
Allows precise insertion
Allows tag deletion/unwrapping
Click box to expand/collapse:
Tip: CTRL+SHIFT toggles Tags On & Normal

15. Plain Text view
Edit all XML markup and content
Indicated by this icon:
Does not check validity
Can create invalid XML

16. Page Preview view
Shows a formatted preview
Indicated by this icon:
Verify the content is formatted correctly
XML document transformed
Opens in browser or Acrobat

17. Tip:
Can’ see the menus?
t
Open a DITA document
Want to see the structure view?
View > Structure View

18. Workbook Exercise:
Basic File Operations

19. Options for saving and opening
files
Click Tools > Options
To use default toolbars, press CTRL on startup

20. File and folder naming
Be systematic and careful
No spaces
No special characters

21. Elements and Structured
Authoring

22. Elements: Key terms
Element
Element type (or name)
Element contents
Start tag
End tag
Attribute

23. Structure and validity
XML must be:
Well-formed
Valid
DITA content model defines validity
How to order elements
Hierarchy of element types
Attributes

24. Validating documents
Click Tools > Validate
Errors most common in converted legacy
documents
Fix “missing required element” problems first

25. Structure and quot;Smart Insertquot;
When pasting XMetaL content:
XMetaL inserts content at closest valid location
May be far from the insertion point
May not be pasted at all
When pasting Word or HTML content:
XMetaL uses DITA elements
Closest match to paste and location
Best advice: watch when pasting

26. Identifying the current element
See context bar (at bottom of screen)
Also shows ancestors' hierarchy
Based on:
Cursor location
Currently selected element
Here's a <li> within a <ul> within a
<section>…

27. Identifying the current element
Be aware of what is selected

28. ENTER key
XMetaL inserts the most logical next element
Often the same type as the current one

29. Insert menu
Allows you to insert elements
Shows most available elements
Context free
“Smart Insert”
Inserts an element in the next valid location
Sometimes asks if you want to split the current
element – usually this is what you want

30. Element List
View > Element List
Lists available valid
elements
Depends on cursor location
Insert new
Change selected

31. Paragraph menu
Change paragraphs to notes and long
quotations
Specify note types:
danger
tip
Apply and remove bullets and numbering

32. Format markup vs.
Semantic markup
Separation of content from formatting
Format markup: how something should look
Semantic markup: what something means
Examples:
<b> vs. <uicontrol>
<li> vs. <step>

33. Inserting domain elements
Domain elements cross topic types
Insert > * Element menus
Programming
Software
User Interface
Utilities
Other

34. Domains in Element List
Domain elements are listed in Element List
Tools > DITA Options
Only affects the Element List
Not the Insert menu

35. Modifying elements
Change element type
Radio button in Insert element list
Expand and collapse content displays
Delete elements

36. Deleting elements
Easiest on Tags On view
To quot;unwrapquot; an element (leave content):
Click just after the start tag, then press
Backspace
To delete the element and content:
Click a tag to select the entire element, then
press Delete or Backspace

37. Workbook Exercise:
Working with Elements

38. Generating Output (Publishing)

39. DITA Open Toolkit
Open-source application for publishing DITA
content to multiple output formats
Integrated with XMetaL
Help > Third-Party Components > DITA Open
Toolkit User Guide

40. Publishing formats
XHTML
PDF
CHM
RTF
Eclipse Help
JavaHelp

41. PDF options
XMetaL Enhanced PDF
Best all-purpose PDF deliverable type
XMetaL Enhanced PDF via Acrobat Distiller
Use if your documents have EPS graphics

42. Generating output
File > Generate Output for DITA Topic
Troubleshooting:
File > View Output Log

43. Workbook Exercise:
Generating Output

44. Attributes

45. Purpose of attributes
Provide additional information
width = “250 px”
Point to a file or URL
href = “http://www.microsoft.com”
href = “images/red_button.gif”
Identify an element
id = “p_73412763”
Conditionalize an element
platform = “macintosh”

46. Attribute Inspector
Click View >
Attribute Inspector
Allows you to
examine and change
values of XML
attributes
Cursor position is
important

47. Working with attributes
XMetaL creates element IDs automatically
Some dialog boxes set attributes
Insert Image
Set Conditional Text
Use Attribute Inspector

48. Attribute tooltips
Tip: Hover over a tag in Tags On view to see
attributes

49. Workbook Exercise:
Attributes

50. Images

51. Supported image formats
PNG, GIF, JPEG
SVG (if an appropriate plug-in is installed)
EPS
displays in XMetaL if preview information is
available in the file
requires Acrobat Distiller to produce optimal
PDF output
TIF, other formats
may not display in all output formats

52. Working with images
Inserting images
Insert > Image
Insert an image with a title
Insert > Figure with Title
Add a title to an existing image
Select Image and wrap in fig
Insert > Other Element > Title
Modify the properties of an existing image

53. Image sizing
Do one of the following:
Best-supported: Resize the image using a
graphics editor
Specify “width” in pixels, inches, cm, etc.
Specify “height”
Least-supported: Specify “scale” by a
percentage

54. Workbook Exercise:
Images

55. Tables

56. Tables
Click Table > Insert Table
Choose type:
Normal table = table with title
Simple table = informal table (no title)
Step choices (task topics only)
Properties (reference topics only)
Specify rows and columns
Specify header or not

57. Header rows
To make the first row of a table a header row:
Click Table > Insert Table
Add later with
Table > Table Properties

58. Working with table properties
Tip: Click in a row to change the properties of
that row. Don’ select the whole row.
t

59. Workbook Exercise:
Tables

60. Writing topics

61. Topics
A Topic is a DITA unit of information
Has a title, short description, and content
All topics have the same basic structure and
capabilities
Long enough to make sense on its own
Short enough to provide essential info

62. Topic types
Main topic types:
Generic Topic
Concepts
Tasks
Reference
DITA also includes:
Composite or multiple topic type
Glossary entry (DITA 1.1)
Specialization

63. Topics: Determining the topics
you need
Identify a task to document.
Identify the subtasks for the task.
Identify the concepts you need to support the
task and subtasks.
Identify the supporting reference information.

64. XMetaL authoring templates
Templates include commonly-needed
elements to get started
To delete empty elements, click between the
tags, then press Backspace
Blue-on-blue placeholder text is not shown
in output

65. Common elements in topics
Title
Short description
Briefly introduce the topic and provide a
concise answer to the question “What is this?”
Begin with a definition, and then expand upon
it
Contain the main point of the topic
1-3 sentences, no more than 50 words
Body

66. Concept topics
Concept topics explain and teach.
Help users build on their experience and
knowledge.
Read before using the product or completing a
task.
Can contain paragraphs, lists, tables, sections,
images, etc.

67. Concept topics: examples
Concept topics can focus on specific types of
information:
Technology
User concerns
Decisions
Background
Overview
Relationships
Process overview

68. Sections and nested topics

69. Sections, topics, and headings
DITA is structured
Not like HTML or Word
Cannot put headings where you want
DITA requires more planning of your heading
hierarchy

70. Sections
Use in Concept and Reference topics
Can have more than one section
Can’ nest sections
t
All following paragraphs must be in section

71. Working with sections
Use Tags On view to see section boundaries
Make sure section encloses all following
content elements

72. Sections and subtopics
To nest information, either:
Nest topics within a DITA map
Insert subtopics within the DITA topic
DITA maps are far preferred
Think about reusability

73. Workbook Exercise:
Creating Topics

74. Reference topics
Reference topics provide quick access to facts
Info users need to complete their tasks
Often read when the info is needed
Little or no background or explanatory detail
Links to other closely related reference topics
Contents defined by your Style Guide
Good use of specialization

75. Reference topics: examples
Documents the facts for categories such as:
device support settings
APIs symbols
messages language elements
schemas and so on

76. Task topics
Task topics document procedures
About 70% of topics are tasks
Each task topic presents information in a strict
chronological sequence:
Prerequisites
Context
Steps (required)
Result
Example
Postrequisites

77. Task topics: Prerequisites
DITA element: <prereq>
Things that users need to know or do before
starting the task steps

78. Task topics: Context
DITA element: <context>
Background information on the task

79. Typical task topic
<steps> element provides numbered steps

80. Sequence within a <step>
element
<cmd> (required)
Any number of the following:
<info> (tables, images, paragraphs, notes)
<substeps > (2a, 2b, 2c… )
<tutorialinfo>
<stepxmp >
<choicetable >
<choices>
<stepresult>

81. Example of <steps>

82. Steps: Example in a step
DITA element: <stepxmp>
Optional step element
Illustrates the successful completion of the
current step

83. Steps: Step result
DITA element: <stepresult>
Describes the result of the current step
Optional step element
Example:
When you depress the Lock button, all doors are
locked automatically.

84. Steps: Substeps
DITA elements: <substeps>, <substep>
Subdivides a major step in a sequence.
Output is the equivalent of a nested ordered
list within an ordered list.
Can use all the elements valid for <step>,
except for <choices> and <choicetable>.
Example:
3. Do the following:
a. Browse for the file.
b. Type the file name.

85. Steps: Choices
DITA elements: <choices>, <choice>
Decisions within a major step in a sequence
Output is the equivalent of a nested
unordered list within an ordered list.
Can contain any general DITA elements
Example:
4. Select one of the following options:
 Import all files
 Import selected files

86. Steps: Choice tables
DITA elements: <choicetable>, <chrow>,
<choption>, <chdesc>
Decisions within a major step in a sequence
Require a significant amount of information
Where there are multiple options
Output is the equivalent of a table
Can contain any general DITA elements
Example:
type attribute for the <note> element

87. Steps: Choice table output
Specify how to open new perspectives:
Option Description
Click in the same To open the perspective in the same window.
window When you open the window, it replaces the
currently open window.
Click in a new To open the perspective in a new window. When
window you open the window, it opens in a new window
and the currently open window remains open.

88. Task with unordered steps
Bullets instead of numbers
<steps-unordered> element

89. Task topics: Results
DITA element: <result>
Illustrates the successful completion of the
task
Example:
The device is fully configured and ready for use.

90. Task topics: Example
DITA element: <example>
Illustrates a successful completion of the task
steps.
<example> is a type of <section> element

91. Task topics: Postrequisites
DITA element: <postreq>
Things that users need to know or do upon
completing the task steps.

92. Workbook Exercise:
Task Topics

93. Cross-references and links

94. Types of links
Inline links <xref>
Cross-reference <xref href=quot;#targetquot;/>
File reference <xref href=quot;file.typquot;/>
Web link <xref href=quot;http://...quot;/>
Related links <related-links>
Links generated by relationship tables

95. Inserting links
Insert > Link > ...
Cross-reference
File reference
Web link
All add <xref> elements
Related links added at end of topic

96. Refreshing References
To update content in cross-references:
Click Edit > Refresh All References
Close and reopen the document

97. Workbook Exercise:
Cross-references and Links

98. Metadata and index elements

99. Metadata in DITA
Maintained in <prolog> element
Examples: author, publisher, copyright
information
Metadata is usually company-specific
Click Insert > Topic Metadata
This dialog can get you started, but best to
create your own

100. Indexing
Use <indexterm>
Can nest <indexterm> elements
Cannot put in <title> elements
Place <indexterm> where appropriate
DITA Open Toolkit will compile an index

101. Creating index entries
Click Insert > Index Marker
Tip: Press Alt+Shift+X
Use commas to create subentries

102. Editing index entries
Braces ({ and }) are XMetaL
Index entry:
Nested index entry:
Nested entry produces:
“Stylesheets, troubleshooting....37”

103. Advanced indexing features
DITA 1.1
Page ranges
See/See also
Sort as

104. Workbook Exercise:
Metadata and Index Elements

105. Track changes

106. Track changes
Purpose:
Communicate to reviewers about what’ new
s
Have reviewers communicate about what they
want
Help you manage your writing process
XMetaL uses processing instructions to track
changes

107. Using change tracking
Turn on and off:
Tools > Track Changes
Accept/reject changes:
Tools > Accept or Reject Changes
Can also use: View > Toolbars [Reviewing]
To change styles:
Name: Tools > Options [General]
Format: Tools > Options [Change Tracking]

108. Workbook Exercise:
Track Changes

109. DITA Maps

110. DITA maps
Organize DITA topics in a TOC-like structure
References to DITA topics
Analogous to a FrameMaker Book file
Can also contain topic metadata

111. Topics and maps
Topic
Unit of information that is meaningful when it
stands alone
Map
Organizes topics into a coherent set
Typically for different deliverables or media
Topics DITA Maps Deliverables

112. Working with maps
Map Editor displays maps in a
GUI
You can:
Add and remove topics
Change topic order
Nest topics
Edit with drag and drop or toolbar
buttons
Change map properties

113. Insert a reference to an existing
topic
Select the map entry under which you want to
nest the topic
Click Insert > Topic Reference
Browse for a topic

114. Tips for working with maps
Plan where to put your map and topic files
usually close to each other
Remember file and folder naming rules:
no spaces, no special characters
Make sure you’ using files in the location
re
you think you’ using
re

115. Insert and create a topic
Select the topic
above where you
want the new topic
Click Insert > Topic
Reference

116. Insert a topic heading
Click Insert > Topic
Heading

117. Create a new map
Click (small) File > New Map.
or
Click (big) File > New
Then choose the DITA Map template

118. Insert a submap
Both maps must exist
Click (small) Insert >
Map Reference

119. Specify map properties
In the Map Editor, select the Properties button.
In the Map Properties dialog, click the Special
Attributes tab
Interesting attributes include:
Navigation title
Scope
Include in TOC
Print

120. Workbook Exercise:
Organizing Topics with Maps

121. Switch to XML view
Click (small) File >
Switch to XML View
of Map.

122. Switch to Map Editor
Select File > Switch
to Map Editor

123. Different views for different tasks
Task Map XML
editor View
Create the table of contents, a.k.a. the 
“hierarchical” part of the map
Browse topics by double-clicking 
Edit relationship tables 
Use conditional text to make parts of the 
map conditional
Troubleshoot 

124. Relationship tables
Automatically generate “Related x” sections
Special type of semantic table
Columns define information types
Rows define relationships between topics
Each <topicref> in a cell will link to the other
topic references in that row
Can control linking

125. Map metadata
Metadata in maps
can fine-tune linking in relationship tables
can be used instead of topic metadata
is inherited from parent elements

126. Relationship Tables: XML View

127. Create a relationship table
Switch to XML view
Insert the relationship table
Add the <topicref> elements
Generate the map
Review the links
Update the relationship table
Generate and review
Switch to Map Editor

128. Insert a relationship table
Click Table > Insert Relationship Table.
Choose one of several common formats, then
click OK:

129. Attributes for managing links
In a <relcell> element:
collection-type = “family”
topicrefs in cell link to each other
linking = “targetonly”
topicrefs can be targets, but cannot be links
linking = “sourceonly”
topicrefs can be links, but cannot be targets

130. Add topics
Hold CTRL and drag
Task topics from the
navigation portion of
the map into the
relationship table. This
copies the <topicref>.
Think of the Concept
and Reference topics
that are related to each
Task. Paste <topicref>s
for those topics on the
same row.
Generate the map and
open the file.

131. Workbook Exercise:
Relationship Tables

132. Glossaries

133. Glossaries
Writing glossary content
Assembling glossary content

134. Glossary content
Basic markup:
<glossentry>
<glossterm></glossterm>
<glossdef></glossdef>
</glossentry>
One or more <glossentry> elements in a file
Specialization of <concept>
DITA 1.1

135. Assembling glossary content
Create a Bookmap file and point the
<glossarylist> element to your glossary
content files.
Add a <topicref> to your map file pointing to
your Bookmap file.

136. Publishing glossaries
During “Generate Output”:
All glossary content is pulled into the same
glossary and is sorted alphabetically.

137. Reusing content

138. Content reuse: overview
Reuse is about reducing duplication and
delivering more customized content
Two main approaches to reuse:
Conditional text
Modular reuse:
reusing topics in different maps
content references (conref)

139. Conditional text
Single source file
Content for multiple deliverables
Markup identifies different subsets
For example,
Windows: quot;Press Ctrl+Squot;
Macintosh: quot;Press Command+Squot;

140. What does conditional text
markup look like?
No conditional text markup:
<p>Press Ctrl+S.</p>
Conditional text markup:
<p platform = quot;windowsquot;>Press Ctrl+S.</p>
attribute attribute value

141. Conditional text overview
Configure XMetaL with conditions
Typically: products, platforms, audiences
In XMetaL:
Mark content as conditional
Style conditional content
Generate output
specify conditional content

142. Make content conditional
Select text or an element
Click Reuse > Apply/Remove Conditions

143. Assigning conditional attributes
Windows only:
<p platform=quot;windowsquot;>Press Ctrl+S.</p>
Windows and Macintosh, but not Unix:
<p platform=quot;windows macintoshquot;>Press Ctrl+S.</p>
All platforms:
<p>Press Ctrl+S.</p>

144. What content can you make
conditional?
DITA allows a high degree of granularity
Single words can be made conditional
(But consider practicality)
Not limited to text, other types of content

145. Elements that can be made
conditional:
Yes: No:
Text Individual table cells
Images Table columns
Cross-references Required elements
Index markers Text within required
elements is OK
Tables
Rows in tables
Content within
content references
Topic references in
DITA maps

146. <ph> element
If you make selected text conditional, XMetaL
inserts <ph> tags so it can “hang” attributes on
the <ph> element.

147. Style conditional text
Styles help keep
track of
conditional text
XMetaL only, not
in deliverables
Reuse > Style
Conditional Text

148. Generate conditional output
Choose what
platforms, products,
and audiences you
want to include

149. How DITA handles multiple
condition types
For an element marked as audience = “Europe”
and platform = “windows”
In output for this Does the Notes
audience and product: element
appear?
Europe No* The element is for the right audience.
Macintosh The element is not for the right platform.
North America No* The element is not for the right audience.
Windows The element is for the right platform.
Europe Yes The element is for the right audience.
Windows and The element is for one of the right platforms.
Macintosh
*Would appear if you used native FrameMaker® 7.x conditions instead of DITA

150. Multiple condition types: the rule
In this example: Content must be for both the
right platform and the right audience in order
to be included.
The general rule: An element is included if, for
each attribute mentioned in Show/Hide
Conditional Text:
It doesn't have any values for that attribute, i.e.
it is quot;common to allquot;
OR it matches at least one value that should be
included.

151. Planning to use conditional text
Determine your team's needs in terms of content
reuse:
What product variations are similar enough
they could be documented through one set of
source files?
What audiences do you want to customize
documentation for?
Would it make sense to achieve reuse through
conditional text, through content
modularization, or both?

152. Configuring XMetaL conditions
Edit ct_config.xml
<conditions>
<attribute name=quot;audiencequot; title=quot;Audiencequot;>
<value name=quot;studentquot; title=quot;Studentquot; />
<value name=quot;teacherquot; title=quot;Trainerquot; />
<value name=“self-studyquot; title=“Self-Studyquot; />
</attribute>
<attribute name=quot;platformquot; title=quot;Platformquot;>
<value name=quot;windowsxpquot; title=quot;Windows XP“ />
<value name=quot;windows2000quot; title=quot;Windows 2000 />
<value name=quot;linuxquot; title=quot;Linuxquot; />
<value name=quot;macosxquot; title=quot;MacOSX“ />
</attribute>
</conditions>

153. Content references (conrefs)
Standard DITA element attribute
References another element of same type
On output, content from referenced element
substituted for the conref element
Similar to FrameMaker “text insets”
Analogous to referencing an image file

154. Content references in XMetaL
Content shown in conref is:
Read-only
Updated when a document is opened
To manually refresh:
Click Edit > Refresh All References
Or press F11

155. Working with content references
Open a document containing a content
reference
Right-click to switch between viewing local
content and referenced content
Local content is highlighted in yellow

156. Reusable components
Reusable components:
Managed snippets of XML
Have titles, short descriptions, and reusable-
content.
One reusable component per file
Click Reuse > Create Reusable Component
XMetaL only; not transportable

157. Reuse strategies
Reuse Opportunity Solution
Multiple similar deliverables Flag some content as conditional
Include it in different topics using
Piece of content used in many content references
different contexts
(Modular reuse)
Include it in different deliverables
Topic used in many different through DITA maps
deliverables (Modular reuse)

158. Workbook Exercise:
Reusing Content

159. Additional resources
DITA Users group on Yahoo! groups:
http://tech.groups.yahoo.com/group/dita-users/
XMetaL-DITA group on Yahoo! groups:
http://tech.groups.yahoo.com/group/xmetal-dita/
dita.xml.org
www.justsystems.com (webinars, events)

160. Thanks!
Last Questions?
Drawing!
sbate@scriptorium.com

161. Introduction to
DITA and XMetaL
Simon Bate
Scriptorium Publishing
Services
1

162. Course Agenda
Overview of XMetaL Sections and nested
Elements and topics
structured authoring Cross-references
Generating output Metadata and
Attributes indexes
Images Track changes
Tables DITA maps
Writing topics Reusing content
2

163. Course purpose
Learn how to author content using XMetaL
Author Enterprise Edition
Understand DITA
Put theory into practice, learn by doing
3

164. About DITA
Darwin Information Typing Architecture
Created at IBM
Now developed and maintained by OASIS
Standard XML language
Cost-effective way to create, publish, reuse,
and exchange structured content
4

165. Role of DITA Tools
An authoring tool is a user interface for creating
DITA content
5

166. DITA documentation
DITA Language Reference
Purpose and content model for each element
Help > DITA Specifications > DITA Language
Reference
DITA Architectural Specification
Describes overall behavior of DITA
Very technical
Help > DITA Specifications > DITA Architectural
Specification
6

167. Overview of XMetaL
7

168. XMetaL Author
Standard word-processing environment
Multiple undo (and redo)
Spell checking & thesaurus
Change tracking
Create and edit text
Familiar editing features to create content
8

169. XMetaL Author Interface: Overview
Menu
Tool bar
Structure
View
View Mode Document Element
buttons Pane List
9

170. Inserting symbols and special
characters
Insert > Symbols
Insert > Special Characters
Or click View > Toolbars,
Then toggle appropriate checkboxes
10

171. Typographical elements
Bold
Italic
Underline
11

172. View modes
Four view modes for the document pane:
Normal
Page Preview
Tags On
Plain Text
Controls in bottom left corner of the pane:
Indicate the current view
Switch between views
12

173. Normal view
Shows content
No XML element tags
Indicated by this icon:
Use most of the time when writing content
13

174. Tags On view
Shows content
Shows XML element tags
Indicated by this icon:
Allows precise insertion
Allows tag deletion/unwrapping
Click box to expand/collapse:
Tip: CTRL+SHIFT toggles Tags On & Normal
14

175. Plain Text view
Edit all XML markup and content
Indicated by this icon:
Does not check validity
Can create invalid XML
15

176. Page Preview view
Shows a formatted preview
Indicated by this icon:
Verify the content is formatted correctly
XML document transformed
Opens in browser or Acrobat
16

177. Tip:
Can’ see the menus?
t
Open a DITA document
Want to see the structure view?
View > Structure View
17

178. Workbook Exercise:
Basic File Operations
11/03/08 18
18

179. Options for saving and opening
files
Click Tools > Options
To use default toolbars, press CTRL on startup
For training, it is useful to turn this option off
because having too many files open confuses
people
19

180. File and folder naming
Be systematic and careful
No spaces
No special characters
20

181. Elements and Structured
Authoring
21

182. Elements: Key terms
Element
Element type (or name)
Element contents
Start tag
End tag
Attribute
22

183. Structure and validity
XML must be:
Well-formed
Valid
DITA content model defines validity
How to order elements
Hierarchy of element types
Attributes
23

184. Validating documents
Click Tools > Validate
Errors most common in converted legacy
documents
Fix “missing required element” problems first
24

185. Structure and quot;Smart Insertquot;
When pasting XMetaL content:
XMetaL inserts content at closest valid location
May be far from the insertion point
May not be pasted at all
When pasting Word or HTML content:
XMetaL uses DITA elements
Closest match to paste and location
Best advice: watch when pasting
25

186. Identifying the current element
See context bar (at bottom of screen)
Also shows ancestors' hierarchy
Based on:
Cursor location
Currently selected element
Here's a <li> within a <ul> within a
<section>…
26

187. Identifying the current element
Be aware of what is selected
27

188. ENTER key
XMetaL inserts the most logical next element
Often the same type as the current one
28

189. Insert menu
Allows you to insert elements
Shows most available elements
Context free
“Smart Insert”
Inserts an element in the next valid location
Sometimes asks if you want to split the current
element – usually this is what you want
29

190. Element List
View > Element List
Lists available valid
elements
Depends on cursor location
Insert new
Change selected
30

191. Paragraph menu
Change paragraphs to notes and long
quotations
Specify note types:
danger
tip
Apply and remove bullets and numbering
31

192. Format markup vs.
Semantic markup
Separation of content from formatting
Format markup: how something should look
Semantic markup: what something means
Examples:
<b> vs. <uicontrol>
<li> vs. <step>
32

193. Inserting domain elements
Domain elements cross topic types
Insert > * Element menus
Programming
Software
User Interface
Utilities
Other

194. Domains in Element List
Domain elements are listed in Element List
Tools > DITA Options
Only affects the Element List
Not the Insert menu
34

195. Modifying elements
Change element type
Radio button in Insert element list
Expand and collapse content displays
Delete elements
35

196. Deleting elements
Easiest on Tags On view
To quot;unwrapquot; an element (leave content):
Click just after the start tag, then press
Backspace
To delete the element and content:
Click a tag to select the entire element, then
press Delete or Backspace
36

197. Workbook Exercise:
Working with Elements
11/03/08 37
37

198. Generating Output (Publishing)
38

199. DITA Open Toolkit
Open-source application for publishing DITA
content to multiple output formats
Integrated with XMetaL
Help > Third-Party Components > DITA Open
Toolkit User Guide
39

200. Publishing formats
XHTML
PDF
CHM
RTF
Eclipse Help
JavaHelp
40

201. PDF options
XMetaL Enhanced PDF
Best all-purpose PDF deliverable type
XMetaL Enhanced PDF via Acrobat Distiller
Use if your documents have EPS graphics
41

202. Generating output
File > Generate Output for DITA Topic
Troubleshooting:
File > View Output Log
42

203. Workbook Exercise:
Generating Output
11/03/08 43
43

204. Attributes
44

205. Purpose of attributes
Provide additional information
width = “250 px”
Point to a file or URL
href = “http://www.microsoft.com”
href = “images/red_button.gif”
Identify an element
id = “p_73412763”
Conditionalize an element
platform = “macintosh”
45

206. Attribute Inspector
Click View >
Attribute Inspector
Allows you to
examine and change
values of XML
attributes
Cursor position is
important
46

207. Working with attributes
XMetaL creates element IDs automatically
Some dialog boxes set attributes
Insert Image
Set Conditional Text
Use Attribute Inspector
47

208. Attribute tooltips
Tip: Hover over a tag in Tags On view to see
attributes
48

209. Workbook Exercise:
Attributes
11/03/08 49
49

210. Images
50

211. Supported image formats
PNG, GIF, JPEG
SVG (if an appropriate plug-in is installed)
EPS
displays in XMetaL if preview information is
available in the file
requires Acrobat Distiller to produce optimal
PDF output
TIF, other formats
may not display in all output formats
51

212. Working with images
Inserting images
Insert > Image
Insert an image with a title
Insert > Figure with Title
Add a title to an existing image
Select Image and wrap in fig
Insert > Other Element > Title
Modify the properties of an existing image
52

213. Image sizing
Do one of the following:
Best-supported: Resize the image using a
graphics editor
Specify “width” in pixels, inches, cm, etc.
Specify “height”
Least-supported: Specify “scale” by a
percentage
53

214. Workbook Exercise:
Images
11/03/08 54
54

215. Tables
55

216. Tables
Click Table > Insert Table
Choose type:
Normal table = table with title
Simple table = informal table (no title)
Step choices (task topics only)
Properties (reference topics only)
Specify rows and columns
Specify header or not
56

217. Header rows
To make the first row of a table a header row:
Click Table > Insert Table
Add later with
Table > Table Properties
57

218. Working with table properties
Tip: Click in a row to change the properties of
that row. Don’ select the whole row.
t
58

219. Workbook Exercise:
Tables
11/03/08 59
59

220. Writing topics
60

221. Topics
A Topic is a DITA unit of information
Has a title, short description, and content
All topics have the same basic structure and
capabilities
Long enough to make sense on its own
Short enough to provide essential info
61

222. Topic types
Main topic types:
Generic Topic
Concepts
Tasks
Reference
DITA also includes:
Composite or multiple topic type
Glossary entry (DITA 1.1)
Specialization
62

223. Topics: Determining the topics
you need
Identify a task to document.
Identify the subtasks for the task.
Identify the concepts you need to support the
task and subtasks.
Identify the supporting reference information.
63

224. XMetaL authoring templates
Templates include commonly-needed
elements to get started
To delete empty elements, click between the
tags, then press Backspace
Blue-on-blue placeholder text is not shown
in output
64

225. Common elements in topics
Title
Short description
Briefly introduce the topic and provide a
concise answer to the question “What is this?”
Begin with a definition, and then expand upon
it
Contain the main point of the topic
1-3 sentences, no more than 50 words
Body
65

226. Concept topics
Concept topics explain and teach.
Help users build on their experience and
knowledge.
Read before using the product or completing a
task.
Can contain paragraphs, lists, tables, sections,
images, etc.
66

227. Concept topics: examples
Concept topics can focus on specific types of
information:
Technology
User concerns
Decisions
Background
Overview
Relationships
Process overview
67

228. Sections and nested topics
68

229. Sections, topics, and headings
DITA is structured
Not like HTML or Word
Cannot put headings where you want
DITA requires more planning of your heading
hierarchy
69

230. Sections
Use in Concept and Reference topics
Can have more than one section
Can’ nest sections
t
All following paragraphs must be in section
70

231. Working with sections
Use Tags On view to see section boundaries
Make sure section encloses all following
content elements
71

232. Sections and subtopics
To nest information, either:
Nest topics within a DITA map
Insert subtopics within the DITA topic
DITA maps are far preferred
Think about reusability
72

233. Workbook Exercise:
Creating Topics
11/03/08 73
73

234. Reference topics
Reference topics provide quick access to facts
Info users need to complete their tasks
Often read when the info is needed
Little or no background or explanatory detail
Links to other closely related reference topics
Contents defined by your Style Guide
Good use of specialization
74

235. Reference topics: examples
Documents the facts for categories such as:
device support settings
APIs symbols
messages language elements
schemas and so on
75

236. Task topics
Task topics document procedures
About 70% of topics are tasks
Each task topic presents information in a strict
chronological sequence:
Prerequisites
Context
Steps (required)
Result
Example
Postrequisites
76

237. Task topics: Prerequisites
DITA element: <prereq>
Things that users need to know or do before
starting the task steps
77

238. Task topics: Context
DITA element: <context>
Background information on the task

239. Typical task topic
<steps> element provides numbered steps
79

240. Sequence within a <step>
element
<cmd> (required)
Any number of the following:
<info> (tables, images, paragraphs, notes)
<substeps > (2a, 2b, 2c… )
<tutorialinfo>
<stepxmp >
<choicetable >
<choices>
<stepresult>
80

241. Example of <steps>
81

242. Steps: Example in a step
DITA element: <stepxmp>
Optional step element
Illustrates the successful completion of the
current step
82

243. Steps: Step result
DITA element: <stepresult>
Describes the result of the current step
Optional step element
Example:
When you depress the Lock button, all doors are
locked automatically.
83

244. Steps: Substeps
DITA elements: <substeps>, <substep>
Subdivides a major step in a sequence.
Output is the equivalent of a nested ordered
list within an ordered list.
Can use all the elements valid for <step>,
except for <choices> and <choicetable>.
Example:
3. Do the following:
a. Browse for the file.
b. Type the file name.
84

245. Steps: Choices
DITA elements: <choices>, <choice>
Decisions within a major step in a sequence
Output is the equivalent of a nested
unordered list within an ordered list.
Can contain any general DITA elements
Example:
4. Select one of the following options:
 Import all files
 Import selected files
85

246. Steps: Choice tables
DITA elements: <choicetable>, <chrow>,
<choption>, <chdesc>
Decisions within a major step in a sequence
Require a significant amount of information
Where there are multiple options
Output is the equivalent of a table
Can contain any general DITA elements
Example:
type attribute for the <note> element
86

247. Steps: Choice table output
Specify how to open new perspectives:
Option Description
Click in the same To open the perspective in the same window.
window When you open the window, it replaces the
currently open window.
Click in a new To open the perspective in a new window. When
window you open the window, it opens in a new window
and the currently open window remains open.
87

248. Task with unordered steps
Bullets instead of numbers
<steps-unordered> element
88

249. Task topics: Results
DITA element: <result>
Illustrates the successful completion of the
task
Example:
The device is fully configured and ready for use.
89

250. Task topics: Example
DITA element: <example>
Illustrates a successful completion of the task
steps.
<example> is a type of <section> element
Haven't introduced <section> yet.
90

251. Task topics: Postrequisites
DITA element: <postreq>
Things that users need to know or do upon
completing the task steps.
91

252. Workbook Exercise:
Task Topics
11/03/08 92
92

253. Cross-references and links
93

254. Types of links
Inline links <xref>
Cross-reference <xref href=quot;#targetquot;/>
File reference <xref href=quot;file.typquot;/>
Web link <xref href=quot;http://...quot;/>
Related links <related-links>
Links generated by relationship tables
94

255. Inserting links
Insert > Link > ...
Cross-reference
File reference
Web link
All add <xref> elements
Related links added at end of topic

256. Refreshing References
To update content in cross-references:
Click Edit > Refresh All References
Close and reopen the document
96

257. Workbook Exercise:
Cross-references and Links
11/03/08 97
97

258. Metadata and index elements
98

259. Metadata in DITA
Maintained in <prolog> element
Examples: author, publisher, copyright
information
Metadata is usually company-specific
Click Insert > Topic Metadata
This dialog can get you started, but best to
create your own
99

260. Indexing
Use <indexterm>
Can nest <indexterm> elements
Cannot put in <title> elements
Place <indexterm> where appropriate
DITA Open Toolkit will compile an index
100

261. Creating index entries
Click Insert > Index Marker
Tip: Press Alt+Shift+X
Use commas to create subentries
101

262. Editing index entries
Braces ({ and }) are XMetaL
Index entry:
Nested index entry:
Nested entry produces:
“Stylesheets, troubleshooting....37”
Explain how to correct a misspelling in an index
entry
102

263. Advanced indexing features
DITA 1.1
Page ranges
See/See also
Sort as
103

264. Workbook Exercise:
Metadata and Index Elements
11/03/08 104
104

265. Track changes
105

266. Track changes
Purpose:
Communicate to reviewers about what’ new
s
Have reviewers communicate about what they
want
Help you manage your writing process
XMetaL uses processing instructions to track
changes
106

267. Using change tracking
Turn on and off:
Tools > Track Changes
Accept/reject changes:
Tools > Accept or Reject Changes
Can also use: View > Toolbars [Reviewing]
To change styles:
Name: Tools > Options [General]
Format: Tools > Options [Change Tracking]
107

268. Workbook Exercise:
Track Changes
11/03/08 108
108

269. DITA Maps
109

270. DITA maps
Organize DITA topics in a TOC-like structure
References to DITA topics
Analogous to a FrameMaker Book file
Can also contain topic metadata
Can have multiple maps for multiple deliverables.
EG: data sheet vs concepts guide
110

271. Topics and maps
Topic
Unit of information that is meaningful when it
stands alone
Map
Organizes topics into a coherent set
Typically for different deliverables or media
Topics DITA Maps Deliverables
111

272. Working with maps
Map Editor displays maps in a
GUI
You can:
Add and remove topics
Change topic order
Nest topics
Edit with drag and drop or toolbar
buttons
Change map properties
112

273. Insert a reference to an existing
topic
Select the map entry under which you want to
nest the topic
Click Insert > Topic Reference
Browse for a topic
113

274. Tips for working with maps
Plan where to put your map and topic files
usually close to each other
Remember file and folder naming rules:
no spaces, no special characters
Make sure you’ using files in the location
re
you think you’ using
re
114

275. Insert and create a topic
Select the topic
above where you
want the new topic
Click Insert > Topic
Reference
Break and re-form a link in a map, by changing the
file name for a referenced topic. See how the topic
title changes to italics.
115

276. Insert a topic heading
Click Insert > Topic
Heading
116

277. Create a new map
Click (small) File > New Map.
or
Click (big) File > New
Then choose the DITA Map template
117

278. Insert a submap
Both maps must exist
Click (small) Insert >
Map Reference
118

279. Specify map properties
In the Map Editor, select the Properties button.
In the Map Properties dialog, click the Special
Attributes tab
Interesting attributes include:
Navigation title
Scope
Include in TOC
Print
119

280. Workbook Exercise:
Organizing Topics with Maps
11/03/08 120
120

281. Switch to XML view
Click (small) File >
Switch to XML View
of Map.
121

282. Switch to Map Editor
Select File > Switch
to Map Editor
122

283. Different views for different tasks
Task Map XML
editor View
Create the table of contents, a.k.a. the 
“hierarchical” part of the map
Browse topics by double-clicking 
Edit relationship tables 
Use conditional text to make parts of the 
map conditional
Troubleshoot 
123

284. Relationship tables
Automatically generate “Related x” sections
Special type of semantic table
Columns define information types
Rows define relationships between topics
Each <topicref> in a cell will link to the other
topic references in that row
Can control linking
124

285. Map metadata
Metadata in maps
can fine-tune linking in relationship tables
can be used instead of topic metadata
is inherited from parent elements
125

286. Relationship Tables: XML View
126

287. Create a relationship table
Switch to XML view
Insert the relationship table
Add the <topicref> elements
Generate the map
Review the links
Update the relationship table
Generate and review
Switch to Map Editor
127

288. Insert a relationship table
Click Table > Insert Relationship Table.
Choose one of several common formats, then
click OK:
128

289. Attributes for managing links
In a <relcell> element:
collection-type = “family”
topicrefs in cell link to each other
linking = “targetonly”
topicrefs can be targets, but cannot be links
linking = “sourceonly”
topicrefs can be links, but cannot be targets
129

290. Add topics
Hold CTRL and drag
Task topics from the
navigation portion of
the map into the
relationship table. This
copies the <topicref>.
Think of the Concept
and Reference topics
that are related to each
Task. Paste <topicref>s
for those topics on the
same row.
Generate the map and
open the file.
130

291. Workbook Exercise:
Relationship Tables
11/03/08 131
131

292. Glossaries
132

293. Glossaries
Writing glossary content
Assembling glossary content
133

294. Glossary content
Basic markup:
<glossentry>
<glossterm></glossterm>
<glossdef></glossdef>
</glossentry>
One or more <glossentry> elements in a file
Specialization of <concept>
DITA 1.1
134

295. Assembling glossary content
Create a Bookmap file and point the
<glossarylist> element to your glossary
content files.
Add a <topicref> to your map file pointing to
your Bookmap file.
135

296. Publishing glossaries
During “Generate Output”:
All glossary content is pulled into the same
glossary and is sorted alphabetically.
136

297. Reusing content
137

298. Content reuse: overview
Reuse is about reducing duplication and
delivering more customized content
Two main approaches to reuse:
Conditional text
Modular reuse:
reusing topics in different maps
content references (conref)
138

299. Conditional text
Single source file
Content for multiple deliverables
Markup identifies different subsets
For example,
Windows: quot;Press Ctrl+Squot;
Macintosh: quot;Press Command+Squot;
139

300. What does conditional text
markup look like?
No conditional text markup:
<p>Press Ctrl+S.</p>
Conditional text markup:
<p platform = quot;windowsquot;>Press Ctrl+S.</p>
attribute attribute value

301. Conditional text overview
Configure XMetaL with conditions
Typically: products, platforms, audiences
In XMetaL:
Mark content as conditional
Style conditional content
Generate output
specify conditional content
..XMetaLAuthorConditional
Textconfigsct_config.xml.
141

302. Make content conditional
Select text or an element
Click Reuse > Apply/Remove Conditions
142

303. Assigning conditional attributes
Windows only:
<p platform=quot;windowsquot;>Press Ctrl+S.</p>
Windows and Macintosh, but not Unix:
<p platform=quot;windows macintoshquot;>Press Ctrl+S.</p>
All platforms:
<p>Press Ctrl+S.</p>
143

304. What content can you make
conditional?
DITA allows a high degree of granularity
Single words can be made conditional
(But consider practicality)
Not limited to text, other types of content
144

305. Elements that can be made
conditional:
Yes: No:
Text Individual table cells
Images Table columns
Cross-references Required elements
Index markers Text within required
elements is OK
Tables
Rows in tables
Content within
content references
Topic references in
DITA maps
145

306. <ph> element
If you make selected text conditional, XMetaL
inserts <ph> tags so it can “hang” attributes on
the <ph> element.
146

307. Style conditional text
Styles help keep
track of
conditional text
XMetaL only, not
in deliverables
Reuse > Style
Conditional Text
147

308. Generate conditional output
Choose what
platforms, products,
and audiences you
want to include
148

309. How DITA handles multiple
condition types
For an element marked as audience = “Europe”
and platform = “windows”
In output for this Does the Notes
audience and product: element
appear?
Europe No* The element is for the right audience.
Macintosh The element is not for the right platform.
North America No* The element is not for the right audience.
Windows The element is for the right platform.
Europe Yes The element is for the right audience.
Windows and The element is for one of the right platforms.
Macintosh
*Would appear if you used native FrameMaker® 7.x conditions instead of DITA
FM conditions were linked with Boolean OR. Now
conditional expressions in FM 8.0 help (a bit).
XMetaL conditions linked with Boolean AND.
149

310. Multiple condition types: the rule
In this example: Content must be for both the
right platform and the right audience in order
to be included.
The general rule: An element is included if, for
each attribute mentioned in Show/Hide
Conditional Text:
It doesn't have any values for that attribute, i.e.
it is quot;common to allquot;
OR it matches at least one value that should be
included.
150

311. Planning to use conditional text
Determine your team's needs in terms of content
reuse:
What product variations are similar enough
they could be documented through one set of
source files?
What audiences do you want to customize
documentation for?
Would it make sense to achieve reuse through
conditional text, through content
modularization, or both?
151

312. Configuring XMetaL conditions
Edit ct_config.xml
<conditions>
<attribute name=quot;audiencequot; title=quot;Audiencequot;>
<value name=quot;studentquot; title=quot;Studentquot; />
<value name=quot;teacherquot; title=quot;Trainerquot; />
<value name=“self-studyquot; title=“Self-Studyquot; />
</attribute>
<attribute name=quot;platformquot; title=quot;Platformquot;>
<value name=quot;windowsxpquot; title=quot;Windows XP“ />
<value name=quot;windows2000quot; title=quot;Windows 2000 />
<value name=quot;linuxquot; title=quot;Linuxquot; />
<value name=quot;macosxquot; title=quot;MacOSX“ />
</attribute>
</conditions>
152

313. Content references (conrefs)
Standard DITA element attribute
References another element of same type
On output, content from referenced element
substituted for the conref element
Similar to FrameMaker “text insets”
Analogous to referencing an image file
153

314. Content references in XMetaL
Content shown in conref is:
Read-only
Updated when a document is opened
To manually refresh:
Click Edit > Refresh All References
Or press F11
154

315. Working with content references
Open a document containing a content
reference
Right-click to switch between viewing local
content and referenced content
Local content is highlighted in yellow
155

316. Reusable components
Reusable components:
Managed snippets of XML
Have titles, short descriptions, and reusable-
content.
One reusable component per file
Click Reuse > Create Reusable Component
XMetaL only; not transportable
156

317. Reuse strategies
Reuse Opportunity Solution
Multiple similar deliverables Flag some content as conditional
Include it in different topics using
Piece of content used in many content references
different contexts
(Modular reuse)
Include it in different deliverables
Topic used in many different through DITA maps
deliverables (Modular reuse)
157

318. Workbook Exercise:
Reusing Content
11/03/08 158
158

319. Additional resources
DITA Users group on Yahoo! groups:
http://tech.groups.yahoo.com/group/dita-users/
XMetaL-DITA group on Yahoo! groups:
http://tech.groups.yahoo.com/group/xmetal-dita/
dita.xml.org
www.justsystems.com (webinars, events)
159

320. Thanks!
Last Questions?
Drawing!
sbate@scriptorium.com