DITA CMS User Guide OXygen

DITA CMS User Guide for
oXygen
WWW.IXIASOFT.COM / DITACMS v. 4.2 / Copyright 2016 IXIASOFT Technologies. All rights reserved.
Last revised: July 19, 2016
Table of contents 3
Table of contents
Preface: Introduction
Copyright notice 29
Technical support 29
DITA CMS documentation 30
New in this documentation release 31
Chapter 1: About DITA
DITA topics and maps 36
Benefits of DITA 36
DITA components 37
DITA CMS functionalities 38
Chapter 2: Understanding the DITA CMS document cycles
About document cycles 42
Document development process 43
Document status dependencies 46
User roles and timelines 47
Chapter 3: Starting the DITA CMS
Log in to DITA CMS 50
Log in to DITA CMS from Eclipse clients with preconfigured settings52
Open an Eclipse Perspective 54
Chapter 4: The DITA CMS working environment

4 DITA CMS User Guide for oXygen
Open the DITA perspective 58
Icons and colors 59
List of icons 60
The DITA CMS toolbar 61
Show or hide the workspace toolbar 63
Configure column display in any DITA view 63
Display or modify connection information 64
Reset connection 66
About views and editors 67
Show views 68
Other useful views 70
Documents view 70
Display recent documents and recent operations 71
Filter Recent Operations display 73
Clear the Recent Documents panel 74
Add documents to your Favorites list 75
Display Favorites 75
Manage your Favorites list 76
Remove entries from the Favorites panel 77
Associate file extensions with applications 77
Working with views and editors 80

Table of contents 5
Maximize, minimize, or restore a view 81
Restore a single view 82
Restore a stack of views 82
Refresh a view 82
Clean all views 83
Other DITA CMS perspectives 83
Synchronize configuration files 85
Chapter 5: DITA CMS Search
Search view enhancements 88
Search for documents 89
Search example: Searching for a specific topic type 94
Search example: Searching for a DITA element 95
Search example: Searching for a specific element 96
Advanced Search features 96
Advanced Search example: Using multiple criteria 102
Advanced Search example: Using the without operator 105
Date search features 107
Search for documents that contain taxonomy terms 109
Search the XML content of a map 110
Search within a sub-tree 111
Search and replace the XML content of a map 112

Apply XSL transformations to one or more topics 116
Select the current topic in a map 118
Standard search operators and wildcards 118
Search Results view operations 121
Create search results groupings 123
Apply groupings to search results 125
Search within search results 126
Isolate appended search results 128
Locate errors 130
Configure search 131
Set default search parameters 131
Restore search defaults 132
Customize the Search view layout 132
Working with queries 133
Create a query 133
Run a personal query 134
Run a TEXTML query 135
Re-run a recently executed search 136
Edit a personal TEXTML query 137
Delete a personal query 137
Shared queries 138

Table of contents 7
Chapter 6: DITA maps
About DITA Map view and DITA Map Editor 143
Topic alert indicators in the DITA Map view and DITA Map Editor 145
Map sub-trees 146
Create a map 147
Map ID naming constraints in DITA CMS 150
Open a map in the DITA Map view 150
Open a map in a DITA map editor 150
Switch editors 151
Open a map from the map history list 151
Print a map 152
Pre-publication flags 152
Export map as TSV 153
Edit a map 154
Resolve all the topics in a map 154
Preview a map 156
Adding and positioning topics in a DITA map 157
Drag documents into a map 157
Add a topic to a map from the XML editor 158
Move a document within a map using drag and drop 158
Promote a document in a map 159

Demote a document in a map 160
Move a document up or down in a sub-tree 161
Define a map drop point 162
Add documents to a map using drop points 162
Displaying topic titles in the DITA Map view 163
Using the navtitle element with the locktitle and href attributes 165
Rename a DITA 1.1 map 167
Rename a DITA 1.0 map 167
Remove a document from a map 168
View map statistics 168
Advanced DITA Map view features 170
About Advanced DITA Map view features 170
Clear the History list 171
Display map elements 172
Add an element to a map 172
Edit map element attributes 173
Change a map element 173
Create a topic stub 174
Generate topic stubs 174
Validate out-of-scope links 176
Chapter 7: Document management

Table of contents 9
Lock a map, topic, image, or resource 180
Release a locked map, topic, or image 180
Release all subtopics for a topic 183
Clone a map, topic, or image 183
Display document object properties 185
Change status 187
Delete a document object 189
Restore a document object 190
Synchronize configuration files 190
About the Information view 191
View information about selected objects 191
Disable update of the Information view 192
Chapter 8: Revision control
Replace with server revision 194
View revision history 194
View a previous revision 196
Revert to older revision 196
Compare documents 197
DITA CMS file comparison utilities 197
Compare two revisions 198
Compare with latest server revision 198

Compare selected documents 199
Compare with authoring source 199
Compare with published source 199
Export children intersection 200
Compare with previously published version (redlining) 201
Chapter 9: Topics
Create a topic 204
Open a topic 205
Open a topic with a specified editor 206
Switch editors 206
Preview a topic 206
Turn off thumbnail display 208
Rename a topic 208
Edit a topic 209
Add a topic to a map from the XML editor 209
Spell checking maps and documents 210
Check the spelling of topics and maps 211
Chapter 10: Creating links
Relationship tables 216
Open the Reltable Editing Perspective from the DITA Map view's menu 216
Open the Reltable Editing Perspective from the main menu bar 216
Table of contents 11
The Reltable Editing Perspective 216
Construct relationship tables 218
Configure relationship tables 225
Locate reltable rows where a topic is used 229
Filter reltable rows in the Table Display area 232
Relationship table examples 233
Creating cross-references (xref) 245
Create a cross-reference to another topic 245
Create a cross-reference to an external file or web site 246
Troubleshooting unresolved cross-references 247
Chapter 11: Referencing other files
Inserting images 250
Insert an image into a topic 250
Insert an image from a remote location into a topic 250
Create related links from one topic to another 251
Create related links to external files or web sites 252
Copy document reference 253
Copy ID 254
Copy full path 254
Copy the element ID 255
Chapter 12: Viewing where documents are used

About the Dependencies view 258
View a document's dependencies 259
Enable update of the Dependencies view 260
Filter the Dependencies view 260
Export Dependencies as TSV 261
Chapter 13: Working with resources
About resources 264
Create a resource 264
Add an item to a resource 267
Set the default resource 268
Edit resource metadata 268
Edit a resource item 269
Creating soft links 270
Remove soft links 271
Prerequisites: Adding soft link indexes 272
Add a resource directly to a map 272
Chapter 14: Images
Working with images 276
Image resolutions and formats 277
Create an image 278
Preview an image 281

View image thumbnails 282
Turn off thumbnail display 282
Open an image 283
Add an image directly to a map 283
Set the default image 283
Edit image metadata 284
Replace an image 285
Edit an image 286
Export images 287
Chapter 15: Offline work
About the Offline Perspective 290
Work offline 290
Offline functionality summary 291
Refresh the Offline Documents view 291
Filter the Images view 292
Return from the Offline Perspective 292
Chapter 16: The oXygen Editor
oXygen quick reference 294
Referencing other files in the oXygen editor 294
Create a cross-reference to another topic 295
Create a cross-reference to an element within the same topic 295

Create a cross-reference (xref) to a file or web site in the oXygen editor 296
Insert related links into a topic in the oXygen editor 298
Insert related links to files or web sites in the oXygen editor 299
Insert an image into a topic in the oXygen editor 300
Insert an image from a remote location into a topic in the Oxygen editor 301
Chapter 17: Document assignments
Assign documents to users 304
Set document due dates 306
Set document approval systems 308
View document assignments in the Todo List 310
Add comments to DITA CMS assignments 311
Chapter 18: Document labels
Add a label category 314
Assign labels to documents 315
Remove labels from documents 316
Manage document labels 317
Rename labels and categories 317
Delete labels and categories 317
Add a label to a category 318
Chapter 19: Collaborative Reviewer
About the Collaborative Reviewer 322

Review content 323
Refresh the current document 324
Attach a file to a review PDF 325
Vote on a document 325
Revise annotations 326
View previous reviews 327
Electronically sign a document 328
Working with annotations 329
Modify annotations 329
Copy annotations 330
Move or resize annotations 331
Delete annotations 331
Hide annotations 331
Insert a new See-note 332
Insert See-note number 333
Chapter 20: Profiling and conditional processing
About conditional attributes 338
About conditional topics 338
Set conditions on objects in a map 339
Identify all conditional objects in a map 340
Review conditional values on a map object 342

Preview which topics are included in a map with conditions 342
Set conditional text attributes in the oXygen editor 344
Preview a topic 345
Using Ditaval files for conditional processing 347
Create a Ditaval file 348
Create a Ditaval folder 352
View a ditaval file 353
Edit the XML contents of the Ditaval file 354
Review Ditaval values 355
Edit a Ditaval file 355
Filter the ditaval files in the Ditaval view 356
Delete a Ditaval file or folder 356
Copy the reference of a Ditaval file 356
Chapter 21: Snapshots
Understanding the Snapshots feature 358
Create a snapshot 361
Generate the output of a snapshot 363
Branch a snapshot 363
Publish a snapshot 364
View the contents of a snapshot 364
Chapter 22: Branching

About branching 368
Branching indicators 369
Create a new branch 370
Branch sub-map(s) 371
Branch topic(s) 371
Branch documents 372
Branch images 373
Branch conrefs 374
Branch resources 375
Revert to published version 376
Merge with authoring 376
Mark as merged 378
Chapter 23: Using conrefs and keyrefs
Conref and keyref best practices 380
Creating and using conrefs 381
Create a reusable component (conref) 382
Create a referable_component_library map 384
Search for reusable components (conrefs) 384
Insert a reusable component (conref) in oXygen 385
Keyrefs and keydefs 386
About keyrefs and keydefs 386

Automatically resolve keyrefs 387
Add keydef example 388
Add keys to a map from preset list defined in the Content Store 390
Inserting a keyword or external link from keys defined in the map 391
Edit keydef actions 392
Keydef representation in the DITA Map view and editor 398
Chapter 24: Import and export documents
Importing content as read-only 401
Import Ditaval files 401
Import images 405
Setting the image description when importing images 408
Import multiple resolution images 409
Import maps 412
Import topics 417
Reimporting the same file into the DITA CMS 421
Troubleshooting import errors 422
Export content from the DITA CMS 423
Chapter 25: Taxonomies
About Taxonomies 426
About the Taxonomy Terms view 426
Open the Taxonomy Terms view 429

Creating and modifying taxonomies 430
Create a new taxonomy 430
Add a taxonomy term to a taxonomy 430
Edit taxonomy terms 431
Remove taxonomy terms from a taxonomy 432
Delete a taxonomy from the Taxonomy Terms view 432
Import a taxonomy from a TSV text file 433
Managing taxonomy terms within documents 434
View which taxonomy terms a group of documents contains 434
Add taxonomy terms to multiple documents 435
Remove a taxonomy term from multiple documents 436
Remove documents listed in the Taxonomy Terms view 436
Add taxonomy terms to a single document as keywords 437
Add taxonomy terms to a single document as metadata 437
Locating documents with taxonomy terms 438
Find the location of a taxonomy term within a taxonomy 438
Search for documents that contain taxonomy terms 438
Chapter 26: Project management
Project Management view 442
Project and deliverable highlight colors 443
Deliverable-specific highlights and icons 445

Team overload indicators 448
Initial project setup and other related tasks 450
Create a project 450
Set project due date 451
Project status 452
Change project status 453
Clone a project 453
Change project name 454
Set project defaults 454
Specify default translation languages 455
Remove default translation languages 456
Set the default approval systems 456
Remove default approval systems 457
Add default milestones 457
Modify default milestones 459
Modify default milestone comments 459
Record default milestone completion dates 460
Remove default milestones 460
Manage project personnel 461
Change project coordinator 461
Add members to the team 461

Remove team members 463
Set default role assignments 463
Remove default role assignments 464
Manage project deliverables 465
Add a deliverable to a project 465
Open a map from Project Management view 466
Remove deliverables 466
Add map-specific milestones 466
Modify map-specific milestones 468
Modify map-specific milestone comments 469
Record map-specific milestone completion dates 469
Remove map-specific milestones 470
Specify targeted translation languages for a deliverable 470
Remove targeted translation languages 472
Use the Bulletin Board 472
Add a message to the Bulletin Board 472
View message details 473
View project statistics 473
View map statistics 473
View statistics for all maps 474
View project milestone statistics 475

Team overload indicators 476
Delete a project 478
Chapter 27: Creating and generating reports
Understanding reports 480
Create viewpoints 481
Use viewpoints in search results 484
Create a TEXTML Server query 485
About reports 486
Create a report 490
Generate a report manually 495
Generate reports using the Scheduler 496
Chapter 28: BIRT Reports
Install the BIRT feature 498
Preparing data for use with the BIRT Report Designer 499
Overview of the BIRT report process 499
The Data Set Definition dialog 499
About the columns in the Data Set Definition dialog 500
Supported Data Set Definition dialog operations by column 501
Available filters in the Data Set Definition dialog 502
Auto-generated columns in the BIRT (and DITA CMS) data sets 503
Create the DITA CMS data set definition 505

Modify a DITA CMS data set definition 506
Create the DITA CMS data source 507
Create a new BIRT project 508
Create a new BIRT report 508
Obtain data source directory location 509
Create a new BIRT data source 510
Create a new BIRT data set 511
BIRT example one: generating a report 512
BIRT example one: TEXTML query 512
BIRT example one: DITA CMS data set definition 513
BIRT example one: DITA CMS data source 514
BIRT example one: BIRT data source 515
BIRT example one: edit BIRT data set 516
BIRT example one: preview BIRT data set 517
BIRT example one: incorporate data into report design 518
BIRT example one: final output 520
BIRT example two: using stamp information 521
BIRT example two: the DITA CMS data set definition 521
BIRT example two: the DITA CMS data source 522
BIRT example two: the BIRT data set part 1 523

BIRT example two: the complete data set 526
BIRT example two: final output 527
Chapter 29: Relationship tables
Open the Reltable Editing Perspective from the DITA Map view's
menu 530
Open the Reltable Editing Perspective from the main menu bar 530
The Reltable Editing Perspective 530
Construct relationship tables 532
Add a reltable to a map 532
Add a pre-configured row to a reltable 533
Add an unconfigured row to a reltable 535
Add a typed cell to a reltable row 535
Add an unconfigured cell to a reltable row 535
Assign a name to a reltable 536
Assign a name to a reltable row 536
Add a topic to a reltable cell 537
Add a topic and its children to a reltable 537
Insert a topic group into a reltable cell 537
Remove a row from a reltable 538
Remove a cell from a reltable row 539
Configure relationship tables 539

Change the type of a reltable cell 539
Change the collection-type of a reltable cell 540
Change the collection-type of a topic group 541
Set linking direction 542
About linking direction in relationship tables 543
Locate reltable rows where a topic is used 544
Filter reltable rows in the Table Display area 546
Relationship table examples 548
Reltable example one: CRT row structure 548
Reltable example one: CRT row output 550
Reltable example two: links are between cells – not within cells 551
Reltable example three: linking topics of the same type 553
Reltable example four: linking direction 555
Reltable example five: creating sequences 556
Chapter 30: Production
Publish 562
Archive a published map 563
Generate output 563
Using conditions in the Output Generator 567
Chapter 31: Using the Build Manifest feature
Understanding the Build Manifest feature 570

Create a Build Manifest 571
Set default values for ditaval files, languages, and user parameters 576
Add and configure output types 577
Output a Build Manifest 580
Search for a Build Manifest 582
Chapter 32: Localizing documents with the DITA CMS
About localization 586
DITA CMS localization models 589
Sequential localization model 590
Concurrent localization model 593
Prepare a pre-localization kit 595
Start the localization process 596
Prepare an image localization kit 597
Prepare the localization kit 598
Import localized images 601
Import a localized map or topic 601
Retranslate from source 603
Reset text that was auto-translated 604
Chapter 33: Workspace configuration
Set file search maximum 606
Associate editors with documents 606

Configure key mapping 608
Customize menu visibility 608
Customize toolbar visibility 609
Enable Eclipse command groups 609
Clear files from your hard drive 610
Clear information from the cache 611
Synchronize image thumbnails 611
Enable the Read-only Editor 612
Specify compare tool 612
Configure import and export directories 613
Add the root-catalog.xml catalog to the oXygen editor 615
Configure column display in any DITA view 617
Restore warning messages 618
Bring a process out of background 618
Glossary
DITA CMS shortcut keys

Introduction
DITA CMS is a documentation solution that combines the mechanics of an extensible environment,
a powerful Content Management System (CMS), and the elegant modularity of DITA. The
application was developed for the Eclipse IDE and is delivered as a plug-in that connects
IXIASOFT’s TEXTML Server with users working with DITA XML files. The result is an efficient
workspace from which text-based documents such as DITA topics and maps, as well as binary
image files, can be authored, managed, tracked, and published.
The union of DITA architecture and a CMS provides tremendous control and flexibility for managing
structured units of information. This evolution for technical documentation lets users:
• Work modularly
• Modify and track documents through a well-defined workflow
• Repurpose content for required markets and audiences
• Manage the localization process
• Deliver documentation in a variety of different formats
• Work in a collaborative environment
• Improve consistency in content structures
• Re-use content in multiple deliverables
Copyright notice
©2011-2016 IXIASOFT Technologies Inc. All rights reserved. Except as otherwise expressly
permitted by IXIASOFT Technologies Inc., this publication, or parts thereof, may not be reproduced
or distributed in any form, by any method, for any purpose.
This publication and the information contained herein are made available by IXIASOFT
Technologies Inc. "as is." IXIASOFT Technologies Inc. disclaims all warranties, either express
or implied, including but not limited to any implied warranties of merchantability or fitness for a
particular purpose regarding these materials.
Technical support
IXIASOFT customer support staff are available to answer your questions. We welcome your
comments.
You can reach us at:
IXIASOFT
825, Querbes
Suite 200
Montreal, Quebec H2V 3X1
Phone: +1 514 279-4942
Fax: +1 514 279-3947
Toll free in North America: 1-877-279-IXIA
Email support-DITA@ixiasoft.com
DITA CMS documentation

You can find the complete DITA CMS documentation set at the following location:
http://www.ixiasoft.com/en/products/dita-cms/documentation/4-2/
This document set includes the following documents:
Table 1: DITA CMS documentation
Document Description
Introduction to DITA CMS Provides an overview of DITA CMS concepts and

functions.
DITA CMS User Guide Provides procedures and reference information for
technical writers and other documentation team
members who use the DITA CMS on a daily basis.
DITA CMS Administrator's Guide Provides procedures and reference information for
administrators responsible for configuring the DITA
CMS application and customizing it for the specific
workflow of their documentation teams. Intended for
CMS administrators.
Planning a DITA CMS Deployment Provides the information required to plan a DITA CMS
deployment. Intended for IT personnel and CMS
administrators.
Installing the DITA CMS Eclipse Client Describes how to package and deploy the DITA CMS
Eclipse Client on user workstations and in remote
access solutions. Intended for CMS administrators.
Introduction 31
Eclipse help
The DITA CMS User Guide is also available as Eclipse help. To display the documentation:
1. In the DITA CMS client, select Help > Help Contents.
The Help - Eclipse SDK window is displayed.
2. If you are using XMetaL as your XML Editor, click DITA CMS User Guide for XMetaL. If you
are using oXygen, click DITA CMS User Guide for oXygen.
The DITA CMS User Guide is expanded and the table of contents is displayed.
New in this documentation release

Build 4.2.45
• Changes have been made to the Branch and Clone features. Branched objects will now
contain the same ID as their source objects. Clone objects must now contain unique IDs so
the option Use same ID has been removed form the Clone dialog box, see Clone a map,
topic, or image on page 183.
• Since the Visible checkbox on the Message dialog box had no effect, it has been removed
from the interface. Therefore, two topics related to that feature have been removed from the
Bulletin Board section, see Use the Bulletin Board on page 472.
• Small change in the .zip file when preparing a localization kit for sequential localization, see
Prepare the localization kit on page 598.
• You can now open a ditaval in a read-only mode in the XML editor area, see View a ditaval
file on page 353.
Build 4.2.38
• Added a new topic about how to log in to the DITA CMS Eclipse client with preconfigured
settings, see Log in to DITA CMS from Eclipse clients with preconfigured settings on
page 52.
• Added a topic for the Copy Element ID feature, which allows you to copy the ID of an element
from a topic in the Referable-Content view. For more information, see Copy the element ID
on page 255.
• Updated the instructions for inserting variables or external links into a topic from a map to
reflect the enhancements made to the Insert Variable dialog box. Variables are organized by
the map in which they are defined and they can also be filtered by name or value. See Inserting
a keyword or external link from keys defined in the map on page 391.
• In the Assignments dialog box, deactivated users no longer appear in the Assignee pane
unless they are still assigned to a document. for more information on assigning documents to
users, see Assign documents to users on page 304.
• The labels for DITA CMS > Label Configuration in the main menu, the Manage Label
Configuration button on the main toolbar, and the Manage Label Configuration dialog box
have all been changed to Configure Labels, see topics in Document labels on page 313.
Build 4.2.34
• Clarified the note about converting older ditaval files to valid format. See Edit the XML contents
of the Ditaval file on page 354.
Build 4.2.33 updates
• The Dependencies view can now be refreshed by clicking the Refresh button, see Refresh
a view on page 82.
• Added a new icon (broken link icon) to the List of icons on page 60.
• The Insert Variable dialog box now displays the current and default values of the keys. See
Inserting a keyword or external link from keys defined in the map on page 391.
• Removed topic "Configure conditional text attributes in the oXygen editor" since it is no longer
needed now that profiling attributes values for conditional processing are defined in a
configuration file.
• Variables now available in map templates, see Create a map on page 147.
• Added a note explaining that localized content must be in the Localized:done state to be output
with a Build Manifest. See Output a Build Manifest on page 580.
• The child intersection report has been fixed to display the authoring revision number of the
reported child objects instead of marking them with an "X", see Export children intersection
on page 200.
• Added a new topic describing a new menu option available in the DITA Map view to allow
users to insert keys from a preset list into their maps. See Add keys to a map from preset
list defined in the Content Store on page 390.
• Added a new topic describing two new menu options for inserting keys defined in a map into
a topic. See Inserting a keyword or external link from keys defined in the map on page
391.
Introduction 33
• The wizards used to import files as external documents in a read-only state have been removed
and replaced by a checkbox called Import As External in the standard import wizards, see
Import and export documents on page 399.
• By default, the Pin Content button is now always enabled in the Dependencies view. See
Enable update of the Dependencies view on page 260 for more information.
• Added a new topic: Export content from the DITA CMS on page 423.
• Added a note to the procedure View document assignments in the Todo List on page 310
indicating that the Todo List must be refreshed manually.
• Fixed spelling error in the originalRelativePath index name.
• Added a note indicating that drop points are valid until a new map is opened in the DITA Map
view. See Define a map drop point on page 162.
• Added a note indicating that the Validate Links command also checks links in reltables. See
Validate out-of-scope links on page 176.
• Updated the following procedures to indicate that a snapshot must be in the the Authoring:done
status before it can be published or branched:
• Branch a snapshot on page 363

• Publish a snapshot on page 364
• Several updates to ditaval topics:
• Documented passthrough and flag actions in Create a Ditaval file on page 348.
• Added new topic describing filter in the Ditaval view, see Filter the ditaval files in the
Ditaval view on page 356.
Build 4.2.29 update
• Added the procedure to Reset text that was auto-translated on page 604.
• Added a use case for searching the Content Store: Search example: Searching for a specific
element on page 96.
• Reorganized and edited the following sections for clarity:
• Referencing other files on page 249

• Viewing where documents are used on page 257
• Using conrefs and keyrefs on page 379
• Removed the procedure for synchronizing working documents since this feature is no longer
supported.
DITA CMS 4.2 updates
• You can now create and generate reports using the DITA CMS . See Creating and generating
reports on page 479.
• The following taxonomy features were added:
• Delete a taxonomy from the Taxonomy Terms view on page 432.

• Import a taxonomy from a TSV text file on page 433.
• When importing images, the DITA CMS now uses information from the source topic to set the
image description that is saved in the DITA CMS. See Setting the image description when
importing images on page 408.
• Multiple improvements were made to the document assignments:
• The Assignments dialog was updated to improve usability. See Assign documents to
users on page 304 and Set document due dates on page 306.
• Additional options were added to view your documents in the Todo list. See View document
assignments in the Todo List on page 310.
• You can add comments to DITA CMS assignments. See Add comments to DITA CMS
assignments on page 311.
• Other minor enhancements:
• Autorefresh in map view - Selecting a map from the history list now automatically opens
the map in the DITA Map Editor.
• Partial synchronization is now always enabled - Partial synchronization is now always
enabled to improve the performance of the DITA CMS. As such, the synchronization page
has been removed from the DITA CMS preferences. Options that were on the synchronization
page were moved to other pages. For more information, see:
• Clear information from the cache on page 611

• Clear files from your hard drive on page 610
• Synchronize image thumbnails on page 611
• Export search results - You can export search results and save them in a file outside the
repository in three different formats: Tab Separated Value (TSV), Extensible Markup
Language (XML), and Spreadsheet (XLS).
1 About DITA
About DITA
Topics: Darwin Information Typing Architecture (DITA) provides a

• DITA topics and maps topic-oriented content architecture built on XML technologies.
• Benefits of DITA The DITA standard focuses on modular content creation,
• DITA components which provides the technical documentation community with
• DITA CMS functionalities
an efficient way to create, update, and manage topic-driven
documents.
This set of topics introduces DITA and lists the DITA CMS
functionalities.
DITA topics and maps

The basic unit of information in DITA is called a topic. A DITA topic represents a single piece of
information that can stand alone. Topics can be reused in different document deliverables as
required.
Document deliverables are controlled and managed by DITA maps. DITA maps are files that
collect and organize references to DITA topics to indicate relationships among the topics; they
basically make up your table of contents.
Figure 1: DITA topics and maps
Benefits of DITA
Organizations are adopting DITA to improve productivity, content accuracy, content repurposing,
and ultimately reduce costs.
A documentation solution based on DITA has many advantages:
About DITA 37
• Increase productivity
• Enable better collaboration for faster delivery

• Distribute work so writers can work in parallel, thanks to topic-driven architecture
• Provide for easy topic reuse without any further manipulation
• Reuse content
• Reuse topics in different projects

• Generate summaries and overviews automatically from structured content
• Repurpose content
• Deliver content in multiple formats

• Re-assemble topics freely to produce customized output
• Target information according to user type and user context
DITA components
Document deliverables include several types of documents.
The following types of documents are used to produce document deliverables.
• DITA Maps display the topic structure of the document deliverable like a table of contents.
Used with features such as conditions and conrefs, they provide you with a powerful way of
re-organizing topics into different types of deliverables.
• Images add a graphic dimension to document deliverables. Images are not added to maps
directly like topic files. They are referenced by the topics you want them to appear in.
• Topics are designed as stand-alone units of information that can be reused in different
document deliverables. They are organized into different types, which are defined by XML
templates. Each type is designed to present a specific kind of information. This provides
guidance to authors on how to organize content with consistency.
Topic Types Description
Concept The concept topic type is for topics that answer the question "what is?",
and sometimes "why?". Concepts often define functionality and/or the
purpose of a feature. They may also explain background information
necessary for understanding the context of use.
Reference Reference topics should contain quantified information about a specific

thing: a product version, technology implementation, or design.
Topic Types Description
Task Tasks answer the question “how?”. They provide step-based instructions
that tell the user how to achieve a specific goal.
Referable-content The referable-content topic type is an IXIASOFT specialization. It is

designed to hold the target text for conrefs – that is, a block of text that
is referenced from many different other topics.
Glossentry A glossentry topic is designed to contain an individual term together

with its definition. This lets you assemble individual definitions into a
final Glossary chapter, thus avoiding conditional phrases.
Topic This is a more generalized type of topic, which is not oriented towards
specific content.
DITA CMS functionalities

DITA CMS is intended for content developers, subject matter experts, communication
representatives, and anyone else who needs hands-on involvement in the document development
life cycle.
DITA CMS is a modular, document-oriented solution based on TEXTML Server – IXIASOFT’s
flagship XML content management product – which allows full use of the DITA standard.
Designed for use with Eclipse (an open-source development toolset), DITA CMS provides a
graphic representation of the file structure and full support of the document life cycle. This
extensible XML content management platform was designed with flexibility in mind to bring
customized solutions within easy reach of content developers.
At the heart of DITA CMS, TEXTML Server provides a robust document repository and advanced
searching capabilities. TEXTML Server’s core architecture and repository were designed to
support XML components natively, making it an ideal platform to manage DITA’s topic-oriented
structure.
Features integrated in DITA CMS include:
• DITA map builder

• Status management
• Version control
• Review process
About DITA 39
• Workflow support
• Image support
• XML templates for standard topic types
• Ditaval support
• Localization management
• Output generation
2 Understanding the DITA CMS
document cycles
Understanding the DITA CMS document cycles
Topics: Documents go through several phases of development.

• About document cycles Topics, for example, are written, edited, and approved by
• Document development technical experts, and then may be sent for translation. Each
process phase of document development has a unique set of people
• Document status who are responsible for the document in that phase.
dependencies
• User roles and timelines This set of topics describes the document cycles and provides
detailed information on the document development process,
status dependencies, as well as user roles and timelines.
About document cycles

DITA CMS has established a formalized cycle that ensures that document development stays
aligned and on track as topics, maps, and images are passed back and forth among the various
users.
Cycles
Cycles establish the larger framework for document development. For example, organizations
typically set up an authoring cycle and may also set up a localization cycle that applies to maps,
documents, and images. In a typical document cycle, content may be created by an author,
approved by subject matter experts (SMEs), and then revised by the editor before being sent off
for translation.
States and status
States identify the status of documents or images at each point in the cycle. For example, the
review state for a document or image means that it has been submitted to SMEs for review. A
document's cycle and state, written together, define its status; for example, Authoring:review.
Moving from one status to another (i.e., status promotions and demotions) is done by the system
users. The figure below provides a graphic example of documentation cycles and the states
comprising them, which you can adapt as needed within your DITA CMS.
Understanding the DITA CMS document cycles 43
Figure 2: Documentation process cycles and states
Related Links
Change status on page 187
Document development process

A document goes through multiple phases before it is published. For example, content may be
created by an author, approved by subject matter experts, and then polished by the editor before
being sent off for translation. The exact scenario varies with the installation.
But whatever the exact scenario your company uses, documents of all types—images, maps
and topics—go through distinct cycles that roughly correspond to the major cycles of DITA CMS.
Important: The cycles and states described here are those implemented at IXIASOFT
Technology. Yours are likely to vary in their specifics. Please contact your CMS
administrator for the specifics of your deployment.
Cycles
Document cycles establish the larger framework for document development.
• Authoring—Each document type has its own distinct set of stages in the Authoring cycle.
• Images/Resources—Graphic artists create, modify, and finalize images. Team members

locate resources (background material not directly utilized by the document deliverable)
and add them to resource packages.
• Topics—Authors develop, edit, and finalize content.
• Maps—Information architects and authors develop map structure and add topics to it. The
project is globally reviewed for inconsistencies and incompleteness.
• Localization—Translators produce different language versions.

• Published—A release version is created where content is kept unaffected by future changes.
Official output may be generated from this location in a number of different formats for
distribution.
States
Within each cycle there are several different states—such as work and review—that identify the
multiple actions performed on content at every level of development. Document states track
content within the different cycles.
Figure 3: Within each cycle there are several different states
Status
A document's cycle and state, written together, define its status, e.g., Authoring:review. The
document's status tracks its progress though the various cycles of the document life
cycle—Authoring, Localization, and Published—and offers further control over the process by
breaking each cycle into states.
When a topic or a map is created (or when an image is imported), it is assigned the status
Authoring:draft. From that point on, status promotions (and demotions) are done by the system
users. The files go out for review and are either accepted (and pass on into another cycle) or are
found incomplete and demoted for further clarification and development.
Document status dependencies

A document's status reflects the status of its referenced files.
Note: DITA CMS may be configured so that status dependencies are overridden. In this
case if a topic is accepted (and promoted), this may automatically promote the topic's
children (conrefs, images, etc.).
Topic, map, and image status depend on the status of the topics or images they reference. In
the diagram below, Map A references Topic A and Topic B. Topic B, in turn, references Image
X.
Documents in the Authoring cycle
In the topic's portion of the Authoring cycle, topics may not be at a higher state than the topics
they reference, whether by xrefs, conrefs, or related links.
Topics are also constrained by the state of their referenced images. A topic cannot advance past
Approved until all its referenced images are Done.
Maps in the Authoring cycle have a slightly different set of constraints. They must stay in the
Draft state until all the topics they contain have reached Review. At that point a map may be
promoted to its own Review state. It must stay in Review until all its constituent topics are Done.
Only when all topics are Done can a map be promoted to Final review. And since topics may not
be considered Done until all their images have reached that state, this means that all of a map's
constituents—images as well as topics—must be in the Done state before the map may be
promoted to Final review.
Documents in the Localization cycle
In the Localization cycle, a map or topic may only move as high as the images or topics that it
contains. This means that you cannot promote a map to Review until after you have promoted
its topics to that state. In the same way, topics must wait until their referenced images reach
Review before they can be promoted to that state in their turn.
Document dependencies
To make sure that these dependencies are respected, the system performs some simple checks
when a user is changing a file's status and only offers the choices that make sense.
This file type Depends on
Map • Its topics
Topic • The topics it conrefs

• The images it contains
Image N/A
Note: Before you can publish or localize a map all its child documents must be Done,
including those referenced by conrefs or related-links.
User roles and timelines

Administrators configure roles and timelines to help DITA CMS documentation team members
manage the documentation cycle.
Roles define the responsibilities of various members of the documentation development team.
Each part of a documentation project—topics, maps, images, and resources—has its own set of
users who work on it at different points in its development. The DITA CMS keeps track of the
user roles and their relationship to each other and to the document's status, as the document
moves through its life cycle.
User responsibilities
To illustrate the concept of roles, let’s say that an organization identifies three user roles with
regard to topics: Author, Reviewer, and Editor. In a typical project scenario, an Author writes
a topic and sends it to the Reviewer to be appraised. If the Reviewer requests changes, the topic
goes back to the Author to be reworked and may be yet again submitted to the Reviewer for
approval.The topic might then be passed to an Editor for proofreading and then finally re-submitted
to the Author for publication. Roles vary from organization to organization. Larger companies
typically have more roles and more stages in the documentation process, while in small companies
one person may fill several roles.
Timelines
Timelines correspond to the degree of involvement that a user role has at any given point in the
document life cycle, as shown in the table below. There are five main timeline states:
• Active: Tasks will be active for this user role at this point in the document cycle.
• Incoming: Tasks are pending for this user role at this point in the document cycle.
• Retained: Tasks will be passed back to this user once another user has finished them.
• Done: The user has completed the work on this document.
• Out of scope: The document is out of scope for this user role.
For example, when a writer is working on a document, the document is active for this user, but
incoming for reviewers and editors. When the writer hands over the document to a reviewer, the
document is retained for the writer (since there might be more work to be done by the writer on
this document after the review, so the writer retains a certain amount of responsibility), active for
the reviewer, and incoming for the editor.
Topic status Timelines
Author Reviewer Editor
Authoring:work Active Incoming Incoming
Authoring:content/review Retained Active Incoming
Authoring:edit/review Out of scope Out of scope Active
Authoring:done Done Done Done
Status and email notifications
Each time a document's timeline status changes, it triggers events in the system that keep users
alerted to document status as it affects their own role in the documentation process. For example,
the DITA CMS can be used to send an email notification to users any time a document becomes
Active for their particular role. Users can view the documents they have been assigned and their
timelines in the Todo List tab within the DITA CMS workspace.
Related Links
Assign documents to users on page 304
Set document due dates on page 306
Set document approval systems on page 308
View document assignments in the Todo List on page 310
3 Starting the DITA CMS
Starting the DITA CMS
Topics: The procedures in this section tell you start the DITA CMS.
• Log in to DITA CMS
• Log in to DITA CMS from
Eclipse clients with
preconfigured settings
• Open an Eclipse
Perspective
Log in to DITA CMS

The first time that you open DITA CMS, or if you are working in a new workspace, you must enter
your access information.
Depending on your confirmation, once the information is validated, you may be logged in
automatically whenever you open DITA CMS from your workstation. If the CMS administrator
has disabled auto-login, you will need to connect to the servers every time that you log in.
Note: If you log in from another workstation, you will need to enter your login information.
You may also need to log in if someone else has logged in to your workstation in your
absence.
Important: If the DITA CMS was configured to launch the DITA CMS Eclipse clients with
preconfigured settings, follow the instructions in Log in to DITA CMS from Eclipse clients
with preconfigured settings on page 52 instead.
To log in to DITA CMS:
1. Open DITA CMS.

2. From the Global Actions menu bar, click the Connection Information button: or
select Window > Preferences > DITA CMS
The Preferences window opens:
Starting the DITA CMS 51
Figure 4: DITA CMS user and connection preferences
3. Enter your user information:

a) Domain: Enter your local domain.
b) Username: Enter your network login name.
c) Password: Enter your network password.
Note: By default, your username and password for TEXTML Server and DITA CMS
are the same as your system username and password.
4. Enter your TEXTML Server connection information:
a) Security: If your deployment is securing communications using SSL, select Use

SSL Connection.
b) Hostname: Enter the name of your TEXTML Server.
c) Port: Enter the TEXTML Server port number (2500 by default). If your deployment
is using SSL, enter the secure port.
d) Document base: Enter the name of your Content Store.
Note: The Major version radio button indicates the current TEXTML Server major
version.
5. Enter the Output Generator information:

a) Hostname: Enter the name of the server hosting the Output Generator.
b) Port: Enter the Output Generator port number (1500 by default).
c) Monitor Port: Enter the local port where output generation progress is sent. Unless
specified otherwise by your CMS administrator, enter 0.
6. Click Apply.
Your access information is saved and for subsequent sessions you will be automatically
logged in.
7. Click OK to close the window.
Note: Logging off is automatic when you close the DITA CMS. DITA CMS remembers
the perspectives you opened for your next work session.
Related Links
Display or modify connection information on page 64
Reset connection on page 66
Log in to DITA CMS from Eclipse clients with preconfigured

settings
When you log in to the preconfigured DITA CMS Eclipse client the first time, it obtains the settings
for the initial working environment from a configuration file. Instead of manually configuring your
environment you can simply enter your password and begin working.
To log in to a preconfigured DITA CMS Eclipse client for the first time:
1. Open DITA CMS.

2. On the Eclipse Welcome page, click Overview.
Figure 5: Example of Eclipse Welcome page
3. Click IXIASOFT DITA CMS.
Figure 6: Example of the Overview page
4. In the Password box, type your password.

Example of the Preferences window with preconfigured settings:
Figure 7: DITA CMS user and connection preferences
5. Click Apply.
6. Click OK.
Open an Eclipse Perspective

If you have never worked with the DITA CMS or if you have been working with another perspective
within the Eclipse Workbench, you will need to open the DITA Perspective.
The DITA Perspective is only one of several offered by DITA CMS. But the DITA Perspective is
the one that offers the basic functionality of creating and editing documents. Once you're familiar
with the DITA Perspective, you may want to take advantage of other specialized perspectives
such as Project Management and Report Design.
1. Open Eclipse.
2. Click Window > Open Perspective > Other... from the menu bar.
The Open Perspective dialog appears.
3. Select DITA.
4. Click OK.
The DITA Perspective opens.

The first time you open DITA CMS in Eclipse you must enter your login information.
Related Links
The DITA CMS working environment on page 57
Project management on page 441
Project Management view on page 442
4 The DITA CMS working environment
The DITA CMS working environment
Topics: This section describes the basic features of the DITA CMS
• Open the DITA perspective working environment.
• Icons and colors Eclipse contains several perspectives that define the layout
• List of icons for different uses of Eclipse. When you first open the DITA
• The DITA CMS toolbar
CMS, you'll see the DITA Perspective. The DITA Perspective
• Show or hide the
is the default working environment for the DITA CMS.
workspace toolbar
• Configure column display
in any DITA view
• Display or modify
connection information
• Reset connection
• About views and editors
• Show views
• Other useful views
• Documents view
• Associate file extensions
with applications
• Working with views and
editors
• Other DITA CMS
perspectives
• Synchronize configuration
files
Open the DITA perspective

A perspective is a set of related views. The DITA perspective is the default working environment
for DITA CMS.
The views are tabbed windows that support specific operations, closely related to the document
development cycles.
Note: You can open additional perspectives from the Perspective Shortcut Bar (see
figure).
To open the DITA perspective:
1. Open the DITA CMS.

2. From the menu bar, select Window > Open Perspective > DITA
Note: If you don't see DITA as an Open Perspective option, select Other > DITA
The DITA Perspective opens. The first time you open DITA CMS in Eclipse you must enter
your login information.
Figure 8: The DITA Perspective
Note:
The DITA CMS working environment 59
You can arrange the DITA Perspective to whatever layout works best for you. Toolbars
at the top of the workspace give you single-click access to many editing and file handling
functions. Changes you make to the DITA Perspective are saved when you log out.
Icons and colors

Icons and text color tell you whether a document is available for editing.
The icons and text color that appear in the various views help you identify which ones are available
for current use:
• Black text indicates a document that is not locked.

• Blue text and a locked icon indicate a document locked by you.
• Red text and a locked icon indicates a document locked by another user.
• Purple text and a locked icon indicates a document locked by you at another workstation.
Related Links
List of icons on page 60
List of icons
The following table provides the complete list of all the document icons that appear in the DITA
CMS.
DITA Map icon. Identifies unlocked maps.
Locked map icon.
DITA Bookmap icon. Identifies unlocked bookmaps.
Locked Bookmap icon.
DITA Map icon with drop point. Identifies a drop point at map-level.
Locked DITA Map icon with drop point.
Topic icon.
Locked topic icon.
Topic icon with drop point. Identifies a topic-level drop point.
Locked topic icon with drop point.
Resource icon.
Locked Resource icon.
Image icon.
Locked image icon.
Broken link icon. Identifies a link to an object that cannot be found in the
DITA CMS or an object whose type cannot be determined.
Snapshot icon.
Build Manifest icon.
Locked Build Manifest icon.
Pre-publication flag. Identifies documents that are about to be published.

Alert indicator. Appears in the DITA Map view and DITA Map Editor.
• In the Status column - identifies documents that prevent the map's
status from moving forward.
• In the Last Mod Date column - identifies documents that have been
worked on since the map reached the final state of the Authoring cycle.
Unresolved keyref. Appears in the DITA Map view and DITA Map Editor.
Keyref resolved with an href. Appears in the DITA Map view and DITA
Map Editor.
Keyref resolved with a keyref. Appears in the DITA Map view and DITA
Map Editor.
Keyref resolved with a null link. Appears in the DITA Map view and DITA
Map Editor.
Related Links
Icons and colors on page 59
The DITA CMS toolbar

This toolbar lets you perform many DITA CMS functions with a single click.
The first section of the toolbar offers many of the general functions such as creating topics and
importing files.
The second section of the toolbar gives you way of quickly performing many useful actions on
the current document in the editor area (the topic or DITA Map Editor that's in front and has
focus).
General functions
Create new topic. Launches the Create Topic dialog.
Create new map. Launches the Create Map dialog.
Create new image. Imports a new image into the repository.
Create new resource. Imports a resource file into the repository.
Clean all views. Resets all views to their original default state, without
rearranging their position in the DITA Perspective.
Connection information. Gives you information about your connection status

and user rights.
Synchronize configuration. Gives you immediate access to the most recent
configuration files on the server.
Import localized images. Imports localized images back into the repository.
Document-specific functions
The functions in this section act on the current document in the editor area – the one that's on
top and has focus.
Show Preview. Opens the Preview view, displaying the current topic.
Select in Map. If the current topic or image is referenced by the map that's
open in the DITA Map view, this button will produce a highlight on it.
Lock. Locks the current topic.
Release. Releases the current topic.
Clone. Clones the current topic.
Assign Labels. Lets you assign a label to the current topic.
View Dependencies. Lets you view the dependencies of the current topic.
Assign to.... Lets you assign the current topic to users, and adjust settings
such as its due date.
Properties. Lets you view system information about the current topic.
Copy. Opens a drop-down which offers the following choices:

• Copy Reference – copies the current topic's file name to the clipboard. For
example, jan1237848217831.xml.
• Copy Full Path – copies the current topic's file name and absolute path
within the TEXTML repository. For example,
/content/authoring/jan1237848217831.xml.
• Copy ID – copies the current topic's root ID to the clipboard. For example,
jan1237848217831.
Compare With. Opens a drop-down that lets you compare the current topic
with other versions of it in the repository: Compare to Latest Server Revision,
for example.
Change Status. Lets you change the status of the current topic.
Generate Output. Lets you generate output from the current topic.
Revision History. Lets you view the current topic's revision history.
Add To Favorites. Adds the current topic to the Favorites panel in the
Documents view.
Open With. Opens a drop-down that lets you open the current topic with one
of the other configured editors.
Show or hide the workspace toolbar

This procedure shows or hides the entire toolbar.
The toolbar provides you with a quick way of performing routine functions such as Save, Release,
View Connection Information, etc. with a single click.
The toolbar across the top of the Eclipse workspace is composed of various function-specific
toolbars. The DITA CMS toolbar, for example, contains buttons that let you synchronize your
documents with the server, and view and reset your connection.
The exact set of toolbars that appears depends on how your workspace is configured, the XML
editor you are using, and the perspective in which you are working.
To use the toolbar:
• To show: From the Window menu, select Show Toolbar.

• To hide: Right-click the toolbar and select Hide Toolbar. This lets you see more of the
workspace.
Configure column display in any DITA view

You can specify the columns you want to see in each view and then place them in the order that
you prefer.
Use this procedure on any view that includes columns of data. To select and arrange the
columns you want to display:
1. Right-click any column header.

The column selection menu appears:
Figure 9: Selecting columns for DITA Map view
2. Select the columns to display and clear those you don't want to see.
The selected columns appear in the view.
3. Drag the columns into your preferred viewing order.
Display or modify connection information

The status of your connection to the TEXTML Server is displayed in the Global Actions toolbar.
You can also modify the connection information as necessary.
To display and/or modify your connection information:
1. In the Global Actions toolbar, observe the Connection Information button.

The button's color indicates your connection status:
(Green icon) You are logged in to TEXTML Server as a recognized user.

Tip: Hover over the button to display a tooltip with your user
name, the server and Content Store connections, and your
user roles.
(Red icon) You are not logged in to the server. You will not be able to search,
lock, or edit documents.
2. To reset the connection, or connect to another server and Content Store, click the
Connection Information button.
The CMS Configuration window appears.
Figure 10: CMS Configuration
3. Enter the connection information.

4. Click Apply.
5. Wait while your connection request is processed.
When your connection is complete, the Connection Information button changes to green ( )
and a confirmation window appears.
6. Click OK to close the Login window.

7. Click OK to close the CMS Configuration window.
Your connection information is saved for the next time you log in.
Related Links
Log in to DITA CMS on page 50
Reset connection
Use this procedure to connect to another Content Store or another server, or as another user.
You need access rights and a password on the server/Content Store you want to connect
to.
This procedure is useful if you have access to more than one server or Content Store, or if you
have more than one user account with different sets of privileges.
1. Do one of the following:
• From the menu bar, click DITA CMS > Reconnect...

• On the Global Actions toolbar, click the Connection Information button
Note: This button's color varies with connection status: it may be red if you are
not connected.
The Preferences dialog opens at the DITA CMS pane.

2. Enter connection information. Ask your system administrator if you're not sure what
is needed here.
3. Click Apply.
A Progress Information dialog appears while the connection is carried out.
A Login dialog appears when the connection is completed.
4. Click OK to close the Login dialog.
5. Click OK to close the Preferences dialog.
Your access information is saved for the next time you login.
Related Links
Log in to DITA CMS on page 50
About views and editors

The DITA Perspective views and editors offer different modes of working with DITA files.
Editors give you direct access to the text of your XML files. Views let you perform specific
operations on specific sets of content resources.
About editors
By default, the center of the DITA Perspective is used for the editor area. When you open XML
files for editing, this is where they appear. You may also be able to have several different files
open in different editors at the same time in the editor area, if your workstation is set up for this.
In addition, when files are in review states, you can open them in the editor area using the
Collaborative Reviewer. This feature displays a PDF preview of a file under review and provides
tools for making annotations in it.
Other editors that are supplied with the DITA CMS include:
• DITA Map Editor - displays an outline view of the document deliverable similar to the DITA
Map view, but without the tag editing features. You can have several DITA Map Editors open
in the pane where your XML editors appear.
• Read-only Editor - displays the selected topic's text and XML tags in read-only mode. This
lets you look at a topic without the risk of inadvertent modifications.
About views
Some views, such as the DITA Map view, show the document deliverable's overall structure.
Others allow you to preview the topic you're working on, or view its properties.
The views include:
• Documents - gives you several document-specific tracking functionalities, such as identifying

recently used documents, or frequently used documents. This view is described later in this
chapter.
• Search - lets you specify the documents types and the cycles in which you want to search.
• Search Results - displays the documents that match your search criteria.
• DITA Map - displays an outline view of the document deliverable corresponding to the table
of contents and offers a set of tag editing features. Only one map can be open at a time in this
view.
• Preview - displays a topic that's open in your XML editor in WYSIWYG format.
• Todo List - displays files that are assigned to the current user, along with their current status
and position on the user's timeline.
• Annotations - displays reviewers' markup and comments. This view appears when the
Collaborative Reviewer is open.
• Votes - lets reviewers vote on documents, and authors view the vote results. This view appears
when the Collaborative Reviewer is open.
• Project Management view - displays information about multi-deliverable projects in a collapsible
tree view.
• Dependencies view – lets you see the documents that a given document references and that
it, in turn, refers to. This gives you a quick way, for example, to see the maps that a specific
topic is in; or the topics that reference a given image.
• Ditaval view – lets you save the sets of output parameters that you use most frequently, and
then apply them as you generate the various types of output.
Show views
Show views lets you open or redisplay views that are closed.
You can close and open views as you require. The following is not a comprehensive list of DITA
CMS views.
Table 2: DITA CMS general views
View Description Default

Perspective
Bulletin Board Displays messages that have been added to a document Project
map's Bulletin Board. Management
Dependencies Displays documents with a parent or child relationship DITA

to the selected document.
DITA Map Displays maps. DITA
Ditaval Displays conditional processing profiles (DITAVAL) files. DITA

They are used to specify the sets of output parameters
that you use most frequently, and then apply them as
you generate the various types of output.
View Description Default

Perspective
Documents Displays user activity in terms of Recent Documents DITA

opened, Recent Operations on documents (for example,
release, lock), and documents the user has marked as
Favorites.
Images Displays the images used in the map. You can use this Offline
view to copy the reference, ID, or full path of an image.
Offline Displays a list of documents that are currently locked, Offline

documents so that you can unlock them all at once if desired.
Preview Displays an HTML preview of the selected topic when DITA

you right-click Show Preview.
Project Displays a summary of the projects for the current user. Project
Management Management
Relationship Used for building relationship tables. Reltable Editing

Outline
Relationship Used for editing relationship tables. Reltable Editing

Table Editor
Search Displays results of a search within the current map. DITA
Search Results Displays results of a Content Store search. DITA
Taxonomy Terms Lets you manage taxonomies in a map and the DITA
documents that contain their terms.
Todo List Displays the user's list of Active document objects. DITA
1. Click Window > Show View from the menu bar.

2. Select the view you want to show.
To show additional views, browse the options provided in Window > Show View > Other.
The view displays in one of the panes of the DITA Perspective.
3. (Optional) Click the view's tab to drag it where you want. You can layer several views
in each pane.
View positions are saved when you exit Eclipse.
Related Links
Project management on page 441
Project Management view on page 442
Preview a topic on page 206
Preview an image on page 281
Preview a map on page 156
Other useful views

The Eclipse environment contains other views that you can use in the DITA Perspective.
The following Eclipse views are available for use within the DITA Perspective. More extensive
information is available from Eclipse help.
• Outline view - displays structured files in a hierarchical format. If you are using an editor that
supports this view, you'll be able to see the structure of the XML file that's currently open in
your editor.
• Properties view - shows the properties of a map or topic in the DITA Map view.
• Error log view - displays information that may help you resolve technical problems (for example,
if you have modified a DTD).
Documents view
This view gives you several document tracking functionalities, such as identifying recently used
documents or frequently used documents.
It also provides you with a means of revisiting these documents without having to search for
them.
The Documents view contains the following panels, which you can open or close as you need:
• Favorites – you can add the documents you work with most often to this view, and group them
into appropriate categories.
• Recent Documents – shows you the documents you've recently worked with. You can remove
any or all the documents from this list, as you wish.
• Recent Operations – shows you the actions you've recently performed on documents.
The Documents view may not be visible when you first open the DITA Perspective. In this case
you'll need to open it from the Windows menu.
Related Links
Restore a document object on page 190
Display recent documents and recent operations

The Recent Documents list provides a means of locating documents that you have recently
opened, while the Recent Operations list organizes documents based on the activities performed
on them.
This can be useful, for example, to locate docs you want to add to your favorites list.
To consult the Recent Documents and Recent Operations lists:
1. Open the DITA perspective.

2. From the menu bar, select Window > Show View > Documents.
The Documents view appears.
3. Expand the Recent Documents and Recent Operations panels.
Documents you have recently opened are listed under Recent Documents; your recent DITA
CMS activities (and their associated documents) are listed under Recent Operations.
Figure 11: Recent Documents and Recent Operations panels
Note: To display the document objects in the Recent Operations list, click the various
folder icons.
4. To add a listed document to your Favorites list, drag it up to the Favorites panel.
5. To filter for a particular document, click in the field at the bottom of the Documents
view and enter a key word from the document's title.
The Favorites, Recent Documents, and Recent Operations lists are filtered to display
documents that contain the specified string.
Note: To clear either list, right-click in the list and select Clear all Recent Documents
or Clear Selected Recent Operations, as appropriate.
Filter Recent Operations display

The Filter field limits the number of documents displayed in the Recent Operations panel.
You can use the Filter field to restrict the number of documents being displayed.
Filtering is performed on the first column of the display. By default, this is the Title of the document,
but it may be configured otherwise.
To filter Recent Operations display:
• In the Filter field of the Recent Operations view, type in characters that you think will
help limit the display.
The application searches the contents of the element specified in the first column and displays
the documents that match.
The following screenshot shows the documents you might see displayed when the string "ca"
is entered.
Folders (actions) that contain matching documents are expanded; folders that have no
matching documents are collapsed.
Clear the Recent Documents panel

This procedure lets you delete any or all documents from the Recent Documents panel of the
Documents view.
Note: When you clear the panel, the information is permanently erased.
1. In the Recent Documents panel, right-click and select one of the following:
• Clear Selected Recent Operations

• Clear All Recent Operations
The Clear Recent Operations warning dialog appears.

2. Click OK.
The relevant entries are removed.
Add documents to your Favorites list

DITA CMS users can bookmark favorite topics, maps, and images for quick access.
For example, if you are working on several topics belonging to different maps
simultaneously, you can make the topics "favorites" so that you can open them as needed
without having to perform a search or open their parent maps.
To make a document a favorite:
1. Open the Documents view.

2. To add a document to the list, select it from another view and drag it to the Favorites
panel.
Figure 12: Favorites panel
Tip: If the document you wish to add is one you worked on recently, no need to search
to locate it—simply expand the Recent Documents panel and drag it to Favorites.
Note: To favorite a document object when Favorites is not displayed, right-click the
document object and select Add to Favorites.
Display Favorites
You can display documents that you have previously marked as favorites.
To open the Favorites panel:

2. From the menu bar, select Window > Show View > Documents.
The Documents view appears.
3. Expand the Favorites panel.
Any topics, maps, or images you have previously favorited are displayed.
Figure 13: Favorites panel
4. To open a document object, double-click it.
Manage your Favorites list

You can organize documents that have previously been marked as favorites into categories.
To organize your Favorites list:
1. Open the Favorites panel.

2. To create a folder for a group of documents, right-click in the Favorites panel and
select New Category.
3. Enter a name for the folder and click OK.
The new folder appears in the Favorites panel.
4. Drag and drop documents into the folder to categorize them.
5. Manage your favorites as follows:
• To rename a folder, right-click the folder and select Rename Category. Enter a new
name and click OK
• To remove a document from the list, right-click the document and select Remove from
Favorites. Click OK to confirm.
Remove entries from the Favorites panel

This procedure lets you delete any or all documents or their categories from the Favorites panel
of the Documents view.
You can remove selected documents from categories, or remove entire categories, together
with all the document they contain.
1. In the Favorites panel, select the documents or categories you want to remove.
2. Right-click and select Remove from Favorites.
The selected entries are removed.
Associate file extensions with applications

You can associate file extensions with applications so that Eclipse knows how to open them.
This may be useful, for example, if you want to open ZIP or Microsoft Word files when using
Eclipse. To associate file extensions with your preferred editors:
1. From the Window menu, select Preferences.

The Preferences dialog opens.
2. Select General > Editors > File Associations.
The File Associations pane appears:
Figure 14: File extensions list
3. If the file extension does not appear in the File types list, click the Add button next to
the File types list.
The Add File Type dialog box appears:
Figure 15: Adding a file extension
4. Beside File type, enter the appropriate file extension, preceded by an asterisk.
5. Click OK.
The new file type appears selected in the File types list.
6. Click the Add button next to the Associated editors list.
The Editor Selection window appears:
Figure 16: Selecting an editor
• To display programs integrated with the Eclipse IDE, such as the browser, select Internal
Editors.
• To display programs available through your system, select External Programs.
8. Select your preferred editor for the selected file format, then click OK.
Your editor appears in the Associated editors list.
9. With the editor selected, click Default to make it your editor of choice.
10. Repeat from Step 3 to set up additional file-editor associations if desired.
11. When all desired associations have been set up, click OK.
The next time you open a file in Eclipse with one of the configured extensions, the selected
editor will be used. If you have more than one editor associated with a given file type, they
will appear as options when you right-click these files and select Open with.
Working with views and editors

You can move and resize views and editors.
Views and editors can be resized and dragged into whatever layout works best for you. Changes
you make to the DITA Perspective are saved when you log off. To restore default settings select:
Window > Reset Perspective.
Moving views and editors
You can click a view’s title bar and drag it on top of any other view. Or you can drag a view out
of the Workbench altogether so that it floats in front of the DITA Perspective.
Editors, on the other hand, can only appear in the editor area, which is in the center of the DITA
Perspective by default.
Like views, the files that are open for editing can be stacked one on top of the other. However,
if you are using more than one editor – Notepad and Oxygen, for example – you have the option
of tiling them in the editor area. See Eclipse help for details.
Resizing views and editors
Views and editors have Maximize, Minimize, and Restore controls at the top to give you more
layout options.
When you minimize a view, it collapses into the trim at the side of the Workbench window along
with all the other views in that particular pane. You can see the icons for each of the minimized
views displayed in the Trim Stack (see the picture in Maximize, minimize, or restore a view on
page 81).
Likewise, when you minimize one editor, all other editors that are currently open will be minimized
as well. The editor area’s Trim Stack, however, only displays a single icon that represents the
contents of the editor area.
You can restore a single view by clicking its icon in a Trim Stack, or you can restore an entire
stack of views by clicking a Trim Stack’s Restore icon.
Maximize, minimize, or restore a view

Views and editors have Maximize, Minimize, and Restore controls at the top to give you more
layout options.
• To minimize a view or set of views: Click the minimize symbol (a in the figure below). The
views collapse and a restore symbol appears in the margin of your workspace.
• To maximize a view: Click the maximize symbol (b in the figure below). The view is maximized.
• To restore a view or set of views: Click the restore icon (c in the figure below). The views
are restored to their original size and position.
Figure 17: Minimize and restore icons

Restore a single view

This procedure re-displays a single minimized view in the DITA Perspective.
Use this procedure when you want to briefly restore one of the views from a Trim Stack. When
you place your cursor into another view or in an editor, the view will minimize back into the Trim
Stack automatically.
To restore a single view:
• Click the view’s icon in the Trim Stack.

The selected view appears in the DITA Perspective.
You can see an example of Trim Stacks containing minimized views in Maximize,
minimize, or restore a view on page 81.
Restore a stack of views

This procedure restores a stack of minimized views into the pane where they were last displayed.
Use this procedure when you want to permanently restore all the views from a Trim Stack. The
views will remain in place when you put your cursor into another view or in an editor.
To restore a stack of views:
• Click the Restore icon in the view’s Trim Stack.

All the views in the Trim Stack are restored into the pane from which they were minimized.
You can see an example of Trim Stacks containing minimized views in Maximize,
minimize, or restore a view on page 81.
Refresh a view
Refresh keeps you up to date with changes by you and by other users.
Note: Some changes, such as changing a topic title, are not displayed until the file is
released.
To refresh a view:
• In the DITA Map view - double-click the title of the map or click the Refresh button.
• In the Todo List, Preview, Project Management, and Dependencies views - click the
blue Refresh button.
Note: You can also refresh the Preview by pressing CTRL+F5.
Clean all views

The Clean All Views command closes all open document objects, leaving the current perspective
open.
This command can be useful when you want to quickly clean up your workspace, perhaps
in order to begin work on a new map.
To clean all views:
1. On the Global Actions toolbar, click the Clean All Views button
If any of your open documents have not been saved, you will get a window prompting you to
save them:
Figure 18: Confirmation window
2. Click Yes to save or No to close without saving.

Any maps, topics, images, and resources open in your DITA CMS workspace are closed.
Other DITA CMS perspectives

In addition to the DITA perspective, the DITA CMS includes several other perspectives designed
for users with specific tasks.
They are described in the following table:
Table 3: DITA CMS perspectives
Perspective Description
Information Architect A set of views for the person responsible for the overall structure
of the document deliverable. This perspective includes the
Todo List, Search Results, and DITA Map view.
Offline A set of views for anybody who has a copy of DITA CMS on
their local PC and who wants to continue working when they
disconnect from the Content Store.
Project Management This set of views for project managers includes the Search,
Search Results, Recent Operations, and Project
Management views.
RelTable Editing This set of views for creating and working with relationship
tables includes the DITA Map, Properties, as well as the
Relationship Table Editor and Relationship Outline views.
SME This set of views, designed for the people who review topic
content, comprises the editor workspace and the Todo List.
TEXTML Administration A set of views for CMS administrators. For details on this
perspective, see the DITA CMS Administrator's Guide.
The editor area is common to all these perspectives. If you have a document open in one
perspective, it will stay open when you switch to another perspective.
All perspectives can be customized as needed, and you can designate any of them as the default
for Eclipse.
For in-depth information on perspectives, see the topic "Working with perspectives" in the Eclipse
help.
Related Links
Open an Eclipse Perspective on page 54
Synchronize configuration files

To apply the latest configuration changes made to the DITA CMS, users must synchronize the
configuration files.
The workstation must be connected to a server and a Content Store.
Each time a DITA CMS user connects to a server and a Content Store, their individual configuration
files are synchronized with the master configuration files located in the Content Store's repository.
However, if an administrator makes changes to the DITA CMS configuration while users are
connected to the Content Store, users who want to work with the most up-to-date settings must
synchronize their configuration manually.
To synchronize the configuration files for a workstation:

From the DITA CMS menu bar, select DITA CMS > Synchronize Configuration.
Your local configuration files are synchronized with those in the Content Store's repository.
Figure 19: Synchronizing configuration
Tip: You can also synchronize by clicking the toolbar Synchronize Configuration
button or by restarting DITA CMS.

5 DITA CMS Search
DITA CMS Search
Topics: DITA CMS provides features that let you search the repository
• Search view enhancements for documents and then search and replace text within these
• Search for documents documents.
• Advanced Search features Some of the DITA CMS search features include:
• Date search features
• Search for documents that • Perform complex (full-text and metadata) searches on the
contain taxonomy terms Content Store and then organize and export these results.
• Search the XML content of For example, you can search for documents in all cycles
a map of the development process: Authoring, Localization, and
• Search within a sub-tree Published. You can also search for documents localized
• Search and replace the XML in a particular language and limit your search to documents
content of a map
locked by yourself or others.
• Apply XSL transformations
to one or more topics • Search within a specific map or sub-tree within a map.
• Select the current topic in • Search and replace the text within selected sets of
a map documents using regular expressions.
• Standard search operators • Re-run recent searches from the search history.
and wildcards
• Save frequently used sets of search parameters.
• Search Results view
operations
• Isolate appended search
results
• Locate errors
• Configure search
• Working with queries
Search view enhancements

You can search the Content Store more easily thanks to enhancements in the Search view.
In DITA CMS, many of the most common Advanced Searches can be accessed from the Cycles,
Document Types, and Search for panels.
For example, you can search the objects that are in the Authoring:work status directly from
the Cycles panel, without having to use the Advanced Search panel.
As shown in the diagram below, the items in the Cycles and Document Types panels have
submenus:
To search a specific state for a cycle, you use the drop-down arrow directly in the Cycles panel
instead of having to specify the state index in the Advanced Search panel.
You can also search an index, attribute, or element by specifying it directly in the Search for
panel with the Search in drop-down list:
Figure 20: Search for panel

DITA CMS Search 89
By default, the DITA CMS searches the whole document for the string specified (i.e., the fulltext
option is selected, as shown above). You can specify any index, attribute, or element directly in
this panel instead of using the Advanced Search panel.
Note: The Advanced Search panel is still useful to construct complex searches using
many different criteria.
Search for documents

To search for documents, you enter search criteria in the Search view. Results are displayed in
the Search Results view.
The Search view is divided into panels, such as Document Types, Languages, Cycles, etc.,
that let you specify search criteria. Each panel has expand and collapse buttons that let you hide
the panels you aren't currently working with. They each also have a set of buttons that let you:
Function Button
Save the current settings as the default for that

panel
Select all checkboxes
Clear all checkboxes
Apply the defaults for that panel
The Search Results view lists the documents returned by your search criteria. You can group
and filter the results.
By default, a maximum of 100 results can be displayed at one time. Search defaults are
configurable.
Note: Search is performed on the last version released to the server.
To search the Content Store:

2. Click the Search tab.
3. In the Cycles panel, select the document cycles you want to search.
Figure 21: Cycles panel
By default, all the states in the cycle selected will be searched. For example, if you select
Authoring and click the drop-down arrow to the right of Authoring, a menu similar to the
following is displayed:
This menu displays all the states that are defined for your deployment.
4. To specify a different list of states, check and uncheck the states as required.
A check sign ( ) in the check box indicates that all the states in the cycle are selected; a
shaded check box ( ) indicates that only some of the states are selected. Click the drop-down
arrow to see the selections.
Note: If you see the message "selected items are different from default items" at the
top of a panel, this means that the selections you have made are different from the
selections that you have saved as default with the button.

5. In the Document Types panel, select the document objects you want to search.
DITA CMS Search 91
Figure 22: Document Types panel
By default, all the subtypes for the document type selected will be searched. For example, if
you select Maps and click the drop-down arrow to the right of Maps, a menu similar to the
following is displayed:
This menu displays all the map types that are defined for your deployment.
6. To specify a different list of subtypes, check and uncheck the subtypes as required.
7. In the Search for panel, enter a search string, such as the title of the document object.
Figure 23: Search for panel
Search is not case-sensitive.

Tip: You can use wildcards to refine your search; click the button for a list of
operators and their descriptions.
By default, the DITA CMS searches the whole document for the string specified (i.e., the
fulltext option is selected).You can search a specific element, index, or attribute by changing
the value in Search in.
8. To search a specific section of the objects (for example, the title element), select the
element from the Search in list.
To search the whole document, select the fulltext option.
9. (Optional) In the Limit to panel, select additional search criteria:
Figure 24: Limit to panel
a) Under Locked by:, choose me or others.

DITA CMS Search 93
b) To find documents assigned to a specific user, select Assigned to and then select
the name of the user in the drop-down list. You can also enter text directly in the
Assigned to field to search for a specific user name.
c) To find documents assigned to a specific role, select Role and then select the role
in the drop-down list.
d) To search for document objects within the active map context, select Dita Map
view.
This will also return the active map in the Search Results.
e) To search for document objects belonging to a specific project, select Project and
choose a project.
Note: The list displays only projects to which you belong.
f) To search for document objects that were last modified by a specific user, select
Last Modified By and select a user name.
g) To search for branched documents, select Branch and then select the branch tag
from the drop-down list.
h) To search documents that are not referenced by any other document in the
repository, select Orphans.
10. In the Languages panel, select at least one language of the documents to be searched.
Figure 25: Languages panel
11. To append the search results to an existing search results list, select Append to current
results.
12. Click the Search button.

Document objects matching your search criteria are displayed in the Search Results view.
Figure 26: Search results for "log in" search
Note: Search criteria stay in effect when a panel is collapsed. If you previously performed
an elaborate search, click in each panel of the Search window to restore the default
settings before you search again.
This topic describes the most common panels in the Search view. For more information on the
Dates, Advanced Search, Taxonomy Terms, and Queries panel, see the documentation for
these panels.
Related Links
Filter the ditaval files in the Ditaval view on page 356
Standard search operators and wildcards on page 118
Date search features on page 107
Advanced Search features on page 96
Search example: Searching for a specific topic type

In this example, we'll search for all referable-content topics in the Authoring cycle.
1. If necessary, click the New Query button.
This sets all panels of the Search view to their defaults.
2. In the Cycles panel of the Search view, select Authoring.
3. In the Document Types panel, select Topics.
4. Click the drop-down arrow to the right of Topics.
DITA CMS Search 95
The list of all topic types are displayed.

5. Unselect all types and keep only referable-content.
Note: If the Search button is disabled, check to see if you've supplied values in all
the panels where one is required. Panels that need values show error messages such
as the following.
Documents matching your search criteria are displayed in the Search Results view.
Search example: Searching for a DITA element

This example builds on the previous example—searching for a specific topic type—and refines
the search so that it finds all referable-content topics that contain the <note> element.
We'll assume that you just finished running the referable-content search and that your search
returned several hundred topics in the results. So now we'll add a search criteria to narrow its
scope.
At the end of the previous example, the Cycles and Document Types panels looked like the image
below.
1. In the Search for panel, select note from the Search in drop-down list.
All the refererable-content documents in the Authoring cycle that contain a note are displayed in
the Search Results view.
Search example: Searching for a specific element

This use case describes how to search for all occurrences of the <draft-comment> element
within a map. Use these steps as a guide to search for any other specific element.
1. Open the map in the DITA Map view.

2. In the Search view, select the following:
• Cycles panel: Authoring check box
• Document Types panel: Topics check box
• Search for panel: leave text box empty, select draft-comment in Search in drop-down
Note: If the element you want to search for is not in the list, it has not been indexed
for searching. Content your DITA CMS system administrator.
• Limit to panel: check Dependencies of DITA Map view check box

Note: To search your entire Content Store, do not check this check box.
3. Click Search.
Advanced Search features

Advanced Search lets you construct complex searches in the repository using many different
criteria.
The following diagram shows the Advanced Search panel:
DITA CMS Search 97
You enter one search criterion per line. You can enter as many criteria as required to make a
truly detailed search of the CMS repository.
The first column specifies a search operator. You can specify three operators:
• and: The search result must contain the specified value.

• or: The search result may contain the specified value.
• without: The search result must not contain the specified value.
The first row always starts with the and operator. This serves as a reminder that the results of
the Advanced Search panel will be aggregated with the results of the other search panels, using
the and operator.
Use the line management buttons ( ) to add, remove, and organize your criteria.
The Advanced Search rows are executed from the top down.
The selections that appear when you construct your search criteria differ according to your choice
of Type. You can specify four types of advanced searches:
• Elements: Search within a specific XML element.

• Attributes: Search for XML elements having specific attribute values.
• Index: Search according to indexed criteria.
• Dates: Search for documents created or modified on fixed or relative dates.
The following sections show the various criteria Types that are available and the Names and
Values that may be used with them. For detailed examples, see the Advanced Search examples
in this document.
Elements
Lets you search within a specific XML element. Select the element Name and then enter the
Value of the expression you are looking for.
For example, you could search with the values shown below.
Operator Type Name Value
And elements title Publish*
This search returns files where the string "Publish" is part of any title in the document. This would
include, for example, topics having sections titled "Publishing Output" and tables with the title
"Published books". The asterisk character is a wildcard that replaces one or more characters.
Attributes
Lets you search for XML elements having specific attribute values.
For example, you could search with the values shown below.
And attribute alt map*
This search would return image files where the alt attribute contains words that begin with the
string "map". This would, for example, include "topics and maps" or "mapping data". The alt
attribute is the text that displays if for some reason the image cannot be loaded.
Index
Lets you search according to other useful indexed criteria.
Indexes available for selection are:
• ID - lets you search for the map, topic, or image ID.
For example, if you are looking for all the places that a specific document is referenced, you
could enter the following values.
And index ID mal1159463936986
This search returns a list of all the files that contain the ID "mal1159463936986".
DITA CMS Search 99
• title - lets you search for files using the topic title as it appears in the Search Results view.
For example, you might set up your search with the following values.
And index title *map*
This search returns all files having the string "map" somewhere in the title. This list might
include a topic called "set map variables", an image called "DITA topics and maps", and a map
called "test_map".
• image description - lets you search for any of the information contained in the image
description.
For example if you are looking for all the descriptions that contain the word "status", you could
enter the following values.
And index image description status
This search returns all the images whose descriptions contain the word "status".
• topic type - lets you search by topic type.
For example, you could search using the following parameters.
And index topic type task
This search returns all topics of the type task. You could combine this with the string "image*"
if you wanted to narrow your search to all tasks that contained words starting with "image".
• status - lets you search for all files having the specified status.
For example you might select the following values.
And index status Localization:in translation

If you select the Localization cycle, this search returns all files with the status Localization:in
translation.
• state - lets you search for all files in the specified state.
For example you could search for the following values in the Authoring cycle.
And index state done
This search returns all topics in the Authoring cycle whose state is done.
• version - lets you search the Published or Localization cycles for all files having the specified
version.
For example you could select the following values.
And index version *alpha*
This search returns all files that contain a word that begins with the string "alpha" in their
version field. This would include versions such as "alpha1" or "alpha_1_b" or " Ixiasoft alpha".
• locale - lets you search the Localization cycle for all files of the specified locale.
For example you could select the following values.
And index locale dan
This search returns all the files that are being localized in Danish.
• created by - lets you search for all files created by the specified user.
For example, if you wanted to search for all files created by a user called SmithJ@ixiasoft.com,
you'd set the search field as follows.
And index created by SmithJ@ixiasoft.com
• modified by - lets you search for all files modified by the specified user.
DITA CMS Search 101
For example, if you wanted to search for all files last modified by a user called
SmithJ@ixiasoft.com, you'd set the search field as follows.
And index modified by SmithJ@ixiasoft.com
• label - lets you search for all files that have a particular label.
For example, if you are looking for all the files whose labels contain the word "obsolete", you
could enter the following values.
And index label obsolete
This search would return files with labels such as "obsoleted in 2009" and "provisionally
obsolete".
• contains elements - lets you search for all files that contain the selected element.
For example, if you wanted to find all the files that contained images, you could search as
shown below.
And index contains elements image
Related Links
Search for documents on page 89
Create search results groupings on page 123
Search within search results on page 126
Apply groupings to search results on page 125
Advanced Search example: Using multiple criteria

When using three or more criteria in the Advanced Search, the order in which you specify the
criteria is very important. This example shows how to use multiple criteria in the Advanced Search.
The Advanced Search rows are executed from the top down, so you must be careful when
specifying three or more criteria. For example, consider a search with three criteria:
1. X
2. and Y
3. or Z
The search algorithm first executes the first two lines (X and Y). It then uses this result and applies
it to the third line ((X and Y) or Z)). The results of this search will then be aggregated to the results
of the other search panels, using the and operator.
For example, consider the case where you want to retrieve all the referable-content topics in
authoring that were used in versions 1.12 or 1.13 of the documentation. To perform this search,
you would enter following Advanced Search criteria:
1. version=1.12
2. or version=1.13
3. and topic-type=referable-content
The Advanced Search will first retrieve all the topics that are in version 1.12 or version 1.13 and
will then retrieve from this list all the referable-content topics. Entering the criteria in a different
order would not return the desired search.
The following procedure describes how to perform this sample search.

2. In the Document Types panel, select Topics.
3. If necessary, expand the Advanced Search panel.
The default Operator is and to indicate that the results of the Advanced Search panel will
be aggregated with the results of the other panels (in this example, this is all the Topics in
Authoring), using the and operator.
DITA CMS Search 103
4. Set your cursor into the Type column.
A drop-down indicator appears.

5. Click the indicator and select index from the drop-down list.
6. Set your cursor into the Name column.

7. Click the indicator and select Version from the drop-down list.
8. Enter 1.12 in the Value field.
9. Click the Add a new line button.

This adds a new line beneath the one shown above.
10. Set your cursor into the Operator column.

11. Select the or operator.


15. Click the indicator and select Version from the drop-down list.
16. Enter 1.13 in the Value field.

This adds a new line beneath the one shown above.

21. Click the indicator and select Type from the drop-down list.
22. Set your cursor into the Value column.

23. Click the indicator and select referable-content from the drop-down list.
The Advanced Search panel should look as follows:
DITA CMS Search 105
24. Click Search.
Advanced Search example: Using the without operator

You can use the without operator if you need to exclude results from the search.
For example, consider the case where you want to retrieve all the topics and images that are not
in the Authoring:done status. This search requires two lines in the Advanced Search:
1. Retrieve all statuses.

2. Exclude the Authoring:done status.

2. In the Document Types panel, select Topics and Images.
3. If necessary, expand the Advanced Search panel.
The default Operator is and to indicate that the results of the Advanced Search panel will
be aggregated with the results of the other panels (in this example, this is all the Topics and
Images in Authoring), using the and operator.


7. Click the indicator and select Status from the drop-down list.
8. Leave the Value column empty.
This will retrieve all the available statuses from the Content Store.

10. Select the without operator.
DITA CMS Search 107


14. Click the indicator and select Status from the drop-down list.
15. Set your cursor into the Value column.

16. Click the indicator and select Authoring:done from the drop-down list.
The Advanced Search panel should now look like the image below.
17. Click Search.
Date search features

You can use the Dates panel of the Search view to search for documents created or modified
on exact calendar dates (Fixed Date) or for documents you worked on Yesterday or Last Week
(Relative Date).
You can also search for all documents that were not created on a specific date. The following
example shows how you could search for documents created any day except Yesterday.
You have the same choice of Fixed and Relative dates if you choose to search within other time
frames: Before a given Date, Since a Date, and Between two Dates. If you choose Between two
Dates, you can apply any of the date search criteria to each endpoint.
The following example shows the values that would let you search for documents modified on
or after May 21st 2009 but before Yesterday.
The interactive calendar

When you search by specifying a Fixed Date, you can open an interactive calendar by clicking
the Choose date with calendar button.
DITA CMS Search 109
This calendar offers the familiar features of the calendar in your computer. It also lets you quickly
navigate between months, years, and even decades by clicking its hypertext links.
Related Links
Search for documents that contain taxonomy terms

You can use the DITA CMS search facility to locate documents containing specific terms.
1. If necessary, expand the Taxonomy Terms panel of the Search view.
2. Click the Add button.
The Select Taxonomy Terms dialog appears.
3. Select the terms you want to search for, then click OK.
4. From the Select documents containing list, select one of the following:
• any of the terms: Documents that contain at least one of the specified taxonomy terms
are returned in the Search Results.
• all of the terms: Only document that contain all of the specified taxonomy terms are
returned in the Search Results.

Related Links
Search the XML content of a map

You can quickly search the content of documents in a map, including the XML elements and
attributes.
To search one or more documents in a map:

2. Open a map in the DITA Map view.
3. (Optional) To search only certain topics in the map, select the target topics.
4. Click the DITA Map view’s Menu button .
5. Select Search and Replace.
The Search and Replace dialog box appears:
Figure 27: Search and Replace
6. Under Containing text, enter the search string.

To search recently used text or expressions, click the list under Containing text and make
a selection.
Note: Your search string can include wildcards, but it cannot include operators.
7. (Optional) If desired, select one or more Options:
• Case sensitive to find only text that matches the case in your search string.
• Whole word to find only whole words that match the search string. (If this is selected, a
search for "cat" would ignore the word "caterpillar".)
• Regular expression if your search uses a codified pattern to represent multiple characters.
If this option is not selected, the [ ] characters, if used, will be interpreted as wildcards.
DITA CMS Search 111
8. If you are targeting selected documents (Step 3), under Applies to, click Selection.
By default, the All option is selected under Applies to.
9. Click Search
The documents that match your search criteria are returned in the Search view:
Figure 28: Search view
Related Links
Search within a sub-tree

You can limit your search to topics within a specific sub-tree of a map.
The criteria you can use may include topic Title, Author, or ID, although the exact set of criteria
that appears may vary according to your configuration.
Unlike Advanced Search, you won't need to enter topic IDs or author names to search for them.
Instead, the Search within a sub-tree procedure offers you lists of information extracted from the
current map.
Note: The map must be open in either the DITA Map view or the DITA Map Editor.
1. In the DITA Map view, click Refresh to update the view.

2. Right-click the parent topic of the sub-tree and select Search within a sub-tree from
the menu.
The Selection Builder dialog appears.
3. Select the Index you want to use to perform the search.

4. Select the Value that you want to search for.
The information in the Value list is extracted from the topics of the current map.
If you select the ID index, then the Value selection list shows the IDs of all the topics in the
current map.
5. Use Add Row to further refine search criteria.
The Clear button removes all rows of search criteria.
The topics that fulfill your search criteria are highlighted within the current sub-tree.
Related Links
Map sub-trees on page 146
Search and replace the XML content of a map

You can search and replace XML text strings within the topics of a map.
Prerequisites:
Documents must be locked for the replace operation to succeed. You can lock the documents
before beginning or allow the DITA CMS to lock them for you during the process.
Caution: This feature is capable of altering the XML code in your documents and could
make your documents invalid.
To replace a particular text string across all topics of a map:

DITA CMS Search 113
2. Open a map in the DITA Map view.

Note: Maps and topics being targeted must have an editable status (that is, they can
be locked). For most document teams, this means any state within the Authoring cycle.
Maps or topics that are not in a lockable state, that are not in the Authoring cycle for
example, are skipped.
3. (Optional) To search only certain topics in the map, select the target topics.
4. Click the DITA Map view’s Menu button .
5. Select Search and Replace.

To search using recently used text or expressions, click the list under Containing text and
make a selection.
• Case Sensitive to find only text that matches the case in your search string.
• Whole Word to find only whole words that match the search string. (If this is selected, a
8. If you are targeting selected documents (Step 3), under Applies to, click Selection.
By default, the All option is selected under Applies to.
9. Click Replace.
Note: If any of the target documents are unlocked, the Unlocked Documents
confirmation window appears. Click Yes to continue with the replace operation.
Figure 30: Found Unlocked Documents
The Replace Text Matches dialog appears:
Figure 31: Replace Text
10. Enter your replacement text in the With field or select it from the drop-down list.
The Regular expression checkbox will be selected if you chose this option for your search.
11. (Optional) To review the changes you're about to make, click Preview.
Note: You can also apply changes globally without previewing them by clicking OK.
However, this option is not recommended unless you are absolutely certain that the
changes will not negatively affect your XML tags and/or change text you don't want
changed.
The Replace Text Matches dialog box appears:
DITA CMS Search 115
Figure 32: Previewing text changes
12. Under Changes to be performed, select the first change in the list.
The search string is highlighted under Original Source, and the replacement string is
highlighted under Refactored Source.
• If the change is acceptable, do nothing and repeat from Step 12 for the next document
in the list.
• If the change is not what you wanted, under Changes to be performed, clear the
checkbox for that particular replacement.
14. Click OK when you are finished.

The replacement action is carried out in the selected documents.
Related Links
Apply XSL transformations to one or more topics

You can use the Search and Replace feature to apply a different XSLT to one or more topics on
the fly.
Prerequisites:
You must have created an XSL file for the XSLT you wish to apply.
XML stylesheet language transformations (XSLTs) use XML language to transform XML documents
into HTML or some other format. XSLTs are carried out through XML stylesheet language (XSL)
templates. Normally XSLTs are applied by the Output Generator when a map is generated.
However, users can also choose to apply XSLTs to one or more specific topics on the fly, as
described below. For example, a user might select a set of topics and transform them into HTML
to add them to a PowerPoint presentation.
To apply XSLTs to one or more topics:

2. Open the DITA Map view.
3. Select the topics to which the XSLT will be applied and lock them.
4. Click the Menu button and select Search and Replace.
Note: Alternatively, you can perform this action from the Search Results view, using
the Search and Replace button:

The Search and Replace window appears.
5. Click the Apply XSLT tab.
The Apply XSLT window appears.
6. In the Applies to area, select your search scope (All or Selection).
7. Click the Browse button and then locate the XSL file to use:
DITA CMS Search 117
Figure 33: Choosing an XSL
8. Click Open.
The XSL document name and path are added to the Apply XSLT window. If there are any
variable parameters defined in the XSL, they will appear in the Name column of the
Parameters list.
Figure 34: Apply XSLT dialog box
9. Under Parameters, enter the required Value for defined parameters (if any).
Parameter values will be written into the XSL and applied during the transformation.
10. Click Apply.
The XSL template is applied to the selected topics.
Select the current topic in a map

You can find out where an open topic is located in a map.
• The map must be open in the DITA Map view.
This feature is useful when you have a topic open in your editor, and you want to find where (or
if) it's located in a map.
Note: You can also use this feature to find images or resources that are referenced directly
by the map.This is useful if you are using the DRM module or for images used in <keydef>
maps.
To select the current topic in a map:
• In the DITA toolbar, click the Select in map button.
The topic must be open and selected (have focus) in the editor area for this to work.
• From most views (Search Result, Dependencies, Documents, etc.), right-click the object
and select Select in map.
The object is highlighted in the map. If necessary, the appropriate map sub-trees expand
to show the location.
Standard search operators and wildcards

Enter the symbols in search text boxes to refine your search criteria.
Standard search operators and wildcards may be used in the Search view in combination with
other text in the Search for panel or in entry fields in the Advanced Search. Search is not case
sensitive.
Note: The search engine ignores text that contains one of these operators. For example,
the search engine sees "DITA-XML" or "DITA|XML" as "DITA XML".
Search operators
Note: These operators cannot be used in the Search and Replace feature.
DITA CMS Search 119
Symbol Name Priority Example Description
"" CONTIGUITY 1 "DITA XML" Retrieves all documents that

contain the phrase "DITA XML"
() PRIORITY 2 (DITA + XML) - Retrieves all documents that

Topic contain the word "DITA" and the
word "XML" but not the word
"Topic"
> FREQUENCY 3 DITA >5 Retrieves all documents that

contain the word "DITA" 5 times or
more
NEAR NEAR 4 DITA NEAR6 Retrieves all documents that

XML contain the word "DITA" located
within 6 words of the word "XML"
ADJ ADJACENCY 5 DITA ADJ4 XML Retrieves all documents that

contain the word "DITA" located
within 4 words of the word "XML" in
this order
- WITHOUT 6 DITA - XML Retrieves all documents that

contain the word "DITA" but not the
word "XML"
Note: You must include a
space before and after the
(-) operator to use the
WITHOUT operator. If you
do not, the search engine
searches for topics that
contain the "DITA-XML"
string.
+ AND 7 DITA + XML Retrieves all documents that

contain the word "DITA" and the
word "XML"
Note: You must include a
space before and after
Symbol Name Priority Example Description

the(+)operator. If you do not,
the search engine ignores it.
| OR 8 DITA | XML Retrieves all documents that

contain the word "DITA" or "XML"
Wildcards
Note: The [ ] wildcard cannot be used in the Search and Replace feature.
Symbol Name Example Description
? Replaces one D?TA Retrieves all documents that

character contain words such as "dita" and
"data"
* Replaces one or more T*y Retrieves all documents that

characters contain words starting with "T" and
ending with the letter "y", like
Technology or toy
[] Defines a choice Tech[,nical] Writer Retrieves all documents that

contain words Technical Writer or
Tech Writer
Related Links
Filter the ditaval files in the Ditaval view on page 356
Search and replace the XML content of a map on page 112
Search the XML content of a map on page 110
DITA CMS Search 121
Search Results view operations

Several utilities are available for refining and working with the results returned by a search.
The table below describes the different ways you can manipulate search results. All of the steps
in the table require that you have previously performed a search and have the Search Results
view open in the DITA perspective.
Table 4: Search results operations
Operation
Locate search This feature is particularly useful with large and complex maps.
results topics in
a map. Steps Results
1. Open the map in the The topic is highlighted in the map.

DITA Map view.
2. Search the repository
for the files that meet
your search criteria.
3. In the Search
Results view,
right-click the topic(s)
and choose Select in
Map.
Clear Search This procedure is useful if you are appending search results and want to clear
Results view. the Search Results view.
Steps Results
Click the Clear Results All values are cleared from the Search Results
button: view.
Filter search This procedure limits the number of documents displayed in the Search Results
results. view. Filtering is performed on the first column of the display. By default, this
is the Title of the document, but it may be configured otherwise.
Operation
Steps Results
In the filter field, enter all DITA CMS displays the documents whose titles
or part of the document match the search string. The screen shot below
title. shows the documents displayed for a string "col":
Export search You can export search results and save them in a file outside the repository
results. in three different formats: Tab Separated Value (TSV), Extensible Markup
Language (XML), and Spreadsheet (XLS) file. These formats can be imported
into other programs such as spreadsheet etc.
Steps Results
1. In the Search The results are saved according to your preferred

Results view, click format.
the Export Search
Results button:
2. Confirm or change
the proposed file
name and location.
3. Click Save.
Show only the If you have developed a large body of published and localized documents,
most recent you may find it useful to exclude earlier versions from your search results.
documents in
the Localization Steps Results
or Published
cycles.
DITA CMS Search 123
Operation
1. Click the Search The results are filtered so that only the more recent
Results view’s Menu documents are listed.
button.
2. Select Show Only

Latest.
3. Re-run the search.
Jump to a If your search returned many results, you can jump to a specific page in the
specific page in search results.
the search
results. Steps Results
Enter the page number The results for this page are displayed.
in the page field at the
bottom of the Search
Results view,
Create search results groupings

Search result groupings are folders that allow you to organize search results. Groupings can be
useful when you are performing broad searches that produce a large number of search results,
to have the search results automatically arranged into folders.
For example, if you are performing a search results on "orphan" topics, you could set up folders
so that the topics would be arranged according to their version.
To create groupings:

2. Click the Search Results tab to display the view.
3. In Search Results view, click the Manage Groupings button.

The Manage Groupings window appears.
4. Click New.
The Group Name window appears.
5. Enter a name to identify the grouping, then click OK.
The new name appears in the Groupings list and the Available criteria list is populated with
all the available document parameters.
Figure 35: Manage Groupings window
6. From the Available criteria pane, select a parameter, then click Add.
Your selection moves into the right-hand pane.
7. To create sub-folders that will further group the results, repeat Step 6.
8. Click OK.
Your new grouping is now available in the Search Results view's Select Grouping list.
You can now apply groupings to search results.

Related Links
DITA CMS Search 125
Apply groupings to search results

Once you have created a search result grouping, you can automatically organize the results of
your search into folders.
To group output in the Search Results view:

2. Perform a search.
Your search results are displayed in the Search Results view.
3. In the Search Results view, click the groupings drop-down and select a grouping.
Figure 36: Apply grouping to search results
The search results are organized into folders according to the grouping selected. In the
example below, results of a topics search with Limit to: Orphans were grouped by version.
The No value folder contains documents for which the selected criteria—Version in this
example—were not defined.
Figure 37: Search results grouped by version
4. Click a folder to access the documents within it.

5. To exit the groupings mode, click the groupings drop-down menu and select None.
Related Links
Search within search results

You can quickly search the content of documents in your Search Results list, including XML
elements and attributes.
To search one or more documents in search results:

3. In the Search Results view, click the Search and Replace button:
DITA CMS Search 127

To search using recently used text or expressions, click the list under Containing text and
make a selection.
• Case sensitive to find only text that matches the case in your search string.
• Whole word to find only whole words that match the search string. (If this is selected, a
6. Click Search
Note: If search results are provided over many pages, the following message is
displayed:
To search all the results, click All pages. To search the current page only, click This page
only.
The documents that match your search criteria are returned in the Search view:
Figure 39: Search view
Related Links
Isolate appended search results

When you append search results or when you locate documents using the Locate button, the
search results are stored in separate lists.
This is shown in the following diagram:
DITA CMS Search 129
While the appended results are organized in separate lists, the Search Results functions available
apply to all the results in the window. For example, if you want to group the search results in the
diagram above, the results from the previous search and from the Locator search are combined
before they are grouped.
You may want to work with the results of only one of the searches. This can be very useful, for
example, when using the Change Status function. If you try to change the status of a map, but
some of its children do not have the appropriate status, a dialog similar to the following is displayed:
To be able to easily change the status of the children before you change the status of the map,
you may want to group the results by status. To work with the Locator results only, you need to
first isolate them.
To isolate search results:
1. In the Search Results window that contains the appended search results, select the
title of the search and right-click Isolate Results.
The Search Results window now only displays the results of the search selected.
Note: If you isolate the Locator results, all the results are displayed on a single page,
so if you have many search results (for example, 200 and more), loading the page
may take a while.
If you isolate the Search results, they are displayed over multiple pages.
2. Apply any of the Search Results window functions on the isolated results.
Locate errors
Buttons in many of the warning dialog boxes let you locate the documents that caused the error.
For example, the image below shows what might happen if you attempted to delete a topic that
was referenced by related links in other topics. The error dialog displays the topic IDs and a short
explanation.
To easily locate the topics that caused the problems:
Choose either (or both) of the following options:
• Click Save to save the information in a .TSV file, which you can import into a spreadsheet
application.
• Click Locate to open the Search Results view, which display the responsible files as an
appended search under the title Locator.
Note: Neither of these options closes the dialog. You can do both before you
leave
Previous search results are preserved in a separate item.
DITA CMS Search 131
Configure search
You can set defaults for the different panels of the Search view and specify how the panels are
displayed.
Set default search parameters

Use this procedure to set the defaults for a panel in the Search view.
You may find it useful to save the settings that you frequently use in certain panels of the Search
view.
To set search defaults:
• In the panel whose default you want to set, click the Set as Defaults button.
All the current selections are saved as the default for that panel of the Search view.
Note: If you see the message "selected items are different from default items" at the top
of a panel, this means that the selections you have made are different from the selections
that you have saved as default with the button.

Restore search defaults

You can restore parameters in the Search view to their defaults.
Prerequisites:
You must have previously configured your default search options for each panel in the Search
view. If you did not configure Search defaults, the system default settings will be applied.
To restore the search defaults for Search view panels individually or for all panels at once:

2. Open the Search view.
• To restore defaults for a particular panel, expand the panel and click the Restore Defaults
button ( ).
• To restore defaults for all panels, click the New Query button ( ).
The targeted panel or panels are reset to their default parameters.
Customize the Search view layout

You can rearrange the Search view panels so they suit your working habits; you can also hide
panels that are not used often.
For example, if you work with different languages, you might want to move the Languages panel
up near the top of the view.
To customize the Search view layout:

2. Open the Search view.
3. Click the Show/hide panels button.
The menu with the panel names is displayed:
DITA CMS Search 133
Figure 40: Show/hide panels menu
4. Select the panels that you wish to hide or clear those you wish to view.
The view is refreshed with your changes.
5. (Optional) To re-arrange the panels displayed, click the Show/hide panels button.
6. Select Enable drag and drop.
7. Drag the various panels to place them in your preferred sequence.
Your settings are saved and will be available for subsequent DITA CMS sessions.
8. Click the Show/hide panels button and clear the Enable drag and drop option.
Working with queries

Queries are sets of search parameters that you can save and reuse. This set of topics provides
instructions to create, edit, and save queries.
Related Links
Create a query
Creating a query saves search parameters that you use frequently so that you can re-use them.
You can create the following types of query:
• Personal queries: Sets of criteria that you can reuse through the DITA CMS
• TEXTML queries: Sets of criteria that you can access and edit through the TEXTML Server
console.
To create a query:
1. Set up a search in the Search view.

• To save the criteria as a personal query, click the Save Query button:
• To save the criteria as a TEXTML query, click the Save TEXTML Query button:
The Save query window appears.
Figure 41: Saving a query with a viewpoint
Note: The Save viewpoint with query option is displayed only if a viewpoint is
selected in the Search Results window.
3. Enter a descriptive name.
4. (Optional) Select Save viewpoint with query if you want to save the query along with
viewpoint.
5. Click OK.
The query is saved under Personal or Personal Textml in the Queries panel.
Run a personal query

Once you have saved a set of parameters as a query, you can quickly load them in the Search
view.
Prerequisites:
Before attempting this procedure, create a query.
To run a personal query:
1. Open the Queries panel of the Search view.

2. Expand the Personal node.
DITA CMS Search 135
Your saved searches are displayed.

3. Right-click the required query and select Load queryname, where queryname is the
query's name.
Figure 42: Loading a personal query
The search parameters are loaded into the various panels of the Search view.
4. (Optional) Modify the search parameters if necessary.
The Search Results view displays the documents returned by your query.
Run a TEXTML query

Contrary to a personal query, a TEXTML query can be run quickly, without first loading search
criteria into the Search view.
To run a TEXTML query:

2. Expand the Personal TEXTML node.
Your saved queries are displayed.
3. Right-click the required query and select Run queryname, where queryname is the
query's name.
The Search Results view displays the documents returned by your query.
Re-run a recently executed search

You can reload all the criteria of a recent search, without having to select and/or enter them
manually.
To re-run a recently executed search:

3. Expand the History node.
Your recent searches are displayed.
4. Right-click the required search and select Load Search for searchstring.
Figure 43: Reloading search criteria
The parameters from that search are loaded into the various panels of the Search view.
Note: You can also remove searches from the history by right-clicking one or more
searches and selecting Delete Search for searchstring.
5. (Optional) Select or modify search parameters as required.
The Search Results view displays the documents returned by your search.
DITA CMS Search 137
Edit a personal TEXTML query

Use this procedure to modify your TEXTML queries.
You can edit your TEXTML queries in the XML editor of your choice, once that editor is
set as the default for DITA CMS.
For TEXTML Query Language syntax, see the TEXTML Server documentation.
1. If necessary, open the Queries panel of the Search view.

2. Expand the Personal TEXTML item.
Your saved queries are displayed.
3. Right-click the required query and select Edit queryname, where queryname is the
query's name.
The query opens in your default XML editor.
4. Modify search parameters as required and save your work.
5. Right-click the query and select Release queryname.
Note: If you decide you don't want to keep your modifications, you can always select
Replace with server revision queryname.
Your edited query is released to the server.
Delete a personal query

Use this procedure to delete saved personal queries.
You can delete both varieties of queries: personal and TEXTML.

2. Expand the item that contains the type of query you want to delete:
• Personal or
• Personal TEXTML
Your saved searches are displayed.

3. Right-click the required query and select Delete queryname, where queryname is the
query's name.
The selected query is deleted from the Search view.

Shared queries
You can share your personal and TEXTML queries with the other people who work on your
documents.
You can share your favorite personal and TEXTML queries with any of the configured roles or
groups on your Content Store.
You can also share queries that other people have shared with you.
Share saved queries

You can share both personal and TEXTML queries.
Queries can be shared with any of the configured roles or groups on your Content Store.
1. In the Queries panel of the Search view, open the appropriate item:
• Personal, or
• Personal TEXTML
2. Right-click a query and select Share queryname.

The Share query with... dialog appears.
3. Select the Roles and Groups you want to share the query with.
4. Click OK.
The people who belong to the Groups and/or Roles you specified will see the query under
their Shared > Personal or Shared > Personal TEXTML item.
If you are a member of any of these groups, you'll also see the query in that place.
Share shared queries

You can share the queries that have been shared with you.
1. In the Queries panel of the Search view, open a Shared item, either:
• Shared, or
• Shared TEXTML
You'll see the Roles and/or Groups items that contain your shared queries.
2. Expand the appropriate Roles or Groups item.
You'll see the items for the various role names or group names that contain shared queries.
DITA CMS Search 139
3. Expand the required rolename or groupname item.
Under each role or group name you'll see the queries that have already been shared.
The following image shows the queries that have been shared with a user in her various roles
– one as an Editor and the other as Project Coordinator.
4. Right-click a query and select Share queryname, where queryname is the query you've
selected.
The Share query with... dialog appears.
5. Select the Roles and Groups you want to share the query with.
6. Click OK.
The query will appear under the Shared item of people who are in the groups and/or roles
you specified.
If you are a member of any of these groups, the query will also appear under your own Shared
item.
Delete shared queries

You can delete the queries that have been shared with you.
You may find that you have many similar queries and want to cut back on ones that are redundant.
Or you may find that you have duplicate queries and you want to delete some of them.
Note: When you delete a shared query, you are deleting it for every other person who is
on that team.
1. In the Queries panel of the Search view, open a Shared item, either:
• Shared, or
• Shared TEXTML
You'll see the Roles and/or Groups items that contain your shared queries.
2. Expand the appropriate Roles or Groups item.
You'll see the items for the various role names or group names configured on your system.
3. Expand the required rolename or groupname item.
Under each role or group name you'll see the queries that have already been shared.
4. Right-click a query and select Delete queryname.
where queryname is the query you've selected. The following message is displayed:
Your selection contains at least one shared query. Are you sure you want to continue?
5. Click OK.
The query will disappear from that Role or Group under your own Shared or Shared TEXTML
item.
It will also disappear from these items for every other person who it has been shared with.
6 DITA maps
DITA maps
Topics: The DITA map defines the document deliverable's structure.

• About DITA Map view and It lists the component topics of that document and defines
DITA Map Editor their position in the table of contents. The map's name is used
• Topic alert indicators in the as the title of the entire document. You cannot have a
DITA Map view and DITA document without a map.
Map Editor
• Map sub-trees Map files can be located in many of the views, such as the
• Create a map Todo List and the Search Results view, where they can be
• Map ID naming constraints locked and released like other types of files.
in DITA CMS
The DITA Map view and DITA Map Editor, however, provide
• Open a map in the DITA
a hierarchical view of the map tree (the document structure)
Map view
• Open a map in a DITA map and its component sub-trees and topics. Once you have
editor locked the map, you can easily drag and drop topics and
• Switch editors sub-trees from place to place to re-order the content.
• Open a map from the map
history list
• Print a map
• Pre-publication flags
• Export map as TSV
• Edit a map
• Resolve all the topics in a
map
• Preview a map
• Adding and positioning
topics in a DITA map
• Displaying topic titles in the

DITA Map view
• Rename a DITA 1.1 map
• Rename a DITA 1.0 map
• Remove a document from
a map
• View map statistics
• Advanced DITA Map view
features
DITA maps 143
About DITA Map view and DITA Map Editor

The DITA Map view and DITA Map Editor offer similar features for working with DITA maps. DITA
Map view has additional features available from its menu.
DITA CMS provides you with two ways to look at and work with maps:
• DITA Map Editor: Appears in the editor area.

• DITA Map view: Can be positioned anyplace in the DITA Perspective (or even floated outside
the Eclipse Workbench). This view offers you all the functionality of the DITA Map Editor, with
added advanced features available from its menu button.
Both of these provide you with a hierarchical view of the map (the document structure) and its
component topics. Both let you drag and drop topics into the map, and then move them around
within the map structure. And they both have a History list that lets you quickly re-open the maps
you’ve recently been working on.
In addition, both of them offer you buttons that facilitate working with topics and sub-trees. The
Expand and Collapse buttons offer a quick way to deal with large complex sub-trees, by expanding
or collapsing all elements in the selected structure. The Print map button gives you a way of
creating a hard copy of the entire map structure. And the arrow buttons let you move documents
up and down within a sub-tree, as well as promote them within the map hierarchy.
DITA Map Editor
Use the DITA Map Editor when you want to work with more than one map at the same time:
perhaps you want to compare the structure of two very similar maps. You can have several open
in the editor area, and switch between them as you would with any other document.
Use them to add and remove topics from the map and change their position in the map. You can
even drag topics directly from one map into the other.
DITA Map View
The DITA Map view offers all the basic functionality of the DITA Map Editor and adds advanced
features that let you view map elements, build relationship tables, and perform searches on the
underlying XML of your topics and map. You can access these advanced features from its menu
button.
DITA maps 145
Topic alert indicators in the DITA Map view and DITA Map
Editor
Icons in these views let you quickly identify topics that are critical to the work flow.
When you are developing a large and complex document deliverable, it becomes difficult to spot
the topics that are keeping the map from progressing to the next stage in the document
development cycle. Similarly, if you are revising a large document, you'll want a way of identifying
exactly which topics have changed so that you can make sure that they are reviewed. DITA CMS
marks these problematical topics so that you can easily spot them in the maps you're working
on.
• Blocking topics - When a topic at the beginning of a development cycle is added to a map, the
system puts an alert indicator in the Status column. This indicator stays there until the topic
advances to a state that will let the parent map advance into its own next state.
When the map is promoted into its next state the alert indicator reappears on all topics. The
indicator stays there until all topics advance to a state that lets the map move forward into the
next cycle in the document development process.
• Modified topics - If a map has gotten to Authoring:done (or an equivalent final state, such as
Authoring:release), then as soon as you demote one of its constituent documents – whether
topic or map – to an earlier state, the system puts an alert indicator into the document's Last
Mod Date column. The icon is removed once the map returns to Authoring:done (or equivalent
final state).
Map sub-trees
Sub-trees display the hierarchy of topics in a map.
A sub-tree is a grouping of topics displayed in the DITA Map view. A sub-tree is usually comprised
of a parent topic and one or more child topics, and may also contain subordinate child sub-trees
within its structure. In fact, the DITA map file is the parent tree of all the sub-trees within the
document project.
Sub-trees can be expanded and collapsed, just like the map itself. You can also move sub-trees
around as a unit, and promote or demote them within the hierarchy.
Several of the topic functions such as Lock and Release are available as sub-tree operations in
the DITA Map view: e.g., Sub-tree > Lock.
Additionally, there is a specific feature that lets you search within specific sub-trees of a map.
DITA maps 147
Related Links
Search within a sub-tree on page 111
Create a map
A map is designed to manage topics – their order and relationships.
To start a new documentation project, you need to create a new map to structure the content.
For example, your group is creating a Training Guide to complete a documentation suite that
already has Marketing Factsheets and a User Guide.
DITA CMS offers you templates for the standard DITA ditamap and bookmap. In addition, your
system may contain custom templates designed for use in your particular working environment.
You'll see them in the Map template pane whenever you create a map.
If your working environment has a large number of templates, these may be organized into folders,
which will appear in the Map Template pane. You'll be able to navigate them to find the template
you need.
When you create a map, you have the option of assigning your own ID to the map. You can then
use this ID – or any portion of the ID – to search for the map in the repository. For example, if
you create the ID "Interim_version_3" you can search for the map using "Interim" or "version" or
"3". You can obtain this user-defined ID using the Copy ID procedure.
Note: Map IDs must follow the w3.org naming conventions.
Note: Any document that you create is automatically assigned to you.
• Press CTRL+ALT+M.
• On the Document Creation toolbar, click the Create Map button ( ).

• From the menu bar, select DITA CMS > Create Map.
The Create Map dialog appears. The ID field displays the system-assigned ID.
2. If you want—and if the field is available—you can assign the map an ID of your own.
If the field is greyed out, this means that your system administrator has disabled this feature.
3. Enter a Map Title.
Titles do not have to be unique.
4. Select a Language.
5. Select a Map template.
Templates provide you with the basic structure for the type of map you are creating and define
the rules for building the map.
6. In the Labels pane, click Select to add labels.
The labels that you select are listed in the Labels pane.
7. If the map template contains variables, the defined variable names appear in the
Template Variables section. Click in the Values column and type or select the values
for each variable as required.
8. If you want to edit the new map immediately, select Open map in DITA Map view.
If you choose not to edit the new map, you will need to use Search and open it from the
Search Results view when you are ready to edit it.
9. If you have a map open and locked in the DITA Map view, you can select the option
Add to current map as sub-map.
10. (Optional) To save the settings you have selected for Language, Map Template, and
Open map in DITA Map view, click the diskette icon at the bottom of the dialog.
Your selections are saved and used as the default values in the Create Map dialog. You'll
see them there the next time you create a map.
11. The next step depends on whether the Dynamic Release Management module is enabled
in your deployment:
DITA maps 149
• If you see the Next button at the bottom of the Create Map dialog, this module is enabled
in your deployment. Go to the next step to specify the release management details.
• If you see the Create button at the bottom of the Create Map dialog, this module is not
enabled. Click Create to create the map. You have completed this procedure.
12. Click Next.

The Select Versions dialog box is displayed. If you selected the Add to current map as
sub-map option, the version of the containing map is automatically selected in the Selected
Products, Releases, and Versions pane, since the sub-map must be added to this version.
13. In the All Products pane, select the products for which you would like to display the
releases and versions.
Use the filter at the bottom of the pane to filter the products in the list by product name.
The products, releases, and versions are displayed in the Selected Products, Releases,
and Versions pane.
14. To exclude products, releases, and versions according to the exclusion filters, click
Apply global exclusion filter settings.
15. In the Selected Products, Releases, and Versions pane, select the versions in which
the object can be used.
Use the filter at the bottom of the pane to filter the versions in the list by release name.
The Primary Version drop-down list is populated with the list of selected versions.
16. In the Primary Version list, select the primary version for the object.
The primary version is the version for which the object was initially created.
17. (Optional) To save the settings you have selected for All Products, Selected Products,
Releases, Versions, and Apply to global exclusion filter settings, click the diskette icon
at the bottom of the dialog.
Your selections are saved and used as the default values in the Select Versions dialog. You'll
see them there the next time you create a map.
18. Click Create.
The map you created is added to the repository.
Related Links
Map ID naming constraints in DITA CMS on page 150
Map ID naming constraints in DITA CMS

You must follow the w3.org naming conventions when you assign map IDs.
The guidelines in this topic are a synopsis of the most salient points of XML NCName conventions.
Map IDs must begin with ONE of the following characters:
• A-Z (uppercase letters)

• a-z (lowercase letters)
• Underscore ( _ )
In the remainder of the map ID, any of the above characters are allowed, with the addition of the
following:
• 0-9
• Period (.)
• Hyphen (-)
• Colon (:)
An exhaustive discussion of permitted characters may be found at the following URL.
http://www.w3.org/TR/xml-names11/#NT-NCName
Related Links
Create a map on page 147
Open a map in the DITA Map view

This procedure displays a map in the DITA Map view.
Tip: You can also open a map by double-clicking its name in the Todo List.
• Double-click the map name or right-click it and select Open from the menu.
Open a map in a DITA map editor

This procedure lets you open a map in one of the associated map editors.
The DITA Map Editor is supplied with DITA CMS. The other choices that appear depend on your
system configuration.
DITA maps 151
You can have several different maps open in different kinds of map editors at the same time.
You can switch from one map to another by clicking the tab with the map title; your file will appear
in the editor with which you opened it.
In fact, it is recommended that you have more than one style of editor associated with your
documents. One, like the DITA Map Editor for an overall structural view; another, such as Simple
XML Editor or Oxygen, for looking at XML details.
Note: The Open With menu option becomes available when you have two editors
associated with a given file extension. To get access to the DITA Map Editor, simply
configure Simple XML Editor as one of your *.ditamap editors.
To open a map in a DITA Map Editor:
• Right-click the map and select Open With, then select the editor from the menu list.
The map opens in the selected map editor.
Switch editors
Use this procedure to change the editor that you're using on an open document.
• The document must be topmost in the editor area.
• The editor area must not be minimized.
Once a document is open in the editor area, you can switch to one of the other editors that are
configured for use with that type of document.
1. From the DITA CMS toolbar, click the Open With... button ( ).
The list of editors configured for the current document appears.
2. Select an editor.
The current document is displayed in the selected editor.
Open a map from the map history list

This procedure opens recently opened maps from a selection list.
You must have either the DITA Map view or the DITA Map Editor open in the DITA Perspective.
DITA CMS keeps track of the maps you've been using (up to 25) and lets you select any of them
to open. You can find the list of recently opened maps at the bottom of the DITA Map view or the
DITA Map Editor.
Select a map from the history list.

The selected map opens in the view (or editor).
Print a map
You can print out the map's structure, complete with all its topics.
This feature lets you produce a hard copy of a map that's open in the DITA Map view or DITA
Map Editor so that you can quickly review its structure.
Tip: On Windows, there's a handy utility that lets you use this feature to produce a PDF
file. Just install PDFCreator.
1. In the DITA Map view or DITA Map Editor, click the Print this tree button ( ).
The Print dialog appears.
2. Select your printer and settings, if necessary.
3. Click Print.
The map structure is output on the printer.
Pre-publication flags
Icons in DITA Map view and DITA Map Editor let you quickly identify documents that are about
to be published.
When you are working in an environment where there is a lot of document re-use, there is always
the possibility that someone will demote a document that is being used in a map that's just about
to be published. This will trigger a status cascade that will send the map, and possibly many of
its subordinate documents, back to the beginning of the Authoring cycle. All of them will then
have to be checked and promoted back to the appropriate level before the map can move on to
the Publication cycle.
For this reason, as a map and its topics reach their final approval stage, DITA CMS puts on
pre-publication flags to warn people that these documents are about to be published.
Images are also flagged; you'll see these in Search Results, Dependencies view, or your Todo
List.
The system will automatically remove the pre-publication flags when the map is published, or if
it's demoted back to an earlier state.
DITA maps 153
Export map as TSV

This procedure exports the contents of the DITA Map view as a TSV file.
You can export the map structure and save it in a format (Tab Separated Values) that can be
easily imported into other programs, such as a spreadsheet. Only the currently displayed columns
will be exported.
1. In the DITA Map view, click the Export Map as TSV button ( ).
The Save As dialog appears.
2. Confirm or change the proposed file name and location.
3. Click Save.
The file is saved in the specified location.

Edit a map
The Edit procedure locks and opens a map at the same time.
The file must not be locked by another user.
Use Edit to save yourself a step when you want to edit a map that is not locked.
Maps can be opened for editing from almost any view in the DITA Perspective, as long as they
are in a state that allows editing. You cannot, for example, edit a map that is in the final review
state (or its equivalent in your workflow).
1. Use Search to display the map in the Search Results view.

Tip: You can also open a map by double-clicking its name in the Todo List.
2. Right-click the map and select Edit from the menu.
The map is locked and opens in the DITA Map view.
Resolve all the topics in a map

You can now resolve all the topics when opening a map.
Note: This feature applies to oXygen only.
This option can be useful to see the content of the whole map without having to generate the
output of the map.
When you select this option, you can see the contents of the map in the Author view of the map.
For example:
DITA maps 155
Note: You can see the content of the map, but you cannot edit it. You must open each
object separately before you can edit it.
This option also allows you to open the map in oXygen and not see error messages such as the
following:
To resolve all the keys in a map:
1. Open a view that lists the map.

2. Right-click the map and select Open With > XML Editor with resolved topics.
The DITA CMS resolved all the keys in the map and opens the map. Depending on the size
of the map, this can take a long time.
Preview a map
You can view the contents of a map using the Show Preview command.
When you use the Show Preview command, the DITA CMS lists the objects in the map, as
shown below:
Some notes:
• You need Output Generator Version 4.0 and up to preview a map.

• The Conditionals panel, which is displayed in the Preview view for topics that contain conditions,
is not displayed for maps.
Note:
To view the contents of a map:
1. Open the Preview view.

2. Use Search to find the map to preview.
3. Right-click the map and select Show Preview.
DITA maps 157
The preview of the map is displayed.
Adding and positioning topics in a DITA map

The DITA Map view and DITA Map Editor both offer a variety of ways to add your topics and
position them within the map hierarchy.
Drag documents into a map

You can add content to a map by dragging in topics and maps from other views.
The map must be locked.
Topics and other maps may be added to maps using a drag and drop technique. This lets you
control where you want the document to appear in the final document deliverable. You can drag
in one or several documents at the same time.
You can add a topic to more than one map.

2. In the Cycles panel of the Search view, select the Authoring or Published check box.
(The actual check box value depends on your workflow).
3. In the Document Type panel of the Search view, select the appropriate check box(s).
• Topics
• Maps

Documents matching the selected type(s) are displayed in the Search Results view.
5. Drag and drop the required document(s) into the map.
• If the cursor is a highlight, the document(s) will be added as a child of the selected file (as
shown in the illustration below).
• If the cursor is a solid line, then the document(s) drop into the map at the level of the line's
end.
• In the second example of the figure, the document(s) will be moved to the same level
as the topic "GUI modifications".
• In the third example, the topic(s) will be moved to the level of "View: My Todo list".
The document(s) appear in the map at the place you dropped them.
Add a topic to a map from the XML editor

You can now add a topic to the map displayed in the DITA Map view when you're working in the
XML editor.
To add a topic to the current map from the XML editor:
Note: The map must be locked.
1. In the XML editor, select the topic to add to the current map.
The tab for that topic is highlighted.
2. In the DITA Map view, select where to add the topic.
3. From the DITA CMS toolbar, click the Append to Map button ( ).
The topic will be added to the map in the DITA Map view. If a topic was highlighted in the
map, the new topic will be added after the highlighted object. Otherwise, the topic will be
added at the end of the map.
Move a document within a map using drag and drop

You can move topics quickly and intuitively using the mouse.
Moving documents within a map lets you decide where information will appear in the final document
deliverable.
Note: If you move the parent topic of a sub-tree, all the child topics move with it.
• In the DITA Map view drag and drop the document into the map.
• If the cursor is a highlight, the document will be added as a child of the selected file (as
shown in the illustration below).
• If the cursor is a solid line, then the document drops into the map at the level of the line's
end.
DITA maps 159
• In the second example of the figure, the document will be moved to the same level as
the document "GUI modifications".
• In the third example, the document will be moved to the level of "View: My Todo list".
Promote a document in a map

You can easily move selected documents and branches to a higher level in a map's hierarchy.
Use the buttons at the top of the DITA Map view and DITA Map Editor to promote documents
within a map.
1. In the DITA Map view or DITA Map Editor, highlight the document you want to promote.
2. Click the Promote one level button ( ).

Tip: You can also use the shortcut keys CTRL+LEFT ARROW.
In the pictures below, the highlighted topic on the left is a child of "Working with views and
editors".
In the picture on the right, it has been promoted one level.

Tip: You can use the CTRL+Z and CTRL+Y shortcut keys to undo and redo moves within
a map.
Demote a document in a map

You can easily move selected documents and branches to a lower level in a map's hierarchy.
Use the buttons at the top of the DITA Map view and DITA Map Editor to demote documents
within a map.
1. In the DITA Map view or DITA Map Editor, highlight the document you want to demote.
2. Click the Demote one level button ( ).

Tip: You can also use the CTRL+RIGHT ARROW shortcut keys.
In the pictures below, the highlighted topic on the left is a first-level child of the map:
"Introduction to DITA CMS".
In the picture on the right, it has been demoted one level to a child of the topic "Working with
views and editors".
DITA maps 161
a map.
Move a document up or down in a sub-tree

You can easily move selected documents and sub-trees up or down within a specific sub-tree in
a map.
Use the buttons at the top of the DITA Map view and DITA Map Editor to move documents up
or down.
1. In the DITA Map view or DITA Map Editor, highlight the document you want to move.
2. Click either:
• The Move one level up button ( )

• The Move one level down button ( )
Tip: You can also use the CTRL+UP ARROW and CTRL+DOWN ARROW shortcut
keys.
The document moves one level up or down.

a map.
Define a map drop point

This procedure defines points in the map where topics and other maps may be easily inserted.
You can specify a document within a map as a insertion point where other documents (topics
and maps) may be added. This is particularly useful if you are adding topics to specific sub-trees
of a large and complex map.
You can specify topics, sub-trees, or other maps within the parent map as drop points.
Note: The drop points defined are active until you open another map in the DITA Map
view.
2. Right-click the topic or map file and select Set Drop Point.
A drop point decoration appears on the selected document.
You can now use these points as targets when you are adding documents from other
views.
Related Links
Add documents to a map using drop points

You can use specified drop points to add topics and maps to another map.
• The target map must be locked and open in the DITA Map view.
• Drop points must be defined in the target map.
Once you have defined the drop points within a map, you can add topics and other maps from
any other view within DITA CMS.
Document(s) may be added as children or as siblings of the document where a drop point is
defined.

2. Right-click the document(s) you want to add to the map and select one of the following:
• Insert as Child of Drop Point > target_document

• Insert After Drop Point > target_document
where target_document is a drop point defined within the map.

DITA maps 163
The document(s) are added to the map at the specified drop point.
Related Links
Displaying topic titles in the DITA Map view

The DITA Map view lists the topics that are included in a map.
The topic title displayed in the map may come from different sources, such as the <title>
element or <navtitle> element or attribute, depending on how the topic is defined in the map:
• If the topic is a reference to an existing topic file, the title displayed in the map is the value of
the <title> element set in the topic file. This will be the case for most topics.
For example, consider the following chapter in a map:
<bookmap id="lar1367336063736" xml:lang="eng">

<title>Sample Bookmap</title>
<chapter href="topicA.xml"/>
</bookmap>
The topicA.xml file has the following content:

<concept id="topicA" xml:lang="eng">
<title>Topic A title, taken from title element</title>
<conbody>
...
</conbody>
</concept>
The title of this chapter will be "Topic A title, taken from title element" in the DITA Map view,
as shown below:
• If the topic is not an href, that is, it does not reference an existing topic file, then the title is
taken from the navtitle attribute set directly on the topic, if available.
For example, consider the following map:

<chapter/>
<chapter href="lar1367336223394.xml" keys="lar1367336223394"/>
<chapter navtitle="Topic title, taken from navtitle attribute">
<topicref href="jan1237671609803.xml" keys="jan1237671609803"/>
</chapter>
</bookmap>
The chapter highlighted in bold does not refer to an existing topic file; instead, it is used as a
container chapter for a set of topics. The title of this chapter will be "Topic title, taken from
navtitle attribute", as shown below:
• If the topic is not an href and the navtitle attribute is not set directly on the topic, then the
title is taken from the <navtitle> element if set for that topic.

<chapter/>
<chapter href="lar1367336223394.xml" keys="lar1367336223394"/>
<chapter navtitle="Topic title, taken from navtitle attribute"/>
<chapter>
<topicmeta>
<navtitle>Topic title, taken from navtitle element</navtitle>
</topicmeta>
</chapter>
</bookmap>
The title of the chapter highlighted in bold will be "Topic title, taken from navtitle element", as
shown below. Note that, to show that the title was not set directly on the chapter element but
rather was pulled from another element, the title is displayed in italics and starts with a number
sign (#):
DITA maps 165
Some notes:
• For all maps other than bookmaps, the titles for topics that are not hrefs are only displayed
when the Show Elements option is selected.
• The display of navtitle attributes and elements in the output depend on your transformation
scenarios. This section only covers how they are displayed in the DITA CMS.
Using the navtitle element with the locktitle and href attributes
In previous releases, the DITA CMS always displayed the title of the referenced topic in the Map
view, even when a <navtitle> was specified and the locktitle attribute was set to "yes".
This behavior did not correspond with the DITA 1.2 Specification.
As of Build 82, this issue has been fixed and the Map view displays the topic titles according to
the DITA 1.2 Specification. For more information, see:
• <navtitle> element: http://docs.oasis-open.org/dita/v1.2/os/spec/langref/navtitle.html

• locktitle attribute:
http://docs.oasis-open.org/dita/v1.2/os/spec/common/topicref-atts.html

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE map PUBLIC "-//IXIA//DTD IXIA DITA Map//EN" "IxiaMap.dtd">
<map id="lar1383859055407" xml:lang="eng">
<title>My Map</title>
<topicref href="lar1383850302167.xml" locktitle="yes">
<topicmeta><navtitle>my navtitle</navtitle>
</topicmeta>
</topicref>
</map>
Since the locktitle attribute is set to "yes" and a <navtitle> element is specified, the
topic title displayed in the Map view will be the content of the <navtitle> element (i.e., "my
navtitle"), as shown below:
Now consider the following code:

<map id="lar1383859055407" xml:lang="eng">
<title>My Map</title>
<topicref href="lar1383850302167.xml" locktitle="no">
<topicmeta><navtitle>my navtitle</navtitle>
</topicmeta>
</topicref>
</map>
Since the locktitle attribute is set to no, the topic title displayed in the Map view will be the
title defined in the referenced topic (even if the <navtitle> element is specified), as shown
below:
Note: As of DITA 1.2, using the <navtitle> element of the <topicref>/<topicmeta>

element is preferred over the navtitle attribute of the <topicref>. As such, the DITA
CMS ignores the navtitle attribute when used with the locktitle="yes" attribute.
DITA maps 167
Rename a DITA 1.1 map

This procedure renames a map created with a DITA 1.1 DTD.
DTDs that follow the DITA 1.1 specification use the map's title element to assign a name to a
map. If your map was created using such a DTD, then you will use this procedure to rename it.

2. Lock and open the map or right-click it and select Edit from the menu.
The map opens in the DITA Map view.
3. If necessary, click the DITA Map view’s Menu button and select Show Elements.
4. Open the Properties view. Either:
• Click its tab if it's already available in the workspace, or

• From the menu bar, click Window > Show view > Properties
The Properties view appears.

5. In the DITA Map view, highlight the <title> element.
In the Properties view, the map's name is displayed in the Value field of the Content property.
6. Change the Value as required.
7. (Optional) To see the new name, release the map and double-click the map title to
refresh the view.
Rename a DITA 1.0 map

This procedure renames a map created with a DITA 1.0 DTD.
Under the DITA 1.0 specification, DITA maps obtained their names from the title attribute of the
map element. If your map was created using such a DTD, then use this procedure to rename it.

2. Lock and open the map or right-click it and select Edit from the menu.
3. Highlight the map name.
4. Open the Properties view. Either:
• Click its tab if it's already available in the workspace, or

• From the menu bar, click Window > Show view > Properties.
The Properties view appears.

5. In the Property column, scroll down the list of Attributes and find the title attribute.
6. Change the Value of the title attribute as required.
7. (Optional) To see the new name, release the map and double-click the map title to
refresh the view.
Remove a document from a map

You can use this procedure to remove topics and maps from other maps.
A document can be easily removed from a map if it is not required for a given document
deliverable. This will not affect other maps where a topic may be referenced.
Tip: If you remove a parent topic from a map, all its children are removed as well. If you
want to keep child topics in a map, first move them elsewhere in the map.

2. Right-click the map, topic, or parent topic for a sub-tree, and select Remove from Map.
If you are removing a sub-tree or a map, the Remove Map dialog asks if you are certain you
want to remove the topic and all its children from the map. Click Yes to continue.
The selected documents are removed from the map but stay in the repository.
View map statistics

The map statistics feature displays a pie chart that shows the number of documents that have
arrived at each status point.
The number of documents at each status point is shown both as a fraction and as a percentage
of the total number.
Note: The total number of documents is the sum of:
• The parent map file

• Topics referenced by the parent map
• Images referenced by the topics
• All referable-content topics used by the topics
DITA maps 169
• Sub-maps referenced by the parent map

• All topics, images, referable-content topics, sub-maps etc. referenced by these sub-maps
Buttons on this display window let you print its contents or export them as a PDF.
To view map statistics:
• Do one of the following:
• In the DITA Map view or DITA Map Editor, click the Show statistics button ( ).
• In Project Management view, right-click any map and then select Show Statistics.
The statistics display appears.

Advanced DITA Map view features

DITA Map view's pull-down menu offers advanced features that let you, among other things,
quickly design a map's structure and then generate the requisite topics.
The topics listed below are dealt with in this section. Search and Replace is described in the
chapter on Search utilities.
About Advanced DITA Map view features

Advanced DITA Map view features are accessed from the DITA Map view's pull-down menu and
from the Properties view.
In the picture below, you can see that element names are showing in the DITA Map view. The
DITA Map view's pull-down menu is open with the Hide Elements option selected.
The Properties view is open also, and you can see that the currently selected map element has
been given the navtitle "Vista Settings".
DITA maps 171
Clear the History list

This procedure removes all entries from the DITA Map view's History list.
Use this procedure when you want to erase all record of previously opened maps.
1. Click the DITA Map view’s Menu button.

The view's pull-down menu appears.
2. Select Clear History List.
All map entries are removed from the DITA Map view's History list.
Display map elements

This procedure makes all the elements in a map visible, along with their tags.
Use this procedure when you want to see all the elements in your map and their XML tags. This
includes otherwise hidden elements, such the map's keywords.

3. Select Show elements.
All elements and their tags are displayed in the map.

Related Links
Inserting a keyword or external link from keys defined in the map on page 391
Add an element to a map

This procedure adds a DITA element directly into a map.
• The map must be locked.
• Map elements must be displayed
Use this procedure to add any of the elements defined in your map's DTD directly to your DITA
map. For example, if you are using a template that supports bookmaps, you could add elements
such as <chapter> and <section>.
You can also use this procedure to add topic elements directly to a map, if you are using the
topic stub feature.

2. Highlight the map element where you want to insert the new element.
3. Right-click the element and select Insert Element > elementname from the menu
where elementname is one of the selections on the menu: topicref, for example.
Your selected element is inserted into the map.

If you want to add text to the element or specify its attribute values, you can do this using
the Properties view.
DITA maps 173
Edit map element attributes

This procedure lets you edit the attributes of a map element.
• Map elements must be displayed.
If you are using the topic stub feature to plan the structure of a map, this procedure lets you
specify the topic navtitle and type. This is also the procedure you use for specifying topic types
when you are working with reltables.
Note: Some attributes cannot be edited from the Properties view. For example, you cannot
change the class or the conditions (audience, product, platform, etc.) from that view.
2. Highlight the map element whose attributes or text you want to edit.
3. Open the Properties view.
4. If necessary, expand the Attributes node.
The element's attributes are listed in alphabetical order.
5. Type a Value in the field next to the appropriate attribute(s).
For example, you could enter "task" (without quotation marks) in the field next to the type
attribute.
Your values are added to the map file.
Change a map element

This procedure lets you re-tag the elements in a map.
• Map elements must be displayed
Use this procedure to change a map element into another element that's valid in that position in
the map.You could, for example, change a <shortdesc> into a <searchtitle>. Or you could
change a <topicref> into a <chapter>.

2. Highlight the map element you want to change.
3. Right-click the element and select Change Element > elementname from the menu
where elementname is one of the selections on the menu: shortdesc, for example.
Your selected element replaces the original in the map.

If you want to add text to the element or specify its attribute values, you can do this using
the Properties view.
Create a topic stub

Topic stubs let you create an empty position in a map; they act as place holders and can be used
to create document outlines.
If you're creating <topicref> elements in a map, you can use the Create Topic Stub dialog to
simultaneously assign navtitles and type attributes.
This procedure simultaneously creates a topic stub and supplies the necessary attribute values.

2. Highlight the map element where you want to insert the new element.
3. Click the DITA Map view's Create Topic button ( ).

The Create Topic Stub dialog appears.
4. Enter a topic title in the Topic Title box.
5. Select a template from the Topic Template list.
6. Click Create.
A new <topicref> element is added to the map and assigned navtitle and type attributes based
on your entries in the Create Topic Stub dialog. You can change navtitle and type, if you want,
by editing these attributes.
The topic will be created when you generate topic stubs.
Generate topic stubs

This procedure generates topics from the elements in a map.
• Navtitle attributes must be assigned to <topicref> elements.
• Type attributes must be assigned to <topicref> elements.
After you have inserted <topicref> elements and assigned each element a navtitle and
type attribute, you are ready to turn these elements into topic stubs.
DITA maps 175
Note: If any of your elements do not have navtitle attributes, you won't be able to start
the generation process.

2. Click the DITA Map view’s Menu button ( ).
3. Select Generate Stubs.
The Generate From Stub dialog appears.
This dialog displays all the <topicref> elements in the map that have not yet been turned
into topics.
If a title is displayed in red it is not in a valid state for stub generation. The Comment column
shows the reason. In the screen shot below, three of the titles are showing "Missing or invalid
template". This may be because their type attributes have not been set.
4. (Optional) You can assign a topic type at this time by selecting a Template.
This method can also be used to change topic types on the fly.
5. (Optional) You can edit any Title at this time, if you want.
6. Select the elements that you want to generate stubs from.
If you select the checkbox next to the map Title, you can generate stubs from all the elements
that are ready.
7. Click OK.
The selected map elements are turned into topics, using the templates appropriate for the
type, and are added to the map.
Validate out-of-scope links

The Validate Links command detects any out-of-scope links, that is, links that point to documents
that are not in the current map. This command also applies to reltables: If a reltable contains a
DITA maps 177
reference to a topic that is not in the map scope, the Validate Links command returns an
out-of-scope error.
You cannot publish a map that contains out-of-scope links.You should run this command regularly
to confirm that all your links are correct.

2. Select Validate Links.
The DITA CMS scans all the files in the map and checks that all the links refer to documents
that are in the map.
If no out-of-scope link is detected, the following message is displayed:
If out-of-scope links are detected, a message similar to the following is displayed:
This message indicates that one or more documents in your map refer to the topic "Default
roles" (with ID mal1306465423706), but this topic is not in the map. To find this reference:
1. Search for the topic with ID mal1306465423706 or click Locate.

2. View the dependencies of the topic, and look for the Cross-referenced by section.
For example:
This view shows that topic "Assign documents to users" is referencing the topic "Default
roles." If you open the "Assign documents to users" topic, you will probably find the faulty
link. You can fix it and run the command again.
7 Document management
Document management
Topics: This set of topics describes management functions common

• Lock a map, topic, image, to all DITA CMS document objects.
or resource
• Release a locked map,
topic, or image
• Clone a map, topic, or
image
• Display document object
properties
• Change status
• Delete a document object
• Restore a document object
• Synchronize configuration
files
• About the Information view
Lock a map, topic, image, or resource

Before you can modify a map, topic, image, or resource, you must lock it.
Prerequisites:
The map, topic, image, or resource must be in the unlocked state.
Note: Any DITA CMS map, topic, image, or resource can be locked.
Locking a document prevents other users from accessing the file and makes it available for
editing. Authors lock files to edit them or merely to prevent other users from modifying them. Any
changes are saved on your local hard drive until the file is released. The Lock function is available
from all DITA CMS views. For images and resources, it is also available from the Show/Edit
dialog.
To lock one or more document objects:
1. Search to locate the map, topic, image, or resource you want to lock.
2. Select one or more document objects.
3. Right-click and select Lock.
Tip: If you are in DITA Map view, to lock all children of a given topic, select the topic,
right-click, and select Sub-tree > Lock.
The selected documents are now locked for your exclusive use. The locked documents are
displayed in blue in the DITA CMS, and the Locked By column (if selected for your setup)
displays the ID of the user who locked them.
4. Double-click a document object to open it for editing.
Tip: The procedure above described how to lock and then open a topic. Alternatively,
to lock an already-open topic:
• From the oXygen editor, click the Lock icon on the toolbar ( )
Related Links
Change status on page 187
Release a locked map, topic, or image

The Release command saves your latest modifications to the server and frees the file so other
users can edit it.
Prerequisites:
Document management 181
• The document object (that is, a map, image, or topic) must be in the locked state.
• Document objects can only be released by the user who locked them.
Releasing a map, topic, or image saves your latest modifications to the server and frees the file
so other users can edit it. In the case of a map, the release command updates changes to the
map's structure. In the case of an XML topic, the release command validates the topic to ensure
that references are correct and that the XML is well-formed. If your XML document has errors,
you will be able to save it locally, but you will not be able to release it to the server. Using the
release function regularly serves two purposes:
• Data preservation: saves a copy of your work in the repository.

• Collaboration: shares your update with other users.
The Release function is available from all DITA CMS views.
To release a document:
1. Search to locate the map, topic, or image you want to release.

2. Select one or more document objects to release.
3. Right-click and select Release.
The Release dialog box appears:
Figure 44: Releasing a topic

4. Do one of the following to describe the changes since the last update:
• Under Comment, enter a comment.

• Select a comment from the Choose a previously entered comment area.
• Select one or more comments in the Preset comments area.
Note: If preset comments have not been configured for your DITA CMS, the Preset
comments area will be blank.
5. (Optional) If you are using a bug tracking system (such as JIRA or Bugzilla), add the
bug number that you are fixing with this release in the Tracker link field.
A link to the bug will be added to the Release History. To add more than one bug, separate
them by a comma.
6. (Optional) To update the document without releasing it, select Keep locked.
Note: The Substantial Change option, selected by default, means that when the
document is released, it can be advanced to the next status (typically edit/review).
However, if you made a minor change to a previously-edited topic, you can clear the
Substantial Change option. The document state will pass directly from rework to
done (or according to your configuration) and the document will not appear in SMEs'
Todo lists.
7. Click OK.
The document is updated in the repository of your Content Store. If you release a document
that has not been changed, the lock is simply removed; no new document version is created
in the DITA CMS. If you did not keep the file locked (Step 5), the file properties are displayed
in black text in the various views. The comment you specified appears under Last User
Comment in Todo Lists, as well as in the other places that file properties are displayed, such
as Search Results view and DITA Map view.
Tip: The procedure above described how to release a closed topic.

Alternatively, you can use release to update an already-open topic:
If you're using the Oxygen editor and you want to release a topic that's
currently open in your editor, you can do one of the following:
• In Text mode, right-click anywhere in the topic, then select Release.

• Press CTRL+ALT+SHIFT+R.
•
Click the Release file button in the toolbar ( ).
Related Links
Release all subtopics for a topic

You can easily release all the subtopics of a topic in a DITA map.
Prerequisites:
• The topics must be in the locked state.
• Files can only be released by the user who locked them.
Use this procedure to release an entire group of subtopics quickly. Note that you cannot
enter comments for sub-topics released this way. If you wish to add comments, use the
release documents procedure instead.
To release all subtopics for a topic:
1. Open the map with the topics you want to release.

2. In the DITA Map view, click the expand icon: to display all nodes in the map.
3. Select the parent topic whose sub-topics you want to release.
4. Right-click and select Sub-tree > Release.
A confirmation window appears:
Figure 45: Confirming a multi-topic release
5. (Optional) Click Yes.

The subtopics are updated in the repository of the Content Store and are once again available
to other DITA CMS users.
Clone a map, topic, or image

The Clone command creates maps, topics, and images from existing ones.
Prerequisites:
• The map, topic, or image must be unlocked.

• You must have the required access rights. See your CMS administrator for more information.
Cloning creates a copy of a map, topic, or image with a new ID. Topics can be cloned to create
a copy of a topic as a starting point for developing a similar—but not identical—topic for use in
a separate map. Similarly, maps can be cloned to serve as a starting point for creating a document
that will share many of the same topics as the original map. Images can be cloned when you
want to create a similar image but you need to keep the original one. The Clone command is
available from all DITA CMS views.
When cloning a map, topic, or image, the following options are available only if the containing
map is locked and opened in the DITA Map view:
• Replace original component: The cloned map, topic, or image is created and added to the
containing map; the original map, topic, or image is removed from the map but is not deleted.
All external cross references that point to the original map, topic, or image are kept as is; they
are not updated to point to the cloned map, topic, or image. Internal cross references (from
point A to point B in the original topic) are updated in the cloned topic.
• Append to parent: The cloned map, topic, or image is added to the containing map. When
you select this option, the Replace original component option is disabled.
1. Search to locate the map, topic, or image to clone.

2. Right-click the map, topic, or image and select Clone.
Tip: If the Clone option is not selectable, your map, topic, or image may be locked.
Right-click the map, topic, or image and select Release, then try again.
Tip: If you want to select one of the Options for current map but they are greyed
out, the containing map is not locked. The containing map must be locked and opened
in the DITA Map view. Open the map in the DITA Map view, right-click the map that
contains the map, topic, or image, select Lock, and try again.
3. Beside Title, enter a name for the map, topic, or image.
Note: By default, the original map, topic, or image title is provided beside Title, with
the prefix "cloned". The cloned map, topic, or image can have the same title as the
original and it will still be distinct, since it will have a different filename. Use your
judgment as to whether the cloned map, topic, or image should have the same title or
whether a different title is more appropriate. For example, a cloned topic that covers
a procedure for a different OS might have the same title with changes to certain steps;
a cloned topic that is being used as a starting point for a different procedure would
have a different title and different steps.
4. To replace the original map, topic, or image with the clone, select Replace original
component.
The cloned map, topic, or image is created and added to the containing map; the original
map, topic, or image is removed from the map but is not deleted.
5. To add the clone to the map displayed in DITA Map view, select Append to current
map.
Note: This option is not available if you selected Replace original component
6. To have the map, topic, or image open in your DITA CMS workspace immediately once
it is created, select Open in default editor.
7. Click Clone.
The cloned map, topic, or image is created with a unique filename and is added to the
repository.
8. If you selected Open in default editor, you may now make changes to the map, topic,
or image as required.
9. If you selected Append to current map, drag the new topic to the required position in
the map.
Display document object properties

Every document object in the repository has a set of properties that describe and identify it
uniquely.
Document properties include information such as the file name, status, creation date, and
last modified date. This information is updated each time there is a change to the file.
To view properties for a document object:
1. Open the DITA CMS DITA perspective.

2. Search to locate the document object you want to view.
3. Right-click the file and select Properties.
The File Properties window appears:
Figure 46: File Properties window for a topic
Properties are categorized as follows:
• File System Information: Provides the file name, path, size, and MIME type.
• Creation Information: Provides information on the documentation team members who
have worked on the file and the dates.
• Metadata Information:Provides the file type, status, title, language, lock, and document
cycle status.
• Version Label: Provides the last published version of the document and other version
details. Version labels appear in the Version: Provides the version labels applied to this
object.
4. Click Close.
Change status
This procedure describes how to update the status of a document object in the document cycle.
Prerequisites:
• The document object must have a status other than published (or as defined in your
configuration).
• The document object must be unlocked.
This function is available from all DITA CMS views.
1. From the DITA perspective, perform a search to locate the document object.
Tip: For topics, you might prefer to search for and open the parent map. Expand the
map ( ) to view all its topics.
2. Release any locked document objects for which you want to change the status.
3. Select the document objects for which you want to change the status.
Note: If you are selecting more than one document object, they must all have the
same status (check the Status column).
4. Right-click and select Change Status from the menu.
The Change Status window appears:
Figure 47: Change Status window
The statuses available depend on which cycle is applicable for the parent map (Authoring
in the example above) and the states configured for your DITA CMS.
5. Do either of the following:
• Beside New Status, select a status from the drop-down list.

• Click a status in the flow chart.
Note: If you cleared the Substantial Change option when releasing the document
object, certain states may not be available.
6. (Optional) To enter a comment, do one of the following:
• Under Comment, enter a comment.

• Select a comment from the Choose a previously entered comment area.
• Select one or more comments in the Preset comments area.
Note: If preset comments have not been configured for your DITA CMS, the Preset
comments area will be blank.
The comment that you enter will appear under Last User Comment in everyone's Todo
Lists, as well as in the other places that file properties are displayed.
7. Click Change.
Note: If your system is configured for obligatory comments, you will need to enter a
comment.
If this change impacts other documents—other maps that refer to a topic, for example—a
warning dialog appears.
8. Click OK to continue with the change.

The status is updated and displayed in the various views.
If you have demoted a document to the beginning of its cycle, you are automatically assigned
that document.
Related Links
Document development process on page 43
Document status dependencies on page 46

About document cycles on page 42
Lock a map, topic, image, or resource on page 180
Delete a document object

The Delete command removes objects from the active area of the repository.
Prerequisites:
• The file must be unlocked.

• The file cannot be referenced by another active map or topic.
Tip: Use the Dependencies view to locate references to a file.
DITA CMS maintains the files you are working on in the active area of the repository. Over time,
you may want to eliminate unnecessary maps, topics and images--for example, multiple topics
of the same name, some of which are outdated or contain inaccuracies. The delete function lets
you eliminate such files from the active area, without erasing them altogether.
The Delete function is available from all DITA CMS views with the exception of the DITA Map
view.
1. Perform a search to locate the document object you want to delete.

2. Right-click the file and select Delete from the menu.
The Delete dialog appears:
Figure 48: Confirming a deletion
3. Click OK.
The file is deleted from the active area of the repository.
Note: Accidentally deleted files may be recovered with the Restore function.
Note: If you get a Cannot Delete window, see Troubleshooting unresolved
cross-references on page 247.
Restore a document object

The Restore command lets you recover files that you may have inadvertently deleted.
Documents are restored to the earliest working state of the cycle that they were in when deleted.
For example, if you delete a topic that has reached Authoring:done, it will be restored to
Authoring:work status (or its equivalent in your workflow).
To recover deleted maps, topics, or images:
1. Search using the Deleted option in the Cycles panel.

Tip: Use the Dates panel to limit the number of files returned.
Note: Alternatively, you can locate recently deleted documents in the Recent
Operations panel of Documents view, under the applicable Delete operation.
Deleted files appear in the Search Results view.
2. Right-click the file and select Restore.
The file is restored to the active area of the repository. Documents are restored to the earliest
working state of the cycle that they were in when deleted.
Note: The Status column is not automatically refreshed. To check the document
object's status, right-click and select Properties.
3. If necessary, update the document's status.
Related Links
Documents view on page 70
Synchronize configuration files

You can easily update your DITA CMS configuration with the most recent configuration settings
on the server.
This procedure copies the most recent version of system configuration files from the server onto
your hard drive. This lets you work with updated information without having to restart Eclipse.
This is useful if the system administrator has updated a style sheet for your preview browser, for
example. Or if new users have been added to the system, and you want to assign documents to
them.
• To synchronize your configuration, do one of the following:
• From the menu bar, select DITA CMS > Synchronize Configuration.
• Press CTRL+SHIFT+S.
• On the Global Actions toolbar, click the Synchronize Configuration button .
About the Information view

The DITA CMS offers a view that provides information about an object selected in any DITA CMS
view (such as the Search Results and DITA Map views).
The following diagram shows a sample Information view:
The Information view provides the following details:
• The Display All Values section lists the values for all the fields that can be displayed in any
view (for example, in the Search Results columns). This information is configurable per
deployment.
Note: For more information about adding or removing the information displayed in the
DITA CMS views, see the DITA CMS Administrator's Guide.
• The Display Parents section lists the parents (for example, containing maps) to which the
selected object belongs.
View information about selected objects

You can view information about DITA CMS objects using the Information view.
The Information view is updated whenever you select an object in any DITA CMS view.
To view information about an object:

1. To display the Information view, from the menu bar select Window > Show View >
Other.
The Show View window is displayed.
2. Expand DITA CMS - General, select Information, and click OK.
The Information view is displayed.
3. Select an object in any of the DITA CMS views (DITA Map, Search Results,
Dependencies, etc.).
The Information view is updated and provides details about the selected object.
4. To customize the information displayed in the Information view:
a) Click the Show/Hide Sections button ( ) in the top-right corner of the view.
b) Customize the options as follows:
• Display All Values: Clear this option to hide the values section.
• Display Parents: Clear this option to hide the parents section.
• Show Empty Values: Clear this option to see only the fields with available values.
The view is updated with your changes.
By default, the Information view is updated whenever you select an object in any DITA CMS view.
You can disable this behavior by pinning a specific document in the view.
Disable update of the Information view

You can keep a specified document open in the Information view while you open other documents.
By default, the Information view is updated whenever you open a document. You can disable
this behavior by pinning a specific document in the view.
To disable update of the Information view:
• In the Information view, click the Pin Content button.
The Information view will no longer be updated when you open other documents.
8 Revision control
Revision control
Topics: File revisions are managed by the system.

• Replace with server Whenever a file is revised and released, the system creates
revision a new revision. You can consult the revision history and
• View revision history
compare your current work with the earlier revisions and, if
• View a previous revision
necessary, replace the current version with one of the
• Revert to older revision
revisions on the server.
• Compare documents
Replace with server revision

This procedure removes the lock on topics, images, a map or a sub-tree of topics. Local work is
not saved.
Replacing a file with the server version removes the lock on the file and replaces your local copy
with the last saved version in the repository. Modifications made locally since the file was locked
are not saved.
This procedure is also available for maps and sub-trees. In this case, it's called Replace sub-tree
with server revision. The Replace sub-tree with server revision option only appears in the DITA
Map view.
Tip: If you're using the oXygen editor and you want to replace a topic that's currently open
in your editor with its last server revision, you can do one of the following:
• In Text mode, right-click anywhere in the topic, then select Replace with Server
Revision.
• Click the Replace with server revision button in the toolbar ( ).
The Replace with server revision function is available from all DITA CMS views.
1. Right-click the file and select History > Replace with server version (or Sub-tree >
Replace sub-tree with server revision if applicable) from the menu.
Tip: You can select several files by holding down CTRL or SHIFT and clicking the
files.
The Confirmation dialog tells you that replacing the file will undo all local modifications.
2. Click Yes.
If you are reverting a sub-tree, a Progress Information dialog will appear.
The file is replaced and its name will be displayed in black text in the view where you
locked it.
View revision history

You can view a list of the revisions available in the repository for a specific file.
Whenever a file is modified and released, and after certain status changes, the system creates
a new revision. These are kept in the repository in case you want to revert to a previous revision
or compare revisions to see what has changed. Details in the revision history include the revision
number, who made the modification, and when it was made.
Revision control 195
The system also creates a new revision when a document is demoted from its final status (for
example, "done" or "released") back to an earlier status point.
In the screenshot shown below, revision #3 shows the file's progress from Authoring:start to
Authoring:accepted. Revision #4 was generated when the file was promoted to Authoring:done;
and revision #5 when the file was demoted back to Authoring:start.
Note: States and status points are installation-specific. Those shown in the illustration
are the ones used at IXIASOFT Technology and may differ from the ones used in your
working environment.
The View revision history function is available from all DITA CMS views.
To view the revision history:
1. Use Search to display the file in the Search Results view or scroll to find it in the DITA
Map view.
2. Right-click the file and select Revision History... from the menu.
The Revision History dialog displays the list of file revisions, with the latest at the top.
3. Close the dialog box when you are done.
View a previous revision

You can view an earlier version of a document.
Use this procedure to open a read-only copy of an earlier version of a document, without affecting
the current version in any way.
1. Right-click the document and select History > Revision History... from the menu.
The Revision History dialog displays the list of file revisions, with the latest at the top.
2. Double-click the revision you want to view.
• If you select a topic, a read-only copy of the earlier document opens in the editor area
• If you select an image the Show/Edit Image dialog displays the earlier version and its
metadata. You can view any of the image resolutions.
• If you select a resource, the Show/Edit Resource dialog displays the earlier version and
its metadata. You can open any of the items that it contains.
• If you select a map, a copy of the earlier map opens in the DITA Map view.
Note: The map file is a copy and cannot be edited. But the topics that it contains
may be actual topics and may be edited like any other topics.
3. Click Cancel to close the Revision History dialog.
The document will remain open in the workspace until you close it.
Revert to older revision

The Revert operation replaces the current version of an object with an earlier revision in the
repository.
Prerequisites:
• The object must not be locked.

• The object must be in the work state (or its equivalent in your workflow).
You may want to revert to an older revision if you encountered an error or made changes in the
wrong file. Revision numbers are managed by the system to ensure they are the same for all
users.
To revert to an older revision:

1. Right-click the object and select History > Revision History... from the menu.
The Revision History dialog displays the list of all revisions, with the latest at the top.
2. Scroll to highlight the revision you want to revert to.
3. Click Revert to.
A new revision is created from the selected older version. If the version you reverted was
revision 5, the new version is now revision 6. The new object has the older version's content,
but its status will not be changed.
Compare documents
DITA CMS lets you compare documents with other documents, and with earlier versions of
themselves.
Inevitably, you will need at some point to see what the exact differences are between two
documents.You can compare topics and maps with their earlier versions or with other documents
of the same type.
You can also generate a report that tells you which topics and images are shared in common by
a given set of maps.
Compare is not, however, available for images or resources.
DITA CMS file comparison utilities

DITA CMS contains utilities that let you perform document comparisons.
You also have the option of configuring DITA CMS to use a compare tool that's installed on your
system.
If you are comparing topics, the two selected topics open as a read-only Compare file in the
Eclipse Compare tool with the differences between the two files indicated. See Eclipse
documentation for more information.
If you are comparing maps, the DITA Map Compare Editor shows the two maps with their
differences highlighted. A red highlight indicates that a topic is present in one map, but not in the
other. A green highlight means that the topic is present in both maps, but not in the same position.
No highlight means that the topics are present in both maps, and in the same position in the
hierarchy.
Note that the DITA Map Compare Editor uses the topic ID and revision number to determine if
two topics are identical. It does not look at the contents of the topics. Therefore, two topics with
the same ID and identical contents but with different revision numbers will be considered different.
Note: Using the DITA Map Compare Tool is not recommended if you are using the
Dynamic Release Management module. Please use the DRM synchronization feature
instead.
Related Links
Specify compare tool on page 612
Compare two revisions

Compare lets you view the differences between any two revisions of a given document. Compare
is not available for image files.
Use Compare to see where the differences are between any two versions of a document in the
repository. Compare can be useful when you want to confirm file content before reverting to an
older revision.
1. Right-click the file and select Revision History... from the menu.
The Revision History dialog displays the list of all file revisions, with the latest at the top.
2. Select the first revision, and hold down CTRL and click the second revision.
The Compare button becomes active in the Revision History dialog.
3. Click Compare.
The two files open beside each other in your compare tool with the differences indicated.
The two selected revisions open in your configured compare tool with the differences
between the two files indicated.
Compare with latest server revision

This procedure lets you view the differences between the current document on your workstation's
hard drive and the latest revision saved on the server. Compare is not available for image files.
The file must be locked.
To compare to latest server revision:

Right-click the file and select Compare With > Compare with Latest Server Revision
from the menu.
The two revisions open in your configured compare tool with the differences between the
two files indicated.
Compare selected documents

This procedure lets you view the differences between any two documents of the same type. You
cannot compare image files or snapshots.
Use this procedure when you want to compare two different documents of the same type. These
documents do not need to be in the same cycle. You can, for example, compare two different
documents in the same cycle; or you can compare versions of the same topic in different cycles.
The comparison must be made between documents in the same view.
1. Select the first document, hold down CTRL, and click the second document.
2. Right-click, then select Compare With > Compare with Each Other from the menu.
The two documents open beside each other in your configured compare tool with the
differences indicated.
Compare with authoring source

This procedure lets you view the differences between a branched document and the most current
version in the Authoring cycle.
Tip: You can search by branch tag in the Limit to panel of the Search facility.
To compare with authoring source:
• Right-click the document, then select Compare With > Compare With Authoring Source
from the menu.
Compare with published source

This procedure lets you view the differences between a branched document and the published
version from which it was branched.
Use this procedure when you want to compare a branched topic or map with the source version
in the Published cycle.
Tip: You can search by branch tag in the Limit to panel of the Search facility.
To compare with published source:
• Right-click the document, then select Compare With > Compare With Published Source
from the menu.
Export children intersection

This lets you determine which documents are shared by a given set of maps.
When you are producing a complex set of documents, you may find it desirable to share a certain
set of core topics among all the maps. Or you may have a set of icons that should be used by
all manuals of a certain type. This utility will tell you if this is actually being done.
1. Highlight the maps you want to compare.

You can select maps in any DITA CMS view, but all the maps must be in the same view:
Search Results view, for example.
2. Right-click and select Compare With > Export Children Intersection.
The Progress Information dialog tells you that the children lists are being built.
4. Click Save.
The report is saved as a TSV (Tab Separated Values) file that can be easily imported into
other programs, such as a spreadsheet application.
The image below shows a comparison between two maps. It:
• Lists the topics and images found in all of them.

• Indicates which map contains each document.
• Has an additional column that shows the documents shared by all selected maps.
Compare with previously published version (redlining)

Use this procedure to find the specific textual differences between the current version of a map
and earlier versions.
The Redline With function is similar to a word processor's compare function. It produces an
output by comparing a selected map to a published version and highlighting the additions and
deletions in different colors. This marking of the differences is referred to as redlining. The colors
are configurable by the DITA CMS administrator.
Changes to images in the topics may or may not be highlighted depending on the type of change
made. If an image element is deleted or the image ID is replaced in the topic, then the change
will appear in the redlined output. Editing the .image file itself such as adding a different format
or editing the graphic will not result in the image being highlighted in the redline output.
Note: Redlining the Table of Contents is not supported by default since it requires a hack
directly in the DITA-OT.
Note: This functionality is only available if your system uses the DITA Open Toolkit version
1.8.5 or later.
To compare with previously published version:
1. Right-click the map and select Compare With > Redline With.
2. Click the checkbox next to the published version to which you want to compare the
map.
A PDF copy of the map is generated with the differences highlighted.

9 Topics
Topics
Topics: Topics are the building blocks for document deliverables.

• Create a topic You can create, edit, and reuse topics to build your
• Open a topic deliverables.
• Open a topic with a
specified editor Referable-content topics
• Switch editors
• Preview a topic DITA CMS includes a specialization of the basic topic –
• Turn off thumbnail display referable-content – designed specifically for use with conrefs.
• Rename a topic This makes conref material easy to identify in the Search
• Edit a topic Results view by its file type: referable-content. You can also
• Add a topic to a map from search specifically for the referable-content file type using
the XML editor Advanced Search.
• Spell checking maps and
documents The referable-content topic type is available as a selection in
the Create Topic dialog.
Create a topic
Use this procedure to create a new unit of information using one of the structured topic templates.
New topics are typically created at the beginning of a project, during the Authoring cycle (or its
equivalent in your workflow) when the units of information take shape.
DITA CMS provides templates for all the standard DITA topic types, such as task and concept.
In addition, your system may contain custom templates designed for use in your particular working
environment. You'll see them in the Topic Template pane whenever you create a topic.
If your working environment has a large number of templates, these may be organized into folders,
which will appear in the Topic Template pane. You'll be able to navigate them to find the template
you need.
• Press CTRL+ALT+T.
• On the Document Creation toolbar, click the Create Topic button .

• From the menu bar, select DITA CMS > Create Topic.
The Create Topic dialog appears.

2. Enter a topic title in the Topic Title box.
3. Select a language from the Language list, if necessary.
4. Select a template from the Topic Template list.
When you click in the check box of a template that contains text, you'll see the text in the
Preview pane.
6. To edit the new topic immediately, select Open topic in default editor.
To edit an existing topic at any time, use Search and then open the topic from the Search
Results view.
7. To add the new topic to the map that's open in the DITA Map view, select Append topic
to current map.
This option is only available if the map is locked.
Topics 205
8. (Optional) To save the settings you have selected for Language, Template, Open topic,
and Append topic, click the diskette icon at the bottom of the dialog.
Your selections are saved and used as the default values in the Create Topic dialog. You'll
see them there the next time you create a topic.
9. Click Create to create the topic.
The new topic is added to the repository and given a unique file name. Use Search with
the Authoring check box selected to display the new file in the Search Results view.
Open a topic
Use Open to view a topic as read-only or to continue work on a topic you already locked. If a
topic is locked by another user, you can only open it as read-only.
Topics can be opened from any view in the DITA Perspective. If you open several topics in the
XML editor, you can switch from one topic to another by clicking the tab with the topic title.
Depending on your configuration, topics that are unlocked, or that are locked by another user,
may open in the Read-only Editor. This feature lets you look at a topic without the risk of
inadvertent modifications. The Read-only Editor shows the XML markup as well as the topic's
text.
Tip: Use the Preview view if you want to see how a topic in the Read-only Editor actually
displays (if, for example, it’s locked by someone else).
If you want to make any changes to a file that is not locked, use Edit to both open and lock the
topic at the same time.

To open a topic:
Right-click the topic and select Open or double-click it.

You can select several files by holding down CTRL or SHIFT and clicking the documents.
The topic (or topics) opens in your XML editor.

Open a topic with a specified editor

Use this procedure to edit a topic with an editor other than the default XML editor.
You can have several different files open in different editors at the same time in the editor area.
To switch from one topic to another, click the tab with the topic title; your file will appear in the
editor with which you opened it.
Use Open With when you have more than one editor associated with the .xml file extension.
To open a topic with a specified editor:
• Right-click the topic.

• Select Open With, then select the editor from the menu list.
The topic opens in the selected XML editor.
Switch editors
Use this procedure to change the editor that you're using on an open document.
• The document must be topmost in the editor area.
• The editor area must not be minimized.
Once a document is open in the editor area, you can switch to one of the other editors that are
configured for use with that type of document.
1. From the DITA CMS toolbar, click the Open With... button ( ).
The list of editors configured for the current document appears.
2. Select an editor.
The current document is displayed in the selected editor.
Preview a topic
Use this procedure to see a WYSIWYG version of a topic.
When you select Show Preview for a topic, the Conditionals panel appears if your topic contains
conditional text. It shows the conditional attributes defined by the DITA specification, with check
boxes for each attribute value used in the current topic.
Topics 207
Here is an example of what a topic that contains conditional text looks like in the Preview window.
Use the check boxes to hide or display the portions of your topic that are tagged with these
attributes.
If you only have one condition in a topic, you’ll always see the conditional text displayed, whether
or not the corresponding check box is selected. If you really want to see what your topic looks
like without that single condition, create an alternate dummy condition and then select its check
box.
Note: The Preview view does not resolve conrefs or keyrefs, so you will not see that
content in the Preview. For example, if the conref is a <note>, you will see the “Note”
prefix because that comes from the display stylesheet, but you will not see the contents
of the note.
To preview a topic:
1. Locate the topic you want to preview.

• Open the topic to preview in your XML editor.

• Right-click the topic and select Show Preview.
• Hover over the topic.
Note: This opens a thumbnail view of the topic, not the Preview pane. This
functionality is not available from all views.
3. If you make changes to the topic in the XML editor, click the Preview pane Refresh
button ( ) or repeat one of the previous options to see your changes.
4. (Optional) If desired, click the Print button ( ) to print the contents of the Preview.
Related Links
About conditional attributes on page 338
Turn off thumbnail display

You can turn off thumbnail display in a specific view.
You have the option of having thumbnail previews appear whenever you hover the cursor over
a topic or image title in a view such as Search Results or your Todo list. By default, thumbnail
display is enabled.
To disable topic thumbnails:
• In the required view, click the Turn off thumbnail display button ( ).
Rename a topic
The Rename procedure changes the title of a topic.
The file must not be locked by another user.
The names that identify topics when they appear in the DITA Map view or in the Search Results
view are determined by their <title> element. You can rename a topic by editing its title.
1. Right-click the topic and select Edit from the menu.

The file is locked and opens in your default XML editor.
2. Edit the <title> element as required.
For example, you could change the following line:

<title>Preface</title>
to
<title>Introduction</title>
3. Save your work and release the file.

4. (Optional) Refresh the view to see the update.
Topics 209
Edit a topic
The Edit procedure locks and opens a topic at the same time.
The document must not be locked by another user.
Use Edit to save yourself a step when you want to work on a topic that is not locked.
Topics can be opened for editing from almost any view in the DITA Perspective, as long as they
are in a state that allows editing. You cannot, for example, edit a topic that is in the review state
(or its equivalent in your workflow).
You can have more than one topic open in the XML editor at a time. You can switch from one
topic to another by clicking the tab with the topic title.
To edit a topic:
• Right-click the topic and select Edit from the menu.

You can select several documents by holding down CTRL or SHIFT and clicking the
documents.
The document is locked and opens in your default XML editor.
Add a topic to a map from the XML editor

You can now add a topic to the map displayed in the DITA Map view when you're working in the
XML editor.
To add a topic to the current map from the XML editor:
1. In the XML editor, select the topic to add to the current map.
The tab for that topic is highlighted.
2. In the DITA Map view, select where to add the topic.
3. From the DITA CMS toolbar, click the Append to Map button ( ).
The topic will be added to the map in the DITA Map view. If a topic was highlighted in the
map, the new topic will be added after the highlighted object. Otherwise, the topic will be
added at the end of the map.
Spell checking maps and documents

You can spell check selected topics and maps without opening them by simply right-clicking the
topic or map and selecting Spellcheck.
The results of the spell check are displayed in the Spellchecker view, shown in the following
diagram:
The Spellchecker view provides the following information:
• Number of errors found in the spellchecked documents

• For each spelling error, the following information is provided:
• Misspelled word
• Number of occurrences of the misspelled word
• Document in which the misspelled word was found
Words are listed once per document, even if the document contains multiple occurrences of
the misspelled word. Words that are misspelled in multiple documents are listed once per
document.
Case sensitivity
The Spellchecker is case sensitive; for example, Unix and unix are considered two different words
when spell checking.
Note: The Replace feature is case insensitive; for example, if you select unix and replace
it with Unix, it will replace all occurrences of the word unix, no matter its casing (e.g.,
Unix, unix, UNIX will be replaced with Unix).
Topics 211
Language
The Spellchecker works with any language configured for your deployment.
To determine the dictionary used to spell check a document, the Spellchecker uses the value of
the xml:language attribute in the root element of the map or topic. For example, consider the
following topic:

<!DOCTYPE concept PUBLIC "-//IXIA//DTD IXIA DITA Composite//EN" "IxiaDitabase.dtd">
<concept id="lar1397660192605" xml:lang="en-us">
<title ixia_locid="1">Troubleshooting the Tomcat installation</title>
...
The en-us dictionary will be used to spell check that document, and custom words will be added
to the en-us custom dictionary.
Skipped elements
By default, the spell checker skips the contents specified in the <codeblock> and <codeph>
elements. This is configurable per deployment, so check with your CMS Administrator for the list
of skipped elements.
Check the spelling of topics and maps

This procedure describes how to spell check topics and maps.
From the Spellchecker view you can:
• Open the document that contains the misspelled word and fix the error
• Add a word to a global custom dictionary
• Choose from a list of suggestions and fix all occurrences of the misspelled word in the selected
document
To check the spelling of a topic or map:
1. Right-click the topic(s) or map you want to check and select Spellcheck.
If you select a map, all of its child topics are checked as well.
The Spellchecker view is displayed, listing misspelled words, if any.

2. To fix a spelling mistake:
a) If the containing document is unlocked, right-click the document in the Spellchecker
view and select Lock.
The containing document is locked.
b) Double-click the misspelled word.

The containing document opens in the XML editor.
c) Fix the spelling in the document.
3. To replace all occurrences of a misspelled word in the selected document with a
suggestion:
a) If the containing document is unlocked, right-click the document in the Spellchecker
view and select Lock.
b) Select the misspelled word in the Spellchecker view.
c) In the Suggestions area, select the correct word.
d) Click Change All.
A message similar to the following is displayed:
To replace all occurrences of the word in the document, click OK.

Note: You will not be able to undo these changes using the Undo feature of your
XML editor. If you clicked OK but need to revert your changes, you can use the
DITA CMS Replace with Server Revision feature.
4. To add a word to the custom dictionary:

a) Select the word to add in the Spellchecker view.
b) Click Add to Dictionary.
c) Click OK to confirm.
The word is added to the custom dictionary, which is shared by all users in your
deployment.
Note: If you get a message similar to the following:
Topics 213
Then a custom dictionary does not exist for your deployment. Ask your CMS Administrator
to create the custom dictionary by adding a word to it.
10 Creating links
Creating links
Topics: You can provide links to reference other topics in a variety of

• Relationship tables ways.
• Creating cross-references The most recommend method to create links between topics
(xref)
is to build relationship tables. Relationship tables allow you
to provide a collection of links between topics without
compromising the reusability of the topics.
Other linking methods include cross-references and related

links.
Relationship tables
These procedures tell you how to use reltables in DITA CMS.
Reltables let you create dynamic linking between topics, without compromising reusability.
Open the Reltable Editing Perspective from the DITA Map view's
menu
This procedure opens the Reltable Editing Perspective from the DITA Map view's pull-down
menu.

2. Select Open Reltable Editing Perspective.
The Reltable Editing Perspective opens in the Eclipse Workbench.
Open the Reltable Editing Perspective from the main menu bar
This procedure tells you how to open the Relationship Table Editing Perspective.
• Click Window > Open Perspective > RelTable Editing from the menu bar.
The Reltable Editing Perspective

DITA CMS offers a view designed expressly for working with DITA relationship tables.
The Reltable Editing Perspective contains several views that you'll already be familiar with from
the DITA Perspective and from the Eclipse environment: the DITA Map and Properties views. It
adds to these the Relationship Outline view and Relationship Table Editor view.
Relationship Outline view
This view provides a quick way of locating all the reltable rows that contain a selected topic or
topics.
When you highlight a topic in the DITA Map view, all the rows and tables where the topic is used
will be listed in the Relationship Outline view.
Creating links 217
If you highlight more than one topic, then the Relationship Outline view will first display the rows
where both topics appear together, followed by lists of the rows containing each topic by itself.
Relationship Table Editor
This view lets you quickly visualize the tables and constituent rows, as well as the cells and their
contents.
• The Table Display area shows the tables in your map as collapsible nodes with their rows
displayed beneath. You can right-click in this area to add and remove tables, rows, and cells.
• The Filter field provides a way of locating rows in the Table Display area. Enter any string,
and the Table Display area will show the rows whose names contain these characters.
• The Row Display area shows the contents of the row that's highlighted in the Table Display
area. The row name appears at the top. Each cell and its topics are displayed beneath. You
can right-click in this area to add and remove topic groups.
Related Links
Locate reltable rows where a topic is used on page 229
Filter reltable rows in the Table Display area on page 232
Construct relationship tables

These procedures deal with the basics of setting up reltables.
Add a reltable to a map

This procedure creates a new relationship table in a map.
DITA CMS lets you insert a pre-formatted table of type CRT into a map. The CRT table has a
single row, which contains three relcells. Each of these relcells has its type attribute set to
concept, reference, or task, respectively.
Note: The exact configuration of available pre-formatted tables may vary with your
installation – like the rest of DITA CMS, all the details are configurable. New templates
can also be created for your environment. See the DITA CMS Administrator's Guide for
more information.
You can retype these cells as you wish or add cells and rows of other types, as you find convenient.
You can have as many reltables as you want in a single map.
1. Open the Reltable Editing Perspective.

2. Right-click in the Table Display area of the Reltable Editing view, then select New
Reltable > CRT Table.xml.
Note: Other options may be available according to your configuration.
Creating links 219
A dialog box appears, asking you to enter a name for the table.
3. Enter a name and click OK.
A new table of the selected type is added to the map.
Add a pre-configured row to a reltable

Use this procedure to add a pre-configured row to a reltable in your DITA map.
DITA CMS lets you insert a pre-configured row of type CRT Row.xml into your reltables.This
type of row contains three cells, whose type attributes are set to concept, reference, or task,
respectively.
Note: The exact configuration of available pre-formatted rows may vary with your
more information.
The number of cells per row and their type are configurable and may vary with your setup.

2. In the Table display area of the Reltable Editing view, highlight the table where you
want to add the row.
3. Right-click, then select Insert Row > CRT Row.xml.
A dialog box appears, asking you to enter a name for the row.
A new row of the selected variety is added to the reltable.

Related Links
Reltable example one: CRT row structure on page 233
Reltable example one: CRT row output on page 236
Reltable example two: links are between cells – not within cells on page 237
Add an unconfigured row to a reltable

You can add a row that has none of its attributes set to a reltable in your DITA map.
Creating links 221
There may be times when you want to work outside the restrictions of a pre-configured row. DITA
CMS lets you add row elements directly to a reltable, so that you can configure them the way
that best suits you.

2. In the Table Display area of the Reltable Editing view, highlight the table where you
3. Right-click, then select Insert Element > relrow.
A new untyped row is added to the reltable.
Note: After you've inserted the new row, it's a good idea to assign it a name. This allows
you to search for the row in the Table Display area.
Add a typed cell to a reltable row

You can add a pre-configured (typed) cell to a reltable row in your DITA map.
1. In the Table Display area, highlight the row where you want to add the cell.
2. Right-click, then select Insert Cell > celltype.
where celltype is one of the following:
• concept.xml
• reference.xml
• task.xml
The choices available depend on your configuration.
A new cell of the selected type is added to the reltable row and appears in the Row Display
area.
Add an unconfigured cell to a reltable row

You can add a cell that has none of its attributes set to a reltable row.
DITA CMS lets you add relcell elements directly to a reltable row, so that you can configure them
the way that best suits you.
2. Right-click, then select Insert Element > relcell.
A new unconfigured cell is added to the reltable row and appears in the Row Display area.
Assign a name to a reltable

This procedure describes how to assign a meaningful name to a reltable.
When you crate a reltable, you specify its name, but you can change that name at any time after
the table is created.
1. In the Table Display area of the Reltable Editing view, highlight the table you want to
name.
2. In the Properties view, click in the entry field for the title attribute.
3. Type in the name you want to assign to the table.
The table name appears in the Table Display area.
Assign a name to a reltable row

This procedure describes how to assign a meaningful name to a reltable row.
When a reltable is created it will have a row named something like "Row 1". Use this procedure
to assign it a descriptive name.
1. In the Table Display area of the Reltable Editing view, expand the table that contains
the row you want to name.
2. Highlight the row.
3. In the Properties view, click in the entry field for the xtrc attribute.
4. Type in the name you want to assign to the row.
The new row name appears in the Table Display area and in the Row Display area.
Add a topic to a reltable cell

You add topics to reltables one at a time using a drag-and-drop technique. You can also drag a
topic from one cell to another.
You can add topics from the DITA Map and Search Results views.The map must be locked.
1. In the Table Display area of the Reltable Editing view, highlight the row where you want
to add the topic.
Creating links 223
The selected row's contents appear in the Row Display area.

2. Drag the topic from the DITA Map or Search Results view into one of the cells in the
row.
The topic appears in the cell at the place you dropped it.
Add a topic and its children to a reltable

You can add a topic and all its children to a reltable in a single operation.
To add a topic and all its children:
to add the topic and its children.
2. Hold down the Alt key and drag the topic from the DITA Map or Search Results view
into one of the cells in the row.
The topic and all its children appear in the cell at the place you dropped it.
Insert a topic group into a reltable cell

Use this procedure to create and configure topic groups.
Topic groups let you create relationships among the topics within a reltable cell. The specifics of
the output they produce will depend on the XSL that is applied to them.
to add the topic.
2. Right-click the reltable cell where you want to insert the group, then select one of the
following values:
• Insert group: choice

• Insert group: family
• Insert group: unordered
Note: The choices available depend on your configuration.

You can insert these groups into any type of cell. The screen shot below shows a sequence
group inside a concept type of cell.
3. Drag and drop topics into the group.

You can drag topics from the DITA Map view, from other cells in the row, or from within the
cell where you've inserted the group.
Related Links
Reltable example three: linking topics of the same type on page 239
Reltable example five: creating sequences on page 242
Remove a row from a reltable

You can remove a row along with all its constituent cells and topics from a reltable in your DITA
map.
1. In the Table Display area, highlight the row you want to remove.
2. Right-click, then select Remove from RelTable.
The row is removed from the reltable.
Remove a cell from a reltable row

You can remove a cell along with all the topics it contains from a reltable in your DITA map.
1. In the Table Display area, highlight the row that contains the cell you want to remove.
2. Right-click the <relcell> line at the top of the cell, then select Remove from RelRow.
The cell and all its topics are removed from the reltable row.
Creating links 225
Configure relationship tables

This section deals with operations such as changing the cell types and configuring link directions.
Change the type of a reltable cell

Use this procedure to reassign or remove the limiting type of a reltable cell in a CRT cell; or to
set the type of an untyped cell.
If you have created a pre-configured CRT row you may at some point want to change a cell's
type so that it accepts other types of topics. Or you may want to remove the type attribute
altogether so that the cell accepts all types of topics.
Or, if you have created an untyped row, you may want to limit it to a specific type of topic.
1. In the Table Display area, highlight the row that contains the cell you want to re-type.
2. Highlight the cell.
3. In the Properties view, click in the entry field for the type attribute.
4. Enter the type you want to assign to the cell.
If you're removing the type, simply clear the contents of the field.
5. Click the Refresh button in the DITA Map view.
The cell type is reassigned and the new type appears in the Table Display area and in the
Row Display area.
Change the collection-type of a reltable cell

Use this procedure to reassign or remove the collection-type of a reltable cell; or to set the
type of an untyped cell.
If you have created a preconfigured row you may at some point want to change the cell's
collection-type to another valid value: "choice", for example. Or you may want to remove
the collection-type attribute altogether.
Or, if you have created an untyped row, you may want to restrict its display characteristics using
this attribute. Display characteristics, of course, will vary according to your XSL.
1. In the Table Display area, highlight the row that contains the cell whose type you want
to change.
3. In the Properties view, click in the entry field for the collection-type attribute.
4. Enter the value you want to assign to the cell.
As of DITA 1.1, the valid values are:
• unordered
• sequence
• choice
• family
The cell collection-type is reassigned and the new type appears in the Table Display
area and in the Row Display area.
Change the collection-type of a topic group

Use this procedure to reassign or remove the collection-type of a topic group within a
reltable cell.
You may at some point want to change a topic goup's collection-type from one type – such
as "family" – to another valid value: "choice", for example. Or you may want to remove the
collection-type attribute altogether.
1. In the Table Display area, highlight the row that contains the group whose type you
want to change.
2. Highlight the group.
Creating links 227
• unordered
• sequence
• choice
• family
The group's collection-type is reassigned and the new type appears in the Row Display
area.
Related Links
Set linking direction

This procedure describes how to specify whether links are visible in source or target topics.
You have the option of setting up directional links between topics so that one topic can refer to
another, without having a link back in return (or vice versa).
You can set the linking properties of entire cells, of individual topics within cells, or for topic groups
within cells.
To set the linking direction:

1. In the Row Display area of the Reltable Editing view, highlight the cell, topic, or topic
group.
2. You can set the linking direction in two ways:
• Right-click the cell, topic, or topic group and select Linking > <direction>, where
<direction> is one of the following:
• targetonly: The topic can only be linked to; it cannot make links to other topics.
• sourceonly: The topic can link to other topics; other topics cannot link to it.
• normal: The topic can link in both directions. This is the default value, and does not
have to be entered.
• none: A topic cannot link or be linked to.
• -dita-use-conref-target: In case of conrefs, indicates that the linking value
should be pulled in from the target.
See the DITA specification for more information.
• In the Properties view set the linking attribute to the required value.
The linking property of the object is set, and the appropriate link direction icons appear
next to the selected object.
Related Links
About linking direction in relationship tables on page 228
Reltable example four: linking direction on page 241
About linking direction in relationship tables

You can specify whether topic links are mutual or unidirectional.
When you drag topics into adjacent cells of a row, by default you'll establish a two-way link: the
topics link to each other. If you're using the output in a set of Related links, for example, you'll
see each topic in the other's list.
another, without having a link back in return (or vice versa). For example, you might want numerous
small related procedures to have access to a conceptual topic; but you might not want all of the
many little topics showing up as links inside the concept.
You can set the linking direction on topics, groups of topics, or on entire cells. Icons next to the
objects indicate the linking direction.
Creating links 229
The following linking values are available:
• targetonly - the topic can only be linked to; it cannot make links to other topics. Indicated
by the following icon:
• sourceonly - the topic can link to other topics; but other topics cannot link to it. Indicated by
the following icon:
• none - a topic cannot link or be linked to. Indicated by the following icon:
• normal - the topic can link in both directions. This is the default value and does not have to
be entered. You can, however, use this value to override the attribute of a parent structure: if,
for example, you want just one topic within a topic group to link in both directions. Indicated
In the screenshot below, both of the cells have the default linking: normal (bidirectional). So does
the topic group in the task cell, as a whole. However, one of the topics in the group – Vote on a
document – is designated as "sourceonly". None of the other members of the group or the concept
cell will be linked to it; but it will link to all the others.
The topic in the concept cell, on the other hand, has been designated "targetonly". All the other
cells in the row will link to it, but it will not be linked back to them.
Note: Your system must use UTF-16 character encoding with the East Asian language
pack installed, or the linking arrows will not display properly.
Related Links
Set linking direction on page 227
Locate reltable rows where a topic is used

You can use the Relationship Outline view to locate the rows where one or more topics appear.
When you highlight a topic in the DITA Map view, the Relationship Outline view displays the
table(s) and row(s) where that topic is used.
where both topics appear together, followed by lists of the rows where each topic appears on its
own.
Note: This information is retrieved from the repository. If you've recently put a topic into
a reltable, you'll need to release the map before you can view the rows where it's being
used.
To locate reltable rows where a topic is used:
• In the DITA Map view, highlight the topic or topics you want to locate.
The Relationship Outline view displays the table(s) and row(s) where the topic(s) is used.
In the following example, you can see in the Relationship Outline view that the topic
"Assign documents to users" appears in the row "Document assignments" in a
reltable called "Projects".
In the next example, you can see that the topic "Set document due dates" appears
in two rows in the reltable called "Projects"; it also appears in one row of the reltable
"Tutorials".
Creating links 231
In the next example, two topics are selected in the DITA Map view. The Relationship
Outline view shows that the selected topics both appear in the "Document
assignments" row of the reltable called "Projects". It then list the rows and tables
where each topic appears on its own.
Related Links
The Reltable Editing Perspective on page 216
Filter reltable rows in the Table Display area

You can use the Filter field of the Table Display area to locate specific rows in the reltables in
your map.
As you enter characters in the Filter field, the Table Display area shows the row names that
contain those characters.
To filter reltable rows in the Table Display area:
• In the Filter field of the Relationship Table Editor, type in characters contained in the
names of the rows you want to locate.
The Table Display area shows rows where the string is used.
Note: The filter function examines all text in the reltable, including the tags. So if you
type in the string "ro", you'll see all the rows in the reltable, since they all begin with
the tag <relrow>.
The screenshot below show the results of entering "as" into the Filter field. The two
rows containing that string are displayed: "Document assignments" and "Assign
values".
The following screenshot shows the rows displayed when the string "va" is entered.
Creating links 233
Related Links
Relationship table examples

This section contains some concrete examples of how to use relationship tables.
Reltable example one: CRT row structure

Once you’ve inserted a reltable into a map, you’ll start adding rows. DITA CMS offers several
types of pre-configured rows.
This example shows the structure of a CRT row, that is a row with three cells, each supporting
a specific type of topic: Concept, Reference, and Task.
The screen capture below shows the Reltable Editing Perspective. The DITA map view has been
expanded, and three topics are highlighted. These are the ones that are being used in the reltable.
The Relationship Table editor is also open, with the “oil change” row highlighted. You can see
that each of the highlighted topics is in the row appropriate to its topic type:
• Concept – When Should I Change my Oil?

• Task – Changing your Oil
• Reference – Oil Grades and Weights
The example uses the default linking – normal – as indicated by the decoration ( ). Normal
linking means that the links will be reciprocal: the task will refer to the concept and the concept
will refer to the task. And likewise for the task and reference topics. Each topic is linked to both
of the others.
You can see the output this produces in Example One: CRT row output.
Creating links 235
Related Links
Add a pre-configured row to a reltable on page 219
Reltable example one: CRT row output

This topic shows the Changing your Oil topic as it would appear in HTML Help.
The image below shows one set of links produced by the reltable in Example One: CRT row
structure. The links to the other two topics in the adjacent reltable cells appear in the Related
Concept and Related Reference sections at the bottom of the page.
If you followed either of these two links, you’d see that these topics are each linked back to the
topic shown below.
Related Links
Creating links 237
Reltable example two: links are between cells – not within cells
When you add topics to a relationship table cell, those topics link to the topics in the other cells
– not to each other.
For example, I could add another topic to the Concept cell in the reltable shown in Example One:
CRT row structure.
Example two output
If we look at the output for the task topic (Figure "Task Topic Output"), we can see that the new
concept topic has been added as a link.
But if we look at either of the concept topics, we’ll see that there is no link between them (Figure
"Concept Topic Output"). The links are between topics in adjacent cells.
Figure 49: Task Topic Output

Creating links 239
Figure 50: Concept Topic Output
Related Links
Reltable example three: linking topics of the same type

If you want links between two topics of the same type – two concepts, for example – you can put
them into a family type of topic group.
The image below (Figure "Relcell Contents") shows a cell where three topics have been added
to a family type of topic group.
In the Eclipse help output each topic shows up in the others’ Related Links as a Related Task
(Figure "Relcell Output").
Figure 51: Relcell Contents
Figure 52: Relcell Output
Related Links
Insert a topic group into a reltable cell on page 223
Creating links 241
Reltable example four: linking direction

You can override the default linking direction.
By default, links are reciprocal. Topics in adjacent reltable cells refer back and forth to each other
(as we showed in examples One and Two). Sometimes, however, you’ll want to limit this reciprocity
to avoid overwhelming the reader with irrelevant links.
In the example below (Figure: "Reltable Contents"), we can see how several localization tasks
– shown in the left-hand cell – are all given a related link to a single task (which deals with setting
up a place on your hard drive where files will automatically be saved).
In order to suppress related links pointing back from the Configuration topic to all the tasks in the
left-hand cell, we’ve set the linking direction on that topic to “targetonly” ( ).
You can look at the related links produced by this reltable row by visiting any of the topic links
below.
• Configure import and export directories (note that this topic has no links to any of the topics
in the left-hand cell)
• Import a localized map and its topics
• Import localized images
• Prepare an image localization kit
• Prepare the localization kit
It’s worth noting that the topics in the left hand cell will not be linked with each other. Links are
always between adjacent cells.
Figure 53: Reltable Contents
Related Links
Reltable example five: creating sequences

You can use a reltable to dynamically create a set of numbered steps from the required topic
titles.
Sometimes you’ll be faced with documenting a large task that is actually made up of other smaller
tasks, taken from various places within a large manual. You can do this using a reltable.
In this example we’ll create the contents of the topic “Motoring Vacation Checklist” from the topics
indicated in the picture (below).
Creating links 243
The reltable cell
First we structure the reltable cell. This is done by:
1. Dragging the container topic (Motoring Vacation Checklist ) into a task-typed cell, and then
2. Dragging the component tasks in as children of that topic
The collection-type properties
Then we’ll set the collection-type of the container topic to sequence, using the Properties view.
Example five output
The finished Motoring vacation checklist would appear in Eclipse Help as shown below. The topic
titles become the numbered steps. The <shortdesc> elements furnish the text below the steps.
Creating links 245
Related Links
Change the collection-type of a topic group on page 226
Creating cross-references (xref)

You can insert link inside topics, between topics, and to documents outside the Content Store.
Create a cross-reference to another topic

You can insert a link to directly reference another element.
The <xref> element lets you make a cross-reference from one topic to another.
DITA Best Practices recommend using cross-references sparingly since they break the principle
of creating "standalone topics". Cross-references, which are directly inserted into a topic, can
cause issues when attempting to reuse the topic in another map. Consider using a relationship
table to manage the links between the topics or organizing your table of contents to imply the
relationship between the topics.
To create a cross-reference:
1. Open and lock the topic in your XML editor.

2. Place the cursor where you want to insert the cross-reference.
Note: You must be within an element that allows an <xref> element.
3. Locate the topic you want to reference.
You can select a topic displayed in any of the DITA CMS views. For example, you can select
the topic from the Search Results view, DITA Map view, or from your favorites.
4. Right-click the reference topic and then click Oxygen Editor > Insert as Xref
The cross-reference is inserted where the cursor was placed.
Create a cross-reference to an external file or web site

You can insert links to web pages, remote locations, FTP sites, or files outside the repository.
You can use absolute or relative paths to cross-reference documents outside the repository;
however, make sure that the path will work when the link is clicked from its published location.
For example, if you are inserting a cross-reference to a file, the file must be in a location that can
be accesses when someone clicks the link in your published output.
To create an external link:
1. Open the topic in your XML editor.

2. In Author mode, right-click where you want to insert the link and click one of the
following:
• To insert a link to a web page, click Link > Web Link, and then type the URL or key.
• To insert a link to a file, click Link > File Reference, and then type the path to the file's
location or the key.
Use the following syntax for the URL depending of the type of external document:
Location Syntax
Web site http://sitename
Secure web site https://sitename
FTP site ftp://sitename
Secure FTP site ftps://sitename
Local file file://driveletter/filename

Creating links 247
3. Click OK.
Related Links
Copy document reference on page 253
Troubleshooting unresolved cross-references

Unresolved cross-references occur when DITA CMS cannot locate a file that is being referenced.
DITA CMS offers tools to help you troubleshoot them.
DITA CMS verifies cross-reference dependencies in the following circumstances:
• When a user attempts to change a map's status: DITA CMS checks all the map's child
topics to ensure that the document objects referenced are located within the map.
• When a user attempts to delete a document object: DITA CMS checks to ensure that the
document object is not referenced within any active topic.
If DITA CMS finds an unresolved cross-reference, the attempted status change or deletion is
cancelled, and the user is presented with a Cannot delete or a Cannot change status window.
Follow the procedure below to resolve the cross-references.
Figure 54: Cannot delete window
To troubleshoot unresolved cross-references:
1. In the Cannot delete or Cannot change status window, select an unresolved

cross-reference.
2. Click Locate.
3. Click OK.
The information for the selected cross-reference is displayed in the Search Results view.
4. Expand the Locator node to display the maps or topics that reference the document
object.
Figure 55: Parent maps for a to-be-deleted topic
In the example above, the topic is referenced in two maps.

5. To resolve the problem, check the parent maps. Do one of the following:
• If the cross-referenced topic is being deleted because it is inaccurate, remove the topic
from these maps and if applicable replace it with an updated topic. Release the affected
maps to update them, and re-attempt the status update or deletion.
• If the cross-referenced topic is still relevant for these maps, do nothing--the delete operation
would have been an error and has been avoided.
11 Referencing other files
Referencing other files
Topics: DITA CMS offers utilities that let you easily make links
• Inserting images between documents. It also gives you the tools to keep track
• Create related links from of these links.
one topic to another
This set of topics describes the various linking methods that
• Create related links to
the DITA specification offers, including:
external files or web sites
• Copy document reference • How to make the various links between topics:
• Copy ID cross-references (inline links), related links, and
• Copy full path referable-content links (conrefs).
• Copy the element ID • How to make these links between files in the Content Store,
or files out on your hard drive or even with remote URLs.
• How to use links to put graphics into a text document.
• The utilities that you can use to make these links in a text
editor, as well as the other tasks these utilities facilitate.
• How to use the Dependencies view to visualize the
relationships between the various documents – the topics
and images that one topic refers to, for example, and the
maps that reference that topic in return.
Related Links
Referencing other files in the oXygen editor on page 294
Inserting images
These procedures describe how to insert images in a topic.
Insert an image into a topic

This procedure inserts a reference to an image into a topic in a text-based editor.
Note: This procedure does not add an image to the Content Store. It inserts a reference
to an image that already exists in the Content Store.
1. Open and lock the topic into which you want to insert an image.
2. Place the cursor where you want to insert the image.
3. Search for the image you want to use.
For example, you can perform a search to display it in the Search Results view.
4. Right-click the image, then select Oxygen Editor > Insert Image from the menu.
Related Links
Create an image on page 278
Insert an image from a remote location into a topic

This procedure uses a text editor to insert images from remote locations, FTP sites or local files
outside the repository.
When you are inserting images from outside the repository, you may use either absolute or
relative pathnames. However, you should keep in mind that setups vary in different machines.
When you specify the path for your image, you’d better be sure that the path makes sense with
regard to the machine (and the local network) where the files will be installed.
Note: When you use this procedure, the images will not be part of your output. The
output will be created with links to the images. When you load your output onto the web
server, the content will link to external images in the location you specified.

3. Insert an <image> tag.
4. Add an href attribute to the opening portion of the image tag.
Referencing other files 251
Your tag should look like this: <image href=""></image>

5. Type the location you want to reference between the quotation marks of the href
attribute.
The following table shows the location types accepted by the href attribute and their syntax.
Location type Syntax
Your tag should look something like this:

<image href="file://C:\Documents and Settings\MalerM\My Documents\Document life
cycle.jpg"></image>
Tip: Add a comment showing the image title just above the <image> tag, if the target
name isn't totally intuitive.
Related Links
Create related links from one topic to another

This procedure uses a text editor to put a group of links to related topics into the current topic.
Referenced topics must be in the Authoring or Published cycle (or its equivalent in your
workflow).
1. Open the topic in your text editor.

2. Place the cursor where you want to insert the related links.
3. Insert a <related-links> tag with a <link> tag inside it.
4. Add an href attribute to the <link> tag.
Your <link> tag should look like this: <link href="">
5. Use Search to find the topic you want to reference in the Search Results view.
6. Right-click the topic, then select Copy > Reference from the menu.
7. Paste the reference between the quotation marks of the href attribute.
Your completed code should now look something like this:
<related-links>
<link href="dit1142280181031.xml"/>
</related-links>
Tip: Add a comment showing the topic title just above the <link> tag so that you
remember what the topic is actually about.
8. (Optional) Insert additional link tags as needed.
Related Links
Create related links to external files or web sites

This procedure uses a text editor to put a series of links to related topics on remote systems or
to files outside the repository.
You can make related links to websites and FTP locations, as well as to files outside the repository.
When you are linking to files you may use either absolute or relative pathnames. However, you
should keep in mind that setups vary in different machines.You can safely use relative pathnames
if you are sure that multiple documents will always be sent as a single package. However, if
there’s a chance that only a portion of the files will be sent, and that the target file isn’t among
them, then the link may become invalid.

2. Place the cursor where you want to insert the related links.
3. Insert a <related-links> tag with a <link> tag inside it.
4. Add href and scope attributes to the link tag.
Your link tag should look like this: <link href="" scope=""/>
5. Type the location you want to reference between the quotation marks of the href
attribute; then type the word "external" between the quotation marks of the scope
attribute.
The following table shows the location types accepted by the href attribute and their syntax.
Your completed code should look something like this:
<related-links>
<link href="http://www.google.ca" scope="external"/>
</related-links>
Tip: Add a comment explaining the link just above the <link> tag, if the target name
isn't totally intuitive.
6. (Optional) Insert additional link tags as needed.
Related Links
Copy document reference

This procedure lets you quickly copy a document's file name.
Use Copy Reference to copy a document's file name to the clipboard. You can use this file name
for making xrefs and conrefs and for inserting images in a text editor.
To copy document reference:
• Right-click the document and select Copy > Copy Reference from the menu.
The document's file name is copied to the clipboard.
The following is an example of an image's file name:

jan1236299873904.image
Related Links
Creating cross-references (xref) on page 245
Copy ID
This procedure lets you copy a document's root ID.
Use Copy ID to copy a document's root ID to the clipboard. You can use this ID for searches.
In most cases the root ID is the file name without its file extension.
For example, a concept topic that has the following file name:
dit1143219004906.xml
would have the following root ID:

dit1143219004906
You can see this ID in the first few lines of the XML, if you open the topic in a text editor,
e.g., <concept id="dit1143219004906">.
To copy a document's root ID:
• Right-click the file and select Copy > Copy ID from the menu.
The document's root ID is copied to the clipboard.
Copy full path

This procedure lets you copy a document's file name and absolute path within the TEXTML
repository.
Use Copy Full Path to copy a document's file name to the clipboard, together with its full path
with respect to the repository root. You may find this useful in an environment with automated
builds or with a backup utility.
To copy full path:
• Right-click the file and select Copy > Copy Full Path from the menu.
The document's full path is copied to the clipboard.

The following is an example of an image document's full path:

/content/authoring/per1236698006846.image
Copy the element ID

The Copy Element ID feature allows you to copy the ID of an element from a topic in the
Referable-Content view.
The Referable-Content view displays the results of searches for reusable components saved
as referable-content topics. When you use Copy Element ID, it copies the first instance of an
element ID in the referable-content topic (whose value is displayed in the Element ID column)
to the clipboard.
To copy the element ID:
1. Perform a search in the Referable-Content view.

2. Right-click the referable-content topic from which you want to copy the ID.
3. Click Copy > Copy Element ID.
12 Viewing where documents are
used
Viewing where documents are used
Topics: The Dependencies view displays the relationships that a

• About the Dependencies specific document has with other DITA documents in your
view system.
• View a document's
When you have the Dependencies view open in the
dependencies
workspace it will, by default, be updated to display the
• Enable update of the
Dependencies view relationships of each document that you open. You have the
• Filter the Dependencies option of disabling this automatic update, if you wish.
view
• Export Dependencies as
TSV
About the Dependencies view

The Dependencies view displays the relationships that a specific document has with other DITA
documents in your system.
When you have the Dependencies view open in the workspace it will, by default, be updated to
display the relationships of each document that you open. You have the option of disabling this
automatic update, if you wish.
In the screen shot below, you can see a topic—"Locate a map, topic or resource"—on one side
of the DITA workspace. On the other side, you can see its relationships displayed in the
Dependencies view. You can see that it:
• has 3 Parent Dependencies of three maps.

• has one Child Dependency, which is an image.
You can also see that it is cross-referenced by one file—including related links and xrefs—and
that no topics cross-reference it.
We've used the filter option to screen out the dependencies that weren't of interest. In a busy
documentation facility, topics can acquire dozens of references. Filtering lets you concentrate
on the references that are currently important.
Drilling down into the Dependencies view
If you double-click one of the related documents in the Dependencies view, then that document
will become the focus. For example, if you clicked any of the maps shown below, you'd see all
the topics that it referenced, and any maps, in turn, that it was part of.
Similarly, if you double-clicked the "New in this documentation release" topic, you'd be able to
see all its dependencies.
Viewing where documents are used 259
Related Links
Enable update of the Dependencies view on page 260
View a document's dependencies on page 259
Filter the Dependencies view on page 260
Export Dependencies as TSV on page 261
View a document's dependencies

This procedure lets you quickly visualize the relationships between documents.
You can view the dependencies of any type of document. You can also double-click any of the
other documents displayed in the view to see its dependencies in turn.
By default, the Dependencies view will be updated whenever you open a document. You can
disable this behavior by pinning a specific document in the view.
To view a document's dependencies:
• Right-click from a list.

a) Select one or more documents from any view.

b) Right-click the selection and select View Dependencies.
Hold down CTRL or SHIFT and click the documents to select more than one document.
• Drag documents into the Dependencies view.

a) Open the Dependencies view.
b) Select one or more documents from any other view.
c) Drag the selected documents into the Dependencies view, making sure to drop it
under the Dependencies tree currently displayed.
• Double-click any document in the Dependencies view.
The selected documents' dependencies are displayed in the Dependencies view.

Tip: If you're using the Oxygen editor and you want to view the dependencies of a topic
that's currently open in your editor, you can do one of the following:
• In Text mode, right-click anywhere in the topic, then select View Dependencies
• Click the View Dependencies button in the toolbar
Related Links
About the Dependencies view on page 258
Enable update of the Dependencies view

By default, the Dependencies view is not updated when you open other documents, because the
Pin Contents button is selected when you first open the Dependencies view.
To disable this behavior:
• In the Dependencies view, click the Pin Contents button ( ) so that it is unselected.
The Dependencies view will be updated when you open other documents. To disable
update of the Dependencies view, click the Pin Contents button again.
Related Links
Filter the Dependencies view

This procedure lets you filter out unwanted categories of dependencies.
You can filter the Dependencies view so that you see only the relationships that you're currently
interested in. If you're looking for all the localized topics that originated from the current document,
Viewing where documents are used 261
it might make the view less cluttered if you eliminated all the cross references from the
Dependencies view.
You can also simplify the view by filtering out categories that have no documents in them.
1. In the Dependencies view, click the Show/hide dependencies button ( ).

The context menu displays the available choices.
2. Select the options that you want displayed.
The selected set of dependencies are displayed in the Dependencies view.

Related Links
Export Dependencies as TSV

Use this procedure to export the contents of the Dependencies view as a tab-separated values
(.tsv) file.
The resulting file will include all dependencies directly related to the selected object, including
those in folders that are currently hidden. This means it will list the dependencies such as the
parent, child, and so on of the selected object, but it will not include the dependencies of those
dependencies.
You can import the .tsv file you create into other programs, such as a spreadsheet.
1. In the Dependencies view, click the Export Dependencies List button ( ).

3. Click Save.
The file is saved in the specified location.
Related Links
13 Working with resources
Working with resources
Topics: Resources are document objects that support a

• About resources documentation project. For example, schedule charts could
• Create a resource be added as a reference resource for a project with a long
• Add an item to a resource and complex timeline.
• Set the default resource
The following procedures describe how to work with
• Edit resource metadata
resources.
• Edit a resource item
• Creating soft links
• Add a resource directly to
a map
About resources
Resources let you store non-DITA material (such as PDF files, legacy documentation, etc.) with
a documentation project.
When document deliverables are developed, you may have background or related material that
isn't part of the deliverable itself, but that you will want to store close to the related documents,
so that you can find it easily. For example, you might want to store the project schedule charts
you used with a particular documentation suite, or a list of map variables and the topics where
they are used.
Resources allow you to bundle similar items and store them in the repository. You can add the
resources to a map or to a project.
Resources are imported into the repository like images and topics. While you import a resource,
you can add keywords and other descriptive text that will help you find the resource when you
need to search for it.You can go back and edit this data later on using the Edit resource metadata
procedure.
Resources go through cycles and status changes just like other files.You can manage resources
in the same ways that you manage your topics and maps.
Related Links
Add a resource directly to a map on page 272
Edit resource metadata on page 268
Create a resource
This procedure adds a new resource to the repository.
Use this procedure to add a new resource to the repository. You can import a single file or a
folder. When you import a folder, all of its files and subfolders are imported and the folder structure
is kept in the resource object.
To create a resource:
• On the Document Creation toolbar, click the Create New Resource Object button ( ).
• From the menu bar, select DITA CMS > Create Resource.
The Show/Edit Resource dialog appears.

2. Enter a Title.
Working with resources 265
Titles do not need to be unique.

3. Enter a brief Description.
This information is stored in the object's metadata. Enter all the keywords that may be useful
when you search for the object.
4. Select a Resource Type.
The selections that you see depend on your system configuration. Typical choices might be
"pdf-legal", "related Word documents", or "multimedia".
6. To import a folder:
a) Click Import Folder.
The Browse for Folder dialog appears.
b) Navigate to the folder to import, select it, and click OK.
The Show/Edit Resource dialog reappears. The Content area displays the imported
folder as well as all the files that it contains.
7. To import a single file:

a) Click Import.
The Open dialog appears.
b) Navigate to the required file, select it, and click Open.
The Show/Edit Resource dialog reappears.The Content area displays the new resource.
8. (Optional) Enter a Description next to the new items, if required.

9. Repeat the import process as necessary.
10. (Optional) Select the resource to use as the default and click Set as Default.
This specifies the file within a resource that will be used, for example, during a build.
11. If required, click User Properties.
The User Properties dialog opens.
12. Enter or select values as required.
The User Properties dialog is another way to enter indexable information about a resource.
The fields or selection lists that appear here are configurable and will vary according to your
setup.
13. (Optional) To save the settings you have selected for Resource Type and Language,
click the diskette icon at the bottom of the dialog ( ).
Your selections are saved and used as the default values in the dialog. You'll see them the
next time you create a resource.
in your deployment:
• If you see the Next button at the bottom of the Show/Edit Resource dialog, this module
is enabled in your deployment. Go to the next step to specify the release management
details.
• Otherwise, this module is not enabled. Click OK to create the resource. You have
completed this procedure.
15. Click Next.

The Select Versions dialog box is displayed.
and Versions.
Use the filter at the bottom of the pane to filter the products in the list by release name.
see them there the next time you create a resource.
21. Click Create.
The resource and all its constituent items are added to the repository.
Note: Any resource that you create is automatically assigned to you.
Tip: You can configure a default import directory where the Open dialog will go
automatically.
Related Links
Configure import and export directories on page 613
Add an item to a resource

This procedure lets you add a new item to an existing resource.
Once you've created a resource, you can add new items to it.
1. Use Search to find the resource to edit.

2. In the Search Results view, right-click the resource and select Edit from the menu.
The Progress Information dialog will be displayed as the file is locked.
3. To import a folder:
a) Click Import Folder.
The Browse for Folder dialog appears.
b) Navigate to the folder to import, select it, and click OK.
The Content area of the Show/Edit Resource dialog now shows the imported folder as
well as all the files that it contains.
4. To import a single file:

a) Click Import.
b) Navigate to the required file, select it, and click Open.
The Content area of the Show/Edit Resource dialog now shows the new resource.
5. (Optional) Type a Description next to the item you've added.

6. Repeat the import process as required.
7. When you are finished importing, click OK.
8. In the Search Results view, right-click the resource and select Release from the menu.
The resource and its additional item(s) are added to the repository, and all descriptive
information is saved.
Related Links
Set the default resource

This procedure designates a file within a resource as the default. This can be used, for example,
to specify the specific file within a resource that will be used during a build.
To set a default resource file:
1. Use Search to find the resource you want to edit.

3. Select the file that you want to set as default.
4. Click Set as Default.
5. Click OK.
Edit resource metadata

Once you've created a resource, you can change its title, description, and user properties.
To edit a resource metadata:

3. Make your edits to the Title and Description fields.
Enter all the keywords in the Description field that you think may be useful when you next
want to search for the resource.
4. If required, click User Properties.
Note: If the User Properties button is disabled, it means that resource properties
have not been defined in the system configuration userproperties.xml file. Please
consult your DITA CMS administrator.
The User Properties dialog opens.
5. Enter or select values as required.
The User Properties dialog is another way for you to enter indexable information about a
resource. The fields or selection lists that appear here are configurable and will vary according
to your setup.
6. Click OK.
Your changes are saved to the repository.

Related Links
About resources on page 264
Edit a resource item

You can edit one of the items in a resource—such as a Word file—from within the DITA Perspective
using your default editor.
Note: An editor must be associated with the extension of the file type you intend to edit.

The Progress Information dialog is displayed while the file is locked and the Show/Edit
Resource dialog then appears.
3. Select the Item name to edit.
4. Click Edit.
The document opens in the default editor specified for this type of file. For example, a .doc
or .docx file might open in Microsoft Word, and a .pdf file might open in Adobe Acrobat. Note
that you must have associated an editor with the extension of the file type you intend to edit.
5. Make the required changes to the document and save it as you normally would in the
editor (using CTRL+S in Word, for example).
6. Close the document.
7. In the DITA CMS Show/Edit Resource dialog, click OK.
8. In the Search Results view, right-click the resource and select Release from the menu.
The edited document replaces the previous document in the repository and all descriptive
information is saved.
Related Links
Associate editors with documents on page 606
Creating soft links

Soft links let you create logical connections between resource objects and DITA CMS objects.
Soft links create a dependency from a binary object to a DITA object. This can be used, for
example, to indicate that an image is used in both a DITA CMS map and legacy documentation
stored in a resource. If you need to update the image, then you know that you will also need to
update it in the legacy documentation. You could also use this feature to link a DITA CMS map
to its FrameMaker legacy documentation resource so that you can access it later on if necessary.
Note: Soft links have no impact on the objects being linked, on the workflow, or on the
output. They simply provide logical linking information.
To create soft links, you manually create a dependency between the binary object and the DITA
object through the Dependencies view, as follows:
1. Open the Dependencies view for the DITA object to link.

For example, to link a DITA CMS map to a FrameMaker legacy documentation resource,
open the Dependencies view for this map.
2. If soft links are not listed in the map's dependencies, click Show soft links ( ).
Two dependency categories are displayed:
• Inward Soft Links: Objects that link to this document.

• Outward Soft Links: Objects to which this document links.
3. Search for the resource or image to which you want to link.

The object is listed in the Search Results window.
4. Drag the resource element to the Outward Soft Links category in the Dependencies
view.
For example:
The resource element is added as an outward soft link. For example:
The map will appear as an inward soft link in the Podcasts object's dependencies.
Remove soft links

You can remove soft links from an object when they are no longer necessary.
To remove soft links from an object:
1. Open the Dependencies view for the DITA CMS object from which to remove the link.
For example, to remove the link from a DITA CMS map to a FrameMaker legacy documentation
object, open the Dependencies view for this map.
2. If soft links are not listed in the dependencies for this map, click Show soft links ( )
in the Dependencies view.
3. Expand the Outward Soft Links category, right-click the link to remove, and select
Remove from soft links.
The link is removed.
Prerequisites: Adding soft link indexes

Two indexes are required for the soft link feature.
If these indexes are not defined, the following warning message is displayed:
System administrator should add this index to the TEXTML index definition. softlink.id is
not a valid key.
To add soft link indexes:
1. Open the TEXTML Administration perspective.

2. Connect to your server and Content Store.
3. Expand the Content Store node to display the Index Definition branch.
4. Right-click Index Definition and select Check out.
5. Open the Index Definition Document in an XML editor.
6. Under <indexes> add the following <index> elements:
<index NAME="softlinks.extractor" SYNC="True" CUSTOMPROPERTY="True">
<stringindex KEEPEXTRACTEDVALUES="True">
<elements>
<element XPATH="//softlink/@key" DEPTH="INFINITE"/>
</elements>
</stringindex>
</index>
<index NAME="softlink.id" SYNC="True" CUSTOMPROPERTY="True">
<stringindex KEEPEXTRACTEDVALUES="True">
<elements>
<element XPATH="//softlink/@id" DEPTH="INFINITE"/>
</elements>
</stringindex>
</index>
7. Save, close, and check in the Index Definition document.
Add a resource directly to a map

You can add a resource directly to a map by dragging the resource to the map view.
When you add a resource to a map, the DITA CMS creates a topicref to the resource and
sets the following attribute:
• @processing-role="resource-only"
For example:
<topicref href="lar1409844676342.res" keys="lar1409844676342" processing-role="resource-only"/>
This ensures that the map can be generated correctly.

To add a resource directly to a map:
Drag the resource to the map in the DITA Map view.

The resource is added to the map.
Related Links
About resources on page 264
14 Images
Images
Topics: This section provides the procedures to manage images for

• Working with images different types of output.
• Image resolutions and Images are imported into the repository and saved with the
formats
.image extension. While you are importing your image, you
• Create an image
can add keywords and other descriptive text that will help you
• Preview an image
find the image when you need to search for it. You can go
• View image thumbnails
back and edit this data later on using the Edit image metadata
• Turn off thumbnail display
• Open an image procedure.
• Add an image directly to a
map
• Set the default image
• Edit image metadata
• Replace an image
• Edit an image
• Export images
Working with images

Images go through cycles and status changes just like other types of files, and they are added
to topics as references.
You can manage images in the same ways that you manage your topics and maps.
When it comes to Localization, you may even find that images need less management than
text-based files. Often a graphic will work equally well whatever language the surrounding text
may be. Instead of having to track these images through the initial portion of the Localization
cycle, you can flag them as not needing translation; then, when the map is put into the Localization
cycle, they'll automatically be promoted by the system into Localization:review (or its equivalent
in your workflow).
Images are imported into the repository and saved with the .image extension. While you are
importing your image, you can add keywords and other descriptive text that will help you find the
image when you need to search for it. You can go back and edit this data later on using the Edit
image metadata procedure.
Images can be referenced by more than one topic and referenced by topics in more than one
map. Image references are validated when the topic is released. An image cannot be deleted if
it is referenced by a topic.
Tip: To view all the places where an image is referenced, search using the image's ID.
For example, if you look at the XML code for a topic and see a reference to an image that
looks something like this:
<image height="300" href="dit1144085184906.image" width="600">

<alt>topics and maps</alt>
</image>
You can use a line like the one below in Advanced Search to find all the topics that refer
to it. Use the Copy ID procedure to obtain the ID Value.
And attributes href dit1144085184906
Related Links
Edit image metadata on page 284
Associate editors with documents on page 606
Import topics on page 417
Import images on page 405
Import multiple resolution images on page 409
Images 277
Import maps on page 412
Image resolutions and formats

DITA CMS lets you maintain images in different resolutions and formats for use with different
types of output.
Different output formats frequently require different image formats for optimal display
characteristics. You might, for example, want to use a low resolution interlaced JPEG with output
that’s designed for the web and have a high-resolution version for PDFs.
When you import multi-resolution images into the system, they are assigned a collective ID and
stored in a zip file with the extension .image. Then, when output is generated, the transformation
template inserts the appropriate image format wherever the image ID appears in your XML text.
The following diagram shows the different formats that can be set for an image:
The format names that you see will vary according to how your system is configured. When you
import multiple formats for an image, they are displayed in the Images pane as shown below:
A line with no image details (no Mime Type, Width, Height) means that there is no image in the
repository for that format. A line with image details means that an image with that format exists
in the repository. The details of an image can be displayed in the following colors:
• Green: The image was created and has not been released (shown above).
• Blue: The image was edited and has not been released.
• Grey: The image was released to the repository.
The default image format is displayed in bold. The default format is the one that is displayed if
the Output Generator cannot find the format specified in the transformation template. This is also
the image that displays in the Preview view.
Related Links
Set the default image on page 283
Create an image
Use the Create Image command to add a totally new image to the repository. If you're simply
adding a new resolution of an existing image, you should use the Replace image procedure.
Once you've imported the first image, you can keep the dialog open and import several different
formats for use with different types of output.
To create a new image:
• Press CTRL+ALT+I.
• On the Document Creation toolbar, click the Create Image button ( ).
• From the menu bar, select DITA CMS > Create Image.
The Show/Edit Image dialog appears.

2. Enter a Title.
Titles do not need to be unique.
3. Enter a brief Description.
This information becomes part of the file metadata. Enter all the keywords that you think may
be useful when you want to search for the file.
4. Select an Image Type: Screen Capture, Line Art, or Equation.
5. If the image requires localization, select Needs Translation.
Images 279
By default, this check box is enabled for Screen Captures and Line Art. You can override the
defaults and select the value that's appropriate.
Note: If Needs Translation is not selected, then when the map is put into the
Localization cycle, the image will automatically be given the status Localization:review
(or its equivalent in your workflow).
7. In the Images area, select a Format name.
Format names represent the different graphic formats or resolutions that your system uses
with different types of output. The format names that you see here will vary according to how
your system is configured.
A line with no image details (no Mime Type, Width, Height) means that there is no image in
the repository for that format.
8. Click Import.
9. Navigate to the required image, select it, and click Open.
Tip: You can configure a default import directory where the Open dialog will go
automatically by configuring the DITA CMS Import Export options in Preferences.
The Show/Edit Image dialog reappears. The Images area displays the new image's Mime
type, Width, and Height, and the image itself is previewed at the side.
10. Repeat the import process for the different formats.
Once an image has been imported into the repository for a specific format name, that line
displays in green to indicate that this is a new image. The default image is displayed in bold.
11. Select the image format that you want to use as the default and click Set as Default.
This is the image that will appear in the Preview view. It's also the image that will be substituted
if the Output Generator cannot find the format specified by a transformation template.
13. (Optional) To save the settings you have selected for Language and Image Type, click
the diskette icon at the bottom of the dialog.
Your selections are saved and used as the default values in the Show/Edit Image dialog.
You'll see them there the next time you import an image.
in your deployment:
• If you see the Next button at the bottom of the Show/Edit Image dialog, this module is
enabled in your deployment. Go to the next step to specify the release management
details.
• Otherwise, this module is not enabled. Click OK to create the image.You have completed
this procedure.
15. Click Next.

The Select Versions dialog box is displayed.
and Versions pane.
Use the filter at the bottom of the pane to filter the products in the list by release name.
Images 281
see them there the next time you create an image.
21. When you are finished importing, click OK.
All the imported images are assigned a collective ID and stored in a zip file with the
extension .image. When output is generated, the transformation template will insert the
correct format or the default format if there is no image with the required format.
You can now insert the image in a topic.

Related Links
Insert an image into a topic on page 250
Insert an image from a remote location into a topic on page 250
Image resolutions and formats on page 277
Replace an image on page 285
Insert an image into a topic in the oXygen editor on page 300
Insert an image into a topic on page 250
Preview an image
The Preview view lets you view image file contents without opening the document.
When you are looking at the images listed in the Results List or other DITA CMS views, you may
find it convenient to quickly preview the images. The Preview view is refreshed whenever you
highlight an image item.
Image previews are available for all common image formats.
You can preview images wherever they are displayed in DITA CMS: Search Results, Todo List,
Dependencies view, etc.
To preview an image, right-click the image name from the view and select Show Preview. You
can also do the following:
1. If necessary, open the Preview view.

2. In the Search Results view (or any other view that displays images), select the image
to preview.
The image preview appears in the Preview view.
3. (Optional) You can print out the contents of the Preview using its Print button.
View image thumbnails

Thumbnails give you a quick way of viewing the contents of an image file.
Even if the Preview view is closed, you can still quickly view a thumbnail of an image that's listed
in the Search Results view, your Todo List, or any other place where you can open image
documents.
A thumbnail is generated:
• The first time an image is displayed in the preview pane.

• When a new image is created.
• When the image is edited in the Edit Image dialog.
Once a thumbnail has been created, it is stored on the server and becomes available to all users
the next time their thumbnails are synchronized. Thumbnails are synchronized every 30 minutes.
1. If necessary, click the Turn on thumbnails button ( ).

The views that support image thumbnails all have this button in their frames.
2. Hover your cursor over the image you want to view.
The image thumbnail appears in a new window. If the following message is displayed:
Thumbnail not available
Then the thumbnail hasn't been synchronized yet. It should be available in the next 30 minutes.
Turn off thumbnail display

You can turn off thumbnail display in a specific view.
You have the option of having thumbnail previews appear whenever you hover the cursor over
a topic or image title in a view such as Search Results or your Todo list. By default, thumbnail
display is enabled.
To disable topic thumbnails:
• In the required view, click the Turn off thumbnail display button ( ).
Images 283
Open an image
This procedure opens an image for viewing.
1. Use Search to display the image in the Search Results view.
2. Right-click the image and select Open from the menu, or double-click the image in the
list.
Tip: You can also open an image by double-clicking its name in the Todo List.
The image opens in the Show/Edit Image dialog.
Add an image directly to a map

You can add an image directly to a map by dragging the image to the map view.
When you add an image to a map, the DITA CMS creates a topicref to the image and sets
the following attributes:
• @format="image"
• @processing-role="resource-only"
For example:
<topicref format="image" href="per1389986115346.image" keys="per1389986115346"
processing-role="resource-only"/>
This ensures that the map can be generated correctly.
To add an image directly to a map:
Drag the image to the map in the DITA Map view.

The image is added to the map.
Set the default image

This procedure designates an image as the default for all output formats.
The default image format is displayed if the Output Generator cannot find the format specified in
the transformation template. This is also the image that displays in the Preview view.
Note: You cannot delete the default image format.
1. Use Search to find the image for which you want to set a default.
2. In the Search Results view, right-click the image and select Edit.
The Progress Information dialog will be displayed as the file is locked and the Show/Edit
Image dialog appears.
3. Select the Format name to set as default.
4. Click Set as Default.
5. Click OK.
6. In the Search Results view, right-click the image and select Release.
The selected image format will display wherever the image is referenced in the Preview
view, or if the format specified by the transformation template cannot be found.
Related Links
Edit image metadata

Use this procedure to modify image descriptions and titles, add keywords, or change the translation
requirements.
1. Use Search to find the image to edit.
3. Edit the Title and Description fields.
Enter all the keywords in the Description field that you think may be useful when you next
want to search for the image.
4. Change the image Language, if required.
5. Select or deselect the Needs Translation check box, as required.
6. Click OK.
Related Links
Working with images on page 276
Images 285
Replace an image
You can replace an image in the repository with another, and you can also add different formats
or resolutions of the same image for use with different output formats.
When you replace an image, the new image will be used by every topic where the image is
referenced.

3. Select the Format Name of the image to replace or add.
Format names represent the different graphic formats or resolutions that your system uses
with different types of output. The format names that you see will vary according to how your
system is configured.
If there is an image in the repository for a specific format name, that line is displayed in dark
gray and details are provided about the image. A line with no details means that there is no
image in the repository for that format. The default image is displayed in bold.
4. Click Import.
5. Navigate to the required image, select it, and click Open.
The Confirm Overwrite dialog appears.
6. Click Yes.
The Show/Edit Image dialog reappears and the new image is displayed in green. The Image
area displays the new image's Mime type, Width, and Height, and the image itself is
previewed at the side.
7. Click OK.
The new image replaces the old image in the repository. The new image will be used by
every topic where the image is referenced.
Related Links
Set the default image on page 283
Export images on page 287
Edit an image
You can edit an image from within the DITA Perspective using your default editor.
Your image editor must be associated with the extension of the image type you intend to
edit.

3. Select the Format name that corresponds to the picture to edit.
Note: If you are changing content, you will need to edit all the different formats of a
given graphic.
4. Click Edit.
The image opens in your default image editor.
5. Make the required changes to the image, save it, and close the default image editor.
The Show/Edit Image dialog reappears and the image you edited is now displayed in blue
to indicate it has been modified. The Image area displays the new image's Mime type, Width,
and Height; the image itself is previewed at the side.
6. (Optional) Edit the Title and Description fields if required.
7. Change the image Language, if applicable.
8. If the edited image requires localization, select Needs Translation.
9. Click OK.
Images 287
The new image replaces the old image in the repository and all descriptive information is
saved. If you have edited the default image, the new image will appear in all existing
references.
Export images
You may want to export images to edit them locally and then reimport them into the DITA CMS.
This can be useful when you are working remotely, and the DITA CMS is installed on a server
that does not have the proper image editing tools. You can use the procedure below to export
images locally, update them using your preferred image editor, and then reimport the images in
the DITA CMS.
To export images:
1. Use Search to find the image to export.

3. Click Export.
4. Navigate to the directory where you want to save the image formats and click OK.
All the available formats for the image are saved in the location you specified. For example:
5. Edit the images with your preferred editor. Make any change required, and then reimport
the files as described in Replace an image.
Related Links
15 Offline work
Offline work
Topics: This feature lets you keep working when you can't connect
• About the Offline to the Content Store.
Perspective
• Work offline
• Offline functionality
summary
• Refresh the Offline
Documents view
• Filter the Images view
• Return from the Offline
Perspective
About the Offline Perspective

The Offline Perspective offers a restricted set of DITA CMS functionalities.
Whenever you're working in DITA CMS, the topics you lock are copied onto your hard drive,
where you edit and save them locally. After you've finished working, you release them, and they
are copied back to the repository.
Working offline lets you continue working when you don't have access to the repository - on an
airline flight, for example - and only release your files back to the server once you're connected
back to the network.
The Offline Perspective contains the following:
• The editor area is where your topics open, just as they do in the DITA Perspective. You can
use any editor that's installed on your machine and configured for use with Eclipse.
• The Offline Documents view lists the topics you locked before you went offline.You can open
and work with these in your editor of choice. You'll be able to copy their IDs and use them for
making cross-references and related-links.
• The Images view displays thumbnails of all the images in the repository. You'll be able to copy
their file names and IDs to use with the <image> tag, or for making cross-references and
related links. You won't, however, be able to modify them in any way.
There are two display modes:
• Small thumbnails - displays the image thumbnail as well as its system ID.
• Details - in addition to the thumbnail and ID, displays the image's CMS title, status, type
(Line art, for example), and all the text from the image's Description field. You'll be able to
filter the images that are displayed using any of this information.
Note: Image thumbnails must be synchronized in order for them to appear in the Offline
Perspective.
Work offline
This procedure opens the Offline Perspective.
Any documents you want to work on must be locked before you go offline.
1. Open DITA CMS.

The Preferences dialog will open with an error message displayed.
2. In the Preferences dialog, click the Work Offline button.
Offline work 291
The Offline Perspective opens.
Offline functionality summary

Summarizes the functionality available in the Offline Perspective.
This table summarizes the DITA CMS functionality that is available from the right-click menu
when you are working offline.
Note: All topics listed in the Offline documents view are already locked. When you open
a topic it is ready to be edited.
• Open (topics only)

• Open With > editorname (topics only)
• Copy > Reference - copies a document's file name to the clipboard. For example,
jan1236299873904.image.
• Copy > Full Path - copies a document's root ID to the clipboard, together with its full path with
respect to the repository root. For example,
/content/authoring/per1236698006846.image.
• Copy > ID - copies a document's root ID to the clipboard. For example, jan1236299873904.
Related Links
Copy ID on page 254
Copy full path on page 254
Open a topic on page 205
Open a topic with a specified editor on page 206
Refresh the Offline Documents view

This procedure updates the display of topics in the Offline Perspective.
If you're frequently moving between the DITA and Offline Perspectives, you may want to
periodically refresh the Offline Documents view. This ensures that all the locked files on your
machine are included in the display.
• In the Offline Documents view, click the Refresh button ( ).

The view is updated.
Filter the Images view

This feature lets you limit the number of images displayed in the Offline Perspective.
The filter field offers you a way of searching through any of the text that's associated with the
images in the Images view.
You can search by a portion of the ID, or by the image title, or by any fragment of the text contained
in the image's Description field.
1. Type the required text into the filter field.

2. Click the Apply Filter button.
The corresponding images are displayed.
Return from the Offline Perspective

This procedure tells you how to return to the DITA Perspective.
When you have access to the Content Store again, you'll want to return to the DITA Perspective
and release your files.
• From the menu bar, click Window > Open Perspective... > DITA.
• In the Perspective Shortcut Bar, click the DITA button.
The DITA Perspective opens in the Eclipse Workbench.

Note: You must now release your files - just as you would after any editing session - in
order for them to be saved to the Content Store.
16 The oXygen Editor
The oXygen Editor
Topics: The oXygen Editor offers you an intuitive interface for working
• oXygen quick reference with XML documents.
• Referencing other files in The oXygen Editor's working environment gives you many
the oXygen editor
powerful tools for working with XML documents. This includes
special views for working with attributes and elements, as
well as display modes that let you switch between WYSIWYG,
text and tag-enhanced displays.
oXygen quick reference

Summarizes the DITA CMS extensions to the oXygen editor.
The following table shows the shortcuts and buttons that activate the DITA CMS extensions to
the oXygen editor.
If you have mapped any Windows CTRL+ALT shortcuts to use the key sequences shown here,
the Windows shortcuts take precedence.
The key mappings shown in this table are the default. Your system may be set up differently. If
you want, you can change key mappings through the Preferences dialog.
Note: Some shortcuts may conflict with other Eclipse plug-ins.
Feature Shortcut Toolbar Other Access Description and

button comments
Lock a topic ALT+L In Text mode, right-click Locks the current topic in
then select Lock. the XML Editor.
Release a CTRL+ALT+SHF
IT+R In Text mode, right-click Releases the current topic
topic then select Release. in the XML Editor.
Replace with In Text mode, right-click Replaces the contents of

server then select Replace with the current topic with the
revision Server Revision. latest revision on the
server.
View In Text mode, right-click Opens Dependencies view

dependencies then select View and displays the current
Dependencies. topic's dependencies.
Related Links
Configure key mapping on page 608
Referencing other files in the oXygen editor

These procedures describe the menu options available in the oXygen editor for making references
and hypertext links to other files.
The oXygen editor gives you powerful tools that let you easily make xrefs and related links. These
operations automate many of the file referencing features.
The oXygen Editor 295
Related Links
Referencing other files on page 249
Create a cross-reference to another topic

You can insert a link to directly reference another element.
The <xref> element lets you make a cross-reference from one topic to another.
DITA Best Practices recommend using cross-references sparingly since they break the principle
of creating "standalone topics". Cross-references, which are directly inserted into a topic, can
cause issues when attempting to reuse the topic in another map. Consider using a relationship
table to manage the links between the topics or organizing your table of contents to imply the
relationship between the topics.
To create a cross-reference:
1. Open and lock the topic in your XML editor.

You can select a topic displayed in any of the DITA CMS views. For example, you can select
the topic from the Search Results view, DITA Map view, or from your favorites.
4. Right-click the reference topic and then click Oxygen Editor > Insert as Xref
The cross-reference is inserted where the cursor was placed.
Create a cross-reference to an element within the same topic

You may want to create links within a topic; for example, have a bulleted list which links each
item to a corresponding section in the topic.
When you create a link referencing another part of the same topic, you need to first add an ID
attribute to the target element and then create the cross-reference.
To create the internal cross-reference:
1. Add an ID attribute in the element to which you want to cross-reference.

For example, if you had a bullet list at the top of your topic and you wanted to link each list
item to a section later in the topic, you would add an ID to each section element: <section
id="firstbullet">

3. In the DITA Map view, right-click your topic.
If you do not have the map containing the topic open in the DITA Map view, either open the
map or perform a search so you can display the topic in a view.
4. Select one of the following depending on your environment and XML editor:
5. Right-click the cross-reference and click Edit Attributes.
6. In the Value box for the href attribute, add the ID attribute for the topic and the ID
attribute for the element that you want to reference.
Use the following syntax:
filename.xml#topicid/idstring
where:
• filename is the file name of the topic

• topicid is the root ID of the topic
• idstring is the ID of the target element
For example, if your topic ID is acb4321987654321 and the target element's ID is

firstbullet, then the value would be:
acb4321987654321.xml#acb4321987654321/firstbullet
7. In the cross-reference element, type the text that you want to display.
For example:
<xref href="acb4321987654321.xml#acb4321987654321/firstbullet">This is the first bullet
point.</xref>
Create a cross-reference (xref) to a file or web site in the oXygen

editor
Use the xref element to create a hypertext link to remote systems, FTP sites, or local files outside
the repository.
When you are cross-referencing files outside the repository, you may use either absolute or
When you specify the path for your cross-referenced file, you should make sure that the path
makes sense with regard to the machine (and the local network) where the files will be installed.

2. In Author mode, highlight a word or phrase where you want to insert the xref.
Note: The text you highlight must be within an element that allows <xref>s.
3. Right-click any topic in one of the DITA CMS views, then select Oxygen Editor > Insert
as Xref from the menu.
Note: This inserts an XML cross-reference (xref). You'll need to edit its attributes so
that it references the actual file or remote location.
4. Highlight the newly created <xref>.
5. Open the oXygen Attributes view.
6. In the <xref> tag's href attribute, type the location you want to reference.
The following table shows the types of location accepted by the href attribute and their
syntax.
The following screen shot shows an example of an edited href attribute.

7. In the <xref> tag's scope attribute, select external.
Insert related links into a topic in the oXygen editor

You can insert a related link using a simple right-click operation.
Referenced topics must be in the Authoring or Published cycle (or its equivalent in your
workflow).
The related link element lets you put a series of links to related topics into the current topic.

2. In Author mode, place the cursor anywhere in the topic.
You can make references to topics displayed in any of the DITA CMS views.
4. Right-click the topic you want to reference, then select Oxygen Editor > Insert as
Related Link from the menu.
The topic title appears in the Related Links section, with the link created. If there is no Related
Links section, oXygen creates one.
5. (Optional) Insert additional links as needed.
Insert related links to files or web sites in the oXygen editor

You can edit the related link element to make links to websites and FTP locations, as well as to
files outside the repository.
When you are linking to files you may use either absolute or relative pathnames. However,
you should keep in mind that setups vary in different machines.You can safely use relative
pathnames if you are sure that multiple documents will always be sent as a single package.
However, if there’s a chance that only a portion of the files will be sent, and that the target
file isn’t among them, then the link may become invalid.

2. Place the cursor anywhere in the topic.
3. Use Search to display topics in the Search Results view.
4. Right-click any topic, then select Oxygen Editor > Insert as Related Link from the menu.
Note: This inserts an XML related link. You'll need to edit its attributes so that it
references the actual file or remote location.
The topic title appears in the Related Links section, with the link created. If there is no Related
Links section, oXygen creates one.
5. Place your cursor on the newly created <link>.
6. Open the oXygen Attributes view.
7. In the <link> tag's href attribute, type the location you want to reference.
syntax.

8. In the <link> tag's scope attribute, select external.

9. (Optional) Insert additional links as needed.
Insert an image into a topic in the oXygen editor

You can insert a graphic using a simple right-click operation.
Note: This procedure does not add an image to the Content Store. It inserts a reference
to an image that already exists in the Content Store. See "Create an image" to add an
image to the Content Store.
1. Open the topic in the oXygen editor.

Note: You must place your cursor within an element that allows images.
3. Locate the image you want to reference.
You can make references to images displayed in any of the DITA CMS views.
4. Right-click the image to insert and select Oxygen Editor > Insert Image from the menu.
Insert an image from a remote location into a topic in the Oxygen

editor
You can edit an image reference to insert images from remote locations, FTP sites, or local files
outside the repository.
When you are inserting images from outside the repository, you may use either absolute or
When you specify the path for your image, you’d better be sure that the path makes sense with
regard to the machine (and the local network) where the files will be installed.
Note: When you use this procedure, the images will not be part of your output. The
output will be created with links to the images. When you load your output onto the web
server, the content will link to external images in the location you specified.

Note: You must place your cursor within an element that allows images.
3. Right-click any image in one of the DITA CMS views, then select Oxygen Editor > Insert
Image from the menu.
Note: This inserts an image. You'll need to edit its attributes so that it references the
actual remote image.
4. Open the Oxygen Attributes view.
5. In the <image> tag's href attribute, type the location you want to reference.
syntax.

Your remote image will appear in the image reference.

17 Document assignments
Document assignments
Topics: These procedures let you assign documents to people and

• Assign documents to users designate the due dates and approval systems.
• Set document due dates Documents are assigned to different sets of users at different
• Set document approval points in the document development cycle. Graphic artists
systems
create images that are reviewed by editors and technical
• View document
assignments in the Todo experts. In some installations, authors create topics in the
List initial stage, and then the editors and technical experts review
• Add comments to DITA them. In others, subject matter experts create the topics and
CMS assignments writers and editors do the polishing.
Whatever document life cycle you follow, DITA CMS offers

functions that let you easily assign documents to the user
roles that are responsible for them in each phase and set due
dates for each set of users.
Users can keep track of their assignments and due dates in

their Todo Lists.
Assign documents to users

The DITA CMS lets you quickly and easily assign documents to the people who will be responsible
for them in the different phases of the document development cycle.
Note: User roles must be configured for each type of document.
The number of people that you can assign to a given document varies according to the role. For
example, there may be several Reviewers assigned to a topic, but there will typically be only one
Author. The Assignments dialog displays the maximum number of people that can be assigned
to the selected documents per role.
The Assignments dialog also contains filters that let you restrict the number of people who appear.
This feature is useful if you are working in a company with dozens of employees, and you need
to limit the choices that are presented. You can filter:
• By project - restricts the display to people that are on the team of a specific project.
• My projects only - further restricts the display to projects where you are on the team.
Note: Project coordinators are considered to be team members of any project they are
currently managing, whether or not they are actually listed in the project.
• By group - restricts the display to the selected group. Group names are configurable, and the
exact list will vary.
Note: Deactivated users who are still assigned to documents are identified in grey. Once
the document is reassigned to an active user, the deactivated user name will no longer
appear.
To assign documents to users:
1. Right-click the required documents.

You can select multiple documents by holding down CTRL or SHIFT and clicking the
documents.
2. Select Assign to.... from the menu.
The Assignments dialog appears with a left and right pane. The left pane displays all the
roles that are configured for the types of documents you selected.
If any of the check boxes are selected, this means that some of the documents you selected
are already assigned to people.
Note: Role names are installation-specific.The diagram below shows the names used
at IXIASOFT Technology.
Document assignments 305
3. Expand each role to see the list of people who are available.
In the following diagram, the Reviewer role is expanded.
4. Select the required people from each role.

You can enter text in the Filter results on the first column's text... field to find certain
people.
5. (Optional) If you are assigning documents that are part of a project and you want to
use the project's default role assignments, right-click the role name and select Use
Project Default(s) > projectname (where projectname specifies the project whose role
assignments you'd like to use).
If there are no available projects, this section will be disabled.
The documents are assigned to the people who hold the default role assignments in the
selected project.
6. (Optional) Expand each person’s name to assign selected documents to that person.
In the following diagram, two reviewers have been assigned topics.
7. Click OK when you're finished.
The people to whom you've assigned documents will see the document names in their
Todo Lists.
Related Links
User roles and timelines on page 47
Set document due dates

Use this procedure to set due dates for document tasks by role and user.
User roles must already have been configured for each type of document.

documents.
2. Select Assign to... from the menu.
The Assignments dialog appears.
3. Go to the right pane.
The right pane displays your selected documents, grouped under the user roles that are
responsible for them. For example:
4. Select and right click a document and then select Set Due Date from the menu.
You can select multiple documents under each role by holding down CTRL or SHIFT and
clicking the documents.
An interactive calendar appears. For example:
5. Select the required date, then click OK.

The selected date appears in the Due Date column.
6. (Optional) If you need to clear the date from a document, right-click and then select
Clear Due Date from the menu.
7. Repeat for each document or role, as required.
8. Click OK in the Assignments dialog when you're finished.
When these documents are assigned to specific people, the document names and their
due dates will appear in their Todo Lists.
Related Links
Set document approval systems

This procedure lets you establish approval criteria for individual documents.
• User roles must have been configured for each type of document.
• Approval rights must have been assigned to the appropriate roles.
Use this procedure to set or change the approval system for the document by role or individual
user.
The list of approval systems and the default approval system (if any) for each role is set during
system configuration. Some roles do not require or allow for an approval system, so you cannot
set an approval system for those roles.
If the selected documents are part of a project, you cannot set a more stringent approval system
than what was set at the project level. If there is a conflict between user-set approval systems,
the more restrictive system always takes precedence.

documents.
2. Select Assign to.... from the menu.
The Assignments dialog appears. It displays all the roles that deal with the types of documents
you selected.
3. Select the Settings tab.
The Settings tab displays your selected documents, grouped under the user roles that are
responsible for them. The screen shot shows a set of users assigned to a selected set of
topics.
4. Right-click a role and then select Set Approval System > systemname
where systemname specifies the approval system you want to use. Typical selections might
be Unanimous, Single Approval, or Simple Majority. The available selections are based
on your system configuration.
Tip: You can select multiple documents under each role by holding down CTRL or
SHIFT and clicking the documents.
Your selection appears in the Approval System column
5. (Optional) If you need to clear the approval system from a document or from a role,
right-click and then select Clear Approval System from the menu.
6. Set approval systems for each document or role, as required.
The assigned users will see the due dates next to the document names in their Todo Lists.
Related Links
View document assignments in the Todo List

You can view your document assignments in the Todo List. This view also shows you when your
documents are due and the other people who are responsible for them.
The Todo List lets you limit your display to the documents that are at specific points on your
Timeline. You can choose to show only the documents that are Active, or you can expand the
display to include documents at other points.
Note: The Todo List does not refresh automatically. To refresh your list of assignments,
click the blue Refresh button .
The Todo List also lets you group your documents in different ways so that you can, for example,
quickly spot the documents that have the earliest due dates.
Note: If you are a project manager, your Todo List lets you view the document assignments
of all the people who are members of the projects that you manage. This lets you keep
tabs on how people are clearing their workloads, and perhaps do some strategic
reassignment of critical documents.
1. If necessary, show the Todo List.

The Todo List is one of the DITA CMS views, available from the Windows menu.
2. If you are a project manager, select the name of the person whose Todo List you want
to see from the List of personnel.
By default, the Todo List shows your own documents and their timelines. When you select
another person's name you are, in effect, looking at their Todo List.
3. Select the timelines of the documents you want to view.
You can choose any combination of the following:
• Incoming
• Active
• Retained
4. Select the way you want to Group your documents.

Your choices are:
• None - simply shows you an alphabetical list of all the documents you are responsible
for in any capacity.
• Page - groups your assignments by page.
• Role - groups your assignments according to the role you play in each: Editor or Author,
for example. Role names are configurable and may vary.
• Timeline - lets you group documents according to their position on your Timeline: Incoming
or Active, for example.
• Status - lets you group documents according to the status of the document. For example,
Authoring:work or Authoring:review.
• Due Date - groups documents by the date they are due.
• Object type - lets you group documents according to their type. For example, concept
or topic or task etc.
The Todo List displays the requested set of documents.

Related Links
Show views on page 68
Add comments to DITA CMS assignments

This topic describes how to add comments while assigning documents to the users.
User roles must already have been configured for each type of document.
To add comments in assignments:

documents.
2. Select Assign to... from the menu.
The Assignments dialog appears.
3. Go to the right pane.
The right pane displays the selected documents, grouped under the user roles that are
responsible for them. For example:
4. Right-click a document and then select Edit Comment.

You can select multiple documents under each role by holding down CTRL or SHIFT and
clicking the documents.
A Comment window appears. For example:
5. Enter a comment and click OK.

The comment appears in the Comment column.
6. (Optional) If you need to clear the comment from a document, right-click and then
select Clear Comment from the menu.
7. Repeat for each document, as required.
To view the comments, go to Todo list/jobs and then right-click RoleComments. The documents
and their comments will be displayed in the Todo list.
Note: The RoleComments displays all the comments assigned to a document, irrespective
of the configured roles. For example, if a document is assigned (with comments) to a
writer/author, and the same document is assigned (with different comments) to a reviewer,
the RoleComments will display both comments made on the document.
18 Document labels
Document labels
Topics: Document labels let you apply additional information to any

• Add a label category document in the repository.
• Assign labels to documents You can apply labels to any type of document.
• Remove labels from
documents Labels are indexed by the CMS; you can see the labels
• Manage document labels applied to a specific document when the Labels column is
displayed in the DITA Map view or Search Results. If a
document has been assigned more than one label then the
different labels will all appear, separated by semicolons.
You can search for specific labels using the Advanced Search.
Add a label category

The labels you assign to documents must be organized into categories. So before you can add
a label, you must first create label categories.
1. On the DITA CMS toolbar, click the Configure Labels button.

Tip: You can also configure labels and categories on the fly, when you're assigning
labels to documents.
The Configure Labels dialog appears.
2. Right-click anywhere within the dialog and select Add Category.
Your new untitled category appears in the dialog.
3. Double-click the category name (untitled) to select it.
4. Type in the name and press Enter.

Category names must be unique.
You can now add labels to your new category.
5. Click OK.
Your changes are saved, and will be available the next time you assign labels.
Document labels 315
Assign labels to documents

This procedure lets you apply additional information to any document in the repository.
You can apply labels to several documents at the same time, if you wish. Or you can apply several
labels to one document, if it's appropriate.
Labels are grouped by category. The selections you see depend on your system's configuration.
Labels are indexed by the CMS; you can see the labels applied to a specific document when the
Labels column is displayed in the DITA Map view or Search Results. If a document has been
assigned more than one label then the different labels will all appear, separated by semicolons.
Note: You can also use the Assign Labels dialog to remove labels from documents.
You can search for labels using the Advanced Search feature.
1. Select the documents you want to label.

You can select one or more documents from the DITA Map view, Search Results view, or
your Todo List.
2. Right-click and select Assign Labels...
The Assign Labels dialog appears.
3. (Optional) Click Manage Categories and Labels to change the text or to add or delete
the labels and categories that appear here.
If you don't have the required user privileges, this checkbox will be disabled.
Your changed labels and categories will be saved to the repository when you click OK. If you
want to discard changes, click Cancel.
The changes you make will not affect existing document labels unless you selected files
before you opened the Assign Labels dialog.
Tip: If you have selected some documents and then delete their labels, these labels
are automatically removed from the documents.
4. Expand a category node.
You'll see the available labels.
5. Expand a label node.
You'll see the documents you selected for labeling.
6. Click the documents that you want to apply the label to.
7. Open other categories and labels as required until all documents are assigned the
appropriate labels.
8. Click OK.
Remove labels from documents

This procedure lets you remove labels from documents in the repository.
1. Select the documents whose labels you want to remove.
You can select one or more documents from the DITA Map view, Search Results view, or
your Todo List.
2. Right-click and select Assign Labels...
The Assign Labels dialog appears.
3. If necessary, expand the categories and label items.
You'll see the documents you selected.
4. Click the documents from which you want to remove the label.
5. Click OK.
The next time you search, you'll see that the labels have been removed from the documents.
Document labels 317
Manage document labels

If you have the required user privileges, you can change the text of any category or label. You
can also add or delete the categories, as well as the labels they contain.
To manage document labels, you use the Configure Labels button ( ), available on the main
toolbar.
You can also manage labels on the fly, when you assign labels to documents using the Assign
Labels right-click menu option.
Rename labels and categories

You can change the text of a label or a category.
When you change a label's text, all documents that are currently being edited and have this label
will have their labels updated.
Note: This does not affect the labels on documents that are not open. These documents
will retain the original label.
1. On the DITA CMS toolbar, click the Configure Labels button ( ).

labels to documents using the Assign Labels right-click menu option.
2. Double-click the category or label name to select it.
3. Type in the new name and press Enter.
Category and label names must be unique.
4. Click OK.
Your changes are saved and will be available the next time you assign labels.
Delete labels and categories

You can delete individual labels or an entire category and all the labels that it contains. If you
delete all the labels within a category, then the category is also deleted automatically.
When you delete a label from the Configure Labels dialog, it is not removed from documents.
You can, however, simultaneously delete labels and remove them from the Assign Labels dialog.
If you delete labels without removing them from documents, then the next time you select these
documents when you are assigning labels, you'll see a category called "Undefined Labels" at the
bottom of the Assign Labels dialog. You can remove the labels from the documents at this time.

2. Right-click the label or category that you want to eliminate and select the appropriate
action:
• Delete Category
• Delete Label
The selected label or the category together with all its labels will disappear from the Configure
Labels dialog.
3. Click OK.
Your changes are saved and will be visible the next time you assign labels.
Add a label to a category

Labels are organized into categories. If you want to add a category or change the name of an
existing category, you must have the appropriate user access rights.
To add a label to a category:

2. Right-click a category and select Add Label.
Your new untitled label appears below the selected category.
3. Double-click the label name (untitled) to select it.
Document labels 319
4. Type in the name and press Enter.

Label names must be unique.
5. Click OK.
Your changes are saved and will be available the next time you assign labels.
19 Collaborative Reviewer
Collaborative Reviewer
Topics: Reviewers can make comments directly on PDF versions of

• About the Collaborative topics, images, and maps during the review process.
Reviewer When files reach the review stage, users with the proper
• Working with annotations
access rights can view PDF versions of topics, images, and
maps, and mark these up with their comments.
The Collaborative Reviewer is available in two versions:
• An Eclipse-based version – This version is available within

the DITA Perspective. It can be used by editors and subject
matter experts to review documents and by authors to
respond to their reviewers' comments.
• A web-based version – This version allows users to access
just the reviewing functionality of DITA CMS, without having
to install Eclipse. Details of this application are available
from its Help menu.
About the Collaborative Reviewer

The Collaborative Reviewer contains a variety of markup tools and is associated with the Votes
and Annotations view.
The review files open in a special PDF editor in the same area of the DITA Perspective where
XML editors appear.
A variety of annotation and markup tools are supplied: virtual sticky notes, highlights, and
underlines, even a set of proofreader's marks.
Several users can review a file at the same time. The annotations and markup are pushed onto
the server whenever the reviewer saves the file and become visible to other reviewers when they
re-open the file.
While a user is reviewing a file, the Collaborative Reviewer creates a temporary file for it on the
local disk. If the connection to the DITA CMS is lost before the review file is saved back to the
server, the temporary file preserves the changes until the connection is reestablished. When the
connection is reestablished and a temporary file is found for a user's assignment, the assignment
is marked as modified, the changes are restored to the review file, and then the user can save
the changes to DITA CMS.
Annotations view
Many of the annotations allow for additional comments to be attached. These reviewer comments
also appear in the Annotations view. Authors or Graphic Designers (or whoever is responsible
for the file) can revise these comments after the file is returned to them and respond to the
suggestions.
DITA CMS maintains successive copies of PDF review files, which may also be accessed from
the Annotations view.
Votes view
Reviewers who have been officially assigned to the file can vote on whether to accept or reject
it using the Votes view. This view also shows the approval system in effect for the current document
and how each of the reviewers has voted.
Collaborative Reviewer 323
Review content
You can annotate a PDF copy of a topic, map, or image.
The file must be in a reviewable state. The actual state depends on your workflow, but it
can be something like "review", "edit review", etc.
Several users can review a file at the same time. The annotations and markup are pushed onto
the server whenever the reviewer saves the file and become visible to other reviewers when they
refresh the current document or (if they're using the Web Reviewer) when they refresh the
Assignments table.
If your company is using XMetaL or Oxygen and change tracking is enabled, you'll see change
indicators in the PDF review file.
Note: There is no provision for conditional output in DITA CMS, as it's installed. All text
is output to the PDF, regardless of conditional attributes.
1. Right-click the file and select Collaborative Reviewer > Review from the menu.
You can select several files by holding down CTRL or SHIFT and clicking the files.
The review file opens in the PDF editor. The Annotations and Votes views also open.
2. Review the file using the annotation tools on the PDF editor's tool bar or the
proofreader's marks at the bottom of the editor.
If you draw a shape while you're reviewing and save without entering text, the review tool will
put a default comment ("No comment") into the Annotations view.
3. Save your comments as you would with any other file: for example, using the CTRL+S
shortcut.
Saving periodically while you review makes your comments visible to anyone else who is
concurrently reviewing the file.
After the file has been reviewed, assigned reviewers vote on whether to accept or reject
it. If it is accepted, the system promotes the file to the next state. If the file is rejected, the
system demotes it back to the previous state.
Refresh the current document

A button in the Reviewer's toolbar lets you know when other reviewers have saved annotations
to the server.
When you're reviewing a document, it's useful to know if other reviewers' comments have been
saved to the server, so that you can update and get a sense of what the others are saying.
When new annotations to the current document are available on the server, you'll see an
exclamation mark in the Refresh button.
To refresh the current document:
• Click the Refresh button ( ).
The new annotations appear in the document you're reviewing.

Attach a file to a review PDF

You can attach files on your system directly to the PDF that you're reviewing.
You may find that you'd like to clarify a point in your review by referring to a document of some
sort: a functional spec, for example. You can use this utility to attach the file directly to the review
PDF, for the convenience of the other reviewers and the author.
1. In the Collaborative Reviewer toolbar, click the Attach a file button ( ).

The cursor becomes a cross-hair.
2. Click anywhere in the PDF.
3. Browse for the file you want to attach, then click Open.
The File Attachment Properties dialog appears.
4. (Optional) Select the Icon and Transparency.
5. Click OK.
The icon denoting your file attachment will appear in the review PDF.
You can double-click the attachment icon to open the file.
Your file can now be opened by other reviewers and by the person who revises the
annotations.
Vote on a document
This is how you vote to accept or reject a document that's in review.
• The file must be in a reviewable state. The actual state depends on your workflow, but it can
be something like "review", "edit review", etc.
• You must be one of the assigned reviewers.
When reviewers have finished annotating the PDF review copy, they may vote to accept or reject
it. Anyone who has a reviewing role can review and add comments to a document, but only the
reviewers assigned to a particular document can vote on it.
The approval system is set by the project coordinator when the file is assigned and may be
changed at any time until a vote has been cast. Once someone has voted on a document, the
system remains in place until the next time the document is reviewed.
Voting concludes whenever the criteria for the document's approval system are met. If voting
concludes on a particular file before you've reviewed it (for example, the approval system is a
simple majority, and three of your other five reviewers have already accepted the file) the vote
option won't be available.
If voting concludes while you have the file open, however, you can still make comments on the
PDF review file and save them. But once you save and close the file, you won't be able to access
it again.
To vote on a document:
2. In the Votes view, click the appropriate button:
• Accept or
• Reject
Note: If you have not made any annotations in the document, your only choice will
be Accept.
Your name and choice are displayed in the Votes view.
If the file is accepted, the system promotes it to the next state. If the file is rejected, the system
demotes it back to the previous state.
Revise annotations
You can view the comments that reviewers have left in a PDF reviewing copy and revise the
annotations as you work on the corresponding topics.
The file must be in the work state (or its equivalent in your workflow).
After content has been reviewed, the people responsible for its production – Authors or Graphic
Designers, for example – can revise the annotations as they work on the corresponding files.
1. Right-click the topic and select Collaborative Reviewer > Revise Annotations from the
menu.
documents.
The review file opens in the PDF editor. The Annotations and Votes views also open. You
may want to open the corresponding XML file so that you can make the suggested changes
as you review the annotated version.
2. Right-click the annotation you want to revise and select a Resolution from the menu.
You can select several annotations by holding down CTRL or SHIFT and clicking the
annotations.
Note: If you select Declined, the Resolution Comment dialog will appear, and you
will need to enter an explanation for your action before you can continue.Your comment
will be displayed in the Annotations view.
When you've finished revising the annotations, the file will be in a reviewable state. The
actual state depends on your workflow, but it can be something like "review", "edit review",
etc.
View previous reviews

This procedure lets you view earlier versions of a PDF review file.
DITA CMS maintains successive copies of PDF review files. After an author has revised the
annotations in a PDF review file (and made the requested changes), he or she will promote the
file to the appropriate review state so that reviewers can generate a new PDF for their review.
Previous review files are not overwritten, however, and these may be accessed from the
Annotations view. These earlier review files are read-only and can be neither annotated nor voted
on.
Note: A new review copy is only generated if the XML file has been changed. If the XML
file has not been altered—all comments were resolved without any text changes, for
example—the PDF review file will not be regenerated. Only the Resolutions in the
Annotations view will be changed.
1. Use Search to display the topic, image or map in the Search Results view or scroll to
find a topic in the DITA Map.
2. Right-click the file and select either:
• Collaborative Reviewer > Review or

• Collaborative Reviewer > Revise Annotations
3. In the Annotations view, click the arrow next to the Older versions button then select
the required date.
The selected PDF review version opens in the Collaborative Reviewer.
Electronically sign a document

This procedure lets you affix an electronic signature to a completed document.
Your electronic signature file must be present in the appropriate directory of the repository.
In regulated environments, an electronic signature may be required in order for a document to

complete the Authoring cycle.
The review file opens in the PDF editor.
2. In the Reviewer's toolbar, click the signature button.

If you have never signed a document before, you will be prompted to upload your signature
file.
3. Your signature will be added to the signature page for the document.
If you are the first person to sign, your signature will create the signature page.
Working with annotations

Most of the annotations and markup tools are intuitive and easy to use. Simply drag them into
the desired spot, and then resize as required. If necessary, you might change the properties to
add some text or adjust the transparency.
There are a few that require a bit of explanation, however, and this section deals with them.
About the annotations’ right-click menu

The annotations are supplied with a right-click menu, some of whose options – like Properties –
allow you to modify the markup and add or change associated text.
Others, however, are not operational. Mark with Checkmark and all of the options under Review
have no effect on the annotations you make in the PDF review file.
One option however – Flatten – will merge the markup symbol into the review file so that it can’t
be removed. It's a way of a producing a read-only annotation. Unfortunately, it also removes your
review comments from the Annotations view (or from the Comments Pane, if you're using the
Web Reviewer) so it's up to you whether it's worth the trade-off.
Modify annotations
This procedure modifies PDF review file comments.
Use this procedure if you want to modify the comments you've made in a PDF review file. You
can also change annotation properties such as Line Width, Transparency, Fill Color, etc.
1. In the PDF editor, click the Exit Selection Mode button ( ).

The cursor becomes a hand.
2. Right-click the annotation and select Properties from the menu.
The Properties dialog for the annotation appears. The Sticky Note Properties dialog is
shown below.
3. Modify the text of the comment as required.

You can also modify other annotation properties.
Note: The Open Initially property of the Sticky Note annotation has no effect when
selected.
4. Click Save.
Copy annotations
This procedure lets you copy the information displayed in the Annotations view.
You can copy one or several reviewer comments from the Annotations view and paste them into
other applications. The columns within each comment are tab-delimited for easy pasting into any
worksheet application.
1. Use Search to display the topic, image, or map in the Search Results view or scroll to

3. In the Annotations view, right-click the annotation and select Copy Annotation.
Tip: You can select several annotations by holding down CTRL or SHIFT and clicking
the annotations.
The selected annotation (or annotations) is copied to the system clipboard.
Move or resize annotations

This procedure moves or resizes comments in PDF review files.
You can move any annotation except the Text Markup tools (Highlight, Strikethrough, Straight
and Squiggly Underline).

2. Click the annotation.
If the annotation can be resized, sizing handles appear at its edges.
3. Move or resize the annotation as required.
Tip: If you've minimized an annotation so that it becomes invisible, you'll be able to
find it if you increase the page size.
Delete annotations
This procedure deletes PDF review file annotations.

2. Right-click the annotation.
3. Select Delete from the menu.
The annotation is removed from the PDF file and from the Annotations view.
Hide annotations
This procedure lets you select the annotations you want to display.
Whether you are reviewing a document or revising your reviewers' comments, you have the
option of hiding selected annotations. You can choose to hide specific comments or all of a
particular reviewer's comments (including your own).
1. Use Search to display the topic, image, or map in the Search Results view or scroll to

3. In the Annotations view, deselect the comments you want to hide.
De-selecting the checkbox next to a reviewer's name hides all their comments. You can
display them all again simply by re-selecting the checkbox.
Insert a new See-note

You can insert notes that refer to several designated places in the reviewed document.
Sometimes, when you're reviewing a document, you'll want to make essentially the same note
in several different places. For example, you've noticed that a product name has changed, and
you'd like to draw attention to all the different places where this same correction needs to be
made.
This annotation lets you insert an initial See-note ("See 1", for example) as the initial annotation.
You'll then insert the number "1" wherever the note applies.
1. In the Reviewer's toolbar, click the See-note button.

The cursor becomes a transparent See-note.
2. Click where you want to put the See-note.

The Rubber Stamp Properties dialog appears.
3. (Optional) Type in text, adjust the transparency, etc., as required.
4. Click OK.
The See-note appears in the PDF file.
You should now insert the See-note number.
Insert See-note number

The See-note number indicates all the places where a See-note applies.
Your original See-note annotation must be inserted in the review PDF.
Once you've inserted a See-note (such as "See 3"), you'll want to indicate the places in the text
where your comment applies.
1. Click the drop-down list next to the See-note button.

You can see the numbers that correspond to all the See-notes that have been inserted into
the PDF review file.
2. Click the number you want inserted.
This number will be displayed at the top of the list.
3. Click the number at the top of the list.
The cursor becomes a transparent See-note number.
4. Click where you want to put the See-note number.

The Rubber Stamp Properties dialog appears.
5. (Optional) Type in text, adjust the transparency, etc. as required.
6. Click OK.
The See-note number appears in the PDF file.You can resize and reposition it as you need.
20 Profiling and conditional
processing
Profiling and conditional processing
Topics: Conditional attributes let you tailor the same document for
• About conditional attributes different audiences and products.
• About conditional topics DITA CMS supports the DITA attributes that let you hide
• Set conditional text portions of text—or even entire topics—that don't apply to a
attributes in the oXygen
specific audience or product. This lets you make
editor
• Preview a topic comparatively minor edits to a single document, instead of
• Using Ditaval files for producing multiple documents.
conditional processing
About conditional attributes

Conditional attributes let you tailor the same document for different audiences and products.
DITA CMS supports the DITA attributes that let you hide portions of text—or even entire
topics—that don't apply to a specific audience or product.This lets you make comparatively minor
edits to a single document, instead of producing multiple documents.
As of writing (DITA 1.2), the supported conditional attributes are:
• audience
• product
• platform
• rev
• props
• otherprops
Almost all DITA elements support conditional attributes. If you're using a text editor, you can
simply enter them as you would enter any other attribute. DITA CMS records the attribute values
that you enter. These same values are presented as choices during output generation.
Preview conditional text
Once you have tagged topic elements with conditional attributes you can use the Preview view
to see how these elements will appear in your topic.
Related Links
Generate output on page 563
Preview a topic on page 206
About conditional topics

You can make entire topics and their children conditional, as well as the reltables that refer to
them.
There are a few points to keep in mind when you make a topic conditional.
• If the topic has any children, then the condition will apply to all its children as well. You don't
need to apply conditions to every topic in the sub-tree.
• If you conditionalize a topic, then every reference in the map file must be conditional as well.
Profiling and conditional processing 339
For example, if you've made a concept topic conditional for Linux, as shown below:
<concept id="per1245699224969" platform="Linux" xml:lang="eng">
then all the corresponding <topicref> statements in the map file must also be conditional
as well:
<topicref href="per1245699224969.xml" platform="Linux">
And you must do the same for every reltable reference to this topic, as well.
Note: It is considered good practice to use top level conditions on topicrefs instead of
the topic root element. If information needs to be kept concerning the audience or
product of the topic, using the prolog is the preferred method.
Fortunately, the CMS includes several utilities that give you a more intuitive interface for applying
these conditions and for identifying the objects to which they have been applied.
Set conditions on objects in a map

You can apply conditions to topics and relationship tables in a map.
The set conditions functionality lets you select one or more documents—topics and/or
sub-maps—and then apply the conditions that you require. You can also apply conditions to the
relationship tables in your maps.
This functionality is available in DITA Map view and DITA Map Editor.
1. Lock the map.

2. Select the objects to which you want to apply a condition and click the Set conditions
button ( ).
The Set Conditions dialog appears.You’ll see all the conditions that are currently configured
in the CMS, grouped by attribute.
Note: If you need a condition that is not listed in the Set conditions dialog, contact
your CMS administrator. The procedure to configure conditions is described in the
DITA CMS Administrator's Guide.
3. Set the conditions that you want to apply and click OK.
Identify all conditional objects in a map

If your map has many conditional topic references, you may find it difficult to remember which
ones have conditions applied to them. This functionality lets you identify the topics and relationship
tables that are conditional.
1. In the DITA Map view or DITA Map Editor, click the Show Conditions button ( ).
The Show Conditions dialog appears.
2. Select the Show all conditions checkbox.
3. Click OK.
All the conditions that are currently applied to topics or relationship tables are highlighted
in yellow.
For example, the following diagram shows that two chapters have conditions in the map:
To see which conditions are applied to each topic, hover your cursor over the topic.
Review conditional values on a map object

You can easily see the conditional values assigned to topics and relationship tables in a map.
• In the DITA Map view or DITA Map Editor, hover your cursor over a topic or relationship
table.
The tooltip displays the condition(s).
Preview which topics are included in a map with conditions

You can use the Show Conditions feature to preview which topics are included in a map when
you specify certain conditions. This can give you an idea of the topics that would be included
when you generate the output of a map.
Note: This feature applies to topic-level conditions, and it shows the topics that would be
included in a map when one or more conditions are applied. It does not apply to conditions
that are set inside a topic.
To preview which topics are included in a map when conditions are set:
1. In the DITA Map view or DITA Map Editor, click the Show Conditions button ( ).
The Show Conditions dialog appears.
Note: If the Show all conditions checkbox is checked, uncheck it.
The list of conditions used at the map level are displayed. For example, the following diagram
shows that the linux and windows Platform conditions are used in this map.
2. Select the conditions to apply to your map.

For example, if you want to preview which topics will be included in your map if you apply the
windows Platform condition, select windows.
3. Click OK.
All the topics that would be excluded from the map are grayed out. For example, the
following diagram shows that one of the "Installing TEXTML Server" chapters would be
excluded from the map when the windows condition is selected:
Set conditional text attributes in the oXygen editor

You can set conditional text attributes to parts of a topic when working in the oXygen editor.
To set conditional text attributes in the oXygen editor:
1. In Author mode, select the text to which you want to apply a condition.
2. Right-click the text and select Edit Profiling Attributes.
The Edit Profiling Attributes window is displayed:
3. Select the conditions to apply and click OK.

The conditions are applied to the text.
Note: To see the conditions in the topic highlighted in colors, view the topic in Author
mode and enable Show Profiling Colors and Styles
Preview a topic
Use this procedure to see a WYSIWYG version of a topic.
When you select Show Preview for a topic, the Conditionals panel appears if your topic contains
conditional text. It shows the conditional attributes defined by the DITA specification, with check
boxes for each attribute value used in the current topic.
Here is an example of what a topic that contains conditional text looks like in the Preview window.
Use the check boxes to hide or display the portions of your topic that are tagged with these
attributes.
If you only have one condition in a topic, you’ll always see the conditional text displayed, whether
or not the corresponding check box is selected. If you really want to see what your topic looks
like without that single condition, create an alternate dummy condition and then select its check
box.
Note: The Preview view does not resolve conrefs or keyrefs, so you will not see that
content in the Preview. For example, if the conref is a <note>, you will see the “Note”
prefix because that comes from the display stylesheet, but you will not see the contents
of the note.
To preview a topic:
1. Locate the topic you want to preview.

• Open the topic to preview in your XML editor.

• Right-click the topic and select Show Preview.
• Hover over the topic.
Note: This opens a thumbnail view of the topic, not the Preview pane. This
functionality is not available from all views.
3. If you make changes to the topic in the XML editor, click the Preview pane Refresh
button ( ) or repeat one of the previous options to see your changes.
4. (Optional) If desired, click the Print button ( ) to print the contents of the Preview.
Related Links
Using Ditaval files for conditional processing

The DITA CMS offers an intuitive interface for creating and organizing Ditaval files.
If you are using conditional attributes extensively in your documentation, you should take
advantage of Ditaval files. These files specify the conditions to include and exclude when you
generate your output. They ensure that conditions are always applied consistently to generated
output.
For example, consider a documentation project with three conditions:
• Platform: Linux or Windows

• Audience: Sys_Admin or End_User
• Product: Product A or Product B
You could create one Ditaval file for each combination that you need to generate. For example,
the following code shows the Ditaval file for generating the Administration Guide for Product A
on Linux:
<val>
<prop action="exclude" att="audience" val="end_user"/>
<prop action="include" att="audience" val="sys_admin"/>
<prop action="include" att="platform" val="linux"/>
<prop action="exclude" att="platform" val="windows"/>
<prop action="include" att="product" val="Product A"/>
<prop action="exclude" att="product" val="Product B"/>
</val>
With the DITA CMS, you do not need to code the Ditaval file manually; you simply use the DITA
CMS Ditaval view to create the file. You then apply the Ditaval file that you need when you
generate the output for your maps. These procedures are described in the following topics.
Note: Before you create Ditavals, confirm with your DITA CMS administrator that they
are used by your transformation scenarios to generate output.
Create a Ditaval file

You use the DITA CMS Ditaval view to create conditional processing profiles for your documents.
Each profile that you create is stored in a .ditaval file.
A Ditaval file is created by specifying the conditions to exclude and to include when generating
the output for a document. By default, all conditions are included, which means that text that is
tagged with these conditions will be included in the generated output. To exclude a condition,
you must explicitly configure it as such in the Ditaval file. Any condition that is not explicitly
excluded is included in the output.
Note: This is the standard behavior of the DITA OT. It is not sufficient to simply specify
the conditions to include; you must also specify the conditions to exclude.
To create a Ditaval file:
1. To open the Ditaval view, select Window > Show View > Other > Ditaval and click OK.
The Ditaval view appears.
2. Right-click the folder where to add the Ditaval file and select New Ditaval.
The Create Ditaval dialog appears. It lists all the conditions that were created for your
company. For example:
Note: This dialog is customized per company. If the condition that you need to set in
your Ditaval is not available, ask your DITA CMS administrator to add it to the DITA
CMS configuration, as described in the DITA CMS Administrator's Guide.
3. Enter a title for this Ditaval file.
Note: This title is also used as the Ditaval file name. It must be unique.
4. (Optional) Enter a description.
5. To exclude a condition, click the check box for that condition and select exclude from
the Action list.
6. To include a condition, click the check box for that condition and select include from
the Action list.
This step is not necessary, since any condition not explicitly excluded is automatically included
in the output. However, for readability it is good practice to specify the conditions to include.
For example:
7. To include the content in the output and also retain the condition as part of the output,
click the check box for that condition and select passthrough from the Action list.
8. To include and mark the content in the output, click the check box for that condition
and select flag from the Action list. By default no formatting of the condition is applied.
Once the initial ditaval is created, you can edit the ditaval XML to add formatting
atrributes.
9. Click OK.
The new Ditaval file is created. You can now generate the output for a document using this
Ditaval file.
10. If you chose flag as an action for a condition, you can edit the ditaval to add the
formatting attributes.
a) Right-click the ditaval in the Ditaval view.
b) Click Edit Ditaval XML.
c) In the prop action="flag" element that you created, add and set the color,
backcolor, and style attributes as desired.
d) Once you have completed your changes, save the file.
e) Right-click the ditaval in the Ditaval view and click Release Ditaval XML.
Related Links
Generate output on page 563
Set a default value for actions in Ditaval files

You can specify a default include, exclude, passthrough, or flag action value for the conditions
in a Ditaval file.
The behavior of the DITA OT is to assume that if a condition is not specified in the Ditaval file,
then it is automatically included in the generated output. For example, consider a documentation
project with three conditions:
• Platform: Linux or Windows

• Audience: Sys_Admin or End_User
• Product: Product A or Product B
Now consider the following Ditaval file:

<val>
<prop action="exclude" att="audience" val="end_user"/>
<prop action="include" att="audience" val="sys_admin"/>
<prop action="include" att="platform" val="linux"/>
<prop action="exclude" att="platform" val="windows"/>
</val>
Because no action value (include or exclude) is specified for the Product condition, the DITA OT
assumes that both the Product A and Product B conditions should be included during the
transformation.
In previous releases of the DITA CMS, if you wanted to exclude some conditions, you had to
explicitly exclude each of them in the Create/Edit Ditaval dialog box. If your deployment includes
dozens of conditions, setting these values may take a long time.
The current release of the DITA CMS now lets you set a default include, exclude, or passthrough
action value for the conditions, as shown in the following diagram:
Using the sample dialog above, to generate documentation for Customer A on Windows for
Product 1, instead of explicitly excluding all the other conditions, you can now:
1. Check Default action and select exclude from the drop-down list.
2. Check the conditions for:
• Customer_A
• Windows
• Product_1
For example:
3. Click OK.
This dialog would create the following Ditaval file:

<val>
<prop action="exclude"/>
<prop action="include" att="audience" val="Customer_A"/>
<prop action="include" att="platform" val="windows"/>
<prop action="include" att="product" val="Product_1"/>
</val>
Create a Ditaval folder

If you have multiple Ditaval files, you can organize them into folders.
For example, you could organize your Ditaval files into admin and user guides, as shown below.
You can then drag and drop Ditaval files to the folders you created.
Note: You cannot drag and drop locked Ditaval files.
1. In the Ditaval view, right-click the folder where to create the new folder and select New
Ditaval Folder.
Select the Ditaval folder if there are no subfolders.
The New Ditaval Folder dialog appears.
2. Enter the name of the new folder and click OK.
Note: The folder name must be unique.
The new folder appears in the Ditaval view.
View a ditaval file

You can open the ditaval's XML file in the XML editor area to make it easier to read.
You cannot lock and edit the ditaval file in the XML editor using this feature.
To open the ditaval file in read-only mode:
1. To open the Ditaval view, select Window > Show View > Other > Ditaval and click OK.
The Ditaval view appears.
2. Right-click a ditaval file and click Open Ditaval XML.
The ditaval opens in the XML editor area.
Edit the XML contents of the Ditaval file

You can view and edit the XML contents of a Ditaval file if you prefer to update it manually.
Note: For more information about the XML structure of a Ditaval file, see the Dita
Specification documentation.
To edit the XML contents of a Ditaval file:
1. In the Ditaval view, right-click the file to edit and select Edit Ditaval XML.
A lock appears on the Ditaval file icon, indicating that you have checked out the file, as shown
below:
Note: If the Edit Ditaval XML option is greyed out, this means that the Ditaval file
was imported or created before this feature was implemented, and the file needs to
be converted to a new format. To solve this issue:
1. In the Ditaval view, right-click the file and select Edit Ditaval.
2. In the Title box, type a title for the ditaval.
3. Click OK (you don't have to modify the values).
4. The Edit Ditaval XML option is now available for the file.
The Ditaval is displayed in your Eclipse XML editor.

2. Update the file as necessary.
3. To save your changes, press CTRL+S.
4. To export the contents of the Ditaval file, select File > Save As and save the file locally
on your system.
5. To commit your changes, in the Ditaval view right-click the file and select Release
Ditaval XML.
If you do not want to keep the changes, in the Ditaval view right-click the file and select
Replace with Server Revision.
Review Ditaval values

Once you’ve created several Ditaval files, you may want to review the conditions to make sure
that they’re the ones you want to apply and to make sure you haven’t forgotten any.
To review Ditaval values:
• In the Ditaval view, hover your cursor over a Ditaval file.
The following diagram shows the conditions for the Product A System Admin Guide on
Linux Ditaval entry.
Edit a Ditaval file

You can add or remove conditions as needed from any Ditaval file using the Ditaval view.
To edit a Ditaval file:
1. In the Ditaval view, locate the file to update.

If necessary, expand the Ditaval folders. You'll see the Ditaval files contained in the folders.
2. Right-click the Ditaval file to edit and select Edit Ditaval.
The Edit Ditaval dialog appears.
3. Change any of the fields or values and click OK.
Filter the ditaval files in the Ditaval view

You can use a filter to reduce the number of ditaval files visible in the Ditaval view.
To filter the Ditaval view:
1. Open the Ditaval view.

2. In the Filter box at the bottom of the view, type the string that you want to use to narrow
the results shown in the view.
The filter uses the same search parameters as the Search for panel in the Search view.
Related Links
Delete a Ditaval file or folder

You can remove unnecessary items from the Ditaval view.
To delete a Ditaval file or folder:
1. In the Ditaval view, locate the file or folder to delete.

If necessary, expand the Ditaval folders.
2. Right-click the Ditaval file or folder to delete and select Delete.
The Delete Ditaval dialog appears, asking you to confirm.
3. Click OK.
The file or folder is deleted.
Copy the reference of a Ditaval file

You may need to know the location of the Ditaval file in the DITA CMS. This can be useful, for
example, if you have nightly scripts that must access the Ditaval files offline.
To copy the reference of a Ditaval file:
• In the Ditaval view, right-click the file and select Copy Ditaval Reference.
21 Snapshots
Snapshots
Topics: You can create snapshots of your working maps.

• Understanding the
Snapshots feature
• Create a snapshot
• Generate the output of a
snapshot
• Branch a snapshot
• Publish a snapshot
• View the contents of a
snapshot
Understanding the Snapshots feature

A snapshot is a DITA CMS object that captures a map at a particular point in time. You can use
this snapshot to rebuild the map and the objects that it contains—topics, images, referable content,
sub-maps, and so on—exactly as they were when the snapshot was created.
Note: The snapshot feature is slightly different for the Dynamic Release Management
module. See the Dynamic Release Management Module User Guide if you are using this
module.
When you create a snapshot for a map, the DITA CMS creates an .xml file that contains the list
of all the objects in the map (and sub-maps, if any) along with their current version numbers.
For example, consider the following map, which contains a topic and a sub-map:
<!DOCTYPE bookmap PUBLIC "-//IXIA//DTD IXIA DITA Map//EN" "IxiaMap.dtd">
<bookmap id="lar1397749975458" xml:lang="en-us">
<title>Sample map</title>
<chapter href="lar1397750021477.xml"/>
<chapter format="ditamap" href="lar1401202413026.ditamap"/>
</bookmap>
The following code shows the contents of the snapshot file for this map. The snapshot includes
the objects referenced in the topic (in this case, an image and referable content) as well as the
objects in the sub-map (in this case, a task that also includes an image).
<!DOCTYPE snapshot PUBLIC "-//IXIA//DTD IXIA DITA Snapshot//EN" "snapshot.dtd">

<snapshot id="lar1397749975458" xml:lang="en-us">
<title>Sample map--Snapshot</title>
<snapshotmeta>
<resourceid base="/content/authoring/" id="lar1397749975458.ditamap"/>
</snapshotmeta>
<manifest>
<snapshotref cms-status="Authoring:done"
href="../../authoring/lar1397749975458.ditamap"
navtitle="Sample map"
rev="4"
type="bookmap">

href="../../authoring/lar1397750021477.xml"
navtitle="Topic 1"
rev="3"
type="concept">
href="../../authoring/lar1397660192937.image"
navtitle="lock manager icon"
rev="1"
type="imagemeta"/>
Snapshots 359
navtitle="Contact Technical Support"
rev="3"
type="referable-content"/>
</snapshotref>

href="../../authoring/lar1401202413026.ditamap"
navtitle="Sample sub-map"
rev="3"
type="bookmap">
navtitle="Install Tomcat on Windows"
rev="3"
type="task">
ref="../../authoring/lar1397660191290.image"
navtitle="Apache Tomcat Configuration"
rev="1"
type="imagemeta"/>
</snapshotref>
</snapshotref>
</snapshotref>
</manifest>
</snapshot>

<!DOCTYPE snapshot PUBLIC "-//IXIA//DTD DITA CMS Snapshot//EN" "snapshot.dtd">
<snapshot id="ddp1441205293768" xml:lang="en-us">
<title>Sample map--Snapshot</title>
<snapshotmeta>
<resourceid base="/content/authoring/" id="ddp1441205293768.ditamap"/>
</snapshotmeta>
<manifest>
<snapshotref cms-status="Authoring:work"
href="../../authoring/ddp1441205293768.ditamap"
navtitle="Sample map"
rev="4"
type="bookmap">

<snapshotref cms-status="Authoring:open"
href="../../authoring/kiy1441205259960.ditamap"
navtitle="4.1.7"
rev="2"
type="container">
<snapshotref cms-status="Authoring:open"
href="../../authoring/klc1441205337071.ditamap"
navtitle="4.1.7 {0001}"
rev="5"
type="containerpart"/>
</snapshotref>


href="../../authoring/dsi1441206564020.ditamap"
navtitle="Reference Map"
rev="1"
type="map"/>

href="../../authoring/bhi1441205335829.xml"
navtitle="Topic 1"
rev="2"
type="concept">
href="../../authoring/klg1441214607797.image"
navtitle="lock manager icon"
rev="1"
type="imagemeta"/>
href="../../authoring/ive1441214836092.xml"
navtitle="Contact Technical Support"
rev="2"
type="referable-content"/>
</snapshotref>
</snapshotref>
</manifest>
</snapshot>
For each object in the map—that is, the map itself as well as all the objects that it contains: topics,
images, referable content, sub-maps (and their contents), etc.—the following information is kept:
• Status of the object

• Link to the object in the DITA CMS
• Navtitle
• Revision number
• Object type
This information allows the DITA CMS to recreate the map exactly as it was when the snapshot
was created. As with any DITA CMS object, you can search for a snapshot in the Content Store.
You can also output a snapshot, branch it, or publish it.
Important note
To create the snapshot, the DITA CMS uses the latest released revisions of the objects in the
map. Therefore, if you have locked documents in your map, the snapshot will not include these
locked revisions but rather the latest released revisions of these objects.
Why use snapshots?
In previous releases of the DITA CMS, if you wanted to keep track of the different versions of a
map, you had to publish the map. For example, if you wanted to be able to go back to all the
versions of all the maps that you delivered to your end users, you had to publish the maps at
each milestone. There are two main issues with publishing maps:
Snapshots 361
• You need to bring the map and its objects to the final state of the Authoring cycle (for example,
Authoring:done). This can be quite time-consuming for large maps.
• When you publish a map, the DITA CMS makes a copy of the map and all its objects and
stores them in the Content Store, so the size of the database keeps growing even if the volume
of source content is stable.
Creating a snapshot does not create copies of the map and its objects. It's simply a text file that
lists the map's contents at a specific point in time, so creating a snapshot has virtually no impact
on the Content Store. Another advantage of snapshots is that you can create a snapshot from a
map that is in any state, as long as the map is not locked.
When using snapshots, you can:
• Create a branch from a snapshot: Let's say that your team is still working on the
documentation for Version 10 of your product, but you need to start working on Version 11.
You can simply create a snapshot of the Version 10 documentation and then create a branch
from the snapshot. Since you can create the snapshot of a map from any state, the Version
10 documentation can remain in the Authoring:work status.
• Generate the output of a snapshot: At any time you can see the content of a snapshot by
generating its output. When you generate the output of a snapshot, the Output Generator
retrieves from the Content Store the versions of the map and its objects as specified by the
snapshot. New files are not created.
• Keep a historical record of all your documentation releases: Every time that you release
your documentation or at important milestones, you can make a snapshot of your map. This
ensures that you can see the content of a specific release at any time by generating its output
or return to it by branching the snapshot.
Note: While you cannot localize a snapshot directly, you can publish a snapshot and then
localize the published version.
Create a snapshot
When you create a snapshot, the DITA CMS creates an .xml file that contains the list of all the
objects in the map along with their version numbers.
Requirements
The map must not be locked, but the objects in the maps may be locked. When you create a
snapshot, the map and its objects can be in any state.
Important note
To create the snapshot, the DITA CMS uses the latest released revisions of the objects in the
map. Therefore, if you have locked documents in your map, the snapshot will not include these
locked revisions but rather the latest released revisions of these objects.
In the default configuration, when you create a snapshot, the snapshot object is in the
Authoring:review status (or the equivalent in your deployment).
You can create a snapshot from any view that lists the map (Search Results, DITA Map,
Dependencies, etc.).
To create a snapshot of a map:
1. In a view that lists the map, right-click the map and select Create snapshot.
The Create Snapshot window appears:
By default, the title of the map is used as the title of the snapshot.
2. If desired, modify the snapshot title in the Title field.
This might be useful to differentiate the snapshots for a map. For example, to indicate that a
snapshot identifies the version of the Web Author Installation Guide that was sent for technical
review, you could enter "Web Author Installation Guide - Tech Review".
3. In the Version field, specify the version for this snapshot.
If a branch is created from the snapshot, the branched map will automatically be assigned
the version of the snapshot.
Note: The version specified is the version of the snapshot and is not related to the product
version.
4. Click OK.
The snapshot is created. As with any DITA CMS object, you can search for a snapshot in the
Content Store. You can also output a snapshot, branch it, or publish it.
Snapshots 363
Generate the output of a snapshot

Just as with maps, you can output a snapshot using the Generate Output command.
When you generate the output of a snapshot, the Output Generator retrieves from the Content
Store the revisions of the map and its objects as specified by the snapshot.
You can generate the output of your snapshot in any format supported by the Output Generator.
To generate the output of a snapshot:
1. Use Search to find the snapshot you want to output.

2. Right-click the snapshot and select Generate Output.
3. Select the Output Format, specify required conditions and user fields (if any), and click
Create.
The Output Generator outputs the snapshot.

Note: The Output Generator does not create copies of the snapshot objects. Instead, it
simply retrieves the objects from the Content Store to create the output.
Branch a snapshot
When you branch a snapshot, the DITA CMS first publishes the snapshot and then creates a
branch from it. New, editable versions of the map and its objects are created in the Authoring
cycle and given the status Authoring:work (or its equivalent in your workflow).
Note: The snapshot must be in the Authoring:done status (or as configured for your
deployment) before you can branch it.
To branch a snapshot:
1. Use Search to find the snapshot you want to branch.

2. Right-click the snapshot and select Branch > Create new branch.
Note: If the Branch > Create new branch option is not available, make sure that the
snapshot is in the Authoring:done status.
The DITA CMS first publishes the map. The Branch Map dialog is then displayed.
3. Enter a tag for this branch and click OK.

The snapshot is branched and the branched map is displayed in the DITA Map view.
Publish a snapshot
When you publish a snapshot, the DITA CMS creates copies of the snapshot map and its objects
and puts them to the Publish:done status (or as configured for your deployment).
Note: The snapshot must be in the Authoring:done status (or as configured for your
deployment) before you can publish it.
To publish a snapshot:
1. Use Search to find the snapshot you want to publish.

2. Right-click the snapshot and select Publish.
Note: If the Publish option is not available, make sure that the snapshot is in the
Authoring:done status.
The Publishing Tags dialog appears.
3. Enter the required tag Value(s) and click Create.
The map and its object are created from the snapshot with the Publish:done status (or its
equivalent in your configuration).
View the contents of a snapshot

You can view the contents of a snapshot using the Show Preview command.
When you use the Show Preview command, the DITA CMS lists the objects in the snapshot, as
shown below:
Snapshots 365
To view the contents of a snapshot:
1. Use Search to find the snapshot to preview.

2. Right-click the snapshot and select Show Preview.
The preview of the snapshot is displayed.
22 Branching
Branching
Topics: Branching lets you create a new, editable version of a

• About branching previously published map.
• Branching indicators When you branch a map, you can modify portions of the map’s
• Create a new branch content without affecting the original published material.
• Branch sub-map(s)
• Branch topic(s)
• Branch documents
• Branch images
• Branch conrefs
• Branch resources
• Revert to published version
• Merge with authoring
• Mark as merged
About branching
When you branch a map and its components, the system creates new copies of all these
documents and automatically takes care of external references.
When a published map is branched, a copy of the map is created in the Authoring cycle and
given the status Authoring:work (or its equivalent in your workflow). Initially, the new map is
identical to the published map. The new map references the same published content as the
original map. The sub-maps, topics, and other content in the map remain in the published cycle.
If you want to modify the content of any of the documents within the branched map, you will have
to branch them as well. This includes all sub-maps and their children.
Modifying a document within a branched map
Once you have branched a map, you can branch the documents it contains (topics, sub-maps,
images, conrefs, etc.).
When a document is branched, a copy of the originally published document is created in the
Authoring cycle. This new document, with its own unique ID, can be edited in the same manner
as any other document in the Authoring cycle, without affecting the original published version of
the document.
Document references within a branched map
When you branch a document, the system automatically finds all topics and maps within the
branched map that reference the document and updates their references. If any topics or maps
containing a reference to the branched document are still in the Published cycle, then they are
automatically branched as well.
This does not affect documents from outside a branched map’s hierarchy. Such topics or maps
are left unchanged, and will continue to reference the original published version of the document.
You cannot branch a document unless it's in a state that permits branching, For example, if you
try to branch a document and the documents that reference it are locked by another user, then
the document cannot be branched. You'll have to wait until the documents are released in order
to proceed with the branching.
Branching a topic across multiple maps within the same branch

If multiple maps reference the same topic within a branch (that is, the maps have the same branch
tag), then when the topic is branched in the maps, the maps will use the same branched topic.
Branching 369
(In previous releases, a new copy of the topic was created every time a topic was branched, even
if the same topic was reused in multiple maps within the same branch).
For example, consider two maps, Map1 and Map2, which reference the same topic (Topic1).
Both Map1 and Map2 are branched using the tag Branch1. When Topic1 is branched in Map1,
a new version of Topic1 is created in Authoring, and the branched Map1 references this new
version. The branched Map2 still references the Topic1 in Published. When Topic1 is branched
in Map2, then both Map1 and Map2 reference the same branched topic in Authoring.
Branching indicators
The graphics that appear in branched maps help you keep track of the documents that have
changed.
When you create a new branch you are prompted for a tag, which the system applies to the new
map. As you branch the topics and sub-maps within this root map, they are also given this tag.
You can see branch tags wherever documents are displayed: Search Results, Todo List, etc
As you work on a branched map – changing the contents of topics, or adding new documents to
the map – you’ll notice asterisks in the Title column, whenever the map is open in the DITA map
view.This lets you quickly identify the documents that differ from their counterparts in the Authoring
cycle.
If at some point you merge the topics (or the entire map) back into the original version, then these
asterisks will be removed – if the merge is successful. However, if the original documents in the
Authoring cycle have changed, the system will not perform the merge. In this case the asterisks
will turn red, to alert you to this fact. You can remove the “needs merging” mark at a later date,
after you’ve merged the documents yourself.
Create a new branch

This procedure creates a copy of a published map in the Authoring cycle.
The map must be in the Published cycle.
When you create a new branch, the system creates a new version of a published map that you
can modify as you like. When a published map is branched, a copy of the map is created in the
Authoring cycle and given the status Authoring:work. This is the root map.
During the branching process you'll be prompted to enter a tag, which will be applied to the root
map and to all the documents which are subsequently branched within it, such as topics, images,
sub-maps, etc. You can use this tag to search the repository for all documents belonging to a
specific branch.
You can branch a map from Search view, your Todo List, or any other view where you can see
a map.
1. Right-click the map and select Branch > Create New Branch.
The Branch Map dialog appears.
2. (Optional) In the Tag field, enter an identifier for the branch you are creating.
The default tag is the version label of the published map. You can replace or modify this tag,
if you want.
3. Click OK.
Branching 371
The Progress Information dialog tells you that the map is being branched.
A copy of the published map with its own unique ID is created in the Authoring cycle, and
this new map opens in the DITA Map view. You'll see the tag that you assigned in the Title
column.
All documents that you want to modify in the map must now be branched.
Branch sub-map(s)
Once you have branched a parent (root) map, you can branch the subordinate maps that it
contains.
• The root map must be open in the DITA Map view.
• All referring documents must be in a state that allows them to be branched.
Use this procedure when you want to branch a map that's inside another map that you've already
branched. This option does not create a new branch; it branches the sub-map as a subordinate
document of the root map. A copy of the map file is created in the Authoring cycle and given the
tag of the root map.
A branched sub-map has the status Authoring:work (or its equivalent in your workflow).
You do not need to explicitly branch a sub-map if you branch any of the topics it contains, because
that action will cause the sub-map to be branched automatically. Otherwise, you must manually
select all the sub-maps you want to branch. If the map contains multiple levels of nested sub-maps,
you must open each map level to see and select all the sub-maps if you want to branch them.
You can also branch sub-maps, together with other topics within a map using the Branch
Documents option.
To branch a map:
• In the DITA Map view, right-click the sub-map and select Branch > Branch Map.
The Progress Information dialog tells you that the map is being branched.
A copy of the sub-map is created in the Authoring cycle and assigned the appropriate
status. A branched sub-map automatically receives the same tag as the parent map.
Branch topic(s)
Use this option to branch one or more topics within a branched map.
• All referring documents must be in a state that allows them also to be branched.
Once you have branched a map, you can go on to branch the topics that it contains. When you
branch a topic the system creates a new, editable version in the Authoring cycle and gives it the
status Authoring:work (or its equivalent in your workflow).
Note: If the topic is referenced by multiple maps in the same branch (that is, the maps
have the same branch tag), and the topic has already been branched in another map,
then a new copy of the topic is not created. Instead, the map will be updated to reference
the branched version of the topic. This ensures that a topic that was reused by multiple
maps before the branching operation continues to be reused by the maps within a branch.
During the branch operation, the system attempts to update all references within the map (xrefs,
rel-links, conrefs, etc.) to refer to the new copy of the topic. This requires that all the documents
that contain these references be branched as well. In addition, the system provides you with the
option of updating any other branched map that contains the topic with the new branched version.
If any of these referring topics is in a state that prevents its references from being updated – if a
topic is locked by another user, for example – then you'll get an error message, listing the maps
and topics that prevented the branch operation from being performed.
1. In the DITA Map view, right-click the topic(s) and select the applicable option:
• Branch > Branch Topic

• Branch > Branch Topics
documents.
If branching this document requires that other documents also be branched, the Branch
Documents dialog appears. It displays a list of the documents that will be affected by this
change and asks if you want to continue.
2. Click OK.
A copy of the published topic(s) is created in the Authoring cycle and assigned the
appropriate status. All branched topics automatically receive the same tag as the parent
map.
Branch documents
This option gives you a convenient method for branching several types of documents within a
root map simultaneously: topics and sub-maps together.
Branching 373
• All referring documents must be in a state which allows them to be branched.
Once you have branched a map, you can go on to branch the documents that it contains. When
you branch a topic the system creates a new, editable version in the Authoring cycle and gives
it the status Authoring:work (or its equivalent in your workflow). Sub-maps are given the status
Authoring:work (or its equivalent in your workflow).
During the branch operation, the system attempts to update all references within the map (xrefs,
rel-links, conrefs, etc.) to refer to the new copy of the document. This requires that all the
documents that contain these references be branched as well.
If any of these referring maps or topics is in a state that prevents its references from being updated
– if a topic is locked by another user, for example – then you'll get an error message, listing the
documents that prevented the branch operation from being performed.
1. In the DITA Map view, right-click the document(s) and select Branch > Branch
Documents.
documents.
If branching this document requires that other documents also be branched, the Branch
2. Click OK.
A copy of the published document (or documents) is created in the Authoring cycle and
assigned the appropriate status. All branched documents automatically receive the same
tag as the parent map.
Branch images
After you have branched a topic, you can go on to branch the images it contains.
• All documents referring to the image must be in a state that allows them to be branched.
• One parent topic containing the image must already have been branched.
When you branch an image the system creates a new, editable version in the Authoring cycle
and gives it the status Authoring:work (or its equivalent in your workflow).
1. In the DITA Map view, right-click the branched parent topic and select Branch > Branch
Referenced Images.
You can select several topics by holding down CTRL or SHIFT and clicking the topics.
The Branch Images dialog displays a list of the selected topic(s) and the images they contain.
2. Select any or all of the images.

3. Click OK.
If branching this image requires that other documents also be branched, the Branch
4. Click OK.
A copy of the published image (or images) is created in the Authoring cycle and assigned
Authoring:work status (or its equivalent in your workflow). All topics that contain that
image will be branched as well.
All branched images automatically receive the same tag as the parent map.
Branch conrefs
After you have branched a topic, you can choose to branch the conrefs used by that topic.
• All documents referring to the conref must be in a state that allows them to be branched.
• One parent topic containing the conref must already have been branched.
When you branch a conref the system creates a new, editable version in the Authoring cycle and
gives it the status Authoring:work (or its equivalent in your workflow).
1. In the DITA Map view, right-click the branched parent topic and select Branch > Branch
Conrefs.
Branching 375
You can select several topics by holding down CTRL or SHIFT and clicking the topics.
If branching this conref requires that other documents also be branched, the Branch
2. Click OK.
A copy of the published conref(s) is created in the Authoring cycle and assigned
Authoring:work status (or its equivalent in your workflow). All topics that contain that
conref will be branched as well.
All branched conrefs automatically receive the same tag as the parent map.
Branch resources
After you have branched a topic, you can go on to branch the resources it references.
• All documents referring to the resource must be in a state that allows them to be branched.
• One parent topic containing the resource must already have been branched.
When you branch a resource the system creates a new, editable version in the Authoring cycle
and gives it the status Authoring:work (or its equivalent in your workflow).
1. In the DITA Map view, right-click the parent topic and select Branch > Branch Referenced
Resources.
You can select several topics by holding down CTRL or SHIFT and clicking the documents.
The Branch Resources dialog displays a list of the selected topic(s) and the resources they
contain.
2. Select any or all of the resources.
3. Click OK.
If branching this resource requires that other documents also be branched, the Branch
4. Click OK.
A copy of the published resource (or resources) is created in the Authoring cycle and
assigned Authoring:work status (or its equivalent in your workflow). All topics that contain
that resource will be branched as well. All branched resources automatically receive the
same tag as the parent map.
Revert to published version

You can replace branched topics or sub-maps with the original published version
• All documents which refer to the document must be in a state that allows them to be locked.
When you're working with a branched map, you have the option of returning any of its branched
components to its counterpart in the original published version. When you do this, all references
(xrefs, related links, etc.) within the map are automatically updated to refer to the original document.
Any images and resources that these documents may reference are also reverted.
If the system contains no other references to the document that you're reverting then you are
offered the option of deleting the branched version.
Tip: If you want to review the differences between two documents before you revert them,
use the Compare With Published Source utility.
1. In the DITA Map view, right-click the document(s) and select Branch > Revert to
Published.
documents.
The Branch Documents dialog displays a list of the documents that will be affected by this
2. Click OK.
The branched map now refers to the published version of the document (or documents).
Merge with authoring

Use this procedure to replace original documents in the Authoring cycle with their branched
counterparts.
• The corresponding documents in the Authoring cycle must be in a state that allows them to
be locked.
After you've added some topics to a branched map for a while, you may decide that you want to
use it as the main line of documentation, instead of the original map. Or you may decide that you
want to replace some of the original topics with their branched counterparts.
Branching 377
The merge function lets you replace the contents of original documents in the Authoring cycle
with the contents of the branched map. All the demoting, locking, and copying is done automatically
by the system.
You can merge individual topics, which replaces the text in just these topics. Or you can merge
the entire map, which replaces the map file itself as well as the topics that have been changed;
all the images and resources that these topics reference will also be merged.
You cannot, however, merge a document if the corresponding document in the Authoring cycle
has been changed. In this case you'll need to perform the merge manually, i.e., lock the document
yourself, and paste in the changed text.
Tip: If you want to review the differences between two documents before you merge
them, use the Compare With Authoring Source utility.
1. In the DITA Map view, right-click the document(s) you want to merge and select Branch >
Merge With Authoring.
documents.
The Progress Information dialog tells you that the document(s) are being merged.
If any corresponding documents in the Authoring cycle have been changed, the Branch
Documents dialog will appear and display them. You will need to merge these documents
yourself, if you want, at a later date.
2. Click OK.
The asterisks that indicate a changed document disappear from the documents that are
successfully merged.
The content of the branched document(s) has now replaced the contents of the original
document(s) in the Authoring cycle, where possible. Replaced topics now are at
Authoring:work (or its equivalent in your workflow); replaced images will go to
Authoring:work (or its equivalent in your workflow) and the map (and any sub-maps) will
receive the status Authoring:work (or its equivalent in your workflow).
If the documents could not be merged – if the corresponding documents in Authoring had already
changed in some way – then the asterisks that indicate a changed document will turn red. You
can use the Mark As Merged feature to remove these, if you want.
Mark as merged
This option lets you manually remove the "needs merging" asterisks from documents that you
have merged by hand.
The root map must be open in the DITA Map view.
When you attempt to merge a branched document back into a document that has changed,
the system puts a red asterisk next to its title. This lets you know that the merge was
unsuccessful, and that if you want to merge the text you'll have to do it yourself.
After you've performed the merge yourself, you can use this procedure to remove the red asterisks.
To mark as merged:
• In the DITA Map view, right-click the document(s) and select Branch > Mark As Merged.
documents.
The Progress Information dialog tells you that the document(s) are being marked.
The red asterisks are removed from the selected documents.

23 Using conrefs and keyrefs
Using conrefs and keyrefs
Topics: The DITA CMS provides multiple features that allow you to
• Conref and keyref best easily reuse content.
practices
• Creating and using conrefs
• Keyrefs and keydefs
Conref and keyref best practices

The DITA CMS provides a topic specialization and a map template that let you store and organize
your reusable components.
You use the referable-content topic type to hold the text that you plan to reuse in other topics.
You then build libraries of referable-content topics using a referable_component_library map.
When creating reusable components and maps, IXIASOFT recommends that you follow these
best practices.
About reusable components
• Always use the referable-content topic type to store your reusable components. Otherwise,
they will not be searchable with the Referable-Content view.
• Ideally, keep each reusable component as small as possible and store them in a separate
referable-content topic. While this is not mandatory, it allows for a better organization of the
reusable components and will have less impact on your work flow. For example, if you plan
to reuse error messages, keep each error message in its own topic. This ensures that if you
need to update a single message, only the topics that refer to this message will be impacted
in your work flow (as opposed to storing all messages in a single topic, which would cause all
the objects that reference any error message in the topic to be impacted).
• Assign IDs to each referable piece of content. IDs should follow a pre-defined naming convention
for ease of use and standardization.You can also use the IDs that are automatically generated
when you release the referable-content topic. See the DITA CMS Administrator's Guide for
more information about configuring the DITA CMS to automatically generate IDs.
• Label your reusable components so that you can also find them using the Advanced Search.
Note: For small phrases such as product names or standard filepaths, IXIASOFT
recommends that you use keys instead of reusable components.
About reusable maps
• Organize your referable-content topics in a referable_component_library map.

• Maps are the key to organizing your reusable components so that you can find them easily.
Determine a strategy for organizing your maps; for example, you could organize your maps:
• By logical group: Create a map for error messages, a map for warnings, a map for labels,
etc.
• By product: Create a map for product A, a map for product B, etc.
Using conrefs and keyrefs 381
• You could also build a map from all reusable objects that share the same label.
About keys
Several ways are available for adding keys to maps; however, you may want to establish a list
of variables for use by the entire team rather than have each user define their own. To provide
this list of common or corporately-approved variables, the DITA CMS Administrator can configure
a list in the Content Store which can be made available for selection in the DITA Map view.
Creating and using conrefs

The Referable-Content view lets you search for reusable components and insert them into
documents.
What is a reusable component?
DITA CMS provides a topic specialization—the referable-content topic type—that you can use
to store the text you plan to use in multiple topics. In DITA CMS, a reusable component is an
element that is within the <rcbody> element and has an id attribute.
For example, consider the following referable-content topic:

<!DOCTYPE referable-content PUBLIC "-//IXIA//DTD IXIA DITA Composite//EN" "IxiaDitabase.dtd">
<referable-content id="per1389985725819" xml:lang="en-us">
<title>Configure Kerberos authentication on the client</title>
<rcbody>
<note id="kerberos_prerequisites">To use Kerberos authentication, the
client application and TEXTML Server must be running on Windows. Linux is not
supported.
</note>
</rcbody>
</referable-content>
The <note> with the kerberos_prerequisites id is considered a reusable component by the

DITA CMS. You can reuse these components in other topics using conrefs.
For example, to reuse the Kerberos prerequisites paragraph in other topics, you create a conref
to this paragraph in the target topic, as shown below:
<note conref="per1389985725819.xml#per1389985725819/kerberos_prerequisites"/>
To easily find reusable components and insert conrefs to them into other topics, the DITA CMS
now provides the Referable-Content view.
Overview of the Referable-Content view
Once you have created reusable content components, you use the Referable-Content view to
search for these components and reuse them in other topics.
The following diagram shows an example of the Referable-Content view after a search:
The Referable-Content view provides the following information about the reusable components:
• Text Preview: Overview of the text that can be reused

• Element: Element type of the reusable component
• Element ID: ID assigned to the reusable component
• Owner Document: Name of the document that contains the reusable component
This information can help you select the component to reuse in your document. You can restrict
your search using the following criteria:
• Element type: This drop-down list displays all the elements for which a reusable component
is defined.You can search inside a specific element type or select All element types to search
inside all element types.
• Containing library: This drop-down list displays all the referable-component-library maps
found in the Content Store. You can search inside a specific map or select All libraries to
search inside all the maps.
Once you have found the text that you want to reuse, you can easily insert it into the target topic
using the Referable-Content view.
Create a reusable component (conref)

You store reusable components in a topic of type referable-content so that you can search for
them with the Referable-Content view and insert them into other topics.
The referable-content topic specialization is designed specifically to store reusable components.
You can then use the Referable-Content view to search reusable components and reuse them
in other topics.
Referable-content topics are created like any other topic. Simply select the specialized template
(referable-content.xml) when you create a topic.
The referable-content topic supports all valid DITA elements.
To create a reusable component:
1. Create a topic of type referable-content.

2. Open the referable-content topic in your XML editor.
3. Place your cursor inside the <rcbody> element.
4. Enter the text you want to reuse in other topics.
You can use any valid XML element. You could, for example, create the following note:
<note>To use Kerberos authentication, the client application and TEXTML Server
must be running on Windows. Linux is not supported.
</note>
5. In the opening tag of the source text, insert an ID attribute.
For example, you might use the string "kerberos_prerequisites", which would give you the
following code:
<note id="kerberos_prerequisites">To use Kerberos authentication, the
client application and TEXTML Server must be running on Windows. Linux is not
supported.
</note>
Note: The DITA CMS will automatically insert an ID to any element that is a direct
child of <rcbody> when you release the topic. If you prefer, you can use these
automatic IDs instead of inserting your own.
6. Save and release the referable-content topic.
7. Add the topic to a referable component library map.
You can now use the Referable-Content view to search for the reusable content and add it to
your topics.
Create a referable_component_library map

IXIASOFT recommends that you organize your referable-content topics into a
referable_component_library map.
A referable_component_library map is a map that includes the <data
name="referable_component_library"/> element. For example, the following code shows
a sample referable_component_library map:
<map id="lar1399918386572" xml:lang="en-us">
<title>ACME Referable Content Map</title>
<data name="referable_component_library"/>
<topicref href="lar1398347925155.xml" keys="lar1398347925155"/>
</map>
Note: The DITA CMS provides a referable_component_library template that you can use
to create your referable component library maps. But you can also use any other type of
map, as long as you add the following element in the map:
<data name="referable_component_library"/>
To create a referable content map:
• Press CTRL+ALT+M.
• On the Document Creation toolbar, click the Create Map button ( ).

• From the menu bar, select DITA CMS > Create Map.
The Create Map dialog appears. The ID field displays the system-assigned ID.
2. Enter a title in the Map Title field.
3. In the Map template area, select referable_component_library.ditamap.
4. Specify the other options as required and click Create.
5. Add your referable-content topics to the map.
Search for reusable components (conrefs)

The Referable-Content view displays the components that you can reuse in your documents.
To search for reusable components
1. To display the Referable-Content view, from the menu bar select Window > Show View >
Other.
The Show View window is displayed.
2. Expand DITA CMS - General, select Referable-Content, and click OK.
The Referable-Content view is displayed.
3. In the Search area, enter a search string.
You can use the standard Search wildcards to refine your search. If you don't enter a search
string, all available reusable components are returned.
4. To search within a specific element type, click the element types drop-down list and
select an element type.
This list displays the element types for which referable content is currently defined. To search
all element types, select All element types.
5. To search within a specific referable content map, click the libraries drop-down list
and select a map.
This list displays all the referable_component_library maps. These are the maps that contain
the <data name="referable_component_library"/> element. To search within all
referable_component_library maps, select All libraries.
6. Click Search.
The referable components that match the search criteria are listed in the search results area.
The search results area displays 20 results at a time. Use the page buttons to navigate through
your results if there are more than 20 results.
Tip: If you assigned labels to your reusable components, you can also use the Advanced
Search panel to search for reusable components with a specific label.
Insert a reusable component (conref) in oXygen

You can add a reusable component to a target topic in oXygen from the Referable-Component
view.
When you add a reusable component using the Referable-Component view, the DITA CMS
inserts a conref to the reusable component in the target topic.
To add a reusable component in oXygen:
1. Open the topic where you want to reuse text in your XML editor.
2. Place your cursor where you want to add the reusable component.
Make sure that your cursor is in a valid position for the type of element you want to insert.
For example, you cannot add a reusable component of type <step> in a topic of type concept.
3. Use the Referable-Content view to search for the component to reuse.
4. In the search results, right-click the reusable text and select oXygen Edit > Insert as
conref.
The reusable text is included in the document.
5. Save your target file.
Keyrefs and keydefs

DITA 1.2 has introduced the keyref feature, which allows you to use indirect addressing in places
such as xrefs and related-links.
The DITA CMS offers utilities to help you manage your keyrefs and keydefs.
About keyrefs and keydefs

DITA 1.2 has introduced the keyref feature, which allows you to use indirect addressing in places
such as xrefs and related-links.
Instead of referring to a topic directly by its file name, the link is made by means of a symbolic
name (keys=”some_name”).
For example, you might make an xref such as the following:

<xref keyref="locale">Import a localized map and its topics</xref>
The link to the target topic is made with the keyref attribute, instead of an href.
The target of this link is established in the map file by inserting the keys attribute into the
appropriate topic reference. You can see an example below.
<topicref href="dit1142432953484.xml" keys="locale"/>
Alternatively, you can use a <keydef> element. This allows you, among other things, to make
reference to topics outside the scope of the current map, without making them visible in the
navigation markup or generating CMS error messages during status changes.
<keydef href="dit1142432953484.xml" keys="locale"/>
You can find many concrete example of other uses for keyrefs and keydefs in the feature article
produced by the OASIS DITA Adoption Committee, available at the following URL:
http://dita.xml.org/resource/keyref-overview-dita-12
Table 5: DITA CMS keyrefs
Icon Description
Unresolved keyref.
Keyref resolved with an href.
Keyref resolved with a keyref.
Keyref resolved with a null link.
Automatically resolve keyrefs

This feature finds all unresolved keyrefs and creates corresponding keydef elements.
If you have made extensive use of keyref linking in your documentation project, it may become
difficult to keep track of the references.
DITA CMS offers a Resolve Keyrefs feature that detects all unresolved keyrefs in your document
deliverable (the map and its topics) and generates syntactically correct keydef statements to
define the corresponding keys.
The system also compares these keys to the file names of existing topics in the repository. For
those where there is a match, the CMS will automatically insert href attributes that link the keys
to the appropriate topics.
1. In DITA Map view or DITA Map Editor, click the Resolve Keyrefs button ( ).
If there are any unresolved keyrefs, the Add all undefined keys dialog appears.
• The Keyref Target Found panel - shows keyrefs that could be resolved by topics in the
Content Store.
• The Undefined Keyref panel - shows keyrefs that will need to be resolved manually.
2. Use the and buttons to move topics between the two panels.
• Use the button to move any of the entries in the Keyref target found panel into the
right-hand panel for manual resolution, if you'd rather use targets other than those that the
CMS automatically generates.
• Use the button if you change your mind and want to move these topics back into
the left-hand panel.
Note: You cannot move an entry from the Undefined Keyref panel unless its keyref
corresponds to the file name of a topic in the repository.
3. Click OK.
The system will write the appropriate <keydef> statements into the map file.
You will need to edit the keydef statements that were generated for the undefined keyrefs,
in order to resolve them.
Add keydef example

This topic shows an example of unresolved keyrefs and how the system would deal with them.
The image below shows the Add All Undefined Keys dialog when the system has found four
unresolved keyrefs.
Figure 56: The Add All Undefined Keys dialog

The left-hand panel (Keyref Target Found) shows that there are two keyrefs that could be
resolved by topics in the Content Store i.e., the keyref attribute value corresponds to an existing
topic's file name. You can see the topic titles displayed there.
The right-hand panel (Unresolved Keyrefs) shows two keyrefs that will need to be resolved
manually.
When you click OK, the system will write <keydef> elements into the map file to define the
missing keys. You can see how these example statements will appear in the DITA Map view, in
the image shown below.
Figure 57: Keydef statements in the DITA Map view
This image shows how the keydef elements display in the DITA map view. The entries from the
Keyref Target Found panel display with black icons. These entries have been automatically
resolved.
The entries that were in the Unresolved Keyref panel display with red icons. These keydef
statements will need to be manually resolved. See Edit keydef actions on page 392.
The code block below shows the underlying XML.

<keydef href="mal1311976516135.xml" keys="mal1311976516135"/>
<keydef href="mal1234494279734.xml" keys="mal1234494279734"/>
<keydef keys="mal6666666666666"/>
<keydef keys="foo" />
Add keys to a map from preset list defined in the Content Store
Although several ways are available for including keys in a map, the DITA CMS Administrator
may have defined a list of keywords and external links in a system configuration file, which you
can insert into your map.
Instead of the writers each defining their own keys, the preset list of keys provides a quick method
for adding keys to a map as well as encouraging consistency in key use across the topics in the
Content Store.
The Edit Variables dialog box displays the list of preset keys defined in the configuration file:
• The Default Values column lists the default values for the keys defined in the configuration
file.
• The Current Values column displays the values of the keys defined in the map.
If the value displayed in the Current Values column is different from the value in the Default
Value column, it means that the map and the configuration file have keys with the same name
but are defined with different values. If a key has the potential for multiple values as a result of
being defined in different places, the key definition highest in the map hierarchy prevails.
Figure 58: Example of the Edit Variables dialog box
To add preset keys to the map:
1. In the DITA Map view, open and lock the map to which you want to add the keys.
2. Right-click the map and click Edit Variables.
3. Select the checkboxes next to the keywords or external links that you want to add.
4. Click OK.
If you cannot see the keys in the DITA Map view, make sure the view is configured to display
the map elements.
Inserting a keyword or external link from keys defined in the map

You can insert a key into your content from the keys defined in the map.
The Insert Variable dialog box obtains its values from the keys defined in the map open in the
DITA Map view. Keys can be added to maps in several ways such as defining them directly in
the ditamap or including submaps containing keys. If a key has the potential for multiple values
as a result of being defined in different places, the key definition highest in the map hierarchy
prevails. This means if you have a map containing nested submaps and the submaps contain a
key defined with the same name but with different values, then the key value defined in the
topmost map in the hierarchy is the value used in the topics.
For example, Map A contains Map B and Map B contains Map C. A key named "product" is
defined in each map, but their values are not the same. In this case, the value defined for the
key in Map A is used. If the "product" key was defined in Map B and Map C but not in Map A,
then the value in Map B is used since it is higher in the map hierarchy than Map C.
When you click Insert variable from map, it inserts a keyword (<keyword
keyref="[value]"/>) at the location where you have placed your cursor. When you click
Insert external link from map, it inserts a link (<xref keyref="[value]"/>).
Restriction: Glossary keys are not available using this dialog box.
To insert the variable or link:
1. Place your cursor at the location where you want to insert the key.
2. Do one of the following depending on the type of key you want to insert:
• To insert a keyword, click the button from the main toolbar.
• To insert a link, click the button from the main toolbar.
3. In the Variable column, click the variable that you want to insert.To search for a variable,
type a relevant string of characters in the Filter results field.
Note: The variables are organized in the Insert Variable dialog box by the map in
which they are defined. If a variable is greyed out, it means it is defined in another
map higher in the map hierarchy.
4. Click OK.
Related Links
Display map elements on page 172
Edit keydef actions

These actions let you change or manually resolve <keydef> elements.
You can use this feature to change a keydef target or modify its action. This is also how you
manually resolve the keydef statements that the system generates for keys that have no
corresponding target in the repository.
Assign a hyperlink to a keydef

Edits the keydef statement so that it links directly to a topic, file or URL.
1. In the DITA Map view, right-click a keydef and select Edit Keydef Action.
The Edit Keydef dialog appears.
2. In the Links to... area, select href.
3. Enter the link target into the href entry field.
4. Select the scope as required.
• local – if the link refers to a document that is part of the current set of content.
• peer – this parameter’s behavior will vary according to your system’s configuration.
• If peer has been configured as equivalent to local, the CMS will perform all validation
and you’ll need to adhere to good CMS praxis when you make these links.
• Otherwise, the CMS performs no validation and it is up to the authors to ensure that
these links reference existing documents/locations.
• external – the resource is not part of the current information set and should open in a
new browser window.
The example below shows an href to an external link: google.ca.
5. Click OK.
The corresponding keydef element is written into the map file.
The code generated for the example dialog is shown below. The image that follows shows
the result in the DITA Map view.
<keydef href="http://www.google.ca/" keys="mal6666666666666" scope="external"/>
Assign a keyref to a keydef

This procedure shows how to edit the keydef statement so that it links to another key.
Use this option when you want to use another layer of indirection in your link.
2. In the Links to... area, select keyref.
3. Enter the link target into the keyref entry field.
The image below shows an example keyref link.
Note: If there is no corresponding keys="bar" attribute on any topicref in the map,

the keyref will not resolve.
4. Click OK.
The appropriate <keydef> element is written into the map file.
The code generated for the example dialog is shown below.

<keydef keyref="bar" keys="foo"/>
The following image shows the result in the DITA Map view after the map has been released.
Remove all links from a keydef

This procedure shows how to edit the keydef statement so that it links to nothing.
Use this option to disable a keyref without removing it from the map.
2. In the Links to... area, select nothing.
3. Click OK.
The appropriate <keydef> element is written into the map file.
The code generated for the example dialog is shown below. The image which follows
shows the result in the DITA Map view.
<keydef keys="mal1234494279734" linking="none"/>
Keydef representation in the DITA Map view and editor

The following table shows the icons that represent linked and unlinked keydefs.
Unresolved keyref.
Keyref resolved with an href.
Keyref resolved with a keyref.
Keyref resolved with a null link.

24 Import and export documents
Import and export documents
Topics: DITA CMS provides wizards that let you import valid DITA
• Importing content as documents into the TEXTML repository.
read-only You can import the following DITA documents:
• Import Ditaval files
• Import images • maps
• Import multiple resolution • topics
images • images
• Import maps
• Import topics You can import a document one at a time, or you can import
• Reimporting the same file in bulk. Any document you import is automatically assigned
into the DITA CMS to you and assigned the initial status (for example,
• Troubleshooting import Authoring:Draft). When you import a map or topic, the map
errors or topic and its dependencies (for example, the map, topics,
• Export content from the and images it refers to) are imported into the repository. If
DITA CMS
one of the document dependencies cannot be found (for
example, one of its topic is missing), the import is canceled
and an error message is displayed.
Advanced options also let you control how to handle

languages and other attributes as well as duplicate
documents.
Note: To import documents into DITA CMS, you must

be assigned the access rights to do so by the DITA
CMS Administrator.
Before importing documents

Before importing content into the DITA CMS, make sure that
the content is valid DITA. In particular, make sure that:
• All maps and topics use valid DITA

• All links and images are valid
Import and export documents 401
Importing content as read-only

You can import external documents into the DITA CMS and mark them as read-only.
This allows you to include content that is not developed by your company and should not be
modified, such as:
• Third-party documentation
• DITA content automatically generated from engineering databases
Once imported, you can use read-only content in your documentation. For example, you could
add a parts catalog provided by a third-party as an appendix to one of your document.
You can also reference content that was added as read-only. You can use any existing key
available in the read-only content.
When you import content as read-only, it is added to the DITA CMS Content Store but it follows
a different workflow than your documentation. The documents are put in the Authoring:readonly
status. You cannot change the status of the documents and you cannot update the content.
Related Links
Import Ditaval files

You can import Ditaval files in the DITA CMS.
These files must follow the standard Ditaval format defined in the Oasis standard. See the following
link for more information:
http://docs.oasis-open.org/dita/v1.2/os/spec/common/about-ditaval.html
When you import a Ditaval file, its file name is added to the object's metadata in the
originalFileName index and the path relative to its containing map is added to the object's
metadata in the originalRelativePath index.
Note: Any document you import is automatically assigned to you.
Specifying a Ditaval title and description

You can specify the Ditaval title and description inside processing instructions before importing
the Ditaval file. This ensures that a meaningful title and description are associated with this Ditaval
file.
To specify the title and description, add the following processing instructions to your Ditaval file
before importing it:
• ixiasoft.ditaval.title
• ixiasoft.ditaval.description
For example:

<?ixiasoft.ditaval.title Internal User Guide for Linux ?>
<?ixiasoft.ditaval.description Conditions for publishing the User Guide for Linux to an
internal audience ?><val>
<prop action="include" att="product"/>
<prop action="include" att="audience"/>
<prop action="include" att="rev"/>
<prop action="include" att="platform"/>
<prop action="exclude" att="audience" val="External"/>
<prop action="include" att="audience" val="Internal"/>
<prop action="include" att="platform" val="Linux"/>
</val>
Import options
You can specify the following options when importing Ditaval files:
Option Description
Update existing When it imports a document, the DITA CMS determines if this
documents document already exists by checking:
1. That a document exists in the repository with the same name as

the original file name of the imported document.
2. If a document with the same name exists, and the Use relative
path along with file name to match documents to update option
is selected, the DITA CMS also checks that the base path of the
imported document also matches the base path of the document
in the repository.
If a document already exists and the Update existing documents

option is selected, the existing document is updated with the contents
of the imported document. If this option is not selected, a new
document is created, with a new file name.
Option Description
Import options
Import Base Specifies the base path to use when replacing existing documents.
Path:
To import one or more Ditaval files:
1. Select File > Import.

The Import dialog appears.
2. Open the DITA CMS folder and select Import Ditaval.
3. Click Next.
The Import Ditaval(s) dialog appears.
4. Click Browse.
5. Navigate to the folder that contains the Ditaval file(s), select the file(s), and click Open.
The selected Ditaval file(s) appear in the Ditavals to import list.
6. To replace existing documents with the contents of the imported documents, select
the Update existing documents checkbox. To also use the relative path to match the
documents to update, select Use relative path along with file name to match documents
to update.
7. Click Next.
8. In the Import base path box, type the base path to use when replacing existing
documents.
9. Click Finish.
Import images
The Import Images wizard offers you a way to import images in bulk.
When you import an image, its file name is added to the object's metadata in the

Important: If you are importing the source file for the image and wish to retain its original
extension, make sure that its MIME type is listed in the mimetypes.xml configuration file.
If its MIME type is not listed in the configuration file, the extension will be converted to a
.bin extension. For example, if you are importing files such as Adobe Illustrator, edit the
mimetypes.xml file to include the .ai MIME type. Instructions for editing the mimetypes.xml
file are available in the DITA CMS Administrator's Guide available on the IXIASOFT web
site.
You can specify the following options when importing images:
Option Description
Import As External When you import the document, it and its children (if any) are imported
into the repository and assigned the Authoring:readonly status.

in the repository.

Option Description
Note that, to be updated, the document:
• Must be in a lockable state (for example Authoring:Draft) unless it

is an existing external document (Authoring:readonly).
• Must not be already locked by another user
When you re-import an external document, this option is always

enabled and the existing document and its children (if any) are always
updated.
Default language All documents in the DITA CMS must have a designated language.
If the documents you are importing do not have a language attribute,
the system will assign them the language you select from this list. If
the document you are importing has children, this language will also
be assigned to these children.
You can also set the Override unknown languages with default
option. If you select this option, when you import documents that
reference a language that’s not configured in your system, the system
will replace these values with the default language specified.
Images You need to specify the type and format of the images you are
importing.
• Type is an informative label that is written into the image metadata.

Default values are Line Art, Screen Capture, and Equation.
If an image is labeled Line Art or Screen Capture, the system will
automatically designate it as Needing Translation. Images labeled
Equation are not designated as needing translation; if these images
are part of a map that is sent for localization, the system will
automatically promote them to the review state and will not include
them in the image localization kit.
You can set the translation designation for specific images as

required once the image has been imported, and the image type
may be changed once the image is in the repository.
• Format may determine the output format of an image, depending

on your system setup.
Option Description
Labels You can assign one or more labels to a document and its children (if
any). Labels are added as metadata and improve searchability.
Import options
Images: If this option is selected and there are two (or more) images with the
Images have same file name, then the system imports just one of them (randomly).
unique names If you leave this check box empty, then all images are imported, they
keep their duplicate titles, and the system assigns unique file names.
Path:

2. Open the DITA CMS folder and select Import Images.
3. Click Next.
The Import Image(s) dialog appears.
4. Click Browse.

5. Navigate to the images, select them, and click Open.
The selected images appear in the Images to import list.
6. To import as a read-only object, select the Import As External checkbox.
Note: As a result of selecting this option, several other features are set to default
values and disabled.
to update.
8. In the Default language list, choose the language you want set for the file. If you want
to overwrite the language attribute set in the imported file with the selected language,
select the Override unknown languages with default checkbox.
9. In the Images options section, choose the type of image in the Type list and the output
format in the Format list.
10. (Optional) To assign a label, click Select and add one or more labels. Click OK when
done.
11. Click Next.
12. Select the Images checkbox to import only one instance of images with the same file
name. Clear the checkbox if you want all images imported and assigned unique file
names.
documents.
14. Click Finish.
Related Links
Importing content as read-only on page 401
Setting the image description when importing images

When importing images, the DITA CMS now uses information from the source topic to set the
image description that is saved in the DITA CMS.
The Image description is determined as follows:
1. Use the <title> element of the figure.

2. If the <title> element is not available, use:
a. the content of the <alt> element, or

b. the value of the alt attribute
3. If neither of these are available, the Image description field remains empty.
Note: As before, the image filename is always used as the image title.
Import multiple resolution images

The Import Images With Multiple Format wizard lets you import images and their different
resolutions in bulk into the repository.
When you publish in different media, you most likely use different image resolutions for each
output. You might, for example, want to use a low resolution interlaced JPEG with output that’s
designed for the web and have a high-resolution version for PDFs.
This procedure lets you simultaneously import all the different formats that you use for each
image and automatically assign them to the different output formats. You can, at the same time,
specify the default format and whether the images will need to be translated.
Pre-requisites
• Each image resolution must be saved in a different directory. It is recommended to create an

import directory with a subdirectory for each type of resolution; for example:
C:\images_import\Medres
C:\images_import\PDF
C:\images_import\Web
C:\images_import\Hires
...
• When multi-resolution images are imported into the system, they are assigned a collective ID
and stored in a zip file with the extension .image. To successfully assign the different resolutions
to the correct DITA CMS image object, all the different resolutions of an image must share the
same file name. For example, you might have a file called bike.jpg that you'd use for web
output, and another called bike.png that you would use for glossy brochures.
You can specify the following options when importing images:

Option Description
Type Type is an informative label that is written into the image metadata.
Default format Format may determine the output format of an image, depending on
your system setup.
Needs translation When a map is sent for localization, only the images designated as
Needs translation are included in the image localization kit. Images
that are not designated as needing translation when a map is sent
for localization are automatically promoted to the review state and
are not included in the image localization kit.
To import multiple resolution images:

2. Open the DITA CMS folder and select Import Images With Multiple Formats.
3. Click Next.
The Images With Multiple Formats dialog opens.
4. Select the image Format to import and click Browse.

The Browse For Folder dialog appears.
5. Navigate to the directory that contains the images for this format and click OK.
The selected directory appears in the Folder Path list.
6. Repeat the steps as required for all the formats that you are using.
8. (Optional) Click Next.
The Specify Default Values dialog opens.
The values you specify will be used for all the resolutions of all the images. You can change
the values for individual images later on, if you want.
9. In the Description box, type a description for the file.

10. In the Default language list, choose the language you want set for the file.
11. In the Type list, click the type of image being imported.
12. In the Default format list, click the output format for the image.
This may determine the output format that an image will be used for, depending on your
system setup.
13. Select the Needs Translation checkbox to designate the image as needing translation
or clear the checkbox if the image should not be included in the image localization kit.
Certain types of graphics may automatically enable this checkbox, but you can change the
values for individual images later on, if you want.
14. Click Finish.
Related Links
Import maps
The Import Maps wizard lets you add one or more maps authored outside the DITA CMS to the
repository.
When you import a map, this map and its dependencies (for example, the map, topics, and images
it refers to) are imported into the repository and assigned the initial status (for example,
Authoring:Draft). If one of the map dependencies cannot be found (for example, one of its topic
is missing), the import is cancelled and an error message is displayed.
When you import a map, its file name is added to the object's metadata in the originalFileName
index and the path relative to its containing map is added to the object's metadata in the
originalRelativePath index.
You can specify the following options when importing maps:
Option Description
Option Description
in the repository.



updated.
Images If the maps you are importing reference images, you need to specify
the type and format of the images.

Option Description


Import options
MAP IDs: If this option is not selected, the map is assigned a new ID by the
Retain root system. This will be used as both the file name and as the map root
map IDs ID. The imported map’s root ID is overwritten.
If this option is selected, then the value of the imported map ID

remains unchanged. If no other map already has this file name, then
this ID will also be used as the document file name. If there is a conflict
with an existing map file name, the system will assign the imported
map a unique file name, which will be different from the map ID.
Topicrefs: If this option is selected, then navtitle and type attributes are
Remove removed from <topicref> elements containing an href attribute
@navtitle and when the map is imported.
@type from
When you are authoring DITA documents, there are several ways
<topicref>
that you can specify topic attributes such as type and title: at the map
containing
level and at topic level. DITA CMS does not maintain map attributes
@href
automatically. If you keep these in the map, then you’ll need to update
them manually if, for example, you change the title of a topic.
Option Description
Resources: If this option is selected and there are two (or more) resources with
Resources the same file name, then the system imports just one of them
have unique (randomly). If you leave this check box empty, then all resources are
names imported, keep their duplicate titles, and the system assigns file
names.
Path:
To import one or more maps and its dependencies:

2. Open the DITA CMS folder and select Import Maps.
3. Click Next.
The Import Map(s) dialog appears.
4. Click Browse.
5. Navigate to the *.ditamap file(s), select them, and click Open.
The selected maps appear in the Maps to import list.
to update.
9. In the Images options section, choose the type of images in the Type list and the output
format in the Format list for the images referenced in the document.
done.
11. Click Next.
12. Select the Map IDs checkbox to keep the existing IDs. Clear the checkbox if you want
new IDs assigned upon import.
13. Select the Topicrefs checkbox to remove the navtitle and type attributes from
<topicref> elements that contain an href attribute upon import. Clear the checkbox
if you do not want the attributes removed.
names.
15. Select the Resources checkbox to import only one instance of resources with the same
file name. Clear the checkbox if you want all resources imported and assigned unique
file names.
documents.
17. Click Finish.
Related Links
Import topics
The Import Topics wizard lets you add one or more topics authored outside DITA CMS to the
repository.
When you import a topic, this topic and its dependencies (for example, the topics and images it
refers to) are imported into the repository and assigned the initial status (for example,
Authoring:Draft). If one of the topic dependencies cannot be found (for example, one of its images
is missing), the import is cancelled and an error message is displayed.
When you import a topic, its file name is added to the object's metadata in the
You can specify the following options when importing topics:
Option Description

in the repository.



updated.
Option Description
Images If the topics you are importing reference images, you need to specify
the type and format of the images.




Import options
Resources: If this option is selected and there are two (or more) resources with
Resources the same file name, then the system imports just one of them
have unique (randomly). If you leave this check box empty, then all resources are
names imported, keep their duplicate titles, and the system assigns file
names.
Option Description
Path:
To import one or more topics and its dependencies:

2. Open the DITA CMS folder and select Import Topics.
3. Click Next.
The Import Topic(s) dialog appears.
4. Click Browse.
5. Navigate to the topics, select them, and click Open.
The selected topics appear in the Topics to import list.
to update.
9. In the Images options section, choose the type of images in the Type list and the output
format in the Format list for the images referenced in the document.
done.
11. Click Next.
names.
13. Select the Resources checkbox to import only one instance of resources with the same
file name. Clear the checkbox if you want all resources imported and assigned unique
file names.
documents.
15. Click Finish.
Related Links
Reimporting the same file into the DITA CMS

The Import dialog allows you to choose whether you want to overwrite content that was previously
imported or import the file as a new object.
DITA CMS uses the following two indexes to identify whether the file already exists as an object
in the Content Store:
• originalFileName, which tracks the original names of files that were imported
• originalRelativePath, which tracks the path of the file relative to its map
If Update existing documents is selected when you import a file, DITA CMS verifies the
originalFileName index for a match to an existing object. If it discovers a match and the Use
relative path along with file name to match documents to update checkbox is selected, DITA
CMS also verifies the originalRelativePath index to verify that the base path of the imported
file also matches the base path of the object in the Content Store. When a match is confirmed,
the existing object is updated with the content from the imported file provided that it is in a lockable
state. Once imported, all objects begin in the Authoring:draft state (or the equivalent initial
workflow status for that object type in your deployment).
If the existing object is not in a lockable state (for example, it is locked by another user or not in
the Authoring:Draft state), the existing object is not updated and the “Existing file NOT replaced”
message is displayed in the Import dialog.
DITA CMS does not automatically change the state of an existing object to allow the update since
a status change in one object may trigger a cascade of status changes in other objects in the
Content Store as a result.
Troubleshooting import errors

When you import an object into the DITA CMS, errors that occur during the import are provided
in the Import Errors dialog.
For example, the following diagram shows errors that occurred when importing a map:
The Error Description field provides information that might help you determine why the file could
not be imported. For example, in the diagram above, the DITA CMS could not find an image
(mte1420485080295.image) which is referenced in file mte1417101584341.xml. To fix the issue,
you can look at the content of the mte1417101584341.xml file and find the missing reference.
To open a document, double-click the initial imported object from the Import Errors dialog (for
example, the imported map in the dialog above). This is the object with a complete path and
filename in the Filename field. The DITA CMS opens the folder that contains the object.
Once you have solved the issue:

1. Click OK to close the Import Errors dialog.
The Import dialog is displayed.
2. Click Finish to try the import again.
Export content from the DITA CMS

You can export content from the DITA CMS to another location to, for example, send your DITA
source to a customer or external user, or to build output using a standalone DITA Open Toolkit
as a troubleshooting measure.
Important: IXIASOFT does not recommend exporting content from the DITA CMS with
the intention of performing external edits and re-importing. While the DITA CMS does
support this from a functional standpoint, you run the risk of losing revision history and
potentially overwriting any changes that occurred within the CMS after the content was
exported. The re-import is an overwrite, not a merge.
1. Locate the map, topic, or image you want to export.
When you export a map, the export includes all the map's references: sub-maps, topics,
images, and topics referenced via xref, conref, keyref, etc. Likewise, when you export a topic,
the export includes all of the topic's references.
2. Right-click the object you're exporting and select Generate Output.

3. In the Output Format drop-down, select the Export output type.
If this option is not available, ask your CMS Administrator to check the system configuration
to ensure that you are assigned to a role that has access to Export and that the output type
is enabled.
4. Select other options as appropriate and click Create.
It is not currently possible to apply a ditaval to exported content. The Export process simply
gathers the required content from the Content Store and returns it to you. The DITA Open
Toolkit is not involved in the Export and therefore there is no opportunity to perform any
transformation on the content.
5. Select the location to save the zip file of exported content.
Within the zip file, the exported content is in the content\authoring subfolder. This subfolder
contains a number of items other than the content itself. For each exported object, the following
files are provided:
• *.properties
• *.customproperties
• *.indexedcontent
While you can use information in these files for different purposes, neither you nor a third party
needs them to generate basic output. You can delete them if you choose.
Important: If you are sending the content to a third party to generate their own output,
you must also send the following plugins from the Output Generator:
• com.ixiasoft.dita.dtd
• org.oasis-open.dita.mathml.doctypes
• com.ixiasoft.images
• org.w3c.mathml3
25 Taxonomies
Taxonomies
Topics: DITA CMS lets you create taxonomies that reflect the structure
• About Taxonomies of the information contained in your documents.
• About the Taxonomy Terms
view
• Open the Taxonomy Terms
view
• Creating and modifying
taxonomies
• Import a taxonomy from a
TSV text file
• Managing taxonomy terms
within documents
• Locating documents with
taxonomy terms
About Taxonomies
Taxonomies are a type of metadata used to classify topics or elements.
A taxonomy is a hierarchical classification system that contains one or more taxonomy terms
that you define. When you apply these terms to documents or elements, you can make information
easier to find, both for authors and for end users. You can also use them when you process
output to facilitate features like dynamic publishing portals.
You can add taxonomy terms to the <metadata> section of a topic or map as either <category>
or <keyword> elements, depending on how your system is configured. This adds those
classifications to the entire topic or map. You can also add taxonomy terms within the body of a
topic or map as <keywords> to classify specific elements.
When used as a metadata category, a taxonomy term contains two components: a Human
Readable category name and a Vocabulary Term Value. The two may be but need not be the
same. For example some output applications may require a taxonomy term format that does not
identify the actual term to the reader.
You can use the Taxonomy Terms view to manage taxonomies and apply taxonomy terms to
multiple documents. (You cannot use this view to add keywords to elements.) You can also use
buttons in the CMS toolbar to add terms to the document that you are editing.
About the Taxonomy Terms view

Use the Taxonomy Terms view to manage taxonomy terms and apply them to documents.
The Taxonomy Terms view is where you create taxonomies and edit the terms they contain. It's
also where you can insert or remove these terms from multiple documents.
It also lets you see which documents contain specific terms.
The Taxonomy Terms view is comprised of three panes:
• The Taxonomy pane shows the taxonomy structures available for you to use. This is also
where you can edit taxonomies and create new ones. It has two columns:
• Human Readable – presents the terms in forms you can read.

• Vocabulary Term Value – shows the term as it is actually embedded in the document. Some
systems are configured so that these are machine-generated and aren’t particularly
meaningful to people.
Taxonomies 427
Figure 59: Taxonomy pane
• The Terms pane shows all terms contained by the documents in the Documents pane.
• The number in parenthesis indicates the number of documents containing that term.
• Blue italic text appears when you highlight one or more documents in the Documents list.
These are the terms the selected documents contain.
Figure 60: Terms pane – shows the terms contained in the documents
• The Documents pane displays the documents you are currently working with. Underlined
documents contain the terms that are currently highlighted in the Terms pane.
Taxonomies 429
Figure 61: Underlined documents contain the highlighted terms
Using the Taxonomy Terms view
You use the Taxonomy Terms view to:
• Create and modify taxonomies: These operations require additional access rights and are
typically performed by information architects and CMS administrators.
• Manage taxonomy terms within document: Once a taxonomy is created, all DITA CMS
users can add and remove terms within their documents.
Open the Taxonomy Terms view

To open the Taxonomy Terms view:
1. From the main menu, click Window > Show View > Other
2. In the Show View dialog box, click DITA CMS - General > Taxonomy Terms
3. Click OK.
Creating and modifying taxonomies

The procedures in this section describe how to create and modify taxonomy structures.
Note: The options in this section are only available if your account is configured for access
to them. This is usually the case for information architects and CMS administrators.
Create a new taxonomy

This creates a new taxonomy.
1. From the main menu, click Window > Show View > Other > DITA CMS - General >
Taxonomy Terms and click OK.
2. Right-click anywhere in the Taxonomy pane and select New Taxonomy.
3. Enter the name of the new taxonomy in the dialog box and click OK.
The taxonomy is displayed in the Taxonomy pane. It does not include any term.
Add a taxonomy term to a taxonomy

Use the Taxonomy Terms view to add taxonomy terms.
1. In the Taxonomy Terms view, right-click the root node of the taxonomy.
2. Select Edit Taxonomy.
The taxonomy is locked, and the word [EDITING] appears beside it.
3. Right-click either the root node or any of the child terms under it and choose one of
the following:
• Append Child Term – adds a term as a child of the selected term or taxonomy. This is
the option you'll use when you add your first terms to a new taxonomy.
• Insert Term – adds a term at the same level as the selected term. (Not available at the
root node.)
A row with "Untitled" values appears at the selected level.

4. Enter a Human Readable value for the term.
5. Double-click the term's Vocabulary Term Value.
6. Enter a Vocabulary Term Value for the term.
Taxonomies 431
This may be the same as the Human Readable value or may be different depending on how
your organization uses taxonomy terms.
If the Vocabulary Term Value already exists, the following message is displayed:
A term with this value already exists. Do you wish to use the existing term?
• To use the existing term, click Yes. You have completed this procedure.
• To enter a different term, click No and specify another Vocabulary Term Value.
7. Right-click the root node of the taxonomy and select Save Taxonomy.
Edit taxonomy terms

You can edit Human Readable and Vocabulary Term Value entries in a taxonomy term.
3. Double-click the term you want to edit in either the Human Readable or Vocabulary
Term Value pane.
The entry becomes editable.
4. Type in the new term.

5. Click outside the entry field.
6. Repeat for each term you want to edit within the editable taxonomy.
7. Right-click the root node of the taxonomy and select Save Taxonomy to save your
changes.
Remove taxonomy terms from a taxonomy

Terms must be removed one at a time.
However, removing a taxonomy or taxonomy term does not remove it from the documents
where it is used.
3. Right-click the term you want to delete and select Delete Term.
4. Click OK.
Both the Human Readable and Vocabulary Term Value are removed from the taxonomy
structure.
5. Repeat for each term you want to delete within the editable taxonomy.
6. Right-click the root node of the taxonomy and select Save Taxonomy to save your
changes.
Delete a taxonomy from the Taxonomy Terms view

You can now delete a taxonomy from the Taxonomy Terms view.
To delete a taxonomy from the Taxonomy Terms view:
Note: The taxonomy must not be in editing mode.
2. Select Delete Taxonomy.
The Delete Taxonomy dialog opens. For example:
3. Click OK.
The taxonomy is removed from the list of taxonomies.
Taxonomies 433
Import a taxonomy from a TSV text file

The import taxonomy wizard lets you add one or more taxonomy files prepared outside DITA
CMS to the repository.
The taxonomy must be specified in a TSV (tab-separated values) text file that reflects the structure
of the taxonomy. For example:
Figure 62: Sample taxonomy structure (from the Google product taxonomy)
To import a taxonomy from a TSV text file:
1. Select File > Import...

2. Open the DITA CMS folder and select Import Taxonomy From TSV Text File.
3. Click Next.
The Import Taxonomy From TSV File dialog appears.
4. Click Browse.
5. Navigate to the TSV file, select the desired file, and click Open.
The selected TSV file appears in the Taxonomy Title.
6. Click Finish.
The taxonomy pane displays the imported taxonomy and is available for you to use.
Managing taxonomy terms within documents

The procedures in this section tell how to add, remove, and modify taxonomy terms within
documents.
View which taxonomy terms a group of documents contains

Use the Taxonomy Terms view to determine which terms are contained in specific documents.
To see which terms are contained by one or more documents:
1. Open the Taxonomy Terms view.

2. Select the documents:
a) Locate the documents; for example, perform a search, open a map, or display them
in a view.
b) Drag the documents into the Documents pane in the Taxonomy Terms view.
3. In the Documents view, click one or more documents.
Taxonomies 435
The terms contained in the selected document(s) are highlighted in blue italic font in the
Terms pane.
Add taxonomy terms to multiple documents

The Taxonomy Terms view allows you to add terms to multiple documents at once.
The documents in the Documents pane must be locked before you can make changes to the
taxonomy terms. If documents are not locked when you attempt to make a change, a message
may appear to request permission to lock the documents. If you click OK to lock the documents,
the documents are locked regardless of their status.
Once you click Apply, the taxonomy changes are applied to the documents. Documents that
were in a 'lockable' status such as Authoring:work or the equivalent remain locked. Documents
with an 'unlockable' status such as Authoring:done or the equivalent that were locked by the
system are handled differently. When Apply is clicked, the document is released, a comment
describing the change is automatically added to the Revision History, and the status remains
unchanged. If any of the documents cannot be locked, an error message displays and the operation
is canceled. To continue, either change the status of the affected documents so that they can be
locked or remove them from the Documents pane.
Terms are added to the document's <metadata> section as keywords or categories, depending
on how the system is configured.
To add terms to all the documents in the Documents pane:

in a view.
3. In the Taxonomy pane, click one or more taxonomy terms.
4. Right-click the term(s) and click Add Term(s) to All Documents.
If a message appears requesting to lock the documents, click OK.
5. Click Apply.
Important: Changes are not applied to the documents until you click Apply. Do not
release documents before clicking Apply or the changes will be lost.
6. Release the documents, as required.
Remove a taxonomy term from multiple documents

The Taxonomy Terms view allows you to remove terms from multiple documents at once.
The documents in the Documents pane must be locked before you can make changes to the
taxonomy terms. If documents are not locked when you attempt to make a change, a message
may appear to request permission to lock the documents. If you click OK to lock the documents,
the documents are locked regardless of their status.
Once you click Apply, the taxonomy changes are applied to the documents. Documents that
were in a 'lockable' status such as Authoring:work or the equivalent remain locked. Documents
with an 'unlockable' status such as Authoring:done or the equivalent that were locked by the
system are handled differently. When Apply is clicked, the document is released, a comment
describing the change is automatically added to the Revision History, and the status remains
unchanged. If any of the documents cannot be locked, an error message displays and the operation
is canceled. To continue, either change the status of the affected documents so that they can be
locked or remove them from the Documents pane.
To remove a term from all the documents in the Documents pane:

in a view.
3. In the Terms pane, right-click a term and click Remove Terms From Documents.
4. Click Apply.
Important: Changes are not applied to the documents until you click Apply. Do not
release documents before clicking Apply or the changes will be lost.
5. Release the documents, as required.
Remove documents listed in the Taxonomy Terms view

You can remove specific documents from the Documents pane.
To remove documents from the documents list:
1. In the Documents pane, click the documents that you want to remove.
2. Right-click the selected documents and click Remove Documents from List.
Taxonomies 437
Add taxonomy terms to a single document as keywords

Use this procedure to add terms from the Taxonomy Terms list as keyword within the body of a
document.
The document must be locked.
This procedure lets you add existing taxonomy terms as keywords in the body of a document.
Note: If you want to add taxonomy terms to the document’s prolog, use the Add taxonomy
terms to a single document as metadata procedure.
1. Place your cursor where you want to insert the term.

You can put a term anywhere it's valid to insert a <keyword> element.
2. Either
• select Insert Taxonomy Keyword from the XML menu, or
• click the icon.

3. Select the terms you want to add to your document, then click OK.
The selected terms are added as keywords at the cursor's position.
Add taxonomy terms to a single document as metadata

Use this procedure to add terms from the Taxonomy Terms list to the metadata section of a
document.
The document must be locked.
The taxonomy terms are added to the <metadata> section of a document as either <category>
or <keyword> elements, depending on how your system is configured.
Note: If you want to add keywords to the document's body, use the Add taxonomy terms
to a single document as keywords procedure.
1. Either
• select Insert Taxonomy Metadata from the XML menu, or

• click the icon.

2. Select the terms you want to add to your document, then click OK.
The selected terms are added as keywords at the cursor's position.
Locating documents with taxonomy terms

The procedures in this section tell you how to find out where terms have already been inserted
and which documents contain specific terms.
Find the location of a taxonomy term within a taxonomy

Use the Taxonomy Terms pane to determine where a specific term is located within a taxonomy.
1. From the main menu, click Window > Show View > Other > Taxonomy Terms and click
OK.
2. Select one or more documents that contains the taxonomy term you want to locate.
a) Locate the documents using a search query, map list, or other means.
b) Drag the documents into the Documents pane.
The Terms pane is populated with the taxonomy terms that have been added to these
documents.
3. Perform either or both of these steps as required:
a) In the Terms pane, right-click one or more terms and choose Select in Taxonomy.
The taxonomy structure in the Taxonomy pane expands, if necessary, and the selected
terms are highlighted.
b) In the Taxonomy pane, right click one or more terms and choose Select in Terms.
If the menu option is unavailable (greyed-out) then none of the items in the Documents
pane contain the term.
The taxonomy structure in the Terms pane expands, if necessary, and the selected terms
are highlighted.
Search for documents that contain taxonomy terms

You can use the DITA CMS search facility to locate documents containing specific terms.
1. If necessary, expand the Taxonomy Terms panel of the Search view.
2. Click the Add button.
3. Select the terms you want to search for, then click OK.
Taxonomies 439
4. From the Select documents containing list, select one of the following:
• any of the terms: Documents that contain at least one of the specified taxonomy terms
are returned in the Search Results.
• all of the terms: Only document that contain all of the specified taxonomy terms are
returned in the Search Results.

Related Links
26 Project management
Project management
Topics: The project management feature lets coordinators handle

• Project Management view project-wide tasks that may involve multiple deliverables.
• Initial project setup and Project management functionality offers an overview of
other related tasks
multi-deliverable projects that may include document
• Set project defaults
deliverables as diverse as installation instructions, training
• Manage project personnel
packages, and reference documentation.
• Manage project deliverables
• Use the Bulletin Board You can find project management functionality in the Project
• View project statistics Management view, which you can open on its own or as part
• Delete a project of the Project Management Perspective.
Related Links
Project Management view

The Project Management view gives coordinators an overview of their projects.
Project Management view displays information about projects in a collapsible tree view, which
is organized into items such as Deliverables and Team. These in turn may be expanded to show
items such as the members that make up a Team, and the various document life cycle Milestones
for each Deliverable.
Use it to assemble the staff that will be responsible for documentation and review, to track the
progress of the maps that make up the projects, and to designate the languages that each map
will be translated into.
The Deliverables list
The Project Management view includes a Deliverables list that displays the selected project's
deliverable maps, their IDs and status.
Two columns let you assess a specific deliverable's status with regard to its own or the project's
milestones, whichever is closest.
• Next Milestone – The next milestone date appears in this column.

• Lateness – Each exclamation mark (!) in the Lateness column represents a milestone that
was not completed by its due date.
Bulletin Board view
Project Management view is associated with the Bulletin Board view. This view displays messages
that project coordinators have posted for their team using the Project Management view's Bulletin
Board item.
Project management 443
Related Links
Project and deliverable highlight colors

These highlights indicate projects and deliverables that are close to or past their milestones.
In the Project Management view and in the Deliverables list, colored highlights help you identify
projects and deliverables that are approaching or past their due dates or milestones.
Highlights in the Project Management view
In the Project Management view, the color of the project folder indicates the ownership of the
project, as follows:
• Blue folder ( ): Projects that you own

• Yellow folder ( ): Projects owned by another coordinator
In the Project Management view, deliverables that are approaching or past their designated
milestones are highlighted in the following colors:
• Yellow - the deliverable is within a week of a milestone.

• Orange - the deliverable is up to 2 weeks past a milestone.
• Red - the deliverable is 2 weeks or more past a milestone.
These colors are removed once the milestone's completion date is recorded.
Note: The exact time intervals are configurable. Your CMS Administrator can tell you
exactly when the colors are set up to appear in your system.
Highlights on the projects use the same set of colors, but reflect the project’s relationship to its
due date.
The example below shows what you would see on January 23, 2008 if you had a project (Test
Project 2) that was due on January 21st. Test Project 2 has an orange highlight – it’s less than
2 weeks past its due date.
The map Setting Up Remote Access, on the other hand, has missed two milestones and is close
to another. In the Project Management view, you can see that those milestones are highlighted
in red and orange and yellow, respectively, and that the map name is also highlighted in red.
Highlights in the Deliverables list
The same system of highlight colors is used in the Deliverables list, but with slightly different
connotations. If a project is getting close to its due date, then the map that’s responsible for the
slippage is highlighted with the color that reflects the project’s status.
In the example below, the map Setting Up Remote Access has an orange highlight. This indicates
that the entire project (Test Project 2) is several days past its due date, and that it’s the Setting
Up Remote Access map that’s causing the problem.
Deliverable-specific highlights and icons

Additional highlighting and colored icons tell you when your deliverables have reached the
Published and Localization cycles.
DITA CMS helps you keep track of each map’s progress through the various production cycles
such as Publish and Localization.You can tell at a glance which ones have arrived in the required
cycles and open them for review.
You can also open previous versions of these deliverables, both in the authoring languages and
the targeted translation languages.
When you expand each deliverable item you can see its subsidiary items:
• Targeted translation languages – shows the languages that this deliverable is to be localized
in.
• Published – shows maps that have completed either the Authoring or Localization cycle and
currently have the status Published:done.
• Milestones – shows the due dates (if any) that are specific to a particular deliverable.
Targeted translation languages
The icons under the Targeted Translation Languages item represent the languages that this
deliverable is to be localized in.
• Blue icons – indicate translation languages specific to this deliverable. This includes languages
set at the project level as well as those set for this particular map.
• Green icons – indicate targeted translation languages in other projects. These are only for
reference and cannot be removed.
In the illustration below, the map has been expanded to show its targeted translation languages.
You can see that this deliverable is scheduled to be localized in German and Italian (blue icons).
The green icons indicate that – in another project – this map is being translated into French and
both Traditional and Simplified Chinese.
Localization history
After a map has been published, it is ready to be localized. You can view the localization history
(if any) under the appropriate icon. In the illustration below, the French icon has been expanded
to show the versions of the map that are currently in the Localization cycle.
Note that these are all earlier versions of the map, which is currently at version 8.
Yellow highlighting
A yellow highlight on one of the targeted translation language icons tells you that the current
version of the map has arrived in the localization cycle. As soon as the version of the map that
is in your project is promoted into the Localization cycle in a specific language, a yellow highlight
appears on the icon representing that language.
In the illustration below, you can see that there are yellow highlights on all three of the targeted
translation languages. The French icon has been expanded so that you can see that the version
number (13) matches that of the map.
Published
The published icon lets you see all the published versions of a map – in all its languages.
Maps arrive in the published cycle in two ways – from the Authoring cycle in their native language
and from the Localization cycle in their targeted translation languages.
When you expand the Published item you'll see icons representing all the languages that the
map has been published in.
In the example below, you can see that there are three targeted translation languages – French,
Simplified Chinese, and Traditional Chinese – indicated with blue icons. The native authoring
language – English – is indicated with a green icon.
You can see that none of the current localizations of this version of the map (9) have yet arrived
in the Published cycle, although an earlier version has been published in French (3).
There are, however, several published versions in the original language. In the illustration below
the English icon is expanded to show the versions that have been published. The highlight on
the language icon indicates these include a version that corresponds to the map version (9).
You can click any of the versions to open it in the editor area.
Team overload indicators

This feature lets coordinators quickly assess the document assignment levels of all team members.
When you expand the Team item in Project Management view, you see the number of documents
assigned to each member. This lets you see if anybody is overloaded.
Team workloads are displayed in two different ways, depending on whether a maximum workload
has been set during DITA CMS configuration.
• If no maximum workload has been set for a given role, Project Management view simply shows
the number of documents assigned. In the screen shot below, you can see that the team
member has one document assigned to him in the role of Project Coordinator.
• If a maximum workload has been set for a role, then the workload displays as a percentage
of the maximum. In the screen shot below, you can see that three of the team member's roles
have been configured that way: Author, Information Architect, and Reviewer.
Maximum workload is the maximum number of documents of a given type that an individual can
be assigned in a given role. This number is configurable and may be different in your installation.
Note: The numbers shown in Project Management view reflect all of a team member's
assigned documents in all projects in the repository. It includes documents that are
Incoming, Active, and Retained.
Overload warning colors
By default, DITA CMS is configured to display the following colors under the following workload
conditions:
• Black - the team member is assigned less than 80% of their configured maximum workload.
• Yellow - the team member is assigned between 80 and 100% of their maximum workload.
• Red - the team member is assigned more than 100% of their maximum workload.
The numbers and colors are configurable and may be different in your installation.
Initial project setup and other related tasks

This section describes how to create a completely new project and provides the general
administrative tasks that are useful in handling projects.
Create a project
This procedure creates a completely new project.
Note: Any project that you create is automatically assigned to you as Project Coordinator.
1. From the Project Management view, click the Create Project button ( ).
The Project Information dialog appears.
2. Enter a Name for the project.
3. (Optional) Set the Due Date.
a) Click the calendar button.

An interactive calendar appears.
b) Select the required date, then click OK.

You'll return to the Project Information dialog where the selected Due date will be
displayed.
4. Click OK.
Your new project appears in the Project Management view.
If you need to change or assign additional project managers you can do so using the
Assignments dialog, if you have project assignment rights.
Set project due date

This procedure sets the project's due date.
1. Right-click the project, and select Manage from the menu.
2. Click the calendar button to set the Due Date.


The Project Information dialog reappears displaying the selected Due Date.
4. Click OK.
Project status
Project status records the stages of the project's development.
The Project Management view lets you record project status to help you keep track of the overall
progress of the project. Project status is there for reference only. There are no document
dependencies as there are for topics, maps, and images.
The diagram shown below illustrates project status levels and their relationship to each other.
Note: When you set a project's status to Done or Cancelled, it will no longer be visible in
the Project Management view.
Related Links
Change project status on page 453
Change project status

This procedure records the state of the project.
1. Right-click the project, and select Change Status... from the menu.
The Change Status dialog appears.
2. Select the New Status from the drop-down list.
3. Click Change.
Project status is changed.

Related Links
Project status on page 452
Clone a project
This procedure creates a duplicate of an existing project.
Use the Clone procedure when you want to create a project that uses the same basic information
as another project. Cloned projects initially always have Planning status.
1. Right-click the project and select Clone from the menu.

2. If you want to change the default project name, enter a new Name.
3. Select the Coordinator if necessary.
Note: You can only see projects that you yourself are coordinating. If you select
someone else's name, then the project you're creating will not be visible in your own
Project Management view. If you intend to edit the cloned project (add deliverables or
milestones for example), you should wait and assign another coordinator after the
project is completely set up.
4. Set the Due Date if required.
a) Click the calendar button.

b) Select the required date, then click OK.

The Project Information dialog reappears displaying the selected Due date.
5. Click OK.
A clone project is created and added to the repository. The system assigns it a unique ID.
Change project name

This procedure lets you rename the project.
2. Type the new name into the New Name field.
3. Click OK.
The project name is changed.
Set project defaults

The procedures in this section let you set the global defaults for localization, milestones, and
approval systems.
Use these procedures to set defaults for an entire project. You can override these settings within
the project for specific deliverables as needed, if you specify targeted translation languages and
map-specific milestones.
Specify default translation languages

This procedure sets the translation languages for all deliverables within a project.
The languages that you specify with this procedure become the default languages for all the
maps in the current project.
You can remove default languages from specific deliverables or add additional languages to
them, using the Specify targeted translation language procedure.
1. Expand the project, if necessary, to display its items.

2. Right-click the Default Translation Languages item, and select Manage from the menu.
The Language Selection dialog appears.
3. Select the Display languages by group checkbox if you want your selections presented
by linguistic families: e.g., Indo-European.
The specific languages and families are configurable and may vary.
4. Select the languages.

If languages are already assigned in this project, their checkboxes will be selected.
5. Click OK.
The selected languages appear as items under Default Translation Languages. They will
also appear in the list of targeted translation languages under each deliverable in the
project.
Remove default translation languages

This procedure removes selected default translation languages from all deliverables in a project.
2. Expand the Default Translation Languages item, if necessary.
3. Click the language(s) you want to remove.
You can select several languages by holding down CTRL or SHIFT and clicking the languages.
4. Right-click, then select Remove from the menu.
The selected languages are removed from the project and from all deliverables' Targeted
Translation Languages lists.
Set the default approval systems

This procedure sets the default approval systems for all documents in a project.
You can establish default approval systems for all the documents in a project: the maps and their
constituent topics and images.
The default approval system for a particular role is set during system configuration. You can
override the system defaults by setting the approval systems for the different roles within a project.
Note: Approval systems may also be set during file assignment. If there is a conflict
between approval systems, the more restrictive system always takes precedence. For
example, if a document is in two projects with different approval systems, the more
restrictive system is the one that's used.The same holds true for approval systems assigned
on a per-document basis.

2. Right-click the Approval Systems item, and select Manage from the menu.
The Default Approval Systems dialog appears.
3. Select an Approval System for each Role, as required.
4. Click OK.
The selected roles and their approval systems appear as items under Approval Systems.
Remove default approval systems

This procedure removes default approval systems from a project.
2. Expand the Approval Systems item.
The default approval systems for each role appear.
3. Click the approval system(s) you want to remove.
You can select several items by holding down CTRL or SHIFT and clicking the items.
The selected approval systems are removed from the project.
Add default milestones

This procedure establishes the due dates for all the deliverables within a project.
Use this procedure to set the completion dates for an entire project.

2. Right-click the Default Milestones item, and select Manage from the menu.
The Manage Milestones dialog appears.
3. Click Add.
The Define Milestone dialog appears.
4. From the Status list, select a document milestone.

A calendar appears.
6. Select the required date and click OK to close the calendar.

The Define Milestone dialog reappears showing the selected due date.
7. Click OK.
The Manage Milestones dialog reappears showing your new milestone with its due date.
8. (Optional) Select the new milestone and enter a Comment, if appropriate.
9. Click Add to set additional milestones.
Tip: If you want to delete a milestone, simply highlight its line in the Manage
Milestones dialog, and then click Remove.
The milestones that you've defined for the project appear beneath it in the Project
Management view.
Modify default milestones

This procedure changes the due dates for all the deliverables within a project.
3. Right-click the milestone you want to modify, and select Set due date... from the menu.

The Manage Milestones dialog reappears showing the modified date.
The modified milestone date appears beneath its project in the Project Management view.
Modify default milestone comments

Use this procedure to change the comments beside a specific due date.
3. Enter text in the Comment column.
Record default milestone completion dates

This procedure records the completion dates for the entire project.
3. Right-click the milestone whose completion dates you want to record, and select Set
finished date... from the menu.

You'll return to the Manage Milestones dialog where the modified date will be displayed.
Remove default milestones

This procedure removes selected milestones from the entire project.
2. Expand the Deliverables item.
The deliverable maps appear.
3. Expand the map whose milestones you want to specify.
4. Expand the Milestones item, if necessary.
5. Click the milestone(s) you want to remove.
You can select several milestones by holding down CTRL or SHIFT and clicking the milestones.
The selected milestones are removed from their deliverable.
Manage project personnel

The procedures in this section let you select your team members and specify their roles within
the project.
Use these functions to assemble the staff for your project and then assign them to the specific
roles that they will play.
Change project coordinator

This procedure lets you select another project coordinator.
Note: If you have project assignment rights, you can change the project coordinator using
the Assignments dialog. If you assign a project to yourself in this manner, you'll need to
refresh your Project Management view (if it's open) in order to see the project.

2. Select the new Coordinator.
3. Click OK.
The project is transferred to the new coordinator and disappears from your own Project
Management view.
Add members to the team

This procedure specifies the set of people who will work on the project.
2. Right-click the Team item, and select Manage from the menu.
The Team Selection dialog appears.
3. From the Group by list, select the way you want your choices displayed.
This list lets you select your personnel from different categories:
• User Role - sorts people by their responsibilities, such as Graphic Artist or Subject Matter
Expert.
• User Group - sorts people by other potentially useful categories, such as Senior Writers
or Paris Employees.
• No Grouping - presents the list of all available personnel.
The categories within each grouping are configurable and may vary.
4. Select the people you want to have as members of your team.

You can select people from within a role or group by opening the tree and selecting individual
names.
Note: In a grouped view, if you select a user from one group then their name will be
selected in every other group for which they are configured. In the example above,
selecting Jane Doe as Author automatically selects her in the Editor group as well.
This does not, however, influence the role assignments that you later make for Jane
(or any other team member). People may be assigned to as few or as many roles as
they are configured to hold.
5. Click OK.
The choices are assigned to your project's team.
These team members should now be assigned to their default roles in the project.
Related Links
Remove team members

This procedure lets you remove team members from a project.
2. Expand the Team item.
The members are displayed.
3. Click the team member(s) you want to remove.
You can select several team members by holding down CTRL or SHIFT and clicking the team
members.
The selected team members are removed from both Team and Default Role Assignments.
Note: Removing team members from a project does not change document assignments.
If you want to reassign documents to other team members, you'll need to do it through
the Assignments dialog.
Related Links
Set default role assignments

This procedure assigns roles such as Author or Editor to the team members.
Team members must be assigned.
Use this procedure to assign the people on your team to the roles that they will play in producing
the document deliverables. Typical roles include Project Leads, Information Architects, Graphic
Artists, etc. The exact titles may vary according to how your system is configured.

2. Right-click the Default Role Assignments item, and select Manage from the menu.
The Role Assignment dialog appears.
3. Select the roles you need for your project.
You can select specific people within a role by opening the tree and selecting individual
names. If there are limits to the number of people that may play a specific role in a project,
you'll see it here, e.g., (Max:1).
4. Click OK.
Your selected roles appear under the Default Role Assignments item, with the specified
set of people under each role.
This procedure establishes the roles that people play in the project. You will need to
explicitly assign documents to these people.
Remove default role assignments

This procedure removes team members from their role assignments in the project.
Use this procedure when you want to remove a team member from a specific role in a project.
This will not remove them from the team, nor will it affect their other role assignments.

2. Expand the Default Role Assignment item.
3. Expand the Role item (Editor, for example) to display the assigned team members.
4. Click the team member(s) you want to remove.
You can select several team members by holding down CTRL or SHIFT and clicking the team
members.
The selected team members are removed from the Role item. If you remove all items from
a Role, the Role item itself will disappear.
Note: Changing someone's role assignment does not change document assignments. If
you want to reassign documents to other team members, you'll need to do it through the
Assignments dialog.
Related Links
Manage project deliverables

The procedures in this section let you manage information specific to each map in a project.
Use these procedures to add maps (deliverables) to a project, establish map-specific milestones,
and target the exact set of translation languages for each map.
Add a deliverable to a project

Maps are added to projects as deliverables.
A map is the backbone of a document deliverable. Maps are added to projects one at a time
using a drag and drop technique.
You can add resource packages to projects like any other map, and then set milestones and
specify translation languages for them, if required.

2. Use Search to display maps in the Search Results view.
3. Drag and drop the required map onto the Deliverables item in the project tree or the
Deliverables list at the bottom of the Project view.
The map appears as an item under the project's Deliverables item. All of the project's
Default Translation Languages will automatically be assigned to it.
If you need to have this map translated into a language other than the defaults for the
project, you will need to add a Targeted Translation Language.
Open a map from Project Management view

This procedure opens a map that has been designated as a project deliverable.
Once you have added a map to a project as a deliverable, you can open it directly from Project
Management view.

2. Expand the project's Deliverables item.
3. Right-click the required map and select Open from the menu.
Remove deliverables
This procedure removes selected deliverables from a project.
3. Click the map(s) you want to remove.
You can select several maps by holding down CTRL or SHIFT and clicking the maps.
The selected maps are removed from the project.
Add map-specific milestones

This procedure establishes the due dates for a specific deliverable within a project.
Use this procedure when you want to assign a different set of completion dates for a deliverable
map.

2. Expand the project's Deliverables item.
4. Right-click the Milestones item, and select Manage from the menu.
5. Click Add.
The Define Milestone dialog appears.
6. From the Status list, select a document milestone.

8. Double-click the required date.

The Define Milestone dialog reappears showing the selected due date.
9. (Optional) Enter a Comment.
10. Click OK.
The Manage Milestones dialog reappears showing your new milestone with its due date.
11. Click Add to set additional milestones.
Tip: If you want to delete a milestone, simply highlight its line in the Manage
Milestones dialog, and then click Remove.
The milestones that you've defined for the deliverable appear beneath it in the Project
Management view.
Modify map-specific milestones

This procedure changes the due dates for a specific deliverable within a project.
5. Right-click the milestone you want to modify, and select Set due date... from the menu.

The Manage Milestones dialog reappears showing the modified date.
The modified milestone date appears beneath its deliverable in the Project Management
view.
Modify map-specific milestone comments

Use this procedure to change the comments beside a specific due date.
5. Enter text in the Comment column.
Record map-specific milestone completion dates

This procedure records the completion dates of a specific deliverable within a project.
3. Expand the map whose milestone completion dates you want to record.
5. Right-click the milestone whose completion dates you want to record, and select Set
finished date... from the menu.

You'll return to the Manage Milestones dialog where the modified date will be displayed.
Remove map-specific milestones

This procedure removes selected milestones from a specific deliverable within a project.
4. Expand the Milestones item, if necessary.
5. Click the milestone(s) you want to remove.
You can select several milestones by holding down CTRL or SHIFT and clicking the
documents.
The selected milestones are removed from their deliverable.
Specify targeted translation languages for a deliverable

This procedure establishes the set of translation languages for a deliverable.
You can specify unique sets of translation languages for each deliverable (map) in a project. You
may remove any (or all) of the default languages or add any number of additional languages.

3. Expand the map whose languages you want to specify.
4. Right-click the Targeted Translation Languages item, and select Manage from the
menu.
5. Select the Display languages by group checkbox if you want your selections presented
by linguistic families: e.g., Indo-European.
The specific languages and families are configurable and may vary.
6. Select the translation languages for this deliverable.

The checkboxes for the default translation languages for the project will be selected. You
may de-select these, if you wish.
7. Click OK.
The selected languages appear as items with blue icons below the deliverable. If a
deliverable has translation languages assigned in other projects, they will appear as items
with green icons below the deliverable. These items are for information only and cannot
be removed.
Remove targeted translation languages

This procedure removes targeted translation languages from a deliverable.
Targeted translation languages appear as items with blue icons below each deliverable. If a
deliverable has translation languages assigned in other projects, these will appear as items with
green icons below the deliverable. These items are for information only and cannot be removed.

3. Expand the map whose targeted translation languages you want to remove.
4. Right-click the Targeted Translation Languages item, and select Manage from the
menu.
5. De-select the required translation languages for this deliverable.
6. Click OK.
The selected languages are removed from the deliverable.
Use the Bulletin Board

The procedures in this section tell you how to use the Project Management's Bulletin Board
feature.
Use the Bulletin Board to keep project staff current with Project developments.
Add a message to the Bulletin Board

This procedure lets you post messages for team members.
When you add a message to the Bulletin Board, it immediately becomes visible to all members
of the team. You can opt to have these messages emailed to team members, as well.
1. Right-click the Bulletin Board item, and select Add Message from the menu.
The Message dialog appears.
2. Fill in the Title.
3. Type the Message.
4. Select Broadcast to email this message to your team.
Email format is configurable and will vary according to your system configuration.
5. Click OK.
All the project's team members will see your message in their Bulletin Board views.
View message details

This procedure lets you view the details of Bulletin Board messages.
1. If necessary, expand the Bulletin Board item to display message items.
2. Double-click the message you want to view.
The Message dialog appears with Message and Title fields grayed out.
View project statistics

The procedures in this section let you produce graphics that summarize the status of maps and
documents within the project.
In addition to the summary graphics, you'll also find a description of the workload statistics that
are visible in Project Management view.
View map statistics

The map statistics feature displays a pie chart that shows the number of documents that have
arrived at each status point.
Note: The total number of documents is the sum of:
• The parent map file

• Topics referenced by the parent map
• Images referenced by the topics
• All referable-content topics used by the topics
• Sub-maps referenced by the parent map
• All topics, images, referable-content topics, sub-maps etc. referenced by these sub-maps
To view map statistics:

• In the DITA Map view or DITA Map Editor, click the Show statistics button ( ).
• In Project Management view, right-click any map and then select Show Statistics.
View statistics for all maps

This feature produces graphics that summarize the status of documents in all maps in a project.
The feature is similar to View map statistics, only it produces a summary pie cart showing the
status for all documents in all the maps in a project. This is in addition to individual pie charts for
each of the maps. You can scroll through this window to see the various graphics.
To view statistics for all maps:
• In Project Management view, right-click on the Deliverables node and then select Show
Statistics.
View project milestone statistics

This feature produces a graphical summary of the milestones for your project, as well as for
individual maps.
It produces a bar chart that summarizes the milestones that you have configured for your project
and gives you an overview of the number of maps that have arrived at each status point.
The project-wide milestones appear at the top of the chart. Map-specific milestones are shown
in a different color at the bottom of the chart.
The illustration below shows the graphic produced for a project containing four maps. The pink
bars show the milestones configured for the project as a whole. The blue bars show the milestones
configured for one specific map: Bicycle Upkeep.
The green bar inside each pink bar represents the number of maps that have reached that status
point. You can see that two of the maps in the project have reached Authoring:review, and that
the same number have reached Authoring:accepted. One map has arrived at Authoring:done,
and none has yet been Published.
Note: States and status points are installation-specific. Those shown in the illustration
are the ones used at IXIASOFT Technology and may differ from the ones used in your
working environment.
To view project milestone statistics:
• In Project Management view, right-click anywhere on the Project and select Show
Project Statistics.
The project statistics display appears.
Team overload indicators

This feature lets coordinators quickly assess the document assignment levels of all team members.
When you expand the Team item in Project Management view, you see the number of documents
assigned to each member. This lets you see if anybody is overloaded.
Team workloads are displayed in two different ways, depending on whether a maximum workload
has been set during DITA CMS configuration.
• If no maximum workload has been set for a given role, Project Management view simply shows
the number of documents assigned. In the screen shot below, you can see that the team
member has one document assigned to him in the role of Project Coordinator.
• If a maximum workload has been set for a role, then the workload displays as a percentage
of the maximum. In the screen shot below, you can see that three of the team member's roles
have been configured that way: Author, Information Architect, and Reviewer.
Maximum workload is the maximum number of documents of a given type that an individual can
be assigned in a given role. This number is configurable and may be different in your installation.
Note: The numbers shown in Project Management view reflect all of a team member's
assigned documents in all projects in the repository. It includes documents that are
Incoming, Active, and Retained.
Overload warning colors
By default, DITA CMS is configured to display the following colors under the following workload
conditions:
• Black - the team member is assigned less than 80% of their configured maximum workload.
• Yellow - the team member is assigned between 80 and 100% of their maximum workload.
• Red - the team member is assigned more than 100% of their maximum workload.
The numbers and colors are configurable and may be different in your installation.
Delete a project
You can delete a project if it's no longer required.
You can delete a project from the Search Results view or from the Project Management view.
To delete a project:
1. In the Search Results or Project Management view, right-click the project and select
Delete.
The Delete Documents window is displayed.
2. (Optional) Click Yes.
The project is deleted.
27 Creating and generating
reports
Creating and generating reports
Topics: You can create and generate reports using the DITA CMS.
• Understanding reports
• Create viewpoints
• Create a TEXTML Server
query
• About reports
• Generate a report manually
• Generate reports using the
Scheduler
Understanding reports
This section provides an overview of reports and describes how to generate them using the DITA
CMS.
What are reports?
A report contains all the information generated from a saved TEXTML search query in DITA CMS.
The search results are presented according to a defined viewpoint, which arranges the search
results into groups and displays them using a defined set of columns. The report is generated
as an HTML output using an XSL transformation template.The following diagram shows a sample
report:
Generating reports
There are two ways to generate search reports:
• Manually from the DITA CMS: In this scenario, a report is generated directly from the search
query panel (Search > Queries > Reports).
• Automatically using the Scheduler: In this scenario, a report is scheduled at a specific time
interval and the report is generated as a Scheduler job. The Scheduler reviews the Content
Store for any scheduled reports. If there are reports scheduled, the Scheduler retrieves all the
relevant information (for example: query name, viewpoint, etc.) about each report and processes
the reports according to their scheduled entries. The Scheduler service must be configured
and running for the report to be generated. The report is sent as an email to a specified list of
recipients.
Creating and generating reports 481
To generate a report you:
1. Create a viewpoint.
2. Create a TEXTML Server query.
3. Create a report.
4. Generate the report manually or automatically (using the Scheduler).
This section shows how to generate a sample report using the Topics in Authoring:work search
criteria.
Create viewpoints
To create a report you have to create a viewpoint.
A viewpoint is a combination of grouping fields and display columns that allows you to organize
search results. They are useful when you are performing broad searches that produce a large
number of search results. When a viewpoint is selected, the search results are automatically
arranged into fields and displayed according to specific columns.
To create viewpoints:
1. In the DITA CMS, click the Search Results tab to display the view.
2. In the Search Results view, click the Manage Viewpoint button ( ).

The Manage Viewpoints window appears. For example:
3. Click Create Viewpoint ( ).

The Viewpoint Name window appears.
4. Enter a name to identify the viewpoint, then click OK.
For example:
The new name appears in the Viewpoints list and the Available Fields list is populated with
all the available fields to create groupings.
Figure 63: Manage Viewpoints window
5. Select the Grouping Columns tab to add your columns.
6. From the Available Fields panel, select a field, then click the Add button ( ).
Your selection moves to the right-hand pane. You can make multiple selections by holding
the SHIFT or CTRL keys and clicking a field.
7. Use the Move Up ( ) or Move Down ( ) button to organize the desired grouping
order.
8. Select the Display Columns to add display columns.
9. From the Available Fields panel, select a display column, then click the Add button
( ).
Your selection moves into the right-hand pane. You can make multiple selections by holding
the SHIFT or CTRL keys and clicking a column.
10. Use the Move Up ( ) or Move Down ( ) button to organize the desired display
order.
11. Click OK.
Your new viewpoint is now available in the Search View Results.
Use viewpoints in search results

To use viewpoints in search results:

Your search results are displayed in the Search Results view. An example of the search
results without viewpoint is displayed.
3. In the Search Results view, click Select viewpoint from the drop-down list and select
a viewpoint.
The search results are organized into folders and display columns according to the viewpoint
selected. The example below shows the viewpoint display of the Maps in Authoring:work
search results grouped by the following fields: title, status, and last mod by. The results are
also displayed in columns according to the selected columns. Click a folder to display the
documents within it.
4. To exit the viewpoint mode, click the Select viewpoint drop-down list and select None.
Create a TEXTML Server query

To create a report you need a TEXTML Server query.
A TEXTML Server query retrieves documents from the Content Store that correspond to a specified
set of search criteria. You save a TEXTML Server query to store search parameters that you use
frequently so you can re-use them.
To create a TEXTML Server query:
1. Set up a search in the Search view.

For example, the following diagram shows the search criteria for Topics in Authoring:work.
2. To save the criteria as a TEXTML query, click the Save TEXTML Query button ( ) and
enter a descriptive name.
Note: (Optional) If a viewpoint is already selected in the viewpoint drop-down list, the
Save viewpoint with query option is available. Click this option to save the TEXTML
query with the currently selected viewpoint.
For example:
3. Click OK.
The query is saved under Personal Textml in the Queries panel.
About reports
This feature allows users to generate reports based on queries that they have created. The report
contains all the required information to generate reports from the saved TEXTML Server query
in the DITA CMS.
Reports are created with the Create report editor as shown below:
Figure 64: Create report editor
The Create report editor has the following tabs:
• Report: Specifies all the information required to create a report.

• XML: Provides the XML view of the report. You cannot modify the XML source.
A Report contains four sections:
1. General Information: Select the query, viewpoint, and XSL transformation template used to
convert the report to an HTML output, as follows:
Field Description
Report name Name given to the report.
State Select one of the following:
• To generate the report, select Enabled.

• Otherwise, select Disabled. This is useful when you are working
on a report and do not want to generate it right away.
Query Shows all the saved TEXTML search queries. Choose the search
query of your choice.
Field Description
Viewpoint Shows all the available viewpoints. Choose the viewpoint of your
choice.
Note: The color of the Viewpoint field indicates its status,
as follows:
• Red: No viewpoint is selected. The report cannot be

Enabled without a viewpoint.
• Purple: A valid viewpoint is selected, but it is different from
the one saved with the TEXTML Server query.
• Black: The viewpoint selected matched the one in the
TEXTML Server query.
XSL template Shows all the available templates used to convert the report to
HTML. By default, only the report2html.xsl XSL template is available,
but additional templates may have been added for your deployment
by your CMS System Administrator. Select the template to use for
this report.
Note to CMS System Administrators: XSL templates are stored

in the Content Store's Repository at the following location:
/system/xsl/report.You can customize the existing template or create
multiple ones as appropriate for your deployment. When you add
templates to the location above, they are listed in the XSL template
field.
Attach Dataset Select this option to receive the report.xml, xslTemplate.xsl,

textMLQuery.tql, Output.xml, and Output.tsv files as attachments
along with the report sent as HTML in the email notification.
2. Notify: You can enter a list of all emails that should receive the generated report.
Field Description
Email Email address of the person to notify when the report is

completed. This does not have to be a DITA CMS user. You
can enter multiple addresses.
Field Description
Type The email can be sent directly, as a carbon copy (cc), or as a

blind carbon copy (bcc).
3. Parameters: You can define the value of parameters used for the report. These parameters
are contained in the selected XSL template.
Field Description
Key Parameter name.
Value Value of the parameter.
4. Schedule: The Schedule allows you to specify the interval at which the report will run. It is a
combination of minutes, hours, days, months, and weekdays.
Note: This section is only applicable to scheduled reports and requires that the
Scheduler be installed and running.
Field Description
Value Enter the exact time to schedule the report.

Note: The scheduled value converts to a cron job:
<schedule>minute hour day month
weekday</schedule>
Description Choose the time interval: minutes, hours, days, months, or days
of week.
The table below describes various available options for the Value field in the Schedule section.
Examples for scheduling in minutes is shown, along with their respective Cron jobs. The
scheduling can be extended to hours, days, months, and weekdays.
Table 6: Schedule values, value description, example for scheduling in minutes, and
the respective Cron job
Value Description Example - Cron job

Schedule in
minutes
Any Runs every minute Every minute <schedule>* * * * *

</schedule>
Fixed Runs at a fixed time At 2 minutes past the <schedule>2 * * * *

hour </schedule>
Range Runs within a certain time Between 0 through 5 <schedule>0-5 * * * *

range minutes past the </schedule>
hour
List Runs at all the listed times At 1,3,5,7,and 9 <schedule>1,3,5,7,9 * * * *

minutes past the </schedule>
hour
Repeated Job repeats itself Every 2 minutes <schedule>*/2 * * * *

</schedule>
Note:
For more information about all available Cron options, see the following URL:
http://www.sauronsoftware.it/projects/cron4j/manual.php#p02
Create a report
The following procedure describes how to create a report.
Before creating a report:
• Create a viewpoint.
• Create a TEXTML query.
1. In the Queries panel, right-click the Reports folder.

The Create report option appears.
2. Click Create report.

The Create report dialog appears.
3. Enter a Report name, select Open report in default editor, and click OK.
For example:
The report is created and opened in the DITA CMS, as shown below. The report name is
displayed:
Note: The created report can also be viewed in the Queries panel.
4. Enter the required information in the report.

5. In the General Information panel:
You first have to choose a Query and a Viewpoint before enabling the report.
a) Choose the relevant Query from the drop-down list.
b) Choose the relevant Viewpoint from the drop-down list.
c) In the State field, select ENABLED to receive a report.
d) In the XSL template field, select the template.
e) To receive the dataset in the email, select Attach Dataset.
For example:
6. In the Notify panel, enter the list of all emails that should receive the generated report.
To add email recipients:
a) Right-click Email to add, delete, and modify email details.
For example:
b) Choose Add to add a new email to the list.

A Notify window opens. For example:
c) Enter the Email and choose the Email type from the drop-down list.
d) Click OK.
For example:
7. In the Parameters panel, enter the parameters that are required for the report.
Note: Both the Key and Value are configurable from the report2html.xsl template.
However, from the Parameters panel only the Value is modifiable.
To modify the Value:

a) Right-click Value.
b) Click Modify to modify the Value.
The Report parameters window opens.
c) Enter the Value.
For example:
d) Click OK.
For example :
8. In the Schedule panel, specify the time interval at which the report will run. To specify
the values:
a) Double-click the Value field on the line that you want to configure.
For example, to set the minutes for the job double-click Value on the Minutes line. The
following dialog appears:
b) Choose the preferred time from the available options.

c) Repeat these steps to set the Hours, Days, Months, and Days of week for the report
to be sent.
In the following example the report is scheduled for 8:00 AM every day.
9. Save and close the report.
An example of the final report is displayed below:

Generate a report manually

Generating a report manually is very useful to test that the report includes the correct information.
To manually run a report:
1. Select and right-click the report you want to run from the search query panel (Search >
Queries > Report > ) folder.
2. Choose Run now from the selection.
Once generated, the report is opened using the default HTML browser of your operating
system. For example:
Generate reports using the Scheduler

Reports can be generated automatically by setting the Schedule information when creating a
report.
The Scheduler must be running for this feature to work. Contact your CMS System Administration
to confirm that a Scheduler is running and configured to generate reports.
28 BIRT Reports
BIRT Reports
Topics: DITA CMS lets you perform data-mining operations on the

• Install the BIRT feature TEXTML Content Store for use with the report-generating
• Preparing data for use with capabilities of the BIRT Report Designer.
the BIRT Report Designer
• Overview of the BIRT report
process
• The Data Set Definition
dialog
• Create the DITA CMS data
set definition
• Modify a DITA CMS data set
definition
• Create the DITA CMS data
source
• Create a new BIRT project
• Create a new BIRT report
• Obtain data source
directory location
• Create a new BIRT data
source
• Create a new BIRT data set
• BIRT example one:
generating a report
• BIRT example two: using
stamp information
Install the BIRT feature

Use this procedure to install the open-source reporting tools.
The Eclipse IDE should be installed and configured.
DITA CMS offers you the option of producing reports and graphs from the data in your repository.
To do this you must download and install the Business Intelligence and Reporting Tools (BIRT)
developed by the Eclipse community.
1. Click Help > Install New Software... from the menu bar.
The Available Software dialog appears.
2. Click Add....
The Add Site dialog appears.
3. In the Name field, enter Eclipse BIRT.
4. In the Location field, enter the following URL.
For example:
http://wiki.eclipse.org/BIRT_Update_Site_URL
5. Click OK.
The Available Software dialog displays your new site.
6. Select the items to install.
7. Click Next.
The Install Details dialog appears, displaying the features that will be installed.
8. Select the set of features you want to install, then click Next.
The Review Licenses dialog appears.
9. Select I accept, then click Finish.
Software installation begins.
When software installation is finished, you will be asked if you want to restart Eclipse.
10. Click Yes.
Eclipse restarts and opens. You can now open the Report Design Perspective.
Related Links
BIRT Reports 499
Preparing data for use with the BIRT Report Designer

Before you can begin to create a BIRT report, you need to prepare your data in the DITA
Perspective.
The process begins with a personal TEXTML query, which you can save from the Search view.
This establishes the broad framework of the information you want to extract from the Content
Store. For example, you might run a query on all topics that are in the Localization cycle. You
could then edit that query to restrict your search to a specific set of topics: concepts, for example.
The next step is to create a data set definition, based on this query, to extract specific information
such as the number of times each topic is going through review. Or to find the number of
auto-translated segments in each topic.
Once you've created your data set definition, you can use it to output the data source file. DITA
CMS creates its data source files in TSV format. These are the files that you select from the
Report Design Perspective when you create a new data source for a report.
Related Links
Overview of the BIRT report process on page 499
Overview of the BIRT report process

BIRT report production begins in the DITA Perspective with a TEXTML query and finishes in the
Report Design Perspective.
1. Create the DITA CMS data set definition on page 505
2. Create the DITA CMS data source on page 507
3. Create a new BIRT project on page 508
4. Create a new BIRT report on page 508
5. Create a new BIRT data source on page 510
The Data Set Definition dialog

The Data Set Definition dialog lets you create complex XML-based queries without having to go
in and edit the code by hand.
This is where you specify the information that will be written into the DITA CMS Data Source.
The columns that you define in this dialog ultimately become the columns in your BIRT data set.
In the Data Set Definition dialog, you select the columns of information that you want to extract
from the TEXTML indexes. You can then specify the operations you want to perform on each
column, and then filter this information to extract even more specific information.
Note: Each row in this dialog defines a column in the corresponding data source.
Related Links
Create the DITA CMS data set definition on page 505
About the columns in the Data Set Definition dialog

The columns that are available for selection in the Data Set Definition dialog reflect indexes in
TEXTML Server. You’ll be familiar with a lot of them from the Search results and DITA Map view
– ID, Title, Status, etc.
There are others that return values that you’ll also find useful when you’re analyzing document
production in your facility. The exact selection varies with each installation. Some typical examples
are shown below.
BIRT Reports 501
• Localization Segment Count – returns the number of translatable segments in your document.
If you look at the XML, these segments are identified with an ixia_locid attribute.
• Localization Autotranslated Segment Count – returns the number of segments where the
system supplied the text for the translation, i.e., the text hadn't changed from the previous
revision.
• Collection – identifies a collection in the repository: content\authoring, for example.
Stamp-related columns
Several columns return information from a document’s custom properties.
Stamp information is read from the custom properties that are written into all documents in the
Content Store.You can see some of it in System Comments if that column is displayed in Search
Results. This information is generated by all actions that modify a document, such as changed
status, modifications, etc. It contains information such as the action performed, the complete date
and time, and the user who performed the action.
Four columns extract information from the stamp:
• Authored by – extracts the name of the person who promoted the document into the review
cycle. This information is useful for finding out how many documents a writer is producing.
• Authored Stamp – in addition to the person who promoted the document into the review cycle,
this column returns the date it was done. This lets you perform analyses on, say, how many
documents are being produced in a particular month by the writers on your team.
• Modification dates – extracts all the dates when a document was modified. You can use this
information to analyze the number of revisions that documents are going through in a given
time period.
• Stamp – returns changes of status, the dates they were performed, and the users that performed
them. Unlike Authored Stamp and Authored by, this column extracts information from documents
in all cycles.
Supported Data Set Definition dialog operations by column

Each column in the Data Set Definition dialog offers you operations that you can perform on the
data you're extracting from the repository.
The operations that are available in the Data Set Definition dialog depend on a column's position
and the choices you've made in the columns above it. Not all columns support the same set of
operations.
First Column
When you configure your first column (that’s the first row in the table), you have the following
choices:
• List all values – produces a list of the required values in the final data set.
• Group on values – groups values according to the number of documents that fit the selected
criterion.
Second Column
Your choice of operations in the first column largely determines what’s available for selection
when you configure your second column, whatever sort of column you’re configuring, be it Type,
Status, Language, or whatever.
• If you chose List all values in the first column, then you’ll only be able to choose List values.
• If you chose Group on values, then you’ll only be offered Also group on values.
Numerical columns such as File size, on the other hand, also offer you the Calculate operation.
And the ID column supports the following three special operations (in addition to List and Group):
• Calculate parent maps – which returns how many maps reference a given document.
• Calculate parent references – which calculates how many documents other than maps refer
to a given document. This includes hrefs and conrefs.
• Calculate child references – which calculates how many child documents a given document
references. This includes hrefs, conrefs, and references by resources.
Third and subsequent columns
These columns only support the List operation. They’re useful when you want details about the
previous columns, such as titles, file names, and so forth.
Available filters in the Data Set Definition dialog

Some of the Data Set Definition dialog's columns let you filter their output.
After you’ve selected the operation you want to perform on a column, you may want to further
refine or manipulate the value by applying a filter.
The following columns support filters:
• The members of the Stamp family let you extract sub-sets of the information they return, such
as the user that performed a specific action, or the year and month an action was carried out.
BIRT Reports 503
• Columns that return numerical information (such as File Size) offer you the following
calculations:
• Average
• Max
• Min
• Total
• The ID column includes a filter called “Greater than 1 count”. This filter appears when you’re
calculating the number of parent map references. Most topics will have one parent map; it’s
the ones that are referenced by more than one map that are statistically interesting.
Auto-generated columns in the BIRT (and DITA CMS) data sets

When you select the Group by values operation in the first column of the Data Set Definition
dialog, DITA CMS automatically generates several additional columns that will be available as
data set columns when you are working in the BIRT environment.
• Documents Count – gives you the number of documents returned by the grouping operation
in the first column. Or by the combined criteria of columns one and two, if you’re grouping by
two sets of criteria: documents per writer per month, for example.
• Running Count – totals the values in the Count column in subsequent cells.
• Values Count – gives the number of values, as opposed to the number of documents, returned
by the first column.
You can see them in the CMS data source TSV file.
Documents Count and Running Count
You can see these columns if you open a DITA CMS data source that’s been produced using a
grouping operation in the first column. DITA CMS data sources are stored as TSV files, which
you can easily open in a spreadsheet application.
The image below shows the TSV file produced if you select Creation Date for your first column
and then apply the Group by values operation. It's also filtered to show the results by Year-Month.
• The first column (column A) contains all the months when documents were created. These
range from September 2006 (2006-09) through September 2007 (2007-09).
• Column D (Documents Count) shows the number of documents that correspond to the criteria
in column A. In the first row, we can see that 114 documents were created in 2006-09.
• Column E (Running Count) progressively sums the Document Count entries. The last entry
at the bottom of this column is the total number of documents that meet the criteria – 286.
Values Count
For many grouping operations the Values Count will be the same as the Documents Count. This
is the case for the example like the one shown above—there’s never more than one creation
date for a document.
But queries on stamp-based information may give you interesting results. The example below
shows the values returned by a query on the Authored Stamp.
The Authored Stamp returns information which includes not only the date that a document was
put into the review cycle, but the number of such events. If the document is put into the review
cycle ten times before it's approved, then there will be a total of ten date values.
If we look at the first data row, we can see that in May of 2009 (2009-05), 6 documents were put
into the review cycle – that's the number in the Documents Count column.
We can also see that the query found 25 occurrences of the date stamp in the documents – that's
the number in the Values Count column.
Taken together these values indicate that each of these documents are going through the review
process an average of four times apiece. This is one sort of analysis that you could perform on
these figures; there might be others.
If you wanted to get a clearer picture of the process, you could set up your data set definition to
first group by Year-Month, and then group by User. This would give you the number of times
each writer needs to send a topic through review before it is approved.
BIRT Reports 505
Create the DITA CMS data set definition

A data set definition sets up the criteria that produce your data source.
A TEXTML query must be defined.
A data set definition is, basically, an advanced form of XML query. Once you've defined an
underlying XML query, the Data Set Definition dialog lets you extract information from specific
columns.
1. If necessary, open the DITA Perspective.

2. In the Queries panel of the Search view, expand one of the TEXTML items to display
its queries.
You can base a Data Set Definition on either a Personal TEXTML or a Shared TEXTML
query.
3. Right-click the TEXTML query you want to use as your starting point, and select Data
Set Definition.
The Data Set Definition dialog appears.
4. Enter the TSV File Name.
Use the file naming convention that applies on your system. The .tsv extension will be added
automatically.
5. From the Available columns list, use the Add and Remove buttons to move desired
items into the Show columns in this order list.
Each row in the Available columns list defines a column in the data source TSV file.
See About the columns in the Data Set Definition dialog.
6. Under Operation select the operation you want performed on the first column of the
data set.
If you are configuring the first column (that's the first row here in the table), you have the
following choices:
• List all values

• Group all values
Your choice of operations for the first column will determine the operations available for
subsequent columns.
See Supported operations by column.
7. Under Filter select the subset of information that you want to extract from the column.
Several columns, such as Stamp, contain complex information fields that you can utilize in
different ways.
Other columns – those that contain numerical values – let you extract information such as
Maximum and Minimum, or support calculations such as Average.
See Available filters.
8. Click Save.
A new data set definition appears under the Data Set Definition item in the Queries panel.
The item will have the same name as the ultimate TSV file, but will have the extension .xml.
For example, a data set definition that's going to produce the data source
"Language_stats.tsv" will be called "Language_stats.xml".
You can now use this data set definition to create a DITA CMS data source.
Related Links
The Data Set Definition dialog on page 499
BIRT example two: the DITA CMS data set definition on page 521
BIRT example one: DITA CMS data set definition on page 513
Modify a DITA CMS data set definition

You can modify existing data set definitions and save them under another name.
Once you've defined a data set that extracts the information that you want to analyze and chart,
you may want to modify it in minor ways.
Note: If you change the TSV file name, this will create a new data set definition. If you
change the column definition information without changing the TSV file name, you will
overwrite the existing data set definition.

2. In the Queries panel of the Search view, expand the Data Set Definition item.
3. Right-click the data set definition you want to use as your starting point, and select
Data Set Definition.
The Data Set Definition dialog appears.
BIRT Reports 507
4. If you wish, enter a new TSV File Name.

When you enter a new file name, you'll create a new data set definition.
5. Modify the columns and operations as necessary.
See About the columns in the Data Set Definition dialog.
See Supported operations by column.
See Available filters.
6. Click Save.
If you changed the TSV file name, then a new data set definition appears under the Data
Set Definition item.
If you kept the original TSV file name, then your original data set definition will be overwritten.
In both cases you will need to generate a new DITA CMS data source.
Related Links
Create the DITA CMS data source on page 507
Create the DITA CMS data source

After you create the data set definition, you use it to generate the DITA CMS data source.
The data set definition must already exist.
DITA CMS creates its data source files in TSV format.You can open these files in any spreadsheet
application if you want to review their contents.
1. In the Queries panel of the Search view, expand the Data Set Definition item.
You can see the existing data set definitions.
2. Right-click the required data set definition and select Generate Data Set.
A data source with the same principal file name as the data set definition that produced
it appears under the Data Source item.
For example, the data source "Language_stats.tsv" is produced by the data set
"Language_stats.xml".
The image below shows an example of a TSV file.

Related Links
BIRT example two: the DITA CMS data source on page 522
BIRT example one: DITA CMS data source on page 514
Create a new BIRT project

BIRT reports must be stored in a project folder.
If you have never created any project folders within BIRT, you should do so before you create
your first report.
1. If necessary, open the Report Design Perspective.

2. From the menu bar, select File > New > Project.
The New Project - Select a Wizard dialog appears.
3. Expand the Business Intelligence and Reporting Tools item and select Report Project.
4. Click Next.
The Report Project dialog appears.
5. Type in the Project name.
6. Click Finish.
Your new project folder appears in the Navigator view.
Create a new BIRT report

This procedure describes how to create a new report within your BIRT project folder.
You must have a project folder available in BIRT.

2. From the menu bar, select File > New > Report.
The New Report dialog appears.
This dialog displays your BIRT project folders.

BIRT Reports 509
3. Select the project folder from the collapsible tree.

Important: The REPOSITORY folder is used by the DITA CMS system. Do not use
this folder to store reports.
The project folder's name appears in the Enter or select parent folder field.
4. (Optional) Append a new subfolder name to the project folder in the Enter or select
parent folder field.
The system can create a subfolder of your project folder at this time. Use the file and path
naming conventions for your system.
5. In the File name field, enter the name you want to use for your new report.
6. Click Next.
The second New Report dialog appears.
This is where you choose the underlying layout of the report.
7. Use the Report templates list to select the template you want to use.
The Preview panel and Description will give you an idea of what the selected template does.
8. Select the required Report Orientation.
9. Click Finish.
Obtain data source directory location

This procedure gives you a quick way of obtaining the full path of the DITA CMS data source for
use within the Report Design Perspective.
When you create a BIRT data source, you'll need to specify the location of your DITA CMS data
source inside the repository. You can obtain the data source location from the Data Source item
in the Queries panel of the DITA CMS Search view.
The data source directory is automatically created in your local copy of the repository when you
create your first data source TSV file.

3. Right-click the Data Source item, and select Copy > Copy Local Folder Path.
The full path to the data source directory in your local repository is copied to the clipboard.
You can paste this into the dialog where you specify the location of the BIRT data source.
C:\Users\malerm\workBIRT\REPOSITORY\ericm\marackix2\delenda\datasource\
Create a new BIRT data source

Once you have created a report design, you connect it with the data source you want to use.
The report design must be open in the editor area.
The TSV data source that you created in the DITA Perspective becomes your data source in the
Report Design Perspective. This procedure shows you how to locate the TSV file and create a
new BIRT data source.

2. In the Data Explorer view, right-click the Data Sources item and select New Data Source.
The New Data Source dialog appears.
3. Click the Create from a data source in the following list radio button.
4. In the list, highlight Flat File Data Source.
5. In the Data Source Name field, enter the name you want to use.
6. Click Next.
The New Flat File Data Source dialog appears.
7. Use the Select folder field to locate the data source folder. Either:
• Click the Browse button and then navigate the tree structure to the data source directory,
OR
• Enter the full path to the data source directory.
Tip: You can get the path from the Data Source item in the DITA Perspective's
Search view. See obtain the data source directory location.
8. From the Select charset list, select UTF-8.

9. From the Select flat file style list, select TSV.
10. Click Finish.
The new data source appears under the Data Sources item in the Data Explorer view.
You must now create the BIRT data set.
Related Links
BIRT example one: BIRT data source on page 515
BIRT Reports 511
Create a new BIRT data set

After you create your BIRT data source, you select the data set columns that you want to use in
the current report.
• The report design must be open in the editor area.
• A data source must linked with this report design.
Once you've selected the set of columns, you can order them as you wish, rename them
or change their data type as appropriate.

2. In the Data Explorer view, right-click the Data Sets item and select New Data Set.
The New Data Set dialog appears.
You'll see the Data Sources associated with your report design in the Data Source Selection
pane.
3. Select the DITA CMS data source you want to use.

BIRT lets you combine data from various sources, but this procedure deals only with connecting
with data sources generated in DITA CMS.
4. From the Data Set Type list, select Flat File Data Set.
5. Enter the Data Set Name you want to use.
6. Click Next.
The Select Table dialog appears.
7. In the File filter list, make sure that *.tsv is selected.
8. From the Select file list, choose the TSV file you want to use.
The columns in the selected TSV file appear in the left-hand pane.
9. In the left-hand pane, double-click the columns that you want to use in your report.
The selected columns appear in the right-hand pane.
You can reorder the columns using the up and down arrows on the right of the dialog.
10. Select the Type.

DITA CMS data is output as strings. You have the option at this point of converting columns
(such as Count) into integer or other numerical representations for use in calculations within
BIRT.
11. Click Finish.
The Edit Data Set dialog appears.

12. You can use the Edit Data Set dialog to further modify your data set or to preview its
results.
13. Click OK.
Your new data set appears under the Data Sets item in the Data Explorer view. You can
expand your new data set to display the selected columns.
You can now start to bind your data set elements to your report design.
Related Links
BIRT example one: edit BIRT data set on page 516
BIRT example one: preview BIRT data set on page 517
BIRT example one: generating a report

This example illustrates the entire process of generating a BIRT report.
You'll see the use of grouped output, showing all the processes you’d follow from the original
TEXTML query through to the final BIRT report.
In this example we’ll create a chart that shows the number of each different types of document
that are in the repository – concept, image, task, etc. – and the average file size of each type.
The chart will also show the maximum and minimum file sizes for each document type.
BIRT example one: TEXTML query

The process starts with a TEXTML query.
You could start with a search for all documents, which you’d save as a personal TEXTML query:
Author-topics.tql. In the screenshot you can see that query open in the editor area of the
workspace.
The screenshot also shows the selections on the right-click menu of the query: one of them is
Edit – that’s how you open the query in the editor area. Another selection is Dataset Definition –
that’s how you’ll open the dialog where you define the data set for the first time.
BIRT Reports 513
BIRT example one: DITA CMS data set definition

The next step is to define the data set inside DITA CMS.
After you've created your basic TEXTML query, you define the data set you want to extract. This
is done in the Data Set Definition dialog. This is where you define the values you want to extract
from the indexes of the TEXTML Server, and the operations you want to perform on each set of
values.
You’ll see the Data Set Definition dialog for the first time when you launch it from a personal
TEXTML query. You can go back later and modify the data set definition directly.
In the image below you can see the columns that we’ve selected for this data set and the
operations we’re going to perform on each.
• Column one – returns how many documents of each type are in the repository, and groups
them by type.
• Column two – calculates the average size of each type of document.
• Column three – calculates the maximum size for each type.
• Column four – calculates the minimum size.
At the top of the dialog, you can see that we’re going to use this data set definition to produce a
file called Aut_size_v3.tsv. This file will be our data source.
Related Links
BIRT example one: DITA CMS data source

From the data set definition you generate the data source.
After you’ve saved the DITA CMS data set definition, you can generate your DITA CMS data
source – Aut_size_v3.tsv. You’ll see it as an item under the Data Sources item in the Search
view.
You can click the file and open it in a spreadsheet application (if you’ve associated the extension
*.tsv with that application).
The image below shows what the data set definition has extracted from the repository. You can
see the various columns and the values in each of them. This is the TSV file that you’ll use as
your BIRT data source in the Report Design Perspective.
BIRT Reports 515
Everything up until this point has been done in the DITA Perspective, but after this you’ll need to
switch to the Report Design Perspective.
Related Links
BIRT example one: BIRT data source

After you've finished defining your DITA CMS data source, you'll move on to defining the data
source in BIRT.
From this point on you are working in the Report Design Perspective.
After you’ve set up your report design, you need to connect it to the DITA CMS data source. The
image below shows the dialog that you can use to browse for the TSV flat file data source in the
repository. This becomes your BIRT data source. You’ll see it under the Data Sources item in
the Data Explorer view.
Related Links
Create a new BIRT data source on page 510
BIRT example one: edit BIRT data set

The next step is to define the BIRT data set.
After you’ve defined the data source, you select the specific set of data that you want to use.
There are two dialogs that guide you through this process.
The first dialog is where you select the data source and give your data set a name. If you’re just
using a single DITA CMS data source, and you’ve set it up as outlined in BIRT example one:
BIRT data source, it will already be selected.
The second dialog is where you actually choose the data columns that you want to incorporate
into the report. This dialog shows the following:
• The TSV data source file appears at the top: Aut_size_v3.tsv.

• The columns that are defined inside the data source appear in the left hand pane.
• The columns you’ve selected are in the right hand pane.
You can see in the image below, that we’re not using all the columns that are available.
BIRT Reports 517
Related Links
Create a new BIRT data set on page 511
BIRT example one: preview BIRT data set

After you've defined the data set, you have the option of previewing the output.
When you finish selecting columns, the Edit Data Set dialog appears. The screenshot below
shows a preview of the data items that we’ve selected in this example.
There are further options in the left hand pane of the dialog for modifying the data items you’ve
selected, but we’ll leave these for another example.
Related Links
Create a new BIRT data set on page 511
BIRT example one: incorporate data into report design

When you’ve finished editing your data set, you’ll see it displayed in the Data Explorer view.
In the screenshot below, you can see the new report open in the editor area. Its associated Data
Source and Data Set are displayed at the left in the Data Explorer view.
Now you can proceed with binding the data and laying out your report. When you’re finished, this
report will produce a chart which you can see in BIRT example one: final output on page 520.
BIRT Reports 519
BIRT example one: final output

This is the output produced by BIRT example one.
BIRT Reports 521
BIRT example two: using stamp information

This example uses information from the Authored Stamp to compare the review rates of different
writers.
Stamp information is read from custom properties that are written into all documents in the
repository. In this example we’ll use the Authored Stamp, which returns the person who promoted
the document into the review cycle, and the date (or dates) when this was done. We'll use this
information to make a comparison between the review rates of various writers.
BIRT example two: the DITA CMS data set definition

In this example we'll use the Authored Stamp two different ways in successive columns.
When you are defining a stamp-based column, you are offered a choice of filters that let you
extract subsets of the information it returns. In the example below, you can see that in each data
column we’ll be extracting a different portion of the Authored Stamp.
The Authored Stamp returns all the dates when a document was promoted into the review cycle,
and the name of the user (or users) that performed the promotion.
• The first column of our data set definition extracts the year-month portion of the date.
• The second column extracts the user name.
You can also see the TEXTML query that the data set definition is based on. It’s simply a query
for all topics in the Authoring cycle.
Related Links
BIRT example two: the DITA CMS data source

After the data source is generated, you can open the file in any spreadsheet application and look
at it.
With the TSV file open in the spreadsheet application, we can see the contents of the first two
columns:
• The first column contains all the months when documents were promoted.This is the year-month
portion of the Authored Stamp.
• The second column shows the users who performed the promotions in that month.
As you’d expect, there are months when several writers are promoting their documents into
review: rows 6 and 7, for example.
BIRT Reports 523
The auto-generated columns
The Document Count and Values Count columns are auto-generated for any grouping query
The Document Count column shows the number of documents returned by the combined grouping
criteria of the first two columns (columns A and B). In this case it's the number of documents that
were promoted in any given month by each writer.
The Values Count, however, is where things get interesting. This column reflects the number of
times that the documents were promoted into the review cycle. (It counts the number of dates in
the stamp.)
In some months (for some writers) the number is the same. In row 5, for example, you can see
that 33 documents went into review 33 times. Basically, they’re going into review and they’re not
coming back. Row 2 shows a values count of 27 and a document count of 26 – one of the
documents went through a second time. Nothing unusual about that.
But if you look at row 11 you can see that in this month, writer Jones sent 97 documents into
review and all them went through a second time; if not a third. This could be caused by a variety
of reasons – Jones might be a new writer, or is dealing with particularly difficult subject material,
or is simply overloaded with work. But it pinpoints a possible area of difficulty and lets you address
it.
Related Links
BIRT example two: the BIRT data set part 1

After you’ve connected to the data source in Report Design perspective, you’ll define your data
set.
The screenshot below shows the dialog where you select the data columns that you want to use
for your report.
You’ll notice that for two of the columns that we’ve selected – Values Count and Document Count
– we’ve changed the Type to Integer. By default, all the values generated by DITA CMS are
returned as strings. We want to do a calculation in our report, so we’ve changed the data type
accordingly.

You have various options for editing your data set.
After you’ve selected and typed your columns, the Edit Data Set dialog appears. We’ve selected
the Computed Columns option on the left, and added a simple averaging calculation. This divides
the Values Count by the Documents Count to give you the average number of reviews a document
is going through.
BIRT Reports 525

The Edit Dialog includes a preview.
Here you can see the preview that we’ve generated in the Edit Data Set Dialog. Our computed
column – Average – appears at the right.
BIRT example two: the complete data set

You can see the data set in the Report Design Perspective.
Finally we can see the columns we selected, as well as the additional computed column, displayed
in the Data Explorer view.
Now you can proceed with binding the data and laying out your report. When you’re finished, this
report will produce a chart which you can see in BIRT example two: final output.
BIRT Reports 527
BIRT example two: final output

This is the output produced by BIRT example two.
29 Relationship tables
Relationship tables
Topics: These procedures tell you how to use reltables in DITA CMS.
• Open the Reltable Editing Reltables let you create dynamic linking between topics,
Perspective from the DITA without compromising reusability.
Map view's menu
• Open the Reltable Editing
Perspective from the main
menu bar
• The Reltable Editing
Perspective
• Construct relationship
tables
• Configure relationship
tables
• Locate reltable rows where
a topic is used
• Filter reltable rows in the
Table Display area
• Relationship table
examples
Open the Reltable Editing Perspective from the DITA Map

view's menu
This procedure opens the Reltable Editing Perspective from the DITA Map view's pull-down
menu.

2. Select Open Reltable Editing Perspective.
Open the Reltable Editing Perspective from the main menu

bar
This procedure tells you how to open the Relationship Table Editing Perspective.
• Click Window > Open Perspective > RelTable Editing from the menu bar.
The Reltable Editing Perspective

DITA CMS offers a view designed expressly for working with DITA relationship tables.
The Reltable Editing Perspective contains several views that you'll already be familiar with from
the DITA Perspective and from the Eclipse environment: the DITA Map and Properties views. It
adds to these the Relationship Outline view and Relationship Table Editor view.
Relationship Outline view
This view provides a quick way of locating all the reltable rows that contain a selected topic or
topics.
When you highlight a topic in the DITA Map view, all the rows and tables where the topic is used
will be listed in the Relationship Outline view.
where both topics appear together, followed by lists of the rows containing each topic by itself.
Relationship Table Editor
This view lets you quickly visualize the tables and constituent rows, as well as the cells and their
contents.
• The Table Display area shows the tables in your map as collapsible nodes with their rows
displayed beneath. You can right-click in this area to add and remove tables, rows, and cells.
• The Filter field provides a way of locating rows in the Table Display area. Enter any string,
and the Table Display area will show the rows whose names contain these characters.
• The Row Display area shows the contents of the row that's highlighted in the Table Display
area. The row name appears at the top. Each cell and its topics are displayed beneath. You
can right-click in this area to add and remove topic groups.
Related Links
Construct relationship tables

These procedures deal with the basics of setting up reltables.
Add a reltable to a map

This procedure creates a new relationship table in a map.
DITA CMS lets you insert a pre-formatted table of type CRT into a map. The CRT table has a
single row, which contains three relcells. Each of these relcells has its type attribute set to
concept, reference, or task, respectively.
Note: The exact configuration of available pre-formatted tables may vary with your
more information.
You can retype these cells as you wish or add cells and rows of other types, as you find convenient.
You can have as many reltables as you want in a single map.

2. Right-click in the Table Display area of the Reltable Editing view, then select New
Reltable > CRT Table.xml.
A dialog box appears, asking you to enter a name for the table.
A new table of the selected type is added to the map.
Add a pre-configured row to a reltable

Use this procedure to add a pre-configured row to a reltable in your DITA map.
DITA CMS lets you insert a pre-configured row of type CRT Row.xml into your reltables.This
type of row contains three cells, whose type attributes are set to concept, reference, or task,
respectively.
Note: The exact configuration of available pre-formatted rows may vary with your
more information.
The number of cells per row and their type are configurable and may vary with your setup.
2. In the Table display area of the Reltable Editing view, highlight the table where you
3. Right-click, then select Insert Row > CRT Row.xml.
A dialog box appears, asking you to enter a name for the row.
A new row of the selected variety is added to the reltable.

Related Links
Add an unconfigured row to a reltable

You can add a row that has none of its attributes set to a reltable in your DITA map.
There may be times when you want to work outside the restrictions of a pre-configured row. DITA
CMS lets you add row elements directly to a reltable, so that you can configure them the way
that best suits you.

2. In the Table Display area of the Reltable Editing view, highlight the table where you
3. Right-click, then select Insert Element > relrow.
A new untyped row is added to the reltable.
Note: After you've inserted the new row, it's a good idea to assign it a name. This allows
you to search for the row in the Table Display area.
Add a typed cell to a reltable row

You can add a pre-configured (typed) cell to a reltable row in your DITA map.
2. Right-click, then select Insert Cell > celltype.
where celltype is one of the following:
• concept.xml
• reference.xml
• task.xml
The choices available depend on your configuration.
A new cell of the selected type is added to the reltable row and appears in the Row Display
area.
Add an unconfigured cell to a reltable row

You can add a cell that has none of its attributes set to a reltable row.
DITA CMS lets you add relcell elements directly to a reltable row, so that you can configure them
the way that best suits you.
2. Right-click, then select Insert Element > relcell.
A new unconfigured cell is added to the reltable row and appears in the Row Display area.
Assign a name to a reltable

This procedure describes how to assign a meaningful name to a reltable.
When you crate a reltable, you specify its name, but you can change that name at any time after
the table is created.
1. In the Table Display area of the Reltable Editing view, highlight the table you want to
name.
2. In the Properties view, click in the entry field for the title attribute.
3. Type in the name you want to assign to the table.
The table name appears in the Table Display area.
Assign a name to a reltable row

This procedure describes how to assign a meaningful name to a reltable row.
When a reltable is created it will have a row named something like "Row 1". Use this procedure
to assign it a descriptive name.
1. In the Table Display area of the Reltable Editing view, expand the table that contains
the row you want to name.
2. Highlight the row.
3. In the Properties view, click in the entry field for the xtrc attribute.
4. Type in the name you want to assign to the row.
The new row name appears in the Table Display area and in the Row Display area.
Add a topic to a reltable cell

You add topics to reltables one at a time using a drag-and-drop technique. You can also drag a
topic from one cell to another.
You can add topics from the DITA Map and Search Results views.The map must be locked.
to add the topic.
2. Drag the topic from the DITA Map or Search Results view into one of the cells in the
row.
The topic appears in the cell at the place you dropped it.
Add a topic and its children to a reltable

You can add a topic and all its children to a reltable in a single operation.
To add a topic and all its children:
to add the topic and its children.
2. Hold down the Alt key and drag the topic from the DITA Map or Search Results view
into one of the cells in the row.
The topic and all its children appear in the cell at the place you dropped it.
Insert a topic group into a reltable cell

Use this procedure to create and configure topic groups.
Topic groups let you create relationships among the topics within a reltable cell. The specifics of
the output they produce will depend on the XSL that is applied to them.
to add the topic.
2. Right-click the reltable cell where you want to insert the group, then select one of the
following values:
• Insert group: choice

• Insert group: family
• Insert group: unordered
Note: The choices available depend on your configuration.

You can insert these groups into any type of cell. The screen shot below shows a sequence
group inside a concept type of cell.
3. Drag and drop topics into the group.

You can drag topics from the DITA Map view, from other cells in the row, or from within the
cell where you've inserted the group.
Related Links
Remove a row from a reltable

You can remove a row along with all its constituent cells and topics from a reltable in your DITA
map.
1. In the Table Display area, highlight the row you want to remove.
2. Right-click, then select Remove from RelTable.
The row is removed from the reltable.

Remove a cell from a reltable row

You can remove a cell along with all the topics it contains from a reltable in your DITA map.
1. In the Table Display area, highlight the row that contains the cell you want to remove.
2. Right-click the <relcell> line at the top of the cell, then select Remove from RelRow.
The cell and all its topics are removed from the reltable row.
Configure relationship tables

This section deals with operations such as changing the cell types and configuring link directions.
Change the type of a reltable cell

Use this procedure to reassign or remove the limiting type of a reltable cell in a CRT cell; or to
set the type of an untyped cell.
If you have created a pre-configured CRT row you may at some point want to change a cell's
type so that it accepts other types of topics. Or you may want to remove the type attribute
altogether so that the cell accepts all types of topics.
Or, if you have created an untyped row, you may want to limit it to a specific type of topic.
1. In the Table Display area, highlight the row that contains the cell you want to re-type.
3. In the Properties view, click in the entry field for the type attribute.
4. Enter the type you want to assign to the cell.
The cell type is reassigned and the new type appears in the Table Display area and in the
Row Display area.
Change the collection-type of a reltable cell

Use this procedure to reassign or remove the collection-type of a reltable cell; or to set the
type of an untyped cell.
If you have created a preconfigured row you may at some point want to change the cell's
collection-type to another valid value: "choice", for example. Or you may want to remove
the collection-type attribute altogether.
Or, if you have created an untyped row, you may want to restrict its display characteristics using
this attribute. Display characteristics, of course, will vary according to your XSL.
1. In the Table Display area, highlight the row that contains the cell whose type you want
to change.
• unordered
• sequence
• choice
• family
The cell collection-type is reassigned and the new type appears in the Table Display
area and in the Row Display area.
Change the collection-type of a topic group

Use this procedure to reassign or remove the collection-type of a topic group within a
reltable cell.
You may at some point want to change a topic goup's collection-type from one type – such
as "family" – to another valid value: "choice", for example. Or you may want to remove the
collection-type attribute altogether.
1. In the Table Display area, highlight the row that contains the group whose type you
want to change.
2. Highlight the group.
• unordered
• sequence
• choice
• family
The group's collection-type is reassigned and the new type appears in the Row Display
area.
Related Links

Set linking direction

This procedure describes how to specify whether links are visible in source or target topics.
another, without having a link back in return (or vice versa).
You can set the linking properties of entire cells, of individual topics within cells, or for topic groups
within cells.
To set the linking direction:
1. In the Row Display area of the Reltable Editing view, highlight the cell, topic, or topic
group.
2. You can set the linking direction in two ways:
• Right-click the cell, topic, or topic group and select Linking > <direction>, where
<direction> is one of the following:
• targetonly: The topic can only be linked to; it cannot make links to other topics.
• sourceonly: The topic can link to other topics; other topics cannot link to it.
• normal: The topic can link in both directions. This is the default value, and does not
have to be entered.
• none: A topic cannot link or be linked to.
• -dita-use-conref-target: In case of conrefs, indicates that the linking value
should be pulled in from the target.
See the DITA specification for more information.
• In the Properties view set the linking attribute to the required value.
The linking property of the object is set, and the appropriate link direction icons appear
next to the selected object.
Related Links
About linking direction in relationship tables

You can specify whether topic links are mutual or unidirectional.
When you drag topics into adjacent cells of a row, by default you'll establish a two-way link: the
topics link to each other. If you're using the output in a set of Related links, for example, you'll
see each topic in the other's list.
another, without having a link back in return (or vice versa). For example, you might want numerous
small related procedures to have access to a conceptual topic; but you might not want all of the
many little topics showing up as links inside the concept.
You can set the linking direction on topics, groups of topics, or on entire cells. Icons next to the
objects indicate the linking direction.
The following linking values are available:
• targetonly - the topic can only be linked to; it cannot make links to other topics. Indicated
• sourceonly - the topic can link to other topics; but other topics cannot link to it. Indicated by
the following icon:
• none - a topic cannot link or be linked to. Indicated by the following icon:
• normal - the topic can link in both directions. This is the default value and does not have to
be entered. You can, however, use this value to override the attribute of a parent structure: if,
for example, you want just one topic within a topic group to link in both directions. Indicated
In the screenshot below, both of the cells have the default linking: normal (bidirectional). So does
the topic group in the task cell, as a whole. However, one of the topics in the group – Vote on a
document – is designated as "sourceonly". None of the other members of the group or the concept
cell will be linked to it; but it will link to all the others.
The topic in the concept cell, on the other hand, has been designated "targetonly". All the other
cells in the row will link to it, but it will not be linked back to them.
Note: Your system must use UTF-16 character encoding with the East Asian language
pack installed, or the linking arrows will not display properly.
Related Links
Locate reltable rows where a topic is used

You can use the Relationship Outline view to locate the rows where one or more topics appear.
When you highlight a topic in the DITA Map view, the Relationship Outline view displays the
table(s) and row(s) where that topic is used.
where both topics appear together, followed by lists of the rows where each topic appears on its
own.
Note: This information is retrieved from the repository. If you've recently put a topic into
a reltable, you'll need to release the map before you can view the rows where it's being
used.
To locate reltable rows where a topic is used:
• In the DITA Map view, highlight the topic or topics you want to locate.
The Relationship Outline view displays the table(s) and row(s) where the topic(s) is used.
In the following example, you can see in the Relationship Outline view that the topic
"Assign documents to users" appears in the row "Document assignments" in a
reltable called "Projects".
In the next example, you can see that the topic "Set document due dates" appears
in two rows in the reltable called "Projects"; it also appears in one row of the reltable
"Tutorials".
In the next example, two topics are selected in the DITA Map view. The Relationship
Outline view shows that the selected topics both appear in the "Document
assignments" row of the reltable called "Projects". It then list the rows and tables
where each topic appears on its own.
Related Links
Filter reltable rows in the Table Display area

You can use the Filter field of the Table Display area to locate specific rows in the reltables in
your map.
As you enter characters in the Filter field, the Table Display area shows the row names that
contain those characters.
To filter reltable rows in the Table Display area:
• In the Filter field of the Relationship Table Editor, type in characters contained in the
names of the rows you want to locate.
The Table Display area shows rows where the string is used.
Note: The filter function examines all text in the reltable, including the tags. So if you
type in the string "ro", you'll see all the rows in the reltable, since they all begin with
the tag <relrow>.
The screenshot below show the results of entering "as" into the Filter field. The two
rows containing that string are displayed: "Document assignments" and "Assign
values".
The following screenshot shows the rows displayed when the string "va" is entered.
Related Links
Relationship table examples

This section contains some concrete examples of how to use relationship tables.
Reltable example one: CRT row structure

Once you’ve inserted a reltable into a map, you’ll start adding rows. DITA CMS offers several
types of pre-configured rows.
This example shows the structure of a CRT row, that is a row with three cells, each supporting
a specific type of topic: Concept, Reference, and Task.
The screen capture below shows the Reltable Editing Perspective. The DITA map view has been
expanded, and three topics are highlighted. These are the ones that are being used in the reltable.
The Relationship Table editor is also open, with the “oil change” row highlighted. You can see
that each of the highlighted topics is in the row appropriate to its topic type:
• Concept – When Should I Change my Oil?

• Task – Changing your Oil
• Reference – Oil Grades and Weights
The example uses the default linking – normal – as indicated by the decoration ( ). Normal
linking means that the links will be reciprocal: the task will refer to the concept and the concept
will refer to the task. And likewise for the task and reference topics. Each topic is linked to both
of the others.
You can see the output this produces in Example One: CRT row output.
Related Links
Reltable example one: CRT row output

This topic shows the Changing your Oil topic as it would appear in HTML Help.
The image below shows one set of links produced by the reltable in Example One: CRT row
structure. The links to the other two topics in the adjacent reltable cells appear in the Related
Concept and Related Reference sections at the bottom of the page.
If you followed either of these two links, you’d see that these topics are each linked back to the
topic shown below.
Related Links

Reltable example two: links are between cells – not within cells
When you add topics to a relationship table cell, those topics link to the topics in the other cells
– not to each other.
For example, I could add another topic to the Concept cell in the reltable shown in Example One:
CRT row structure.
Example two output
If we look at the output for the task topic (Figure "Task Topic Output"), we can see that the new
concept topic has been added as a link.
But if we look at either of the concept topics, we’ll see that there is no link between them (Figure
"Concept Topic Output"). The links are between topics in adjacent cells.
Figure 65: Task Topic Output

Figure 66: Concept Topic Output
Related Links
Reltable example three: linking topics of the same type

If you want links between two topics of the same type – two concepts, for example – you can put
them into a family type of topic group.
The image below (Figure "Relcell Contents") shows a cell where three topics have been added
to a family type of topic group.
In the Eclipse help output each topic shows up in the others’ Related Links as a Related Task
(Figure "Relcell Output").
Figure 67: Relcell Contents
Figure 68: Relcell Output
Related Links
Reltable example four: linking direction

You can override the default linking direction.
By default, links are reciprocal. Topics in adjacent reltable cells refer back and forth to each other
(as we showed in examples One and Two). Sometimes, however, you’ll want to limit this reciprocity
to avoid overwhelming the reader with irrelevant links.
In the example below (Figure: "Reltable Contents"), we can see how several localization tasks
– shown in the left-hand cell – are all given a related link to a single task (which deals with setting
up a place on your hard drive where files will automatically be saved).
In order to suppress related links pointing back from the Configuration topic to all the tasks in the
left-hand cell, we’ve set the linking direction on that topic to “targetonly” ( ).
You can look at the related links produced by this reltable row by visiting any of the topic links
below.
• Configure import and export directories (note that this topic has no links to any of the topics
in the left-hand cell)
• Import a localized map and its topics
• Prepare an image localization kit
It’s worth noting that the topics in the left hand cell will not be linked with each other. Links are
always between adjacent cells.
Figure 69: Reltable Contents
Related Links
Reltable example five: creating sequences

You can use a reltable to dynamically create a set of numbered steps from the required topic
titles.
Sometimes you’ll be faced with documenting a large task that is actually made up of other smaller
tasks, taken from various places within a large manual. You can do this using a reltable.
In this example we’ll create the contents of the topic “Motoring Vacation Checklist” from the topics
indicated in the picture (below).
The reltable cell
First we structure the reltable cell. This is done by:
1. Dragging the container topic (Motoring Vacation Checklist ) into a task-typed cell, and then
2. Dragging the component tasks in as children of that topic
The collection-type properties
Then we’ll set the collection-type of the container topic to sequence, using the Properties view.
Example five output
The finished Motoring vacation checklist would appear in Eclipse Help as shown below. The topic
titles become the numbered steps. The <shortdesc> elements furnish the text below the steps.
Related Links
30 Production
Production
Topics: Production includes publishing final document deliverables

• Publish and generating interim drafts for circulation.
• Archive a published map You can use Generate Output to create output for a single
• Generate output file or for an entire document. Draft output can be generated
at any time, regardless of the current status.
You can also use Generate Output to create final output for
a document. Final output is generated from published maps
with the status Published:done (or its equivalent in your
deployment).
Publish
Publish creates an official copy of the document deliverable that can then be generated in any
of the available formats.
To publish a document, the map and all its referenced files – including those referenced
by conrefs or related-links – must have reached their final state.
Use Publish when you are ready to create a final, official version of a document: the one you
intend to use for publishing in various formats and to send to localization.
Files must be assigned a version label every time they are published. The version identifies
completed files for a specific release. The version label that you assign to the map is assigned,
in turn, to all the files in the project. If a file is published in more than one document, it will have
a label for each publication. If you want to see a file's version labels, look in the file's Properties.
Tip: You can use the version label in your search criteria to find published topics, maps,
and images.
• In the DITA Map view, right-click the map and select Publish.
• In the Todo List, right-click the map and select Publish.
• In Project Management view, select the deliverable(s) you want to publish, then right-click
and select Publish.
You can select one map, select several maps by holding down CTRL or SHIFT and
clicking the maps, or right-click on the Deliverables node to select all the maps within a
project.
The Publishing Tags dialog appears.

2. Enter the required tag Value(s).
The specific tags that appear vary with system configuration.Typical tags may include Version,
Scope, etc, and may or may not be mandatory according to your system's configuration.
3. Click Create Label(s).
A new version label is recorded in the map and all its topics. Topics that are published in
more than one document will have a label for each map in which they have been published.
The Publish… dialog tells you that publication was successful.
4. Click OK.
A Progress Information dialog appears as your local file (or files) is copied to the server.
Production 563
5. Click Run in Background if you want to hide the Progress Information dialog and
continue working in Eclipse.
The Progress Information dialog will be minimized into the trim at the bottom of the workspace.
You can click the Results icon to restore the Progress Information dialog or to view the results
of the operation.
A copy of the map and its contents is created in the published area.
Archive a published map

You can archive published maps that you don't refer to frequently.
Once you've published several versions of a map, you may want to clear the earlier versions out
of the published area of the repository. You will no longer be able to see this map in the DITA
CMS. If you need to work with this map in the future, your CMS Administrator can retrieve it from
the archive collection of your Content Store.
Note: You won't be able to archive a map that has only been published as a component
of another map. Only a map that has been published as a top-level map will have the
Archive action available.
1. Use Search with the Published checkbox selected to display maps in the Published
cycle.
2. In the Search Results view, right-click the required map and select Archive.
The map disappears from the Search Results view.
The map and all its documents are moved to the archive section of the repository.
Generate output
The Generate Output command creates document deliverables in different formats.
You can generate the output of a single topic, a selected group of topics, or an entire map. You
can even select several maps and generate the output for all of them.
The generated output is saved as a ZIP file on your local file system. If you generate the output
for a single topic or map, the ZIP file contains either a single file of the output type you selected,
or a folder structure that produces the selected file; the specifics vary according to the output
type selected and your system's configuration.
If you are generating output for a single topic, the ZIP file name is compounded from the file name
and its language: Change_the_Oil.English.zip, for example.
If you have selected several topics or maps for output generation, then a file called
outputgenerator_bundle.zip will be produced. This file contains other ZIP files—one for each
document selected—each named as described above.
Note: Output is generated from the documents in the repository—not from the files you
have locked on your machine. If you have unreleased documents in your map, you will
not get the most recent content from the locked items.
1. Use Search to find the document you want to output.

2. Right-click the map(s) or topic(s) that you want to output.
documents.
3. Select Generate Output from the menu.
The Generate Output dialog appears.
Production 565
The fields and selections that appear in this dialog are configurable by the CMS Administrator.
The dialog above shows the current configuration at IXIASOFT.
• Fields in bold blue text are required.

• Entry fields may be filtered. If the text you enter appears in red, it is not valid for that field.
4. Select the Output Format that you want to use.

Each output format uses specific transformation templates. Some might even produce more
than one output. See your organization's template descriptions for details.
5. To apply a DITAVAL file to the output:
a) Beside the DITAVAL box, click the browse button ( ).

b) Select a DITAVAL file from the list.
Your selection appears in the DITAVAL file to apply to output field.
Click to clear the entry and choose a different DITAVAL file.
Note: If no DITAVAL files exist in your Content Store, the DITAVAL box will not appear
on the Generate Output dialog.
6. (Optional) To open the folder that contains the generated output when the
transformation is completed, select Open output folder when done.
7. To unzip the generated output when the transformation is completed, select Unzip
when done.
When you select this option, the Output Generator unzips the generated output in the output
folder, in a sub-folder with the file name. For example, if the output directory is called Outputs
and the generated output is saved in a file called
Web_Author_Installation_Guide.Dita2Pdf.English.zip, the file is unzipped in the
Outputs\Web_Author_Installation_Guide.Dita2Pdf.English directory.
If you select both the Open output folder when done and Unzip when done options, the
Output Generator opens the folder that contains the unzipped files.
8. (Optional) To save the Output Format you selected, click the diskette icon at the bottom
of the dialog.
Your selection will be used as the default value in the Generate Output dialog. You'll see it
the next time you generate output.
9. Click Create.
A Progress Information dialog appears as the output is generated.
10. (Optional) Click Run in Background if you want to hide the Progress Information dialog
and continue working.
The Progress Information dialog will be minimized into the trim at the bottom of the workspace.
You can click the Results icon to restore the Progress Information dialog or to view the results
of the operation.
11. When output generation is finished you have the following options:
• If Auto save is enabled, the Generate Output dialog displays the location where the file
was saved. Click OK.
Production 567
• If Auto save is not enabled, the Save As dialog appears. Confirm or change the proposed
filename and location, then click Save.
Auto save is set when you configure your import and export directories.
The ZIP file is saved in the specified location.

Related Links
Create a Ditaval file on page 348
Using conditions in the Output Generator

When you select Generate Output, the Generate Output window appears, displaying checkboxes
for conditions within your content. The conditions that appear depend on what attributes you have
assigned within the content.
For example, if you assigned @product="widget" to some elements within the topics used in the
map, then a checkbox for widget is present. If you also assigned @product="gadget" to some
elements, then a checkbox for gadget is also present.
You can use these checkboxes to include or exclude marked content from your output. The way
these checkboxes work is not completely logical, but it's important to understand.
Let's say you have a map with a bunch of topics. Each topic contains some elements marked
@product="gadget," @product="thingy," and @product="widget." When you select Generate
Output, the window looks something like this:
If you leave all checkboxes unchecked, you're telling the Output Generator to include
everything—all conditions—in your output. Now you might conclude from this that an unchecked
box means "include." You'd be logical but you'd be wrong. An unchecked box only means "include"
when all boxes are unchecked.
As soon as you check a box, the whole picture changes. When you check a box, the meaning
of that checked box becomes "include" and the meaning of unchecked boxes becomes "exclude."
So, in this example, you're telling the Output Generator to include content marked
@product="gadget" or @product="widget" but exclude content marked @product="thingy":
One implication of this approach is that if you want to use the checkboxes to exclude, you have
to have more than one checkbox under a given attribute. For example, say your content contains
one value for @otherprops, "thing1".You want to exclude all content where @otherprops="thing1"
and include everything else. When you go to generate output, you have only one checkbox under
otherprops: thing1. With only one checkbox, obviously you can't force the CMS to make a
distinction between a checked and an unchecked value for @otherprops. In such a case, what
you need to do is add another value for @otherprops somewhere within your content, for example,
"all". You only need to add this other value to one topic. Doing so creates a second checkbox
under otherprops for that value.You can then check that box and leave the thing1 box unchecked
to force the exclude.
31 Using the Build Manifest
feature
Using the Build Manifest feature
Topics: This section describes how to use the Build Manifest feature.
• Understanding the Build
Manifest feature
• Create a Build Manifest
• Set default values for
ditaval files, languages, and
user parameters
• Add and configure output
types
• Output a Build Manifest
• Search for a Build Manifest
Understanding the Build Manifest feature

A Build Manifest is a DITA CMS object that allows you to configure a list of different outputs for
a map.
For each map, you can specify the following information:
• Types of output to generate (PDF, HTML, xHTML, etc.)

• Languages to output; you can specify default languages for all the output types or specify them
per output type
• Ditaval file to use; you can specify a default ditaval file for all the output types or specify it per
output type
• User parameters that must be applied; these are the user parameters that are defined in the
transformation scenario for the output type. You can specify default parameters for all the
output types or specify them per output type.
Sample use case
Let's take the DITA CMS User Guide as an example.This document is generated in three different
output types:
• xHTML
• PDF
• Eclipse help
There are two flavors of this document—oXygen and XMetaL—so two different outputs must be
generated for each output type.
For the purpose of this example, we'll also assume that the User Guide is available in 3 languages:
• English
• French
• Japanese
This means that a total of 18 outputs (3 output types * 2 flavors * 3 languages) need to be
generated for the User Guide. With the Build Manifest, instead of having to call the Generate
Output command 18 times, you generate the output of a single object—the Build Manifest
object—which generates these 18 outputs.
Using the Build Manifest feature 571
Build Manifest workflow
Just like any object, the Build Manifest goes through a DITA CMS workflow. When you create a
Build Manifest object, it's in Authoring:work (or the equivalent in your workflow). The object
must be locked before you can work on it, and you release it when the work is completed.
You can also create a snapshot of a Build Manifest object.
Using the NightBuild
IXIASOFT provides a script that you can run to process multiple Output Generator jobs in batch
without having to use the DITA CMS Eclipse client. You can call the NightBuild script directly on
the command-line or create a batch file that will store the parameter values you want to use for
the script.
Using the NightBuild with the Build Manifest can be very useful. You use the DITA CMS Eclipse
Client to create the Build Manifest for a map, and then you output the Build Manifest from the
NightBuild script.
For more information about the NightBuild script, contact IXIASOFT Support.
To create a Build Manifest for a map
1. You create a Build Manifest object.

2. If applicable, you set default values for ditaval files, languages, and user parameters.
3. You create and configure all the output types into which you want to generate the map.
4. You output the Build Manifest with the Output Generator, which generates all the outputs
configured in the Build Manifest.
This chapter provides these procedures.
Create a Build Manifest

The first step is to create the Build Manifest object.
This procedure will use the DITA CMS User Guide as a use case for creating a Build Manifest.
To create a Build Manifest for a map:
1. In a view that lists the map, right-click the map and select Create Build Manifest.
The Create Build Manifest window is displayed:
The following table describes the fields in the Build Manifest window:
Table 7: Build Manifest window
Field Description
Id Id of the Build Manifest object. This field is generated automatically

and cannot be modified.
Title Name of the Build Manifest.
Description Description of the Build Manifest object. The description will be

added to the <shortdesc> element of the object.
Mode Flag that can be used by the NightBuild script in a query to

determine whether to generate the Build Manifest. For example,
if you have a script that runs every night to generate the output for
the maps in your Content Store, you can write a query that uses
this field as follows:
• Mode=Debug: The NightBuild script does not generate output

for the Build Manifests that are in Debug mode. This lets you
debug your Build Manifest using the DITA CMS interface without
impacting the night build.
Field Description
• Mode=Production: The NightBuild script generates output for

the Build Manifests that are in Production mode.
Notify Email address of the person to notify when the build is completed.
This does not have to be a DITA CMS user.
You can enter multiple addresses, separated by either a space or

a comma. The addresses can take any of the following forms:
1. address@xyz.com
2. name <address@xyz.com>
3. <address@xyz.com> name
4. (name) address@xyz.com
5. address@xyz.com (name)
Note: For this feature, you must configure the notification

message as well as the SMTP information in the Output
Generator. See Output Generator Installation Guide for
more information.
Mapref ID of the map to generate.
Language List of default languages into which to generate the outputs.
Template Template to use to create this Build Manifest object.
2. Enter the fields as appropriate for your Build Manifest.

For example, the following diagram shows the window for the DITA CMS User Guide:
3. To open the Build Manifest after you created it and configure the default values and
output types, select Open build manifest in default editor.
4. Click Create.
The Build Manifest object is created. If you selected the Open build manifest in default
editor, the Build Manifest object is opened in the DITA CMS, as shown below, and the values
you entered in the Create Build Manifest window are displayed:
The Build Manifest window has the following tabs:
• Default values: Specifies general information about the Build Manifest. It also lets you
configure default values for ditaval files, languages, and user parameters. The default
values are used for all the output types defined in the Build Manifest, unless you override
them for a specific output type.
• Outputs: Specifies the different types of output into which to transform the source map.
You can override the default ditaval, language, and user parameter values for an output
type in this tab.
• XML Preview: Provides the XML preview of the Build Manifest object. You cannot modify
the XML source.
The next step is to set default values for ditaval files, languages, and user parameters.
Set default values for ditaval files, languages, and user

parameters
You can set a ditaval file, languages, and user parameters that will apply to all the output types
defined in the Build Manifest.
When you set a ditaval file, languages, or user parameters in the Default values tab, they will be
used for all outputs that do not have ditaval, languages, or user parameters values defined.
When you define values for a specific output type, the default values are ignored for that output
type.
To define default values for the output types:
1. In the Build Manifest window, select the Default values tab.

2. To set a default ditaval file:
a) In the Ditaval field, click the ... button.
The Ditaval dialog is displayed.
b) Select the ditaval file to use and click OK.
3. To set default languages, select them in the Languages area.
4. To set default user parameters:
a) In the User parameters area, right-click the area and select Add.
The User parameters window is displayed.
b) In the Key field, enter the name of the user parameter.
Note: The name specified in the Key must match *exactly* the name of the user
parameter as defined in the preprocessors.xml file of the Output Generator; for
example, ixia.args.rellinks.
c) In the Value field, enter the value for this user parameter.
d) Click OK.
The parameter is added to the window.
e) Repeat for every default user parameters that must be set.
5. Save the Build Manifest.
The next step is to add and configure output types.

Add and configure output types

You add and configure output types in the Outputs tab of the Build Manifest window.
For each output type, you define the following information in the Output type information area:
• Type: Name of the output type from the Output Generator.

Note: You need to be connected to a running Output Generator before you can define
output types. The Build Manifest feature retrieves the list of available output types from
the running Output Generator.
• Status: Specifies whether the output type is enabled or not. This can be useful if you want to
configure an output type without generating it right away. When set to DISABLED, the output
type will not be generated when you output the Build Manifest.
• Description: Description of the output type.
You can also override the following values for the output type:
• Ditaval: Ditaval file that will be used for this output type. If you specify a ditaval file for the
output type, the default ditaval file specified in the Default values tab (if any) will be ignored.
• Languages: Languages that will be used for this output type. If you specify a language for the
output type, the default language(s) specified in the Default values tab (if any) will be ignored.
• User parameters: User parameters that will be used for this output type. These are the user
parameters that are defined in the transformation scenario for the output type. If you specify
parameters for the output type, the default parameters specified in the Default values tab (if
any) will be ignored. The name specified in the Key must match *exactly* the name of the user
parameter as defined in the preprocessors.xml file of the Output Generator.
Important: User parameters are not cumulative. For example, if you set parameter
values at the Default level and then set other parameter values at the Output type levels,
only the parameters set at the Output type level will be used.
To add output types:
1. In the Build Manifest window, click the Outputs tab.

The Output types tab is displayed:
Depending on the Build Manifest template that you are using, one or more output types may
already be defined.
2. To add a new output type, right-click in the Output types area and select Add.
A new output type is added in the Output types area. By default, the output type is enabled,
meaning that it will get generated.
3. Select the new output type and specify the information for this type in the Output type
information area, as follows:
Option Description
Type Select the output type
Note: If the Type field is displayed in red and you cannot select
an output type, this means that there is no Output Generator
running. You must connect to a running Output Generator before
you can configure an output type.
Status Select one of the following:
• To generate this output type when you generate the build manifest,
select Enabled.
• Otherwise, select Disabled.
Description Enter a description for this output type.

4. To configure a ditaval file, user parameters, or languages specifically for this output
type, select the output type and click Override default ditaval/languages/parameters.
The Overridden output values area appears.
5. To override a ditaval file:
a) In the Ditaval field, click the ... button.
The Ditaval dialog is displayed.
b) Select the ditaval file to use and click OK.
6. To override languages, select the languages in the Languages field.
7. To override user parameters:
a) In the User parameters area, right-click the area and select Add.
The User parameters window is displayed.
b) In the Key field, enter the name of the user parameter.
Note: The name specified in the Key must match *exactly* the name of the user
parameter as defined in the preprocessors.xml file of the Output Generator; for
example, ixia.args.rellinks.
c) In the Value field, enter the value for this user parameter.
d) Click OK.
The parameter is added to the window.
e) Repeat for every default user parameters that must be set.
8. Repeat this procedure for every output type to generate.
9. Save the Build Manifest.
The following diagram shows the Output type tab for the DITA CMS User Guide. Six output
types are created for this document:
• 2 Dita2PDF (one oXygen and one XMetaL)

• 2 Dita2xhtml (one oXygen and one XMetaL)
• 2 Dita2EclipseHelp (one oXygen and one XMetaL)
This is necessary since the oXygen and XMetaL versions require different ditaval files and user
parameters.
The final step is to output the Build Manifest.
Output a Build Manifest

To output a Build Manifest, you use the Build Manifest output generator type.
Note: You must release the Build Manifest to get the most recent content.
This procedure describes how to output a Build Manifest using the Generate Output command
in the DITA CMS Eclipse Client. You can also use the NightBuild script to generate the output.
For more information, contact IXIASOFT Support.
Output a Build Manifest in multiple languages
When you output a Build Manifest in multiple languages, the localized content must be in the
Localization:done state (or the equivalent in your deployment), otherwise the output will not be
generated for this language. This ensures that only final localized content is output (as opposed
to content that is partially translated).
Configure the Auto-save option
Generating a Build Manifest can take a long time, depending on the size of your maps and the
number of output types/languages configured. Therefore, IXIASOFT recommends that you
configure an output directory and select the Auto-Save option so that the Build Manifest outputs
are saved automatically when the operation is completed. See Configure import and export
directories on page 613 for more information.
To output a build manifest in the DITA CMS Eclipse Client:
1. Right-click the Build Manifest to output and select Generate Output.

The Generate Output window is displayed.
2. Select the BuildManifest output type and click Create.
The outputs are generated for this map.

Note: This operation may take hours, depending on the number of output type/languages
and map sizes.
When the output is completed, it is saved in a file called:
<build_manifest_title>.BuildManifest.<authoring_language>.zip
For example:
DITA_CMS_User_Guide-Build_Manifest.BuildManifest.English.zip
The zip file includes the following:
• The Build Manifest file in XML format (for example, mte1425048934103.bmanifest)

• A log file for the output operation (for example, mte1425048934103.build.html)
• Directories for all the output types, as follows:
<output_type_1>
authoring --> Contains output 1 for the source language
localization
<language1> --> Contains the output for the localized language 1
...
<languagex> --> Contains the output for the localized language x
...
<output_type_x>
authoring --> Contains output X for the source language
localization
<language1> --> Contains the output for the localized language 1
...
<languagex> --> Contains the output for the localized language x
For example, the 18 outputs for the DITA CMS User Guide might be packaged as follows:
Search for a Build Manifest

Build Manifests are categorized as "other" document types in the DITA CMS Search view.
To search for a Build Manifest:

2. In the Document Types panel, select Others.
3. Click the drop-down arrow to the right of Others.

4. Deselect all types and keep only build-manifest.
32 Localizing documents with
the DITA CMS
Localizing documents with the DITA CMS
Topics: This section describes how to localize your DITA CMS

• About localization documents.
• Prepare a pre-localization
kit
• Start the localization
process
• Prepare an image
localization kit
• Import a localized map or
topic
• Retranslate from source
• Reset text that was
auto-translated
About localization
Localization is the process of translating the content and adapting it for use in another language.
"Translate" and "localize" are often used interchangeably, but they are a bit different. More
accurately, localization is translation taken a step further. For example, say an auto parts guide
is written in German and translated to English. The initial translation is to British English, so the
guide refers to a "windscreen." While a U.S. audience would probably understand the reference,
to truly make the guide as "native" as possible, it should be localized to U.S. English, where the
"windscreen" becomes a "windshield."
The xml:lang attribute in DITA topics can be used to make this distinction. In typical deployments,
it specifies both the language and locale of the topic; for example, pt-br (Portuguese-Brazil) or
pt-pt (Portuguese-Portugal). (Note that your environment may use this attribute differently).
The following diagram shows an overview of the localization process in the DITA CMS.
Note: This process is based on the default localization workflow provided with the DITA
CMS. Your workflow and its statuses may differ.
Localizing documents with the DITA CMS 587
The process begins when you select the Localize command and specify the set of target
languages. When you localize a map, copies of the map and its contents (topics, images, and
referred topics) are created in the localization area—one set for each language you selected.
When you localize a topic, that topic, its images, and referred topics are created. The files have
the status Localization:tb translated.
If auto-translation is enabled, and a previous translation exists, the CMS will try to auto-translate
as much of the topics as possible based on previous translations of the same topic.
Note: In the concurrent localization model, if a document was fully translated during
auto-translation, it may have the status Localization:machine translated (depending on
your configuration). See Concurrent localization model on page 593 for more information.
The next step is to prepare the localization kit; this is the set of files that you’ll be sending to the
translation team for localization. You might need to prepare two localization kits:
• A localization kit, which contains the maps and topics to translate. The files are provided in
XLIFF or DITA format, depending on the localization method used. The kit may also contain
some of the following files: PDF files of the current version and the previous translation (if any)
to provide context for the translation, as well as the .image containers for the images referenced
by topics being translated. It doesn't include the actual images. If you need to translate some
or all of the images, you also need to create an image localization kit.
• An image localization kit, which contains the images that are included in the map or topic.
An image localization kit includes all the image formats available so that they can all be
localized. Images are sent in a separate localization package since they are treated differently
in translation.
After you have prepared the localization kits, the files are in the Localization:in translation
status.
When the localized files are returned from translation, they are imported back in the DITA CMS.
You first import the localized images back into the system (using the Import localized images
command) before you import the localized map and its topics (using the Import localized content
command). The system promotes the files to Localization:review.
You can now review the content of the localized files. You can return them to the Localization:tb
translated status if there are issues with them, or you can complete the process by putting the
files in the Localization:done status.
When the map and all its contents have reached the Localization:done status, you can create
a snapshot of the map.
At any time, you can create a pre-localization kit, which is a snapshot of the content that’s under
development; you send it to the translation team so that they can prepare their translation memory.
Pre-localization kits can contain as many output languages as you require. They can be generated
at any point in the document development cycle, and this operation does not change the status
of the files.
DITA CMS localization models

The DITA CMS provides two implementations of the localization process: the sequential localization
model and the concurrent localization model.
Sequential localization model
In this model, when you localize a source object for the first time, the DITA CMS creates a new
object in the target language. This language object is then updated when a new version of the
source object is sent to localization, so there is a one-to-one mapping between the files in
localization and their authoring sources. In the sequential localization model, the files are sent
to the translation team in DITA format.
Concurrent localization model
In this model, each localization creates a "branch" of the content in localization, one set for each
language selected. Therefore, a new file is created in the localization workflow each time a new
revision of a source object is localized. There are two flavors of the concurrent localization model:
• Node-based localization method: This is the original version of the concurrent localization
method in the DITA CMS (for clarity, this original version was renamed node-based localization
in DITA CMS 4.1). In the node-based localization method, when the files are exported to the
localization kit, they are converted into an XLIFF format used by translation memory tools.
They remain in DITA format in the DITA CMS.
• Concurrent localization method: This is the new version of the concurrent localization method
introduced in DITA CMS 4.1. It includes the following new features:
• Ability to generate the localization kit in XLIFF and DITA formats

• Very flexible auto-translation process, which can be configured to ignore changes that you
consider minor such as extra spaces, punctuation, <draft-comment> elements, etc.
• A new status in the workflow that indicates whether a document was completely
auto-translated by the system
• A new report that provides detailed feedback on the localization process
• An improved localization kit that provides more content, such as a document that includes
all the source text and images to provide context for the translation
Note: To differentiate between the two flavors of the concurrent localization model, the
original version was renamed node-based localization method in DITA CMS 4.1. The term
concurrent localization method is used to refer to the improved version introduced in 4.1.
The node-based localization method will be deprecated in an upcoming DITA CMS release.
If you are currently using the node-based localization method, IXIASOFT highly
recommends that you upgrade to the new concurrent localization method. Please contact
IXIASOFT Support for more information.
Sequential localization model

This section describes the sequential localization model.
First translation of an object
Figure 70: First localization of an object in the sequential localization model on page 591
shows the process for the first translation of an object in the sequential localization model. When
a source object is translated for the first time into a language, the DITA CMS creates a new object
in the target language (called language object in this document). This language object has its
own Revision number as well as an Authoring Revision property, which stores the revision
number of the source object when it was sent for translation. For example, if you send for
translation a source object that is at Revision 6, a new language object is created in Localization
with its own Revision number of 1 and an Authoring Revision of 6.
The language object file keeps the same name as the source object file. Its content is still in the
original language (for example, English), but its language attribute is set to the target language.
The language object has the tb translated state.
When you prepare the localization kit to send the files to the translation team, the language object
still has the same Revision number (for example, 1), but its state is now in translation. The files
sent to the translation team are in DITA format.
When translated content is imported into the DITA CMS, a new revision of the language object
is created (e.g., Revision 2), and its state is changed to review so that the translated content
can be reviewed internally. The Authoring Revision is not updated so that it is always possible
to correlate a language object with its original source. If the translation is updated during the
review process, a new revision of the language object is created (for example, 3).
When the translation is approved, its state is changed to Done, and you can now publish the
localized map.
Figure 70: First localization of an object in the sequential localization model
Subsequent localizations
As shown in Figure 71: Subsequent localizations of an object in the sequential localization

model on page 592, when a new revision of a source object is sent to localization (for example,
Revision 9), the DITA CMS first checks to see if this revision has already been sent for localization;
that is, it checks if a language object with the Authoring Revision 9 already exists in localization
for this source object. This can happen if, for example, the topic was part of another map already
sent for localization. If so, the localization process skips the file.
If this revision has not been sent for localization (for example, the corresponding language object
is at Authoring Revision 6), the DITA CMS then checks the status of the corresponding language
object in Localization:
• If the status is Localization:in translation or Localization:review, this means that the

language object is currently being translated or reviewed, so the language object in Localization
cannot be updated. The Localize operation will report an error for the source object and will
continue processing the other source objects.
• If the status is Localization:tb translated or Localization:done, the DITA CMS checks if

auto-translation feature is enabled and a previous translation exists with a Localization:done
status. In that case, it auto-translates the content using the translated text from the previous
version of the language object (that is, the Localization:done version). It then creates a new
revision of the language object with the auto-translated content. The language object is then
ready to be sent to translation.
If auto-translation is not enabled (or a previous translation does not exist), the DITA CMS
creates a new revision of the language object; the content is still in the original language.
Figure 71: Subsequent localizations of an object in the sequential localization model

Concurrent localization model

This section describes the concurrent localization model.
This localization model allows multiple revisions of the source to be in translation at the same
time. It is more flexible than the sequential model but it can lead to a much larger repository size
and increase the risk of duplicate translations.
First localization of an object
Figure 72: First localization of an object in the concurrent localization model on page 594
shows the process for the first translation of an object in the concurrent localization model. The
first translation of a source object in the concurrent localization model happens exactly as with
the sequential localization, but the language object created includes the authoring version number
in its name. For example, consider a document named abc1386692219292.xml that is at revision
6. When this document is localized, a file named abc1386692219292_00006.xml is created in
each target language.
This language object has its own Revision number as well as an Authoring Revision property,
which stores the revision number of the source object when it was sent for translation. Its content
is still in the original language (for example, English), but its language attribute is set to the target
language. The language object has the tb translated state.
When you prepare the localization kit to send the files to the translation team, the language object
still has the same Revision number (for example, 1), but its state is now in translation. The files
sent to the translation team are extracted from the DITA CMS and then converted to the XLIFF
format.
When translated content is imported into the DITA CMS, a new revision of the language object
is created (e.g., Revision 2), and its state is changed to review so that the translated content
can be reviewed internally. The Authoring Revision is not updated so that it is always possible
to correlate a language object with its original source. If the translation is updated during the
review process, a new revision of the language object is created (for example, 3).
When the translation is approved, its state is changed to Done, and you can now publish the
localized map.
Figure 72: First localization of an object in the concurrent localization model
Subsequent localizations
When a new revision of a source object is sent to localization (for example, Revision 9), the DITA
CMS does not update the language object, as with the sequential localization model. Instead, it
first checks to see if this revision has already been sent for localization (for example, if it was part
of a another map already sent for localization). If so, the localization process skips the file.
If this revision has not been sent for localization, it creates a new object in the target language,
and its name includes the authoring version number (for example, abc1386692219292_00009.xml).
This new localization object has no impact on the previous translation (named
abc1386692219292_00006.xml). This is why this model is concurrent: multiple language objects
of the same source object exist concurrently.
The new language object has its own revision number at 1 and its status is set to Localization:tb
translated, as shown in Figure 73: Subsequent localizations of an object in the concurrent
localization model on page 595.
Figure 73: Subsequent localizations of an object in the concurrent localization model
Auto-translation is always enabled for the concurrent localization model. If a previous translation
exists with a Localization:done status, the DITA CMS then auto-translates the content using
the translated text from the previous version of the language object (that is, the Localization:done
version).
If the language object was fully translated during auto-translation, the DITA CMS creates a new
revision of the language object with the auto-translated content and sets its status to
Localization:machine translated (or its equivalent in your workflow, depending on your
configuration). Otherwise, the next step depends on whether your system is configured to accept
partially auto-translated documents.
If partially-translated documents are accepted, then the DITA CMS creates a new revision of the
language object with the partly translated content and sets its status to Localization:tb translated.
Otherwise, the partial translation is rejected and the source content is sent in the localization kit.
With the concurrent localization model, there is no dependency between the various authoring
revisions that are sent to translation; a new authoring revision can be sent to translation
independently of the localization status of the previous authoring revision.
Prepare a pre-localization kit

You can send a preliminary version of your text to the translation team.
Note: Pre-localization kits are not available for the sequential localization method.
Preparing a pre-localization kit lets you take a snapshot of the content that’s under development
and send it to the translation team so that they can prepare their translation memory.
Pre-localization kits can contain as many output languages as you require.
When a pre-localization kit is prepared, the CMS attempts to auto-translate as much as possible
of the map and its topics, based on previous translations (if there are any). The result is
concatenated into one file per language you select.
The localization process requires a substantial amount of system resources. If you are localizing
several maps in many different languages you may notice an impact on your computer's
performance.
Pre-localization kits may be generated at any point in the document development cycle, and from
any view in DITA CMS.
The pre-localization kit is output in XLIFF format and DITA format. Each XLIFF translation unit
contains the original source text. It also contains the automatically translated text, or a copy of
the source text if auto-translation was not possible.
1. Right-click the map and select Localization > Prepare Pre-Localization Kit from the
menu.
The Select Languages dialog appears.
2. In the Select Languages dialog, select the required language(s).
3. Click Create.
The Generate Kit dialog appears as the localization kit is generated and zipped.
4. After the localization kit is prepared you have the following options:
• If Auto save is enabled, the Generate Kit dialog displays the location where the file was
saved. Click OK.
Auto save is set when you configure your import and export directories.
Related Links
Start the localization process

Localization begins by creating a copy of the map and its contents in the localization area, one
for each of the target languages.
You can localize a map or a topic. When you localize a map, all of the topics and images that it
contains (including referred topics) are also localized. When you localize a topic, its images and
referred topics are also localized.
Note: You cannot localize a snapshot directly. To localize a snapshot, first publish the
snapshot and then run the select Localization > Localize... command on the published
version of the snapshot.
During localization, if auto-translation is enabled, the DITA CMS will try to auto-translate as much
of the topics as possible based on previous translations of the same topic.
Note: By default, auto-translation is always enabled in the concurrent localization method.
It is optional in the sequential localization method. See your CMS Administrator to know
which method you are using and whether auto-translation is enabled.
performance.
1. Search for the map or topic to localize.

2. In the Search Results view, right-click the required map or topic and select
Localization > Localize... from the menu.
The Select Languages dialog appears. If the map is in one or more projects, all the targeted
translation languages in all these projects will be selected by default.
3. In the Select Languages dialog, select the required language(s).
4. Click Create.
The Localize dialog appears as copies of the map and its topics are being created in the
localization area, one for each of the target languages.
5. When the localization process is complete, the Localize dialog displays a message
telling you that the operation was successful.
6. Click OK.
The map and its topics now have the status Localization:tb translated (or its equivalent
in your workflow).
You must now create:
• an image localization kit for the graphics, if required

• a localization kit for the map and its topics
Related Links
Specify default translation languages on page 455
Specify targeted translation languages for a deliverable on page 470
Prepare an image localization kit

Images are sent for translation in a separate package.
The images as well as the map or topic that contains the images must have the status
Localization:tb translated (or its equivalent in your workflow).
To prepare an image localization kit:
1. In the Cycles panel of the Search view, select the Localization checkbox.
2. In the Document Types panel of the Search view, select Maps or Topics, depending
on whether you are localizing a map or a topic.
3. In the Languages panel of the Search view, select the target translation languages.
5. In the Search Results view, right-click the map or topic you are localizing and select
Localization > Prepare Image Localization Kit from the menu.
A Progress Information dialog appears as the image localization kit containing all the images
in the map or topic is generated and zipped.
6. After the image localization kit is prepared you have the following options:
• If Auto save is enabled, the Prepare Image Localization Kit dialog displays the location
where the file was saved. Click OK.
When the localized images are returned from translation, you'll need to import them back
into the system.
Related Links
Start the localization process on page 596
Prepare the localization kit

Once the files are in the Localization cycle, a localization kit is prepared for each language and
sent to the translation team.
Requirements:
• If preparing a localization kit for a map, the map's title must be in an element – not an attribute.
• The map or topic must have the status Localization:tb translated (or its equivalent in your
workflow).
The following table describes the contents of the localization kit according to the localization
method configured:
Table 8: Localization kit contents
Sequential localization method Concurrent localization method
A ZIP file that contains the following: A ZIP file with the content in XLIFF format, as
follows:
• A <language> directory (for example,
ja-jp) that contains the map and its topics • The map and its topics in XLIFF format.
in DITA format. If auto-translation is enabled Each XLIFF translation unit contains the
and a previous translated copy existed, the original source text. It will also contain the
files will contain the automatically translated automatically translated text (or a copy of
text. Depending on the configuration, this the source text if auto-translation was not
directory may include the .image containers possible). Depending on the configuration,
for the images in the map for context. this directory may include the .image
• (Optional) A file called originals.zip. This file containers for the images in the map for
is saved in the <language> directory and context.
contains the current version of the document • Two PDF files: filename_current.pdf and
sent for localization in a format configured filename_lasttranslation.pdf (optional).
by your CMS administrator (for example, These contain the current version of the
PDF, HTML, etc.). If auto-translation is document (including auto-translated text, if
enabled, this document includes the available) and the previous translation (if
auto-translated text. there is one).
• (Optional) A file called lasttranslation.zip. A ZIP file with the content in DITA format, as
This file is saved in the <language> directory follows:
and contains the previous translation of the
document in a format configured by your • A <language> directory (for example,
CMS administrator (for example, PDF, ja-jp) that contains the map and its topics
HTML, etc.). in DITA format. If auto-translation is enabled
and a previous translated copy existed, the
files will contain the automatically translated
text. Depending on the configuration, this
directory may include the .image containers
for the images in the map for context.
• (Optional) A file called originals.zip, which
contains the current version of the document
sent for localization in a format configured
by your CMS administrator (for example,
PDF, HTML, etc.). If auto-translation is
Sequential localization method Concurrent localization method
enabled, this document includes the

auto-translated text.
• (Optional) A file called lasttranslation.zip,
which contains the previous translation of
the document in a format configured by your
CMS administrator (for example, PDF,
HTML, etc.).
Note: A localization kit must be prepared for each of the target languages.
performance.
To prepare the localization kit:
1. In the Cycles panel of the Search view, select the Localization checkbox.
2. In the Document Types panel of the Search view, select Maps or Topics, depending
on whether you are localizing a map or a topic.
3. In the Languages panel of the Search view, select the target translation languages.
All maps or topics that are being localized in these languages appear in the Search Results
view.
5. In the Search Results view, right-click the required map(s) or topic(s) and select
Localization > Prepare Localization Kit from the menu.
The Generate Kit dialog appears as the localization kit is generated and zipped.
6. After the localization kit is prepared you have the following options:
• If Auto save is enabled, the Generate Kit dialog displays the location where the file was
saved. Click OK.
The localized objects now have the status Localization:in translation (or its equivalent in
your workflow).
When the files returns from translation, it must be imported back into the system.
Related Links
Start the localization process on page 596
Import localized images

After images return from translation, they must be imported back into the system.
The returned localized images must be unzipped and located on your hard drive.
• On the Localization toolbar, click the Import Localized Images button ( ).

• From the menu bar, select DITA CMS > Import Localized Images
The Import Localization Package dialog appears.

2. Click the Set Files button and then navigate to the directory where the returned images
are located.
Tip: You can configure a default directory where the Import Localization Package
dialog will open automatically.
3. Select the file(s), then click Open.
The Import Localization Package dialog reappears, with the selected files displayed.
4. Click Import.
The images are copied into the system and given the status Localization:review (or its
equivalent in your workflow).
Related Links
Import a localized map or topic

After files return from translation, they must be imported back into the system.
The returned localization file must be unzipped and located on your hard drive.
It's a good idea to import your localized images first and make sure that they all have the review
status. If you have done this, then when you import the localized map or topic, the system will
automatically set the status of these files to Localization:review/Localization:translated or its
equivalent in your workflow.
If, on the other hand, some of the images referenced by the topics still have Localization:in
translation status (or its equivalent in your workflow), then the system will keep these imported
topics (and their map) at this status too, and you'll have to promote them all manually at some
point in the future.
Note: It is possible to have the DITA CMS handle most of the complex operations by
using a combination of specific status configuration and triggers. For example, your system
could be configured to behave as follows:
• During the import process, the system checks the status of the image files referenced
by the topics. If any of these images still have Localization:in translation status, then
the referring topics (and consequently the map) are assigned the status
Localization:awaiting images.
• These topics will stay at this status until their translated images are imported into the
system. At this time the CMS will automatically promote the topics to
Localization:translated status. When all images have been returned and all topics have
been promoted to the translated state you’ll be able to promote the map to
Localization:translated as well.
Please contact IXIASOFT Support for more information.
• On the Localization toolbar, click the Import Localized Content button ( ).

• From the menu bar, select DITA CMS > Import Localization Package.
The Import Localization Package dialog appears.

2. You have two options:
• To import all the files in a folder, click the Add Folder button, navigate to the folder that
contains the localized files, and click OK.
• To import one or more localized files:
1. Click the Set Files button.

2. Navigate to the localized files.
3. In the bottom-right area of the Open dialog, select the type of files to import (for example,
XLIFF document, XML document, etc.).
The files are displayed in the dialog.
4. Select the files to import and click Open.

Tip: You can configure a default directory where the Import Localization Package
dialog will open automatically.
The Import Localization Package dialog is displayed, listing the localized files.
3. Click Import.
The files are imported into the DITA CMS and given the status Localization:review (or its
equivalent in your workflow).
You can now complete the localization process by reviewing the localized files and approving
them or returning them to localization.
Related Links
Retranslate from source

Use this function when you want to have a topic completely retranslated from scratch.
Sometimes it’s easier to have an entire topic retranslated, rather than trying to salvage individual
phrases. This function reverts the content of one or more topics to the original source language.
You can revert a topic at any point in the Localization cycle. The reverted topic’s status is set to
Localization:tb translated (or its equivalent in your workflow).
Note that parent document status will be adjusted as appropriate.
For example, if you revert a referable-content topic that’s reached Localization:done, then all the
topics that reference that topic will have their status set to their initial Localization state as well.
These topics will be included in the localization kit, when it is generated. Their content, however
will remain unchanged and they need not be sent to the translation team.You can safely set their
status to Localization:done (or its equivalent in your workflow) once the referable-content topic
is finished and re-imported into the repository.
1. Right-click the appropriate topic(s) and select Localization > Retranslate from Source.
2. When the localization process is complete, the Retranslate dialog displays a message
telling you that the operation was successful.
3. Click OK.
Reset text that was auto-translated

In some cases, text that has been auto-translated must be reviewed again by the localizers.
When auto-translation is enabled, the DITA CMS sets the translate="no" attribute on
previously-translated elements when preparing the localization kit. This ensures that localizers
do not translate text that has not changed since the previous translation.
However, there might be cases where you want your content to be reviewed again by the localizers,
even if the content has not changed from the previous translation. This is done by running the
linguistic review process, which removes the translate="no" attribute from auto-translated
text.
The linguistic review process is executed when you run the Prepare Localization Kit command
on localized maps that are in the Localization:review status.
Requirements
• This process requires specific configuration and works for the sequential and node-based
localization methods only.
• This process also assumes that auto-translation is enabled in your configuration and that
content has already been translated at least once.
See your CMS Administrator to determine if this process is enabled in your deployment.
To reset text that was auto-translated:
1. Change the status of the map and its topics to Localization:review

2. Right-click the map and select Localization > Prepare Localization Kit.
The DITA CMS generates the localization kit and removes the translate="no" attribute
from pre-translated elements in the kit, according to the configuration.
33 Workspace configuration
Workspace configuration
Topics: The procedures in this section tell you how to configure the
• Set file search maximum Eclipse environment.
• Associate editors with
documents
• Configure key mapping
• Customize menu visibility
• Customize toolbar visibility
• Enable Eclipse command
groups
• Clear files from your hard
drive
• Clear information from the
cache
• Synchronize image
thumbnails
• Enable the Read-only Editor
• Specify compare tool
• Configure import and
export directories
• Add the root-catalog.xml
catalog to the oXygen
editor
• Configure column display
in any DITA view
• Restore warning messages
• Bring a process out of
background
Set file search maximum

This procedures configures the maximum number of files that display in the Search Results view
when you perform a search.
You can increase the number of results returned by a search by changing the number specified
in your DITA CMS Preferences.
Note: The larger the number you specify, the longer it will take to complete a search.
1. From the Window menu, select Preferences....

2. Select DITA CMS > General Behavior.
The General Behavior pane appears.
3. In the Maximum number of results field, enter the appropriate number.
4. Click OK.
Associate editors with documents

This procedure associates the file extensions of various document types with your preferred
editors.
You can configure the Eclipse environment to let you choose the editors you use within
the DITA Perspective for topics, images, and maps. To do this, you need to associate the
documents' file extensions with your preferred editors.
Note: If the Read-only editor is enabled, then XML documents that are not locked will
open in it—not in the associated XML editor.

2. Select General > Editors > File Associations.
The File Associations pane appears.
3. Click the Add button next to the File types list.
The New File Type dialog appears.
4. In the File Type entry field, type the appropriate file extension:
• *.xml - for topics

• *.ditamap - for maps
Workspace configuration 607
• *.bmp - for bitmap images

• *.jpg - for JPEG images
Note: You must associate the extension of each image type you want to edit. The
above extensions are examples.
5. Click OK.
The new file type (*.png, for example) appears in the File types list. Your new entry should
be highlighted.
6. Click the Add button next to the Associated editors list.
The Editor Selection dialog appears.
7. Select either:
• Internal Editors: Display a list of programs integrated with the Eclipse IDE, such as the
browser.
1. Select your preferred editor, then click OK.
• External Programs: Let you select other programs available on your system.
1. Click the Browse button to navigate to the program of your choice.

2. Select your preferred editor, then click OK.
Your editor appears in the Associated editors list.

8. With the editor selected, click Default to make it your editor of choice.
9. Click OK.
Your editor is now associated with the document's file extension. If you have more than one
editor associated with documents such as maps and topics, they will appear as selections
on the Open with menu when you right-click these documents. The image editor that opens
when you edit an image (from within the Show/Edit Image dialog) depends on the type of
image selected there, and the editor associated with that image type.
Repeat this procedure for each editor and document type as required.
Related Links
Edit a resource item on page 269
Configure key mapping

Use this procedure to associate key sequences with actions in the DITA Perspective.
Within Eclipse and DITA CMS, certain key sequences are used to invoke menu commands and
other actions: for example, CTRL+C copies the currently selected text. This procedure opens
the Keys pane of the Preferences dialog, so that you can customize key assignments.
See Eclipse Help for further information.

2. Select General > Keys.
The Keys pane appears.
3. In the Command list, select the command you want to configure.
Tip: Sort the commands by Category. This will display all the DITA CMS keys
assignments together.
The command Name and its current Binding are displayed.
4. With the cursor in the Binding field, press the new key sequence you want to assign.
5. Click Apply.
The key sequence is assigned.
6. Repeat as needed for each key sequence you want to reassign.
7. Click OK.
Related Links
DITA CMS shortcut keys on page 623
oXygen quick reference on page 294
Customize menu visibility

Use this procedure to display or hide menus and their options in the current perspective.
Note: To enable menu options other than those of DITA CMS, you may need to enable
their command groups.
1. From the Window menu, select Customize Perspective....

The Customize Perspective - perspectivename dialog opens.
The perspectivename indicates the current Eclipse perspective – the one you are customizing.
2. Select the Menu Visibility tab.

You can expand the menus to display the available options.
3. Add or remove menus or menu options as required.
Caution: Do NOT remove the Window menu.This is the entry point to the Customize
Perspective dialog.
4. Click OK.
Related Links
Enable Eclipse command groups on page 609
Customize toolbar visibility

Use this procedure to display or hide toolbar options in the current perspective.
You can configure any of the perspectives in Eclipse so that they show only the toolbars that you
use most frequently.
For example, if you use a text editor frequently in the DITA Perspective, you might find it convenient
to have it display whitespace characters such as tab and space. You would do this by enabling
the Editor Presentation toolbar.

2. Select the Toolbar Visibility tab.

Note: To enable toolbar options other than those of DITA CMS, you may need to
enable their command groups. This is done in the Command Groups Availability
tab in this dialog.
3. Add or remove toolbar options as required.
4. Click OK.
Related Links
Enable Eclipse command groups on page 609
Enable Eclipse command groups

Use this procedure to enable the commands that appear on menus and toolbars.
Many of the menu and toolbar options must first be enabled, before they can be made visible.

2. Select the Commands tab.

In the Commands tab, you can highlight each of the Available command groups to see
the menu and toolbar options that are available.
3. In the Available command groups list, select the option you want to add to the current
perspective.
4. Repeat as needed for each toolbar you want to add to the perspective.
5. Click OK.
You can now go to the Toolbar Visibility or Menu Visibility tab and select the required
menu and toolbar options.
Related Links
Customize menu visibility on page 608
Customize toolbar visibility on page 609
Clear files from your hard drive

This procedure removes unnecessary files from your local hard drive.
Use this procedure when you have been working with a large number of repository files and want
to free up space on your hard drive. This will flush all Content Store files from your local repository,
with the exception of files that are currently open and/or locked by you.

3. Click Clear Workspace.
All Content Store files are erased from your hard drive, with the exception of those that
are currently open and/or locked by you.
Clear information from the cache

This feature removes server information from your local cache, so that you can have access to
the most recent information.
DITA CMS keeps information from the server on the local machine for the purposes of optimizing
performance. This information is updated approximately every 2 minutes, which results in a small
lag behind what you see in DITA CMS and the file status information on the server.
Clearing your local machine's cache updates server information immediately. You will however,
notice a small increase in time for subsequent operations such as searches during the 5 or 10
minutes that it takes for the cache information to be rebuilt.
Note: Cache information is distinct from the local copies of any topics or other documents
you may working on in DITA CMS. Clearing the cache in no way affects these.

3. Click Clear Memory Cache.
Information in the local machine's memory cache is cleared, and replaced with the most
recent information from the server.
Synchronize image thumbnails

This procedure copies existing image thumbnails onto your local hard drive.
You must synchronize image thumbnails if you want to enable thumbnail display in the Search
Results, Todo List, or any other view.

3. Select Synchronize Image Thumbnails.
Note: If the Synchronize Image Thumbnails is greyed out, this indicates that this
option was disabled by your CMS Administrator.
4. Click Apply.
5. Click OK.
You can now enable thumbnail previews.
Enable the Read-only Editor

This procedure causes unlocked topics to open in the Read-only Editor.
With this option enabled, double-clicking a topic that is unlocked, or locked by another user,
opens it in a Read-only text editor. All text, including XML markup, is visible but cannot be modified.
This editor is built in to the DITA CMS and does not need to be associated with the *.xml file
extension.

3. Select Open unlocked documents in Read-only Editor.
4. Click Apply.
5. Click OK.
Unlocked documents will now open in the Read-only Editor.
Specify compare tool

This procedure lets you use an alternate tool for the compare function.
DITA CMS lets you specify an external compare tool, if you'd rather use your own – rather than
the one that's built into Eclipse.

3. In the External Compare area, click the Browse... button.
The Browse For File dialog appears.
4. Navigate to the required application and select it.

Note: If your compare tool requires command line parameters, you may need to write
a batch file and select it instead.
5. Click OK.
The path to the selected application (or batch file) appears in the Application field.
6. Select the documents type(s) that the compare tool should be used with: Topics or
Maps (or both).
7. Click Apply.
8. Click OK.
The specified compare tool will be used for the document types you selected.
Related Links
DITA CMS file comparison utilities on page 197
Configure import and export directories

This procedure lets you specify default directories for frequently performed import/export
operations.
The Import Export options let you configure the source and target directories for your most
frequently performed file operations such as importing images and exporting files for localization.
The following diagram shows the Import Export preferences dialog:

For Export directories, you can enable Auto-Save, which means that this directory will always
be used and the Save dialog will not appear to let you specify an export directory. You'll just see
an information dialog to show you where the files were written.

2. Select DITA CMS > Import Export.
The Import Export pane appears.
3. Click the Browse... button next to the directory field to configure.
The Browse For Folder dialog appears.
4. Navigate to the required folder.
You can create a new folder, if applicable.
5. Click OK.
The path to the selected folder appears in the directory field.
6. Select Auto-save, if desired.
7. Click Apply.
8. Click OK.
The specified directories will be used for future import and export operations.
Related Links
Add the root-catalog.xml catalog to the oXygen editor

For the DITA CMS to locate the DTDs for the DITA objects and elements in your documentation,
you must add the root-catalog.xml file to the oXygen editor.
The root-catalog.xml dynamically points to the master-catalog.xml catalog file, which contains
the list of all the catalogs used by the DITA CMS. If you add a new catalog to the system, make
sure to add it to the master-catalog.xml catalog file as described in the Integrating DTDs into the
DITA CMS document.
1. From the Window menu, select Preferences.

2. Select oXygen > XML > XML Catalog.
The XML Catalog pane appears.
3. Click the New (+) button, as shown below.
The Choose Catalog dialog appears.

4. In the Choose Catalog dialog, click the Browse button's selection arrow and then
select Browse workspace.
5. Expand the REPOSITORY node and then select the root-catalog.xml file.
Note: If you do not see this file:
• Click Cancel twice to return to the Preferences dialog.

• In the Preferences dialog, select General > Workspace.
• Select Refresh using native hooks or polling and click Apply.
• Repeat this procedure from step 2. You should now see the file.
6. Click Open.
The Choose Catalog dialog reappears, with your selection in it.
7. Click OK.
The Preferences dialog is displayed again and the root-catalog.xml catalog is listed in the
Catalogs list.
8. In the Preferences dialog, click Apply and then OK.
The DITA CMS catalogs are now available to the oXygen editor.
Configure column display in any DITA view

You can specify the columns you want to see in each view and then place them in the order that
you prefer.
Use this procedure on any view that includes columns of data. To select and arrange the
columns you want to display:
1. Right-click any column header.

The column selection menu appears:
Figure 74: Selecting columns for DITA Map view
2. Select the columns to display and clear those you don't want to see.
The selected columns appear in the view.
3. Drag the columns into your preferred viewing order.
Restore warning messages

This option lets you select the warning messages that you want to re-activate.
Many of the DITA CMS actions, such as Revert to server revision, launch a warning dialog that
asks you if you're sure you want to continue. These dialogs have a checkbox that you can select
if you want to stop the warning dialog from appearing.
If you decide that you would prefer to receive these warnings in future, you can reactivate them
using this procedure.

3. In the Reset Warnings area, select the warning messages you would like restored.
4. Click Apply.
5. Click OK.
The selected warnings will now appear.
Bring a process out of background

Use this procedure if you've selected Always Run in Background for a DITA CMS process and
you'd like to restore it to the foreground.
Many DITA CMS processes, such as Generate Output and Sub-tree Release, show a dialog that
gives you the option of running the process in the background. This dialog also contains a
checkbox - Always run in background - which, once selected, will permanently minimize the
process; now and in future.
This procedure restores all processes where you have selected Always run in background.

2. Select General.
The General pane appears.
3. De-select the Always run in background checkbox.
4. Click Apply.
5. Click OK.
Glossary
Term Description
Conref An abbreviation of “content reference”. A DITA hypertext mechanism

that provides a means for re-using frequently repeated phrases or
passages of text.
Document A file containing information. In the DITA context these are

predominantly XML format (topics and maps). However, the term also
includes the reviewing PDFs and the various binary formats that are
used for images. By extension, this may also refer to the final document
deliverable in its entirety.
Document deliverable The final document that is produced by the map and its component
topics and images. A PDF file destined for printed output would be one
type of document deliverable; an online help module would be another.
With some foresight, a single topic may be used in both types of
deliverable.
Map An XML file that contains references to topics, and that structures the
document deliverable as a whole. In a book deliverable, it is the basis
of the Table of Contents.
Project The entire set of information required by a manager for producing a

multiple-document project: one involving a user guide, installation
manual, quickstart and help modules, for example.
Status point A point in the document development life cycle, expressed as its cycle
and state written together, e.g., Authoring:draft. Also known as the
document's status.
Topic An XML file that deals with a single unit of information.

DITA CMS shortcut keys
Shortcut keys let you perform many routine actions with just two or three keystrokes.
The following table shows you the keyboard shortcuts currently implemented in DITA CMS.
If there are any Windows CTRL+ALT shortcuts mapped to the key sequences shown here, the
Windows shortcuts take precedence.
The key mappings shown in this table are the default. Your system may be set up differently. If
you want, you can change key mappings through the Preferences dialog.
Note: Some shortcuts may conflict with other Eclipse plug-ins.
Feature Shortcut Icon Other Access Description and

comments
Clean all CTRL+SHIFT+V DITA CMS > Clean Resets all views to
Views All Views their original default
state, without
rearranging their
position in the DITA
Perspective.
Copy CTRL+C Copy selection to

clipboard.
Create map CTRL+ALT+M DITA CMS > Create Opens the Create
Map Map dialog.
Create topic CTRL+ALT+T DITA CMS > Create Opens the Create
Topic Topic dialog.
Cut CTRL+X Cut selection to

clipboard.
Delete Del Standard delete.
Delete Del Deletes the selected

document and all its
children in the DITA
Map view or DITA
Map Editor.

comments
Demote CTRL+RIGHT Demotes the selected

document ARROW document one level in
the DITA Map view or
DITA Map Editor.
File CTRL+N File > New > Other... Opens the New -
/New/Other Select a Wizard
dialog
Find CTRL+F Opens the

Find/Replace dialog.
Create image CTRL+ALT+I DITA CMS > Create Opens the Show/Edit
Image Image dialog.
Import CTRL+L DITA CMS > Import Opens the Import

localization Localization Package Localization Package
package dialog.
Move down CTRL+DOWN Moves the selected

one level ARROW document one level
down within a branch
in the DITA Map view
or DITA Map Editor.
Move up one CTRL+UP Moves the selected

level ARROW document one level up
within a branch in the
DITA Map view or
DITA Map Editor.
Open/ close Spacebar With the parent

current branch document selected,
toggles the current
branch open and shut
in the DITA Map view
or DITA Map Editor.
DITA CMS shortcut keys 625

comments
Paste CTRL+V Paste from clipboard.
Promote CTRL+LEFT Promotes the selected

document ARROW document one level in
the DITA Map view or
DITA Map Editor.
Redo CTRL+Y • In a text editor -

redo typing.
• In DITA Map view
or DITA Map Editor
- redo the latest
move.
Refresh CTRL+ALT+F5 Updates the Preview

preview view.
Retrieve CTRL+SHIFT+0 Right-click the object Retrieves the revision

revision and select Revision history.
history History.
Save CTRL+S File > Save Saves the current

document.
Save all CTRL+Q File > Save all Saves all documents.
Synchronize CTRL+ALT+S DITA CMS > Copies the most

configuration Synchronize recent version of
Configuration system configuration
files from the server to
your hard drive.
Undo CTRL+Z • In a text editor -

undo typing.
• In DITA Map view
or DITA Map Editor
- undo the latest
move.
Related Links
Configure key mapping on page 608
Index
A BIRT, install 498
Branch 368–376
Add 75 conrefs 374
Documents to favorites 75 create new 370
Add image directly to map 283 documents 372
Add resource directly to map 272 images 373
Advanced search 102, 105 map 370–371
Multiple operators 102 merge 376
without operator 105 resources 375
Advanced Search 96 revert 376
Operators 96 topic(s) 371
See also sub-tree
Advanced Search features 96 Bulletin Board 442, 472–473

Alerts 145, 152, 443, 448, 476
Annotations 323–324, 326, 329–331
about 329 C
copy 330 Cannot delete window 189
display selected 331 Children intersection, export 200
enter 323 Clean all views 83
modify 329, 331 Clear search results 121
refresh 324 Clone 183, 453
revise 326 Maps, topics, and images 183
update 324 project 453
Annotations view 322 Collaborative Reviewer 322–323, 325–327, 329–330, 332–333
Append search results 89, 128 about 322
isolate 128 attach file to PDF 325
Apply 116 copy annotations 330
XSLT to topics 116 enter comments 323
Approval system 308, 325, 456–457 modify annotations 326, 329
assign to document 308 previous reviews 327
set default 456
See also Vote on document see-note 332–333
Archive 563 vote on a document 325
Assignments 147, 204, 278, 304, 310, 405, 409, 412, 417, 448, 463–464, Columns, configure display 63, 617
476 Comment 187, 323, 326
default 147, 204, 278, 405, 409, 412, 417 on a PDF review file 323
Associate file extensions with editors 77 on an annotation 326
Attach file to PDF review file 325 On status change 187
Attributes 173, 206, 338–340, 342, 345, 347, 354–355 See also annotations
Compare documents 197–199, 201

conditional map objects 339–340, 342 Compare tool 612
conditional text 206, 338, 345 Concurrent localization model 589, 593
Conditional text 347, 354–355 Conditional processing 347, 354
edit map 173 Conditional text 206, 338–340, 342, 345
Auto-generated columns 503, 522 Configuration files, synchronizing 85
Configuration files, update 190
B Configure 50
User settings 50
Background, restore process from 618 Connection 66
Benefits of DITA 36 Connection information 64
BIRT reports 499, 505–507, 509–512, 521 Conref 46, 203, 374, 621
data set 505–506, 511 branch 374
Data Set Definition dialog 499 definition 621
data source 507, 509–510 Copy 253–254, 276, 330
examples 512, 521 annotations 330
overview 499 file name 253
Copy (continued) Display (continued)
full path 254 Recent operations 71
ID 254, 276 topic titles in maps 163
reference 253 DITA Map Editor 143, 145, 152
Copy the reference of a Ditaval file 356 DITA Map view 143, 145, 152, 170
Create 133, 147, 174, 204, 264, 278, 348, 352, 354, 370, 450, 485 advanced features 170
A query 133, 485 DITA perspective 58
branch 370 DITA topics and maps 36
Conditional processing profile 354 Ditaval files 347–348, 354–356
Ditaval files 348 Copy reference 356
Ditaval folders 352 Create 348
map 147 Delete 356
new image 278 Edit 355
project 450 Manually update 354
resource 264 Review values 355
topic 174, 204 XML contents 354
Cross-reference 245–246, 295–296 Ditaval folders 352, 356
CRT row 219, 533 Create 352
Customer support 29 Delete 356
contact information 29 Document 147, 204, 211, 278, 304, 306, 308, 310, 325, 448, 463–464, 476,
Customize 132 621
Search view layout 132 approval system 308, 325
Cycles 43 assignments 304, 310, 448, 463–464, 476
assignments, default 147, 204, 278
definition 621
D due date 306, 310
spell check 211
Data set 499, 505–506, 511, 513, 516–517, 521, 523–526
Document cycles 42
BIRT 511, 516–517, 523–526
Document deliverable 621
DITA CMS 499, 505–506, 513, 521
definition 621
Data Set Definition dialog 499–503 See also Deliverable
columns 500–503 Document development process 43

filters 502 Document management 179
Data source 507, 509–510, 514–515, 522 Document objects 180, 189–190
BIRT 509–510, 515 Deleting 189
DITA CMS 507, 514, 522 Releasing 180
Date search features 107 Restoring 190
Default directories 613 Document properties 185
import and export 613 Displaying 185
Default role assignments 304, 463–464 Documents Count column 503, 522–524
assign documents to 304 Documents view 70
See also Team members
Drop points 145, 162

Default search settings 132
Due date 306, 443, 451, 457, 460, 466, 469–470
Defaults 131–132, 268, 283, 455–457, 463
map 457, 460, 466, 469–470
Delete 189, 356, 478
set document 306
Ditaval files and folders 356
set project 451
Document objects 189
view project 443
Project 478
Deleted document objects, restoring 190
Deliverable 457, 459–460, 465–466, 468–470, 621 E
add to project 465
due date 457, 459–460, 466, 468–470 Edit 150, 154, 209, 268–269, 284, 286
remove from project 466 image 286
Deliverables List 442–443 image metadata 284
Dependencies view 258–261 map 150, 154
export as TSV 261 resource document 269
Dependencies, about 46 resource metadata 268
Display 71, 75, 163, 185 topic 209
Document properties 185 Edit Ditaval XML 354
Favorites 75 Editors 67, 80, 606, 612
Recent documents 71 about 67, 80
Editors (continued) Image (continued)
configure 606, 612 insert from remote location 250, 301
Element 172–173 multiresolution 277
add to map 172 open 283
change 173 preview 281
display 172 replace 285
edit 173 search for references to 276
Email notification 47 set default 283
Errors, locate 130 thumbnails 282, 611
Exclude conditions in Ditaval files 348 Image localization kit 586, 597
Export 153, 200, 261, 613 images 287
children intersection as TSV 200 export 287
configure default directories for 613 Import 285, 405, 409, 412, 417, 601, 613
Dependencies view as TSV 261 configure default directories for 613
map as TSV 153 images 405, 409
export images 287 Localized images 601
Export search results 121 Localized maps and topics 601
maps 412
modified image 285
F topics 417
Include conditions in Ditaval files 348
Favorites 75–77
Indicators 60–61, 145, 152, 369, 443, 445, 448, 476
Displaying 75
Information view 192
Managing 76
Insert 173, 250, 300
File associations 77
attributes 173
File name, copy 253
images 250, 300
Files 180, 189
Install new software 498
Deleting 189
Inward soft links 270
Lock 180
Isolate search results 128
Filter search results 121
G K
Keep locked option 180
Generate output 563
Key mapping 608
Group search results 123, 481
Keydefs 386–388, 392–394, 396, 398
Grouping search results 125
Keyrefs 386–388, 392–394, 396, 398
H L
History list 143, 171
Labels 314–318
History, document 196, 198–199
assign 315
History, search 136
configure 314, 317–318
remove 315–316
I undefined 317
Languages Translation languages
, See
Icons 59–61, 145, 152, 369, 443, 445, 448, 476 Lateness 442
ID 147, 150, 254 Localization 278, 284, 455–456, 470, 472, 585–586, 595–598, 601
copy 254 designate image as requiring 278, 284
user-assigned 147, 150, 254 Image localization kit 597
Image 183, 250, 276–278, 281–286, 300–301, 373, 611 Localization kit 598
about 276 Pre-localization kit 595
Add directly to map 283 specify languages for 455–456, 470, 472
branch 373 Localization kit 586, 598
Cloning 183 Localization models 589–590, 593
create 278 Localize method 596
designate as requiring translation 278, 284, 286 Locate errors 130
edit 286 Locate search results 121
edit metadata 284 Lock files 180
insert 250, 300 locktitle attribute 165
Login 64, 66 Open (continued)
Login, logout 50 map 150–151, 466
topic 205–206
Open With... 150–151, 206
M Operators in Advanced Search 96
Orphan documents, search for 89
Managing 76
out-of-scope links, validate 176
Favorite documents 76
Output, generating 562–563
Map 110, 112, 145, 147, 150, 152–154, 157–163, 167–168, 172, 183, 370–371,
Outward soft links 270
457, 465–466
Overload 448, 476
add documents 162
oXygen 294, 615
add element 172
configure 615
add to another map 157, 162
quick reference 294
add to project 465
branch 371
Cloning 183 P
create 147
create new branch 370 Parent-child relations for a document 46, 258
drop point 145, 162 PDF review file 323, 326–327, 329
due date 457, 466 Personal queries 133, 485
edit 150, 154 Perspectives 54, 58, 83
element, display 172 Plug-in 498
export as TSV 153 Pre-publication flags 152
move within map 158 Preferences 50
open 150, 466 For DITA CMS connection 50
pre-publication flags 152 Preferences dialog 608
re-position documents in 158–161 prerequisites, adding soft link indexes 272
remove from map 168 Preset comments 180
remove from project 466 Preview 206, 281, 345
rename 167 Print 152, 168, 473–475, 563
Replacing text in topics of 112 map 152, 168, 473
Searching XML content 110 output 563
topic alert indicators 145 statistics 474–475
topic title display 163 Project 450–454, 465–466, 475, 478
Map ID 147, 150, 254 add deliverable 465
Map view 165 add map 465
Showing navtitles 165 clone 453
Menus 608 create 450
Merge 378 Delete 478
branch 378 due date 451
Milestones, default 457, 459–460 remove deliverable 466
Milestones, map-specific 466, 468–470 remove map 466
Milestones, view statistics 475 rename 454, 475
Minimize a view 81 status 452–453
Multiple operators in Advanced search 102 Project coordinator 450, 461
Multiresolution images 277, 283 Project Management Perspective 441
about 277 Project Management view 442–443, 445
set default 283 Properties view 173
Publish 562
N
Q
navtitle element 165
Queries 133
Query 133–135, 137–139, 485, 499, 512
O Creating 133, 485
edit 137
Offline Perspective 289–292
personal 137
Open 75, 150–151, 205–206, 283, 466
Personal, running 134
Favorites panel 75
release 137
image 283
replace with server revision 137
Query (continued) Revert (continued)
share 138–139 file 194
TEXTML 137 object 196
TEXTML, running 135 Revisions 137, 194, 196, 198–199, 327
use with BIRT 499, 512 compare 198–199
revert to previous 137, 194, 196
view previous 194, 196, 327
R Roles 47, 64, 304, 306, 308, 461, 463–464
about 47
Read-only Editor 205, 606, 612 See also Default role assignments
Recent Documents 71, 74 Root ID 254, 412

Recent Documents panel 75
Recent Operations 71 S
Recent Operations panel 73
Referable-content 203 Search 89, 94–96, 109–111, 118, 121, 126, 131–133, 135–136, 438, 485, 606
reimporting same file into the DITA CMS 421 Append results 89
Related links 251–252, 298–299 by taxonomy terms 109, 438
to file or web site 252, 299 defaults 131
Relationship Outline view 216, 530 locate topics in map 118
Relationship table Reltable , See
output 118
Relationship Table Editor view 216, 530 Re-run 136
Release 183 re-use 135
All subtopics for a topic 183 Restore default settings 132
Release a map, topic or image 180 save 133, 485
Release Ditaval XML 354 within a sub-tree 111
Reltable 216, 218–229, 232–233, 236–237, 239, 241–242, 530, 532–533, 535– Within search results 126
544, 546, 548, 550–551, 553, 555–556 XML content of a map 110
add a topic and its children to a cell 223, 537
See also Search results
Search and Replace 112, 116, 123, 125, 481

add cell 221, 535 Search features 87
add row 219–220, 533, 535 Search history 136
add to map 218, 532 Display or clear 136
add topic group to a cell 223, 537 Search results 121, 123, 125–126, 128, 481
add topic to a cell 222, 537 Apply groupings to 125
assign name 222, 536 Clear view 121
assign row name 222, 536 Export 121
change type 225–226, 539–541 Filter 121
example 233, 236–237, 239, 241–242, 548, 550–551, 553, 555–556 Groupings 123, 481
linking direction 227–228, 542–543 isolate 128
locate row 229, 232, 544, 546 Locate topics in DITA MAP view 121
remove cell 224, 539 Searching within 126
remove row 224, 538 Search Results 111
Reltable Editing Perspective 216, 530
See also Reltable
locate topics in DITA Map view 111
Remove soft links 271 Search Results view 89
Rename 167, 208, 454, 475 Search Results view functions 121
Replace with server revision 137, 194 Search view layout 132
Reports BIRT , See
Customize 132
Resource 264, 267–268, 272 See-note 332–333
about 264 Sequential localization model 589–590
Add directly to map 272 Share queries 138–139
add item 267 Shortcut keys 294, 608, 623
create 264 Signature 328
edit metadata 268 soft links 272
set default 268 adding indexes 272
Restore 190 Soft links 270–271
Document objects 190 softlink.id is not a valid key message 272
Restore a view 81 Software 498
Restore default search settings 132 install new 498
Retranslate from source 603 Spell check 211
Revert 194, 196, 376 States 43
branch 376 Statistics 168, 448, 473–476
Status 43, 46, 187, 452–453, 562 Translation language (continued)
Change 187 map-specific 445, 470, 472
for publication 562 Retranslate from source 603
Status point, defined 621 TSV 153, 200, 261
Sub-trees 111, 146 export children intersection as 200
Substantial Change option 180 export Dependencies as 261
Synchronize configuration files 85, 190 export map as 153
Synchronize files 610–611 TSV file 505
create as DITA CMS data set for BIRT 505
T
U
Taxonomy terms 109, 434, 437–438
add keywords to documents 437 Undefined labels 317
add terms to document metadata 437 Update files 180, 190
add terms to documents 434 User 47, 304, 461, 463–464
locate within Terms pane 438 assign documents to 304
search repository using 109, 438 roles 47, 304, 461, 463–464
Taxonomy Terms view 426 User documentation 30
Taxonomy, editing 430–432 User roles 42
create new taxonomy 430
Team members 304, 310, 448, 461, 463–464, 476
assign documents to 304 V
assign roles in project 463
Validate out-of-scope links 176
view documents assigned to 310
Values Count column 503, 522–524
view workload 448, 476
Version label 562
Technical support 29
Versions revisions
contact information 29
, See
View 74, 77, 170, 205–206, 216, 281, 322, 345, 442, 530
TEXTML queries 133, 485
Annotations 322
TEXTML Server connection information 50
Bulletin Board 442
Thumbnails 208, 282, 611
Deliverables List 442
Timelines 47
DITA Map 170
about 47
Documents 74, 77
Todo List 310
Preview 205–206, 281, 345
Toolbars 61, 63, 609
Project Management 442
Topic 37, 145, 152, 157–158, 162, 168, 174, 183, 204–206, 208–209, 222–
Relationship Outline 216, 530
223, 345, 371, 537
Relationship Table Editor 216, 530
add a topic and its children to reltable 223, 537
Votes 322
add to map 157, 162
Views 67–68, 70, 75, 80, 82, 143
add to reltable 222, 537
about 67
alert indicators 145
DITA Map 143
blocking map progress, indicators 145
Documents 75
branch 371
refresh 82
Cloning 183
restore a stack 82
create 174, 204
restore single 82
edit 209
show 68
modified in map, indicators 145 See also editors
move within map 158 Vote on document 308, 325

open 205–206
pre-publication flags 152 W
preview 206, 345
remove from map 168 Warning messages 618
rename 208 without operator in Advanced search 105
types 37 Workload 448, 476
Topic groups 223, 537
add to reltable 223, 537
Topic stubs 174 X
Topic titles 163
Translation language 445, 455–456, 470, 472, 585–586, 595–598, 603 Xref 245–246, 295–296
default for project 455–456 file or web site 246, 296
Xref (continued) XSL transformations 116
topic 245, 295
within topic 295

DITA CMS User Guide OXygen

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

DITA CMS User Guide OXygen

Uploaded by

Copyright:

Available Formats

DITA CMS User Guide for

DITA CMS documentation 30

New in this documentation release 31

Chapter 1: About DITA

DITA topics and maps 36

DITA CMS functionalities 38

Chapter 2: Understanding the DITA CMS document cycles

About document cycles 42

Document development process 43

Document status dependencies 46

User roles and timelines 47

Chapter 3: Starting the DITA CMS

Log in to DITA CMS 50

Log in to DITA CMS from Eclipse clients with preconfigured settings52

Open an Eclipse Perspective 54

Chapter 4: The DITA CMS working environment

Open the DITA perspective 58

Icons and colors 59

The DITA CMS toolbar 61

Show or hide the workspace toolbar 63

Configure column display in any DITA view 63

Display or modify connection information 64

About views and editors 67

Other useful views 70

Display recent documents and recent operations 71

Filter Recent Operations display 73

Clear the Recent Documents panel 74

Add documents to your Favorites list 75

Manage your Favorites list 76

Remove entries from the Favorites panel 77

Associate file extensions with applications 77

Working with views and editors 80

Maximize, minimize, or restore a view 81

Restore a single view 82

Restore a stack of views 82

Clean all views 83

Other DITA CMS perspectives 83

Synchronize configuration files 85

Chapter 5: DITA CMS Search

Search view enhancements 88

Search for documents 89

Search example: Searching for a specific topic type 94

Search example: Searching for a DITA element 95

Search example: Searching for a specific element 96

Advanced Search features 96

Advanced Search example: Using multiple criteria 102

Advanced Search example: Using the without operator 105

Date search features 107

Search for documents that contain taxonomy terms 109

Search the XML content of a map 110

Search within a sub-tree 111

Search and replace the XML content of a map 112

Apply XSL transformations to one or more topics 116

Select the current topic in a map 118

Standard search operators and wildcards 118

Search Results view operations 121

Create search results groupings 123

Apply groupings to search results 125

Search within search results 126

Isolate appended search results 128

Locate errors 130

Configure search 131

Set default search parameters 131

Restore search defaults 132