Introduction to DITA and XMetaL

Simon BateScriptorium Publishing Services

Course Agenda

Overview of XMetaLElements and structured authoringGenerating output AttributesImagesTablesWriting topics

Sections and nested topicsCross-referencesMetadata and indexesTrack changesDITA mapsReusing content

Course purpose

Learn how to author content using XMetaL Author Enterprise EditionUnderstand DITAPut theory into practice, learn by doing

About DITA

Darwin Information Typing ArchitectureCreated at IBMNow developed and maintained by OASISStandard 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 ReferencePurpose and content model for each elementHelp > DITA Specifications > DITA Language Reference

DITA Architectural SpecificationDescribes overall behavior of DITAVery technicalHelp > DITA Specifications > DITA Architectural Specification

Overview of XMetaL

XMetaL Author

Standard word-processing environmentMultiple undo (and redo)Spell checking & thesaurusChange tracking

Create and edit textFamiliar editing features to create content

XMetaL Author Interface: OverviewMenu

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

BoldItalicUnderline

View modes

Four view modes for the document pane:NormalPage PreviewTags OnPlain Text

Controls in bottom left corner of the pane:

Indicate the current viewSwitch between views

Normal view

Shows content No XML element tagsIndicated by this icon: Use most of the time when writing content

Tags On view

Shows content Shows XML element tagsIndicated by this icon: Allows precise insertionAllows tag deletion/unwrappingClick box to expand/collapse:Tip: CTRL+SHIFT toggles Tags On & Normal

Plain Text view

Edit all XML markup and contentIndicated by this icon: Does not check validityCan create invalid XML

Page Preview view

Shows a formatted preview Indicated by this icon: Verify the content is formatted correctlyXML document transformedOpens 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 carefulNo spacesNo special characters

Elements and Structured Authoring

Elements: Key terms

Element Element type (or name)Element contentsStart tagEnd tagAttribute

Structure and validity

XML must be:Well-formedValid

DITA content model defines validityHow to order elements Hierarchy of element typesAttributes

Validating documents

Click Tools > ValidateErrors most common in converted legacy documentsFix “missing required element” problems first

Structure and "Smart Insert"

When pasting XMetaL content:XMetaL inserts content at closest valid locationMay be far from the insertion pointMay not be pasted at all

When pasting Word or HTML content:XMetaL uses DITA elementsClosest match to paste and locationBest advice: watch when pasting

Identifying the current element

See context bar (at bottom of screen)Also shows ancestors' hierarchyBased on:

Cursor locationCurrently 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 elementsShows most available elementsContext free“Smart Insert”

Inserts an element in the next valid locationSometimes asks if you want to split the current element – usually this is what you want

Element List

View > Element ListLists available valid elementsDepends on cursor location

Insert newChange selected

Paragraph menu

Change paragraphs to notes and long quotationsSpecify note types:

dangertip

Apply and remove bullets and numbering

Format markup vs. Semantic markup

Separation of content from formatting

Format markup: how something should lookSemantic markup: what something means

Examples:<b> vs. <uicontrol><li> vs. <step>

Inserting domain elements

Domain elements cross topic typesInsert > * Element menus

ProgrammingSoftwareUser InterfaceUtilitiesOther

Domains in Element List

Domain elements are listed in Element ListTools > DITA Options Only affects the Element List

Not the Insert menu

Modifying elements

Change element typeRadio button in Insert element list

Expand and collapse content displaysDelete 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

XHTMLPDFCHMRTFEclipse HelpJavaHelp

PDF options

XMetaL Enhanced PDFBest 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 informationwidth = “250 px”

Point to a file or URLhref = “http://www.microsoft.com”href = “images/red_button.gif”

Identify an elementid = “p_73412763”

Conditionalize an elementplatform = “macintosh”

Attribute Inspector

Click View > Attribute InspectorAllows you to examine and change values of XML attributesCursor position is important

Working with attributes

XMetaL creates element IDs automaticallySome dialog boxes set attributes

Insert ImageSet 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, JPEGSVG (if an appropriate plug-in is installed)EPS

displays in XMetaL if preview information is available in the filerequires Acrobat Distiller to produce optimal PDF output

TIF, other formatsmay not display in all output formats

Working with images

Inserting imagesInsert > Image

Insert an image with a titleInsert > Figure with Title

Add a title to an existing imageSelect Image and wrap in figInsert > 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 editorSpecify “width” in pixels, inches, cm, etc.Specify “height”Least-supported: Specify “scale” by a percentage

Workbook Exercise:Images

Tables

Tables

Click Table > Insert TableChoose type:

Normal table = table with titleSimple table = informal table (no title)Step choices (task topics only) Properties (reference topics only)

Specify rows and columnsSpecify 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 informationHas a title, short description, and content All topics have the same basic structure and capabilitiesLong enough to make sense on its own Short enough to provide essential info

Topic typesMain topic types:

Generic TopicConceptsTasksReference

DITA also includes:Composite or multiple topic typeGlossary 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 templatesTemplates 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 topicsTitleShort 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 topic1-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:

TechnologyUser concernsDecisionsBackgroundOverviewRelationshipsProcess overview

Sections and nested topics

Sections, topics, and headings

DITA is structuredNot like HTML or WordCannot put headings where you want

DITA requires more planning of your heading hierarchy

SectionsUse in Concept and Reference topicsCan have more than one sectionCan’t nest sectionsAll following paragraphs must be in section

Working with sections

Use Tags On view to see section boundariesMake sure section encloses all following content elements

Sections and subtopics

To nest information, either:Nest topics within a DITA mapInsert subtopics within the DITA topic

DITA maps are far preferredThink about reusability

Workbook Exercise:Creating Topics

Reference topics

Reference topics provide quick access to factsInfo users need to complete their tasksOften read when the info is neededLittle or no background or explanatory detailLinks to other closely related reference topics

Contents defined by your Style GuideGood use of specialization

Reference topics: examples

Documents the facts for categories such as:

device supportAPIsmessagesschemas

settingssymbolslanguage elementsand so on

Task topics

Task topics document proceduresAbout 70% of topics are tasksEach task topic presents information in a strict chronological sequence:

PrerequisitesContextSteps (required)ResultExamplePostrequisites

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 elementIllustrates the successful completion of the current step

Steps: Step result

DITA element: <stepresult>Describes the result of the current stepOptional step elementExample:

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 sequenceOutput 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 informationWhere there are multiple options

Output is the equivalent of a tableCan contain any general DITA elementsExample:

type attribute for the <note> element

Steps: Choice table output

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.

Specify how to open new perspectives:

Task with unordered steps

Bullets instead of numbers <steps-unordered> element

Task topics: Results

DITA element: <result>Illustrates the successful completion of the taskExample: 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-referenceFile referenceWeb link

All add <xref> elements

Related links added at end of topic

Refreshing References

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

Workbook Exercise:Cross-references and Links

Metadata and index elements

Metadata in DITA

Maintained in <prolog> elementExamples: author, publisher, copyright informationMetadata is usually company-specificClick Insert > Topic Metadata

This dialog can get you started, but best to create your own

Indexing

Use <indexterm>Can nest <indexterm> elementsCannot put in <title> elements

Place <indexterm> where appropriateDITA Open Toolkit will compile an index

Creating index entries

Click Insert > Index MarkerTip: Press Alt+Shift+XUse commas to create subentries

Editing index entries

Braces ({ and }) are XMetaLIndex entry:

Nested index entry:

Nested entry produces: “Stylesheets, troubleshooting....37”

Advanced indexing features

DITA 1.1 Page rangesSee/See alsoSort as

Workbook Exercise:Metadata and Index Elements

Track changes

Purpose:Communicate to reviewers about what’s newHave reviewers communicate about what they wantHelp 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 structureReferences to DITA topicsAnalogous to a FrameMaker Book fileCan also contain topic metadata

Topics and mapsTopic

Unit of information that is meaningful when it stands alone

MapOrganizes topics into a coherent setTypically for different deliverables or media

Topics DITA Maps Deliverables

Working with maps

Map Editor displays maps in a GUIYou can:

Add and remove topicsChange topic orderNest topicsEdit with drag and drop or toolbar buttonsChange map properties

Insert a reference to an existing topic

Select the map entry under which you want to nest the topicClick Insert > Topic ReferenceBrowse 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 topicClick Insert > Topic Reference

Insert a topic heading

Click Insert > Topic Heading

Create a new map

Click (small) File > New Map.

or

Click (big) File > NewThen 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 tabInteresting attributes include:

Navigation titleScopeInclude in TOCPrint

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” sectionsSpecial type of semantic table

Columns define information typesRows define relationships between topicsEach <topicref> in a cell will link to the other topic references in that rowCan control linking

Map metadata

Metadata in mapscan fine-tune linking in relationship tablescan be used instead of topic metadatais inherited from parent elements

Relationship Tables: XML View

Create a relationship table

Switch to XML viewInsert the relationship tableAdd the <topicref> elementsGenerate the mapReview the linksUpdate the relationship tableGenerate and reviewSwitch 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 otherlinking = “targetonly”

topicrefs can be targets, but cannot be links

linking = “sourceonly”topicrefs can be links, but cannot be targets

Add topicsHold 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

Reusing content

Content reuse: overview

Reuse is about reducing duplication and delivering more customized content

Two main approaches to reuse: Conditional textModular reuse:

reusing topics in different mapscontent references (conref)

Conditional text

Single source fileContent for multiple deliverablesMarkup identifies different subsetsFor 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 conditionsTypically: products, platforms, audiences

In XMetaL:Mark content as conditionalStyle conditional contentGenerate 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 granularitySingle words can be made conditional(But consider practicality)Not limited to text, other types of content

Elements that can be made conditional:

Yes:TextImagesCross-referencesIndex markersTablesRows in tablesContent within content referencesTopic references in DITA maps

No:Individual table cellsTable columnsRequired 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 textXMetaL only, not in deliverablesReuse > Style Conditional Text

Generate conditional output

Choose what platforms, products, and audiences you want to include

How DITA handles multiple condition types

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.

For an element marked as audience = “Europe” and platform = “windows”

*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 attributeReferences another element of same typeOn output, content from referenced element substituted for the conref elementSimilar to FrameMaker “text insets”Analogous to referencing an image file

Content references in XMetaL

Content shown in conref is:Read-onlyUpdated when a document is opened

To manually refresh:Click Edit > Refresh All ReferencesOr press F11

Working with content references

Open a document containing a content referenceRight-click to switch between viewing local content and referenced content

Local content is highlighted in yellow

Reusable components

Reusable components:Managed snippets of XMLHave titles, short descriptions, and reusable-content.

One reusable component per fileClick Reuse > Create Reusable ComponentXMetaL only; not transportable

Reuse strategiesReuse Opportunity Solution

Multiple similar deliverablesFlag 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

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