Introduction to
DITA and XMetaL
Simon Bate
Scriptorium Publishing
Services

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

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

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

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

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

Overview of XMetaL

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

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

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

Typographical elements
Bold
Italic
Underline

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

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

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

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

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

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

Workbook Exercise:
Basic File Operations

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

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

Elements and Structured
Authoring

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

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

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

Structure and \"Smart Insert\"
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

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>

Identifying the current element
Be aware of what is selected

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

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

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

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

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>

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

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

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

Deleting elements
Easiest on Tags On view
To \"unwrap\" 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

Workbook Exercise:
Working with Elements

Generating Output (Publishing)

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

Publishing formats
XHTML
PDF
CHM
RTF
Eclipse Help
JavaHelp

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

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

Workbook Exercise:
Generating Output

Attributes

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”

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

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

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

Workbook Exercise:
Attributes

Images

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

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

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

Workbook Exercise:
Images

Tables

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

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

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

Workbook Exercise:
Tables

Writing topics

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

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

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.

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

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

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.

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

Sections and nested topics

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

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

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

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

Workbook Exercise:
Creating Topics

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

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

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

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

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

Typical task topic
<steps> element provides numbered steps

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>

Example of <steps>

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

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.

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.

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

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

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.

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

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

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

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

Workbook Exercise:
Task Topics

Cross-references and links

Types of links
Inline links <xref>
Cross-reference <xref href=\"#target\"/>
File reference <xref href=\"file.typ\"/>
Web link <xref href=\"http://...\"/>
Related links <related-links>
Links generated by relationship tables

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

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

Workbook Exercise:
Cross-references and Links

Metadata and index elements

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

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

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

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

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

Workbook Exercise:
Metadata and Index Elements

Track changes

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

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]

Workbook Exercise:
Track Changes

DITA Maps

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

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

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

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

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

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

Insert a topic heading
Click Insert > Topic
Heading

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

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

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

Workbook Exercise:
Organizing Topics with Maps

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

Switch to Map Editor
Select File > Switch
to Map Editor

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 

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

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

Relationship Tables: XML View

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

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

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

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.

Workbook Exercise:
Relationship Tables

Glossaries

Glossaries
Writing glossary content
Assembling glossary content

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

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.

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

Reusing content

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)

Conditional text
Single source file
Content for multiple deliverables
Markup identifies different subsets
For example,
Windows: \"Press Ctrl+S\"
Macintosh: \"Press Command+S\"

What does conditional text
markup look like?
No conditional text markup:
<p>Press Ctrl+S.</p>
Conditional text markup:
<p platform = \"windows\">Press Ctrl+S.</p>
attribute attribute value

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

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

Assigning conditional attributes
Windows only:
<p platform=\"windows\">Press Ctrl+S.</p>
Windows and Macintosh, but not Unix:
<p platform=\"windows macintosh\">Press Ctrl+S.</p>
All platforms:
<p>Press Ctrl+S.</p>

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

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

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

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

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

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

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 \"common to all\"
OR it matches at least one value that should be
included.

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?

Configuring XMetaL conditions
Edit ct_config.xml
<conditions>
<attribute name=\"audience\" title=\"Audience\">
<value name=\"student\" title=\"Student\" />
<value name=\"teacher\" title=\"Trainer\" />
<value name=“self-study\" title=“Self-Study\" />
</attribute>
<attribute name=\"platform\" title=\"Platform\">
<value name=\"windowsxp\" title=\"Windows XP“ />
<value name=\"windows2000\" title=\"Windows 2000 />
<value name=\"linux\" title=\"Linux\" />
<value name=\"macosx\" title=\"MacOSX“ />
</attribute>
</conditions>

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

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

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

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

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)

Workbook Exercise:
Reusing Content

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)

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

Introduction to
DITA and XMetaL
Simon Bate
Scriptorium Publishing
Services
1

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

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

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

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

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

Overview of XMetaL
7

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

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

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

Typographical elements
Bold
Italic
Underline
11

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

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

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

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

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

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

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

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

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

Elements and Structured
Authoring
21

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

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

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

Structure and \"Smart Insert\"
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

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

Identifying the current element
Be aware of what is selected
27

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

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

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

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

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

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

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

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

Deleting elements
Easiest on Tags On view
To \"unwrap\" 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

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

Generating Output (Publishing)
38

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

Publishing formats
XHTML
PDF
CHM
RTF
Eclipse Help
JavaHelp
40

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

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

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

Attributes
44

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

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

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

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

Workbook Exercise:
Attributes
11/03/08 49
49

Images
50

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

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

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

Workbook Exercise:
Images
11/03/08 54
54

Tables
55

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

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

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

Workbook Exercise:
Tables
11/03/08 59
59

Writing topics
60

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

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

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

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

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

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

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

Sections and nested topics
68

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

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

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

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

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

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

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

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

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

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

Typical task topic
<steps> element provides numbered steps
79

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

Example of <steps>
81

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

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

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

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

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

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

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

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

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

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

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

Cross-references and links
93

Types of links
Inline links <xref>
Cross-reference <xref href=\"#target\"/>
File reference <xref href=\"file.typ\"/>
Web link <xref href=\"http://...\"/>
Related links <related-links>
Links generated by relationship tables
94

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

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

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

Metadata and index elements
98

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

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

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

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

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

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

Track changes
105

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

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

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

DITA Maps
109

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

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

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

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

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

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

Insert a topic heading
Click Insert > Topic
Heading
116

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

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

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

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

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

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

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

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

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

Relationship Tables: XML View
126

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

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

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

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

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

Glossaries
132

Glossaries
Writing glossary content
Assembling glossary content
133

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

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

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

Reusing content
137

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

Conditional text
Single source file
Content for multiple deliverables
Markup identifies different subsets
For example,
Windows: \"Press Ctrl+S\"
Macintosh: \"Press Command+S\"
139

What does conditional text
markup look like?
No conditional text markup:
<p>Press Ctrl+S.</p>
Conditional text markup:
<p platform = \"windows\">Press Ctrl+S.</p>
attribute attribute value

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
..\\XMetaL\\Author\\Conditional
Text\\configs\\ct_config.xml.
141

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

Assigning conditional attributes
Windows only:
<p platform=\"windows\">Press Ctrl+S.</p>
Windows and Macintosh, but not Unix:
<p platform=\"windows macintosh\">Press Ctrl+S.</p>
All platforms:
<p>Press Ctrl+S.</p>
143

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

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

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

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

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

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

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 \"common to all\"
OR it matches at least one value that should be
included.
150

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

Configuring XMetaL conditions
Edit ct_config.xml
<conditions>
<attribute name=\"audience\" title=\"Audience\">
<value name=\"student\" title=\"Student\" />
<value name=\"teacher\" title=\"Trainer\" />
<value name=“self-study\" title=“Self-Study\" />
</attribute>
<attribute name=\"platform\" title=\"Platform\">
<value name=\"windowsxp\" title=\"Windows XP“ />
<value name=\"windows2000\" title=\"Windows 2000 />
<value name=\"linux\" title=\"Linux\" />
<value name=\"macosx\" title=\"MacOSX“ />
</attribute>
</conditions>
152

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

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

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

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

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

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

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

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