Authoring and Publishing with XMetaL and DITA

Introduction to DITA and XMetaL

Simon Bate

Scriptorium Publishing Services

Course Agenda

Overview of XMetaL

Elements and structured authoring

Generating output

Attributes

Images

Tables

Writing topics

Sections and nested topics

Cross-references

Metadata and indexes

Track changes

DITA maps

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 Structure View Tool bar Document Pane View Mode buttons Element 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

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

Does not check validity

Can create invalid XML

Page Preview view

Shows a formatted preview

Verify the content is formatted correctly

XML document transformed

Opens in browser or Acrobat

Tip:

Can’t see the menus?

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>…

Be aware of what is selected

Identifying the current element

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:

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

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’t select the whole row.

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’t nest sections

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

APIs

messages

schemas

settings

symbols

language elements

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 window To open the perspective in the same window. When you open the window, it replaces the currently open window. Click in a new window To open the perspective in a new window. When 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

Purpose:

Communicate to reviewers about what’s new

Have reviewers communicate about what they want

Help you manage your writing process

XMetaL uses processing instructions to track changes

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’re using files in the location you think you’re using

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 editor XML 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

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:

Press Ctrl+S.

Conditional text markup:

Press Ctrl+S.

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:

Press Ctrl+S.

Windows and Macintosh, but not Unix:

Press Ctrl+S.

All platforms:

Press Ctrl+S.

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:

Text

Images

Cross-references

Index markers

Tables

Rows in tables

Content within content references

Topic references in DITA maps

No:

Individual table cells

Table columns

Required elements

Text within required elements is OK

<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” *Would appear if you used native FrameMaker ® 7.x conditions instead of DITA In output for this audience and product: Does the element appear? Notes Europe Macintosh No* The element is for the right audience. The element is not for the right platform. North America Windows No* The element is not for the right audience. The element is for the right platform. Europe Windows and Macintosh Yes The element is for the right audience. The element is for one of the right platforms.

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 Piece of content used in many different contexts Include it in different topics using content references (Modular reuse)‏ Topic used in many different deliverables Include it in different deliverables through DITA maps (Modular reuse)‏

Workbook Exercise: Reusing Content

Additional resources