Tutorial

Arbortext Editor
8.3.0.0
Copyright © 2024 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved.

Copyright for PTC software products is with PTC Inc. and its subsidiary companies (collectively “PTC”), and
their respective licensors. This software is provided under written license or other agreement, contains
valuable trade secrets and proprietary information, and is protected by the copyright laws of the United States
and other countries. It may not be copied or distributed in any form or medium, disclosed to third parties, or
used in any manner not provided for in the applicable agreement except with written prior approval from
PTC. More information regarding third party copyrights and trademarks and a list of PTC’s registered
copyrights, trademarks, and patents can be viewed here: https://www.ptc.com/support/go/copyright-and-
trademarks

User and training guides and related documentation from PTC are also subject to the copyright laws of the
United States and other countries and are provided under a license agreement that restricts copying,
disclosure, and use of such documentation. PTC hereby grants to the licensed software user the right to make
copies of product documentation and guides in printed form, but only for internal/personal use and in
accordance with the license agreement under which the applicable software is licensed. Any copy made shall
include the PTC copyright notice and any other proprietary notice provided by PTC. Note that training
materials may not be copied without the express written consent of PTC. This documentation may not be
disclosed, transferred, modified, or reduced to any form, including electronic media, or transmitted or made
publicly available by any means without the prior written consent of PTC and no authorization is granted to
make copies for such purposes.

UNITED STATES GOVERNMENT RIGHTS

PTC software products and software documentation are “commercial items” as that term is defined at 48 C.F.
R. 2.101. Pursuant to Federal Acquisition Regulation (FAR) 12.212 (a)-(b) (Computer Software) (MAY 2014)
for civilian agencies or the Defense Federal Acquisition Regulation Supplement (DFARS) at 227.7202-1(a)
(Policy) and 227.7202-3 (a) (Rights in commercial computer software or commercial computer software
documentation) (FEB 2014) for the Department of Defense, PTC software products and software
documentation are provided to the U.S. Government under the PTC commercial license agreement. Use,
duplication or disclosure by the U.S. Government is subject solely to the terms and conditions set forth in the
applicable PTC software license agreement.

PTC Inc., 121 Seaport Blvd, Boston, MA 02210 USA

 Contents

About This Guide ........................................................................................................5

Structured Documentation Overview.............................................................................9
The Arbortext Editor Environment............................................................................... 11
Opening a Sample Document ..............................................................................12
Arbortext Editor Window Components ..................................................................12
Viewing Cursor Changes.....................................................................................15
Expanding and Collapsing Tag Content ................................................................16
Using Drag and Drop ..........................................................................................17
Deleting Tags and Content ..................................................................................19
Viewing Generated Text ......................................................................................19
Getting Help .......................................................................................................20
Authoring with Arbortext Editor ...................................................................................23
Creating a New Document...................................................................................24
Inserting Tags and Content..................................................................................24
Adding Structure to Content.................................................................................28
Creating and Inserting a Text Entity ......................................................................29
Inserting Links ....................................................................................................30
Modifying Attributes ............................................................................................31
Inserting Graphics ..............................................................................................32
Inserting Symbols ...............................................................................................33
Searching for Content .........................................................................................34
Searching for Tags..............................................................................................34
Working with Tables ............................................................................................35
Checking Spelling...............................................................................................36
Saving Your Document as HTML .........................................................................37
Using Change Tracking .......................................................................................37
Comparing Documents .......................................................................................38
Working with DITA Topics...........................................................................................39
Concept .............................................................................................................41
Task...................................................................................................................43
Reference ..........................................................................................................46
Glossary ............................................................................................................50
Inserting a section...............................................................................................51
Generating an ID ................................................................................................53
Using the Resource Manager ..............................................................................54
Adding Index Terms ............................................................................................61
Checking Completeness .....................................................................................62
Working with DITA Maps............................................................................................65

3
 Creating a Map...................................................................................................67
Opening Edit View for Part of a Map .....................................................................68
Adding Content to a Map .....................................................................................69
Using Column View.............................................................................................78
Updating References ..........................................................................................86
Generating a Resolved Document for Editing........................................................88
Index........................................................................................................................91

4 Tutorial
 About This Guide

This Tutorial introduces you to the basic concepts for editing and authoring with
Arbortext Editor. The tutorial includes both general examples and step-by-step
exercises that you can duplicate with Arbortext Editor for practice.
The exercises cover two document types: DocBook and DITA (Darwin
Information Typing Architecture). For these document types, some Arbortext
Editor features are different. The exercises note where these differences occur.

Prerequisite Knowledge
The following knowledge is prerequisite to the content in this document:
• Familiarity with your operating system and computer
• Experience using authoring or editing software

Organization of this Guide

This tutorial is organized as follows:
• Structured Documentation Overview — A brief introduction to structured
documentation concepts
• The Arbortext Editor Environment — An overview of the Arbortext Editor
authoring environment
• Authoring with Arbortext Editor — Exercises covering basic authoring tasks

5
• Working with DITA Topics — Exercises providing an introduction to authoring
DITA topic documents
• Working with DITA Maps — Exercises providing an introduction to authoring
DITA map documents

Related Documentation
For more information refer to the PTC Arbortext Help Center.

Technical Support
The PTC eSupport portal provides resources and tools to support your Arbortext
implementation:
www.ptc.com/support/
If you encounter problems using this product, contact PTC Technical Support. For
complete details, see “Opening a Case” on the Processes tab of the PTC
Customer Support Guide:
www.ptc.com/support/csguide/Processes
You must have a Service Contract Number (SCN) before you can receive
technical support. If you do not know your SCN, see “Preparing to contact TS” on
the Processes tab of the PTC Customer Support Guide for information about how
to locate it.

Help for PTC Products

You can access PTC product help using the following resources:
• Online Help
Click Help from the user interface for online help available for the product.
• Reference Documents website — Information assistance in PDF format:

www.ptc.com/support/refdoc
You must have a Service Contract Number (SCN) before you can access the
Reference Documents site. If you do not know your SCN, see “Preparing to
contact TS” on the Processes tab of the PTC Customer Support Guide for
information about how to locate it:
www.ptc.com/support/csguide
• Help Center
Use the following link to access all PTC Help Centers:
support.ptc.com/apps/help_center/help/

6 Tutorial
Global Services
PTC Global Services delivers the highest quality, most efficient and most
comprehensive deployments of the PTC Product Development System including
Creo, Windchill, Arbortext, and PTC Mathcad. PTC’s Implementation and
Expansion solutions integrate the process consulting, technology implementation,
education and value management activities customers need to be successful.
Customers are led through Solution Design, Solution Development and Solution
Deployment phases with the continuous driving objective of maximizing value
from their investment.
Contact your PTC sales representative for more information on Global Services.

Comments
PTC welcomes your suggestions and comments on its documentation:
• To send feedback about a topic you are viewing in the PTC Arbortext Help
Center, click the send feedback icon in the top right corner of the topic.
The title of the help topic you were viewing when you clicked the icon is
automatically included with your feedback.
• You can also send an email to [email protected].
To help us more quickly address your concern, include the name of the PTC
product and its release number with your comments. If your comments are
about a specific help topic or book, include the title.

Documentation Conventions
This guide uses the following notational conventions:
• Bold text represents exact text that appears in the program's user interface.
This includes items such as button text, menu selections, and dialog box
elements. For example,
Click OK to begin the operation.
• A right arrow represents successive menu selections. For example,
Choose File ▶ Print to print the document.
• Monospaced text represents code, command names, file paths, or other
text that you would type exactly as described. For example,
At the command line, type version to display version information.
• Italicized monospaced text represents variable text that you would
type. For example,

About This Guide 7

 installation-dir\custom\scripts\
• Italicized text represents a reference to other published material. For example,
If you are new to the product, refer to the Getting Started Guide for basic
interface information.

8 Tutorial
 1
Structured Documentation
Overview
Structured documents conform to a set of rules that define and control the
structure of a document. XML and HTML are examples of structured documents.
The set of rules that define a document's structure is called its “document type.”
When you author a document in Arbortext Editor, the Editor is constantly
checking the rules defined in the associated document type and will only let you
insert content into the document that conforms to those rules. DocBook and DITA
(Darwin Information Typing Architecture) are examples of document types.
A document type defines the following components of a document:
• The set of tags that can be used in a document
A tag is the basic building block of a structured document. A tag is a container
and has a start tag and an end tag. Tags can contain other tags, attributes, and
text. Paragraphs and lists are examples of tags.
• The “attributes” associated with each tag
An attribute provides additional information about a tag and is contained
inside of the tag. For example, a tag could have an attribute that defines the
type of user for whom the information in the tag is intended.
• The structure in which the tags can be arranged
Each document type has a single tag that contains all of the other tags defined
in the document type. The document type defines the tag hierarchy contained
in that outer tag. The document type also defines whether a tag is optional or
required and whether it can contain other tags, text, or both.
Following is an example of a document type for writing a letter:
Letter
Date

9
 Greeting
Body
Paragraph or List or Table
Close
The Letter document type contains the following primary tags:
• Letter
The Letter tag is the outer tag in the document type and contains seven other
tags. Four of those tags (Date, Greeting, Body, and Close) are required and
must be in a Letter document in that order.
• Date
The Date tag must be the first tag inserted into a Letter document. It can only
contain text and is intended to contain a date.
• Greeting
The Greeting tag must be the second tag inserted into a Letter document. It
can only contain text.
• Body
The Body tag must be the third tag inserted into a Letter document. It can only
contain other tags, not text. The Body tag can contain one or more Paragraph,
List, or Table tags. Body can contain any number of these tags in any order.
• Close
The Close tag must be the last tag inserted into a Letter document. It can only
contain text.

Stylesheets
The formatting for a structured document is not stored in the document itself.
Instead, each document type has one or more stylesheets associated with the
document type that controls the appearance of the document through a collection
of style settings. Style settings can include basic formatting information such as
font size, paragraph spacing, and page layout, or more advanced formatting such
as automatic generation of a table of contents and an index.
The appearance of a document in the Arbortext Editor window is controlled by a
stylesheet.

10 Tutorial
 2
The Arbortext Editor Environment
Opening a Sample Document.....................................................................................12
Arbortext Editor Window Components.........................................................................12
Viewing Cursor Changes ...........................................................................................15
Expanding and Collapsing Tag Content.......................................................................16
Using Drag and Drop .................................................................................................17
Deleting Tags and Content .........................................................................................19
Viewing Generated Text .............................................................................................19
Getting Help..............................................................................................................20

The Arbortext Editor user interface conforms to standard windows conventions.

The following topics provide an overview of appearance and functionality that is
specific to Arbortext Editor.

11
Opening a Sample Document
Before performing this exercise, start Arbortext Editor.
Most of the document types in Arbortext Editor have both a template and sample
document associated with them. A template is a predefined set of empty tags that
provide all of the basic tagging required for a document. In this exercise, you will
open a sample document.
1. Choose File ▶ New to open the New Document dialog box.
2. Choose DocBook in the Category list and Arbortext XML DocBook V4.0 in the
Type list, then select the Sample option and click OK.
The sample document displays in the Arbortext Editor window. Note that the
sample document that displays in your Arbortext Editor window might differ from
the document shown in the following examples.

Arbortext Editor Window Components

The Arbortext Editor window is, by default, divided into two panes. The
Document Map provides an outline view and the Edit view displays the full
content of the document. The split bar divides the Document Map and the Edit
view. The bar can be adjusted to change the size of the panes.
The following figure shows the primary Arbortext Editor window components.

12 Tutorial
Menus and Toolbars
The menus and toolbars display a standard set of commands. For detailed
descriptions of the menus, toolbars, and their functionality, refer to the online Help
topics available from Help ▶ Arbortext Editor.

Edit View
The Edit view displays your document with its content and the tags that control
the structure of the document. You can change the display of these tags using the
View menu. The options enable you to control how much of the tagging structure
you want to see as you add content and new tags to your document. The following
examples are from the Arbortext XML DocBook document type (the tag
appearance in your documents might vary):

• Full Tags — Displays tag icons and names.

• No Tags — Suppresses the display of tags.
If you are accustomed to working in a “tagged view” environment (for example,
with HTML documents), you might want to work with the tags displayed in
Arbortext Editor.

Document Map
The Document Map enables you to navigate a graphical outline of the document
structure. You can also collapse large sections of the document and move them
within the Document Map. The Document Map and the Edit view are fully
interactive, so any changes made in one pane are immediately reflected in the
other.

The Arbortext Editor Environment 13

The following figure shows the Document Map components.

The Document Map contains the following components:

• Tag icon

Element — Identifies a tag in your document. Content associated with the

tag is displayed with the icon.
• Expand and Collapse icons
Collapse — Enables you to collapse the content of tags in the document.
Expand — Enables you to expand the content of tags in the document.
• Modify Attributes icons
Modify Attributes Plus — Displays when attributes associated with an
element have values that are not open in the map. Click on the icon to see the
attribute names and edit their associated values.
Modify Attributes Minus — Displays when attributes associated with an
element have values that are open in the map. Click on the icon to close the
display of attribute values.
• Graphic icon
Graphic — Identifies a graphic in your document. The graphic itself does
not appear in the Document Map, but you can click on the Modify Attributes

14 Tutorial
 icon associated with a graphic to obtain information about the graphic. The
graphic displays in the Edit view.
• Table icon
Table — Identifies a table in your document. The Document Map contains
the tagging for a table, but does not display the table as rows and columns.
The graphical representation of the table is displayed in the Edit view.

Status Bar
The status bar, located in the lower left area of the screen, displays tool tips and
other messages related to Arbortext Editor's interface and operation.

Viewing Cursor Changes

Before performing this exercise, open the Arbortext XML DocBook V4.0 sample
document in Arbortext Editor.
The Arbortext Editor cursor changes appearance based on the location of the
cursor in the Document Map and Edit view. Follow these steps to view some of
the cursor changes:
1. Use the arrow keys to navigate through the Document Map.
The cursor will change its shape depending on its location.
2. Move the cursor to the left of a para tag.

The I-beam cursor indicates that you can enter text and possibly other tags.
3. Type the following text: Inserting text into my document using
the Document Map.
As you type, a new para tag is added automatically to accommodate the new
text.
4. Move the cursor to the end of a chapter tag.

The cursor appears as a double-headed arrow indicating that no text

insertion is allowed at this location.
5. Type your name.
A message will appear on the status bar, warning you that inserting text is not
allowed.
6. Click outside of the Arbortext Editor window.
The cursor changes to the inactive cursor indicating that the window is not
active.

The Arbortext Editor Environment 15

For more information, refer to the The Cursor topic in the Arbortext Editor help.

Expanding and Collapsing Tag Content

Before performing this exercise, open the Arbortext XML DocBook V4.0 sample
document in Arbortext Editor.
Using the Document Map, you can view or hide the content of tags to make it
easier to navigate through your document. Follow these steps to collapse and
expand tag content:
1. Find the book tag at the top of the Document Map.
The following figure shows the completely expanded hierarchy of the book
tag.

2. Click the collapse icon to the left of the book element.

16 Tutorial
 Note that the entire book content collapses, but the title remains so you can
identify the collapsed content. The collapse icon is replaced with the expand
icon , as in the following figure.

3. Click the expand icon to expand the book tag.

Using Drag and Drop

Before performing this exercise, open the Arbortext XML DocBook V4.0 sample
document in Arbortext Editor.
You can drag and drop just content, a tag with its content, an empty tag, or a mix
of content and tags. You can use drag and drop in the following locations:
• Within a document
• Between different views of a document in the same Editor window
• Between separate documents
• Between applications

The Arbortext Editor Environment 17

Follow these steps to use drag and drop:
1. In the Document Map, locate a para tag.
2. Click on the para tag icon associated with the para tag to select the tag
and its associated content, as in the following example.

3. Click and, holding down the mouse button, drag the selected text down the
Document Map hierarchy.
Notice how the pointer changes:
• This symbol displays when moving the selected region would result in a

violation of the document's structure:

• This symbol displays when the selection is positioned over a valid paste

location:
• This symbol displays if the drop location is positioned over a valid paste
location, but will result in an element being added to the pasted content to

maintain proper document structure:

4. Move your cursor in the document until it looks like this:

18 Tutorial
5. Release the mouse button to complete the drop operation.
You could also select some of the text inside of the para tag and then drag that
text to another location in the document. The same symbols are displayed for this
operation, as when you are moving a tag and its content.
For more information, refer to the Drag and Drop topic in the Arbortext Editor
help.

Deleting Tags and Content

Before performing this exercise, open the Arbortext XML DocBook V4.0 sample
document in Arbortext Editor.
You can delete either just text or a tag with its content. Follow these steps to delete
a tag:

1. In the Document Map, click the tag icon to the left of a para element.
2. Press the DELETE key.
The element and its contents are deleted.
3. Click the Undo toolbar button to undo the deletion.
You could also select some of the text inside of the para tag and delete just that
text.
For more information, refer to the Deleting a Tag Pair topic in the Arbortext
Editor help.

Viewing Generated Text

Before performing this exercise, open the Arbortext XML DocBook V4.0 sample
document in Arbortext Editor.
Generated text is defined and automatically inserted in your document according
to your document type's stylesheet. Examples of generated text include a table of
contents, an index, and list numbers. Generated text is displayed in a different font
color (blue by default) and cannot be edited directly in Arbortext Editor. Follow
these steps to change the display of generated text:
1. Choose Tools ▶ Preferences and select the Window category.
2. If Full Menus is not checked, click on the check box. Click OK.
3. Choose View ▶ Generated Text ▶ Show to clear the selection and suppress the
display of generated text.

The Arbortext Editor Environment 19

4. Scroll through your document and note the absence of bullets, chapter
numbers, and list numbers.
5. Choose View ▶ Generated Text ▶ Show again to restore the display of generated
text.
6. Choose View ▶ Generated Text and note the choices available for updating
generated text. Verify that the Partial Auto-Updates option is selected.
7. Press the ESC key to exit from the menu.
For more information, refer to the Generated Text Overview topic in the Arbortext
Editor help.

Getting Help
Before performing this exercise, open the Arbortext XML DocBook V4.0 sample
document in Arbortext Editor.
Arbortext Editor provides online help through the Arbortext Help Center. The
Help Center contains all of the documentation for Arbortext Editor and its
associated product options. The Help Center also contains the documentation for
other Arbortext products. However, when you invoke the Help Center as online
help for a particular product, only the documentation associated with that product
is displayed in the Help Center.
Follow these steps to get help:
1. Choose Help ▶ Arbortext Editor.
The Arbortext Help Center appears displaying the Arbortext Editor online
help.
2. Enter keyboard shortcuts into the search field and click the Search
button.
The Help Center displays your search results in the Search tab. Note that
the search terms are highlighted in the title and excerpt displayed in the search
results.
3. Select the Keyboard shortcuts overview topic in the search results list.
The Help Center displays the topic. Note that the search terms are also
highlighted in the topic. By default, search terms are highlighted and linked
together in a help topic displayed from the search results. You can use the
TAB key or click on the highlighted search terms to navigate through
occurrences of the search terms in the topic.
4. Click on the Show in Table of Contents toolbar button.
The Help Center opens the Table of Contents tab with the Keyboard shortcuts
overview topic highlighted in the table of contents.

20 Tutorial
5. Select the Keyboard shortcuts topic below the Keyboard shortcuts overview
topic.
The Help Center displays the Keyboard shortcuts topic.
6. Close the Arbortext Help Center.
For more information, refer to the Arbortext Help Center help. You can access the
Help Center help by clicking Help ▶ Help Center.

The Arbortext Editor Environment 21

 3
Authoring with Arbortext Editor
Creating a New Document .........................................................................................24
Inserting Tags and Content ........................................................................................24
Adding Structure to Content .......................................................................................28
Creating and Inserting a Text Entity.............................................................................29
Inserting Links...........................................................................................................30
Modifying Attributes ...................................................................................................31
Inserting Graphics .....................................................................................................32
Inserting Symbols......................................................................................................33
Searching for Content................................................................................................34
Searching for Tags ....................................................................................................34
Working with Tables...................................................................................................35
Checking Spelling .....................................................................................................36
Saving Your Document as HTML ................................................................................37
Using Change Tracking..............................................................................................37
Comparing Documents ..............................................................................................38

Now that you are more familiar with the Arbortext Editor user interface, the
following topics provide some exercises that introduce you to using Arbortext
Editor for authoring documents.

23
Creating a New Document
Follow these steps to create a new document:
1. Choose File ▶ New.
The New Document dialog box opens.
2. In the New Document dialog box, select DocBook in the Category list and
Arbortext XML DocBook V4.0 in the Type list and then click OK.

An Arbortext XML DocBook template is loaded into the Arbortext Editor

window. The template includes tags that are pre-populated in your document.
Your template may differ slightly from the template used in this book.
3. Save your document by choosing File ▶ Save.
The Save As dialog box opens.
4. In the File Name field, type mydocument.
5. Navigate to the folder where you want to save the document and click Save.
By default, Arbortext Editor saves new documents in the directory that was
last used.
Arbortext Editor saves your new document in the folder you selected.

Inserting Tags and Content

For this exercise, use the Arbortext XML DocBook document you created in the
previous exercise.
Arbortext Editor enables you to insert tags into your document in several ways,
including the Insert Markup dialog box and toolbar button . In this exercise, you
will use the Quick Tags feature to insert tags into your document.
Follow these steps to insert tags and content into your new document:
1. In the Document Map, place your cursor at the beginning of an existing
paragraph.
2. Press ENTER to display the Quick Tags menu.
Only the tags that the document type allows at that location are available.

24 Tutorial
3. Using the mouse, click on para to insert a new para tag.

The cursor is automatically positioned for inserting text.

4. Type Inserting text in a new paragraph.
5. Place the cursor in the Edit view and choose View ▶ Full Tags.
6. In the Edit view, place the cursor between the title tags at the top of the
document and type Creating Structured Documents

Authoring with Arbortext Editor 25

7. Place the cursor between the next set of title tags (under the chapter tag)
and type Inserting New Elements.

8. Between the second set of para tags, type Authors were once
responsible for maintaining both the content and the

26 Tutorial
 format of their documents. Structured documents allow
authors to focus entirely on content.

9. Press ENTER to select tags from the Quick Tags list.

10. Click on note to insert a note element

Authoring with Arbortext Editor 27

11. Type This document was written to demonstrate entering
content into a structured document.

12. Choose File ▶ Save to save your changes.

For more information, refer to the Inserting Markup and Inserting Tags using
Quick Tags topics in the Arbortext Editor help.

Adding Structure to Content

For this exercise, use the Arbortext XML DocBook document you modified in the
previous exercise.
Arbortext Editor enables you to convert blocks of paragraphs into bulleted or
numbered lists. Follow these steps to create a numbered list:
1. Position your cursor to the right of the last para tag.
2. Insert a new para tag into your document by pressing ENTER and selecting
the para tag from the Quick Tags list.

28 Tutorial
3. Enter the following text, inserting a new para tag at the end of each the first
three lines, resulting in four para elements and their content:
A numeric list can provide step by step instructions.
Each item is preceded by a number, which is automatically
generated by Arbortext Editor.
The appropriate indentation is also determined and
applied automatically.
Working with structured content reduces the amount of
manually applied formatting required for consistent
presentation.
4. Select all four paragraphs (including the para tags) and click on the Numeric
List toolbar button on the Application toolbar.
The four paragraphs are displayed as a numeric list.

You can also develop a list by inserting an numeric or bullet list tag into your
document and adding list items to the list.
For more information, refer to the Creating Lists topic in the Arbortext Editor
help.

Creating and Inserting a Text Entity

For this exercise, use the Arbortext XML DocBook document you modified in the
previous exercise.

Authoring with Arbortext Editor 29

Entities are blocks of content that you want to be able to use repeatedly.
Documents that contain entities are automatically updated when the content of the
entity is changed. You can create file entities or text entities, depending on the
amount of content you would like to reuse. Entities can be displayed in a
document using either an icon with the name of the entity, or with the contents of
the entity expanded.
There are several menus and options, such as the Entities menu, that are only
available if you have elected to display full menus. To display full menus, choose
Tools ▶ Preferences, select the Window tab, and click the check box next to Full
Menus. Click OK to exit from the Preferences dialog box.

Note
DITA documents reuse content in a different way. Refer to the Working with
DITA Topics on page 39 for information on DITA references.

Follow these steps to create and insert a text entity:

1. Select a range of text.
2. Choose Entities ▶ Create Text Entity From Selection.
The Create Text Entity from Selection dialog box opens.
3. In the Name field, type mytext and click OK to close the dialog box.
4. Place your cursor within a para tag and choose Entities ▶ Text.
The Text Entities dialog box opens.
5. Select the mytext text entity.
6. Click Insert, then click Close to close the dialog box.
The text entity is inserted as an icon.
7. Choose View ▶ Text Entity to view the expanded content of the entity.
For more information, refer to the Text Entities Overview and File Entities
Overview topics in the Arbortext Editor help.

Inserting Links
For this exercise, use the Arbortext XML DocBook document you modified in the
previous exercise.
You can link from one location in your document to another, or to a URL, using
Link tags.

30 Tutorial
 Note
DITA documents support linking in a different way. Refer to the Working with
DITA Topics on page 39 for information on DITA references.

Follow these steps to insert a link to a URL:

1. Insert a new para tag.
2. Type For more information about structured
documentation, refer to the PTC website.
3. Select the words PTC website, and choose Insert ▶ Link.
The Insert Link dialog box opens.
4. Choose the Web tab, type http://www.ptc.com/ in the URL field, and
click Insert to insert the link and close the dialog box.
5. Double-click on the highlighted link to open your web browser and display the
PTC web site.
For more information, refer to the Insert Link Dialog Box and Insert Link Target
Dialog Box topics in the Arbortext Editor help.

Modifying Attributes
For this exercise, use the Arbortext XML DocBook document you modified in the
previous exercise.
Tags such as sections, titles, paragraphs, and lists make up the basic structure of a
document. An attribute defines a particular aspect of a tag. Adding attributes
assigns special properties such as file references, magnification, and font styles.

Note
DITA documents support modifying some attributes in a different way. Refer
to the Working with DITA Topics on page 39 for information on modifying
DITA references.

Follow these steps to modify and attribute to change a font style:

1. Select any single word within a paragraph and press ENTER to activate the
Quick Tags menu.
2. Select the emphasis tag.

Authoring with Arbortext Editor 31

 The word formatting changes to italics. Italics is the default font style when
emphasis is applied to text in this document type.
3. Choose Edit ▶ Modify Attributes.
The Modify Attributes dialog box opens.
4. Type bold in the role field and click OK to close the dialog box.
Notice that the formatting for the word changes from italics to bold in the Edit
view and the Document Map.
5. In the Document Map, click on the corresponding Modify Attributes icon to
see the list of attributes that have been defined for this tag.
6. Click on the Modify Attributes icon again to close the list of attributes.
For more information, refer to the Attributes-Overview topic in the Arbortext
Editor help.

Inserting Graphics
For this exercise, use the Arbortext XML DocBook document you modified in the
previous exercise.
In Arbortext Editor, graphics are included in a document by reference. The
document contains a reference to an external graphic file, not the graphic itself.

Note
DITA documents support inserting graphics in a different way. Refer to the
Working with DITA Topics on page 39 for information on DITA references.

Follow these steps to insert a graphic and modify the size of the graphic:
1. Insert a new para tag.
2. Choose Insert ▶ Graphic.
The Insert Graphic dialog box opens.
3. Choose the inlinegraphic tag to allow your graphic to remain in line
with the flow of text in your document and click OK.
The Locate Graphic file to reference dialog box opens.
4. Navigate to a graphic file on your system, or open the graphics folder in
the Arbortext Editor installation folder and select instrument.jpg, then
select Open to insert the graphic.
The graphic is displayed in your document in line with the existing text.

32 Tutorial
5. Display the attributes associated with your new graphic by clicking on the
Modify Attributes icon in the Document Map.
6. Click once on the displayed attributes to open the Modify Attributes dialog box.
7. Type 25 in the scale field and click OK to close the dialog box.
The graphic is scaled to 25 percent of its original size.
For more information, refer to the Inserting Graphics Overview topic in the
Arbortext Editor help.

Inserting Symbols
For this exercise, use the Arbortext XML DocBook document you modified in the
previous exercise.
You can insert a variety of symbols into your document. Follow these steps to
insert a symbol:
1. Place your cursor within a para tag.
2. Choose Insert ▶ Symbol.
The Insert Symbol dialog box displays.
3. Click on a symbol in the dialog box.

4. Click Insert to insert the symbol at the cursor location.

5. Click Close to close the dialog box.

Authoring with Arbortext Editor 33

For more information, refer to the Inserting Symbols topic in the Arbortext Editor
help.

Searching for Content

For this exercise, use the Arbortext XML DocBook document you modified in the
previous exercise.
Arbortext Editor provides a standard find and replace feature. Follow these steps
to find content in a document:
1. Choose Find ▶ Find/Replace.
The Find/Replace dialog box displays.
2. Type structure in the Find What field.
3. Click the Find Next button.
The first occurrence of a word containing structure is highlighted in your
document. If you wanted to search just for the word “structure,” you can select
the Match Whole Word Only check box before searching for the word.
4. Click Cancel to close the dialog box.
For more information, refer to the Finding and Changing Text topic in the
Arbortext Editor help.

Searching for Tags

For this exercise, use the Arbortext XML DocBook document you modified in the
previous exercise.
In addition to searching for content, you can also search for tags. Follow these
steps to find a tag in a document:
1. Choose Find ▶ Find Tag/Attribute.
The Find Tag/Attribute dialog box displays.
2. Type inlinegraphic in the Tag Name field.
3. Click the Find Next button.
The first occurrence of an inlinegraphic tag is highlighted in your
document. You can also search for a tag with a specific attribute or attribute
value.
4. Click Cancel to close the dialog box.
For more information, refer to the Finding and Changing Markup topic in the
Arbortext Editor help.

34 Tutorial
Working with Tables
For this exercise, use the Arbortext XML DocBook document you modified in the
previous exercise.
Arbortext Editor provides a table editor to assist you with authoring tables. The
table editor hides the tags associated with a table and enables you to manipulate
the parts of a table in the Edit view.
Follow these steps to insert and work with a table in your document:
1. Place your cursor inside a para tag.
2. Choose Insert ▶ Table.
The Insert Table dialog box opens.
3. In the Rows field, click the up arrow to increase the number of rows to 7, then
click OK.
The table is inserted into your document.
4. Place the cursor in the first cell in the table.
5. Click on the Insert Column Left toolbar button.
A new column is inserted into the table to the left of the cursor. You can also
choose Table ▶ Insert ▶ Column Left for this and other table operations.
6. Select the new column by clicking in the column ruler above the column.
The cursor changes to a down arrow when it is in the ruler:

7. Click on the Span Cells toolbar button .

All of the cells in the column are joined together.
8. Click the arrow on the Apply Cell Shading toolbar button to display a drop
down list.

Authoring with Arbortext Editor 35

9. Select a color from the color palette.
10. Click in another area of the table to deselect the column to view the cell
shading.
For more information, refer to the Tables Overview, Table Menu Introduction, and
Table Toolbar topics in the Arbortext Editor help.

Checking Spelling
For this exercise, use the Arbortext XML DocBook document you modified in the
previous exercise.
Arbortext Editor automatically checks your document for spelling errors as you
type and marks any suspect words with a red wavy line. Arbortext Editor also
automatically corrects a limited set of misspelled words and similar errors. In
addition to the automatic spell checking, you can also explicitly check a selected
portion of a document, or the entire document, for spelling errors.
Follow these steps to check the spelling in your document:
1. Choose Tools ▶ Preferences.
The Preferences dialog box opens.
2. Select the Spelling category icon.
3. Make sure the Check Spelling as you type spelling preference is on and click
OK to close the dialog box.
4. Place your cursor in a para tag, and enter the misspelled word bok.
The misspelled word will have a red wavy line under it.
5. Right mouse click on the misspelled word to get a shortcut menu with
alternative words.
6. Choose book from the menu.
bok is replaced by book in your document.
7. Enter another misspelled word in the para tag and select the contents of the
tag.
8. Choose Tools ▶ Spelling.
The Spelling dialog box opens when Arbortext Editor detects a spelling error.
9. From the list of Suggestions, click on the correct word and choose Change to
correct the misspelled word.
Arbortext Editor displays a status message with details about the spell check
operation.
10. Click OK to close the status message and the Spelling dialog box.

36 Tutorial
For more information, see Spelling and Autocorrection Checks in the Arbortext
Editor help.

Saving Your Document as HTML

For this exercise, use the Arbortext XML DocBook document you modified in the
previous exercise.
Arbortext Editor enables you to save your document as an HTML file, which can
be displayed in a web browser.

Note
This feature is not available for DITA documents.

Follow these steps to save your document as an HTML file:

1. Choose File ▶ Save as HTML.
The Save as HTML File dialog box opens.
2. Type myhtml in the File name field, navigate to an appropriate save location,
and click the Save button.
The dialog box closes. Arbortext Editor saves your document as an HTML file
and opens the file in your default web browser. A folder is also created to hold
the graphics associated with the file.
For more information, refer to the Saving a Document as an HTML file topic in
the Arbortext Editor help.

Using Change Tracking

For this exercise, use the Arbortext XML DocBook document you modified in the
previous exercise.
The change tracking facilitates collaboration with other authors and editors by
highlighting changes and allowing you to accept or reject them. Follow these steps
to use change tracking:
1. Turn on change tracking by choosing Tools ▶ Change Tracking ▶ Track
Changes.
2. Select several words in different paragraphs and delete or replace them.
Arbortext Editor tracks the deletion of the original words using red strike-
through font and indicates the addition of new text with green underlined font.

Authoring with Arbortext Editor 37

3. Choose View ▶ Change Tracking ▶ Changes Applied to see how the changes
would appear if they were incorporated into the document.
4. Choose View ▶ Change Tracking ▶ Changes with Highlighting to highlight the
changes again.
5. You can accept or reject individual changes by choosing Tools ▶ Change
Tracking ▶ Accept or Reject Changes.

The Accept or Reject Changes dialog box opens.

6. Use the Next and Previous buttons in the dialog box to navigate through the
changes you've made to the document.
Click the Accept or Reject buttons to accept or reject an individual change.
Click Accept All or Reject All to accept or reject all of the changes.
7. When you have resolved all of the changes, click Close to close the dialog
box.
For more information, refer to the Change Tracking Overview topic in the
Arbortext Editor help.

Comparing Documents
For this exercise, use the Arbortext XML DocBook document you modified in the
previous exercise.
You can compare the differences between two documents using the compare
feature. The documents must either use the same document type, or they must
both be free-form XML.
Follow these steps to compare your document to the last saved version of the
document:
1. Save your document.
2. Modify the document by adding or deleting text, tags, and so forth.
3. Choose Tools ▶ Compare ▶ Last Saved.
The Compare window opens. This window is an Arbortext Editor view that
highlights the changes made since the last time you saved the document.
4. Close the Compare window.
5. Close your document.
For more information, refer to the Document Comparison Overview topic in the
Arbortext Editor help.
This completes the first part of the Arbortext Editor tutorial. In the next part of the
tutorial, you will learn how to use Arbortext Editor to author DITA (Darwin
Information Typing Architecture) documents.

38 Tutorial
 4
Working with DITA Topics
Concept....................................................................................................................41
Task .........................................................................................................................43
Reference.................................................................................................................46
Glossary ...................................................................................................................50
Inserting a section .....................................................................................................51
Generating an ID .......................................................................................................53
Using the Resource Manager .....................................................................................54
Adding Index Terms...................................................................................................61
Checking Completeness ............................................................................................62

The DITA (Darwin Information Typing Architecture) standard was pioneered at

IBM and is sponsored by OASIS (Organization for the Advancement of
Structured Information Standards), a not-for-profit, international consortium that
drives the development, convergence, and adoption of e-business standards.
OASIS defines DITA as “an architecture for creating topic-oriented, information-
typed content that can be reused and single-sourced in a variety of ways.” To
obtain more information on OASIS and DITA, refer to the DITA XML.org web
site at dita.xml.org.
Arbortext Editor supports the DITA standard and provides a sophisticated, flexible
environment for authoring and publishing DITA documents. Arbortext Editor has
customized configurations for editing both DITA topics and DITA maps. DITA
maps are covered in the next part of this tutorial. Maps enable you to organize
references to DITA topics and other resources.
Authoring a DITA topic is similar to working with other types of XML
documents. A DITA topic is intended to be a modular document that provides
discrete information about a single subject. There are four primary types of DITA
topics:

39
• Concept
• Task
• Reference
• Glossary
The Arbortext Editor configuration for editing DITA topics is similar to the
standard configuration for editing other types of XML documents. Arbortext
Editor also provides a tool called the Resource Manager that assists you with
locating content to include in your DITA topics.

Note
Some Arbortext Editor features are different depending on whether you are
authoring a DITA document or a document in another document type, such as
Arbortext XML DocBook. For example, when authoring a DITA document
you use the Resource Manager to add links and other references to your
document instead of using the Insert Link dialog box.

This part of the Tutorial introduces you to some basic DITA topic concepts and
provides more step-by-step exercises to help you become familiar with the support
for DITA documents.
For more information, refer to the DITA Authoring Overview and Authoring DITA
Topics topics in the Arbortext Editor help.

40 Tutorial
Concept
The DITA Concept topic is used to provide background information that users
must understand before they can work with a product or interface, or perform a
task. This topic type answers “What is...” questions. Concepts can provide an
extended definition of a process, function, or product. You often use a Concept
topic as an introduction to another topic, such as a task or reference.
A Concept contains the following primary tags:
• concept — Contains all of the other tags
• title — The subject of the topic
• shortdesc — A short description or overview of the topic
• prolog — Various types of metadata about the topic, such as author,
copyright, index terms, and so forth
• conbody — Contains the actual content of the topic
The Concept body contains paragraphs, lists, table, sections, and other tags
used to author the content of the topic.
• related-links — Cross reference links to related information
Most of these tags are optional, so you only use the ones you need to author the
topic.

Creating a Concept
Before performing this exercise, start Arbortext Editor. If necessary, turn on full
tags with View ▶ Full Tags.
For this and the following exercises, you will be creating some DITA topics that
will eventually be used to develop a DITA map. Be sure to save the topics in a
location where you can retrieve them later, such as on your Windows desktop.
Follow these steps to create a Concept topic:
1. Choose File ▶ New.
The New Document dialog box opens.
2. Select the appropriate version of DITA Technical Content in the Category list
and DITA Concept in the Type list and then click OK.

Working with DITA Topics 41

 A DITA Concept template is loaded into the Arbortext Editor window:

3. Enter the following text in the title tag:

Productive Meetings
4. Enter the following text in the shortdesc tag:
Following some consistent practices can make business
meetings more productive.
5. Enter the following text in the p tag inside of the conbody tag:
Meetings are usually a large part of any business.
Unfortunately, poorly run meetings can often cause more
harm than good by wasting the participants' time and
affecting both their and the company's productivity.
There are some consistent practices you can follow to
ensure that a meeting is a productive one. Following are
some ways to make your meetings more productive:
6. Place your cursor after the p tag and press ENTER to display the Quick Tags
menu.
7. Click on ul (unordered list) in the menu to insert a bullet list into the
document.
8. Enter the following items into the list, inserting additional li (list item) tags
as needed:
• Provide and stick to an agenda
• Send participants anything you need to review at the
meeting ahead of time
• Start and finish the meeting on time

42 Tutorial
 • Provide meeting minutes
• Follow up on action items
9. Save the document with the name prodMeetings.dita.
Note that Arbortext Editor automatically assigns an ID to the top topic tag
when you first save it.
Your completed Concept should look like this:

Task
The DITA Task topic provides procedural information. This topic type answers
“How to...” questions. Tasks generally provide step-by-step instructions that
enable a user to perform a specific task. Tasks also provide information on
prerequisites, the expected result, and other aspects of a task.
A Task contains the following primary tags:
• task — Contains all of the other tags
• title — The subject of the topic
• shortdesc — A short description or overview of the topic
• prolog — Various types of metadata about the topic, such as author,
copyright, index terms, and so forth
• taskbody — Contains the actual content of the topic
A Task is much more structured than a DITA Concept. The topic body
contains the following series of tags in a set order:

Working with DITA Topics 43

 ○ prereq — The prerequisite things a user must know or do to perform the
task
○ context — Background information for the task
○ steps — The series of steps a user must follow to do the task
○ result — The expected outcome for the task
○ example — Examples that illustrate or support the task
○ postreq — The things a user must do after completing the task
• related-links — Cross reference links to related information
Most of these tags are optional, so you only use the ones you need to author the
topic.

Creating a Task
Follow these steps to create a Task topic:
1. Choose File ▶ New.
The New Document dialog box opens.
2. Select the appropriate version of DITA Technical Content in the Category list
and DITA Task in the Type list and then click OK.
A DITA Task template is loaded into the Arbortext Editor window:

44 Tutorial
3. Enter the following text in the title tag:
Preparing for a Meeting
4. Enter the following text in the shortdesc tag:
There are certain steps you should follow to prepare for a
meeting.
5. Enter the following text in the prereq tag:
Before scheduling a meeting, make sure that the things
you want to discuss cannot be handled in another way such
as through E-mail.
6. Enter the following text in the context tag:
Whether a meeting is successful or not is usually
determined by the things you do to prepare for it. Follow
these steps to prepare for a successful meeting:
7. In the steps tag, for each bullet in the following list enter the following steps
in the cmd tag inside of the step tag (adding additional step tags as
needed):
• Define the desired outcome of the meeting.
• Design the meeting agenda and objectives.
• List the participants and their role in the meeting.
• Reserve the meeting room and make sure it has the
equipment you need.
• Invite the meeting participants including information
about the agenda, their roles, and anything they need
to review before the meeting.
• An hour before the meeting, check the meeting room to
make sure it is set up correctly.
8. Enter the following text in the result tag:
If you follow these steps, your meeting is much more
likely to be a successful one.
9. Select and delete the example tag.
10. Enter the following text in the postreq tag:
Be sure to take minutes during the meeting and send them to
all participants.
11. Save the Task with the name schedMeetings.dita.

Working with DITA Topics 45

Your completed Task should look like this:

Reference
The DITA Reference topic describes the regular features of a subject or product,
such as the commands in a programming language or an application programming
interface (API). DITA Reference topics can provide information on any subject
that has regular content, including recipes, catalogs, bibliographies, and similar
structured descriptive information.
A Reference contains the following primary tags:
• reference — Contains all of the other tags
• title — The subject of the topic
• shortdesc — A short description or overview of the topic
• prolog — Various types of metadata about the topic, such as author,
copyright, index terms, and so forth
• refbody — Contains the actual content of the topic

46 Tutorial
 A Reference is typically organized into one or more sections, tables, and lists
that you can arrange in any order. Following are the primary tags in the
Reference body:
○ section — A container for content that you want to group in a reference
○ refsyn — Syntax or similar information
○ properties — A list of properties associated with the subject of the
reference, usually presented as a table
○ example — Examples that illustrate or support the reference information
The refbody tag can also contain the standard DITA tables.
• related-links — Contains cross reference links to related information
Most of these tags are optional, so you only use the ones you need to author the
topic.

Creating a Reference
Follow these steps to create a Reference topic:
1. Choose File ▶ New.
The New Document dialog box opens.
2. Select the appropriate version of DITA Technical Content in the Category list
and DITA Reference in the Type list and then click OK.

Working with DITA Topics 47

 A DITA Reference template is loaded into the Arbortext Editor window:

3. Enter the following text in the title tag:

The Parts of Meeting Minutes
4. Enter the following text in the shortdesc tag:
Meeting minutes should follow a standard format.
5. Select and delete all of the tags inside of the refbody tag.
One way you can select all of the content in the tag is to place the cursor to the
right of the opening refbody tag and press CTRL+E.
6. Use Quick Tags or Insert ▶ Markup to insert a properties tag inside of
refbody.

48 Tutorial
 The properties tag appears as a table in the Edit view:

7. Select the Value column and choose Table ▶ Delete ▶ Cells.

The column is deleted from the table.
8. Select the text Type in the first cell of the header row and replace it with the
following text:
Meeting Minutes Part
9. Press TAB twice and enter the following text in the first cell of the next row:
Date and Time
10. Press TAB and enter the following text in the second cell of the row:
The date and time on which the meeting was held
11. Add the following additional properties and descriptions to the table using
either Table ▶ Insert ▶ Row Below, the Insert Row Below toolbar button, or
the TAB key to insert additional rows as needed:

Location The meeting room or other location

where the meeting was held
Organizer The name of the person who
organized and facilitated the meeting
Attendees The list of people who attended the
meeting, optionally noting regular
attendees who were absent from the
meeting
Topics and Discussion The topics covered at the meeting
with a brief, relevant recording of the
discussion about those topics
Action Items Any action items that were assigned
at the meeting with the person
responsible for the item
Next Meeting The date, time and location of any
follow up meetings

12. Save the Reference with the name meetingMinutes.dita.

Working with DITA Topics 49

Your completed Reference should look like this:

Glossary
The DITA Glossary topic provides a single term and its associated definition,
enabling users to get an explanation of unfamiliar terminology. The topic can also
provide additional information about the term. If a term has multiple definitions,
you should create a separate DITA Glossary topic for each definition.
A Glossary contains the following primary tags:
• glossentry — Contains all of the other tags
• glossterm — The term
• glossdef — The definition
• prolog — Various types of metadata about the topic, such as author,
copyright, index terms, and so forth
• glossBody — Provides additional information about the term
The glossBody tag contains several other tags that enable you to provide
additional information about the term, such as the part of speech, its usage,
variants of the term, and so forth.
• related-links — Cross reference links to related terms

50 Tutorial
Most of these tags are optional, so you only use the ones you need to author the
topic.

Creating a Glossary
Follow these steps to create a Glossary topic:
1. Choose File ▶ New.
The New Document dialog box opens.
2. Select the appropriate version of DITA Technical Content in the Category list
and DITA Glossary in the Type list and then click OK.
A DITA Glossary template is loaded into the Arbortext Editor window:

3. Enter the following text in the glossterm tag:

Meeting Agenda
4. Enter the following text in the glossdef tag:
A list of meeting activities in the order in which they are
to be taken up, beginning with the call to order and ending
with adjournment. It usually includes one or more
specific items of business to be considered. It may, but
is not required to, include specific times for one or more
activities.
5. Save the Glossary with the name meetingAgenda.dita.
Your completed Glossary should look like this:

Inserting a section
For this exercise, you will need the prodMeetings.dita document you
created in the Creating a Concept Topic exercise.

Working with DITA Topics 51

The section tag enables you to include divisions in the body of a DITA topic.
All topic types, except for Glossary, allow sections in the body of the topic.
Sections should contain subsets of information that are directly related to the
topic. If the information you want to include in a section can stand alone, then you
should include it in another topic instead.
If you include multiple sections in a topic, the sections do not represent a
hierarchy. Instead, they are peer divisions. A section can have an optional title.
Follow these steps to include a section in the prodMeetings.dita document.
1. Open prodMeetings.dita in Arbortext Editor.
2. Place your cursor after the ul tag and press ENTER to display the Quick Tags
menu.
3. Click on section in the menu to insert a section into the document.
4. Enter the following text in the title tag:
Remote Meeting Participants
5. Insert a p tag after the title tag.
6. Enter the following text in the p tag:
If your meeting includes participants who will attend
remotely, make sure that you make adequate preparations
for those attendees. For example, set up telephone
conferences ahead of time, send out the meeting agenda by
electronic mail, and so forth.
7. Save the document.

52 Tutorial
Your completed document should look like this:

Generating an ID
For this exercise, you will need the prodMeetings.dita document you
modified in the previous exercise.
DITA tags contain an id attribute to hold the tag's ID. An ID enables you to
uniquely identify either a DITA topic or one of the tags contained in the topic. All
topics must have an ID assigned to them. Arbortext Editor automatically assigns
an ID to a new topic the first time that you save the topic. IDs are optional on all
other DITA tags.
You use IDs to identify the target for a link or cross reference. Arbortext Editor
also provides a feature that enables you to generate an ID for any DITA tag.
Follow these steps to generate an ID for a tag:
1. In the prodMeetings.dita document, place the cursor to the right of the
opening section tag:

2. Choose Insert ▶ Generate ID.

Working with DITA Topics 53

 Arbortext Editor generates an ID for the section tag:

You can also generate an ID with the Generate ID toolbar button.

3. Save your document.
For more information, refer to the Customizing DITA ID Generation topic in the
Arbortext Editor help.

Using the Resource Manager

You can add the following types of references to DITA topics:
• Cross references
• Links
• Images
• Content references

54 Tutorial
To assist you in adding these reference types to your documents, Arbortext Editor
provides the Resource Manager. The Resource Manager is a dialog box that
enables you to browse a file system, content management system, or the Internet
to find references to add to your document. It contains tabs enabling you to add all
of the above reference types:

You invoke the Resource Manager by choosing View ▶ Resource Manager or

selecting the Resource Manager toolbar button. In some cases, the Resource
Manager opens when you do an editing operation related to inserting references in
a DITA topic. For example, when you choose Insert ▶ Graphic the Resource
Manager appears docked to the left side of the Arbortext Editor window with the
Image tab active.
For more information, refer to the Resource Manager overview topic in the
Arbortext Editor help.

Adding a Cross Reference

For this exercise, you will need the prodMeetings.dita and
meetingAgenda.dita documents you created in the previous exercises.

Working with DITA Topics 55

You use DITA cross references to link to content inside of the topic you are
authoring. Cross references can also link to another topic, a tag inside of a topic,
or an external document. Cross references use the xref tag.
Follow these steps to add a cross reference in the prodMeetings.dita
document:
1. Open prodMeetings.dita in Arbortext Editor.
2. Choose View ▶ Resource Manager.
The Resource Manager opens with the Link/Xref tab active.
3. Select the word “agenda” in the first li tag in the unordered list (ul).
4. Use the Resource Manager browser to navigate to the folder where you saved
the DITA Glossary document created in these exercises.
You can use the Look in: drop-down list to find the place in your file system
where the folder is located. The folder you select in the Look in: list is
displayed in the browser. Double-clicking on a folder displayed in the browser
makes that folder and its hierarchy the focus in the browser. Use the plus and
minus signs in the browser to open and close both folder and document
hierarchies.
5. Click on the plus sign next to the meetingAgenda.dita document to
open that document's hierarchy in the browser:

6. Select the glossentry tag and click the Insert button.

The Resource Manager inserts the cross reference into your document:

7. Double-click on the agenda link.

The meetingAgenda.dita topic opens in a new Arbortext Editor window.
8. Close meetingAgenda.dita and save prodMeetings.dita.
For more information, refer to the Using Linking with DITA Documents and Link/
Xref Tab topics in the Arbortext Editor help.

56 Tutorial
Adding Links
For this exercise, you will need the prodMeetings.dita,
meetingsMinutes.dita, and schedMeetings.dita documents you
created in the previous exercises.
You use DITA links in the related-links tag of a topic. Links can link to a
topic or an external document. Unlike cross references, links cannot link to a tag
inside of a topic. Links use the link tag.
Follow these steps to add a related links section in the prodMeetings.dita
document:
1. If necessary, open prodMeetings.dita in Arbortext Editor.
2. Place the cursor after the closing conbody tag near the end of the document
and press ENTER to display the Quick Tags menu.
3. Click on related-links in the menu to insert a related links section into the
document.
4. Use Quick Tags to insert a linklist tag in the related-links tag and a
title tag in the linklist tag.
5. Enter the following text in the title tag:
Related Topics
6. Place the cursor after the closing title tag.
7. If necessary, open the Resource Manager and navigate to the folder where you
saved the DITA document created in these exercises.
8. Select the schedMeetings.dita topic and click the Insert button.
The Resource Manager inserts the link into your document:

Note that Arbortext Editor automatically inserts the title of the topic into your
link as preview text. If you do not want to author the text for your links, you
can use these titles for your link text. Since the topic also had a short
description, that description is also added to the link. If you do not want to use
the automatically inserted text in your document, you can click on the preview
text to highlight it and enter authored link or description text instead.

Working with DITA Topics 57

9. Add a link to the meetingsMinutes.dita topic as well.
10. Save prodMeetings.dita.
Your completed related links sections should look like this:

For more information, refer to the Using Linking with DITA Documents and Link/
Xref Tab topics in the Arbortext Editor help.

Adding an Image
For this exercise, you will need the schedMeetings.dita document you
created in the previous exercises. You will also need access to your Arbortext
Editor installation folder.
Follow these steps to add an image in the schedMeetings.dita document:
1. Open schedMeetings.dita in Arbortext Editor.
2. Place the cursor at the end of the text in the postreq tag and enter the
following sentence:
Minutes are an essential tool for holding the results of a
meeting together:
Add a space after the sentence.
3. Open the Resource Manager, select the Image tab, and navigate to the
graphics folder in the Arbortext Editor installation folder.
4. Select the staplegun.tif image in the Resource Manager browser and
click the Insert button.

58 Tutorial
 The Resource Manager inserts the image into your document:

5. Save schedMeetings.dita.
For more information, refer to the Image Tab topic in the Arbortext Editor help.

Using Content References

Content references (conref) enable you to include the content of a tag from one
DITA document into another DITA document. This enables you to reuse content
in DITA documents from a single original source. For example, you can have a
tag in the source document that contains a product name and then use content
references to include that product name in all of your related documents. Should
the product name change, you only have to change the name in the source
document. That change will then be reflected in all of the referencing documents.
When content is included from another document using a content reference, the
included content replaces any content in the referencing tag. Content references
are based on tags, so the tag you reference must be the same as the tag containing
the content reference. Content referenced can be viewed in a document, but cannot
be edited. You must modify the original source of the reference in order to make
changes. You can double-click on a content referenced tag to open the source
document.
Arbortext Editor enables you to use the Resource Manager to locate content to
reference in your documents. If a valid referencing tag is not currently in your
document, the Resource Manager automatically inserts a new, empty tag into the
document to be the target of the content reference.
For more information, refer to the DITA Content Reference Overview topic in the
Arbortext Editor help.

Adding a Content Reference

For this exercise, you will need the prodMeetings.dita,
schedMeetings.dita, and meetingAgenda.dita documents you
created in the previous exercises.

Working with DITA Topics 59

Follow these steps to add a content reference in the schedMeetings.dita
document:
1. If necessary, open schedMeetings.dita in Arbortext Editor.
2. If necessary, open the Resource Manager, select the Content Reference tab,
and navigate to the folder where you saved the DITA document created in
these exercises.
3. Select the word agenda in the second step tag in the procedure (steps).
4. In the Resource Manager, click on the plus sign next to the
prodMeetings.dita document and select the xref tag:

5. Click the Insert button in the Resource Manager.

The Resource Manager inserts the content reference into your document:

6. Place the cursor inside of the referenced xref tag and try to edit the text.
Since this content is referenced from another file, you cannot edit it.
7. Double-click on the agenda link.
The meetingAgenda.dita topic opens in a new Arbortext Editor window,
just as it would in the prodMeetings.dita document.
8. Close meetingAgenda.dita and save schedMeetings.dita.
For more information, refer to the Inserting and Modifying DITA Content
References and Content Reference Tab topics in the Arbortext Editor help.

Using the Resource Manager to Modify a Reference

For this exercise, you will need the schedMeetings.dita document you
created in the previous exercises. You will also need access to your Arbortext
Editor installation folder.

60 Tutorial
In addition to the standard Resource Manager, an undocked version of the
Resource Manager is available through the Modify Attributes dialog box. You use
this version of the Resource Manager to modify existing references in your DITA
topics.
Follow these steps to change the image in the schedMeetings.dita
document:
1. If necessary, open schedMeetings.dita in Arbortext Editor.
2. Place the cursor inside of the image tag in the postreq tag.
3. Choose Edit ▶ Modify Attributes.
The Modify Attributes dialog box opens.

4. Click on the modify reference button next to the href attribute:

The Modify Attributes - Resource Manager opens with just the Image tab
available.
5. If necessary, use the Modify Attributes - Resource Manager browser to navigate
to the graphics folder in the Arbortext Editor installation folder.
6. Select the dtduck3.gif image in the browser and click the Modify button.
The Resource Manager modifies the value of the href attribute to the new
image and closes.
7. Click OK to close the Modify Attributes dialog box.
The image in your document is changed to the new image:

8. Save schedMeetings.dita.
For more information, refer to the Resource Manager Overview and Image Tab for
Modifying Attributes topics in the Arbortext Editor help.

Adding Index Terms

For this exercise, you will need the prodMeetings.dita document you
created in the previous exercises.

Working with DITA Topics 61

DITA index terms are enclosed in the indexterm tag. You author secondary and
tertiary index terms by nesting additional indexterm tags inside of the primary
tag. The indexterm tag also contains additional tags such as index-see and
index-see-also that enable you to add see, see also, and other indexing
constructs.
You can add index terms to many DITA tags in the body of a topic. However, for
index terms that apply to an entire topic you should add the index terms to the
topics prolog tag.
Follow these steps to add some index terms to the prodMeetings.dita
document:
1. Open prodMeetings.dita in Arbortext Editor.
2. Enter the following text in the indexterm tag:
meetings
3. Insert another indexterm tag in the first indexterm tag to make a
secondary index term.
4. Enter the following text in the secondary indexterm tag:
practices for productive meetings
5. Save prodMeetings.dita.
The completed prolog should look like this:

Checking Completeness
For this exercise, you will need the prodMeetings.dita document you
created in the previous exercises.
Arbortext Editor provides a completeness checking feature that enables you to
perform a check on a document to make sure that all of the components required
by the document type are contained in the document. For DITA documents,
Arbortext Editor enhances the regular completeness check by also checking for
details described in the DITA specification that cannot be validated against the
document type. For example, enhanced completeness checking checks for missing
files, incorrect or unusual URL formats, unusual attribute values, the use of
deprecated elements or attributes, and so forth.

62 Tutorial
Follow these steps to run a completeness check on the prodMeetings.dita
document:
1. If necessary, open prodMeetings.dita in Arbortext Editor.
2. Place the cursor inside of the xref tag.
3. Choose Edit ▶ Modify Attributes.
The Modify Attributes dialog box opens.
4. Change the value of the type attribute from glossentry to task, and
click OK to close the dialog box.
5. Choose Tools ▶ Check Completeness.
Arbortext Editor runs a completeness check on the document. The progress of
the check is displayed on the status bar. Since the check found a problem in
the document, the Completeness Check Log dialog box opens:

6. Place the cursor somewhere in the document outside of the xref tag.
7. Double-click on the xref link next to the warning in the Completeness Check
Log dialog box.

Arbortext Editor moves the cursor to the xref tag, which is the location in
the document that corresponds to the warning.
8. Use the Modify Attributes dialog box to change the value of the xref tag's
type attribute from task back to glossentry, and click OK.
You could also use the Tools ▶ Update References feature to fix the attribute.
9. Close the Completeness Check Log dialog box, and choose Tools ▶ Check
Completeness again.

Working with DITA Topics 63

 This time, Arbortext Editor reports No completeness errors found in the status
bar.
10. Save and close schedMeetings.dita.
For more information, refer to the Check Completeness and Using Check
Completeness with DITA Documents topics in the Arbortext Editor help.

64 Tutorial
 5
Working with DITA Maps
Creating a Map .........................................................................................................67
Opening Edit View for Part of a Map............................................................................68
Adding Content to a Map............................................................................................69
Using Column View ...................................................................................................78
Updating References .................................................................................................86
Generating a Resolved Document for Editing ..............................................................88

Authoring a DITA map is very different from authoring a DITA topic. DITA maps
primarily contain tag and attribute content with relatively little text. You use DITA
maps to organize a collection of DITA topics and other types of resources into a
deliverable document. Instead of containing the content for the deliverable, a
DITA map contains references to the topics and other documents that are included
in the deliverable. These references are called topic references (topicref).
When you are developing a DITA document, it is often better to start with a DITA
map instead of DITA topics. The map is essentially the outline for the document
and enables you to develop and rearrange the hierarchy for your document as you
author it. DITA topics are intended to be standalone modules that provide
information about a single subject. The DITA map is where you take these
standalone topics and provide the overall structure for the deliverable as a whole.
Arbortext Editor provides the following features that help you develop DITA
maps:
• Resource Manager — The Resource Manager provides two new tabs that help
you add new and existing topics to your map
• Column view — Column view is a special Arbortext Editor view that provides
both a hierarchical view of a DITA map and a series of rows and columns,

65
 similar to a spreadsheet, where you can view and edit the attributes of the tags
in the map.
• DITA Map toolbar — This toolbar enables you to rearrange the tags in your
DITA map.
This part of the Tutorial introduces you to some basic DITA map concepts and
provides more step-by-step exercises to help you become familiar with how
Arbortext Editor supports DITA map editing.
For more information, refer to the DITA Authoring Overview and Authoring DITA
Maps topics in the Arbortext Editor help.

66 Tutorial
Creating a Map
Before performing this exercise, start Arbortext Editor.
For this and the following exercises, you will be creating and adding content to a
DITA map. You will be using the DITA topics created in the previous exercises to
develop your map. Be sure to save the map in a location where you can retrieve it
later.
Follow these steps to create a DITA map:
1. Choose File ▶ New.
The New Document dialog box opens.
2. Select the appropriate version of DITA Technical Content in the Category list
and DITA Map in the Type list and then click OK.
A DITA map template is loaded into the Arbortext Editor window in column
view with the Resource Manager open:

3. Save the document with the name businessMeetings.ditamap.

Save the new document in the same location where you stored the DITA topics
created in the previous exercises.

Working with DITA Maps 67

Opening Edit View for Part of a Map
For this exercise, use the DITA map document you created in the previous
exercise.
In general, DITA maps just contain tag and attribute content with very little text.
An exception is the title of the map. In a DITA map outline, a tag to which you
can add text has an icon with a blue box associated with it . For these tags, you
can open the Edit view for that part of a DITA map to add text to the tag.
Follow these steps to add a title to your map:
1. If necessary, open businessMeetings.ditamap in Arbortext Editor.
2. Place your cursor over the icon next to the Map Title.
3. Hold down the CTRL key and click on the icon.
Edit view opens for the title tag:

4. Click on Map Title inside of the template tags.

The template tags and their content are selected.
5. Enter the following text:
Business Meetings
The template text in the map is replaced with your title text. The title also
appears in the Column view.
6. Place the cursor inside of the Edit view and right-click.

68 Tutorial
 The Edit window shortcut menu opens.
7. Select Close View from the menu.
The Edit view closes.
8. Save the map.
For more information, refer to the Using Column View and Edit Window Shortcut
Menu topics in the Arbortext Editor help.

Adding Content to a Map

The primary type of reference you insert in a DITA map is a topic reference
(topicref). The topicref tag identifies a DITA topic or other resource (such
as a PDF file or web page) that you want to add to the map. The topic content or
resource is not actually added to the map. Instead, a reference to the resource is
added to the map similar to how a reference to an image is added to a DITA topic.
You can nest topic references inside of other topic references enabling you to
create a hierarchy in your outline.
The Resource Manager provides different tabs for DITA maps than it does for
DITA topics. The following tabs are available for DITA maps:
• Topic tab — Enables you to add topic references to existing DITA topics and
other resources
• New Topic tab — Enables you to create a new DITA topic and add a topic
reference to that topic
• Key Definition tab — Enables you to insert key definitions into a DITA map

The DITA standard provides for key based references. However, key
definitions are beyond the scope of this tutorial. For more information about
key references, refer to the Using Keys and Key References topic in the
Arbortext Editor help.
As with DITA topics, an undocked version of the Resource Manager is available
through the Modify Attributes dialog box to modify existing topic references. This
version of the Resource Manager also enables you to add content references to
DITA maps.
For more information, refer to the Resource Manager Overview topic in the
Arbortext Editor help.

Adding a New Topic

For this exercise, use the businessMeetings.ditamap document you
modified in the previous exercise.

Working with DITA Maps 69

When you are authoring a DITA map, you can use the Resource Manager’s New
Topic tab to both create a new DITA topic and to add a reference to that topic to
the map. You can also open a referenced topic directly from the map.
Follow these steps to add a new topic to the businessMeetings.ditamap
document:
1. Place your cursor after the title of the map in the Outline.

The Outline column has a special cursor that helps you determine where a
topic reference will be inserted into your map.
2. Select DITA Concept in the Resource Manager’s New Topic tab.
3. Type Introduction in the Title field.
Note that the Resource Manager automatically adds a name to the File Name
field based on the title. If desired, you can change the file name before the new
topic is created.

4. In the Folder field, use the Browse for Folder button to open the Browse for
Folder dialog box. In the dialog box, navigate to the location where you stored
your DITA topics. Select OK to close the dialog box and add that location to
the Folder field.
5. Click the Insert button.
The new topic is created and a reference to the topic is added to the map:

6. Double-click on Introduction in the Outline.

The new Introduction.dita topic opens in an Arbortext Editor window.
7. Enter the following text in the short description (shortdesc) tag:
This document provides information on making business
meetings more productive.
8. Enter the following text in the paragraph (p) tag in the concept body
(conbody) tag:

70 Tutorial
 Meetings can often cause more harm than good to a business
by wasting the time and hurting the productivity of
meeting participants. It is important to only hold
meetings when truly necessary and to make those meetings
as efficient as possible. It is also important to make
sure that meeting participants have an accurate record of
what took place at a meeting. This document will help you
make your business meetings more productive.
9. Save and close Introduction.dita.
10. Save businessMeetings.ditamap.
For more information, refer to the New Topic Tab topic in the Arbortext Editor
help.

Adding an Existing Topic

For this exercise, use the businessMeetings.ditamap document you
modified in the previous exercise.
In a DITA map, you can use the Resource Manager’s Topic tab to add a reference
to an existing topic to the map.
Follow these steps to add a topic to the businessMeetings.ditamap
document:
1. In the Resource Manager, click the Topic tab.
2. Use the Resource Manager browser to navigate to the folder where you saved
the DITA document created in these exercises.

Working with DITA Maps 71

3. Click on the prodMeeting.dita file in the browser to select the topic for
insertion:

4. Click the Insert button.

A reference to the prodMeeting.dita topic is added to the map:

72 Tutorial
 You can also double-click on a topic in the browser to insert that topic into
your map.
5. Save businessMeetings.ditamap.
For more information, refer to the Topic Tab topic in the Arbortext Editor help.

Adding Multiple Topics

For this exercise, use the businessMeetings.ditamap document you
modified in the previous exercise.
In the Resource Manager’s Topic tab, you can select multiple topics in the browser
and insert them into your DITA map in a single operation.
Follow these steps to add more topics to the businessMeetings.ditamap
document:
1. In the Topic tab’s browser, click on the meetingAgenda.dita file to
select it for insertion:

Working with DITA Maps 73

2. CTRL+click on the schedMeetings.dita file to also select that topic for
insertion.
3. Click the Insert button.

74 Tutorial
 References to those topics are added to the map:

Multiple topics are inserted into the map in the order the topics appear in the
browser. You can also select a folder in the browser and use the Insert button
to insert all of the topics in that folder into your map at the same time. You
will learn how to rearrange topic references in a later exercise.
4. Save businessMeetings.ditamap.

Dragging and Dropping a Topic

For this exercise, use the businessMeetings.ditamap document you
modified in the previous exercise.
In the Resource Manager’s Topic tab, you can also drag and drop topics from the
browser to insert them into your DITA map.
Follow these steps to add the last topic to the businessMeetings.ditamap
document:
1. In the Topic tab’s browser, click on the meetingMinutes.dita file to
select it for insertion.
2. Hold down the left mouse button and drag the topic to the bottom of your
DITA map:

Working with DITA Maps 75

3. Drop the topic at the bottom of the map.
A reference to that topic is added to the map:

4. Save businessMeetings.ditamap.
You have now added all of your topics to the DITA map.

Referencing a Web Page

For this exercise, use the businessMeetings.ditamap document you
modified in the previous exercise.
In the Resource Manager’s Topic tab, you can also add references to web pages to
your DITA map.
Follow these steps to add a web page reference to the
businessMeetings.ditamap document:
1. In the Topic tab, click on the Browse the Web button .

76 Tutorial
 The Topic tab changes to the mode for inserting a reference to a web page:

2. Open the following web page in your web browser:

en.wikipedia.org/wiki/Meetings
If you do not already have a web browser open, you can click the Open
Browser button to open your default web browser.
3. On the Topic tab, click the Get Browser URL button.
The URL for the Wikipedia web page is inserted in the URL option.
4. Click the Insert button.

Working with DITA Maps 77

 A reference to the web page is added to the map:

You can also type a URL into the URL control.

5. Click on the Previous Folder button to change the Topic tab back to the file
insertion mode.
6. Save businessMeetings.ditamap.

Using Column View

By default, Arbortext Editor opens a DITA map in Column view. Column view is
designed to support document types that primarily consist of tags and attribute
content and have relative little text or other inline content. Column view combines
a structural view of a document with a series of rows and columns, similar to a
spreadsheet, where you can view and edit the attributes of the elements in the
document.
Column view has the following parts:
• Outline column — This is always the first column and provides a structural
view of the document.
By default, this is the only column displayed when you edit a DITA map.
Column view also provides a special cursor for the Outline column. The
Column view cursor shows the current insertion point in your document
hierarchy.
• Modify attributes column — This is usually the second column and enables
you to view and modify the attributes of a tag that have assigned values.
• Attribute value columns — These are a series of columns that enable you to
modify a defined set of a tag’s attributes.
For more information, refer to the Column View Overview and Authoring DITA
Maps topics in the Arbortext Editor help.

78 Tutorial
Rearranging the Map Structure
For this exercise, use the businessMeetings.ditamap document you
developed in the previous exercises.
You use the Column view Outline column to rearrange the structure of a DITA
map. Arbortext Editor provides the DITA Map toolbar to assist you with changing
the map hierarchy. You can also use drag and drop to modify the hierarchy.
Follow these steps to add hierarchy to the businessMeetings.ditamap
document:
1. Place the Column view cursor on the line under the Preparing for a Meeting
topic:

2. Click the Move Element Up button on the DITA Map toolbar.

The Preparing for a Meeting topic moves up one spot in the map hierarchy.
3. Place the Column view cursor on the line under the Meeting Agenda topic.
4. Click the Demote Element button on the DITA Map toolbar.
The Meeting Agenda topic becomes a child of the Preparing for a Meeting
topic:

Working with DITA Maps 79

5. Click on the icon next to the Parts of Meeting Minutes topic to select that
topic reference:

6. Hold down the left mouse button and drag the topic above the Meeting Agenda
topic:

7. Drop the topic.

80 Tutorial
 The Parts of Meeting Minutes topic also becomes a child of the Preparing for a
Meeting topic:

8. Save businessMeetings.ditamap.
For more information, refer to the DITA Map Toolbar and Column View Cursor
topics in the Arbortext Editor help.

Opening and Closing the Hierarchy

For this exercise, use the businessMeetings.ditamap document you
modified in the previous exercise.
You can use the expand and collapse controls in the Outline column to open
and close parts of the map hierarchy.
Follow these steps to close some of the map hierarchy in the
businessMeetings.ditamap document:
1. Click on the collapse control next to the Preparing for a Meeting topic.
That part of the map closes:

2. Click on the expand control next to the Preparing for a Meeting topic to reopen
that part of the map.
3. Save businessMeetings.ditamap.

Working with DITA Maps 81

You completed map should look like this:

Showing and Hiding the Columns

For this exercise, use the businessMeetings.ditamap document you
developed in the previous exercises.
Besides the Outline column, Column view has two other types of columns that you
can use to modify the attributes of a tag in the map. When you edit a DITA map,
only the Outline column is displayed by default.
Follow these steps to display the other columns:
1. In businessMeetings.ditamap, click on the Show Multiple Columns
button at the right edge of the Outline column.
The rest of the columns are displayed:

2. Click on the Show Single Column button to hide the columns.

82 Tutorial
3. Right click on the Outline column title bar to display the related shortcut
menu:

4. Deselect the Show Single Column menu choice.

The columns are displayed again.
You can use either the buttons or the shortcut menu to show and hide the columns.
For more information, refer to the Column View Heading Shortcut Menu topic in
the Arbortext Editor help.

Using the Modify Attributes Column

For this exercise, use the businessMeetings.ditamap document you
developed in the previous exercises.
The Column view modify attributes column enables you to see all of the attributes
for a DITA map tag that currently have a value assigned to the attribute. You can
also modify the attribute values in this column. All of the attributes for a tag might
not be displayed in one of the other attribute value columns, so the modify
attributes column enables you to always see the attributes that currently have
assigned values for a tag.
Follow these steps to change an attribute using the modify attributes column:
1. In businessMeetings.ditamap, click on the attribute plus icon next
to the Introduction topic.

Working with DITA Maps 83

 The attributes defined for the topic reference are displayed:

When the attribute for a tag are displayed in the modify attributes column, the
icon next to the tag changes to the attribute minus icon .
If a tag does not currently have any attributes defined, the attribute icon is
displayed next to the tag. In this case, clicking on the icon opens the Modify
Attributes dialog box.
2. Click on the concept value for the type attribute.
The attribute value is selected for modification:

3. Type task for the value of the attribute.

4. Click on the attribute minus icon to close the attributes for the Introduction
topic.
5. Save businessMeetings.ditamap.

Using the Attribute Value Columns

For this exercise, use the businessMeetings.ditamap document you
modified in the previous exercise.
In addition to the modify attributes column, Column view provides a series of
attribute value columns where you can view and modify the more commonly used
attributes for the tags in a DITA map. These columns do not represent all of the
attributes associated with a tag. Instead, you can select the attributes you want to
display and the order in which you want to display them in the Preferences dialog
box. The attribute value columns are similar to a spreadsheet with rows for the
tags and columns for the attribute values.

84 Tutorial
Follow these steps to modify an attribute value using the attribute value columns:
1. In businessMeetings.ditamap, use the scroll bar at the bottom of
Column view to scroll the columns until you see attribute values:

You can also set the place in columns where you want to scroll in the
Preferences dialog box. Note that the Outline column is always the first
column, and it never scrolls.
2. Double-click on the value in the Type column for the Preparing for a Meeting
tag.
The attribute value is selected for modification:

3. Type concept for the value of the attribute.

4. Right click on the title bar to display the shortcut menu and select Configure
Columns.

Working with DITA Maps 85

 The Preferences dialog box opens with the Columns category displayed:

You can use this dialog box to select which attributes you want to display in
the columns, to reorder the columns, and to set the scroll boundary.

5. Click on the Move Down button .

The scroll boundary moves down in the list of columns.
6. Click OK to close the dialog box.
7. Use the scroll bar to scroll the columns again.
The modify attributes column is now the scroll boundary.
8. Save businessMeetings.ditamap.
For more information, refer to the Columns Preferences topic in the Arbortext
Editor help.

Updating References
For this exercise, use the businessMeetings.ditamap document you
modified in the previous exercise.

86 Tutorial
Arbortext Editor provides an update references feature for DITA maps that
enables you to check all of the DITA topics referenced from the map and update
any incorrect information in the associated topic references. You can also use the
update references feature for a DITA topic. In that case, the operation will update
things such as cross references, link preview text, and so forth.
Follow these steps to update the references in businessMeetings.ditamap:
1. In businessMeetings.ditamap, double-click on the The Parts of
Meeting Minutes topic to open that topic in a new Arbortext Editor window.
2. Change the title of the meetingMinutes.dita topic to the following text:
The Format of Meeting Minutes
3. Save and close meetingMinutes.dita.
4. In businessMeetings.ditamap, choose Tools ▶ Update References.
The progress of the update references operation is displayed on the status bar.
Since the operation found references in the map that needed to be updated, the
Update References Messages window opens:

The operation corrected the changes you made in previous exercises to the
type attribute for two of the topic references. It also updated the map’s
navigation title to reflect the change you just made to the title of
meetingMinutes.dita.
5. Save businessMeetings.ditamap.
In addition to the update references feature, you can also use Arbortext Editor’s
enhanced completeness checking with DITA maps.

Working with DITA Maps 87

For more information, refer to the Updating DITA Referencesand Using Check
Completeness with DITA Documents topics in the Arbortext Editor help.

Generating a Resolved Document for

Editing
For this exercise, use the businessMeetings.ditamap document you
modified in the previous exercise.
Arbortext Editor can produce a resolved document for a DITA map that assembles
all of the topics referenced in the map into a single document. The resolved
document enables you to edit the text and tags of the topics included in the DITA
map. It also enables you to perform a spell check or find/replace operation for all
of the topics referenced in the map. Any changes you make to the content of the
resolved document are saved to the associated source documents referenced in the
map. However, you cannot make changes to the structure of your DITA map in the
resolved document. The resolved document is a temporary document and only
exists until you close it.
Follow these steps to produce a resolved document for editing for
businessMeetings.ditamap:
1. In businessMeetings.ditamap, choose Edit ▶ Edit Resolved Document
▶ For Editing.

88 Tutorial
 The Resolved Document View of businessMeetings.ditamap opens in a new
Arbortext Editor window:

2. Scroll through the resolved document.

Each topic in the document is enclosed in an object boundary, so you can
easily see where the individual topics begin and end.
3. Position the cursor over the green triangle at the top left corner of the
Introduction topic.

A message displays showing where the topic is located on the file system:

Object boundaries appear in Arbortext Editor for many types of included

object such as file entities, XML inclusions, and Content Management System
objects.
4. Choose Find ▶ Find/Replace.
The Find/Replace dialog box opens.
5. Type participants in the Find What field and attendees in the Replace
With field.
6. Click the Find Next button.
The first occurrence of “participants” is highlighted in the resolved document.
7. Click the Replace button to replace “participants” with “attendees”.

Working with DITA Maps 89

 Continue the find/replace operation until you have replaced all occurrences of
“participants” in the resolved document.
8. Choose File ▶ Save and close the resolved document.
All of the changes you made to the resolved document are saved back to the
individual source documents.
9. In businessMeetings.ditamap, double-click on the Productive
Meetings topic to open that topic in a new Arbortext Editor window.

Note that the changes you made to this topic in the resolved document are
reflected in the source file.
10. Close prodMeetings.dita.
11. Save and close businessMeetings.ditamap.
This concludes the Tutorial.
For more information, refer to the Authoring DITA Maps and Using Object
Boundaries topics in the Arbortext Editor help.

90 Tutorial
 Index

A DITA
Column view, 78
Arbortext Editor
completeness checking, 62
opening a sample document, 12
Concept topics, 41
attribute values
creating, 41
inserting, 31
content references, 59
attributes
adding, 59
introduction to, 31
cross references
adding, 55
C DITA Maps
creating, 67
change tracking, 37
Edit view, 68
collapse icon
tutorial, 65
Document Map, 12
DITA Topics
Column view
DITA maps, 78 tutorial, 39
attribute value columns, 84 Glossary topics, 50
changing the hierarchy, 79 creating, 51
modify attributes column, 83 IDs, 53
images
opening and closing the hierarchy,
adding, 58
81
index terms
showing the columns, 82
adding, 61
completeness checking
links
DITA, 62
adding, 57
content
Reference topics, 46
deleting, 19
creating, 47
finding, 34
references, 54
inserting, 24
DITA maps, 69
content references, 59
modifying, 60
adding, 59
Resource Manager, 54
cross references
DITA maps, 69
adding, 55
sections, 51
cursors, 15
Task topics, 43
creating, 44
D DITA Maps
Delete button, 19 Column view, 78

91
 attribute value columns, 84 F
changing the hierarchy, 79
finding
modify attributes column, 83
content, 34
opening and closing the hierarchy,
tags, 34
81
showing the columns, 82
resolved document for editing, 88 G
Resource Manager, 69 generated text, 19
adding existing topics, 71 graphic icon
adding multiple topics, 73 Document Map, 12
adding new topics, 69 graphics
adding topics with drag and drop, inserting, 32
75 scaling, 32
adding web pages, 76
updating references, 86
Document Map, 12 H
collapse icon, 12 help, 20
components, 12 HTML
element icon, 12 saving documents as, 37
expand icon, 12
graphic icon, 12
modify attributes icon, 12 I
navigating in, 17 icons
table icon, 12 collapse, 12
documents element, 12
change tracking, 37 expand, 12
comparing, 38 graphic, 12
creating new, 24 modify attributes, 12
saving, 24 table, 12
drag and drop IDs
tag with content, 17 DITA, 53
text, 17 index terms
adding, 61
E inserting
attributes values, 31
Edit view, 12 graphics, 32
element icon links, 30
Document Map, 12 symbols, 33
expand icon tables, 35
Document Map, 12 tags, 24
Quick Tags, 24
text entities, 29

92 Tutorial
Inserting S
content, 24
sample document
opening, 12
L searching
for content, 34
links
for tags, 34
adding, 57
sections
inserting, 30
DITA, 51
spelling
M check, 36
modify attributes icon check automatically, 36
Document Map, 12 Split bar, 12
structure
in content, 28
O structured documentation, 9
overview symbols
structured documentation, 9 inserting, 33

Q T
Quick Tags, 24 table icon
Document Map, 12
tables
R editing, 35
Resource Manager, 54 inserting, 35
content references tags
adding, 59 collapsing, 16
cross references deleting, 19
adding, 55 expanding, 16
DITA maps, 69 finding, 34
adding existing topics, 71 inserting, 24
adding multiple topics, 73 moving, 17
adding new topics, 69 text entities
adding topics with drag and drop, inserting, 29
75
adding web pages, 76 U
images
adding, 58 Undo button, 19
links
adding, 57 W
references
modifying, 60 window

Index 93
 components, 12
Document Map, 12
Edit view, 12
menus, 12
Split bar, 12
status bar, 12
toolbars, 12

94 Tutorial