XMetaL with DITA Evaluation Guide

JustSystems Canada Inc.

Contents
Welcome to XMetaL Author...........................................................................................5 Introduction to DITA authoring......................................................................................7 XMetaL advantages........................................................................................................9 Learn more....................................................................................................................11 About this guide...........................................................................................................13

Chapter 1: XMetaL at a glance.................................................................15

Choose a view............................................................................................................................................15 Identify the current element........................................................................................................................16 Display elements.........................................................................................................................................16 Create content............................................................................................................................................18 Edit your document.....................................................................................................................................18

Chapter 2: Creating topics and maps.....................................................19

Create a map..............................................................................................................................................19 Create a topic and add it to a map..............................................................................................................20 Organize topics in a map............................................................................................................................20 Create a bookmap......................................................................................................................................21 Specify relationships between topics..........................................................................................................21 Create an index entry.................................................................................................................................22 Insert a cross-reference..............................................................................................................................22

Chapter 3: Creating and binding keys....................................................25

Create a key definition and add it to a map................................................................................................25 Create a key definition with keyword and add it to a map...........................................................................25

Chapter 4: Re-using content....................................................................27

Working with content and key references...................................................................................................27 Insert a content reference...........................................................................................................................28 Insert a key-based content reference.........................................................................................................28 Insert a key reference.................................................................................................................................28

Chapter 5: Working with conditions........................................................31

Apply conditions..........................................................................................................................................31 Create a condition.......................................................................................................................................32

Chapter 6: Operating on multiple topics................................................33

Finding text content.....................................................................................................................................33 Spell checking topics in a map....................................................................................................................33 Run a custom cross-file operation..............................................................................................................34

Chapter 7: Publishing...............................................................................35
Generate output..........................................................................................................................................35 Generate output with complex conditions...................................................................................................35

iii

Welcome to XMetaL Author

Built on a history of support for structured authoring, XMetaL Author offers unparalleled exibility and performance. The best-of-breed feature set is designed to simplify your DITA-based authoring and deployment tasks. XMetaL is designed for DITA XMetaL is designed to make correct DITA markup automatically. You dont have to memorize DITA markup rules or constantly think about its details. The content you create is continually checked for validity, and you are prevented from entering content that would make your document invalid. XMetaL also supports DITA specializations with a minimum of setup work. You can also customize the formatting of DITA elements, for example, to treat them as tables. XMetaL is WYSIOO XMetaL is WYSIOO (What You see Is One Option), rather than WYSIWYG (What You See Is What You Get). Your documents are styled in a logical, easy-to-read way. For example, section titles are bold, and numbered lists are auto-numbered. However, there are differences between how your document looks in the editor and how it looks in print or HTML. This is because different style sheets are used for producing output. XMetaL is easy to configure As you complete the exercises in this guide and become familiar with XMetaL, you may nd things that you want to change and features you would like to add. You can easily customize the authoring environment and style sheets. For example, you can do the following: Change the style sheets for generating PDF and HTML output, to reect corporate standards. Add or remove menu commands and toolbar buttons. For example, if you dont want writers to use the <bold> element, you can remove the Bold toolbar button and inline element. Add a custom dialog box for recording topic metadata. Change the way that element IDs are automatically generated. Change the way topics are named. By default, XMetaL adds prexes to topic le names to reect the topic type, such as c_ for concept topics. XMetaL can support different document types XMetaL is designed to support DITA out of the box, and the exercises in this guide refer to examples of DITA documents. However, your company may need to author documentation according to a standard other than DITA. Some companies set up XMetaL to efciently create content for news web sites, printed catalogs, training materials, forms, and legal contracts. Designing the XML vocabulary and the user interface for creating a new type of document requires a signicant amount of setup work. If you need to work with these XML editor for a specic type of document, please contact us. XMetaL is not ... XMetaL is not a content management system. The content you create with XMetaL can be stored on your Windows le system, or in a source control or content management system.

XMetaL is not a page layout tool. It comes with style sheets that are used to display your content in the editor and in the output you generate. You can customize the existing style sheets or develop your own using another application.

XMetaL with DITA Evaluation Guide

Introduction to DITA authoring

If this is your rst introduction to writing structured or topic-based content, take a few minutes to learn about why teams are adopting this strategy. Why structured authoring? XMetaL Author is a full-featured editor for creating structured documents in XML. Although word processors are useful for writing letters and ad-hoc documents, they cannot address the need to publish information in a standard format or re-use part of the content in another document. Structured authoring environments require authors to follow a dened set of rules that determine what kind of content can be added to a document and in what sequence. Rules are dened in a DTD (Document Type Denition) or schema le. If you're new to structured authoring, youll nd that you cant arbitrarily add content anywhere in a document. Structured environments direct you to place certain types of content at specic locations. Formatting and layout are determined not by authors, but by style sheets. You can easily create and deploy style sheets that meet the needs of your organization. By being relieved of the responsibility for formatting, writers can concentrate on writing. Structured documents let you realize the following advantages: Eliminate the repetitive, time-consuming tasks involved in preparing content for publishing Ensure that your content satises regulatory or legal requirements, for example, by containing required warning messages Ensure that your content can be properly catalogued and searched Support for content re-use, for example, among service manuals for several products Allow content to be deployed in different formats, for example, in print and online Support for personalized content for different audiences Reduced localization costs, by localizing only the changed XML source, not the generated deliverables Why Topic-Based Authoring? The Darwin Information Typing Architecture (DITA) is an architecture for topic-based, structured XML authoring. As opposed to standards that support long, book-oriented writing, DITA is optimized for creating content in small, discrete units called topics that you then can organize in different ways to product output deliverables, including books, Web page content or online Help systems. You specify the organization for the deliverables using an XML le called a DITA map. Why Topic-Typed Authoring? DITA not only organizes content into topics, it also species a type for each topic. Each topic type has a specic set of rules for authoring content. For example, you cannot include a step in a concept topic because steps are only valid as part of a task. This structure guarantees consistency for all the topics of the same type. XMetaL provides templates so that you can start writing DITA-based topics quickly and easily. If you need to either further restrict the structure of a topic or need to change the rules for a topic type, you can specialize the topic. However, this requires signicant XML and DITA prociency.

XMetaL advantages
XMetaL Author has some characteristics that set it apart from other DITA-based authoring solutions. Content references DITA supports reuse in several ways, one of which is by using the conref attribute to reference content from one topic or le into another. XMetaL enables you to create and manage content references by browsing to the target that you want to reference, so that you do not have to type le paths and element IDs. You can work with referenced content displayed within the document, as it would appear in output. Conditional text DITA has powerful support for creating multiple variations of a document from a single set of source les. You can congure XMetaL's conditional text feature to use conditions specic to your organization, and then assign conditions to content using a simple dialog. You can then display conditional text with color-coding, and produce deliverables with complex sets of conditions by clicking a few checkboxes. Integrated publishing capabilities XMetaL integrates with the DITA Open Toolkit for publishing deliverables. You do not have to install the Toolkit separately. XMetaL also includes enhanced support for PDF output to improve bookmap generation. This support includes extended conguration options for PDF publishing for better control over output without XSL-FO programming. Templates By default, XMetaL includes templates for each DITA topic type, maps, and bookmaps. When an author creates a new topic, the template of the appropriate type opens and provides the commonly used elements for the topic. This helps new authors get started quickly and provides default structure for the topics. If the default templates do not contain the elements you want authors to use or if you want embed instructions in the templates, you can easily update them. Natural Structured Authoring XMetaL includes special features to support writing valid DITA, without having to know the details of DITA markup or having to view tags. For example, when you press Enter, XMetaL creates the most likely subsequent element to follow the current one. When you copy and paste formatted content from Word or HTML documents, XMetaL converts the formatted content to valid DITA markup. Specialization support Administrators can easily congure XMetaL to support specializations of DITA topics and maps.

Learn more
To learn more about DITA, check the following resources:: XMetaL online Help and the XMetaL website at http://www.xmetal.com XMetaL Community Forums at http://forums.xmetal.com DITA Language Specication, available from the Help menu or at http://docs.oasis-open.org/dita/v1.2/spec/DITA1.2-spec.html http://dita.xml.org DITA TC FAQ about keys is at http://dita.xml.org/resource/dita-tc-faq-about-keys Organization for the Advancement of Structured Information Standards (OASIS) at http://docs.oasis-open.org DITA Open Toolkit User Guide available at http://dita-ot.sourceforge.net/1.5.4/readme/DITA-readme.html xmetal-dita and dita-users user groups at http://groups.yahoo.com

11

About this guide

The exercises in this guide are designed to familiarize you with the XMetaL editor. Although they are designed to be done in order, you do not have to complete an exercise before moving on to the next one. Sample files Some exercises refer to sample les that are included with XMetaL. These les are best accessed the rst time through the Help > Samples > World Time Pro (DITA) menu item. This shortcut will create and open a copy from My Documents folder under: My Documents\XMetaL\Samples\DITA. You can restore the sample les to their original state any time by deleting the folder mentioned above. The next time you open the samples from the Help menu, XMetaL will create a fresh copy.

13

Chapter
XMetaL at a glance
Views

XMetaL provides four ways to view the same document. Choose a view that you nd most comfortable for your style of work and your level of expertise with DITA and XML. Table 1: XMetaL Views
Name Normal Description This is a styled view of your document, similar to word processors and HTML. When you work in Normal view, XMetaL keeps your document valid. Like Normal view, this is a styled view of your document. Element tags are displayed, indicating where elements start and end. When you work in Tags On view, XMetaL keeps your document valid. This is an unformatted view of your XML content. This view is useful for troubleshooting or if you need to paste raw XML into your document. This is a preview of how your document will look once it has been rendered as HTML. You cannot edit the document in this view.

Tags On

Plain Text

Preview

Elements and attributes Like every XML document, your DITA topic is associated with a DTD or schema. The DTD includes rules about what elements are allowed at any given point in your document. XMetaL continually ensures that your document remains valid. For example, the selection of elements available in the Insert Element pane includes only those elements that are valid at the insertion point. Also, when you try to insert elements using the menus or by cut and paste, XMetaL inserts the element at the next valid location in the document if it is not valid at the cursor location.

Choose a view
You can choose a view from the menu bar or from the view button bar. If you are not familiar with XML, try working in Normal view. If you are familiar with structured content, switch to Tags On view to see element boundaries. 1. Open the le AboutWorldTimePro.xml . By default, the document appears in Normal view.

15

2. Do one of the following: Click View and select a view Click a view button at the bottom of the document editor

Identify the current element

The list of elements that are valid to insert depends on the position of the cursor in your document. The context bar displays the location of the cursor within the XML elements of the document. Switch to Tags On view for this exercise. 1. Open the le AboutWorldTimePro.xml. 2. Place the cursor within a List Item (<li>) element. Check the context bar at the bottom of the editor. The context bar identies the element in which the cursor is located, as well as all the ancestors of that element. (Ancestors may not be an exact match for this illustration.)

3. Select the list item including the opening and closing tags. The following image shows that the context bar now shows the parent of the selected item.

Display elements
The Insert Element pane displays a list of the elements that are valid at the insertion point. You can choose to display all valid elements or the most frequently used (and valid) elements. Switch to Tags On view for this exercise. 1. Open the le AboutWorldTimePro.xml . 2. Place the cursor in the rst paragraph (<p>) element. 3. Type the shortcut Ctrl+Enter The In-place, look-ahead Element List is displayed near the current insertion point. It contains a list of elements you can insert into your document. 4. Select an element from the In-place, look-ahead Element List and type Enter The selected element is inserted. Note: The element may not be inserted exactly at the location where your cursor was position. If the element is not valid at that location, XMetaL will nd the next valid location to insert the element. 5. If the Insert Element pane is not already visible, click View > Element List to display it. By default, the pane displays the All tab. This list displays all the elements that are valid at the insertion point.

16

XMetaL with DITA Evaluation Guide

XMetaL at a glance

6. Move the cursor to different places in your le and observe how the Element List changes. 7. Click the Used tab. The Used tab displays only elements that are currently in use in open documents.

17

Create content
XMetaL includes many editing features you would expect to nd in a word processor. However, if you work in Normal or Tags On view, some operations may be different than what you are used to. This is because XMetaL keeps your document valid as you work. 1. Open the le AboutWorldTimePro.xml. 2. Now you can begin creating and editing content. As you edit, youll notice how XMetaL handles some common operations. Try the following: Write some new sentences. Click in different parts of the document and press the Enter key. Youll see that XMetaL creates a new element that is appropriate for the context. For example, press Enter at the end of the topic title to create the Short Description element. Highlight a selection of text in a paragraph and drag and drop it to another location. If the location is valid, XMetaL moves the selected text. Copy and paste multiple paragraphs or tables from Word, Excel, or HTML. See how heading styles are mapped to sections, and lists to lists. Select multiple paragraphs, and turn them into a bulleted list by clicking Insert > List > Bulleted List. Select a paragraph, then click Paragraph > Change Paragraph Type > Note. XMetaL changes the selected paragraph to a note. To undo your changes, click Edit > Undo or press Ctrl+Z. XMetaL supports multiple levels of Undo.

Edit your document

Use the editing features to check spelling and nd and replace. You can also track your changes. 1. Open the le AboutWorldTimePro.xml. 2. Click Tools > Track Changes and make some changes to your document. Notice how changes are marked according to the type of modication made. You can accept or reject changes by clicking Tools > Accept or Reject Changes. 3. Choose Tools > Spell Checker and spell-check the document. 4. Choose Edit > Find and Replace to nd and replace terms in the document.

18

XMetaL with DITA Evaluation Guide

Chapter
Creating topics and maps

You may be familiar with writing a section or a chapter, but DITA focuses on a much smaller unit of information: the topic. The topic is the basic building block for DITA information. DITA provides the following topic types: Concept. For general, conceptual information such as a description of a product or feature. Task. For procedural information such as how to use a dialog. Reference. For reference information. If you have completed the exercises that show you how to edit a document, you are already familiar with DITA topics. Open the le AboutWorldTimePro.xml and switch to Tags On view. Check the rst or root element; it is <concept>. This means that the document is a concept topic. You can organize topics into a DITA map or bookmap. A basic map allows a hierarchy of topics, and bookmaps also support book divisions such as chapters and booklists such as indexes. Maps do not actually contain topics, but rather references to them. These are known as topic references. Maps and bookmaps are saved with the extension '.ditamap'. Maps can also contain relationship tables, which establish relationships between the topics contained within the map. Relationship tables are also used to generate links in your published document. Many teams start writing projects by creating a map and then adding topic references to it. In XMetaL, you can create a DITA topic and insert a reference to it in one step. After you create the topic, you can double-click on the topic reference in the DITA map to open the topic. You can use your map or bookmap to generate output using a deliverable type such as HTML Help or PDF.

Create a map
The procedure for creating a map is similar to that for creating a topic. Use the menus to select the map template. 1. Click File > New. 2. On the DITA Map tab, select Map and click OK. XMetaL opens the Map Properties dialog. 3. Type a name for the map and click OK. The Map Editor opens in the Resource Manager pane. Notice that there is a set of menus in the Map Editor.

19

4. In the Map Editor menus, click File > Save to save the map le.

Create a topic and add it to a map

You can create a topic and add it to a map through the Insert Topic Reference dialog. You can open topics by double-clicking in the Map Editor. 1. In the Map Editor, click Insert > Topic Reference. XMetaL opens the Insert Topic Reference dialog. 2. In the Navtitle eld, type a title for your topic. 3. Click Create. XMetaL displays the New dialog. 4. Click the DITA Topic tab. XMetaL displays the topic templates. There is a template for each topic type. 5. Select Concept and click OK. 6. Type a le name and click OK. 7. Click OK to close the Insert Topic Reference dialog. The new topic appears in the map.

Organize topics in a map

It is easier to get a better understanding of how to organize topics in a DITA map using a populated map. Try moving topics by clicking and dragging and through the Map Editor menus. 1. Open the le WorldTimePro.ditamap. This sample map includes topics of different types. 2. Use the + and - icons to expand/collapse submaps. 3. Select the Calculating Time topic reference, then click the down arrow button on the map editor toolbar. The topic and all the topics nested within it move as a unit underneath the next topic at the same level (in this case, Using the fraction converter). 4. Select The World Time Pro window and click Edit > Demote Item. The topic and all the topics nested within it move as a unit underneath the previous topic at the same level. 5. Close the map without saving.

20

XMetaL with DITA Evaluation Guide

Creating topics and maps

Create a bookmap
The procedure for creating a bookmap is similar to that for creating a map. Use the menus to select the bookmap template. You can create a bookmap in the XML or Map Editor. 1. You can either: In the XML Editor, click File > New in the main menu. In the Map Editor, click File > New Map in the main menu.

XMetaL displays the New dialog box. 2. On the DITA Map tab, select Bookmap template, and then click OK. The Bookmap Properties dialog box opens. 3. Enter bookmap properties , and then click OK. For example, enter 'My bookmap' in the 'Main book title' eld. The bookmap opens in the Map Editor and includes the following common book elements: Front matter - contains the material that precedes the main body of a document. It may include items such as an abstract, a preface, and various types of book lists such as a <toc>, <tablelist>, or <gurelist> Untitled part - contains the chapters that make up the main body of the document Appendix - references a topic as an appendix within the bookmap Back matter - contains the material that follows the main body of a document and any appendixes. 4. Open the folders that make up the common book elements to view the contents of the available elements. 5. To rename a part of the main body of the document without adding content, select the <Untitled part> element, and then click Properties. In the Topic Title eld, enter Part 1, and then click OK. The element is now named Part A. The names of most of the elements can be changed in this manner if you do not want to directly reference content. 6. To insert a chapter within the newly renamed part elements, select the <Part 1> element. Then select Insert > Chapter Reference from the Map Editor menu, browse to the Samples folder, and select a DITA topic for the new reference. Click OK. The new chapter reference appears at the same level with Part 1 in the document hierarchy. 7. With the new chapter reference highlighted, click the right arrow icon in Map Editor. The new chapter reference is moved under Part 1 in the document structure. 8. Save the bookmap le.

Specify relationships between topics

DITA supports specifying relationships that are manifested by links between topics using relationship tables. 1. Open the sample World Time Pro (DITA) (WorldTimePro.ditamap) le. To do this, go to Help> Samples and select World Time Pro (DITA). This sample map includes topics of different types as well as a relationship table. 2. From the map editor menu, click File > Switch to XML View of Map to display the map in the editing pane. The map, viewed in the editing pane, includes a relationship table that species relationships between the topics in the map. Note: The map closes in Resource Manager.

21

3. Place the cursor in the last row of the table and click the button on the Table toolbar.

Note: You may need to open the Table toolbar by right-clicking in the toolbar area. 4. Copy the "Where to buy World Time Pro" topic reference and paste it in the rst cell of the new row. You include it in the rst column because it is a concept topic. 5. Copy the "Using the Date Analysis Engine" topic reference and paste it in the second cell of the new row to establish a relationship between the topics. You include this topic in the second column because it is a task topic. 6. Right-click on the new "Where to buy World Time Pro" topic reference and click Properties. 7. In the Topic Reference Properties dialog box, click the Special Attributes tab. 8. In the Linking eld, select "Target Only", and then click OK. The result of this setting is that the "Using the Date Analysis Engine" topic will contain a link to the "Where to buy World Time Pro" topic, but the "Where to buy World Time Pro" topic will not have a reciprocal link. 9. In the main menu, click File > Switch to Map Editor to display the map in the Map Editor. The relationship table appears as an item at the end of the map.

Create an index entry

You can specify index entries that apply to the entire topic or for a specic location in the topic. Index entries are used to create the index when you generate output. Switch to Tags On view (View > Tags On in the main menu) for this exercise. 1. Open the le About World Time Pro (AboutWorldTimePro.xml) le in Tags On view. 2. In the <prolog> element, locate and place your cursor between the <metadata> and <prodinfo> tags, then insert keywords from the Element List pane. The <prolog> element contains metadata that applies to the entire topic. 3. Place the cursor within the <keyword> element, then click Insert > Index Marker. 4. In the Index term eld, type: World Time Pro, About . 5. To add another index entry, click More Markers and type: feature summary , then click OK. 6. To add an index entry to a specic location in the topic, place the cursor at the beginning of the last paragraph, then click Insert > Index Marker. 7. Type feature summary , then click OK. The <indexterm> element appears at the end of the paragraph. 8. Close the topic without saving. To view results, generate output. For more information, see the Publishing on page 35 section in this guide.

Insert a cross-reference
When you insert a cross-reference to another topic, the title of the topic is displayed in the place of the cross-reference. Cross-references can also point to elements other than topics, such as tables and sections. Cross-references are difcult to create in tools that lack strong DITA support, but are straightforward in XMetaL.

22

XMetaL with DITA Evaluation Guide

Creating topics and maps

1. Open the sample map le. 2. In the Map Editor view, double-click the title of any topic to open it. 3. Click in a paragraph in the topic. Note: DITA 1.2 does not allow cross-references in the title or Short Description of a topic. 4. Click Insert > Link > Cross-Reference. 5. Click Browse. 6. Browse to and select another le from the DITA sample documents folder. Click OK. An <xref> element is inserted. The title of the topic you selected appears in the <xref> element. 7. View the attributes of the <xref> element you just inserted: In Tags On view, hover the mouse pointer over one of the <xref> tags. A tooltip appears. The href attribute includes the path to the le and the topic ID of the target topic. The type and format attributes have also been set automatically based on the target topic. 8. Click View > Page Preview. A hyperlinked topic title appears in place of the <xref> element. You can try generating output in multiple formats to see how cross-references appear. PDF output displays the topic title and page number. PDF, HTML, and help outputs display a hyperlinked topic title. If you change the target topic title after you insert the cross-reference, the updated title is used when you generate output. You can make XMetaL display the updated title by clicking Edit > Refresh All References.

23

Chapter
Creating and binding keys

The DITA key reference is an indirect addressing technique that separates references (topicrefs, conrefs, etc.) from the direct address of the target. Unlike the @href and @conref which contain direct addresses to the element that references, the @keyref and @conkeyref refer to key names instead of target les or addresses; the key names then are bound to specic targets by maps. Different maps can bind the same key names to different targets or resources. This form of referencing is late bound, because the binding of key names to targets is computed by the DITA-aware processor rather than from a static binding (e.g. a relative le URI) that is created when a topic or map is authored. XMetaL Author Enterprise's DITA-awareness includes the ability to conguring which late-binding to use when refreshing referent content so you can have a context-specic authoring experience.

Create a key definition and add it to a map

You can create a key denition and add it to a map through the Insert Key Denition dialog. 1. In the Map Editor, click Insert > Key Denition. XMetaL opens the Insert Key Denition dialog. 2. In the Keys eld, type one or more key names separated by spaces. 3. Click Browse to set the Href eld to a selected DITA topic. 4. Click OK to close the Insert Key Denition dialog. The new key denition and binding appears in the map.

Create a key definition with keyword and add it to a map

You can create a key denition and add it to a map through the Insert Key Denition with Keyword dialog. 1. In the Map Editor, click Insert > Key Denition with Keyword. XMetaL opens the Insert Key Denition with Keyword dialog. 2. In the Keys eld, type one or more key names separated by spaces. 3. In the Keyword eld, type a key value. 4. Click OK to close the Insert Key Denition with Keyword dialog. The new key denition and binding appears in the map.

25

Chapter
Re-using content

For DITA experts: When you insert referenced content, XMetaL adds an element with a conref (content reference) attribute that points to the referenced content. You can create content references to any DITA element. XMetaL provides the following ways of re-using content: You can attach a content reference to an existing element. You can insert an element with a content reference. DITA makes the distinction between local content, that is the text and graphics that are actually present in the element, and referenced content that is referred to by the element. You have the option of displaying local content or referenced content.

Working with content and key references

DITA has two referencing mechanisms, one direct and one indirect. For each of these DITA reuse mechanisms, a piece of content can be included by reference in multiple contexts. When you need to update that content, you need to update it in only one place. Content references are useful for standard warnings and denitions. Key references are useful for product names and other content that varies while the context does not. XMetaL includes rich functionality for creating, viewing, and managing both content and key references. You can use any of the following strategies for managing content and key references: Arbitrary content references: You may prefer to keep many pieces of reusable content in one le. For example, you might want one le to consist of a list of product names, with each product name in a "phrase" (<ph> element) within the le. Then, wherever you need to display a product name, you can insert a content reference that points to the appropriate <ph> element in this le. Arbitrary key bindings: You may prefer to keep key bindings dened in a submap (i.e. key map) and use a ditaval le to select a particular submap. Additionally or alternatively, you can dene key bindings in your root map. How content & content key references work XMetaL creates the reference to the external content by adding a conref or conkeyref attribute to an element in the local document. These attributes dene a link to the referenced content, one direct (conref) and made up of a path to the le and the topic ID within the le. The other indirect (conkeyref) and made up with a key name and the topic ID within the le for the current effective key space. The path may also reference a specic element ID within the topic. Referenced content is not physically copied to the referencing le, however XMetaL displays it as if it were actually there. You can also choose to view "local content" instead of referenced content, to edit the attributes or contents of the referencing element.

27

How key references work XMetaL creates the indirect reference to the external content by adding a keyref attribute to an element in the local document. The keyref attribute denes a link to the referenced content that best matches the local element type. There are no paths to le or extra ID addressing required. Referenced content is not physically copied to the referencing le, however XMetaL displays it as if it were actually there using an xm-replace_text processing instruction to surround the bound text.

Insert a content reference

This exercise shows you how to insert an element with a content reference. 1. Open the le AboutWorldTimePro.xml . 2. Click at the end of last paragraph in the le. 3. Click Reuse > Insert Element with Content Reference. 4. In the Start of range list box, select the element ID beginning with "ul_". A preview showing ve bulleted list items appears. 5. Click OK. A <ul> element is inserted, with a conref attribute pointing to the other <ul> element. The new <ul> element is selected.

Insert a key-based content reference

This exercise shows you how to insert an element with a key-based content reference. 1. Open the le AboutWorldTimePro.xml by selecting Help > Samples > World Time Pro (DITA). 2. Click at the end of last paragraph in the le. 3. Click Reuse > Insert Element with Key-Based Content Reference. 4. Click the Select Key button. The Select Key dialog will appear and display the associated key space 5. Select the about_world_time_pro key from the list of keys presented in the list view. 6. Click OK. about_world_time_pro key will be set into the Reference an element in this le eld. 7. In the Start of range list box, select the element ID beginning with "ul_". A preview showing ve bulleted list items appears. 8. Click OK. A <ul> element is inserted, with a conkeyref attribute pointing to the other <ul> element. The new <ul> element is selected.

Insert a key reference

This exercise shows you how to insert an element with a key reference. 1. Open the le AboutWorldTimePro.xml by selecting Help > Samples > World Time Pro (DITA). 2. Click at the end of last paragraph in the le. 3. Click Reuse > Insert Element with Keyref.
28 XMetaL with DITA Evaluation Guide

Re-using content

4. Select an element from the Element type drop-down list an element to be inserted. 5. Click the Select Key button. The Select Key dialog will appear and display the associated key space. 6. Select the product_name key from the list of keys presented in the list view. 7. Click OK. 8. Click OK. The selected element is inserted; the value of its keyref attribute is the selected key name.

29

Chapter
Working with conditions
By default, XMetaL comes with the following conditions: Audience Platform Product

Each condition denes values. For example, Audience includes values of "Administrator" and "User" by default. You can specify your own conditions through the following conguration le: ..\XMetaL\Author\Conditional Text\configs\ct_config.xml. Without specializing DITA, you can: Change the values for Audience, Platform, and Product. E.g. congure the system to use your own product names. Add a fourth condition, to be stored using the DITA otherprops attribute. For example, you can add a "Location" condition with values of "on-site" and "mobile". For DITA experts: If you need more than four conditions, you can create new ones by specializing the otherprops attribute. You can then congure the system to use those new attributes.

Apply conditions
You can apply conditions to text and images in your document through the Apply/Remove Conditions dialog. For this exercise, switch to Tags On view. 1. Open the le AboutWorldTimePro.xml . 2. Select some text in the rst list item. 3. Click Reuse > Apply/Remove Conditions.

31

4. From the Audience category, select Administrator, then click OK. XMetaL Author automatically creates the <ph> tags that are necessary to mark the conditional range. The conditional range appears with a colored background, with ~ symbols before and after it. If you do not see <ph> tags or ~ symbols, it is because you selected an entire element, rather than text within an element, before you chose the condition to apply. 5. Optionally, change the appearance of the conditional text by clicking Reuse > Style Conditional Text. 6. Save and close the document.

Create a condition
You can create your own conditions in the Condition Conguration File. You can add values to the existing default conditions or create your own DITA lets you dene conditions through the attribute element that has the name 'otherprops'. After you modify the conguration le, you need to re-start XMetaL. In order to create your own conditions, you must be able to read and understand XML. This topic is intended for advanced users. 1. Open the le ..\XMetaL\Author\Conditional Text\configs\ct_config.xml. 2. Add a new <value> element with the name 'evaluator'. For example, <attribute name="audience" title="Audience"> ... <value name="evaluator" title="Evaluator" /> </attribute> Use the title attribute to indicate how the condition value should appear in the XMetaL interface. 3. Now try creating a new condition and values. The following example creates a new condition called 'Release', with values of 'Beta' and '1.0'. <attribute name="otherprops" title="Release"> <value name="beta" title="Beta" /> <value name="1.0" title="1.0" /> </attribute>

32

XMetaL with DITA Evaluation Guide

Chapter
Operating on multiple topics

With DITA's topic-oriented writing paradigm, familiar tasks like Find and Replace or Spell Check are more cumbersome when you have many topics in your DITA map to oversee. The cross-le operation mechanism in XMetaL Author can repeatedly apply a specic operation in a batch-style manner saving you from opening individual topics and doing the same operation topic by topic. The cross-le operation mechanism reports the results in a docked panel at the bottom of the XMetaL Author application window. You can review the results and act upon them in an orderly fashion.

Finding text content

This exercise shows you how to nd a text phrase. 1. Open the le AboutWorldTimePro.xml by selecting Help > Samples > World Time Pro (DITA). The Using World Time Pro map will open in the Map Editor. 2. In the Map Editor, click the Cross-map Find button A Find in Files dialog appears. 3. Activate the Text tab and move your keyboard focus into the Text: edit box. 4. Type a word to search for such as calendar. 5. Click Find. A Find 1 results tab appears listing all the occurrences of the text inputted. 6. Double-click upon one of the results to jump to that occurrence of text.

Spell checking topics in a map

This exercise shows you how to spell check all topics in a DITA map. 1. Open the le AboutWorldTimePro.xml by selecting Help > Samples > World Time Pro (DITA). The Using World Time Pro DITA map will open in the Map Editor 2. In the Map Editor, click the Cross-map Spell Check button A Spell Checking results tab appears listing all the spelling mistakes. 3. Double-click upon one of the results to jump to the misspelled word.

33

Run a custom cross-file operation

This exercise shows you how to run a custom cross-le operation that does Word Counting for all topics in a DITA map. 1. Open the le AboutWorldTimePro.xml by selecting Help > Samples > World Time Pro (DITA). 2. Click Tools > Run Cross-File Operation. The Run Cross-File Operation dialog appears. 3. From the Operation drop-down list select the Word Count item. 4. Click Run. A Cross-File Operation results tab appears listing all the word totals per topic and an overall total for the entire set of topics referenced by the DITA map.

34

XMetaL with DITA Evaluation Guide

Chapter
Publishing

The DITA Open Toolkit is installed when you install XMetaL Author and you can run it through the Generate Output menu item. You get the same results that you would using the toolkit directly, but XMetaL is much easier to use. The format and characteristics of your output is determined by saved conguration called a deliverable type. By default, XMetaL includes deliverable types for several standard output formats. Note: If you want to create Microsoft HTML Help (CHM) output, ensure you have Microsoft HTML Help Workshop installed. This is available from http://www.microsoft.com.

Generate output
You can generate output from the sample map les. You can specify which conditions to include in your output. This exercise requires Microsoft HTML Help Workshop. 1. Open the le WorldTimePro.ditamap. 2. Click File > Generate Output for DITA Map. 3. Select the HTML Help (CHM) deliverable type, then click Show/Hide Conditional Text. You can now select conditions that you want to appear in the output. The settings are retained for all subsequent output. 4. From the Audience condition, select Administrator and click OK. XMetaL begins the process of creating output for your document. 5. At the end of the generating process, click Open File. Open the generated CHM le and click through the topics to see how the generated links appear in the parent and child topics, as well as the Related links specied by the relationship table. 6. Now create a PDF le for your document. Click File > Generate Output for DITA Map and select XMetaL Enhanced PDF, then click OK. 7. Open the generated PDF document and browse through the document to see how the same information appears in the different output format.

Generate output with complex conditions

This exercise shows you how to generate output for content that is conditionalized for multiple audiences and multiple platforms.
35

For this exercise, use the table below as an example. This table already has conditions applied. For example, row 3 has been conditionalized to indicate that it applies to the "Administrator" audience and the "Windows" platform.
# 1 Sample Audiences Platforms All

The PrintFlamingo system stores important settings in a conguration le. All

1. Open the le t_Generate_output_with_complex_conditions.xml from your C:\Program Files\XMetaL\Author\Evaluation Guide\tasks folder. 2. Optionally, view what conditions are used in the document: a) Click anywhere in row 3 of the table above. b) Click Reuse > Apply/Remove Conditions. c) From the Conditional Range drop-down list, choose "row". The dialog displays which conditions apply to table row 3. 3. Click File > Generate Output for DITA Topic. 4. In the Generate Output for DITA Topic dialog, click Show/Hide Conditional Text. 5. Expand the Audience node and select the Administrator checkbox. Expand the Platform node and select the Mac OS X checkbox. Click OK. 6. In the Generate Output for DITA Topic dialog, choose any deliverable type, and click OK. In output, only rows 1, 2, and 4 of the table appear. This is what you want: all material that is needed by administrators using a Macintosh, and no material that is irrelevant to them. To get this result using other tools, you would probably have had to create conditions such as "Macintosh not-administrator" for the other rows. You can experiment with styling of conditions using this le. When viewing the document in XMetaL, note that by default, all conditional text is colored with a light blue background. You can congure this by choosing Reuse > Style Conditional Text, for example to style content for Windows in green text and content for the Macintosh in red text.

36

XMetaL with DITA Evaluation Guide

Index
A
authoring structured 7 topic-based 7 topic-typed 7

I
index entries 22

K
key denition adding to maps 25 creating 25 key denition with keyword adding to maps 25 creating 25

B
bookmaps 21

C
CHM output 35 condition conguration le 31 conditions 31 applying 31 creating 32 publishing with 35

M
maps adding key denitions 25 adding topics 20 bookmap 21 creating 19 organizing topics 20 relationship tables 21

D
deliverables CHM 35 HTML 35 PDF 35 DITA 7 DITA bookmaps create 21 DITA maps 19

N
Normal view 15

P
PDF output 35 Plain Text view 15 Preview view 15

E
editing 18 Element List displaying elements 16 elements identifying currently selected 16 displaying in Element List 16

R
related links 21 relationship tables 21

S
specialization 7 spell checker 18 structured authoring 7

F
Find and Replace 18

G
generating output 35

T
Tags On view 15 topic-based authoring 7 topic-typed authoring 7 topics adding to maps 20

H
HTML output 35

Index

topics (continued) creating 20 organizing in maps 20 relationships between 21 Track Changes 18

V
views change 15

38

XMetaL with DITA Evaluation Guide